[ Previous | Next | Contents | Glossary | Home | Search ]
Motif 2.1 Widget Writer's Guide

ExmMenuButton

The MenuButton widget class demonstration widget

Format

#include <Exm/MenuB.h>

DESCRIPTION

ExmMenuButton is a demonstration widget. OSF provides this widget solely to teach programmers how to write their own Motif widgets. OSF does not support this widget in any way.

The source code for the ExmMenuButton widget illustrates how to do the following:

  1. Create a menu child widget

  2. Install the XmQTmenuSavvy trait

  3. Call some of the trait methods of XmQTmenuSystem

    ExmMenuButton is similar to the standard Motif toolkit widget XmPushButton. The primary difference is that XmPushButton supports a richer set of actions and callbacks than ExmMenuButton. ExmMenuButton illustrates only the essentials of creating a menu button.

    ExmMenuButton is an instantiable widget. ExmMenuButton expects XmRowColumn to be its parent.

    ExmMenuButton is a subclass of the ExmString widget. Therefore, ExmMenuButton inherits all of ExmString's resources for rendering compound strings.

    When a user activates an ExmMenuButton widget, the widget calls the callback procedure associated with the XmNactivateCallback resource.

    4. Classes

    ExmMenuButton inherits behavior and resources from Core, XmPrimitive, ExmSimple, and ExmString.

    The class pointer is exmMenuButtonWidgetClass.

    The class name is ExmMenuButton.

    New Resources

    The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the XmN, ExmN, XmC or ExmC prefix and use the remaining letters. To specify one of the defined values for a resource in a .Xdefaults file, remove the Xm or Exm prefix and use the remaining letters (in either lowercase or uppercase, but include any underscores between words). The codes in the "Access" column indicate if the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A).


    ExmMenuButton Resource Set
    Name Class Type Default Access
    XmNaccelerator XmCAccelerator String NULL CSG
    XmNaccleratorText XmCAcceleratorText XmString NULL CSG
    XmNactivateCallback XmCCallback XtCallbackList
    		CSG
    XmNmnemonic XmCMnemonic KeySym XK_VoidSymbol CSG
    XmNmnemonicCharSet XmCMnemonicCharSet XmStringCharSet XmFONTLIST_DEFAULT_TAG CSG

    XmNaccelerator
    Sets the accelerator on a MenuButton widget in a menu, which activates a visible or invisible, but managed, button from the keyboard. This resource is a string that describes a set of modifiers and the key that may be used to select the button. The format of this string is identical to that used by the translations manager, with the exception that only a single event may be specified and only KeyPress events are allowed.

    Accelerators for MenuButtons are supported only in Pulldown and Popup MenuPanes.

    XmNacceleratorText
    Specifies the text displayed for the accelerator. The text is displayed adjacent to the label string or pixmap. The direction of its layout depends on the XmNlayoutDirection resource of the widget. Accelerator text for buttons is displayed only for MenuButtons in Pulldown and Popup Menus.

    XmNactivateCallback
    Specifies the list of callbacks that is called when MenuButton is activated. MenuButton is activated when the user presses and releases the active mouse button while the pointer is inside that widget. Activating the MenuButton also disarms it. For this callback, the reason is XmCR_ACTIVATE.

    XmNmnemonic
    Provides the user with an alternate means of activating a button. A MenuButton in a MenuBar, a Popup MenuPane, or a Pulldown MenuPane can have a mnemonic.

    This resource contains a keysym as listed in the X11 keysym table. The first character in the label string that exactly matches the mnemonic in the character set specified in XmNmnemonicCharSet is underlined when the button is displayed.

    When a mnemonic has been specified, the user activates the button by pressing the mnemonic key while the button is visible. The user can activate the button by pressing either the shifted or the unshifted mnemonic key.

    XmNmnemonicCharSet
    Specifies the character set of the mnemonic for the label. The default is XmFONTLIST_DEFAULT_TAG.

    Inherited Resources

    MenuButton inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the reference page for that superclass.


    ExmString Resource Set
    Name Class Type Default Access
    ExmNcompoundString ExmCCompoundString XmString NULL CSG
    XmNalignment XmCAlignment unsigned char XmALIGNMENT_BEGINNING CSG
    XmNrecomputeSize XmCRecomputeSize Boolean True CSG
    XmNrenderTable XmCRenderTable XmRenderTable dynamic CSG


    ExmSimple Resource Set
    Name Class Type Default Access
    ExmNsimpleShape ExmCSimpleShape unsigned char ExmSHAPE_OVAL CSG
    XmNmarginHeight XmCMarginHeight Dimension 4 CSG
    XmNmarginWidth XmCMarginWidth Dimension 4 CSG


    XmPrimitive Resource Set
    Name Class Type Default Access
    XmNbottomShadowColor XmCBottomShadowColor Pixel dynamic CSG
    XmNbottomShadowPixmap XmCBottomShadowPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
    XmNconvertCallback XmCCallback XtCallbackList NULL C
    XmNforeground XmCForeground Pixel dynamic CSG
    XmNhelpCallback XmCCallback XtCallbackList NULL C
    XmNhighlightColor XmCHighlightColor Pixel dynamic CSG
    XmNhighlightOnEnter XmCHighlightOnEnter Boolean False CSG
    XmNhighlightPixmap XmCHighlightPixmap Pixmap dynamic CSG
    XmNhighlightThickness XmCHighlightThickness Dimension 0 CSG
    XmNlayoutDirection XmCLayoutDirection XmDirection dynamic CG
    XmNnavigationType XmCNavigationType XmNavigationType XmNONE CSG
    XmNpopupHandlerCallback XmCCallback XtCallbackList NULL C
    XmNshadowThickness XmCShadowThickness Dimension 2 CSG
    XmNtopShadowColor XmCTopShadowColor Pixel dynamic CSG
    XmNtopShadowPixmap XmCTopShadowPixmap Pixmap dynamic CSG
    XmNtraversalOn XmCTraversalOn Boolean True CSG
    XmNunitType XmCUnitType unsigned char dynamic CSG
    XmNuserData XmCUserData XtPointer NULL CSG


    Core Resource Set
    Name Class Type Default Access
    XmNaccelerators XmCAccelerators XtAccelerators dynamic CSG
    XmNancestorSensitive XmCSensitive Boolean dynamic G
    XmNbackground XmCBackground Pixel dynamic CSG
    XmNbackgroundPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
    XmNborderColor XmCBorderColor Pixel XtDefaultForeground CSG
    XmNborderPixmap XmCPixmap Pixmap XmUNSPECIFIED_PIXMAP CSG
    XmNborderWidth XmCBorderWidth Dimension 0 CSG
    XmNcolormap XmCColormap Colormap dynamic CG
    XmNdepth XmCDepth int dynamic CG
    XmNdestroyCallback XmCCallback XtCallbackList NULL C
    XmNheight XmCHeight Dimension dynamic CSG
    XmNinitialResourcesPersistent XmCInitialResourcesPersistent Boolean True C
    XmNmappedWhenManaged XmCMappedWhenManaged Boolean True CSG
    XmNscreen XmCScreen Screen * dynamic CG
    XmNsensitive XmCSensitive Boolean True CSG
    XmNtranslations XmCTranslations XtTranslations dynamic CSG
    XmNwidth XmCWidth Dimension dynamic CSG
    XmNx XmCPosition Position 0 CSG
    XmNy XmCPosition Position 0 CSG

    ExmMenuButton provides the following translations:

    EnterWindow:
    MenuButtonEnter()

    LeaveWindow:
    MenuButtonLeave()

    BtnDown:
    BtnDown()

    BtnUp:
    BtnUp()

    :osfActivate:
    ArmAndActivate()

    :osfCancel:
    MenuEscape()

    :osfHelp:
    MenuButtonHelp()

    ~s ~m ~a <Key>Return:
    ArmAndActivate()

    ~s ~m ~a <Key>space:
    ArmAndActivate()

    In addition, ExmMenuButton provides the following traversal translations:

    Unmap:
    Unmap()

    FocusOut:
    FocusOut()

    FocusIn:
    FocusIn()

    osfCancel:
    MenuEscape()

    osfLeft:
    MenuTraverseLeft()

    osfRight:
    MenuTraverseRight()

    osfUp:
    MenuTraverseUp()

    osfDown:
    MenuTraverseDown()

    Action Routines

    The ExmMenuButton action routines are

    ArmAndActivate() :
    Unposts all menus in the menu hierarchy and, unless the button is already armed, calls the XmNactivateCallback callbacks.

    BtnDown() :
    This action unposts any menus posted by the MenuButton's parent menu, disables keyboard traversal for the menu, and enables mouse traversal for the menu. It draws the shadow in the armed state.

    BtnUp() :
    This action unposts all menus in the menu hierarchy and activates the MenuButton. It calls the XmNactivateCallback callbacks.

    MenuButtonEnter :
    If keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the armed state and calls the XmNarmCallback callbacks.

    MenuButtonHelp() :
    In a Pulldown or Popup MenuPane, unposts all menus in the menu hierarchy and, when the shell's keyboard focus policy is XmEXPLICIT, restores keyboard focus to the widget that had the focus before the menu system was entered. This action calls the callbacks for XmNhelpCallback if any exist. If there are no help callbacks for this widget, this action calls the help callbacks for the nearest ancestor that has them.

    MenuButtonLeave :
    If keyboard traversal is enabled, this action does nothing. Otherwise, it draws the shadow in the unarmed state and calls the XmNdisarmCallback callbacks.

    The following actions are handled by the XmRowColumn widget:

    1. MenuEscape

    2. MenuTraverseDown

    3. MenuTraverseLeft

    4. MenuTraverseRight

    5. MenuTraverseUp

      6. Virtual Bindings

      The bindings for virtual keys are vendor specific. For information about bindings for virtual buttons and keys, see VirtualBindings(3).

      RELATED

      Core(3), ExmSimple(3), ExmString(3), and XmPrimitive(3).

      [ Previous | Next | Contents | Glossary | Home | Search ]