Display item for the BMenu class. More...

Public Member Functions
	BMenuItem (BMenu menu, BMessage message=NULL)
	Creates a new BMenuItem object with the specified menu and message.

	BMenuItem (BMessage *data)
	Archive constructor.

	BMenuItem (const char label, BMessage message, char shortcut=0, uint32 modifiers=0)
	Creates a new BMenuItem object with the specified label and message.

virtual	~BMenuItem ()
	Destructor.

BRect	Frame () const
	Returns the bounds rectangle of the menu item.

bool	IsEnabled () const
	Returns whether or not the item is enabled.

bool	IsMarked () const
	Returns whether or not the item is marked.

const char *	Label () const
	Returns the item's label.

BMenu *	Menu () const
	Returns a pointer to the menu that the item is attached to.

virtual void	SetEnabled (bool enable)
	Enables or disables the menu item.

virtual void	SetLabel (const char *name)
	Sets the menu item label to string.

virtual void	SetMarked (bool mark)
	Marks or unmarks the menu item.

virtual void	SetShortcut (char shortcut, uint32 modifiers)
	Set the keyboard shortcut of the menu item.

virtual void	SetTrigger (char trigger)
	Set the character that activates this menu item. The triggered character is drawn underlined in the menu.

char	Shortcut (uint32 *_modifiers=NULL) const
	Returns the currently set shortcut and fills out modifiers with a bitmap of the modifier keys required to invoke the item.

BMenu *	Submenu () const
	Returns a pointer to the attached menu.

char	Trigger () const
	Returns the item's trigger character.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.

virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

Public Member Functions inherited from BInvoker
	BInvoker ()
	Initializes a BInvoker without a message or target.

	BInvoker (BMessage *message, BMessenger target)
	Initializes the BInvoker with message and sets the target messenger where the message is sent when Invoke() is called.

	BInvoker (BMessage message, const BHandler handler, const BLooper *looper=NULL)
	Initializes the BInvoker with message and sets the target to either a local handler or as the preferred handler of a local looper where the message is sent when Invoke() is called.

virtual	~BInvoker ()
	Destructor method, deletes the BMessage object if set.

uint32	Command () const
	Returns the message's `what` data member.

BHandler *	HandlerForReply () const
	Returns the previously set reply handler or `NULL` if not set.

virtual status_t	Invoke (BMessage *message=NULL)
	Sends the message to the invoker's target.

status_t	InvokeNotify (BMessage *message, uint32 kind=B_CONTROL_INVOKED)
	Sends the message to its target, using the notification code specified by kind.

bool	IsTargetLocal () const
	Returns whether or not the invoker and its target belong to the same team.

BMessage *	Message () const
	Returns a pointer to the invoker's message object.

BMessenger	Messenger () const
	Returns the BMessenger object that the invoker uses to send its messages.

virtual status_t	SetHandlerForReply (BHandler *handler)
	Sets the BHandler object responsible for handling reply messages.

virtual status_t	SetMessage (BMessage *message)
	Assigns message to the invoker, deleting any previously assigned message.

virtual status_t	SetTarget (BMessenger messenger)
	Sets the invoker's target to messenger.

virtual status_t	SetTarget (const BHandler handler, const BLooper looper=NULL)
	Sets the target to either a local handler or as the preferred handler of a local looper.

status_t	SetTimeout (bigtime_t timeout)
	Sets the timeout to use when sending the message to the target.

BHandler *	Target (BLooper **_looper=NULL) const
	Invoke BMessenger::Target() on the internal messenger.

bigtime_t	Timeout () const
	Returns the current timeout value.

Protected Member Functions
BPoint	ContentLocation () const
	Returns the top-left point of the content rectangle.

virtual void	Draw ()
	Hook method used to draw the menu items.

virtual void	DrawContent ()
	Hook method used to draw the menu items contents.

virtual void	GetContentSize (float _width, float _height)
	Fills out _width and _height with the content rectangle dimensions.

virtual void	Highlight (bool highlight)
	Highlights or unhighlights the menu item.

virtual status_t	Invoke (BMessage *message=NULL)
	Sends a copy of the model message to the target.

bool	IsSelected () const
	Returns whether or not the item is selected.

virtual void	TruncateLabel (float maxWidth, char *newLabel)
	Truncates the label and stashes it into newLabel.

Protected Member Functions inherited from BInvoker
void	BeginInvokeNotify (uint32 kind=B_CONTROL_INVOKED)
	Implement this method to set up an InvokeNotify() context.

void	EndInvokeNotify ()
	Implement this method to tear down an InvokeNotify() context.

uint32	InvokeKind (bool *_notify=NULL)
	Returns the kind set by InvokeNotify().

Archiving
virtual status_t	Archive (BMessage *archive, bool deep=true) const
	Archives the the BMenuItem object into the data message.

static BArchivable *	Instantiate (BMessage *archive)
	Creates a new BMenuItem object from an data message.

Additional Inherited Members
Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

Detailed Description

Display item for the BMenu class.

A BMenuItem either consists of a label or a submenu and message that is sent to the attached menu's target when the item is selected. BMenu and BMenuItem work in concert with each other in order to create a menu tree hierarchy. BMenuItem's serve as nodes in the tree while BMenu's serve as branches.

See also: SetLabel()

A menu item, unless it represents a submenu, can have a keyboard shortcut which is a printable character used in combination with the Command key and possibly other modifiers to invoke the item. The shortcut is displayed right of the item's label.

See also: SetShortcut()

A menu item may also have a trigger character assigned to it that invokes the item without using the Command key. The trigger characters is drawn underlined in the menu item's label. Unlike shortcuts, triggers are automatically assigned to a menu item. You can set the trigger character explicitly by calling SetTrigger().

See also: SetTrigger()

Attention: Triggers are currently disabled.

Both the shortcut character and trigger character are case-insensitive.

A menu item may be marked, which draws a checkmark on the left side of the item. only one menu items may be marked at a time if attached to a menu in radio mode.

See also: SetMarked(); BMenu::SetRadioMode()

Menu items can also be enabled or disabled. A disabled item's label is drawn in a lighter color to indicate that it may not be used. A disabled menu item may not be selected or invoked. If the menu item controls a submenu the submenu may still be opened but each of the items will be disabled.

See also: SetEnabled()

Since: BeOS R3

Constructor & Destructor Documentation

◆ BMenuItem() [1/3]

BMenuItem::BMenuItem	(	const char *	label,
		BMessage *	message,
		char	shortcut = `0`,
		uint32	modifiers = `0`
	)

Creates a new BMenuItem object with the specified label and message.

Parameters

label	The text label that is displayed.
message	The BMessage that is sent when the item is selected.
shortcut	The shortcut characters to activate the menu item.
modifiers	The modifier keys to active the menu item, `B_COMMAND_KEY` is assumed.

Since: BeOS R3

◆ BMenuItem() [2/3]

BMenuItem::BMenuItem	(	BMenu *	menu,
		BMessage *	message = `NULL`
	)

Creates a new BMenuItem object with the specified menu and message.

The menu item's label is derived from the menu name. This method makes the menu item a submenu.

Parameters

menu	The menu to assign to the item.
message	The BMessage that is sent when the item is selected.

Since: BeOS R3

◆ BMenuItem() [3/3]

BMenuItem::BMenuItem ( BMessage * data )

Archive constructor.

Parameters

data	The message data to construct the menu item from.

Since: BeOS R3

◆ ~BMenuItem()

BMenuItem::~BMenuItem ( )

virtual

Destructor.

If this item is attached to a menu, it will be removed from it.

Also destroys the label and submenu.

Since: BeOS R3

Member Function Documentation

◆ Archive()

status_t BMenuItem::Archive	(	BMessage *	data,
		bool	deep = `true`
	)		const

virtual

Archives the the BMenuItem object into the data message.

Adds the label and current state of the BMenuItem to the archive.

Parameters

data	A pointer to the BMessage to archive the object into.
deep	Whether or not to archive attached menus as well.

Returns: A status code, B_OK if everything went well or an error code otherwise.

Return values

B_OK	The object was archived successfully.
B_NO_MEMORY	Ran out of memory while archiving the object.

Since: BeOS R3

Reimplemented from BArchivable.

Reimplemented in BSeparatorItem.

◆ ContentLocation()

BPoint BMenuItem::ContentLocation ( ) const

protected

Returns the top-left point of the content rectangle.

You only need to call this method if you're implementing your own DrawContent() method to override how the contents of the menu item are drawn.

The content rectangle can be calculated using this method as well as GetContentSize() to get the width and height.

Returns: The top-left point of the content rectangle as a BPoint in the coordinate system of the attached BMenu.

See also: GetContentSize(); DrawContent()

Since: BeOS R3

◆ Draw()

void BMenuItem::Draw ( )

protectedvirtual

Hook method used to draw the menu items.

This method is called by automatically by BMenu::Draw(). You should not need to call this method yourself but you may want to override it in a derived class to do something other than the default. The default draws the mark, shortcut and possibly a right arrow to indicate there is submenu and then calls DrawContent() to fill in the label. Lastly Highlight() is called if the item is selected.

Since: BeOS R3

Reimplemented in BSeparatorItem.

◆ DrawContent()

void BMenuItem::DrawContent ( )

protectedvirtual

Hook method used to draw the menu items contents.

This method is called automatically by BMenu::Draw(), you need not call it yourself. You may want to override this method in derived classes to do something different than drawing a text label.

Since: BeOS R3

◆ Frame()

BRect BMenuItem::Frame ( ) const

Returns the bounds rectangle of the menu item.

Returns: The bounds rectangle of the menu item in the coordinate system of the menu that the item is attached to.

Since: BeOS R3

◆ GetContentSize()

void BMenuItem::GetContentSize	(	float *	_width,
		float *	_height
	)

protectedvirtual

Fills out _width and _height with the content rectangle dimensions.

You only need to call this method if you're implementing your own DrawContent() method to override how the contents of the menu item are drawn.

The content rectangle excludes the item margins and the area that contains the checkmark, shortcut, and submenu arrow.

The content rectangle can be calculated using this method as well as ContentLocation() to get location of the top left corner.

Parameters

_width	Filled out with the width of the content rectangle.
_height	Filled out with the height of the content rectangle.

See also: ContentLocation(); DrawContent()

Since: BeOS R3

Reimplemented in BSeparatorItem.

◆ Highlight()

void BMenuItem::Highlight ( bool highlight )

protectedvirtual

Highlights or unhighlights the menu item.

This method is called by Draw() when the item is selected or unselected.

You shouldn't need to call this method unless you override the Draw() method in a derived class and you want to highlight differently.

Parameters

highlight Highlights if highlight is true, unhighlights if false.

Since: BeOS R3

◆ Instantiate()

BArchivable * BMenuItem::Instantiate ( BMessage * data )

static

Creates a new BMenuItem object from an data message.

Returns: A newly created BMenuItem object or NULL if the message doesn't contain an archived BMenuItem.

Since: BeOS R3

◆ Invoke()

status_t BMenuItem::Invoke ( BMessage * message = NULL )

protectedvirtual

Sends a copy of the model message to the target.

This method extends BInvoker::Invoke() to guarantee that only enabled items attached to the menu can be invoked and automatically marks the item.

The following fields added to the message:

"when" B_INT64_TYPE system_time()
"source" B_POINTER_TYPE A pointer to the menu item object.
"index" B_INT32_TYPE The index of the menu item.

Parameters

message The message to send or NULL to send the message set in the constructor.

Returns: B_OK on success or an error code on error.

Return values

B_OK	The message was sent successfully.
B_BAD_VALUE	The message was `NULL`.

See also: BInvoker::Invoke()

Since: BeOS R3

Reimplemented from BInvoker.

◆ IsEnabled()

bool BMenuItem::IsEnabled ( ) const

Returns whether or not the item is enabled.

Returns: true if the item is enabled, false if disabled.

Since: BeOS R3

◆ IsMarked()

bool BMenuItem::IsMarked ( ) const

Returns whether or not the item is marked.

Returns: true if the item is marked, false if unmarked.

Since: BeOS R3

◆ IsSelected()

bool BMenuItem::IsSelected ( ) const

protected

Returns whether or not the item is selected.

Returns: true if selected, false if not selected.

Since: BeOS R3

◆ Label()

const char * BMenuItem::Label ( ) const

Returns the item's label.

Returns: The item's label as a const char array.

Since: BeOS R3

◆ Menu()

BMenu * BMenuItem::Menu ( ) const

Returns a pointer to the menu that the item is attached to.

Returns: A pointer to the menu that the item is attached to.

Since: BeOS R3

◆ SetEnabled()

void BMenuItem::SetEnabled ( bool enable )

virtual

Enables or disables the menu item.

Enabling or disabling the menu item invalidates the attached menu.

Parameters

enable true to enable the menu item, false to disable it.

Since: BeOS R3

Reimplemented in BSeparatorItem.

◆ SetLabel()

void BMenuItem::SetLabel ( const char * string )

virtual

Sets the menu item label to string.

The memory used by the label is copied so you may free the original. Setting the label invalidates the attached menu.

Parameters

string The string to set the label to.

Since: BeOS R3

◆ SetMarked()

void BMenuItem::SetMarked ( bool mark )

virtual

Marks or unmarks the menu item.

Marking or unmarking the menu item invalidates the attached menu.

Marking a menu item attached to a menu in radio mode causes the currently marked item to be unmarked.

Parameters

mark	`true` to mark the menu item, `false` to unmark it.

See also: BMenu::SetRadioMode()

Since: BeOS R3

◆ SetShortcut()

void BMenuItem::SetShortcut	(	char	shortcut,
		uint32	modifiers
	)

virtual

Set the keyboard shortcut of the menu item.

Setting a shortcut invalidates the attached menu.

This method will override the existing shortcut set to the window.

Parameters

shortcut	The ASCII shortcut character to set.
modifiers	A bitmap mask of modifier keys used to activate the shortcut.

Since: BeOS R3

◆ SetTrigger()

void BMenuItem::SetTrigger ( char trigger )

virtual

Set the character that activates this menu item. The triggered character is drawn underlined in the menu.

Attention: Triggers are currently disabled.

Parameters

trigger The trigger character to set on this menu item.

Since: BeOS R3

◆ Shortcut()

char BMenuItem::Shortcut ( uint32 * modifiers = NULL ) const

Returns the currently set shortcut and fills out modifiers with a bitmap of the modifier keys required to invoke the item.

Parameters

modifiers A pointer to a uint32 to fill out.

Returns: The shortcut character assigned to the menu item as a char.

Since: BeOS R3

◆ Submenu()

BMenu * BMenuItem::Submenu ( ) const

Returns a pointer to the attached menu.

Returns: A pointer to the attached menu.

Since: BeOS R3

◆ Trigger()

char BMenuItem::Trigger ( ) const

Returns the item's trigger character.

Returns: The current trigger character as a char or 0 if unset.

Since: BeOS R3

◆ TruncateLabel()

void BMenuItem::TruncateLabel	(	float	maxWidth,
		char *	newLabel
	)

protectedvirtual

Truncates the label and stashes it into newLabel.

You are responsible for allocating newLabel with enough space to fit the label including the trailing NUL. The method will NUL terminate the string for you.

Parameters

maxWidth	The maximum number of bytes to truncate the label to.
newLabel	The buffer to store the truncated label in.

Since: BeOS R3

Public Member Functions

Protected Member Functions

Archiving

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BMenuItem() [1/3]

◆ BMenuItem() [2/3]

◆ BMenuItem() [3/3]

◆ ~BMenuItem()

Member Function Documentation

◆ Archive()

◆ ContentLocation()

◆ Draw()

◆ DrawContent()

◆ Frame()

◆ GetContentSize()

◆ Highlight()

◆ Instantiate()

◆ Invoke()

◆ IsEnabled()

◆ IsMarked()

◆ IsSelected()

◆ Label()

◆ Menu()

◆ SetEnabled()

◆ SetLabel()

◆ SetMarked()

◆ SetShortcut()

◆ SetTrigger()

◆ Shortcut()

◆ Submenu()

◆ Trigger()

◆ TruncateLabel()