manpagez: man pages & more
man XmDropDown(3)
Home | html | info | man
XmDropDown(library call)                              XmDropDown(library call)




NAME

       XmDropDown -- The DropDown widget class


SYNOPSIS

       #include <Xm/DropDown.h>


DESCRIPTION

       The  DropDown  widget allows the user to select elements from a list of
       choices, and enter their own values  in  a  text  widget.  To  conserve
       screen  space,  the list of choices is shown only when the user selects
       the down arrow button. The choices may then be selected from this list.
       If  the  list  widget  is in Browse Select mode (the default) or Single
       Select mode, then the list will automatically be removed when the  user
       selects  an item in the list. When the list is in other modes, multiple
       items may be selected and the list may be popped down by either another
       click  on the arrow button, a click outside the list or double-clicking
       an item. When using keyboard traversal, the list may be popped down  by
       selecting  the  arrow button or Alt - down arrow, and popped back up by
       typing either the osfActivate key, a  carriage  return,  or  Alt  -  up
       arrow.  In  any  case,  when the list is removed the item or items that
       were selected will be placed in the text widget  separated  by  commas.
       Typing  the  escape  key  when  the list is up, cancels the list popup,
       restoring the DropDown widget to the state it was in  before  the  list
       was  popped  up.  If the text field area is non-editable, clicking any-
       where in the text field the list will also pop down.

       Resources are available to change the margin sizes, the location of the
       left edge of the popup list, whether or not the label is shown, whether
       the text field widget may be edited, and whether or not the text in the
       list  is verified against the choices available in the list. By setting
       resources that occur in the children of the DropDown widget,  the  con-
       tents of the list, the number of items visible in the list, the initial
       value of the text field, and the value of  the  label  may  be  set  or
       changed dynamically.

       If  a  developer  wishes  the  popup list's shell to be resizable, they
       should set the allowShellResize to True at creation time.

   Classes
       XmDropDown inherits behavior, resources, and traits from Core,  Compos-
       ite, and XmManager classes.

       The class pointer is xmDropDownWidgetClass.

       The class name is XmDropDown.


   New Resources
       The  following table defines a set of widget resources used by the pro-
       grammer to specify data. The programmer can also set the resource  val-
       ues  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 or XmC prefix and use the remaining letters. To specify one of
       the defined values for a resource in a .Xdefaults file, remove  the  Xm
       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 at creation time (C), set
       by using XtSetValues (S), retrieved by using XtGetValues (G), or is not
       applicable (N/A).

       +---------------------------------------------------------------------------------------+
       |                            |  XmDropDown Resource|Set             |          |        |
       |Name                        | Class               | Type           | Default  | Access |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNcustomizedCombinationBox | XmCBoolean          | Boolean        | False    | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNeditable                 | XmCBoolean          | Boolean        | True     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNhorizontalMargin         | XmCMargin           | Dimension      | 2        | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNitemCount                | list                | int            | 0        | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNitems                    | list                | XmStringTable  | NULL     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNlabelString              | label               | XmString       | "label"  | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNpopupCursor              | XmCCursor           | Cursor         | left_ptr | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNpopupOffset              | MxCPopupOffset      | int            | 15       | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNpopupShellWidget         | XmCWidget           | Widget         | NULL     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNshowLabel                | XmCBoolean          | Boolean        | True     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNupdateShellCallback      | XmCCallback         | XtCallbackList | NULL     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNupdateTextCallback       | XmCCallback         | XtCallbackList | NULL     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNuseTextField             | XmCUseTextField     | Boolean        | True     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNvalue                    | text                | String         | ""       | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNverify                   | XmCVerify           | Boolean        | True     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNverifyTextCallback       | XmCCallback         | XtCallbackList | NULL     | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNverticalMargin           | XmCMargin           | Dimension      | 2        | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       |XmNvisibleItemCount         | XmCVisibleItemCount | int            | 0        | CSG    |
       +----------------------------+---------------------+----------------+----------+--------+
       +----------------------------+---------------------+----------------+----------+--------+
       XmNcustomizedCombinationBox
                 If  this  resource is True then the widget will not automati-
                 cally create a popup shell and list widget. This resource can
                 be  used, as the name implies, to create a custom combination
                 box that has something other than  a  list  in  it.  If  this
                 resource  is  true then a shell must be provided to the Drop-
                 Down widget via the popupShellWidget  resource.  Just  before
                 the  shell  is  popped  up the updateShellCallback is called.
                 Just after the shell is popped down the updateTextCallback is
                 called.  If  verify  is  true  then the verifyTextCallback is
                 called when the combo box needs to verify the contents of the
                 text widget against the allowable values in the custom shell.

       XmNeditable
                 This boolean value determines whether the user is allowed  to
                 type  into  TextField  widget of the DropDown widget. If this
                 value is False, selecting the text field will popup the combo
                 box list

       XmNhorizontalMargin
                 Specifies  the  horizontal  spacing between the child widgets
                 and the boundary of the DropDown widget.

       XmNverticalMargin
                 Specifies the vertical spacing between the child widgets  and
                 the boundary of the DropDown widget.

       XmNitemCount
                 The number of items in the popup list.

       XmNitems  The  list  of  all choice that will be displayed in the popup
                 list.

       XmNlabelString
                 The string displayed as the label of the DropDown widget.

       XmNpopupCursor
                 The cursor to display to the user when the DropDown's list is
                 popped  up.   See  X Window System, Robert Scheiffler et al.,
                 Appendix B, for choices.

       XmNpopupOffset
                 The amount of space in pixels between the left  edge  of  the
                 Text  widget  and  the left edge of the list when the list is
                 displayed. Positive values mean the text's left edge is  far-
                 ther  to  the  left,  negative values mean the list's edge is
                 farther to the left. If this is a non-custom DropDown  widget
                 the  right  edge  of the text and the right edge of the arrow
                 button will always line up.

       XmNpopupShellWidget
                 The widget identifier for the shell that is  popped  up  when
                 the  arrow  is  clicked. If customizedCombinationBox is False
                 then this widget is automatically  created  by  the  DropDown
                 widget.

       XmNshowLabel
                 A  boolean value that specifies whether or not to display the
                 DropDown Label widget.

       XmNupdateShellCallback

       XmNupdateTextCallback
                 The callback routine to call when  either  the  shell  widget
                 contents  or the Text widget need to be updated to correspond
                 with the other. The shell is updated just before it is popped
                 up.  The text is updated just after the shell is popped down.
                 If customizedComboBox is False  then  the  updates  are  done
                 automatically  by the combo box. These routines are called to
                 inform the application that an action has been taken, in case
                 it would like to do any further processing.

       XmNuseTextField
                 A boolean value that specifies if an XmTextField or an XmText
                 widget should be used for the text entry portion of the Drop-
                 Down widget.

       XmNvalue  The string displayed in the Text widget.

       XmNverify If  this resource is true the DropDown widget will verify its
                 value against the list whenever it loses focus  or  the  user
                 types  <Carriage  Return>.  If  the  verification  fails,  an
                 XtWarning is generated with a name of XmNtextVerifyFailed. To
                 trap this message register an XtWarningMsgHandler.

       XmNverifyTextCallback
                 This  routine  is  called whenever the Text widget's contents
                 may need to be verified against the popup  shell's  contents.
                 If the customizedComboBox resource is False then the DropDown
                 widget has already performed the verification when this  rou-
                 tine is called.

       XmNvisibleItemCount
                 The number of items visible in the popup list at one time.

   Children
       The  DropDown  is composed of many sub-widgets. Most of the information
       displayed to the user is set through these  sub  widgets.  Most  values
       passed to this widget through the argument list at creation time or via
       set values are passed to each of this  widget's  children.  Get  values
       requests  must  be  made on a child by child basis. The children of the
       DropDown are listed below. The OSF/Motifdocumentation  should  be  con-
       sulted  for  an  exhaustive set of resources for each child.  A partial
       list of the most common resources are listed here for convenience.



       XmDropDown        comboBox

                         XmLabel          label

                         XmTextField      text

                         XmArrowButton    arrow

                         OverrideShell    popupShell

                         XmScrolledWindow listSW

                                          XmScrollBar    ListvScrollBar

                                          XmScrollBar    ListhScrollBar

                                          XmList         list

       The popup shell and its children are only created when customizedCombi-
       nationBox is False.


   Inherited Resources
       XmDropDown  inherits  behavior  and  resources  from  the  superclasses
       described in the following tables.  For a complete description of  each
       resource, refer to the reference page for that superclass.


       +----------------------------------------------------------------------------------------------------+
       |                        |             XmManager Resource Set        |                      |        |
       |Name                    | Class                 | Type              | Default              | Access |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNbottomShadowColor    | XmCBottomShadowColor  | Pixel             | dynamic              | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNbottomShadowPixmap   | XmCBottomShadowPixmap | Pixmap            | XmUNSPECIFIED_PIXMAP | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNforeground           | XmCForeground         | Pixel             | dynamic              | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhelpCallback         | XmCCallback           | XtCallbackList    | NULL                 | C      |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhighlightColor       | XmCHighlightColor     | Pixel             | dynamic              | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNhighlightPixmap      | XmCHighlightPixmap    | Pixmap            | dynamic              | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNinitialFocus         | XmCInitialFocus       | Widget            | NULL                 | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNlayoutDirection      | XmCLayoutDirection    | XmDirection       | dynamic              | CG     |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNnavigationType       | XmCNavigationType     | XmNavigationType  | XmTAB_GROUP          | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNpopupHandlerCallback | XmCCallback           | XtCallbackList    | NULL                 | C      |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNshadowThickness      | XmCShadowThickness    | Dimension         | 0                    | CSG    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |XmNstringDirection      | XmCStringDirection    | XmStringDirection | dynamic              | CG     |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       |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    |
       +------------------------+-----------------------+-------------------+----------------------+--------+
       +------------------------+-----------------------+-------------------+----------------------+--------+

       +-----------------------------------------------------------------------+
       |                  |     Composite Resource Set      |         |        |
       |Name              | Class             | Type        | Default | Access |
       +------------------+-------------------+-------------+---------+--------+
       |XmNchildren       | XmCReadOnly       | WidgetList  | NULL    | G      |
       +------------------+-------------------+-------------+---------+--------+
       |XmNinsertPosition | XmCInsertPosition | XtOrderProc | NULL    | CSG    |
       +------------------+-------------------+-------------+---------+--------+
       |XmNnumChildren    | XmCReadOnly       | Cardinal    | 0       | G      |
       +------------------+-------------------+-------------+---------+--------+
       +------------------+-------------------+-------------+---------+--------+
       +---------------------------------------------------------------------------------------------------------------+
       |                              |               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    |
       +------------------------------+-------------------------------+----------------+----------------------+--------+
       +------------------------------+-------------------------------+----------------+----------------------+--------+
   Callback Information
       None of the DropDown's callback procedures have any call data currently
       defined for them. The widget passed to each of these functions  is  the
       DropDown widget.

       void (Callback)(Widget cbw, XtPointer client_data, XtPointer unused)

       cbw            This is the widget identifier of the DropDown widget.


       client_data    The client data passed to this widget by the application
                      programmer.

       unused         This value is undefined.


   Geometry Management
       The DropDown widget lays out its children (the label, text  and  arrow)
       in  a  row.  The amount of space they are each allocated when the Drop-
       Down is not allowed to be the exact size it desires is determined using
       the following rules:

       1.   The arrow is always given its requested size.

       2.   If  the combo box is bigger than it wants to be all extra space is
            given to the text widget.

       3.   If the combo box is smaller that is wants to be then the text  and
            label  widgets  are each sized smaller than they desire in exactly
            the same ratio.

            For example:

            If the amount of space for the label and text is  100  pixels  and
            the label wants to be 50 pixels wide and the text would like to be
            100 pixels wide then the label will get 34 pixels and the text 66.

            The  popup  shell  widget  is  sized  such  that  the width of the
            scrolled list widget equals the width of the text widget minus the
            value of the "popupOffset" resource. If the popup shell resides in
            a customized combination box, however, it is allowed to  be  what-
            ever size the child of the popup shell would like to be.



RELATED

       Composite(3),   Core(3),   XmCreateDropDown(3),  XmDropDownGetArrow(3),
       XmDropDownGetLabel(3),   XmDropDownGetList(3),    XmDropDownGetText(3),
       XmDropDownGetValue(3),    XmList(3),    XmManager(3),   XmTextField(3),
       XmVaCreateDropDown(3), and XmVaCreateManagedDropDown(3).



COPYRIGHT

       Copyright (c) 1992 by Integrated Computer Solutions, Inc.



                                                      XmDropDown(library call)

openMotif 2.3.1 - Generated Sun Nov 30 12:12:22 CST 2008
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.