All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | Protected Member Functions | List of all members
BMenuItem Class Reference

Display item for the BMenu class. More...

Inherits BArchivable, and BInvoker.

Inherited by BSeparatorItem.

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.
 
BMenuMenu () 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.
 
BMenuSubmenu () 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.
 
BHandlerHandlerForReply () 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.
 
BMessageMessage () 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.
 
BHandlerTarget (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 BArchivableInstantiate (BMessage *archive)
 Creates a new BMenuItem object from an data message.
 

Additional Inherited Members

- Static Public Member Functions inherited from BArchivable
static BArchivableInstantiate (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
labelThe text label that is displayed.
messageThe BMessage that is sent when the item is selected.
shortcutThe shortcut characters to activate the menu item.
modifiersThe 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
menuThe menu to assign to the item.
messageThe BMessage that is sent when the item is selected.
Since
BeOS R3

◆ BMenuItem() [3/3]

BMenuItem::BMenuItem ( BMessage data)

Archive constructor.

Parameters
dataThe 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
dataA pointer to the BMessage to archive the object into.
deepWhether 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_OKThe object was archived successfully.
B_NO_MEMORYRan 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
_widthFilled out with the width of the content rectangle.
_heightFilled 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
highlightHighlights 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
messageThe 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_OKThe message was sent successfully.
B_BAD_VALUEThe 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
enabletrue 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
stringThe 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
marktrue 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
shortcutThe ASCII shortcut character to set.
modifiersA 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
triggerThe 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
modifiersA 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
maxWidthThe maximum number of bytes to truncate the label to.
newLabelThe buffer to store the truncated label in.
Since
BeOS R3