<section ID="chapter.widgets.menubutton">
  <TITLE>Menubutton widget</TITLE>

<subsection> <TITLE>Description</TITLE>

<P>
A menubutton is a widget that displays a textual string, bitmap, or image and is associated with a menu. If text is displayed, it must all be in a single font, but it can occupy multiple lines on the screen (if it contains newlines or if wrapping occurs because of the <<wraplength>> option) and one of the characters may optionally be underlined using the underline option. In normal usage, pressing mouse button 1 over the menubutton causes the associated menu to be posted just underneath the menubutton. If the mouse is moved over the menu before releasing the mouse button, the button release causes the underlying menu entry to be invoked. When the button is released, the menu is unposted.
</P>
<P>
Menubuttons are typically organized into groups called menu bars that allow scanning: if the mouse button is pressed over one menubutton (causing it to post its menu) and the mouse is moved over another menubutton in the same menu bar without releasing the mouse button, then the menu of the first menubutton is unposted and the menu of the new menubutton is posted instead. 
</P>
<P>
The menu that drops down when the menubutton is activated is defined either by a record describing a menu, or by a previously built menu with the <<Qtk.buildmenu>> command. See <ptr to="misc.menu"> for details about menus.

</P>

<subsection> <TITLE>Parameters</TITLE>

<P>
<LIST>
<ITEM> <<1:VS>> : Specifies the text displayed inside the widget (same as text). This parameter can be only used with the <<set()>> and <<get()>> methods.
&param_init_text;

<ITEM> <<return:V>> : If the execution of the action of the button closes the window, Variable is bound to true. In all other cases where the window is closed, Variable is bound to false. This parameter is valid at creation time only. <<V>> must be a free variable.

&param_activebackground;
&param_activeforeground;
&param_anchor;
&param_background;
&param_bitmap;
&param_borderwidth;
&param_cursor;
&param_disabledforeground;
&param_font;
&param_foreground;
&param_highlightbackground;
&param_highlightcolor;
&param_highlightthickness;
&param_image;
&param_justify;
&param_relief;
&param_takefocus;
&param_text;
&param_underline;
&param_wraplength;
&param_ipadx;
&param_ipady;

<ITEM> <<direction:A>> : Specifies where the menu is going to be popup up. <<above>> tries to pop the menu above the menubutton. <<below>> tries to pop the menu below the menubutton. <<left>> tries to pop the menu to the left of the menubutton. <<right>> tries to pop the menu to the right of the menu button. <<flush>> pops the menu directly over the menubutton. 

<ITEM> <<height:P>> : Specifies a desired height for the button. If an image or bitmap is being displayed in the button then the value is in screen units; for text it is in lines of text. If this option isn't specified, the button's desired height is computed from the size of the image or bitmap or text being displayed in it. <<P>> must be a valid screen distance (see  <ptr to="misc.distance">).

<ITEM> <<indicatoron:B>> : If it is true then a small indicator rectangle will be displayed on the right side of the menubutton and the default menu bindings will treat this as an option menubutton. If false then no indicator will be displayed. <<B>> must be a boolean.

<ITEM> <<menu:O>> : Specifies the menu that is posted when the user selects the menubutton. <<O>> must be either a record describing a proper menu, or a menu already built by the command <<QTk.buildmenu>>. See <ptr to="misc.menu"> for menu details.

<ITEM> <<state:A>> : Specifies one of three states for the button: <<normal>>, <<active>>, or <<disabled>>. In normal state the button is displayed using the foreground and background options. The active state is typically used when the pointer is over the button. In active state the button is displayed using the activeforeground and activebackground options. Disabled state means that the button should be insensitive: the default bindings will refuse to activate the widget and will ignore mouse button presses. In this state the disabledforeground and background options determine how the button is displayed. <<A>> must be one of these three atoms : <<normal>>, <<active>>, or <<disabled>>.

<ITEM> <<width:P>> : Specifies a desired width for the button. If an image or bitmap is being displayed in the button then the value is in screen units; for text it is in characters. If this option isn't specified, the button's desired width is computed from the size of the image or bitmap or text being displayed in it. <<P>> must be a valid screen distance (see  <ptr to="misc.distance">).

<ITEM> <<action:C>> : Specifies an action to execute juste after the user clicked the button, before the posting of the menu. <<C>> can take several different forms (see <ptr to="basics.events">).

&param_glue;
&param_padx;
&param_pady;
&param_feature;
&param_handle;
&param_tooltips;


</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

<P>
The object you get by an handle on the widget implements the following methods :

<LIST>

&interface_set;
&interface_get;
&interface_bind;
&interface_getFocus;
&interface_setGrab;
&interface_releaseGrab;
&interface_getGrabStatus;
&interface_raise;
&interface_lower;
&interface_winfo;

</LIST>

</section>
