| Class Overview |
BPopUpMenu(const char* name,
bool radioMode = true,
bool labelFromMarked = true,
menu_layout layout = B_ITEMS_IN_COLUMN);
BPopUpMenu(BMessage
* archive);
Initializes the BPopUpMenu
object. If the object
is added to a BMenuBar
,
its name
also becomes the initial label of its controlling item (just as
for other BMenu
s).
If the labelFromMarked
flag is true
(as it is by default), the label of
the controlling item will change to reflect the label of the item that
the user last selected. In addition, the menu will operate in radio mode
(regardless of the value passed as the radioMode
flag). When the menu
pops up, it will position itself so that the marked item appears directly
over the controlling item in the BMenuBar
.
If labelFromMarked
is false
, the
menu pops up so that its first item is over the controlling item.
If the radioMode
flag is true
(as it is by default), the last item
selected by the user will always be marked. In this mode, one and only
one item within the menu can be marked at a time. If
radioMode
is false
,
items aren't automatically marked or unmarked.
However, the radioMode
flag has no effect unless
the labelFromMarked
flag
is false
. As long as labelFromMarked
is true
, radio mode will also be
true
.
The layout of the items in a BPopUpMenu
can be either
B_ITEMS_IN_ROW
or
the default B_ITEMS_IN_COLUMN
. It should never be
B_ITEMS_IN_MATRIX
. The
menu is resized so that it exactly fits the items that are added to it.
The new BPopUpMenu
is empty; you add items to it by calling
BMenu
's
AddItem()
function.
See also:
BMenu::SetRadioMode()
,
BMenu::SetLabelFromMarked()
virtual ~BPopUpMenu();
Does nothing. The BMenu
destructor is sufficient to clean up after a BPopUpMenu
.
virtual status_t Archive(BMessage
* archive,
bool deep = true) const;
Calls the inherited version of Archive()
and stores the BPopUpMenu
in the
BMessage
archive.
See also:
BArchivable::Archive()
,
Instantiate()
static function
BMenuItem
* Go(BPoint
screenPoint,
bool deliversMessage = false,
bool openAnyway = false,
bool asynchronous = false);
BMenuItem
* Go(BPoint
screenPoint,
bool deliversMessage,
bool openAnyway,
BRect
clickToOpenRect,
bool asynchronous = false);
Places the pop-up menu on-screen so that its left top corner is located
at screenPoint
in the screen coordinate system.
If the asynchronous
flag
is true
, Go()
returns right
away; the return value is NULL
. Otherwise, it
doesn't return until the user dismisses the menu from the screen. If the
user invoked an item in the menu, it returns a pointer to the item. If no
item was invoked, it returns NULL
.
Go()
is typically called from within the
MouseDown()
function of a BView
.
For example:
voidMyView
::MouseDown
(BPoint
point
) {BMenuItem
*selected
;BMessage
*copy
; . . .ConvertToScreen
(&point
);selected
=myPopUp
->Go
(point
); . . . if (selected
) { BLooper *looper
; BHandler *target
=selected
->Target
(&looper
);looper
->PostMessage
(selected
->Message
(),target
); } . . . }
Go()
operates in two modes:
If the deliversMessage
flag is true
,
the BPopUpMenu
works just like a menu that's controlled
by a BMenuBar
. When the
user invokes an item in the menu, the item posts a message to its target.
If the deliversMessage
flag is false
,
a message is not posted.
Invoking an item doesn't automatically accomplish anything. It's up to
the application to look at the returned
BMenuItem
and decide what to
do. It can mimic the behavior of other menus and post the
message—as shown in the example above—or it can take some
other course of action.
Go()
always puts the pop-up menu on-screen, but ordinarily keeps it there
only as long as the user holds a mouse button down. When the user
releases the button, the menu is hidden and Go()
returns. However, the
openAnyway
flag and the clickToOpenRect
arguments can alter this behavior
so that the menu will stay open even when the user releases the mouse
button (or even if a mouse button was never down). It will take another
user action—such as invoking an item in the menu or clicking
elsewhere—to dismiss the menu.
If the openAnyway
flag is true
,
Go()
keeps the menu on-screen even if no
mouse buttons are held down. This permits a user to open and operate a
pop-up menu from the keyboard. If openAnyway
is
false
, mouse actions
determine whether the menu stays on-screen.
If the user has the click-to-open menu preference turned on and releases
the mouse button while the cursor lies inside the clickToOpenRect
rectangle, Go()
interprets the action as clicking to open the menu and
keeps it on-screen. If the cursor is outside the rectangle when the mouse
button goes up, the menu is removed from the screen and Go()
returns. The
rectangle should be stated in the screen coordinate system.
Once Go()
returns, your application should delete
the BPopUpMenu
object.
See also:
BInvoker::SetMessage()
virtual BPoint
ScreenLocation();
Determines where the pop-up menu should appear on-screen (when it's being
run automatically, not by Go()
). As explained in the description of the
class constructor, this largely depends on whether the label of the
superitem changes to reflect the item that's currently marked in the
menu. The point returned is stated in the screen coordinate system.
This function is called only for BPopUpMenu
s that have been added to a
menu hierarchy (a BMenuBar
).
You should not call it to determine the
point to pass to Go()
. However, you can override it to change where a
customized pop-up menu defined in a derived class appears on-screen when
it's controlled by a BMenuBar
.
See also:
BMenu::SetLabelFromMarked()
,
BMenu::ScreenLocation()
,
the BPopUpMenu
constructor
void SetAsyncAutoDestruct(bool state);
bool AsyncAutoDestruct() const;
SetAsyncAutoDestruct()
lets you specify whether
you want BPopUpMenu
to
automatically delete its
BMenu
when the pop-up menu closes. If you want the
BMenu
to be deleted, specify true
for state
.
AsyncAutoDestruct()
returns the current state of the flag.
static BArchivable
* Instantiate(BMessage
* archive);
Returns a new BPopUpMenu
object, allocated by new and created with the
version of the constructor that takes a BMessage
archive. However, if the
archive message doesn't contain data for a BPopUpMenu
, this function
returns NULL
.
See also:
BArchivable::Instantiate()
,
instantiate_object()
,
Archive()