


     XXmmGGaaddggeett((33XX))             RReeffeerreennccee PPaaggeess             XXmmGGaaddggeett((33XX))



     NNAAMMEE
          XXmmGGaaddggeett-The Gadget widget class

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>


     DDEESSCCRRIIPPTTIIOONN
          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.

        CCllaasssseess
          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.

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the 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
     ___________________________________________________________________________________
     XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C







     2-347                                            (printed 5/7/92)






     XXmmGGaaddggeett((33XX))             RReeffeerreennccee PPaaggeess             XXmmGGaaddggeett((33XX))



     XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG
     XmNhighlightThickness   XmCHighlightThickness   Dimension          2         CSG
     XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
     XmNshadowThickness      XmCShadowThickness      Dimension          2         CSG
     XmNtraversalOn          XmCTraversalOn          Boolean            True      CSG
     XmNuserData             XmCUserData             XtPointer          NULL      CSG


          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tOOnnEEnntteerr
                    Specifies if the highlighting rectangle is drawn
                    when the cursor 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 policy is
                    XXmmPPOOIINNTTEERR and if this resource is True, the
                    highlighting 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  XXmmNNOONNEE indicates that the widget is not a tab
                         group.

                      +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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  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  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at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.



     2-348                                            (printed 5/7/92)






     XXmmGGaaddggeett((33XX))             RReeffeerreennccee PPaaggeess             XXmmGGaaddggeett((33XX))



                         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.


          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trraavveerrssaallOOnn
                    Specifies traversal activation for this gadget.

          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.


        IInnhheerriitteedd RReessoouurrcceess
          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
      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

        CCaallllbbaacckk IInnffoorrmmaattiioonn
          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



     2-349                                            (printed 5/7/92)






     XXmmGGaaddggeett((33XX))             RReeffeerreennccee PPaaggeess             XXmmGGaaddggeett((33XX))



                 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.


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          OObbjjeecctt((33XX)), RReeccttOObbjj((33XX)), and XXmmMMaannaaggeerr((33XX)).
















































     2-350                                            (printed 5/7/92)






     XXmmGGeettAAttoommNNaammee((33XX))        RReeffeerreennccee PPaaggeess        XXmmGGeettAAttoommNNaammee((33XX))



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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          The include file AAttoommMMggrr..hh moved from the XX1111 directory to
          the XXmm directory.  In revision B this include file will be
          accessible from either directory.  In future revisions it
          will only be accessible from the XXmm directory.

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 caching.  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


     RREETTUURRNN VVAALLUUEE
          Returns a string.

















     2-351                                            (printed 5/7/92)






     XXmmGGeettCCoolloorrss((33XX))          RReeffeerreennccee PPaaggeess          XXmmGGeettCCoolloorrss((33XX))



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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Trial-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 allocated

          _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 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 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
                 returned for this color.




     2-352                                            (printed 5/7/92)






     XXmmGGeettCCoolloorrss((33XX))          RReeffeerreennccee PPaaggeess          XXmmGGeettCCoolloorrss((33XX))



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




















































     2-353                                            (printed 5/7/92)






     XXmmGGeettDDrraaggCCoonntteexxtt((33XX))     RReeffeerreennccee PPaaggeess     XXmmGGeettDDrraaggCCoonntteexxtt((33XX))



     NNAAMMEE
          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

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 associated with a given display and timestamp.
          A timestamp uniquely identifies which DragContext is active
          when more than one drag and drop transaction 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)).

     RREETTUURRNN VVAALLUUEE
          Returns the ID of the DragContext widget that is active for
          the specified timestamp.  Otherwise, returns NULL if no
          active DragContext is found.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmDDrraaggCCoonntteexxtt((33XX)).












     2-354                                            (printed 5/7/92)






     XXmmGGeettMMeennuuCCuurrssoorr((33XX))      RReeffeerreennccee PPaaggeess      XXmmGGeettMMeennuuCCuurrssoorr((33XX))



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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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.


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


          For a complete definition of the menu cursor resource, see
          XXmmRRoowwCCoolluummnn((33XX)).

     RREETTUURRNN VVAALLUUEE
          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 application makes this call before the
          client has created any menus on the specified display.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmRRoowwCCoolluummnn((33XX)).




















     2-355                                            (printed 5/7/92)






     XXmmGGeettPPiixxmmaapp((33XX))          RReeffeerreennccee PPaaggeess          XXmmGGeettPPiixxmmaapp((33XX))



     NNAAMMEE
          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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 specifies 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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 bitmap 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 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



     2-356                                            (printed 5/7/92)






     XXmmGGeettPPiixxmmaapp((33XX))          RReeffeerreennccee PPaaggeess          XXmmGGeettPPiixxmmaapp((33XX))



          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
                    //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.



     2-357                                            (printed 5/7/92)






     XXmmGGeettPPiixxmmaapp((33XX))          RReeffeerreennccee PPaaggeess          XXmmGGeettPPiixxmmaapp((33XX))



          %%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
                    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


     RREETTUURRNN VVAALLUUEE
          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.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          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)).





















     2-358                                            (printed 5/7/92)






     XXmmGGeettPPoosstteeddFFrroommWWiiddggeett((33XX))RReeffeerreennccee PPaaggeessXXmmGGeettPPoosstteeddFFrroommWWiiddggeett((33XX))



     NNAAMMEE
          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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Trial-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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.  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)).

     RREETTUURRNN VVAALLUUEE
          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.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmRRoowwCCoolluummnn((33XX)).



















     2-359                                            (printed 5/7/92)






     XXmmIInnssttaallllIImmaaggee((33XX))       RReeffeerreennccee PPaaggeess       XXmmIInnssttaallllIImmaaggee((33XX))



     NNAAMMEE
          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 pixmap cache

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 converter 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 installation process does not make a local
                    copy of the image.  Therefore, 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 .Xdefaults 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
          ____________________________________________________________







     2-360                                            (printed 5/7/92)






     XXmmIInnssttaallllIImmaaggee((33XX))       RReeffeerreennccee PPaaggeess       XXmmIInnssttaallllIImmaaggee((33XX))



          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

     RREETTUURRNN VVAALLUUEE
          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.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          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)).






































     2-361                                            (printed 5/7/92)






     XXmmIInntteerrnnAAttoomm((33XX))         RReeffeerreennccee PPaaggeess         XXmmIInntteerrnnAAttoomm((33XX))



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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          The include file AAttoommMMggrr..hh moved from the XX1111 directory to
          the XXmm directory.  In revision B this include file will be
          accessible from either directory.  In future revisions it
          will only be accessible from the XXmm directory.

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 pseudonyms 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


     RREETTUURRNN VVAALLUUEE
          Returns an atom.












     2-362                                            (printed 5/7/92)






     XXmmIIssMMoottiiffWWMMRRuunnnniinngg((33XX))   RReeffeerreennccee PPaaggeess   XXmmIIssMMoottiiffWWMMRRuunnnniinngg((33XX))



     NNAAMMEE
          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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          This include file for this function has changed from
          XX1111//SShheellll..hh to XXmm//XXmm..hh.

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 presence.


     RREETTUURRNN VVAALLUUEE
          Returns True if MWM is running.






















     2-363                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



     NNAAMMEE
          XXmmLLaabbeell-The Label widget class

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          Changes have been made in the determination of default label
          strings (for Trial-use).

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLaabbeell..hh>>


     DDEESSCCRRIIPPTTIIOONN
          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rggiinnHHeeiigghhtt resources as set by the application.

          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.

        CCllaasssseess
          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.



     2-364                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



          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.

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the 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.



     2-365                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



                    Accelerators for buttons are supported only for
                    PushButton and ToggleButton 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 ToggleButtons
                    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.


                      +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  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  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gD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.



     2-366                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



                    If this value is NULL at initialization, the font
                    list is initialized by looking up the parent
                    hierarchy of the widget for an ancestor 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 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.

          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.

          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 converting 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 structure of compound strings.

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


                      +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  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 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 the amount of spacing between the top of
                    the label (specified 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



     2-367                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



                    spacing between the bottom of the label (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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 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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nWWiiddtthh
                    Specifies the amount of spacing between the left
                    side of the label (specified 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 side of the label
                    (specified 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
                    selecting a button.  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



     2-368                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



                    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 visible.  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 attempts to be big enough to contain
                    the label.  If True, an XXttSSeettVVaalluueess with a
                    resource value that would change the size of the
                    widget causes the widget to shrink or expand 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  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  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.


        IInnhheerriitteedd RReessoouurrcceess
          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






     2-369                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



     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
     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
     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

        AAccttiioonn RRoouuttiinneess
          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XP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 callbacks for this widget, this
                    action calls the help callbacks for the nearest
                    ancestor that has them.



     2-370                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



          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 keyboard 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, rightmost corner of the MenuPane, then
                    this action wraps to the tear-off control, if
                    present, or to the top, leftmost menu item.

          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
                    submenu attached to a MenuBar item, then this
                    action unposts the submenu and traverses to the
                    MenuBar item to the left, wrapping if necessary.
                    If that MenuBar item has a submenu, it posts the



     2-371                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



                    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 submenus 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, rightmost 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



     2-372                                            (printed 5/7/92)






     XXmmLLaabbeell((33XX))              RReeffeerreennccee PPaaggeess              XXmmLLaabbeell((33XX))



                    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.


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          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)).











































     2-373                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



     NNAAMMEE
          XXmmLLaabbeellGGaaddggeett-The LabelGadget widget class

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          Changes have been made in the determination of default label
          strings (for Trial-use).

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLaabbeellGG..hh>>


     DDEESSCCRRIIPPTTIIOONN
          LabelGadget is an instantiable widget and is also used as a
          superclass for other button gadgets, such as
          PushButtonGadget and ToggleButtonGadget.

          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, multiline,
          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.  Accelerators in a menu
          system are accessible even when the button is not visible.
          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 pixmap.  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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rggiinnHHeeiigghhtt resources as set by the application.

          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.  Otherwise these resources default to
          False.

        CCllaasssseess
          LabelGadget inherits behavior and resources from OObbjjeecctt,



     2-374                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



          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.

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the 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



     2-375                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



                    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
                    PushButtonGadget and ToggleButtonGadget 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
                    Specifies the label alignment for text or pixmap.


                      +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  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
                         vertically aligned with the center of the
                         gadget.

                      +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gD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.



     2-376                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



          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 ancestor 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.

          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.

          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.

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


                      +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  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 subclasses.  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 the amount of spacing between the top of



     2-377                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



                    the label (specified 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 of the label (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 subclasses.  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 subclasses.  For
                    example, CascadeButtonGadget 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rg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 the amount of spacing between the left
                    side of the label (specified 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 side of the label
                    (specified 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
                    selecting a button.  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



     2-378                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



                    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 visible.  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 attempts to be big enough to contain
                    the label.  If True, an XXttSSeettVVaalluueess with a
                    resource value that would change the size of the
                    gadget causes the gadget to shrink or expand 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  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  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.


        IInnhheerriitteedd RReessoouurrcceess
          LabelGadget 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mGGaaddggeett RReessoouurrccee SSeett




     2-379                                            (printed 5/7/92)






     XXmmLLaabbeellGGaaddggeett((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLaabbeellGGaaddggeett((33XX))



     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
     ___________________________________________________________________________________
     XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
     XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG
     XmNhighlightThickness   XmCHighlightThickness   Dimension          0         CSG
     XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
     XmNshadowThickness      XmCShadowThickness      Dimension          0         CSG
     XmNtraversalOn          XmCTraversalOn          Boolean            False     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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          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)).

























     2-380                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



     NNAAMMEE
          XXmmLLiisstt-The List widget class

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          The visible item count default value is now dynamic (for
          Trial-use).  The valid return fields in the
          XXmmLLiissttCCaallllbbaacckkSSttrruucctt for the reason XXmmCCRR__DDEEFFAAUULLTT__AACCTTIIOONN are
          being extended in revision D to include _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, and _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s.

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLiisstt..hh>>


     DDEESSCCRRIIPPTTIIOONN
          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.

        SSeelleeccttiioonn
          Each list has one of four selection models:


            +o  Single Select

            +o  Browse Select




     2-381                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



            +o  Multiple Select

            +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 selection 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 along with the cursor.

          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.

          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 outside that range.

          Extended Select also allows the user to select and deselect
          discontiguous 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



     2-382                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



          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gg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.

        CCllaasssseess
          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.

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the 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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
     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







     2-383                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



     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nC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.  The reason is
                    XXmmCCRR__DDEEFFAAUULLTT__AACCTTIIOONN.

          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
                    looking 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
                    initialized 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 dependent.  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



     2-384                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    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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.

          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 horizontally 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 widest item.  If
                    it cannot grow to match the widest size, a
                    horizontal 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tV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.





     2-385                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



          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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  XXmmSSIINNGGLLEE__SSEELLEECCTT-allows only single selections

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

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

                      +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



     2-386                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    resource is equivalent to calling 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.


        IInnhheerriitteedd RReessoouurrcceess
          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
     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
     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







     2-387                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



     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

        CCaallllbbaacckk IInnffoorrmmaattiioonn
          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;;
          }} 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



     2-388                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                       points to a temporary storage space that is
                       reused after the callback is finished.
                       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 existing
                       selection (XXmmMMOODDIIFFIICCAATTIIOONN), or an additional
                       noncontiguous selection (XXmmAADDDDIITTIIOONN).


          The following table describes the reasons for which the
          individual callback 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XmmCCRR__DDEEFFAAUULLTT__AACCTTIIOON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
     ______________________________________________________________________
     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

        AAccttiioonn RRoouuttiinneess
          The XmList action routines are described below.  The current
          selection is always shown with inverted colors.




     2-389                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



          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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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 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 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 callbacks.

          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 selection was done.  Changes the
                    selection 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,
                    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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.



     2-390                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    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 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, 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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, does the following:  If an
                    extended selection is being made and an extended
                    selection has previously been made from the
                    current anchor point, restores the selection state
                    of the items in that range to their state before
                    the previous extended selection was done.  Changes
                    the selection 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



     2-391                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    motion.

          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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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 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 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 callbacks.

          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



     2-392                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    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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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 current
                    anchor point, restores the selection state of the
                    items in that range to their state before the
                    extended selection 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lb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 selection 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cttiioonnCCaallllbbaacckk callbacks.

          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 selection was done.  Changes the



     2-393                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    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 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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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



     2-394                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



                    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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,
                    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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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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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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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,
                    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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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.




     2-395                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



          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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 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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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 selection or
                    the anchor.



     2-396                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((33XX))



          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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 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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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 previous tab group.  If the beginning of the
                    tab group list is reached, it wraps to the end of
                    the tab group list.


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          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tCCrreeaattee((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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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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)),



     2-397                                            (printed 5/7/92)






     XXmmLLiisstt((33XX))               RReeffeerreennccee PPaaggeess               XXmmLLiisstt((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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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tP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)).

















































     2-398                                            (printed 5/7/92)






     XXmmLLiissttAAddddIItteemm((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLiissttAAddddIItteemm((33XX))



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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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)).

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).














     2-399                                            (printed 5/7/92)






     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RR)e)effeerreennccee PPaaggeeXXsms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))



     NNAAMMEE
          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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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)).

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).















     2-400                                            (printed 5/7/92)






     XXmmLLiissttAAddddIItteemmss((33XX))       RReeffeerreennccee PPaaggeess       XXmmLLiissttAAddddIItteemmss((33XX))



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

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 position.  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)).

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).







     2-401                                            (printed 5/7/92)






     XXmmLLiissttDDeelleetteeAAllllIItteemmss((33XX)) RReeffeerreennccee PPaaggeess XXmmLLiissttDDeelleetteeAAllllIItteemmss((33XX))



     NNAAMMEE
          XXmmLLiissttDDeelleetteeAAllllIItteemmss-A List function that deletes all items
          from the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeelleetteeAAllllIItteemmss ((_w_i_d_g_e_t))
               WWiiddggeett    _w_i_d_g_e_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeelleetteeAAllllIItteemmss deletes all items from the list.


          _w_i_d_g_e_t Specifies the ID of the List from whose list the
                 items are deleted


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).




























     2-402                                            (printed 5/7/92)






     XXmmLLiissttDDeelleetteeIItteemm((33XX))     RReeffeerreennccee PPaaggeess     XXmmLLiissttDDeelleetteeIItteemm((33XX))



     NNAAMMEE
          XXmmLLiissttDDeelleetteeIItteemm-A List function that deletes an item from
          the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeelleetteeIItteemm ((_w_i_d_g_e_t, _i_t_e_m))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeelleetteeIItteemm deletes the first item in the list that
          matches _i_t_e_m.  A warning message appears if the item does
          not exist.


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

          _i_t_e_m   Specifies the text of the item to be deleted from the
                 list


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).






















     2-403                                            (printed 5/7/92)






     XXmmLLiissttDDeelleetteeIItteemmss((33XX))    RReeffeerreennccee PPaaggeess    XXmmLLiissttDDeelleetteeIItteemmss((33XX))



     NNAAMMEE
          XXmmLLiissttDDeelleetteeIItteemmss-A List function that deletes items from
          the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeelleetteeI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))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeelleetteeIItteemmss deletes the specified items from the list.
          For each element of _i_t_e_m_s, the first item in the list that
          matches that element is deleted.  A warning message appears
          if any of the items do not exist.


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

          _i_t_e_m_s  Specifies a pointer to items to be deleted from 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.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).
















     2-404                                            (printed 5/7/92)






     XXmmLLiissttDDeelleetteeIItteemmssPPooss((33XX)) RReeffeerreennccee PPaaggeess XXmmLLiissttDDeelleetteeIItteemmssPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttDDeelleetteeIItteemmssPPooss-A List function that deletes items from
          the list starting at the given position

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeelleetteeIItteemmssPPooss ((_w_i_d_g_e_t, _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;;
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeelleetteeIItteemmssPPooss deletes the specified number of items
          from the list starting at the specified position.


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

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

          _p_o_s_i_t_i_o_n
                 Specifies the position in the list of the first item
                 to be deleted.  A value of 1 indicates that the first
                 deleted item is the first item in the list; a value
                 of 2 indicates that it is the second item; and so on.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).















     2-405                                            (printed 5/7/92)






     XXmmLLiissttDDeelleetteePPooss((33XX))      RReeffeerreennccee PPaaggeess      XXmmLLiissttDDeelleetteePPooss((33XX))



     NNAAMMEE
          XXmmLLiissttDDeelleetteePPooss-A List function that deletes an item from a
          list at a specified position

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeelleetteePPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       _p_o_s_i_t_i_o_n;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeelleetteePPooss deletes an item at a specified position.  A
          warning message appears if the position does not exist.


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

          _p_o_s_i_t_i_o_n
                 Specifies the position of the item to be deleted.  A
                 value of 1 indicates that the first item in the list
                 is deleted; a value of 2 indicates that the second
                 item is deleted; and so on.  A value of 0 indicates
                 that the last item in the list is deleted.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).



















     2-406                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeess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))



     NNAAMMEE
          XXmmLLiissttDDeesseelleeccttAAllllIItteemmss-A List function that unhighlights and
          removes all items from the selected list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeesseelleeccttAAllllIItteemmss ((_w_i_d_g_e_t))
               WWiiddggeett    _w_i_d_g_e_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeesseelleeccttAAllllIItteemmss unhighlights and removes all items
          from the selected list.


          _w_i_d_g_e_t Specifies the ID of the List widget from whose list
                 all selected items are deselected


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).



























     2-407                                            (printed 5/7/92)






     XXmmLLiissttDDeesseelleeccttIItteemm((33XX))   RReeffeerreennccee PPaaggeess   XXmmLLiissttDDeesseelleeccttIItteemm((33XX))



     NNAAMMEE
          XXmmLLiissttDDeesseelleeccttIItteemm-A List function that deselects the
          specified item from the selected list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeesseelleeccttIItteemm ((_w_i_d_g_e_t, _i_t_e_m))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeesseelleeccttIItteemm unhighlights and removes from the
          selected list the first item in the list that matches _i_t_e_m.


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

          _i_t_e_m   Specifies the item to be deselected from the list


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).
























     2-408                                            (printed 5/7/92)






     XXmmLLiissttDDeesseelleeccttPPooss((33XX))    RReeffeerreennccee PPaaggeess    XXmmLLiissttDDeesseelleeccttPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttDDeesseelleeccttPPooss-A List function that deselects an item at
          a specified position in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tDDeesseelleeccttPPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       _p_o_s_i_t_i_o_n;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttDDeesseelleeccttPPooss unhighlights the item at the specified
          position and deletes it from the list of selected items.


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

          _p_o_s_i_t_i_o_n
                 Specifies the position of the item to be deselected.
                 A value of 1 indicates that the first item in the
                 list is deselected; a value of 2 indicates that the
                 second item is deselected; and so on.  A value of 0
                 indicates that the last item in the list is
                 deselected.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).



















     2-409                                            (printed 5/7/92)






     XXmmLLiissttGGeettMMaattcchhPPooss((33XX))    RReeffeerreennccee PPaaggeess    XXmmLLiissttGGeettMMaattcchhPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttGGeettMMaattcchhPPooss-A List function that returns all instances
          of an item in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLiisstt..hh>>

          BBoooolleeaann XXmmLLiissttGGeettMMaattcchhPPooss ((_w_i_d_g_e_t, _i_t_e_m, _p_o_s_i_t_i_o_n__l_i_s_t, _p_o_s_i_t_i_o_n__c_o_u_n_t))
               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__l_i_s_t;;
               iinntt       **_p_o_s_i_t_i_o_n__c_o_u_n_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttGGeettMMaattcchhPPooss is a Boolean function that returns an
          array of positions where a specified item is found in a
          List.


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

          _i_t_e_m   Specifies the item to search for.

          _p_o_s_i_t_i_o_n__l_i_s_t
                 Returns an array of positions at which the item
                 occurs in the List.  The position of the first item
                 in the list is 1; the position of the second item is
                 2; and so on.  When the return value is TRUE,
                 XXmmLLiissttGGeettMMaattcchhPPooss allocates memory for this array.
                 The caller is responsible for freeing this memory.

          _p_o_s_i_t_i_o_n__c_o_u_n_t
                 Returns the number of elements in the _p_o_s_i_t_i_o_n__l_i_s_t.


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

     RREETTUURRNN VVAALLUUEE
          Returns TRUE if the specified item is present in the list,
          and FALSE if it is not.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).







     2-410                                            (printed 5/7/92)






     XXmmLLiissttGGeettSSeelleecctteeddPPooss((33XX)) RReeffeerreennccee PPaaggeess XXmmLLiissttGGeettSSeelleecctteeddPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttGGeettSSeelleecctteeddPPooss-A List function that returns the
          position of every selected item in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLiisstt..hh>>

          BBoooolleeaann XXmmLLiissttGGeettSSeelleecctteeddPPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n__l_i_s_t, _p_o_s_i_t_i_o_n__c_o_u_n_t))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       ****_p_o_s_i_t_i_o_n__l_i_s_t;;
               iinntt       **_p_o_s_i_t_i_o_n__c_o_u_n_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttGGeettSSeelleecctteeddPPooss is a Boolean function that returns an
          array of the positions of the selected items in a List.


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

          _p_o_s_i_t_i_o_n__l_i_s_t
                 Returns an array of the positions of the selected
                 items in the List.  The position of the first item in
                 the list is 1; the position of the second item is 2;
                 and so on.  When the return value is TRUE,
                 XXmmLLiissttGGeettSSeelleecctteeddPPooss allocates memory for this array.
                 The caller is responsible for freeing this memory.

          _p_o_s_i_t_i_o_n__c_o_u_n_t
                 Returns the number of elements in the _p_o_s_i_t_i_o_n__l_i_s_t.


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

     RREETTUURRNN VVAALLUUEE
          Returns TRUE if the list has any selected items, and FALSE
          if it does not.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).











     2-411                                            (printed 5/7/92)






     XXmmLLiissttIItteemmEExxiissttss((33XX))     RReeffeerreennccee PPaaggeess     XXmmLLiissttIItteemmEExxiissttss((33XX))



     NNAAMMEE
          XXmmLLiissttIItteemmEExxiissttss-A List function that checks if a specified
          item is in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLiisstt..hh>>

          BBoooolleeaann XXmmLLiissttIItteemmEExxiissttss ((_w_i_d_g_e_t, _i_t_e_m))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttIItteemmEExxiissttss is a Boolean function that checks if a
          specified item is present in the list.


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

          _i_t_e_m   Specifies the item whose presence is checked


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

     RREETTUURRNN VVAALLUUEE
          Returns True if the specified item is present in the list.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).






















     2-412                                            (printed 5/7/92)






     XXmmLLiissttIItteemmPPooss((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLiissttIItteemmPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttIItteemmPPooss-A List function that returns the position of
          an item in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Trial-use

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//LLiisstt..hh>>

          iinntt XXmmLLiissttIItteemmPPooss ((_w_i_d_g_e_t, _i_t_e_m))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttIItteemmPPooss returns the position of the first instance of
          the specified item in a List.


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

          _i_t_e_m   Specifies the item whose position is returned


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

     RREETTUURRNN VVAALLUUEE
          Returns the position in the list of the first instance of
          the specified item.  The position of the first item in the
          list is 1; the position of the second item is 2; and so on.
          This function returns 0 if the item is not found.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).



















     2-413                                            (printed 5/7/92)






     XXmmLLiissttRReeppllaacceeIItteemmss((33XX))   RReeffeerreennccee PPaaggeess   XXmmLLiissttRReeppllaacceeIItteemmss((33XX))



     NNAAMMEE
          XXmmLLiissttRReeppllaacceeIItteemmss-A List function that replaces the
          specified elements in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tRReeppllaacceeIItteemmss ((_w_i_d_g_e_t, _o_l_d__i_t_e_m_s, _i_t_e_m__c_o_u_n_t, _n_e_w__i_t_e_m_s))
               WWiiddggeett    _w_i_d_g_e_t;;
               XXmmSSttrriinngg  **_o_l_d__i_t_e_m_s;;
               iinntt       _i_t_e_m__c_o_u_n_t;;
               XXmmSSttrriinngg  **_n_e_w__i_t_e_m_s;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttRReeppllaacceeIItteemmss replaces each specified item of the list
          with a corresponding new item.


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

          _o_l_d__i_t_e_m_s
                 Specifies the items to be replaced

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

          _n_e_w__i_t_e_m_s
                 Specifies the replacement items


          Every occurrence of each element of _o_l_d__i_t_e_m_s is replaced
          with the corresponding element from _n_e_w__i_t_e_m_s.

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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).












     2-414                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmLLiissttRReeppllaacceeIItteemmssPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttRReeppllaacceeIItteemmssPPooss-A List function that replaces the
          specified elements in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tRReeppllaacceeIItteemmssPPooss ((_w_i_d_g_e_t, _n_e_w__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  **_n_e_w__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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttRReeppllaacceeIItteemmssPPooss replaces the specified number of items
          of the List with new items, starting at the specified
          position in the List.


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

          _n_e_w__i_t_e_m_s
                 Specifies the replacement items.

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

          _p_o_s_i_t_i_o_n
                 Specifies the position of the first item in the list
                 to be replaced.  A value of 1 indicates that the
                 first item replaced is the first item in the list; a
                 value of 2 indicates that it is the second item; and
                 so on.

                 Beginning with the item specified in _p_o_s_i_t_i_o_n,
                 _i_t_e_m__c_o_u_n_t items in the list are replaced with the
                 corresponding elements from _n_e_w__i_t_e_m_s.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).





     2-415                                            (printed 5/7/92)






     XXmmLLiissttSSeelleeccttIItteemm((33XX))     RReeffeerreennccee PPaaggeess     XXmmLLiissttSSeelleeccttIItteemm((33XX))



     NNAAMMEE
          XXmmLLiissttSSeelleeccttIItteemm-A List function that selects an item in the
          list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeelleeccttIItteemm ((_w_i_d_g_e_t, _i_t_e_m, _n_o_t_i_f_y))
               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;;
               BBoooolleeaann   _n_o_t_i_f_y;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeelleeccttIItteemm highlights and adds to the selected list
          the first item in the list that matches _i_t_e_m.


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

          _i_t_e_m   Specifies the item to be selected in the List widget

          _n_o_t_i_f_y Specifies a Boolean value that when True invokes the
                 selection callback for the current mode.  From an
                 application interface view, calling this function
                 with _n_o_t_i_f_y True is indistinguishable from a user-
                 initiated selection action.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).

















     2-416                                            (printed 5/7/92)






     XXmmLLiissttSSeelleeccttPPooss((33XX))      RReeffeerreennccee PPaaggeess      XXmmLLiissttSSeelleeccttPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttSSeelleeccttPPooss-A List function that selects an item at a
          specified position in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeelleeccttPPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n, _n_o_t_i_f_y))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       _p_o_s_i_t_i_o_n;;
               BBoooolleeaann   _n_o_t_i_f_y;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeelleeccttPPooss highlights a List item at the specified
          position and adds it to the list of selected items.


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

          _p_o_s_i_t_i_o_n
                 Specifies the position of the item to be selected.  A
                 value of 1 indicates that the first item in the list
                 is selected; a value of 2 indicates that the second
                 item is selected; and so on.  A value of 0 indicates
                 that the last item in the list is selected.

          _n_o_t_i_f_y Specifies a Boolean value that when True invokes the
                 selection callback for the current mode.  From an
                 application interface view, calling this function
                 with _n_o_t_i_f_y True is indistinguishable from a user-
                 initiated selection action.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).













     2-417                                            (printed 5/7/92)






     XXmmLLiissttSSeettAAddddMMooddee((33XX))     RReeffeerreennccee PPaaggeess     XXmmLLiissttSSeettAAddddMMooddee((33XX))



     NNAAMMEE
          XXmmLLiissttSSeettAAddddMMooddee-A List function that sets add mode in the
          list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Trial-use

     SSYYNNOOPPSSIISS
          ##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tSSeettAAddddMMooddee ((_w_i_d_g_e_t, _s_t_a_t_e))
               WWiiddggeett    _w_i_d_g_e_t;;
               BBoooolleeaann   _s_t_a_t_e;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeettAAddddMMooddee allows applications control over Add Mode
          in the extended selection model.


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

          _s_t_a_t_e  Specifies whether to activate or deactivate Add Mode.
                 If _s_t_a_t_e is True, Add Mode is activated.  If _s_t_a_t_e is
                 False, Add Mode is deactivated.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).























     2-418                                            (printed 5/7/92)






     XXmmLLiissttSSeettBBoottttoommIItteemm((33XX))  RReeffeerreennccee PPaaggeess  XXmmLLiissttSSeettBBoottttoommIItteemm((33XX))



     NNAAMMEE
          XXmmLLiissttSSeettBBoottttoommIItteemm-A List function that makes an existing
          item the last visible item in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeettBBoottttoommIItteemm ((_w_i_d_g_e_t, _i_t_e_m))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeettBBoottttoommIItteemm makes the first item in the list that
          matches _i_t_e_m the last visible item in the list.


          _w_i_d_g_e_t Specifies the ID of the List widget from whose list
                 an item is made the last visible

          _i_t_e_m   Specifies the item


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).
























     2-419                                            (printed 5/7/92)






     XXmmLLiissttSSeettBBoottttoommPPooss((33XX))   RReeffeerreennccee PPaaggeess   XXmmLLiissttSSeettBBoottttoommPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttSSeettBBoottttoommPPooss-A List function that makes a specified
          item the last visible item in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeettBBoottttoommPPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       _p_o_s_i_t_i_o_n;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeettBBoottttoommPPooss makes the item at the specified position
          the last visible item in the List.


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

          _p_o_s_i_t_i_o_n
                 Specifies the position of the item to be made the
                 last visible item in the list.  A value of 1
                 indicates that the first item in the list is the last
                 visible item; a value of 2 indicates that the second
                 item is the last visible item; and so on.  A value of
                 0 indicates that the last item in the list is the
                 last visible item.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).


















     2-420                                            (printed 5/7/92)






     XXmmLLiissttSSeettHHoorriizzPPooss((33XX))    RReeffeerreennccee PPaaggeess    XXmmLLiissttSSeettHHoorriizzPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttSSeettHHoorriizzPPooss-A List function that scrolls to the
          specified position in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeettHHoorriizzPPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       _p_o_s_i_t_i_o_n;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeettHHoorriizzPPooss sets the XXmmNNvvaalluuee resource of the
          horizontal ScrollBar to the specified position and updates
          the visible portion of the list with the new value if the
          List widget's XXmmNNlliissttSSiizzeePPoolliiccyy is set to XXmmCCOONNSSTTAANNTT or
          XXmmRREESSIIZZEE__IIFF__PPOOSSSSIIBBLLEE and the horizontal ScrollBar is
          currently visible.  This is equivalent to moving the
          horizontal ScrollBar to the specified position.


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

          _p_o_s_i_t_i_o_n
                 Specifies the horizontal position


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).



















     2-421                                            (printed 5/7/92)






     XXmmLLiissttSSeettIItteemm((33XX))        RReeffeerreennccee PPaaggeess        XXmmLLiissttSSeettIItteemm((33XX))



     NNAAMMEE
          XXmmLLiissttSSeettIItteemm-A List function that makes an existing item
          the first visible item in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeettIItteemm ((_w_i_d_g_e_t, _i_t_e_m))
               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;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeettIItteemm makes the first item in the list that matches
          _i_t_e_m the first visible item in the list.


          _w_i_d_g_e_t Specifies the ID of the List widget from whose list
                 an item is made the first visible

          _i_t_e_m   Specifies the item


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).
























     2-422                                            (printed 5/7/92)






     XXmmLLiissttSSeettPPooss((33XX))         RReeffeerreennccee PPaaggeess         XXmmLLiissttSSeettPPooss((33XX))



     NNAAMMEE
          XXmmLLiissttSSeettPPooss-A List function that makes the item at the
          given position the first visible position in the list

     AAEESS SSUUPPPPOORRTT LLEEVVEELL
          Full-use

     SSYYNNOOPPSSIISS
          ##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tSSeettPPooss ((_w_i_d_g_e_t, _p_o_s_i_t_i_o_n))
               WWiiddggeett    _w_i_d_g_e_t;;
               iinntt       _p_o_s_i_t_i_o_n;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmLLiissttSSeettPPooss makes the item at the given position the first
          visible position in the List.


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

          _p_o_s_i_t_i_o_n
                 Specifies the position of the item to be made the
                 first visible item in the list.  A value of 1
                 indicates that the first item in the list is the
                 first visible item; a value of 2 indicates that the
                 second item is the first visible item; and so on.  A
                 value of 0 indicates that the last item in the list
                 is the first visible item.


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmLLiisstt((33XX)).


















     2-423                                            (printed 5/7/92)



 m
