FLTK 1.3.2
Fl_Choice Class Reference

A button that is used to pop up a menu. More...

#include <Fl_Choice.H>

Inheritance diagram for Fl_Choice:
Fl_Menu_ Fl_Widget

List of all members.

Public Member Functions

 Fl_Choice (int X, int Y, int W, int H, const char *L=0)
 Create a new Fl_Choice widget using the given position, size and label string.
int handle (int)
 Handles the specified event.
int value () const
 Gets the index of the last item chosen by the user.
int value (int v)
 Sets the currently selected value using the index into the menu item array.
int value (const Fl_Menu_Item *v)
 Sets the currently selected value using a pointer to menu item.

Protected Member Functions

void draw ()
 Draws the widget.

Detailed Description

A button that is used to pop up a menu.

This is a button that, when pushed, pops up a menu (or hierarchy of menus) defined by an array of Fl_Menu_Item objects. Motif calls this an OptionButton.

The only difference between this and a Fl_Menu_Button is that the name of the most recent chosen menu item is displayed inside the box, while the label is displayed outside the box. However, since the use of this is most often to control a single variable rather than do individual callbacks, some of the Fl_Menu_Button methods are redescribed here in those terms.

When the user picks an item off the menu the value() is set to that item and then the item's callback is done with the menu_button as the Fl_Widget* argument. If the item does not have a callback the menu_button's callback is done instead.

All three mouse buttons pop up the menu. The Forms behavior of the first two buttons to increment/decrement the choice is not implemented. This could be added with a subclass, however.

The menu will also pop up in response to shortcuts indicated by putting a '&' character in the label(). See Fl_Button::shortcut(int s) for a description of this.

Typing the shortcut() of any of the items will do exactly the same as when you pick the item with the mouse. The '&' character in item names are only looked at when the menu is popped up, however.

choice.png
Todo:
Refactor the doxygen comments for Fl_Choice changed() documentation.

Constructor & Destructor Documentation

Fl_Choice::Fl_Choice ( int  X,
int  Y,
int  W,
int  H,
const char *  L = 0 
)

Create a new Fl_Choice widget using the given position, size and label string.

The default boxtype is FL_UP_BOX.

The constructor sets menu() to NULL. See Fl_Menu_ for the methods to set or change the menu.

Parameters:
[in]X,Y,W,Hposition and size of the widget
[in]Lwidget label, default is no label

Member Function Documentation

void Fl_Choice::draw ( ) [protected, virtual]

Draws the widget.

Never call this function directly. FLTK will schedule redrawing whenever needed. If your widget must be redrawn as soon as possible, call redraw() instead.

Override this function to draw your own widgets.

If you ever need to call another widget's draw method from within your own draw() method, e.g. for an embedded scrollbar, you can do it (because draw() is virtual) like this:

        Fl_Widget *s = &scroll;         // scroll is an embedded Fl_Scrollbar
        s->draw();                      // calls Fl_Scrollbar::draw()

Implements Fl_Widget.

int Fl_Choice::handle ( int  event) [virtual]

Handles the specified event.

You normally don't call this method directly, but instead let FLTK do it when the user interacts with the widget.

When implemented in a widget, this function must return 0 if the widget does not use the event or 1 otherwise.

Most of the time, you want to call the inherited handle() method in your overridden method so that you don't short-circuit events that you don't handle. In this last case you should return the callee retval.

Parameters:
[in]eventthe kind of event received
Return values:
0if the event was not used or understood
1if the event was used and can be deleted
See also:
Fl_Event

Reimplemented from Fl_Widget.

int Fl_Choice::value ( ) const [inline]

Gets the index of the last item chosen by the user.

The index is zero initially.

Reimplemented from Fl_Menu_.

int Fl_Choice::value ( int  v)

Sets the currently selected value using the index into the menu item array.

Changing the selected value causes a redraw().

Parameters:
[in]vindex of value in the menu item array.
Returns:
non-zero if the new value is different to the old one.

Reimplemented from Fl_Menu_.

int Fl_Choice::value ( const Fl_Menu_Item v)

Sets the currently selected value using a pointer to menu item.

Changing the selected value causes a redraw().

Parameters:
[in]vpointer to menu item in the menu item array.
Returns:
non-zero if the new value is different to the old one.

Reimplemented from Fl_Menu_.


The documentation for this class was generated from the following files: