


   XmGadget(3X)



   NAME
     XXmmGGaaddggeett-The Gadget widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>

   DESCRIPTION
     Gadget is a widget class used as a supporting superclass for other
     gadget classes.  It handles shadow-border drawing and highlighting,
     traversal activation and deactivation, and various callback lists needed
     by gadgets.

     The color and pixmap resources defined by XmManager are directly used by
     gadgets.  If XXttSSeettVVaalluueess is used to change one of the resources for a
     manager widget, all of the gadget children within the manager also
     change.

     Classes

     Gadget inherits behavior and resources from OObbjjeecctt and RReeccttOObbjj classes.

     The class pointer is xxmmGGaaddggeettCCllaassss.

     The class name is XXmmGGaaddggeett.

     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
     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 XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     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 XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                                  XXmmGGaaddggeett RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt   AAcccceessss
   ___________________________________________________________________________________
   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic   G
   XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
   XmNhighlightColor       XmCHighlightColor       Pixel              dynamic   G
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG
   XmNhighlightThickness   XmCHighlightThickness   Dimension          2         CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
   XmNshadowThickness      XmCShadowThickness      Dimension          2         CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic   G
   XmNtraversalOn          XmCTraversalOn          Boolean            True      CSG
   XmNunitType             XmCUnitType             unsigned char      dynamic   CSG
   XmNuserData             XmCUserData             XtPointer          NULL      CSG



   1-392






                                                                 XmGadget(3X)



     XXmmNNbboottttoommSShhaaddoowwCCoolloorr
               Contains the color to use to draw the bottom and right sides
               of the border shadow.

     XXmmNNhheellppCCaallllbbaacckk
               Specifies the list of callbacks that is called when the help
               key sequence is pressed.  The reason sent by the callback is
               XXmmCCRR__HHEELLPP.

     XXmmNNhhiigghhlliigghhttCCoolloorr
               Contains the color of the highlighting rectangle.

     XXmmNNhhiigghhlliigghhttOOnnEEnntteerr
               Specifies if the highlighting rectangle is drawn when the cur-
               sor moves into the widget.  If the shell's focus policy is
               XXmmEEXXPPLLIICCIITT, this resource is ignored, and the widget is
               highlighted when it has the focus.  If the shell's focus pol-
               icy is XXmmPPOOIINNTTEERR and if this resource is True, the highlight-
               ing rectangle is drawn when the the cursor moves into the
               widget.  If the shell's focus policy is XXmmPPOOIINNTTEERR and if this
               resource is False, the highlighting rectangle is not drawn
               when the the cursor moves into the widget.  The default is
               False.

     XXmmNNhhiigghhlliigghhttTThhiicckknneessss
               Specifies the thickness of the highlighting rectangle.

     XXmmNNnnaavviiggaattiioonnTTyyppee
               Determines whether the widget is a tab group.

                 ++oo  XXmmNNOONNEE indicates that the widget is not a tab group.

                 ++oo  XXmmTTAABB__GGRROOUUPP indicates that the widget is a tab group,
                    unless another widget in the hierarchy has an XXmmNNnnaavviiggaa--
                    ttiioonnTTyyppee of XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP.

                 ++oo  XXmmSSTTIICCKKYY__TTAABB__GGRROOUUPP indicates that the widget is a tab
                    group, even if another widget in the hierarchy has an
                    XXmmNNnnaavviiggaattiioonnTTyyppee of XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP.

                 ++oo  XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP indicates that the widget is a tab
                    group and that widgets in the hierarchy whose XXmmNNnnaavviiggaa--
                    ttiioonnTTyyppee is XXmmTTAABB__GGRROOUUPP are not tab groups.
                    When a parent widget has an XXmmNNnnaavviiggaattiioonnTTyyppee of
                    XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP, traversal of non-tab-group widgets
                    within the group is based on the order of those widgets
                    in their parent's XXmmNNcchhiillddrreenn list.
                    When any widget in a hierarchy has an XXmmNNnnaavviiggaattiioonnTTyyppee
                    of XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP, traversal of tab groups in the
                    hierarchy proceeds to widgets in the order in which their
                    XXmmNNnnaavviiggaattiioonnTTyyppee resources were specified as
                    XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP or XXmmSSTTIICCKKYY__TTAABB__GGRROOUUPP, whether by
                    creating the widgets with that value, by calling


   1-393






   XmGadget(3X)


                    XXttSSeettVVaalluueess, or by calling XXmmAAddddTTaabbGGrroouupp.

     XXmmNNsshhaaddoowwTThhiicckknneessss
               Specifies the size of the drawn border shadow.

     XXmmNNttooppSShhaaddoowwCCoolloorr
               Contains the color to use to draw the top and left sides of
               the border shadow.

     XXmmNNttrraavveerrssaallOOnn
               Specifies traversal activation for this gadget.

     XXmmNNuunniittTTyyppee
               Provides the basic support for resolution independence.  It
               defines the type of units a widget uses with sizing and posi-
               tioning resources.  If the widget's parent is a subclass of
               XXmmMMaannaaggeerr and if the XXmmNNuunniittTTyyppee resource is not explicitly
               set, it defaults to the unit type of the parent widget.  If
               the widget's parent is not a subclass of XXmmMMaannaaggeerr, the
               resource has a default unit type of XXmmPPIIXXEELLSS.
               XXmmNNuunniittTTyyppee can have the following values:

                 ++oo  XXmmPPIIXXEELLSS-all values provided to the widget are treated as
                    normal pixel values.

                 ++oo  XXmm110000TTHH__MMIILLLLIIMMEETTEERRSS-all values provided to the widget are
                    treated as 1/100 millimeter.

                 ++oo  XXmm11000000TTHH__IINNCCHHEESS-all values provided to the widget are
                    treated as 1/1000 inch.

                 ++oo  XXmm110000TTHH__PPOOIINNTTSS-all values provided to the widget are
                    treated as 1/100 point.  A point is a unit used in text
                    processing applications and is defined as 1/72 inch.

                 ++oo  XXmm110000TTHH__FFOONNTT__UUNNIITTSS-all values provided to the widget are
                    treated as 1/100 of a font unit.  A font unit has hor-
                    izontal and vertical components.  These are the values of
                    the XmScreen resources XXmmNNhhoorriizzoonnttaallFFoonnttUUnniitt and XXmmNNvveerr--
                    ttiiccaallFFoonnttUUnniitt.

     XXmmNNuusseerrDDaattaa
               Allows the application to attach any necessary specific data
               to the gadget.  This is an internally unused resource.

     Inherited Resources

     Gadget inherits the following resources from the named superclass.  For
     a complete description of each resource, refer to the man page for that
     superclass.
                               RReeccttOObbjj RReessoouurrccee SSeett
       NNaammee                   CCllaassss            TTyyppee        DDeeffaauulltt   AAcccceessss
       ____________________________________________________________________
       XmNancestorSensitive   XmCSensitive     Boolean     dynamic   G


   1-394






                                                                 XmGadget(3X)


       XmNborderWidth         XmCBorderWidth   Dimension   0         CSG
       XmNheight              XmCHeight        Dimension   dynamic   CSG
       XmNsensitive           XmCSensitive     Boolean     True      CSG
       XmNwidth               XmCWidth         Dimension   dynamic   CSG
       XmNx                   XmCPosition      Position    0         CSG
       XmNy                   XmCPosition      Position    0         CSG
                               OObbjjeecctt RReessoouurrccee SSeett
       NNaammee                 CCllaassss         TTyyppee             DDeeffaauulltt   AAcccceessss
       ____________________________________________________________________
       XmNdestroyCallback   XmCCallback   XtCallbackList   NULL      C

     Callback Information

     A pointer to the following structure is passed to each callback:
     ttyyppeeddeeff ssttrruucctt
     {{
       iinntt          _r_e_a_s_o_n;;
       XXEEvveenntt       * _e_v_e_n_t;;
     }} XXmmAAnnyyCCaallllbbaacckkSSttrruucctt;;

     _r_e_a_s_o_n Indicates why the callback was invoked.  For this callback, _r_e_a_-
            _s_o_n is set to XXmmCCRR__HHEELLPP.

     _e_v_e_n_t  Points to the XXEEvveenntt that triggered the callback.

     Behavior

     Gadgets cannot have translations associated with them.  Because of this,
     a Gadget's behavior is determined by the Manager widget into which the
     Gadget is placed.  If focus is on a Gadget, events are passed to the
     Gadget by its Manager.

   RELATED INFORMATION
     OObbjjeecctt((33XX)), RReeccttOObbjj((33XX)), XXmmMMaannaaggeerr((33XX)), and XXmmSSccrreeeenn((33XX)).






















   1-395






   XmGetAtomName(3X)



   NAME
     XXmmGGeettAAttoommNNaammee-A function that returns the string representation for an
     atom

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//AAttoommMMggrr..hh>>
     SSttrriinngg XXmmGGeettAAttoommNNaammee ((_d_i_s_p_l_a_y, _a_t_o_m))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          AAttoomm      _a_t_o_m;;

   DESCRIPTION
     XXmmGGeettAAttoommNNaammee returns the string representation for an atom.  It mirrors
     the XXlliibb interfaces for atom management but provides client-side cach-
     ing.  When and where caching is provided in XXlliibb, the routines will
     become pseudonyms for the XXlliibb routines.

     _d_i_s_p_l_a_ySpecifies the connection to the X server

     _a_t_o_m   Specifies the atom for the property name you want returned

   RETURN VALUE
     Returns a string.
































   1-396






                                                    XmGetColorCalculation(3X)



   NAME
     XXmmGGeettCCoolloorrCCaallccuullaattiioonn-A function to get the procedure used for default
     color calculation

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmCCoolloorrPPrroocc XXmmGGeettCCoolloorrCCaallccuullaattiioonn (())

   DESCRIPTION
     XXmmGGeettCCoolloorrCCaallccuullaattiioonn returns the procedure being used to calculate
     default colors.

     For a description of XXmmCCoolloorrPPrroocc, see XXmmSSeettCCoolloorrCCaallccuullaattiioonn((33XX)).

   RETURN VALUE
     Returns the procedure used for default color calculation.

   RELATED INFORMATION
     XXmmCChhaannggeeCCoolloorr((33XX)), XXmmGGeettCCoolloorrss((33XX)), and XXmmSSeettCCoolloorrCCaallccuullaattiioonn((33XX)).




































   1-397






   XmGetColors(3X)



   NAME
     XXmmGGeettCCoolloorrss-A function that generates foreground, select, and shadow
     colors

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmGGeettCCoolloorrss ((_s_c_r_e_e_n, _c_o_l_o_r_m_a_p, _b_a_c_k_g_r_o_u_n_d, _f_o_r_e_g_r_o_u_n_d, _t_o_p__s_h_a_d_o_w, _b_o_t_t_o_m__s_h_a_d_o_w, _s_e_l_e_c_t))
          SSccrreeeenn    * _s_c_r_e_e_n;;
          CCoolloorrmmaapp  _c_o_l_o_r_m_a_p;;
          PPiixxeell     _b_a_c_k_g_r_o_u_n_d;;
          PPiixxeell     * _f_o_r_e_g_r_o_u_n_d;;
          PPiixxeell     * _t_o_p__s_h_a_d_o_w;;
          PPiixxeell     * _b_o_t_t_o_m__s_h_a_d_o_w;;
          PPiixxeell     * _s_e_l_e_c_t;;

   DESCRIPTION
     XXmmGGeettCCoolloorrss takes a screen, a colormap, and a background pixel, and it
     returns pixel values for foreground, select, and shadow colors.

     _s_c_r_e_e_n Specifies the screen for which these colors should be allocated

     _c_o_l_o_r_m_a_p
            Specifies the colormap from which these colors should be allo-
            cated

     _b_a_c_k_g_r_o_u_n_d
            Specifies the background on which the colors should be based

     _f_o_r_e_g_r_o_u_n_d
            Specifies a pointer to the returned foreground pixel value.  If
            this argument is NULL no value is allocated or returned for this
            color.

     _t_o_p__s_h_a_d_o_w
            Specifies a pointer to the returned top shadow pixel value.  If
            this argument is NULL no value is allocated or returned for this
            color.

     _b_o_t_t_o_m__s_h_a_d_o_w
            Specifies a pointer to the returned bottom shadow pixel value.
            If this argument is NULL no value is allocated or returned for
            this color.

     _s_e_l_e_c_t Specifies a pointer to the returned select pixel value.  If this
            argument is NULL no value is allocated or  returned for this
            color.

   RELATED INFORMATION
     XXmmCChhaannggeeCCoolloorr((33XX)), XXmmGGeettCCoolloorrCCaallccuullaattiioonn((33XX)), and
     XXmmSSeettCCoolloorrCCaallccuullaattiioonn((33XX)).





   1-398






                                                         XmGetDestination(3X)



   NAME
     XXmmGGeettDDeessttiinnaattiioonn-A function that returns the widget ID of the widget to
     be used as the current destination for quick paste and certain clipboard
     operations

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     WWiiddggeett XXmmGGeettDDeessttiinnaattiioonn ((_d_i_s_p_l_a_y))
          DDiissppllaayy   *_d_i_s_p_l_a_y;;

   DESCRIPTION
     XXmmGGeettDDeessttiinnaattiioonn returns the widget that is the current destination on
     the specified display.  The destination is generally the last editable
     widget on which a select, edit, insert, or paste operation was performed
     and is the destination for quick paste and certain clipboard functions.
     The destination is NULL if the application makes this call before any of
     the specified operations have been performed on an editable widget.

     _d_i_s_p_l_a_ySpecifies the display whose destination widget is to be queried

   RETURN VALUE
     Returns the widget ID for the current destination or NULL if there is no
     current destination.
































   1-399






   XmGetDragContext(3X)



   NAME
     XXmmGGeettDDrraaggCCoonntteexxtt-A Drag and Drop function that retrieves the DragContext
     widget ID associated with a timestamp

   SYNOPSIS
     ##iinncclluuddee <<XXmm//DDrraaggCC..hh>>
     WWiiddggeett XXmmGGeettDDrraaggCCoonntteexxtt ((_r_e_f_w_i_d_g_e_t, _t_i_m_e_s_t_a_m_p))
          WWiiddggeett      _r_e_f_w_i_d_g_e_t;;
          TTiimmee        _t_i_m_e_s_t_a_m_p;;

   DESCRIPTION
     XXmmGGeettDDrraaggCCoonntteexxtt returns the widget ID of the active DragContext associ-
     ated with a given display and timestamp.  A timestamp uniquely identi-
     fies which DragContext is active when more than one drag and drop tran-
     saction has been initiated on a display.  If the specified timestamp
     matches a timestamp processed between the start and finish of a single
     drag and drop transaction, the function returns the corresponding
     DragContext ID.

     _r_e_f_w_i_d_g_e_t
            Specifies the ID of the widget that the routine uses to identify
            the intended display.  The function returns the ID of the
            DragContext associated with the display value passed by this
            widget.

     _t_i_m_e_s_t_a_m_p
            Specifies a timestamp.

     For a complete definition of DragContext and its associated resources,
     see XXmmDDrraaggCCoonntteexxtt((33XX)).

   RETURN VALUE
     Returns the ID of the DragContext widget that is active for the speci-
     fied timestamp.  Otherwise, returns NULL if no active DragContext is
     found.

   RELATED INFORMATION
     XXmmDDrraaggCCoonntteexxtt((33XX)).

















   1-400






                                                         XmGetFocusWidget(3X)



   NAME
     XXmmGGeettFFooccuussWWiiddggeett-Returns the ID of the widget that has keyboard focus

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     WWiiddggeett XXmmGGeettFFooccuussWWiiddggeett ((_w_i_d_g_e_t))
          WWiiddggeett    _w_i_d_g_e_t;;

   DESCRIPTION
     XXmmGGeettFFooccuussWWiiddggeett examines the hierarchy that contains the specified
     widget and returns the ID of the widget that has keyboard focus.  The
     function extracts the widget ID from the associated Shell widget; there-
     fore the specified widget can be located anywhere in the hierarchy.

     _w_i_d_g_e_t Specifies a widget ID within a given hierarchy

   RETURN VALUE
     Returns the ID of the widget with keyboard focus.  If no child of the
     Shell has focus, the function returns NULL.

   RELATED INFORMATION
     XXmmPPrroocceessssTTrraavveerrssaall((33XX)).

































   1-401






   XmGetMenuCursor(3X)



   NAME
     XXmmGGeettMMeennuuCCuurrssoorr-A function that returns the cursor ID for the current
     menu cursor

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     CCuurrssoorr XXmmGGeettMMeennuuCCuurrssoorr ((_d_i_s_p_l_a_y))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;

   DESCRIPTION
     XXmmGGeettMMeennuuCCuurrssoorr queries the menu cursor currently being used by this
     client on the specified display and returns the cursor ID.

     This function returns the menu cursor for the default screen of the
     display.  XXmmGGeettMMeennuuCCuurrssoorr is obsolete and exists for compatibility with
     previous releases.  Instead of using this function, call XXttGGeettVVaalluueess for
     the XmScreen resource XXmmNNmmeennuuCCuurrssoorr.

     _d_i_s_p_l_a_ySpecifies the display whose menu cursor is to be queried

   RETURN VALUE
     Returns the cursor ID for the current menu cursor or the value None if a
     cursor is not yet defined.  A cursor will not be defined if the applica-
     tion makes this call before the client has created any menus on the
     specified display.

   RELATED INFORMATION
     XXmmSSccrreeeenn((33XX)).



























   1-402






                                                              XmGetPixmap(3X)



   NAME
     XXmmGGeettPPiixxmmaapp-A pixmap caching function that generates a pixmap, stores it
     in a pixmap cache, and returns the pixmap

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     PPiixxmmaapp XXmmGGeettPPiixxmmaapp ((_s_c_r_e_e_n, _i_m_a_g_e__n_a_m_e, _f_o_r_e_g_r_o_u_n_d, _b_a_c_k_g_r_o_u_n_d))
          SSccrreeeenn    **_s_c_r_e_e_n;;
          cchhaarr      **_i_m_a_g_e__n_a_m_e;;
          PPiixxeell     _f_o_r_e_g_r_o_u_n_d;;
          PPiixxeell     _b_a_c_k_g_r_o_u_n_d;;

   DESCRIPTION
     XXmmGGeettPPiixxmmaapp uses the parameter data to perform a lookup in the pixmap
     cache to see if a pixmap has already been generated that matches the
     data.  If one is found, a reference count is incremented and the pixmap
     is returned.  Applications should use XXmmDDeessttrrooyyPPiixxmmaapp when the pixmap is
     no longer needed.

     If a pixmap is not found, _i_m_a_g_e__n_a_m_e is used to perform a lookup in the
     image cache.  If an image is found, it is used to generate the pixmap,
     which is then cached and returned.

     If an image is not found, the _i_m_a_g_e__n_a_m_e is used as a filename, and a
     search is made for an XX1100 or XX1111 bitmap file.  If it is found, the file
     is read, converted into an image, and cached in the image cache.  The
     image is then used to generate a pixmap, which is cached and returned.

     If _i_m_a_g_e__n_a_m_e has a leading slash (//), it specifies a full pathname, and
     XXmmGGeettPPiixxmmaapp opens the file as specified.  Otherwise, _i_m_a_g_e__n_a_m_e speci-
     fies a filename.  In this case XXmmGGeettPPiixxmmaapp looks for the file along a
     search path specified by the XXBBMMLLAANNGGPPAATTHH environment variable or by a
     default search path, which varies depending on whether or not the XXAAPP--
     PPLLRREESSDDIIRR environment variable is set.

     The XXBBMMLLAANNGGPPAATTHH environment variable specifies a search path for X bit-
     map files.  It can contain the substitution field %B, where the
     _i_m_a_g_e__n_a_m_e argument to XXmmGGeettPPiixxmmaapp is substituted for %B.  It can also
     contain the substitution fields accepted by XXttRReessoollvveePPaatthhnnaammee.  The sub-
     stitution field %T is always mapped to bbiittmmaappss, and %S is always mapped
     to NULL.

     If XXBBMMLLAANNGGPPAATTHH is not set but the environment variable XXAAPPPPLLRREESSDDIIRR is
     set, the following pathnames are searched:
               %%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%NN//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%NN//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%NN//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%BB
               $$HHOOMMEE//bbiittmmaappss//%%BB
               $$HHOOMMEE//%%BB


   1-403






   XmGetPixmap(3X)


               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
               //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

     If neither XXBBMMLLAANNGGPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set, the following pathnames
     are searched:
               %%BB
               $$HHOOMMEE//%%LL//bbiittmmaappss//%%NN//%%BB
               $$HHOOMMEE//%%ll//bbiittmmaappss//%%NN//%%BB
               $$HHOOMMEE//bbiittmmaappss//%%NN//%%BB
               $$HHOOMMEE//%%LL//bbiittmmaappss//%%BB
               $$HHOOMMEE//%%ll//bbiittmmaappss//%%BB
               $$HHOOMMEE//bbiittmmaappss//%%BB
               $$HHOOMMEE//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
               //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

     These paths are defaults that vendors may change.  For example, a vendor
     may use different directories for //uussrr//lliibb//XX1111 and //uussrr//iinncclluuddee//XX1111.

     The following substitutions are used in these paths:

     %%BB   The image name, from the _i_m_a_g_e__n_a_m_e argument.

     %%NN   The class name of the application.

     %%LL   The display's language string.

     %%ll   The language component of the display's language string.

     Parameter descriptions are listed below:

     _s_c_r_e_e_n    Specifies the display screen on which the pixmap is to be
               drawn.  The depth of the pixmap is the default depth for this
               screen.

     _i_m_a_g_e__n_a_m_e
               Specifies the name of the image to be used to generate the
               pixmap

     _f_o_r_e_g_r_o_u_n_d
               Combines the image with the _f_o_r_e_g_r_o_u_n_d color to create the
               pixmap if the image referenced is a bit-per-pixel image

     _b_a_c_k_g_r_o_u_n_d


   1-404






                                                              XmGetPixmap(3X)


               Combines the image with the _b_a_c_k_g_r_o_u_n_d color to create the
               pixmap if the image referenced is a bit-per-pixel image

   RETURN VALUE
     Returns a pixmap when successful; returns XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP if the
     image corresponding to the _i_m_a_g_e__n_a_m_e cannot be found.

   RELATED INFORMATION
     XXmmDDeessttrrooyyPPiixxmmaapp((33XX)), XXmmGGeettPPiixxmmaappBByyDDeepptthh((33XX)), XXmmIInnssttaallllIImmaaggee((33XX)), and
     XXmmUUnniinnssttaallllIImmaaggee((33XX)).














































   1-405






   XmGetPixmapByDepth(3X)



   NAME
     XXmmGGeettPPiixxmmaappBByyDDeepptthh-A pixmap caching function that generates a pixmap,
     stores it in a pixmap cache, and returns the pixmap

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     PPiixxmmaapp XXmmGGeettPPiixxmmaappBByyDDeepptthh ((_s_c_r_e_e_n, _i_m_a_g_e__n_a_m_e,_f_o_r_e_g_r_o_u_n_d, _b_a_c_k_g_r_o_u_n_d, _d_e_p_t_h))
          SSccrreeeenn    **_s_c_r_e_e_n;;
          cchhaarr      **_i_m_a_g_e__n_a_m_e;;
          PPiixxeell     _f_o_r_e_g_r_o_u_n_d;;
          PPiixxeell     _b_a_c_k_g_r_o_u_n_d;;
          iinntt       _d_e_p_t_h;;

   DESCRIPTION
     XXmmGGeettPPiixxmmaappBByyDDeepptthh uses the parameter data to perform a lookup in the
     pixmap cache to see if a pixmap has already been generated that matches
     the data.  If one is found, a reference count is incremented and the
     pixmap is returned.  Applications should use XXmmDDeessttrrooyyPPiixxmmaapp when the
     pixmap is no longer needed.

     If a matching pixmap is not found, _i_m_a_g_e__n_a_m_e is used to perform a
     lookup in the image cache.  If an image is found, it is used to generate
     the pixmap, which is then cached and returned.

     If an image is not found, _i_m_a_g_e__n_a_m_e is used as a filename, and a search
     is made for an XX1100 or XX1111 bitmap file.  If it is found, the file is
     read, converted into an image, and cached in the image cache.  The image
     is then used to generate a pixmap, which is cached and returned.

     If _i_m_a_g_e__n_a_m_e has a leading slash (//), it specifies a full pathname, and
     XXmmGGeettPPiixxmmaappBByyDDeepptthh opens the file as specified.  Otherwise, _i_m_a_g_e__n_a_m_e
     specifies a filename.  In this case XXmmGGeettPPiixxmmaappBByyDDeepptthh looks for the
     file along a search path specified by the XXBBMMLLAANNGGPPAATTHH environment vari-
     able or by a default search path, which varies depending on whether or
     not the XXAAPPPPLLRREESSDDIIRR environment variable is set.

     The XXBBMMLLAANNGGPPAATTHH environment variable specifies a search path for X bit-
     map files.  It can contain the substitution field %B, where the
     _i_m_a_g_e__n_a_m_e argument to XXmmGGeettPPiixxmmaappBByyDDeepptthh is substituted for %B.  It can
     also contain the substitution fields accepted by XXttRReessoollvveePPaatthhnnaammee.  The
     substitution field %T is always mapped to bbiittmmaappss, and %S is always
     mapped to NULL.

     If XXBBMMLLAANNGGPPAATTHH is not set, but the environment variable XXAAPPPPLLRREESSDDIIRR is
     set, the following pathnames are searched:
               %%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%NN//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%NN//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%NN//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%BB
               $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%BB
               $$HHOOMMEE//bbiittmmaappss//%%BB


   1-406






                                                       XmGetPixmapByDepth(3X)


               $$HHOOMMEE//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
               //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

     If neither XXBBMMLLAANNGGPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set, the following pathnames
     are searched:
               %%BB
               $$HHOOMMEE//%%LL//bbiittmmaappss//%%NN//%%BB
               $$HHOOMMEE//%%ll//bbiittmmaappss//%%NN//%%BB
               $$HHOOMMEE//bbiittmmaappss//%%NN//%%BB
               $$HHOOMMEE//%%LL//bbiittmmaappss//%%BB
               $$HHOOMMEE//%%ll//bbiittmmaappss//%%BB
               $$HHOOMMEE//bbiittmmaappss//%%BB
               $$HHOOMMEE//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%NN//%%BB
               //uussrr//lliibb//XX1111//%%LL//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//%%ll//bbiittmmaappss//%%BB
               //uussrr//lliibb//XX1111//bbiittmmaappss//%%BB
               //uussrr//iinncclluuddee//XX1111//bbiittmmaappss//%%BB

     These paths are defaults that vendors may change.  For example, a vendor
     may use different directories for //uussrr//lliibb//XX1111 and //uussrr//iinncclluuddee//XX1111.

     The following substitutions are used in these paths:

     %%BB   The image name, from the _i_m_a_g_e__n_a_m_e argument

     %%NN   The class name of the application

     %%LL   The display's language string

     %%ll   The language component of the display's language string

     Parameter descriptions are listed below:

     _s_c_r_e_e_n    Specifies the display screen on which the pixmap is to be
               drawn

     _i_m_a_g_e__n_a_m_e
               Specifies the name of the image to be used to generate the
               pixmap

     _f_o_r_e_g_r_o_u_n_d
               Combines the image with the _f_o_r_e_g_r_o_u_n_d color to create the
               pixmap if the image referenced is a bit-per-pixel image

     _b_a_c_k_g_r_o_u_n_d


   1-407






   XmGetPixmapByDepth(3X)


               Combines the image with the _b_a_c_k_g_r_o_u_n_d color to create the
               pixmap if the image referenced is a bit-per-pixel image

     _d_e_p_t_h     Specifies the depth of the pixmap

   RETURN VALUE
     Returns a pixmap when successful; returns XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP if the
     image corresponding to _i_m_a_g_e__n_a_m_e cannot be found.

   RELATED INFORMATION
     XXmmDDeessttrrooyyPPiixxmmaapp((33XX)), XXmmIInnssttaallllIImmaaggee((33XX)), and XXmmUUnniinnssttaallllIImmaaggee((33XX)).













































   1-408






                                                    XmGetPostedFromWidget(3X)



   NAME
     XXmmGGeettPPoosstteeddFFrroommWWiiddggeett-A RowColumn function that returns the widget from
     which a menu was posted

   SYNOPSIS
     ##iinncclluuddee <<XXmm//RRoowwCCoolluummnn..hh>>
     WWiiddggeett XXmmGGeettPPoosstteeddFFrroommWWiiddggeett ((_m_e_n_u))
          WWiiddggeett    _m_e_n_u;;

   DESCRIPTION
     XXmmGGeettPPoosstteeddFFrroommWWiiddggeett returns the widget from which a menu was posted.
     For torn-off menus, this function returns the widget from which the menu
     was originally torn.  An application can use this routine during the
     activate callback to determine the context in which the menu callback
     should be interpreted.

     _m_e_n_u   Specifies the widget ID of the menu

     For a complete definition of RowColumn and its associated resources, see
     XXmmRRoowwCCoolluummnn((33XX)).

   RETURN VALUE
     Returns the widget ID of the widget from which the menu was posted.  If
     the menu is a Popup Menu, the returned widget is the widget from which
     the menu was popped up.  If the menu is a Pulldown Menu, the returned
     widget is the MenuBar or OptionMenu from which the widget was pulled
     down.

   RELATED INFORMATION
     XXmmRRoowwCCoolluummnn((33XX)).

























   1-409






   XmGetSecondaryResourceData(3X)



   NAME
     XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa-A function that provides access to secondary
     widget resource data

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     CCaarrddiinnaall XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa ((_w_i_d_g_e_t__c_l_a_s_s, _s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n))
          WWiiddggeettCCllaassss         _w_i_d_g_e_t__c_l_a_s_s;;
          XXmmSSeeccoonnddaarryyRReessoouurrcceeDDaattaa****_s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n;;

   DESCRIPTION
     Some Motif widget classes (such as Gadget, Text, and VendorShell) have
     resources that are not accessible via the functions XXttGGeettRReessoouurrcceeLLiisstt
     and XXttGGeettCCoonnssttrraaiinnttRReessoouurrcceeLLiisstt.  In order to retrieve the descriptions
     of these resources, an application must use XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa.

     When a widget class has such resources, this function provides descrip-
     tions of the resources in one or more data structures.  XXmmGGeettSSeeccoonn--
     ddaarryyRReessoouurrcceeDDaattaa takes a widget class argument and returns the number of
     these data structures associated with the widget class.  If the return
     value is greater than 0, the function allocates and fills an array of
     pointers to the corresponding data structures.  It returns this array at
     the address that is the value of the _s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n argument.

     The type XXmmSSeeccoonnddaarryyRReessoouurrcceeDDaattaa is a pointer to a structure with two
     members that are useful to an application: _r_e_s_o_u_r_c_e_s, of type XXttRReessoouurr--
     cceeLLiisstt, and _n_u_m__r_e_s_o_u_r_c_e_s, of type CCaarrddiinnaall.  The _r_e_s_o_u_r_c_e_s member is a
     list of the widget resources that are not accessible using Xt functions.
     The _n_u_m__r_e_s_o_u_r_c_e_s member is the length of the _r_e_s_o_u_r_c_e_s list.

     If the return value is greater than 0, XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa allo-
     cates memory that the application must free.  Use XXttFFrreeee to free the
     resource list in each structure (the value of the _r_e_s_o_u_r_c_e_s member), the
     structures themselves, and the array of pointers to the structures (the
     array whose address is _s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n).

     _w_i_d_g_e_t__c_l_a_s_s
            Specifies the widget class for which secondary resource data is
            to be retrieved.

     _s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n
            Specifies a pointer to an array of XXmmSSeeccoonnddaarryyRReessoouurrcceeDDaattaa
            pointers to be returned by this function.  If the widget class
            has no secondary resource data (i.e., if the value returned by
            the function is 0), the function returns no meaningful value for
            this argument.

   RETURN VALUE
     Returns the number of secondary resource data structures associated with
     this widget class.





   1-410






                                               XmGetSecondaryResourceData(3X)


   EXAMPLE
     The following example uses XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa to print the names
     of the secondary resources of the Motif Text widget and then frees the
     data allocated by the function:
     XmSecondaryResourceData * block_array ;
     Cardinal num_blocks, i, j ;
     if (num_blocks = XmGetSecondaryResourceData (xmTextWidgetClass,
                                                  &block_array)) {
       for (i = 0; i < num_blocks; i++) {
         for (j = 0 ; j < block_array[i]->num_resources; j++) {
           printf("%s\n", block_array[i]->resources[j].resource_name);
         }
         XtFree((char*)block_array[i]->resources);
         XtFree((char*)block_array[i]);
       }
       XtFree((char*)block_array);
     }







































   1-411






   XmGetTabGroup(3X)



   NAME
     XXmmGGeettTTaabbGGrroouupp-Returns the widget ID of a tab group

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     WWiiddggeett XXmmGGeettTTaabbGGrroouupp ((_w_i_d_g_e_t))
          WWiiddggeett    _w_i_d_g_e_t;;

   DESCRIPTION
     XXmmGGeettTTaabbGGrroouupp returns the widget ID of the tab group that contains the
     specified widget.

     _w_i_d_g_e_t Specifies a widget ID within a tab group

   RETURN VALUE
     Returns the widget ID of a tab group or shell, determined as follows:

       ++oo  If _w_i_d_g_e_t is a tab group or shell, returns _w_i_d_g_e_t

       ++oo  If neither _w_i_d_g_e_t nor any ancestor up to the nearest shell is a tab
          group, returns the nearest ancestor of _w_i_d_g_e_t that is a shell

       ++oo  Otherwise, returns the nearest ancestor of _w_i_d_g_e_t that is a tab
          group

   RELATED INFORMATION
     XXmmAAddddTTaabbGGrroouupp((33XX)), XXmmMMaannaaggeerr((33XX)), and XXmmPPrriimmiittiivvee((33XX)).




























   1-412






                                                      XmGetTearOffControl(3X)



   NAME
     XXmmGGeettTTeeaarrOOffffCCoonnttrrooll-A RowColumn function that obtains the widget ID for
     the tear-off control in a menu

   SYNOPSIS
     ##iinncclluuddee <<XXmm//RRoowwCCoolluummnn..hh>>
     WWiiddggeett XXmmGGeettTTeeaarrOOffffCCoonnttrrooll ((_m_e_n_u))
          WWiiddggeett    _m_e_n_u;;

   DESCRIPTION
     XXmmGGeettTTeeaarrOOffffCCoonnttrrooll provides the application with the means for obtain-
     ing the widget ID of the internally created tear-off control in a tear-
     off menu.

     RowColumn creates a tear-off control for a PulldownMenu or PopupMenu
     when the XXmmNNtteeaarrOOffffMMooddeell resource is initialized or set to
     XXmmTTEEAARR__OOFFFF__EENNAABBLLEEDD.  The tear-off control is a widget that appears as
     the first element in the menu.  The user tears off the menu by means of
     mouse or keyboard events in the tear-off control.

     The tear-off control has Separator-like behavior.  Once the application
     has obtained the widget ID of the tear-off control, it can set resources
     to specify the appearance of the control.  The application or user can
     also set these resources in a resource file by using the name of the
     control, which is "TearOffControl".  For a list of the resources the
     application or user can set, see XXmmRRoowwCCoolluummnn((33XX)).

     _m_e_n_u   Specifies the widget ID of the RowColumn PulldownMenu or Popup-
            Menu

     For more information on tear-off menus and a complete definition of
     RowColumn and its associated resources, see XXmmRRoowwCCoolluummnn((33XX)).

   RETURN VALUE
     Returns the widget ID for the tear-off control, or NULL if no tear-off
     control exists.  An application should not assume that the returned
     widget will be of any particular class.

   RELATED INFORMATION
     XXmmRRoowwCCoolluummnn((33XX)).















   1-413






   XmGetVisibility(3X)



   NAME
     XXmmGGeettVViissiibbiilliittyy-A function that determines if a widget is visible

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmVViissiibbiilliittyy XXmmGGeettVViissiibbiilliittyy ((_w_i_d_g_e_t))
          WWiiddggeett    _w_i_d_g_e_t;;

   DESCRIPTION
     XXmmGGeettVViissiibbiilliittyy returns the visibility state of the specified widget.

     _w_i_d_g_e_t Specifies the ID of the widget

   RETURN VALUE
     Returns one of the following values:

       ++oo  XXmmVVIISSIIBBIILLIITTYY__UUNNOOBBSSCCUURREEDD

       ++oo  XXmmVVIISSIIBBIILLIITTYY__PPAARRTTIIAALLLLYY__OOBBSSCCUURREEDD

       ++oo  XXmmVVIISSIIBBIILLIITTYY__FFUULLLLYY__OOBBSSCCUURREEDD

   RELATED INFORMATION
     XXmmIIssTTrraavveerrssaabbllee((33XX)), XXmmMMaannaaggeerr((33XX)), and XXmmPPrroocceessssTTrraavveerrssaall((33XX)).































   1-414






                                                           XmGetXmDisplay(3X)



   NAME
     XXmmGGeettXXmmDDiissppllaayy-A Display function that returns the XXmmDDiissppllaayy object ID
     for a specified display

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     WWiiddggeett XXmmGGeettXXmmDDiissppllaayy ((_d_i_s_p_l_a_y))
          DDiissppllaayy     **_d_i_s_p_l_a_y;;

   DESCRIPTION
     XXmmGGeettXXmmDDiissppllaayy returns the XXmmDDiissppllaayy object ID associated with a
     display.  The application can access Display resources by using XXttGGeett--
     VVaalluueess.

     _d_i_s_p_l_a_ySpecifies the display for which the XXmmDDiissppllaayy object ID is to be
            returned

     For a complete definition of Display and its associated resources, see
     XXmmDDiissppllaayy((33XX)).

   RETURN VALUE
     Returns the XXmmDDiissppllaayy object ID for the specified display.

   RELATED INFORMATION
     XXmmDDiissppllaayy((33XX)).






























   1-415






   XmGetXmScreen(3X)



   NAME
     XXmmGGeettXXmmSSccrreeeenn-A Screen function that returns the XXmmSSccrreeeenn object ID for
     a specified screen

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     WWiiddggeett XXmmGGeettXXmmSSccrreeeenn ((_s_c_r_e_e_n))
          SSccrreeeenn      **_s_c_r_e_e_n;;

   DESCRIPTION
     XXmmGGeettXXmmSSccrreeeenn returns the XXmmSSccrreeeenn object ID associated with a screen.
     The application can access and manipulate Screen resources by using
     XXttGGeettVVaalluueess and XXttSSeettVVaalluueess.

     _s_c_r_e_e_n Specifies the screen for which the XXmmSSccrreeeenn ID is to be returned

     For a complete definition of Screen and its associated resources, see
     XXmmSSccrreeeenn((33XX)).

   RETURN VALUE
     Returns the XXmmSSccrreeeenn object ID.

   RELATED INFORMATION
     XXmmSSccrreeeenn((33XX)).































   1-416






                                                           XmInstallImage(3X)



   NAME
     XXmmIInnssttaallllIImmaaggee-A pixmap caching function that adds an image to the pix-
     map cache

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmIInnssttaallllIImmaaggee ((_i_m_a_g_e, _i_m_a_g_e__n_a_m_e))
          XXIImmaaggee    * _i_m_a_g_e;;
          cchhaarr      * _i_m_a_g_e__n_a_m_e;;

   DESCRIPTION
     XXmmIInnssttaallllIImmaaggee stores an image in an image cache that can later be used
     to generate a pixmap.  Part of the installation process is to extend the
     resource converter used to reference these images.  The resource con-
     verter is given the image name so that the image can be referenced in a
     .Xdefaults file.  Since an image can be referenced by a widget through
     its pixmap resources, it is up to the application to ensure that the
     image is installed before the widget is created.

     _i_m_a_g_e     Points to the image structure to be installed.  The installa-
               tion process does not make a local copy of the image.  There-
               fore, the application should not destroy the image until it is
               uninstalled from the caching functions.

     _i_m_a_g_e__n_a_m_e
               Specifies a string that the application uses to name the
               image.  After installation, this name can be used in .Xde-
               faults for referencing the image.  A local copy of the name is
               created by the image caching functions.

     The image caching functions provide a set of eight preinstalled images.
     These names can be used within a ..XXddeeffaauullttss file for generating pixmaps
     for the resource for which they are provided.

           IImmaaggee NNaammee      DDeessccrriippttiioonn
           ____________________________________________________________
           background      A tile of solid background
           25_foreground   A tile of 25% foreground, 75% background
           50_foreground   A tile of 50% foreground, 50% background
           75_foreground   A tile of 75% foreground, 25% background
           horizontal      A tile of horizontal lines of the two colors
           vertical        A tile of vertical lines of the two colors
           slant_right     A tile of slanting lines of the two colors
           slant_left      A tile of slanting lines of the two colors

   RETURN VALUE
     Returns True when successful; returns False if NULL _i_m_a_g_e, NULL
     _i_m_a_g_e__n_a_m_e, or duplicate _i_m_a_g_e__n_a_m_e is used as a parameter value.

   RELATED INFORMATION
     XXmmUUnniinnssttaallllIImmaaggee((33XX)), XXmmGGeettPPiixxmmaapp((33XX)), and XXmmDDeessttrrooyyPPiixxmmaapp((33XX)).




   1-417






   XmInternAtom(3X)



   NAME
     XXmmIInntteerrnnAAttoomm-A function that returns an atom for a given name

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//AAttoommMMggrr..hh>>
     AAttoomm XXmmIInntteerrnnAAttoomm ((_d_i_s_p_l_a_y, _n_a_m_e, _o_n_l_y__i_f__e_x_i_s_t_s))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          SSttrriinngg    _n_a_m_e;;
          BBoooolleeaann   _o_n_l_y__i_f__e_x_i_s_t_s;;

   DESCRIPTION
     XXmmIInntteerrnnAAttoomm returns an atom for a given name.  It mirrors the XXlliibb
     interfaces for atom management, but provides client-side caching.  When
     and where caching is provided in XXlliibb, the routines will become pseu-
     donyms for the XXlliibb routines.

     _d_i_s_p_l_a_y   Specifies the connection to the X server

     _n_a_m_e      Specifies the name associated with the atom you want returned

     _o_n_l_y__i_f__e_x_i_s_t_s
               Specifies a Boolean value that indicates whether XXIInntteerrnnAAttoomm
               creates the atom

   RETURN VALUE
     Returns an atom.




























   1-418






                                                       XmIsMotifWMRunning(3X)



   NAME
     XXmmIIssMMoottiiffWWMMRRuunnnniinngg-A function that determines whether the window manager
     is running

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmIIssMMoottiiffWWMMRRuunnnniinngg ((_s_h_e_l_l))
          WWiiddggeett    _s_h_e_l_l;;

   DESCRIPTION
     XXmmIIssMMoottiiffWWMMRRuunnnniinngg lets a user know whether the Motif Window Manager is
     running on a screen that contains a specific widget hierarchy.  This
     function first sees whether the __MMOOTTIIFF__WWMM__IINNFFOO property is present on
     the root window of the shell's screen. If it is, its window field is
     used to query for the presence of the specified window as a child of
     root.

     _s_h_e_l_l  Specifies the shell whose screen will be tested for mmwwmm's pres-
            ence.

   RETURN VALUE
     Returns True if MWM is running.

































   1-419






   XmIsTraversable(3X)



   NAME
     XXmmIIssTTrraavveerrssaabbllee-A function that identifies whether a widget can be
     traversed

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmIIssTTrraavveerrssaabbllee ((_w_i_d_g_e_t))
          WWiiddggeett    _w_i_d_g_e_t;;

   DESCRIPTION
     XXmmIIssTTrraavveerrssaabbllee determines whether the specified widget is eligible to
     receive focus through keyboard traversal.  In general, a widget is eli-
     gible to receive focus when all of the following conditions are true:

       ++oo  The widget and its ancestors are not being destroyed, are sensi-
          tive, and have a value of True for XXmmNNttrraavveerrssaallOOnn.

       ++oo  The widget and its ancestors are realized, managed, and (except for
          gadgets) mapped.

       ++oo  Some part of the widget's rectangular area is unobscured by the
          widget's ancestors, or some part of the widget's rectangular area
          is inside the work window (but possibly outside the clip window) of
          a ScrolledWindow whose XXmmNNssccrroolllliinnggPPoolliiccyy is XXmmAAUUTTOOMMAATTIICC and whose
          XXmmNNttrraavveerrsseeOObbssccuurreeddCCaallllbbaacckk is not NULL.

     Some widgets may not be eligible to receive focus even if they meet all
     these conditions.  For example, most managers cannot receive focus
     through keyboard traversal.  Some widgets may be eligible to receive
     focus under particular conditions.  For example, a DrawingArea is eligi-
     ble to receive focus if it meets the conditions above and has no child
     whose XXmmNNttrraavveerrssaallOOnn resource is True.

     _w_i_d_g_e_t Specifies the ID of the widget

   RETURN VALUE
     Returns True if the widget is eligible to receive focus through keyboard
     traversal; otherwise, returns False.

   RELATED INFORMATION
     XXmmGGeettVViissiibbiilliittyy((33XX)) and XXmmPPrroocceessssTTrraavveerrssaall((33XX)).














   1-420






                                                                  XmLabel(3X)



   NAME
     XXmmLLaabbeell-The Label widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLaabbeell..hh>>

   DESCRIPTION
     Label is an instantiable widget and is also used as a superclass for
     other button widgets, such as PushButton and ToggleButton.  The Label
     widget does not accept any button or key input, and the help callback is
     the only callback defined.  Label also receives enter and leave events.

     Label can contain either text or a pixmap.  Label text is a compound
     string.  Refer to the _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r'_s Guide for more information
     on compound strings.  The text can be multilingual, multiline, and/or
     multifont.  When a Label is insensitive, its text is stippled, or the
     user-supplied insensitive pixmap is displayed.

     Label supports both accelerators and mnemonics primarily for use in
     Label subclass widgets that are contained in menus.  Mnemonics are
     available in a menu system when the button is visible.  Accelerators in
     a menu system are accessible even when the button is not visible.  The
     Label widget displays the mnemonic by underlining the first matching
     character in the text string.  The accelerator is displayed as a text
     string adjacent to the label text or pixmap.

     Label consists of many margin fields surrounding the text or pixmap.
     These margin fields are resources that may be set by the user, but Label
     subclasses and Manager parents also modify some of these fields.  They
     tend to modify the XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt, XXmmNNmmaarrggiinnTToopp, and
     XXmmNNmmaarrggiinnBBoottttoomm resources and leave the XXmmNNmmaarrggiinnWWiiddtthh and XXmmNNmmaarr--
     ggiinnHHeeiigghhtt resources as set by the application.

     Label takes into account XXmmNNsshhaaddoowwTThhiicckknneessss in determining its layout
     but does not draw the shadow.  That is, if XXmmNNsshhaaddoowwTThhiicckknneessss is greater
     than 0, Label leaves space for the shadow, but the shadow does not
     appear.

     In a Label XXmmNNttrraavveerrssaallOOnn and XXmmNNhhiigghhlliigghhttOOnnEEnntteerr are forced to False
     inside Popup MenuPanes, Pulldown MenuPanes, and OptionMenus.  Otherwise
     these resources default to False.

     Classes

     Label inherits behavior and resources from CCoorree and XXmmPPrriimmiittiivvee Classes.

     The class pointer is xxmmLLaabbeellWWiiddggeettCCllaassss.

     The class name is XXmmLLaabbeell.






   1-421






   XmLabel(3X)


     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
     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 XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     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 XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                                              XXmmLLaabbeell RReessoouurrccee SSeett
   NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                  AAcccceessss
   ___________________________________________________________________________________________________________
   XmNaccelerator              XmCAccelerator              String              NULL                     CSG
   XmNacceleratorText          XmCAcceleratorText          XmString            NULL                     CSG
   XmNalignment                XmCAlignment                unsigned char       dynamic                  CSG
   XmNfontList                 XmCFontList                 XmFontList          dynamic                  CSG
   XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP     CSG
   XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP     CSG
   XmNlabelString              XmCXmString                 XmString            dynamic                  CSG
   XmNlabelType                XmCLabelType                unsigned char       XmSTRING                 CSG
   XmNmarginBottom             XmCMarginBottom             Dimension           0                        CSG
   XmNmarginHeight             XmCMarginHeight             Dimension           2                        CSG
   XmNmarginLeft               XmCMarginLeft               Dimension           0                        CSG
   XmNmarginRight              XmCMarginRight              Dimension           0                        CSG
   XmNmarginTop                XmCMarginTop                Dimension           0                        CSG
   XmNmarginWidth              XmCMarginWidth              Dimension           2                        CSG
   XmNmnemonic                 XmCMnemonic                 KeySym              NULL                     CSG
   XmNmnemonicCharSet          XmCMnemonicCharSet          String              XmFONTLIST_DEFAULT_TAG   CSG
   XmNrecomputeSize            XmCRecomputeSize            Boolean             True                     CSG
   XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                  CSG

     XXmmNNaacccceelleerraattoorr
               Sets the accelerator on a button 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 KKeeyyPPrreessss events are allowed.
               Accelerators for buttons are supported only for PushButtons
               and ToggleButtons in Pulldown and Popup MenuPanes.

     XXmmNNaacccceelleerraattoorrTTeexxtt
               Specifies the text displayed for the accelerator.  The text is
               displayed adjacent to the label string or pixmap.  Accelerator
               text for buttons is displayed only for PushButtons and Tog-
               gleButtons in Pulldown and Popup Menus.

     XXmmNNaalliiggnnmmeenntt
               Specifies the label alignment for text or pixmap.


   1-422






                                                                  XmLabel(3X)



                 ++oo  XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG (left alignment)-causes the left
                    sides of the lines of text to be vertically aligned with
                    the left edge of the widget window.  For a pixmap, its
                    left side is vertically aligned with the left edge of the
                    widget window.

                 ++oo  XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR (center alignment)-causes the centers
                    of the lines of text to be vertically aligned in the
                    center of the widget window.  For a pixmap, its center is
                    vertically aligned with the center of the widget window.

                 ++oo  XXmmAALLIIGGNNMMEENNTT__EENNDD (right alignment)-causes the right sides
                    of the lines of text to be vertically aligned with the
                    right edge of the widget window.  For a pixmap, its right
                    side is vertically aligned with the right edge of the
                    widget window.
               The above descriptions for text are correct when XXmmNNssttrriinngg--
               DDiirreeccttiioonn is XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR.  When that resource is
               XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__RR__TTOO__LL, the descriptions for
               XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG and XXmmAALLIIGGNNMMEENNTT__EENNDD are switched.
               If the parent is a RowColumn whose XXmmNNiissAAlliiggnneedd resource is
               True, XXmmNNaalliiggnnmmeenntt is forced to the same value as the
               RowColumn's XXmmNNeennttrryyAAlliiggnnmmeenntt if the RowColumn's
               XXmmNNrroowwCCoolluummnnTTyyppee is XXmmWWOORRKK__AARREEAA or if the widget is a subclass
               of XmLabel.  Otherwise, the default is XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR.

     XXmmNNffoonnttLLiisstt
               Specifies the font of the text used in the widget.  If this
               value is NULL at initialization, the font  list is initialized
               by looking up the parent hierarchy of the widget for an ances-
               tor that is a subclass of the XmBulletinBoard, VendorShell, or
               XmMenuShell widget class.  If such  an ancestor is found, the
               font list is initialized to the XXmmNNbbuuttttoonnFFoonnttLLiisstt  (for button
               subclasses) or XXmmNNllaabbeellFFoonnttLLiisstt of the ancestor widget.  If no
               such ancestor is found, the default is implementation depen-
               dent.  Refer to XXmmFFoonnttLLiisstt((33XX)) for more information on the
               creation and structure of a font list.

     XXmmNNllaabbeellIInnsseennssiittiivveePPiixxmmaapp
               Specifies a pixmap used as the button face if XXmmNNllaabbeellTTyyppee is
               XXmmPPIIXXMMAAPP and the button is insensitive.  The default value,
               XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP, displays an empty label.

     XXmmNNllaabbeellPPiixxmmaapp
               Specifies the pixmap when XXmmNNllaabbeellTTyyppee is XXmmPPIIXXMMAAPP.  The
               default value, XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP, displays an empty label.

     XXmmNNllaabbeellSSttrriinngg
               Specifies the compound string when the XXmmNNllaabbeellTTyyppee is
               XXmmSSTTRRIINNGG.  If this value is NULL, it is initialized by con-
               verting the name of the widget to a compound string.  Refer to
               XXmmSSttrriinngg((33XX)) for more information on the creation and struc-
               ture of compound strings.


   1-423






   XmLabel(3X)



     XXmmNNllaabbeellTTyyppee
               Specifies the label type.

                 ++oo  XXmmSSTTRRIINNGG-displays text using XXmmNNllaabbeellSSttrriinngg.

                 ++oo  XXmmPPIIXXMMAAPP-displays pixmap using XXmmNNllaabbeellPPiixxmmaapp or XXmmNNllaa--
                    bbeellIInnsseennssiittiivveePPiixxmmaapp.

     XXmmNNmmaarrggiinnBBoottttoomm
               Specifies the amount of spacing between the bottom of the
               label text and the top of the bottom margin specified by
               XXmmNNmmaarrggiinnHHeeiigghhtt.  This may be modified by Label's subclasses.
               For example, CascadeButton may increase this field to make
               room for the cascade pixmap.

     XXmmNNmmaarrggiinnHHeeiigghhtt
               Specifies an equal amount of spacing above the margin defined
               by XXmmNNmmaarrggiinnTToopp and below the margin defined by XXmmNNmmaarrggiinnBBoott--
               ttoomm. XXmmNNmmaarrggiinnHHeeiigghhtt specifies the amount of spacing between
               the top edge of the margin set by XXmmNNmmaarrggiinnTToopp and the bottom
               edge of the top shadow, and the amount of spacing between the
               bottom edge of the margin specified by XXmmNNmmaarrggiinnBBoottttoomm and the
               top edge of the bottom shadow.

     XXmmNNmmaarrggiinnLLeefftt
               Specifies the amount of spacing between the left edge of the
               label text and the right side of the left margin (specified by
               XXmmNNmmaarrggiinnWWiiddtthh).  This may be modified by Label's subclasses.
               For example, ToggleButton may increase this field to make room
               for the toggle indicator and for spacing between the indicator
               and label.  Whether this actually applies to the left or right
               side of the label may depend on the value of XXmmNNssttrriinnggDDiirreecc--
               ttiioonn.

     XXmmNNmmaarrggiinnRRiigghhtt
               Specifies the amount of spacing between the right edge of the
               label text and the left side of the right margin (specified by
               XXmmNNmmaarrggiinnWWiiddtthh).  This may be modified by Label's subclasses.
               For example, CascadeButton may increase this field to make
               room for the cascade pixmap.  Whether this actually applies to
               the left or right side of the label may depend on the value of
               XXmmNNssttrriinnggDDiirreeccttiioonn.

     XXmmNNmmaarrggiinnTToopp
               Specifies the amount of spacing between the top of the label
               text and the bottom of the top margin specified by XXmmNNmmaarr--
               ggiinnHHeeiigghhtt.  This may be modified by Label's subclasses.  For
               example, CascadeButton may increase this field to make room
               for the cascade pixmap.

     XXmmNNmmaarrggiinnWWiiddtthh
               Specifies an equal amount of spacing to the left of the margin
               defined by XXmmNNmmaarrggiinnLLeefftt and to the right of the margin


   1-424






                                                                  XmLabel(3X)


               defined by XXmmNNmmaarrggiinnRRiigghhtt.  XXmmNNmmaarrggiinnWWiiddtthh specifies the
               amount of spacing between the left edge of the margin set by
               XXmmNNmmaarrggiinnLLeefftt and the right edge of the left shadow, and the
               amount of spacing between the right edge of the margin speci-
               fied by XXmmNNmmaarrggiinnRRiigghhtt and the left edge of the right shadow.

     XXmmNNmmnneemmoonniicc
               Provides the user with an alternate means of activating a but-
               ton.  A button 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
               XXmmNNmmnneemmoonniiccCChhaarrSSeett 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 visi-
               ble.  If the button is a CascadeButton in a MenuBar and the
               MenuBar does not have the focus, the user must use the MMAAlltt
               modifier while pressing the mnemonic.  The user can activate
               the button by pressing either the shifted or the unshifted
               mnemonic key.

     XXmmNNmmnneemmoonniiccCChhaarrSSeett
               Specifies the character set of the mnemonic for the label.
               The default is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

     XXmmNNrreeccoommppuutteeSSiizzee
               Specifies a Boolean value that indicates whether the widget
               shrinks or expands to accommodate its contents (label string
               or pixmap) as a result of an XXttSSeettVVaalluueess resource value that
               would change the size of the widget.  If True, the widget
               shrinks or expands to exactly fit the label string or pixmap.
               If False, the widget never attempts to change size on its own.

     XXmmNNssttrriinnggDDiirreeccttiioonn
               Specifies the direction in which the string is to be drawn.
               The following are the values:

                 ++oo  XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR-left to right

                 ++oo  XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__RR__TTOO__LL-right to left
               The default for this resource is determined at creation time.
               If no value is specified for this resource and the widget's
               parent is a manager, the value is inherited from the parent;
               otherwise, it defaults to XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR.

     Inherited Resources

     Label inherits behavior and resources from the following superclasses.
     For a complete description of each resource, refer to the man page for
     that superclass.
                                       XXmmPPrriimmiittiivvee RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt                AAcccceessss
   ________________________________________________________________________________________________


   1-425






   XmLabel(3X)


   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
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False                  CSG
   XmNhighlightPixmap      XmCHighlightPixmap      Pixmap             dynamic                CSG
   XmNhighlightThickness   XmCHighlightThickness   Dimension          0                      CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE                 CSG
   XmNshadowThickness      XmCShadowThickness      Dimension          0                      CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic                CSG
   XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap             dynamic                CSG
   XmNtraversalOn          XmCTraversalOn          Boolean            False                  CSG
   XmNunitType             XmCUnitType             unsigned char      dynamic                CSG
   XmNuserData             XmCUserData             XtPointer          NULL                   CSG
                                                 CCoorree RReessoouurrccee SSeett
   NNaammee                            CCllaassss                           TTyyppee             DDeeffaauulltt                AAcccceessss
   ______________________________________________________________________________________________________________
   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

     Translations

















   1-426






                                                                  XmLabel(3X)


     XmLabel includes translations from Primitive.  The XmLabel translations
     are listed below.  These translations may not directly correspond to a
     translation table.
     BBDDrraagg PPrreessss::   PPrroocceessssDDrraagg(())
     KKHHeellpp::         HHeellpp(())
     The translations used by subclasses of XmLabel for menu traversal are
     listed below.  These translations may not directly correspond to a
     translation table.
     KKLLeefftt::         MMeennuuTTrraavveerrsseeLLeefftt(())
     KKRRiigghhtt::        MMeennuuTTrraavveerrsseeRRiigghhtt(())
     KKUUpp::           MMeennuuTTrraavveerrsseeUUpp(())
     KKDDoowwnn::         MMeennuuTTrraavveerrsseeDDoowwnn(())
     MMAAnnyy KKCCaanncceell::  MMeennuuEEssccaappee(())

     Action Routines

     The XmLabel action routines are described below:

     HHeellpp(()):   In a Popup or Pulldown MenuPane, unposts all menus in the menu
               hierarchy and, when the shell's keyboard focus policy is XXmmEEXX--
               PPLLIICCIITT, restores keyboard focus to the widget that had the
               focus before the menu system was entered.  Calls the callbacks
               for XXmmNNhheellppCCaallllbbaacckk if any exist.  If there are no help call-
               backs for this widget, this action calls the help callbacks
               for the nearest ancestor that has them.

     MMeennuuEEssccaappee(()):
               In a MenuBar, disarms the CascadeButton and the menu and, when
               the shell's keyboard focus policy is XXmmEEXXPPLLIICCIITT, restores key-
               board focus to the widget that had the focus before the menu
               was entered.
               In a toplevel Pulldown MenuPane from a MenuBar, unposts the
               menu, disarms the MenuBar CascadeButton and the MenuBar, and,
               when the shell's keyboard focus policy is XXmmEEXXPPLLIICCIITT, restores
               keyboard focus to the widget that had the focus before the
               MenuBar was entered.  In other Pulldown MenuPanes, unposts the
               menu and moves the focus to its CascadeButton.  In a Popup
               MenuPane, unposts the menu and, when the shell's keyboard
               focus policy is XXmmEEXXPPLLIICCIITT, restores keyboard focus to the
               widget from which the menu was posted.

     MMeennuuTTrraavveerrsseeDDoowwnn(()):
               If the current menu item has a submenu and is in a MenuBar,
               then this action posts the submenu, disarms the current menu
               item, and arms the submenu's first traversable menu item.
               If the current menu item is in a MenuPane, then this action
               disarms the current menu item and arms the item below it.
               This action wraps within the MenuPane.  When the current menu
               item is at the MenuPane's bottom edge, then this action wraps
               to the topmost menu item in the column to the right, if one
               exists.  When the current menu item is at the bottom, right-
               most corner of the MenuPane, then this action wraps to the
               tear-off control, if present, or to the top, leftmost menu
               item.


   1-427






   XmLabel(3X)



     MMeennuuTTrraavveerrsseeLLeefftt(()):
               When the current menu item is in a MenuBar, then this action
               disarms the current item and arms the MenuBar item to the
               left.  This action wraps within the MenuBar. In MenuPanes, if
               the current menu item is not at the left edge of a MenuPane,
               this action disarms the current item and arms the item to its
               left.  If the current menu item is at the left edge of a sub-
               menu attached to a MenuBar item, then this action unposts the
               submenu and traverses to the MenuBar item to the left, wrap-
               ping if necessary.  If that MenuBar item has a submenu, it
               posts the submenu and arms the first traversable item in the
               submenu.  If the current menu item is at the left edge of a
               submenu not directly attached to a MenuBar item, then this
               action unposts the current submenu only.  In Popup or Torn-off
               MenuPanes, when the current menu item is at the left edge,
               this  action wraps within the MenuPane.  If the current menu
               item is at the left edge of the MenuPane and not in the top
               row, this action wraps to the rightmost menu item in the row
               above.  If the current menu item is in the upper, leftmost
               corner, this action wraps to the tear-off control, if present,
               or else it wraps to the bottom, rightmost menu item in the
               MenuPane.

     MMeennuuTTrraavveerrsseeRRiigghhtt(()):
               If the current menu item is in a MenuBar, then this action
               disarms the current item and arms the MenuBar item to the
               right.  This action wraps within the MenuBar. In MenuPanes, if
               the current menu item is a CascadeButton, then this action
               posts its associated submenu.  If the current menu item is not
               a CascadeButton and is not at the right edge of a MenuPane,
               this action disarms the current item and arms the item to its
               right, wrapping if necessary. If the current menu item is not
               a CascadeButton and is at the right edge of a submenu that is
               a descendent of a MenuBar, then this action unposts all sub-
               menus and traverses to the MenuBar item to the right.  If that
               MenuBar item has a submenu, it posts the submenu and arms the
               submenu's first traversable item.  In Popup or Torn-off menus,
               if the current menu item is not a CascadeButton and is at the
               right edge of a row (except the bottom row), this action wraps
               to the leftmost menu item in the row below.  If the current
               menu item is not a CascadeButton and is in the bottom, right-
               most corner of a Popup or Pulldown MenuPane, this action wraps
               to the tear-off control, if present, or else it wraps to the
               top, leftmost menu item of the MenuPane.

     MMeennuuTTrraavveerrsseeUUpp(()):
               When the current menu item is in a MenuPane, then this action
               disarms the current menu item and arms the item above it.
               This action wraps within the MenuPane.  When the current menu
               item is at the MenuPane's top edge, then this action wraps to
               the bottommost menu item in the column to the left, if one
               exists.  When the current menu item is at the top, leftmost
               corner of the MenuPane, then this action wraps to the tear-off


   1-428






                                                                  XmLabel(3X)


               control, if present, or to the bottom, rightmost menu item.

     PPrroocceessssDDrraagg(()):
               Drags the contents of a Label, identified by pressing BBDDrraagg.
               This action creates a DragContext object whose XXmmNNeexxppoorrttTTaarr--
               ggeettss resource is set to "COMPOUND_TEXT" for a label type of
               XXmmSSTTRRIINNGG; otherwise, "PIXMAP" if the label type is XXmmPPIIXXMMAAPP.
               This action is undefined for Labels used in a menu system.

     Virtual Bindings

     The bindings for virtual keys are vendor specific.  For information
     about bindings for virtual buttons and keys, see VViirrttuuaallBBiinnddiinnggss((33XX)).

   RELATED INFORMATION
     CCoorree((33XX)), XXmmCCrreeaatteeLLaabbeell((33XX)), XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy((33XX)),
     XXmmSSttrriinnggCCrreeaattee((33XX)), XXmmSSttrriinnggCCrreeaatteeLLttooRR((33XX)), and XXmmPPrriimmiittiivvee((33XX)).







































   1-429






   XmLabelGadget(3X)



   NAME
     XXmmLLaabbeellGGaaddggeett-The LabelGadget widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLaabbeellGG..hh>>

   DESCRIPTION
     LabelGadget is an instantiable widget and is also used as a superclass
     for other button gadgets, such as PushButtonGadget and ToggleBut-
     tonGadget.

     LabelGadget can contain either text or a pixmap.  LabelGadget text is a
     compound string.  Refer to the _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r'_s Guide for more
     information on compound strings.  The text can be multilingual, multi-
     line, and/or multifont.  When a LabelGadget is insensitive, its text is
     stippled, or the user-supplied insensitive pixmap is displayed.

     LabelGadget supports both accelerators and mnemonics primarily for use
     in LabelGadget subclass widgets that are contained in menus.  Mnemonics
     are available in a  menu system when the button is visible.  Accelera-
     tors in a menu system are accessible even when the button is not visi-
     ble.  The LabelGadget displays the mnemonic by underlining the first
     matching character in the text string.  The accelerator is displayed as
     a text string adjacent to the label text or pixmap.

     LabelGadget consists of many margin fields surrounding the text or pix-
     map.  These margin fields are resources that may be set by the user, but
     LabelGadget subclasses and Manager parents also modify some of these
     fields.  They tend to modify the XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt, XXmmNNmmaarr--
     ggiinnTToopp, and XXmmNNmmaarrggiinnBBoottttoomm resources and leave the XXmmNNmmaarrggiinnWWiiddtthh and
     XXmmNNmmaarrggiinnHHeeiigghhtt resources as set by the application.

     LabelGadget takes into account XXmmNNsshhaaddoowwTThhiicckknneessss in determining its
     layout but does not draw the shadow.  That is, if XXmmNNsshhaaddoowwTThhiicckknneessss is
     greater than 0, LabelGadget leaves space for the shadow, but the shadow
     does not appear.

     In a LabelGadget XXmmNNttrraavveerrssaallOOnn and XXmmNNhhiigghhlliigghhttOOnnEEnntteerr are forced to
     False inside Popup MenuPanes, Pulldown MenuPanes, and OptionMenus.  Oth-
     erwise these resources default to False.

     Classes

     LabelGadget inherits behavior and resources from OObbjjeecctt, RReeccttOObbjj and
     XXmmGGaaddggeett classes.

     The class pointer is xxmmLLaabbeellGGaaddggeettCCllaassss.

     The class name is XXmmLLaabbeellGGaaddggeett.






   1-430






                                                            XmLabelGadget(3X)


     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
     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 XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     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 XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                                          XXmmLLaabbeellGGaaddggeett RReessoouurrccee SSeett
   NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                AAcccceessss
   _________________________________________________________________________________________________________
   XmNaccelerator              XmCAccelerator              String              NULL                   CSG
   XmNacceleratorText          XmCAcceleratorText          XmString            NULL                   CSG
   XmNalignment                XmCAlignment                unsigned char       dynamic                CSG
   XmNfontList                 XmCFontList                 XmFontList          dynamic                CSG
   XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP   CSG
   XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP   CSG
   XmNlabelString              XmCXmString                 XmString            dynamic                CSG
   XmNlabelType                XmCLabelType                unsigned char       XmSTRING               CSG
   XmNmarginBottom             XmCMarginBottom             Dimension           0                      CSG
   XmNmarginHeight             XmCMarginHeight             Dimension           2                      CSG
   XmNmarginLeft               XmCMarginLeft               Dimension           0                      CSG
   XmNmarginRight              XmCMarginRight              Dimension           0                      CSG
   XmNmarginTop                XmCMarginTop                Dimension           0                      CSG
   XmNmarginWidth              XmCMarginWidth              Dimension           2                      CSG
   XmNmnemonic                 XmCMnemonic                 KeySym              NULL                   CSG
   XmNmnemonicCharSet          XmCMnemonicCharSet          String              dynamic                CSG
   XmNrecomputeSize            XmCRecomputeSize            Boolean             True                   CSG
   XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                CSG

     XXmmNNaacccceelleerraattoorr
               Sets the accelerator on a button 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 KKeeyyPPrreessss events are allowed.
               Accelerators for buttons are supported only for PushBut-
               tonGadgets and ToggleButtonGadgets in Pulldown and Popup
               menus.

     XXmmNNaacccceelleerraattoorrTTeexxtt
               Specifies the text displayed for the accelerator.  The text is
               displayed adjacent to the label string or pixmap.  Accelerator
               text for buttons is displayed only for PushButtonGadgets and
               ToggleButtonGadgets in Pulldown and Popup Menus.

     XXmmNNaalliiggnnmmeenntt


   1-431






   XmLabelGadget(3X)


               Specifies the label alignment for text or pixmap.

                 ++oo  XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG (left alignment)-causes the left
                    sides of the lines of text to be vertically aligned with
                    the left edge of the gadget.  For a pixmap, its left side
                    is vertically aligned with the left edge of the gadget.

                 ++oo  XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR (center alignment)-causes the centers
                    of the lines of text to be vertically aligned in the
                    center of the gadget.  For a pixmap, its center is verti-
                    cally aligned with the center of the gadget.

                 ++oo  XXmmAALLIIGGNNMMEENNTT__EENNDD (right alignment)-causes the right sides
                    of the lines of text to be vertically aligned with the
                    right edge of the gadget.  For a pixmap, its right side
                    is vertically aligned with the right edge of the gadget.
               The above descriptions for text are correct when XXmmNNssttrriinngg--
               DDiirreeccttiioonn is XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR; the descriptions for
               XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG and XXmmAALLIIGGNNMMEENNTT__EENNDD are switched when
               the resource is XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__RR__TTOO__LL.
               If the parent is a RowColumn whose XXmmNNiissAAlliiggnneedd resource is
               True, XXmmNNaalliiggnnmmeenntt is forced to the same value as the
               RowColumn's XXmmNNeennttrryyAAlliiggnnmmeenntt if the RowColumn's
               XXmmNNrroowwCCoolluummnnTTyyppee is XXmmWWOORRKK__AARREEAA or if the gadget is a subclass
               of XmLabelGadget.  Otherwise, the default is
               XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR.

     XXmmNNffoonnttLLiisstt
               Specifies the font of the text used in the gadget.  If this
               value is NULL at initialization, the font list is initialized
               by looking up the parent hierarchy of the widget for an ances-
               tor that is a subclass of the XmBulletinBoard, VendorShell, or
               XmMenuShell widget class.  If such an ancestor is found, the
               font list is initialized to the XXmmNNbbuuttttoonnFFoonnttLLiisstt (for button
               gadget subclasses) or XXmmNNllaabbeellFFoonnttLLiisstt of the ancestor widget.
               If no such ancestor is found, the default is implementation
               dependent.  Refer to XXmmFFoonnttLLiisstt((33XX)) for more information on
               the creation and structure of a font list.

     XXmmNNllaabbeellIInnsseennssiittiivveePPiixxmmaapp
               Specifies a pixmap used as the button face if XXmmNNllaabbeellTTyyppee is
               XXmmPPIIXXMMAAPP and the button is insensitive.  The default value,
               XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP, displays an empty label.

     XXmmNNllaabbeellPPiixxmmaapp
               Specifies the pixmap when XXmmNNllaabbeellTTyyppee is XXmmPPIIXXMMAAPP.  The
               default value, XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP, displays an empty label.

     XXmmNNllaabbeellSSttrriinngg
               Specifies the compound string when XXmmNNllaabbeellTTyyppee is XXmmSSTTRRIINNGG.
               If this value is NULL, it is initialized by converting the
               name of the gadget to a compound string.  Refer to
               XXmmSSttrriinngg((33XX)) for more information on the creation and the
               structure of compound strings.


   1-432






                                                            XmLabelGadget(3X)



     XXmmNNllaabbeellTTyyppee
               Specifies the label type.

                 ++oo  XXmmSSTTRRIINNGG - text displays XXmmNNllaabbeellSSttrriinngg

                 ++oo  XXmmPPIIXXMMAAPP - icon data in pixmap displays XXmmNNllaabbeellPPiixxmmaapp or
                    XXmmNNllaabbeellIInnsseennssiittiivveePPiixxmmaapp

     XXmmNNmmaarrggiinnBBoottttoomm
               Specifies the amount of spacing between the bottom of the
               label text and the top of the bottom margin specified by
               XXmmNNmmaarrggiinnHHeeiigghhtt.  This may be modified by LabelGadget's subc-
               lasses.  For example, CascadeButtonGadget may increase this
               field to make room for the cascade pixmap.

     XXmmNNmmaarrggiinnHHeeiigghhtt
               Specifies an equal amount of spacing above the margin defined
               by XXmmNNmmaarrggiinnTToopp and below the margin defined by XXmmNNmmaarrggiinnBBoott--
               ttoomm. XXmmNNmmaarrggiinnHHeeiigghhtt specifies the amount of spacing between
               the top edge of the margin set by XXmmNNmmaarrggiinnTToopp and the bottom
               edge of the top shadow, and the amount of spacing between the
               bottom edge of the margin specified by XXmmNNmmaarrggiinnBBoottttoomm and the
               top edge of the bottom shadow.

     XXmmNNmmaarrggiinnLLeefftt
               Specifies the amount of spacing between the left edge of the
               label text and the right side of the left margin (specified by
               XXmmNNmmaarrggiinnWWiiddtthh).  This may be modified by LabelGadget's subc-
               lasses.  For example, ToggleButtonGadget may increase this
               field to make room for the toggle indicator and for spacing
               between the indicator and label.  Whether this actually
               applies to the left or right side of the label may depend on
               the value of XXmmNNssttrriinnggDDiirreeccttiioonn.

     XXmmNNmmaarrggiinnRRiigghhtt
               Specifies the amount of spacing between the right edge of the
               label text and the left side of the right margin (specified by
               XXmmNNmmaarrggiinnWWiiddtthh).  This may be modified by LabelGadget's subc-
               lasses.  For example, CascadeButtonGadget may increase this
               field to make room for the cascade pixmap.  Whether this actu-
               ally applies to the left or right side of the label may depend
               on the value of XXmmNNssttrriinnggDDiirreeccttiioonn.

     XXmmNNmmaarrggiinnTToopp
               Specifies the amount of spacing between the top of the label
               text and the bottom of the top margin specified by XXmmNNmmaarr--
               ggiinnHHeeiigghhtt.  This may be modified by LabelGadget's subclasses.
               For example, CascadeButtonGadget may increase this field to
               make room for the cascade pixmap.

     XXmmNNmmaarrggiinnWWiiddtthh
               Specifies an equal amount of spacing to the left of the margin
               defined by XXmmNNmmaarrggiinnLLeefftt and to the right of the margin


   1-433






   XmLabelGadget(3X)


               defined by XXmmNNmmaarrggiinnRRiigghhtt.  XXmmNNmmaarrggiinnWWiiddtthh specifies the
               amount of spacing between the left edge of the margin set by
               XXmmNNmmaarrggiinnLLeefftt and the right edge of the left shadow, and the
               amount of spacing between the right edge of the margin speci-
               fied by XXmmNNmmaarrggiinnRRiigghhtt and the left edge of the right shadow.

     XXmmNNmmnneemmoonniicc
               Provides the user with an alternate means of activating a but-
               ton.  A button 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
               XXmmNNmmnneemmoonniiccCChhaarrSSeett 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 visi-
               ble.  If the button is a CascadeButtonGadget in a MenuBar and
               the MenuBar does not have the focus, the user must use the
               MMAAlltt modifier while pressing the mnemonic.  The user can
               activate the button by pressing either the shifted or the
               unshifted mnemonic key.

     XXmmNNmmnneemmoonniiccCChhaarrSSeett
               Specifies the character set of the mnemonic for the label.
               The default is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

     XXmmNNrreeccoommppuutteeSSiizzee
               Specifies a Boolean value that indicates whether the gadget
               shrinks or expands to accommodate its contents (label string
               or pixmap) as a result of an XXttSSeettVVaalluueess resource value that
               would change the size of the gadget.  If True, the gadget
               shrinks or expands to exactly fit the label string or pixmap.
               If False, the gadget never attempts to change size on its own.

     XXmmNNssttrriinnggDDiirreeccttiioonn
               Specifies the direction in which the string is to be drawn.
               The following are the values:

                 ++oo  XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR - left to right

                 ++oo  XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__RR__TTOO__LL - right to left
               The default for this resource is determined at creation time.
               If no value is specified for this resource and the widget's
               parent is a manager, the value is inherited from the parent;
               otherwise, it defaults to XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR.

     Inherited Resources

     LabelGadget inherits behavior and resources from the following superc-
     lasses.  For a complete description of each resource, refer to the man
     page for that superclass.
                                  XXmmGGaaddggeett RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt   AAcccceessss
   ___________________________________________________________________________________


   1-434






                                                            XmLabelGadget(3X)


   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic   G
   XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
   XmNhighlightColor       XmCHighlightColor       Pixel              dynamic   G
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG
   XmNhighlightThickness   XmCHighlightThickness   Dimension          0         CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
   XmNshadowThickness      XmCShadowThickness      Dimension          0         CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic   G
   XmNtraversalOn          XmCTraversalOn          Boolean            False     CSG
   XmNunitType             XmCUnitType             unsigned char      dynamic   CSG
   XmNuserData             XmCUserData             XtPointer          NULL      CSG
                               RReeccttOObbjj RReessoouurrccee SSeett
       NNaammee                   CCllaassss            TTyyppee        DDeeffaauulltt   AAcccceessss
       ____________________________________________________________________
       XmNancestorSensitive   XmCSensitive     Boolean     dynamic   G
       XmNborderWidth         XmCBorderWidth   Dimension   0         CSG
       XmNheight              XmCHeight        Dimension   dynamic   CSG
       XmNsensitive           XmCSensitive     Boolean     True      CSG
       XmNwidth               XmCWidth         Dimension   dynamic   CSG
       XmNx                   XmCPosition      Position    0         CSG
       XmNy                   XmCPosition      Position    0         CSG
                               OObbjjeecctt RReessoouurrccee SSeett
       NNaammee                 CCllaassss         TTyyppee             DDeeffaauulltt   AAcccceessss
       ____________________________________________________________________
       XmNdestroyCallback   XmCCallback   XtCallbackList   NULL      C

     Behavior

     XmLabelGadget includes behavior from XmGadget.  Additional XmLabelGadget
     behavior is described below:

     BBDDrraagg PPrreessss:
               Drags the contents of a LabelGadget, identified by pressing
               BBDDrraagg.  This action creates a DragContext object whose XXmmNNeexx--
               ppoorrttTTaarrggeettss resource is set to "COMPOUND_TEXT" for a label
               type of XXmmSSTTRRIINNGG; otherwise, "PIXMAP" if the label type is
               XXmmPPIIXXMMAAPP.  This action is undefined for LabelGadgets used in a
               menu system.

     KKHHeellpp:    In a Popup or Pulldown MenuPane, unposts all menus in the menu
               hierarchy and, when the shell's keyboard focus policy is XXmmEEXX--
               PPLLIICCIITT, restores keyboard focus to the widget that had the
               focus before the menu system was entered.  Calls the callbacks
               for XXmmNNhheellppCCaallllbbaacckk if any exist.  If there are no help call-
               backs for this widget, this action calls the help callbacks
               for the nearest ancestor that has them.

     MMAAnnyy KKCCaanncceell:
               In a MenuBar, disarms the CascadeButton and the menu and, when
               the shell's keyboard focus policy is XXmmEEXXPPLLIICCIITT, restores key-
               board focus to the widget that had the focus before the menu
               was entered.  In a toplevel Pulldown MenuPane from a MenuBar,
               unposts the menu, disarms the MenuBar CascadeButton and the
               MenuBar, and, when the shell's keyboard focus policy is


   1-435






   XmLabelGadget(3X)


               XXmmEEXXPPLLIICCIITT, restores keyboard focus to the widget that had the
               focus before the MenuBar was entered.  In other Pulldown Menu-
               Panes, unposts the menu.  In a Popup MenuPane, unposts the
               menu and, when the shell's keyboard focus policy is XXmmEEXXPPLLII--
               CCIITT, restores keyboard focus to the widget from which the menu
               was posted.

     KKDDoowwnn:    If the current menu item has a submenu and is in a MenuBar,
               then this action posts the submenu, disarms the current menu
               item, and arms the submenu's first traversable menu item.  If
               the current menu item is in a MenuPane, then this action
               disarms the current menu item and arms the item below it.
               This action wraps within the MenuPane.  When the current menu
               item is at the MenuPane's bottom edge, then this action wraps
               to the topmost menu item in the column to the right, if one
               exists.  When the current menu item is at the bottom, right-
               most corner of the MenuPane, then this action wraps to the
               tear-off control, if present, or to the top, leftmost menu
               item.

     KKLLeefftt:    When the current menu item is in a MenuBar, then this action
               disarms the current item and arms the MenuBar item to the
               left.  This action wraps within the MenuBar.  In MenuPanes, if
               the current menu item is not at the left edge of a MenuPane,
               this action disarms the current item and arms the item to its
               left.  If the current menu item is at the left edge of a sub-
               menu attached to a MenuBar item, then this action unposts the
               submenu and traverses to the MenuBar item to the left, wrap-
               ping if necessary.  If that MenuBar item has a submenu, it
               posts the submenu and arms the first traversable item in the
               submenu.  If the current menu item is at the left edge of a
               submenu not directly attached to a MenuBar item, then this
               action unposts the current submenu only.  In Popup or Torn-off
               MenuPanes, when the current menu item is at the left edge,
               this  action wraps within the MenuPane.  If the current menu
               item is at the left edge of the MenuPane and not in the top
               row, this action wraps to the rightmost menu item in the row
               above.  If the current menu item is in the upper, leftmost
               corner, this action wraps to the tear-off control, if present,
               or else it wraps to the bottom, rightmost menu item in the
               MenuPane.

     KKRRiigghhtt:   If the current menu item is in a MenuBar, then this action
               disarms the current item and arms the MenuBar item to the
               right.  This action wraps within the MenuBar.  In MenuPanes,
               if the current menu item is a CascadeButton, then this action
               posts its associated submenu.  If the current menu item is not
               a CascadeButton and is not at the right edge of a MenuPane,
               this action disarms the current item and arms the item to its
               right, wrapping if necessary.  If the current menu item is not
               a CascadeButton and is at the right edge of a submenu that is
               a descendent of a MenuBar, then this action unposts all sub-
               menus and traverses to the MenuBar item to the right.  If that
               MenuBar item has a submenu, it posts the submenu and arms the


   1-436






                                                            XmLabelGadget(3X)


               submenu's first traversable item.  In Popup or Torn-off menus,
               if the current menu item is not a CascadeButton and is at the
               right edge of a row (except the bottom row), this action wraps
               to the leftmost menu item in the row below.  If the current
               menu item is not a CascadeButton and is in the bottom, right-
               most corner of a Popup or Pulldown MenuPane, this action wraps
               to the tear-off control, if present, or else it wraps to the
               top, leftmost menu item of the MenuPane.

     KKUUpp:      When the current menu item is in a MenuPane, then this action
               disarms the current menu item and arms the item above it.
               This action wraps within the MenuPane.  When the current menu
               item is at the MenuPane's top edge, then this action wraps to
               the bottommost menu item in the column to the left, if one
               exists.  When the current menu item is at the top, leftmost
               corner of the MenuPane, then this action wraps to the tear-off
               control, if present, or to the bottom, rightmost menu item.

     Virtual Bindings

     The bindings for virtual keys are vendor specific.  For information
     about bindings for virtual buttons and keys, see VViirrttuuaallBBiinnddiinnggss((33XX)).

   RELATED INFORMATION
     OObbjjeecctt((33XX)), RReeccttOObbjj((33XX)), XXmmCCrreeaatteeLLaabbeellGGaaddggeett((33XX)), XXmmFFoonnttLLiissttCCrreeaattee((33XX)),
     XXmmSSttrriinnggCCrreeaattee((33XX)), XXmmSSttrriinnggCCrreeaatteeLLttooRR((33XX)), and XXmmGGaaddggeett((33XX)).






























   1-437






   XmList(3X)



   NAME
     XXmmLLiisstt-The List widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLiisstt..hh>>

   DESCRIPTION
     List allows a user to select one or more items from a group of choices.
     Items are selected from the list in a variety of ways, using both the
     pointer and the keyboard.  List operates on an array of compound strings
     that are defined by the application.  Each compound string becomes an
     item in the List, with the first compound string becoming the item in
     position 1, the second becoming the item in position 2, and so on.

     The size of the List is set by specifying the number of items that are
     visible.  If the number of visible items is not specified, the height of
     the list controls the number of visible items.  Each item assumes the
     height of the tallest element in the list.  To create a list that allows
     the user to scroll easily through a large number of items, use the
     XXmmCCrreeaatteeSSccrroolllleeddLLiisstt convenience function.

     To select items, move the pointer or cursor to the desired item and
     press the BBSSeelleecctt mouse button or the key defined as KKSSeelleecctt.  There are
     several styles of selection behavior, and they all highlight the
     selected item or items by displaying them in inverse colors.  An
     appropriate callback is invoked to notify the application of the user's
     choice.  The application then takes whatever action is required for the
     specified selection.  When a List is insensitive, all of the list items
     are displayed in a stippled fill pattern.

     Selection

     Each list has one of four selection models:

       ++oo  Single Select

       ++oo  Browse Select

       ++oo  Multiple Select

       ++oo  Extended Select

     In Single Select and Browse Select, at most one item is selected at a
     time.  In Single Select, pressing BBSSeelleecctt on an item toggles its selec-
     tion state and deselects any other selected item.  In Browse Select,
     pressing BBSSeelleecctt on an item selects it and deselects any other selected
     item; dragging BBSSeelleecctt moves the selection as the pointer is moved.
     Releasing BBSSeelleecctt on an item moves the location cursor to that item.

     In Multiple Select, any number of items can be selected at a time.
     Pressing BBSSeelleecctt on an item toggles its selection state but does not
     deselect any other selected items.



   1-438






                                                                   XmList(3X)


     In Extended Select, any number of items can be selected at a time, and
     the user can easily select ranges of items.  Pressing BBSSeelleecctt on an item
     selects it and deselects any other selected item.  Dragging BBSSeelleecctt or
     pressing or dragging BBEExxtteenndd following a BBSSeelleecctt action selects all
     items between the item under the pointer and the item on which BBSSeelleecctt
     was pressed.  This action also deselects any other selected items out-
     side that range.

     Extended Select also allows the user to select and deselect discontigu-
     ous ranges of items.  Pressing BBTTooggggllee on an item toggles its selection
     state but does not deselect any other selected items.  Dragging BBTTooggggllee
     or pressing or dragging BBEExxtteenndd following a BBTTooggggllee action sets the
     selection state of all items between the item under the pointer and the
     item on which BBTTooggggllee was pressed to the state of the item on which
     BBTTooggggllee was pressed.  This action does not deselect any other selected
     items outside that range.

     All selection operations available from the mouse are also available
     from the keyboard.  List has two keyboard selection modes, Normal Mode
     and Add Mode.  In Normal Mode, navigation operations and KKSSeelleecctt select
     the item at the location cursor and deselect any other selected items.
     In Add Mode, navigation operations have no effect on selection, and
     KKSSeelleecctt toggles the selection state of the item at the location cursor
     without deselecting any other selected items, except in Single Select.

     Single and Multiple Select use Add Mode, and Browse Select uses Normal
     Mode.

     Extended Select can use either mode; the user changes modes by pressing
     KKAAddddMMooddee.  In Extended Select Normal Mode, pressing KKSSeelleecctt has the same
     effect as pressing BBSSeelleecctt; KKEExxtteenndd and shifted navigation have the same
     effect as pressing BBEExxtteenndd following a BBSSeelleecctt action.  In Extended
     Select Add Mode, pressing KKSSeelleecctt has the same effect as pressing BBTToogg--
     ggllee; KKEExxtteenndd and shifted navigation have the same effect as pressing
     BBEExxtteenndd following a BBTTooggggllee action.

     Normal Mode is indicated by a solid location cursor, and Add Mode is
     indicated by a dashed location cursor.

     Classes

     List inherits behavior and resources from CCoorree and XXmmPPrriimmiittiivvee classes.

     The class pointer is xxmmLLiissttWWiiddggeettCCllaassss.

     The class name is XXmmLLiisstt.

     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
     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 XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of


   1-439






   XmList(3X)


     the defined values for a resource in a .Xdefaults file, remove the XXmm
     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 XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                                             XXmmLLiisstt RReessoouurrccee SSeett
   NNaammee                           CCllaassss                       TTyyppee                DDeeffaauulltt           AAcccceessss
   _______________________________________________________________________________________________________
   XmNautomaticSelection          XmCAutomaticSelection       Boolean             False             CSG
   XmNbrowseSelectionCallback     XmCCallback                 XtCallbackList      NULL              C
   XmNdefaultActionCallback       XmCCallback                 XtCallbackList      NULL              C
   XmNdoubleClickInterval         XmCDoubleClickInterval      int                 dynamic           CSG
   XmNextendedSelectionCallback   XmCCallback                 XtCallbackList      NULL              C
   XmNfontList                    XmCFontList                 XmFontList          dynamic           CSG
   XmNitemCount                   XmCItemCount                int                 0                 CSG
   XmNitems                       XmCItems                    XmStringTable       NULL              CSG
   XmNlistMarginHeight            XmCListMarginHeight         Dimension           0                 CSG
   XmNlistMarginWidth             XmCListMarginWidth          Dimension           0                 CSG
   XmNlistSizePolicy              XmCListSizePolicy           unsigned char       XmVARIABLE        CG
   XmNlistSpacing                 XmCListSpacing              Dimension           0                 CSG
   XmNmultipleSelectionCallback   XmCCallback                 XtCallbackList      NULL              C
   XmNscrollBarDisplayPolicy      XmCScrollBarDisplayPolicy   unsigned char       XmAS_NEEDED       CSG
   XmNselectedItemCount           XmCSelectedItemCount        int                 0                 CSG
   XmNselectedItems               XmCSelectedItems            XmStringTable       NULL              CSG
   XmNselectionPolicy             XmCSelectionPolicy          unsigned char       XmBROWSE_SELECT   CSG
   XmNsingleSelectionCallback     XmCCallback                 XtCallbackList      NULL              C
   XmNstringDirection             XmCStringDirection          XmStringDirection   dynamic           CSG
   XmNtopItemPosition             XmCTopItemPosition          int                 1                 CSG
   XmNvisibleItemCount            XmCVisibleItemCount         int                 dynamic           CSG

     XXmmNNaauuttoommaattiiccSSeelleeccttiioonn
               Invokes XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk or XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk when BSelect is pressed and the items that are shown
               as selected change if the value is True and the selection mode
               is either XXmmBBRROOWWSSEE__SSEELLEECCTT or XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT respectively.
               If False, no selection callbacks are invoked until the user
               releases the mouse button.  See the Behavior section for
               further details on the interaction of this resource with the
               selection modes.

     XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk
               Specifies a list of callbacks that is called when an item is
               selected in the browse selection mode.  The reason is
               XXmmCCRR__BBRROOWWSSEE__SSEELLEECCTT.

     XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk
               Specifies a list of callbacks that is called when an item is
               double clicked or KKAAccttiivvaattee is pressed.  The reason is
               XXmmCCRR__DDEEFFAAUULLTT__AACCTTIIOONN.






   1-440






                                                                   XmList(3X)



     XXmmNNddoouubblleeCClliicckkIInntteerrvvaall
               If a button click is followed by another button click within
               the time span specified by this resource (in milliseconds),
               the button clicks are considered a double-click action, rather
               than two single-click actions.  The value must not be nega-
               tive.  The default value is the display's multi-click time.

     XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk
               Specifies a list of callbacks that is called when items are
               selected using the extended selection mode.  The reason is
               XXmmCCRR__EEXXTTEENNDDEEDD__SSEELLEECCTT.

     XXmmNNffoonnttLLiisstt
               Specifies the font list associated with the list items.  This
               is used in conjunction with the XXmmNNvviissiibblleeIItteemmCCoouunntt resource
               to determine the height of the List widget.  If this value is
               NULL at initialization, the font list is initialized by look-
               ing up the parent hierarchy of the widget for an ancestor that
               is a subclass of the XmBulletinBoard or VendorShell widget
               class.  If such an ancestor is found, the font list is ini-
               tialized to the XXmmNNtteexxttFFoonnttLLiisstt of the ancestor widget.  If no
               such ancestor is found, the default is implementation depen-
               dent.  Refer to XXmmFFoonnttLLiisstt((33XX)) for more information on a font
               list structure.

     XXmmNNiitteemmCCoouunntt
               Specifies the total number of items.  The value must be the
               number of items in XXmmNNiitteemmss and must not be negative.  It is
               automatically updated by the list whenever an item is added to
               or deleted from the list.

     XXmmNNiitteemmss  Points to an array of compound strings that are to be
               displayed as the list items.  Refer to XXmmSSttrriinngg((33XX)) for more
               information on the creation and structure of compound strings.
               XXttGGeettVVaalluueess for this resource returns the list items them-
               selves, not a copy of the list items.  The application must
               not free the returned items.

     XXmmNNlliissttMMaarrggiinnHHeeiigghhtt
               Specifies the height of the margin between the list border and
               the items.

     XXmmNNlliissttMMaarrggiinnWWiiddtthh
               Specifies the width of the margin between the list border and
               the items.










   1-441






   XmList(3X)



     XXmmNNlliissttSSiizzeePPoolliiccyy
               Controls the reaction of the List when an item grows horizon-
               tally beyond the current size of the list work area.  If the
               value is XXmmCCOONNSSTTAANNTT, the list viewing area does not grow, and
               a horizontal ScrollBar is added for a ScrolledList.  If this
               resource is set to XXmmVVAARRIIAABBLLEE, the List grows to
               match the size of the longest item, and no horizontal
               ScrollBar appears.
               When the value of this resource is XXmmRREESSIIZZEE__IIFF__PPOOSSSSIIBBLLEE, the
               List attempts to grow or shrink to match the width of the wid-
               est item.  If it cannot grow to match the widest size, a hor-
               izontal ScrollBar is added for a ScrolledList if the longest
               item is wider than the list viewing area.
               The size policy must be set at the time the List widget is
               created.  It cannot be changed at a later time through XXttSSeett--
               VVaalluueess.

     XXmmNNlliissttSSppaacciinngg
               Specifies the spacing between list items.  This spacing
               increases by the value of the XXmmNNhhiigghhlliigghhttTThhiicckknneessss resource
               in Primitive.

     XXmmNNmmuullttiipplleeSSeelleeccttiioonnCCaallllbbaacckk
               Specifies a list of callbacks that is called when an item is
               selected in multiple selection mode. The reason is
               XXmmCCRR__MMUULLTTIIPPLLEE__SSEELLEECCTT.

     XXmmNNssccrroollllBBaarrDDiissppllaayyPPoolliiccyy
               Controls the display of vertical ScrollBars in a ScrolledList.
               When the value of this resource is XXmmAASS__NNEEEEDDEEDD, a vertical
               ScrollBar is displayed only when the number of items in the
               List exceeds the number of Visible items.  When the value is
               XXmmSSTTAATTIICC, a vertical ScrollBar is always displayed.

     XXmmNNsseelleecctteeddIItteemmCCoouunntt
               Specifies the number of strings in the selected items list.
               The value must be the number of items in XXmmNNsseelleecctteeddIItteemmss and
               must not be negative.

     XXmmNNsseelleecctteeddIItteemmss
               Points to an array of compound strings that represents the
               list items that are currently selected, either by the user or
               by the application.  XXttGGeettVVaalluueess for this resource returns the
               list items themselves, not a copy of the list items.  The
               application must not free the returned items.
               Setting XXmmNNsseelleecctteeddIItteemmss selects those list items that exactly
               match items in the given XXmmNNsseelleecctteeddIItteemmss list.  There may be
               additional items in XXmmNNsseelleecctteeddIItteemmss that do not match items
               in the list.  These items remain until XXmmNNsseelleecctteeddIItteemmss is
               updated.  If XXmmNNiitteemmss is changed such that the list now con-
               tains items matching previously unmatched items in XXmmNNsseelleecc--
               tteeddIItteemmss, those new items will also appear selected.
               Any user interaction with the list that causes at least one


   1-442






                                                                   XmList(3X)


               item to be selected or deselected and any call to XXmmLLiisstt--
               DDeesseelleeccttAAllllIItteemmss, XXmmLLiissttDDeesseelleeccttAAllllIItteemmss, XXmmLLiissttDDeesseelleeccttPPooss,
               XXmmLLiissttSSeelleeccttIItteemm, XXmmLLiissttSSeelleeccttPPooss, or XXmmLLiissttUUppddaatteeSSeelleecctteeddLLiisstt
               cause XXmmNNsseelleecctteeddIItteemmss to be updated immediately to exactly
               reflect the visual state of the list.  Calls to any other
               XXmmLLiisstt functions do not affect XXmmNNsseelleecctteeddIItteemmss.

     XXmmNNsseelleeccttiioonnPPoolliiccyy
               Defines the interpretation of the selection action.  This can
               be one of the following:

                 ++oo  XXmmSSIINNGGLLEE__SSEELLEECCTT-allows only single selections

                 ++oo  XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT-allows multiple selections

                 ++oo  XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT-allows extended selections

                 ++oo  XXmmBBRROOWWSSEE__SSEELLEECCTT"-allows "drag and browse" functionality

     XXmmNNssiinngglleeSSeelleeccttiioonnCCaallllbbaacckk
               Specifies a list of callbacks that is called when an item is
               selected in single selection mode. The reason is
               XXmmCCRR__SSIINNGGLLEE__SSEELLEECCTT.

     XXmmNNssttrriinnggDDiirreeccttiioonn
               Specifies the initial direction to draw the string.  The
               values are XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR and
               XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__RR__TTOO__LL.  The value of this resource is
               determined at creation time.  If the widget's parent is a
               manager, this value is inherited from the widget's parent,
               otherwise it is set to XXmmSSTTRRIINNGG__DDIIRREECCTTIIOONN__LL__TTOO__RR.

     XXmmNNttooppIItteemmPPoossiittiioonn
               Specifies the position of the item that is the first visible
               item in the list.  Setting this resource is equivalent to cal-
               ling the XXmmLLiissttSSeettPPooss function.  The position of the first
               item in the list is 1; the position of the second item is 2;
               and so on.  A position of 0 specifies the last item in the
               list.  The value must not be negative.

     XXmmNNvviissiibblleeIItteemmCCoouunntt
               Specifies the number of items that can fit in the visible
               space of the list work area.  The List uses this value to
               determine its height.  The value must be greater than 0.

     Inherited Resources

     List inherits behavior and resources from the following superclasses.
     For a complete description of each resource, refer to the man page for
     that superclass.
                                       XXmmPPrriimmiittiivvee RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt                AAcccceessss
   ________________________________________________________________________________________________
   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic                CSG


   1-443






   XmList(3X)


   XmNbottomShadowPixmap   XmCBottomShadowPixmap   Pixmap             XmUNSPECIFIED_PIXMAP   CSG
   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          2                      CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmTAB_GROUP            CSG
   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
                                                 CCoorree RReessoouurrccee SSeett
   NNaammee                            CCllaassss                           TTyyppee             DDeeffaauulltt                AAcccceessss
   ______________________________________________________________________________________________________________
   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

     List defines a new callback structure.  The application must first look
     at the reason field and use only the structure members that are valid
     for that particular reason, because not all fields are relevant for
     every possible reason.  The callback structure is defined as follows:
     ttyyppeeddeeff ssttrruucctt
     {{
       iinntt          _r_e_a_s_o_n;;
       XXEEvveenntt       **_e_v_e_n_t;;
       XXmmSSttrriinngg     _i_t_e_m;;
       iinntt          _i_t_e_m__l_e_n_g_t_h;;
       iinntt          _i_t_e_m__p_o_s_i_t_i_o_n;;
       XXmmSSttrriinngg     **_s_e_l_e_c_t_e_d__i_t_e_m_s;;
       iinntt          _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t;;
       iinntt          **_s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s;;
       cchhaarr         _s_e_l_e_c_t_i_o_n__t_y_p_e;;


   1-444






                                                                   XmList(3X)


     }} XXmmLLiissttCCaallllbbaacckkSSttrruucctt;;

     _r_e_a_s_o_n       Indicates why the callback was invoked.

     _e_v_e_n_t        Points to the XXEEvveenntt that triggered the callback.  It can
                  be NULL.

     _i_t_e_m         Is the last item selected at the time of the _e_v_e_n_t that
                  caused the callback.  _i_t_e_m points to a temporary storage
                  space that is reused after the callback is finished.
                  Therefore, if an application needs to save the item, it
                  should copy the item into its own data space.

     _i_t_e_m__l_e_n_g_t_h  Is the length in bytes of _i_t_e_m.

     _i_t_e_m__p_o_s_i_t_i_o_nIs the position of _i_t_e_m in the List's XXmmNNiitteemmss array.

     _s_e_l_e_c_t_e_d__i_t_e_m_s
                  Is a list of items selected at the time of the _e_v_e_n_t that
                  caused the callback.  _s_e_l_e_c_t_e_d__i_t_e_m_s points to a temporary
                  storage space that is reused after the callback is fin-
                  ished.  Therefore, if an application needs to save the
                  selected list, it should copy the list into its own data
                  space.

     _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t
                  Is the number of items in the _s_e_l_e_c_t_e_d__i_t_e_m_s list.  This
                  number must be non-negative.

     _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s
                  Is an array of integers, one for each selected item,
                  representing the position of each selected item in the
                  List's XXmmNNiitteemmss array.  _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s points to a
                  temporary storage space that is reused after the callback
                  is finished.  Therefore, if an application needs to save
                  this array, it should copy the array into its own data
                  space.

     _s_e_l_e_c_t_i_o_n__t_y_p_e
                  Indicates that the most recent extended selection was the
                  initial selection (XXmmIINNIITTIIAALL), a modification of an exist-
                  ing selection (XXmmMMOODDIIFFIICCAATTIIOONN), or an additional noncon-
                  tiguous selection (XXmmAADDDDIITTIIOONN).













   1-445






   XmList(3X)


     The following table describes the reasons for which the individual call-
     back structure fields are valid:
             RReeaassoonn                           VVaalliidd FFiieellddss
      ____________________________________________________________________________________________________________________________________________
      XXmmCCRR__SSIINNGGLLEE__SSEELLEECCTT     _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h, _i_t_e_m__p_o_s_i_t_i_o_n
      ______________________________________________________________________
            X X mm CC RR __ DD EE FF AA UU LL TT __ AA CC TT II OO NN    _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h,
                             _i_t_e_m__p_o_s_i_t_i_o_n, _s_e_l_e_c_t_e_d__i_t_e_m_s,
                             _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t, _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s
      ______________________________________________________________________
      ______________________________________________________________________
      XXmmCCRR__BBRROOWWSSEE__SSEELLEECCTT     _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h, _i_t_e_m__p_o_s_i_t_i_o_n
      ______________________________________________________________________
            X X mm CC RR __ MM UU LL TT II PP LL EE __ SS EE LL EE CC TT   _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h,
                             _i_t_e_m__p_o_s_i_t_i_o_n, _s_e_l_e_c_t_e_d__i_t_e_m_s,
                             _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t, _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s
      ______________________________________________________________________
            X X mm CC RR __ EE XX TT EE NN DD EE DD __ SS EE LL EE CC TT   _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h,
                             _i_t_e_m__p_o_s_i_t_i_o_n, _s_e_l_e_c_t_e_d__i_t_e_m_s,
                             _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t, _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s,
                             _s_e_l_e_c_t_i_o_n__t_y_p_e

     Translations

     XmList includes translations from Primitive.  The XmList translations
     are listed below.  These translations may not directly correspond to a
     translation table.
     BBSSeelleecctt PPrreessss:: LLiissttBBeeggiinnSSeelleecctt(())
     BBSSeelleecctt MMoottiioonn::LLiissttBBuuttttoonnMMoottiioonn(())
     BBSSeelleecctt RReelleeaassee::LLiissttEEnnddSSeelleecctt(())
     BBEExxtteenndd PPrreessss:: LLiissttBBeeggiinnEExxtteenndd(())
     BBEExxtteenndd MMoottiioonn::LLiissttBBuuttttoonnMMoottiioonn(())
     BBEExxtteenndd RReelleeaassee::LLiissttEEnnddEExxtteenndd(())
     BBTTooggggllee PPrreessss:: LLiissttBBeeggiinnTTooggggllee(())
     BBTTooggggllee MMoottiioonn::LLiissttBBuuttttoonnMMoottiioonn(())
     BBTTooggggllee RReelleeaassee::LLiissttEEnnddTTooggggllee(())
     BBDDrraagg PPrreessss::   LLiissttPPrroocceessssDDrraagg(())
     KKUUpp::           LLiissttPPrreevvIItteemm(())
     MMSShhiifftt KKUUpp::    LLiissttEExxtteennddPPrreevvIItteemm(())
     KKDDoowwnn::         LLiissttNNeexxttIItteemm(())
     MMSShhiifftt KKDDoowwnn::  LLiissttEExxtteennddNNeexxttIItteemm(())
     KKLLeefftt::         LLiissttLLeeffttCChhaarr(())
     MMCCttrrll KKLLeefftt::   LLiissttLLeeffttPPaaggee(())
     KKRRiigghhtt::        LLiissttRRiigghhttCChhaarr(())
     MMCCttrrll KKRRiigghhtt::  LLiissttRRiigghhttPPaaggee(())
     KKPPaaggeeUUpp::       LLiissttPPrreevvPPaaggee(())
     KKPPaaggeeDDoowwnn::     LLiissttNNeexxttPPaaggee(())
     KKPPaaggeeLLeefftt::     LLiissttLLeeffttPPaaggee(())
     KKPPaaggeeRRiigghhtt::    LLiissttRRiigghhttPPaaggee(())
     KKBBeeggiinnLLiinnee::    LLiissttBBeeggiinnLLiinnee(())
     KKEEnnddLLiinnee::      LLiissttEEnnddLLiinnee(())
     KKBBeeggiinnDDaattaa::    LLiissttBBeeggiinnDDaattaa(())
     MMSShhiifftt KKBBeeggiinnDDaattaa::LLiissttBBeeggiinnDDaattaaEExxtteenndd(())
     KKEEnnddDDaattaa::      LLiissttEEnnddDDaattaa(())


   1-446






                                                                   XmList(3X)


     MMSShhiifftt KKEEnnddDDaattaa::LLiissttEEnnddDDaattaaEExxtteenndd(())
     KKAAddddMMooddee::      LLiissttAAddddMMooddee(())
     KKAAccttiivvaattee::     LLiissttKKbbddAAccttiivvaattee(())
     KKCCooppyy PPrreessss::   LLiissttCCooppyyTTooCClliippbbooaarrdd(())
     KKSSeelleecctt PPrreessss:: LLiissttKKbbddBBeeggiinnSSeelleecctt(())
     KKSSeelleecctt RReelleeaassee::LLiissttKKbbddEEnnddSSeelleecctt(())
     KKEExxtteenndd PPrreessss:: LLiissttKKbbddBBeeggiinnEExxtteenndd(())
     KKEExxtteenndd RReelleeaassee::LLiissttKKbbddEEnnddEExxtteenndd(())
     MMAAnnyy KKCCaanncceell::  LLiissttKKbbddCCaanncceell(())
     KKSSeelleeccttAAllll::    LLiissttKKbbddSSeelleeccttAAllll(())
     KKDDeesseelleeccttAAllll::  LLiissttKKbbddDDeeSSeelleeccttAAllll(())
     KKHHeellpp::         PPrriimmiittiivveeHHeellpp(())
     KKNNeexxttFFiieelldd     PPrriimmiittiivveeNNeexxttTTaabbGGrroouupp(())
     KKPPrreevvFFiieelldd     PPrriimmiittiivveePPrreevvTTaabbGGrroouupp(())

     Action Routines

     The XmList action routines are described below.  The current selection
     is always shown with inverted colors.

     LLiissttAAddddMMooddee(()):
               Toggles the state of Add Mode for keyboard selection.

     LLiissttBBeeggiinnDDaattaa(()):
               Moves the location cursor to the first item in the list.  In
               Normal Mode, this also deselects any current selection,
               selects the first item in the list, and calls the appropriate
               selection callbacks (XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleecc--
               ttiioonnPPoolliiccyy is set to XXmmBBRROOWWSSEE__SSEELLEECCTT, XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT).

     LLiissttBBeeggiinnDDaattaaEExxtteenndd(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT or
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, moves the location cursor to the first item
               in the list.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does the following: If an extended selec-
               tion has been made from the current anchor point, restores the
               selection state of the items in that range to their state
               before the extended selection was done.  Changes the selection
               state of the first item and all items between it and the
               current anchor point to the state of the item at the current
               anchor point.  Calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk call-
               backs.

     LLiissttBBeeggiinnEExxtteenndd(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does
               the following: If an extended selection has been made from the
               current anchor point, restores the selection state of the
               items in that range to their state before the extended selec-
               tion was done.  Changes the selection state of the item under
               the pointer and all items between it and the current anchor





   1-447






   XmList(3X)


               point to the state of the item at the current anchor point.
               If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to True, calls the XXmmNNeexxtteenn--
               ddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttBBeeggiinnLLiinnee(()):
               Moves the horizontal scroll region to the beginning of the
               line.

     LLiissttBBeeggiinnSSeelleecctt(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT, deselects
               any current selection and toggles the selection state of the
               item under the pointer.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, deselects any current selection and selects
               the item under the pointer.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set
               to True, calls the XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk callbacks.  If
               the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, toggles
               the selection state of the item under the pointer.  Any previ-
               ous selections remain.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, deselects any current selection, selects
               the item under the pointer, and sets the current anchor at
               that item.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to True, calls the
               XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttBBeeggiinnTTooggggllee(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does
               the following: Moves the current anchor to the item under the
               pointer without changing the current selection.  If the item
               is unselected, it is selected; if the item is selected, it is
               unselected.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to True, calls
               the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttBBuuttttoonnMMoottiioonn(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmBBRROOWWSSEE__SSEELLEECCTT, deselects
               any current selection and selects the item under the
               pointer.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to True and the
               pointer has entered a new list item, calls the XXmmNNbbrroowwsseeSSeelleecc--
               ttiioonnCCaallllbbaacckk callbacks.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does the following: If an extended selec-
               tion is being made and an extended selection has previously
               been made from the current anchor point, restores the selec-
               tion state of the items in that range to their state before
               the previous extended selection was done.  Changes the selec-
               tion state of the item under the pointer and all items between
               it and the current anchor point to the state of the item at
               the current anchor point.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to
               True and the pointer has entered a new list item, calls the
               XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.  If the pointer leaves
               a scrolled list, this action scrolls the list in the direction
               of the pointer motion.

     LLiissttCCooppyyTTooCClliippbbooaarrdd(())
               Copies the content of the selected items to the clipboard as a
               single compound string with each item separated by a newline.



   1-448






                                                                   XmList(3X)


     LLiissttEEnnddDDaattaa(()):
               Moves the location cursor to the last item in the list.  In
               Normal Mode, this also deselects any current selection,
               selects the last item in the list, and calls the appropriate
               selection callbacks (XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleecc--
               ttiioonnPPoolliiccyy is set to XXmmBBRROOWWSSEE__SSEELLEECCTT, XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT).

     LLiissttEEnnddDDaattaaEExxtteenndd(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT or
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, moves the location cursor to the last item
               in the list.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does the following: If an extended selec-
               tion has been made from the current anchor point, restores the
               selection state of the items in that range to their state
               before the extended selection was done.  Changes the selection
               state of the last item and all items between it and the
               current anchor point to the state of the item at the current
               anchor point.  Calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk call-
               backs.

     LLiissttEEnnddEExxtteenndd(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, moves
               the location cursor to the last item selected or deselected
               and, if XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to False, calls the
               XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttEEnnddLLiinnee(()):
               Moves the horizontal scroll region to the end of the line.

     LLiissttEEnnddSSeelleecctt(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT or
               XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, moves the location cursor to the last item
               selected or deselected and calls the appropriate selection
               callbacks (XXmmNNssiinngglleeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy
               is set to XXmmSSIINNGGLLEE__SSEELLEECCTT, XXmmNNmmuullttiipplleeSSeelleeccttiioonnCCaallllbbaacckk when
               XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT).  If the
               XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmBBRROOWWSSEE__SSEELLEECCTT or
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, moves the location cursor to the last item
               selected or deselected and, if XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to
               False, calls the appropriate selection callbacks
               (XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleecc--
               ttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT).

     LLiissttEEnnddTTooggggllee(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, moves
               the location cursor to the last item selected or deselected
               and, if XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to False, calls the
               XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttEExxtteennddNNeexxttIItteemm(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does
               the following: If an extended selection has been made from the


   1-449






   XmList(3X)


               current anchor point, restores the selection state of the
               items in that range to their state before the extended selec-
               tion was done.  Moves the location cursor to the next item and
               changes the selection state of the item and all items between
               it and the current anchor point to the state of the item at
               the current anchor point.  Calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallll--
               bbaacckk callbacks.

     LLiissttEExxtteennddPPrreevvIItteemm(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does
               the following: If an extended selection has been made from the
               current anchor point, restores the selection state of the
               items in that range to their state before the extended selec-
               tion was done.  Moves the location cursor to the previous item
               and changes the selection state of the item and all items
               between it and the current anchor point to the state of the
               item at the current anchor point.  Calls the XXmmNNeexxtteennddeeddSSeelleecc--
               ttiioonnCCaallllbbaacckk callbacks.

     LLiissttSSccrroollllCCuurrssoorrVVeerrttiiccaallllyy((_p_e_r_c_e_n_t_a_g_e)):
               Scrolls the line containing the insertion cursor vertically to
               an intermediate position in the visible window based on an
               input percentage.  A value of 0 indicates the top of the win-
               dow; a value of 100, the bottom of the window.   If this
               action is called with no argument, the line containing the
               insertion cursor is scrolled vertically to a new position
               designated by the _y event passed to the routine.

     LLiissttKKbbddAAccttiivvaattee(()):
               Calls the callbacks for XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk.  If the
               List's parent is a manager, this action passes the event to
               the parent.

     LLiissttKKbbddBBeeggiinnEExxtteenndd(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does
               the following: If an extended selection has been made from the
               current anchor point, restores the selection state of the
               items in that range to their state before the extended selec-
               tion was done.  Changes the selection state of the item at the
               location cursor and all items between it and the current
               anchor point to the state of the item at the current anchor
               point.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to True, calls the
               XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttKKbbddBBeeggiinnSSeelleecctt(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT, deselects
               any current selection and toggles the state of the item at the
               location cursor.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, deselects any current selection and selects
               the item at the location cursor.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is
               set to True, calls the XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk callbacks.
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, toggles
               the selection state of the item at the location cursor.  Any



   1-450






                                                                   XmList(3X)


               previous selections remain.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set
               to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, moves the current anchor to the item at
               the location cursor.  In Normal Mode, deselects any current
               selection and selects the item at the location cursor.  In Add
               Mode, toggles the selection state of the item at the location
               cursor and leaves the current selection unchanged.  If XXmmNNaauu--
               ttoommaattiiccSSeelleeccttiioonn is set to True, calls the XXmmNNeexxtteennddeeddSSeelleecc--
               ttiioonnCCaallllbbaacckk callbacks.

     LLiissttKKbbddCCaanncceell(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT and an
               extended selection is being made from the current anchor
               point, cancels the new selection and restores the selection
               state of the items in that range to their state before the
               extended selection was done.  If XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set
               to True, calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks,
               otherwise, and if the parent is a manager, passes the event to
               the parent.

     LLiissttKKbbddDDeeSSeelleeccttAAllll(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT,
               XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, or XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT in Add Mode, deselects
               all items in the list.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT in Normal Mode, deselects all items in the
               list (except the item at the location cursor if the shell's
               XXmmNNkkeeyybbooaarrddFFooccuussPPoolliiccyy is XXmmEEXXPPLLIICCIITT).  Calls the appropriate
               selection callbacks (XXmmNNssiinngglleeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleecc--
               ttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT, XXmmNNmmuullttiipplleeSSeelleeccttiioonn--
               CCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT,
               XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT).

     LLiissttKKbbddEEnnddEExxtteenndd(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT and if
               XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to False, calls the XXmmNNeexxtteenn--
               ddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.

     LLiissttKKbbddEEnnddSSeelleecctt(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT or
               XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT or if XXmmNNaauuttoommaattiiccSSeelleeccttiioonn is set to False,
               calls the appropriate selection callbacks (XXmmNNssiinngglleeSSeelleeccttiioonn--
               CCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT,
               XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, XXmmNNmmuullttiipplleeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleecc--
               ttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT).

     LLiissttKKbbddSSeelleeccttAAllll(()):
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT or
               XXmmBBRROOWWSSEE__SSEELLEECCTT, selects the item at the location cursor.  If
               the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT or
               XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, selects all items in the list.  Calls the
               appropriate selection callbacks (XXmmNNssiinngglleeSSeelleeccttiioonnCCaallllbbaacckk
               when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmSSIINNGGLLEE__SSEELLEECCTT,


   1-451






   XmList(3X)


               XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, XXmmNNmmuullttiipplleeSSeelleeccttiioonnCCaallllbbaacckk when XXmmNNsseelleecc--
               ttiioonnPPoolliiccyy is set to XXmmMMUULLTTIIPPLLEE__SSEELLEECCTT, XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk when XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT).

     LLiissttLLeeffttCChhaarr(()):
               Scrolls the list one character to the left.

     LLiissttLLeeffttPPaaggee(()):
               Scrolls the list one page to the left.

     LLiissttNNeexxttIItteemm(()):
               Moves the location cursor to the next item in the list.  If
               the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmBBRROOWWSSEE__SSEELLEECCTT, this action
               also selects the next item, deselects any current selection,
               and calls the XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk callbacks.  If the
               XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, this action in
               Normal Mode also selects the next item, deselects any current
               selection, moves the current anchor to the next item, and
               calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk callbacks.  In Add Mode
               this action does not affect the selection or the anchor.

     LLiissttNNeexxttPPaaggee(()):
               Scrolls the list to the next page, moving the location cursor
               to a new item.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, this action also selects the new item,
               deselects any current selection, and calls the XXmmNNbbrroowwsseeSSeelleecc--
               ttiioonnCCaallllbbaacckk callbacks.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, this action in Normal Mode also selects the
               new item, deselects any current selection, moves the current
               anchor to the new item, and calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk callbacks.  In Add Mode this action does not affect
               the selection or the anchor.

     LLiissttPPrreevvIItteemm(()):
               Moves the location cursor to the previous item in the list.
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmBBRROOWWSSEE__SSEELLEECCTT, this
               action also selects the previous item, deselects any current
               selection, and calls the XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk callbacks.
               If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, this
               action in Normal Mode also selects the previous item,
               deselects any current selection, moves the current anchor to
               the previous item, and calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk
               callbacks.  In Add Mode this action does not affect the selec-
               tion or the anchor.

     LLiissttPPrreevvPPaaggee(()):
               Scrolls the list to the previous page, moving the location
               cursor to a new item.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmBBRROOWWSSEE__SSEELLEECCTT, this action also selects the new item,
               deselects any current selection, and calls the XXmmNNbbrroowwsseeSSeelleecc--
               ttiioonnCCaallllbbaacckk callbacks.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
               XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, this action in Normal Mode also selects the
               new item, deselects any current selection, moves the current


   1-452






                                                                   XmList(3X)


               anchor to the new item, and calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonn--
               CCaallllbbaacckk callbacks.  In Add Mode this action does not affect
               the selection or the anchor.

     LLiissttPPrroocceessssDDrraagg(()):
               Drags the content of a one or more selected list items.  Each
               item is separated by a newline.  This action creates a
               DragContext object whose XXmmNNeexxppoorrttTTaarrggeettss resource is set to
               "COMPOUND_TEXT" and the XXmmNNcclliieennttDDaattaa resource is set to the
               index of the item in the list.  If BBDDrraagg is pressed on an
               unselected item, drags only that item, excluding any other
               selected items.

     LLiissttRRiigghhttCChhaarr(()):
               Scrolls the list one character to the right.

     LLiissttRRiigghhttPPaaggee(()):
               Scrolls the list one page to the right.

     PPrriimmiittiivveeHHeellpp(()):
               Calls the callbacks for XXmmNNhheellppCCaallllbbaacckk 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.

     PPrriimmiittiivveeNNeexxttTTaabbGGrroouupp(()):
               Moves the focus to the first item contained within the next
               tab group.  If the current tab group is the last entry in the
               tab group list, it wraps to the beginning of the tab group
               list.

     PPrriimmiittiivveePPrreevvTTaabbGGrroouupp(()):
               Moves the focus to the first item contained within the previ-
               ous tab group.  If the beginning of the tab group list is
               reached, it wraps to the end of the tab group list.

     Additional Behavior

     The List widget has the additional behavior described below:

     <<DDoouubbllee CClliicckk>>
               If a button click is followed by another button click within
               the time span specified by the display's multi-click time, the
               List interprets that as a double click and calls the callbacks
               for XXmmNNddeeffaauullttAAccttiioonnCCaallllbbaacckk.  The item's colors invert to
               indicate that it is selected.  The XXmmNNddoouubblleeCClliicckkIInntteerrvvaall
               resource can be used to specify a time span that overrides the
               display's multi-click time.

     <<FFooccuussIInn>>:
               If the focus policy is Explicit, sets the focus and draw the
               location cursor.

     <<FFooccuussOOuutt>>:
               If the focus policy is Explicit, removes the focus and erase


   1-453






   XmList(3X)


               the location cursor.

     Virtual Bindings

     The bindings for virtual keys are vendor specific.  For information
     about bindings for virtual buttons and keys, see VViirrttuuaallBBiinnddiinnggss((33XX)).

   RELATED INFORMATION
     CCoorree((33XX)), XXmmCCrreeaatteeLLiisstt((33XX)), XXmmCCrreeaatteeSSccrroolllleeddLLiisstt((33XX)),
     XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy((33XX)), XXmmLLiissttAAddddIItteemm((33XX)), XXmmLLiissttAAddddIItteemmss((33XX)),
     XXmmLLiissttAAddddIItteemmUUnnsseelleecctteedd((33XX)), XXmmLLiissttAAddddIItteemmssUUnnsseelleecctteedd((33XX)),
     XXmmLLiissttDDeelleetteeAAllllIItteemmss((33XX)), XXmmLLiissttDDeelleetteeIItteemm((33XX)), XXmmLLiissttDDeelleetteeIItteemmss((33XX)),
     XXmmLLiissttDDeelleetteeIItteemmssPPooss((33XX)), XXmmLLiissttDDeelleetteePPooss((33XX)),
     XXmmLLiissttDDeelleetteePPoossiittiioonnss((33XX)), XXmmLLiissttDDeesseelleeccttAAllllIItteemmss((33XX)),
     XXmmLLiissttDDeesseelleeccttIItteemm((33XX)), XXmmLLiissttDDeesseelleeccttPPooss((33XX)), XXmmLLiissttGGeettKKbbddIItteemmPPooss
     XXmmLLiissttGGeettMMaattcchhPPooss((33XX)), XXmmLLiissttGGeettSSeelleecctteeddPPooss((33XX)), XXmmLLiissttIItteemmEExxiissttss((33XX)),
     XXmmLLiissttIItteemmPPooss((33XX)), XXmmLLiissttPPoossTTooBBoouunnddss((33XX)), XXmmLLiissttRReeppllaacceeIItteemmss((33XX)),
     XXmmLLiissttRReeppllaacceeIItteemmssPPooss((33XX)), XXmmLLiissttRReeppllaacceeIItteemmssPPoossiittiioonnss((33XX)),
     XXmmLLiissttRReeppllaacceeIItteemmssPPoossUUnnsseelleecctteedd((33XX)), XXmmLLiissttRReeppllaacceeIItteemmssUUnnsseelleecctteedd((33XX)),
     XXmmLLiissttSSeelleeccttIItteemm((33XX)), XXmmLLiissttSSeelleeccttPPooss((33XX)), XXmmLLiissttSSeettAAddddMMooddee((33XX)),
     XXmmLLiissttSSeettBBoottttoommIItteemm((33XX)), XXmmLLiissttSSeettBBoottttoommPPooss((33XX)), XXmmLLiissttSSeettHHoorriizzPPooss((33XX)),
     XXmmLLiissttSSeettIItteemm((33XX)), XXmmLLiissttSSeettKKbbddIItteemmPPooss((33XX)), XXmmLLiissttSSeettPPooss((33XX)),
     XXmmLLiissttUUppddaatteeSSeelleecctteeddLLiisstt((33XX)), XXmmLLiissttYYTTooPPooss((33XX)), XXmmPPrriimmiittiivvee((33XX)) and
     XXmmSSttrriinnggCCrreeaattee((33XX)).
































   1-454






                                                            XmListAddItem(3X)



   NAME
     XXmmLLiissttAAddddIItteemm-A List function that adds an item to the list

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLiisstt..hh>>
     vvooiidd XXmmLLiissttAAddddIItteemm ((_w_i_d_g_e_t, _i_t_e_m, _p_o_s_i_t_i_o_n))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  _i_t_e_m;;
          iinntt       _p_o_s_i_t_i_o_n;;

   DESCRIPTION
     XXmmLLiissttAAddddIItteemm adds an item to the list at the given position.  When the
     item is inserted into the list, it is compared with the current
     XXmmNNsseelleecctteeddIItteemmss list.  If the new item matches an item on the selected
     list, it appears selected.

     _w_i_d_g_e_t Specifies the ID of the List to which an item is added.

     _i_t_e_m   Specifies the item to be added to the list.

     _p_o_s_i_t_i_o_n
            Specifies the position of the new item in the list.  A value of 1
            makes the new item the first item in the list; a value of 2 makes
            it the second item; and so on.  A value of 0 makes the new item
            the last item in the list.

     For a complete definition of List and its associated resources, see
     XXmmLLiisstt((33XX)).

   RELATED INFORMATION
     XXmmLLiisstt((33XX)).
























   1-455






   XmListAddItemUnselected(3X)



   NAME
     XXmmLLiissttAAddddIItteemmUUnnsseelleecctteedd-A List function that adds an item to the list

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLiisstt..hh>>
     vvooiidd XXmmLLiissttAAddddIItteemmUUnnsseelleecctteedd ((_w_i_d_g_e_t, _i_t_e_m, _p_o_s_i_t_i_o_n))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  _i_t_e_m;;
          iinntt       _p_o_s_i_t_i_o_n;;

   DESCRIPTION
     XXmmLLiissttAAddddIItteemmUUnnsseelleecctteedd adds an item to the list at the given position.
     The item does not appear selected, even if it matches an item in the
     current XXmmNNsseelleecctteeddIItteemmss list.

     _w_i_d_g_e_t Specifies the ID of the List from whose list an item is added.

     _i_t_e_m   Specifies the item to be added to the list.

     _p_o_s_i_t_i_o_n
            Specifies the position of the new item in the list.  A value of 1
            makes the new item the first item in the list; a value of 2 makes
            it the second item; and so on.  A value of 0 makes the new item
            the last item in the list.

     For a complete definition of List and its associated resources, see
     XXmmLLiisstt((33XX)).

   RELATED INFORMATION
     XXmmLLiisstt((33XX)).

























   1-456






                                                           XmListAddItems(3X)



   NAME
     XXmmLLiissttAAddddIItteemmss-A List function that adds items to the list

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLiisstt..hh>>
     vvooiidd XXmmLLiissttAAddddIItteemmss ((_w_i_d_g_e_t, _i_t_e_m_s, _i_t_e_m__c_o_u_n_t, _p_o_s_i_t_i_o_n))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  **_i_t_e_m_s;;
          iinntt       _i_t_e_m__c_o_u_n_t;;
          iinntt       _p_o_s_i_t_i_o_n;;

   DESCRIPTION
     XXmmLLiissttAAddddIItteemmss adds the specified items to the list at the given posi-
     tion.  The first _i_t_e_m__c_o_u_n_t items of the _i_t_e_m_s array are added to the
     list.  When the items are inserted into the list, they are compared with
     the current XXmmNNsseelleecctteeddIItteemmss list.  If any of the new items matches an
     item on the selected list, it appears selected.

     _w_i_d_g_e_t Specifies the ID of the List to which an item is added.

     _i_t_e_m_s  Specifies a pointer to the items to be added to the list.

     _i_t_e_m__c_o_u_n_t
            Specifies the number of items in _i_t_e_m_s.  This number must be
            non-negative.

     _p_o_s_i_t_i_o_n
            Specifies the position of the first new item in the list.  A
            value of 1 makes the first new item the first item in the list; a
            value of 2 makes it the second item; and so on.  A value of 0
            makes the first new item follow the last item in the list.

     For a complete definition of List and its associated resources, see
     XXmmLLiisstt((33XX)).

   RELATED INFORMATION
     XXmmLLiisstt((33XX)).


















   1-457






   XmListAddItemsUnselected(3X)



   NAME
     XXmmLLiissttAAddddIItteemmssUUnnsseelleecctteedd-A List function that adds items to a list

   SYNOPSIS
     ##iinncclluuddee <<XXmm//LLiisstt..hh>>
     vvooiidd XXmmLLiissttAAddddIItteemmssUUnnsseelleecctteedd ((_w_i_d_g_e_t, _i_t_e_m_s, _i_t_e_m__c_o_u_n_t, _p_o_s_i_t_i_o_n))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  **_i_t_e_m_s;;
          iinntt       _i_t_e_m__c_o_u_n_t;;
          iinntt       _p_o_s_i_t_i_o_n;;

   DESCRIPTION
     XXmmLLiissttAAddddIItteemmssUUnnsseelleecctteedd adds the specified items to the list at the
     given position.  The inserted items remain unselected, even if they
     currently appear in the XXmmNNsseelleecctteeddIItteemmss list.

     _w_i_d_g_e_t    Specifies the ID of the List widget to add items to.

     _i_t_e_m_s     Specifies a pointer to the items to be added to the list.

     _i_t_e_m__c_o_u_n_t
               Specifies the number of elements in _i_t_e_m_s.  This number must
               be non-negative.

     _p_o_s_i_t_i_o_n  Specifies the position of the first new item in the list.  A
               value of 1 makes the first new item the first item in the
               list; a value of 2 makes it the second item; and so on.  A
               value of 0 makes the first new item follow the last item of
               the list.

     For a complete definition of List and its associated resources, see
     XXmmLLiisstt((33XX)).

   RELATED INFORMATION
     XXmmLLiisstt((33XX)).




















   1-458



 d
