


     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

     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
     ___________________________________________________________________________________
     XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic   G
     XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
     XmNhighlightColor       XmCHighlightColor       Pixel              dynamic   G
     XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG







     1-448                                            (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))



     XmNhighlightThickness   XmCHighlightThickness   Dimension          2         CSG
     XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
     XmNshadowThickness      XmCShadowThickness      Dimension          2         CSG
     XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic   G
     XmNtraversalOn          XmCTraversalOn          Boolean            True      CSG
     XmNunitType             XmCUnitType             unsigned char      dynamic   CSG
     XmNuserData             XmCUserData             XtPointer          NULL      CSG


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

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

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

          XXmmNNhhiigghhlliigghhttOOnnEEnntteerr
                    Specifies if the highlighting rectangle is drawn
                    when the 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



     1-449                                            (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))



                         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.

                         When a parent widget has an XXmmNNnnaavviiggaattiioonnTTyyppee
                         of XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP, traversal of non-
                         tab-group widgets within the group is based
                         on the order of those widgets in their
                         parent's XXmmNNcchhiillddrreenn list.

                         When any widget in a hierarchy has an
                         XXmmNNnnaavviiggaattiioonnTTyyppee of XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP,
                         traversal of tab groups in the hierarchy
                         proceeds to widgets in the order in which
                         their XXmmNNnnaavviiggaattiioonnTTyyppee resources were
                         specified as XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP or
                         XXmmSSTTIICCKKYY__TTAABB__GGRROOUUPP, whether by creating the
                         widgets with that value, by calling
                         XXttSSeettVVaalluueess, or by calling XXmmAAddddTTaabbGGrroouupp.


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

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

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

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

                    XXmmNNuunniittTTyyppee can have the following values:


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



     1-450                                            (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))



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

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

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

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


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


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



     1-451                                            (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))



            iinntt          _r_e_a_s_o_n;;
            XXEEvveenntt       * _e_v_e_n_t;;
          }} XXmmAAnnyyCCaallllbbaacckkSSttrruucctt;;


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

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


        BBeehhaavviioorr
          Gadgets cannot have translations associated with them.
          Because of this, a Gadget's behavior is determined by the
          Manager widget into which the Gadget is placed.  If focus is
          on a Gadget, events are passed to the Gadget by its Manager.

     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mMMaannaaggeerr((33XX)), and XXmmSSccrreeeenn((33XX)).




































     1-452                                            (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

     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.


























     1-453                                            (printed 5/7/92)






     XXmmGGeettCCoolloorrCCaallccuullaattiioonn((33XX))RReeffeerreennccee PPaaggeessXXmmGGeettCCoolloorrCCaallccuullaattiioonn((33XX))



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

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

          XXmmCCoolloorrPPrroocc XXmmGGeettCCoolloorrCCaallccuullaattiioonn (())


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettCCoolloorrCCaallccuullaattiioonn returns the procedure being used to
          calculate default colors.

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

     RREETTUURRNN VVAALLUUEE
          Returns the procedure used for default color calculation.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCChhaannggeeCCoolloorr((33XX)), XXmmGGeettCCoolloorrss((33XX)), and
          XXmmSSeettCCoolloorrCCaallccuullaattiioonn((33XX)).
































     1-454                                            (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

     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
                 allocated or returned for this color.

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

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

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



     1-455                                            (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))



     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCChhaannggeeCCoolloorr((33XX)), XXmmGGeettCCoolloorrCCaallccuullaattiioonn((33XX)), and
          XXmmSSeettCCoolloorrCCaallccuullaattiioonn((33XX)).




















































     1-456                                            (printed 5/7/92)






     XXmmGGeettDDeessttiinnaattiioonn((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Deessttiinnaattiioonn((33XX))



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

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

          WWiiddggeett XXmmGGeettDDeessttiinnaattiioonn ((_d_i_s_p_l_a_y))
               DDiissppllaayy   *_d_i_s_p_l_a_y;;


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


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


     RREETTUURRNN VVAALLUUEE
          Returns the widget ID for the current destination or NULL if
          there is no current destination.

     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.



     1-457                                            (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))



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



































     1-458                                            (printed 5/7/92)






     XXmmGGeettFFooccuussWWiid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GeettFFooccuussWWiiddggeett((33XX))



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

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

          WWiiddggeett XXmmGGeettFFooccuussWWiiddggeett ((_w_i_d_g_e_t))
               WWiiddggeett    _w_i_d_g_e_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettFFooccuussWWiiddggeett examines the hierarchy that contains the
          specified widget and returns the ID of the widget that has
          keyboard focus.  The function extracts the widget ID from
          the associated Shell widget; therefore the specified widget
          can be located anywhere in the hierarchy.


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


     RREETTUURRNN VVAALLUUEE
          Returns the ID of the widget with keyboard focus.  If no
          child of the Shell has focus, the function returns NULL.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmPPrroocceessssTTrraavveerrssaall((33XX)).



























     1-459                                            (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 function that returns the cursor ID for
          the current menu cursor

     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.

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


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


     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mSSccrreeeenn((33XX)).




















     1-460                                            (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

     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
          XXAAPPPPLLRREESSDDIIRR is set, the following pathnames are searched:

                    %%BB



     1-461                                            (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//%%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.

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



     1-462                                            (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))



          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mGGeettPPiixxmmaappBByyDDeepptthh((33XX)),
          XXmmIInnssttaallllIImmaaggee((33XX)), and XXmmUUnniinnssttaallllIImmaaggee((33XX)).

























     1-463                                            (printed 5/7/92)






     XXmmGGeettPPiixxmmaappBByyDDeepptthh((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pBByyDDeepptthh((33XX))



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

     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pBByyDDeepptthh ((_s_c_r_e_e_n, _i_m_a_g_e__n_a_m_e,_f_o_r_e_g_r_o_u_n_d, _b_a_c_k_g_r_o_u_n_d, _d_e_p_t_h))
               SSccrreeeenn    **_s_c_r_e_e_n;;
               cchhaarr      **_i_m_a_g_e__n_a_m_e;;
               PPiixxeell     _f_o_r_e_g_r_o_u_n_d;;
               PPiixxeell     _b_a_c_k_g_r_o_u_n_d;;
               iinntt       _d_e_p_t_h;;


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

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

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

          If _i_m_a_g_e__n_a_m_e has a leading slash (//), it specifies a full
          pathname, and XXmmGGeettPPiixxmmaappBByyDDeepptthh opens the file as
          specified.  Otherwise, _i_m_a_g_e__n_a_m_e specifies a filename.  In
          this case XXmmGGeettPPiixxmmaappBByyDDeepptthh looks for the file along a
          search path specified by the XXBBMMLLAANNGGPPAATTHH environment
          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pBByyDDeepptthh is
          substituted for %B.  It can also contain the substitution
          fields accepted by XXttRReessoollvveePPaatthhnnaammee.  The substitution
          field %T is always mapped to bbiittmmaappss, and %S is always
          mapped to NULL.




     1-464                                            (printed 5/7/92)






     XXmmGGeettPPiixxmmaappBByyDDeepptthh((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pBByyDDeepptthh((33XX))



          If XXBBMMLLAANNGGPPAATTHH is not set, but the environment variable
          XXAAPPPPLLRREESSDDIIRR is set, the following pathnames are searched:

                    %%BB
                    $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%NN//%%BB
                    $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%NN//%%BB
                    $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%NN//%%BB
                    $$XXAAPPPPLLRREESSDDIIRR//%%LL//bbiittmmaappss//%%BB
                    $$XXAAPPPPLLRREESSDDIIRR//%%ll//bbiittmmaappss//%%BB
                    $$XXAAPPPPLLRREESSDDIIRR//bbiittmmaappss//%%BB
                    $$HHOOMMEE//bbiittmmaappss//%%BB
                    $$HHOOMMEE//%%BB
                    //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




     1-465                                            (printed 5/7/92)






     XXmmGGeettPPiixxmmaappBByyDDeepptthh((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pBByyDDeepptthh((33XX))



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

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


          Parameter descriptions are listed below:


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

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

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

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

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


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



















     1-466                                            (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

     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.  For torn-off menus, this function returns the
          widget from which the menu was originally torn.  An
          application can use this routine during the activate
          callback to determine the context in which the menu callback
          should be interpreted.


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


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

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




















     1-467                                            (printed 5/7/92)






     XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaaRR(e(e3f3fXeXe)r)reennccee PPXXamamgGgGeeeeststSSeeccoonnddaarryyRReessoouurrcceeDDaattaa((33XX))



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

     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Caarrddiinnaall XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa ((_w_i_d_g_e_t__c_l_a_s_s, _s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n))
               WWiiddggeettCCllaassss         _w_i_d_g_e_t__c_l_a_s_s;;
               XXmmSSeeccoonnddaarryyRReessoouurrcceeDDaattaa****_s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n;;


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

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

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

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


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

          _s_e_c_o_n_d_a_r_y__d_a_t_a__r_e_t_u_r_n
                 Specifies a pointer to an array of
                 XXmmSSeeccoonnddaarryyRReessoouurrcceeDDaattaa pointers to be returned by



     1-468                                            (printed 5/7/92)






     XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaaRR(e(e3f3fXeXe)r)reennccee PPXXamamgGgGeeeeststSSeeccoonnddaarryyRReessoouurrcceeDDaattaa((33XX))



                 this function.  If the widget class has no secondary
                 resource data (i.e., if the value returned by the
                 function is 0), the function returns no meaningful
                 value for this argument.


     RREETTUURRNN VVAALLUUEE
          Returns the number of secondary resource data structures
          associated with this widget class.

     EEXXAAMMPPLLEE
          The following example uses XXmmGGeettSSeeccoonnddaarryyRReessoouurrcceeDDaattaa to
          print the names of the secondary resources of the Motif Text
          widget and then frees the data allocated by the function:

          XmSecondaryResourceData * block_array ;
          Cardinal num_blocks, i, j ;
          if (num_blocks = XmGetSecondaryResourceData (xmTextWidgetClass,
                                                       &block_array)) {
            for (i = 0; i < num_blocks; i++) {
              for (j = 0 ; j < block_array[i]->num_resources; j++) {
                printf("%s\n", block_array[i]->resources[j].resource_name);
              }
              XtFree((char*)block_array[i]->resources);
              XtFree((char*)block_array[i]);
            }
            XtFree((char*)block_array);
          }



























     1-469                                            (printed 5/7/92)






     XXmmGGeettTTaabbGGrroouup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tTTaabbGGrroouupp((33XX))



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

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

          WWiiddggeett XXmmGGeettTTaabbGGrroouupp ((_w_i_d_g_e_t))
               WWiiddggeett    _w_i_d_g_e_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettTTaabbGGrroouupp returns the widget ID of the tab group that
          contains the specified widget.


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


     RREETTUURRNN VVAALLUUEE
          Returns the widget ID of a tab group or shell, determined as
          follows:


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

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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmAAddddTTaabbGGrroouupp((33XX)), XXmmMMaannaaggeerr((33XX)), and XXmmPPrriimmiittiivvee((33XX)).




















     1-470                                            (printed 5/7/92)






     XXmmGGeettTTeeaarrOOffffCCoonnttrrooll((33XX))  RReeffeerreennccee PPaaggeess  XXmmGGeettTTeeaarrOOffffCCoonnttrrooll((33XX))



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

     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tTTeeaarrOOffffCCoonnttrrooll ((_m_e_n_u))
               WWiiddggeett    _m_e_n_u;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettTTeeaarrOOffffCCoonnttrrooll provides the application with the means
          for obtaining the widget ID of the internally created tear-
          off control in a tear-off menu.

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

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


          _m_e_n_u   Specifies the widget ID of the RowColumn PulldownMenu
                 or PopupMenu


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

     RREETTUURRNN VVAALLUUEE
          Returns the widget ID for the tear-off control, or NULL if
          no tear-off control exists.  An application should not
          assume that the returned widget will be of any particular
          class.

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






     1-471                                            (printed 5/7/92)






     XXmmGGeettVViissiibbiilliittyy((33XX))      RReeffeerreennccee PPaaggeess      XXmmGGeettVViissiibbiilliittyy((33XX))



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

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

          XXmmVViissiibbiilliittyy XXmmGGeettVViissiibbiilliittyy ((_w_i_d_g_e_t))
               WWiiddggeett    _w_i_d_g_e_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettVViissiibbiilliittyy returns the visibility state of the
          specified widget.


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


     RREETTUURRNN VVAALLUUEE
          Returns one of the following values:


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

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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmIIssTTrraavveerrssaabbllee((33XX)), XXmmMMaannaaggeerr((33XX)), and
          XXmmPPrroocceessssTTrraavveerrssaall((33XX)).






















     1-472                                            (printed 5/7/92)






     XXmmGGeettXXmmDDiissppllaayy((33XX))       RReeffeerreennccee PPaaggeess       XXmmGGeettXXmmDDiissppllaayy((33XX))



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

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

          WWiiddggeett XXmmGGeettXXmmDDiissppllaayy ((_d_i_s_p_l_a_y))
               DDiissppllaayy     **_d_i_s_p_l_a_y;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettXXmmDDiissppllaayy returns the XXmmDDiissppllaayy object ID associated
          with a display.  The application can access Display
          resources by using XXttGGeettVVaalluueess.


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


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

     RREETTUURRNN VVAALLUUEE
          Returns the XXmmDDiissppllaayy object ID for 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mDDiissppllaayy((33XX)).


























     1-473                                            (printed 5/7/92)






     XXmmGGeettXXmmSSccrreeeenn((33XX))        RReeffeerreennccee PPaaggeess        XXmmGGeettXXmmSSccrreeeenn((33XX))



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

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

          WWiiddggeett XXmmGGeettXXmmSSccrreeeenn ((_s_c_r_e_e_n))
               SSccrreeeenn      **_s_c_r_e_e_n;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmGGeettXXmmSSccrreeeenn returns the XXmmSSccrreeeenn object ID associated with
          a screen.  The application can access and manipulate Screen
          resources by using XXttGGeettVVaalluueess and XXttSSeettVVaalluueess.


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


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

     RREETTUURRNN VVAALLUUEE
          Returns the XXmmSSccrreeeenn object ID.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmSSccrreeeenn((33XX)).


























     1-474                                            (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

     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
          ____________________________________________________________
          background      A tile of solid background
          25_foreground   A tile of 25% foreground, 75% background
          50_foreground   A tile of 50% foreground, 50% background







     1-475                                            (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))



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









































     1-476                                            (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

     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.





















     1-477                                            (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

     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.





























     1-478                                            (printed 5/7/92)






     XXmmIIssTTrraavveerrssaabbllee((33XX))      RReeffeerreennccee PPaaggeess      XXmmIIssTTrraavveerrssaabbllee((33XX))



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

     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sTTrraavveerrssaabbllee ((_w_i_d_g_e_t))
               WWiiddggeett    _w_i_d_g_e_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmIIssTTrraavveerrssaabbllee determines whether the specified widget is
          eligible to receive focus through keyboard traversal.  In
          general, a widget is eligible to receive focus when all of
          the following conditions are true:


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

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

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


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


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


     RREETTUURRNN VVAALLUUEE
          Returns True if the widget is eligible to receive focus
          through keyboard traversal; otherwise, returns False.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmGGeettVViissiibbiilliittyy((33XX)) and XXmmPPrroocceessssTTrraavveerrssaall((33XX)).




     1-479                                            (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

     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.

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

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

        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.

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



     1-480                                            (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 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.

                    Accelerators for buttons are supported only for



     1-481                                            (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))



                    PushButtons and ToggleButtons in Pulldown and
                    Popup MenuPanes.

          XXmmNNaacccceelleerraattoorrTTeexxtt
                    Specifies the text displayed for the accelerator.
                    The text is displayed adjacent to the label string
                    or pixmap.  Accelerator text for buttons is
                    displayed only for PushButtons and 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.
                    If this value is NULL at initialization, the font



     1-482                                            (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))



                    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.  The default value,
                    XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP, displays an empty label.

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

          XXmmNNllaabbeellSSttrriinngg
                    Specifies the compound string when the
                    XXmmNNllaabbeellTTyyppee is XXmmSSTTRRIINNGG.  If this value is NULL,
                    it is initialized by 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-displays text using 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-displays pixmap using 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 an equal amount of spacing above the
                    margin defined by XXmmNNmmaarrggiinnTToopp and below the



     1-483                                            (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))



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

          XXmmNNmmaarrggiinnLLeefftt
                    Specifies the amount of spacing between the left
                    edge of the label text and the right side of the
                    left margin (specified by XXmmNNmmaarrggiinnWWiiddtthh).  This
                    may be modified by Label's subclasses.  For
                    example, ToggleButton may increase this field to
                    make room for the toggle indicator and for spacing
                    between the indicator and label.  Whether this
                    actually applies to the left or right side of the
                    label may depend on the value of
                    XXmmNNssttrriinnggDDiirreec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 an equal amount of spacing to the left
                    of the margin defined by XXmmNNmmaarrggiinnLLeefftt and to the
                    right of the margin defined by XXmmNNmmaarrggiinnRRiigghhtt.
                    XXmmNNmmaarrggiinnWWiiddtthh specifies the amount of spacing
                    between the left edge of the margin set by
                    XXmmNNmmaarrggiinnLLeefftt and the right edge of the left
                    shadow, and the amount of spacing between the
                    right edge of the margin 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



     1-484                                            (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))



                    Provides the user with an alternate means of
                    activating 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
                    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 shrinks or expands to accommodate its
                    contents (label string or pixmap) as a result of
                    an XXttSSeettVVaalluueess resource value that would change
                    the size of the widget.  If True, the widget
                    shrinks or expands to exactly fit the label string
                    or pixmap.  If False, the widget never attempts to
                    change size on its own.

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


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



     1-485                                            (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))



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

                                         XXmmPPrriimmiittiivvee RReessoouurrccee SSeett
     NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt                AAcccceessss
     ________________________________________________________________________________________________
     XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic                CSG
     XmNbottomShadowPixmap   XmCBottomShadowPixmap   Pixmap             XmUNSPECIFIED_PIXMAP   CSG
     XmNforeground           XmCForeground           Pixel              dynamic                CSG
     XmNhelpCallback         XmCCallback             XtCallbackList     NULL                   C
     XmNhighlightColor       XmCHighlightColor       Pixel              dynamic                CSG
     XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False                  CSG
     XmNhighlightPixmap      XmCHighlightPixmap      Pixmap             dynamic                CSG
     XmNhighlightThickness   XmCHighlightThickness   Dimension          0                      CSG
     XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE                 CSG
     XmNshadowThickness      XmCShadowThickness      Dimension          0                      CSG
     XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic                CSG
     XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap             dynamic                CSG
     XmNtraversalOn          XmCTraversalOn          Boolean            False                  CSG
     XmNunitType             XmCUnitType             unsigned char      dynamic                CSG
     XmNuserData             XmCUserData             XtPointer          NULL                   CSG

                                                   CCoorree RReessoouurrccee SSeett
     NNaammee                            CCllaassss                           TTyyppee             DDeeffaauulltt                AAcccceessss
     ______________________________________________________________________________________________________________
     XmNaccelerators                 XmCAccelerators                 XtAccelerators   dynamic                CSG
     XmNancestorSensitive            XmCSensitive                    Boolean          dynamic                G
     XmNbackground                   XmCBackground                   Pixel            dynamic                CSG
     XmNbackgroundPixmap             XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
     XmNborderColor                  XmCBorderColor                  Pixel            XtDefaultForeground    CSG
     XmNborderPixmap                 XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
     XmNborderWidth                  XmCBorderWidth                  Dimension        0                      CSG
     XmNcolormap                     XmCColormap                     Colormap         dynamic                CG
     XmNdepth                        XmCDepth                        int              dynamic                CG
     XmNdestroyCallback              XmCCallback                     XtCallbackList   NULL                   C
     XmNheight                       XmCHeight                       Dimension        dynamic                CSG
     XmNinitialResourcesPersistent   XmCInitialResourcesPersistent   Boolean          True                   C
     XmNmappedWhenManaged            XmCMappedWhenManaged            Boolean          True                   CSG
     XmNscreen                       XmCScreen                       Screen *         dynamic                CG
     XmNsensitive                    XmCSensitive                    Boolean          True                   CSG
     XmNtranslations                 XmCTranslations                 XtTranslations   dynamic                CSG
     XmNwidth                        XmCWidth                        Dimension        dynamic                CSG
     XmNx                            XmCPosition                     Position         0                      CSG
     XmNy                            XmCPosition                     Position         0                      CSG

        TTrraannssllaattiioonnss








     1-486                                            (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))



          XmLabel includes translations from Primitive.  The XmLabel
          translations are listed below.  These translations may not
          directly correspond to a translation table.

          BBDDrraagg PPrreessss::   PPrroocceessssDDrraagg(())

          KKHHeellpp::         HHeellpp(())

          The translations used by subclasses of XmLabel for menu
          traversal are listed below.  These translations may not
          directly correspond to a translation table.

          KKLLeefftt::         MMeennuuTTrraavveerrsseeLLeefftt(())
          KKRRiigghhtt::        MMeennuuTTrraavveerrsseeRRiigghhtt(())
          KKUUpp::           MMeennuuTTrraavveerrsseeUUpp(())
          KKDDoowwnn::         MMeennuuTTrraavveerrsseeDDoowwnn(())
          MMAAnnyy KKCCaanncceell::  MMeennuuEEssccaappee(())


        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.

          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.
















     1-487                                            (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))



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



     1-488                                            (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))



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




     1-489                                            (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))



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


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

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




































     1-490                                            (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

     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.

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

          In a LabelGadget XXmmNNttrraavveerrssaallOOnn and XXmmNNhhiigghhlliigghhttOOnnEEnntteerr are
          forced to False inside Popup MenuPanes, Pulldown MenuPanes,
          and OptionMenus.  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,
          RReeccttOObbjj and XXmmGGaaddggeett classes.




     1-491                                            (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 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
                    exception that only a single event may be
                    specified and only KKeeyyPPrreessss events are allowed.



     1-492                                            (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))



                    Accelerators for buttons are supported only for
                    PushButtonGadgets and ToggleButtonGadgets in
                    Pulldown and Popup menus.

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

          XXmmNNaalliiggnnmmeenntt
                    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.

          XXmmNNffoonnttLLiisstt
                    Specifies the font of the text used in the gadget.



     1-493                                            (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))



                    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.  The default value,
                    XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP, displays an empty label.

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

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

          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 an equal amount of spacing above the



     1-494                                            (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))



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

          XXmmNNmmaarrggiinnLLeefftt
                    Specifies the amount of spacing between the left
                    edge of the label text and the right side of the
                    left margin (specified by XXmmNNmmaarrggiinnWWiiddtthh).  This
                    may be modified by LabelGadget's 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 an equal amount of spacing to the left
                    of the margin defined by XXmmNNmmaarrggiinnLLeefftt and to the
                    right of the margin defined by XXmmNNmmaarrggiinnRRiigghhtt.
                    XXmmNNmmaarrggiinnWWiiddtthh specifies the amount of spacing
                    between the left edge of the margin set by
                    XXmmNNmmaarrggiinnLLeefftt and the right edge of the left
                    shadow, and the amount of spacing between the
                    right edge of the margin 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.




     1-495                                            (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Nmmnneemmoonniicc
                    Provides the user with an alternate means of
                    activating 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
                    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 shrinks or expands to accommodate its
                    contents (label string or pixmap) as a result of
                    an XXttSSeettVVaalluueess resource value that would change
                    the size of the gadget.  If True, the gadget
                    shrinks or expands to exactly fit the label string
                    or pixmap.  If False, the gadget never attempts to
                    change size on its own.

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


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





     1-496                                            (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))



        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
     NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt   AAcccceessss
     ___________________________________________________________________________________
     XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic   G
     XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
     XmNhighlightColor       XmCHighlightColor       Pixel              dynamic   G
     XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG
     XmNhighlightThickness   XmCHighlightThickness   Dimension          0         CSG
     XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
     XmNshadowThickness      XmCShadowThickness      Dimension          0         CSG
     XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic   G
     XmNtraversalOn          XmCTraversalOn          Boolean            False     CSG
     XmNunitType             XmCUnitType             unsigned char      dynamic   CSG
     XmNuserData             XmCUserData             XtPointer          NULL      CSG

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

                              OObbjjeecctt RReessoouurrccee SSeett
      NNaammee                 CCllaassss         TTyyppee             DDeeffaauulltt   AAcccceessss
      ____________________________________________________________________
      XmNdestroyCallback   XmCCallback   XtCallbackList   NULL      C

        BBeehhaavviioorr
          XmLabelGadget includes behavior from XmGadget.  Additional
          XmLabelGadget behavior is described below:


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

          KKHHeellpp:    In a Popup or Pulldown MenuPane, unposts all menus
                    in the menu hierarchy and, when the shell's



     1-497                                            (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))



                    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.

          MMAAnnyy KKCCaanncceell:
                    In a MenuBar, disarms the CascadeButton and the
                    menu and, when the shell's keyboard focus policy
                    is XXmmEEXXPPLLIICCIITT, restores 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.

                    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.

          KKDDoowwnn:    If the current menu item has a submenu and is in a
                    MenuBar, then this action posts the submenu,
                    disarms the current menu item, and arms the
                    submenu's first traversable menu item.

                    If the current menu item is in a MenuPane, then
                    this action disarms the current menu item and arms
                    the item below it.  This action wraps within the
                    MenuPane.  When the current menu item is at the
                    MenuPane's bottom edge, then this action wraps to
                    the topmost menu item in the column to the right,
                    if one exists.  When the current menu item is at
                    the bottom, rightmost corner of the MenuPane, then
                    this action wraps to the tear-off control, if
                    present, or to the top, leftmost menu item.

          KKLLeefftt:    When the current menu item is in a MenuBar, then
                    this action disarms the current item and arms the
                    MenuBar item to the left.  This action wraps
                    within the MenuBar.

                    In MenuPanes, if the current menu item is not at
                    the left edge of a MenuPane, this action disarms
                    the current item and arms the item to its left.



     1-498                                            (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))



                    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
                    submenu and arms the first traversable item in the
                    submenu.  If the current menu item is at the left
                    edge of a submenu not directly attached to a
                    MenuBar item, then this action unposts the current
                    submenu only.

                    In Popup or Torn-off MenuPanes, when the current
                    menu item is at the left edge, this  action wraps
                    within the MenuPane.  If the current menu item is
                    at the left edge of the MenuPane and not in the
                    top row, this action wraps to the rightmost menu
                    item in the row above.  If the current menu item
                    is in the upper, leftmost corner, this action
                    wraps to the tear-off control, if present, or else
                    it wraps to the bottom, rightmost menu item in the
                    MenuPane.

          KKRRiigghhtt:   If the current menu item is in a MenuBar, then
                    this action disarms the current item and arms the
                    MenuBar item to the right.  This action wraps
                    within the MenuBar.

                    In MenuPanes, if the current menu item is a
                    CascadeButton, then this action posts its
                    associated submenu.  If the current menu item is
                    not a CascadeButton and is not at the right edge
                    of a MenuPane, this action disarms the current
                    item and arms the item to its right, wrapping if
                    necessary.  If the current menu item is not a
                    CascadeButton and is at the right edge of a
                    submenu that is a descendent of a MenuBar, then
                    this action unposts all 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.

          KKUUpp:      When the current menu item is in a MenuPane, then



     1-499                                            (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))



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


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

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



































     1-500                                            (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

     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.  When a List is insensitive, all of
          the list items are displayed in a stippled fill pattern.

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


            +o  Single Select

            +o  Browse Select

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



     1-501                                            (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))



          item selects it and deselects any other selected item;
          dragging BBSSeelleecctt moves the selection as the pointer is
          moved.  Releasing BBSSeelleecctt on an item moves the location
          cursor to that item.

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

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



     1-502                                            (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))



        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
     XmNdoubleClickInterval         XmCDoubleClickInterval      int                 dynamic           CSG
     XmNextendedSelectionCallback   XmCCallback                 XtCallbackList      NULL              C
     XmNfontList                    XmCFontList                 XmFontList          dynamic           CSG
     XmNitemCount                   XmCItemCount                int                 0                 CSG
     XmNitems                       XmCItems                    XmStringTable       NULL              CSG
     XmNlistMarginHeight            XmCListMarginHeight         Dimension           0                 CSG
     XmNlistMarginWidth             XmCListMarginWidth          Dimension           0                 CSG
     XmNlistSizePolicy              XmCListSizePolicy           unsigned char       XmVARIABLE        CG
     XmNlistSpacing                 XmCListSpacing              Dimension           0                 CSG
     XmNmultipleSelectionCallback   XmCCallback                 XtCallbackList      NULL              C
     XmNscrollBarDisplayPolicy      XmCScrollBarDisplayPolicy   unsigned char       XmAS_NEEDED       CSG
     XmNselectedItemCount           XmCSelectedItemCount        int                 0                 CSG
     XmNselectedItems               XmCSelectedItems            XmStringTable       NULL              CSG
     XmNselectionPolicy             XmCSelectionPolicy          unsigned char       XmBROWSE_SELECT   CSG
     XmNsingleSelectionCallback     XmCCallback                 XtCallbackList      NULL              C
     XmNstringDirection             XmCStringDirection          XmStringDirection   dynamic           CSG
     XmNtopItemPosition             XmCTopItemPosition          int                 1                 CSG
     XmNvisibleItemCount            XmCVisibleItemCount         int                 dynamic           CSG

          XXmmNNaauuttoommaattiiccSSeelleeccttiioonn
                    Invokes XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk or
                    XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk when BSelect is
                    pressed and the items that are shown as selected



     1-503                                            (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))



                    change if the value is True and the selection mode
                    is either XXmmBBRROOWWSSEE__SSEELLEECCTT or XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT
                    respectively.  If False, no selection callbacks
                    are invoked until the user releases the mouse
                    button.  See the Behavior section for further
                    details on the interaction of this resource with
                    the selection modes.

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

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

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

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

          XXmmNNffoonnttLLiisstt
                    Specifies the font list associated with the list
                    items.  This is used in conjunction with the
                    XXmmNNvviissiibblleeIItteemmCCoouunntt resource to determine the
                    height of the List widget.  If this value is NULL
                    at initialization, the font list is initialized by
                    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
                    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



     1-504                                            (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))



                    the list whenever an item is added to or deleted
                    from the list.

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

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

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

          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.





     1-505                                            (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XttGGeettVVaalluueess for this resource
                    returns the list items themselves, not a copy of
                    the list items.  The application must not free the
                    returned items.

                    Setting XXmmNNsseelleecctteeddIItteemmss selects those list items
                    that exactly match items in the given
                    XXmmNNsseelleecctteeddIItteemmss list.  There may be additional
                    items in XXmmNNsseelleecctteeddIItteemmss that do not match items
                    in the list.  These items remain until
                    XXmmNNsseelleecctteeddIItteemmss is updated.  If XXmmNNiitteemmss is
                    changed such that the list now contains items
                    matching previously unmatched items in
                    XXmmNNsseelleecctteeddIItteemmss, those new items will also appear
                    selected.

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

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


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



     1-506                                            (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  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
                    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







     1-507                                            (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))



     XmNhighlightColor       XmCHighlightColor       Pixel              dynamic                CSG
     XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False                  CSG
     XmNhighlightPixmap      XmCHighlightPixmap      Pixmap             dynamic                CSG
     XmNhighlightThickness   XmCHighlightThickness   Dimension          2                      CSG
     XmNnavigationType       XmCNavigationType       XmNavigationType   XmTAB_GROUP            CSG
     XmNshadowThickness      XmCShadowThickness      Dimension          2                      CSG
     XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic                CSG
     XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap             dynamic                CSG
     XmNtraversalOn          XmCTraversalOn          Boolean            True                   CSG
     XmNunitType             XmCUnitType             unsigned char      dynamic                CSG
     XmNuserData             XmCUserData             XtPointer          NULL                   CSG

                                                   CCoorree RReessoouurrccee SSeett
     NNaammee                            CCllaassss                           TTyyppee             DDeeffaauulltt                AAcccceessss
     ______________________________________________________________________________________________________________
     XmNaccelerators                 XmCAccelerators                 XtAccelerators   dynamic                CSG
     XmNancestorSensitive            XmCSensitive                    Boolean          dynamic                G
     XmNbackground                   XmCBackground                   Pixel            dynamic                CSG
     XmNbackgroundPixmap             XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
     XmNborderColor                  XmCBorderColor                  Pixel            XtDefaultForeground    CSG
     XmNborderPixmap                 XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
     XmNborderWidth                  XmCBorderWidth                  Dimension        0                      CSG
     XmNcolormap                     XmCColormap                     Colormap         dynamic                CG
     XmNdepth                        XmCDepth                        int              dynamic                CG
     XmNdestroyCallback              XmCCallback                     XtCallbackList   NULL                   C
     XmNheight                       XmCHeight                       Dimension        dynamic                CSG
     XmNinitialResourcesPersistent   XmCInitialResourcesPersistent   Boolean          True                   C
     XmNmappedWhenManaged            XmCMappedWhenManaged            Boolean          True                   CSG
     XmNscreen                       XmCScreen                       Screen *         dynamic                CG
     XmNsensitive                    XmCSensitive                    Boolean          True                   CSG
     XmNtranslations                 XmCTranslations                 XtTranslations   dynamic                CSG
     XmNwidth                        XmCWidth                        Dimension        dynamic                CSG
     XmNx                            XmCPosition                     Position         0                      CSG
     XmNy                            XmCPosition                     Position         0                      CSG

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



     1-508                                            (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))



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





     1-509                                            (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))



          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X mm CC RR __ DD EE FF AA UU LL TT __ AA CC TT II OO NN    _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h,
                            _i_t_e_m__p_o_s_i_t_i_o_n, _s_e_l_e_c_t_e_d__i_t_e_m_s,
                            _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t, _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s
     ______________________________________________________________________
     ______________________________________________________________________
     XXmmCCRR__BBRROOWWSSEE__SSEELLEECCTT     _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h, _i_t_e_m__p_o_s_i_t_i_o_n
     ______________________________________________________________________
           XX mm CC RR __ MM UU LL TT II PP LL EE __ SS EE LL EE CC TT   _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h,
                            _i_t_e_m__p_o_s_i_t_i_o_n, _s_e_l_e_c_t_e_d__i_t_e_m_s,
                            _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t, _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s
     ______________________________________________________________________
           XX mm CC RR __ EE XX TT EE NN DD EE DD __ SS EE LL EE CC TT   _r_e_a_s_o_n, _e_v_e_n_t, _i_t_e_m, _i_t_e_m__l_e_n_g_t_h,
                            _i_t_e_m__p_o_s_i_t_i_o_n, _s_e_l_e_c_t_e_d__i_t_e_m_s,
                            _s_e_l_e_c_t_e_d__i_t_e_m__c_o_u_n_t, _s_e_l_e_c_t_e_d__i_t_e_m__p_o_s_i_t_i_o_n_s,
                            _s_e_l_e_c_t_i_o_n__t_y_p_e

        TTrraannssllaattiioonnss
          XmList includes translations from Primitive.  The XmList
          translations are listed below.  These translations may not
          directly correspond to a translation table.

          BBSSeelleecctt PPrreessss:: LLiissttBBeeggiinnSSeelleecctt(())
          BBSSeelleecctt MMoottiioonn::LLiissttBBuuttttoonnMMoottiioonn(())
          BBSSeelleecctt RReelleeaassee::LLiissttEEnnddSSeelleecctt(())

          BBEExxtteenndd PPrreessss:: LLiissttBBeeggiinnEExxtteenndd(())
          BBEExxtteenndd MMoottiioonn::LLiissttBBuuttttoonnMMoottiioonn(())
          BBEExxtteenndd RReelleeaassee::LLiissttEEnnddEExxtteenndd(())

          BBTTooggggllee PPrreessss:: LLiissttBBeeggiinnTTooggggllee(())
          BBTTooggggllee MMoottiioonn::LLiissttBBuuttttoonnMMoottiioonn(())
          BBTTooggggllee RReelleeaassee::LLiissttEEnnddTTooggggllee(())
          BBDDrraagg PPrreessss::   LLiissttPPrroocceessssDDrraagg(())

          KKUUpp::           LLiissttPPrreevvIItteemm(())
          MMSShhiifftt KKUUpp::    LLiissttEExxtteennddPPrreevvIItteemm(())

          KKDDoowwnn::         LLiissttNNeexxttIItteemm(())
          MMSShhiifftt KKDDoowwnn::  LLiissttEExxtteennddNNeexxttIItteemm(())

          KKLLeefftt::         LLiissttLLeeffttCChhaarr(())
          MMCCttrrll KKLLeefftt::   LLiissttLLeeffttPPaaggee(())

          KKRRiigghhtt::        LLiissttRRiigghhttCChhaarr(())
          MMCCttrrll KKRRiigghhtt::  LLiissttRRiigghhttPPaaggee(())



     1-510                                            (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))



          KKPPaaggeeUUpp::       LLiissttPPrreevvPPaaggee(())
          KKPPaaggeeDDoowwnn::     LLiissttNNeexxttPPaaggee(())
          KKPPaaggeeLLeefftt::     LLiissttLLeeffttPPaaggee(())
          KKPPaaggeeRRiigghhtt::    LLiissttRRiigghhttPPaaggee(())

          KKBBeeggiinnLLiinnee::    LLiissttBBeeggiinnLLiinnee(())
          KKEEnnddLLiinnee::      LLiissttEEnnddLLiinnee(())

          KKBBeeggiinnDDaattaa::    LLiissttBBeeggiinnDDaattaa(())
          MMSShhiifftt KKBBeeggiinnDDaattaa::LLiissttBBeeggiinnDDaattaaEExxtteenndd(())

          KKEEnnddDDaattaa::      LLiissttEEnnddDDaattaa(())
          MMSShhiifftt KKEEnnddDDaattaa::LLiissttEEnnddDDaattaaEExxtteenndd(())

          KKAAddddMMooddee::      LLiissttAAddddMMooddee(())

          KKAAccttiivvaattee::     LLiissttKKbbddAAccttiivvaattee(())

          KKCCooppyy PPrreessss::   LLiissttCCooppyyTTooCClliippbbooaarrdd(())
          KKSSeelleecctt PPrreessss:: LLiissttKKbbddBBeeggiinnSSeelleecctt(())
          KKSSeelleecctt RReelleeaassee::LLiissttKKbbddEEnnddSSeelleecctt(())

          KKEExxtteenndd PPrreessss:: LLiissttKKbbddBBeeggiinnEExxtteenndd(())
          KKEExxtteenndd RReelleeaassee::LLiissttKKbbddEEnnddEExxtteenndd(())

          MMAAnnyy KKCCaanncceell::  LLiissttKKbbddCCaanncceell(())
          KKSSeelleeccttAAllll::    LLiissttKKbbddSSeelleeccttAAllll(())
          KKDDeesseelleeccttAAllll::  LLiissttKKbbddDDeeSSeelleeccttAAllll(())

          KKHHeellpp::         PPrriimmiittiivveeHHeellpp(())
          KKNNeexxttFFiieelldd     PPrriimmiittiivveeNNeexxttTTaabbGGrroouupp(())
          KKPPrreevvFFiieelldd     PPrriimmiittiivveePPrreevvTTaabbGGrroouupp(())


        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.


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



     1-511                                            (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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.

                    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



     1-512                                            (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, 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
                    motion.

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

          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



     1-513                                            (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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
                    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(()):



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

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

          LLiissttKKbbddBBeeggiinnEExxtteenndd(()):
                    If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
                    XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, does the following:  If an
                    extended selection has been made from the current



     1-515                                            (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))



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



     1-516                                            (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mEEXXTTEENNDDEEDD__SSEELLEECCTT in Add Mode, deselects all items
                    in the list.  If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
                    XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT in Normal Mode, deselects all
                    items in the list (except the item at the location
                    cursor if the shell's XXmmNNkkeeyybbooaarrddFFooccuussPPoolliiccyy is
                    XXmmEEXXPPLLIICCIITT).  Calls the appropriate selection
                    callbacks (XXmmNNssiinngglleeSSeelleeccttiioonnCCaallllbbaacckk when
                    XXmmNNsseelleec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.




     1-517                                            (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tLLeeffttPPaaggee(()):
                    Scrolls the list one page to the left.

          LLiissttNNeexxttIItteemm(()):
                    Moves the location cursor to the next item in the
                    list.

                    If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
                    XXmmBBRROOWWSSEE__SSEELLEECCTT, this action also selects the next
                    item, deselects any current selection, and calls
                    the XXmmNNbbrroowwsseeSSeelleeccttiioonnCCaallllbbaacckk callbacks.

                    If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
                    XXmmEEXXTTEENNDDEEDD__SSEELLEECCTT, this action in Normal Mode also
                    selects the next item, deselects any current
                    selection, moves the current anchor to the next
                    item, and calls the XXmmNNeexxtteennddeeddSSeelleeccttiioonnCCaallllbbaacckk
                    callbacks.  In Add Mode this action does not
                    affect the selection or the anchor.

          LLiissttNNeexxttPPaaggee(()):
                    Scrolls the list to the next page, moving the
                    location cursor to a new item.

                    If the XXmmNNsseelleeccttiioonnPPoolliiccyy is set to
                    XXmmBBRROOWWSSEE__SSEELLEECCTT, this action also selects the new
                    item, deselects any current selection, and calls
                    the XXmmNNbbrroowwsseeSSeelleec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



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

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

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

          PPrriimmiittiivveeHHeellpp(()):
                    Calls the callbacks for XXmmNNhheellppCCaallllbbaacckk if any
                    exist.  If there are no help callbacks for this
                    widget, this action calls the help callbacks for
                    the nearest ancestor that has them.

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

          PPrriimmiittiivveePPrreevvTTaabbGGrroouupp(()):
                    Moves the focus to the first item contained within
                    the previous tab group.  If the beginning of the



     1-519                                            (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))



                    tab group list is reached, it wraps to the end of
                    the tab group list.


        AAddddiittiioonnaall BBeehhaavviioorr
          The List widget has the additional behavior described below:


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

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

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


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

     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tAAppppeennddEEnnttrryy((33XX)), XXmmLLiissttAAddddIItteemm((33XX)),
          XXmmLLiissttAAddddIItteemmss((33XX)), XXmmLLiissttAAddddIItteemmUUnnsseelleecctteedd((33XX)),
          XXmmLLiissttAAddddIItteemmssUUnnsseelleecctteedd((33XX)), XXmmLLiissttDDeelleetteeAAllllIItteemmss((33XX)),
          XXmmLLiissttDDeelleetteeIItteemm((33XX)), XXmmLLiissttDDeelleetteeIItteemmss((33XX)),
          XXmmLLiissttDDeelleetteeIItteemmssPPooss((33XX)), XXmmLLiissttDDeelleetteePPooss((33XX)),
          XXmmLLiissttDDeelleetteePPoossiittiioonnss((33XX)), XXmmLLiissttDDeesseelleeccttAAllllIItteemmss((33XX)),
          XXmmLLiissttDDeesseelleeccttIItteemm((33XX)), XXmmLLiissttDDeesseelleeccttPPooss((33XX)),
          XXmmLLiissttGGeettKKbbddIItteemmPPooss XXmmLLiissttGGeettMMaattcchhPPooss((33XX)),
          XXmmLLiissttGGeettSSeelleecctteeddPPooss((33XX)), XXmmLLiissttIItteemmEExxiissttss((33XX)),
          XXmmLLiissttIItteemmPPooss((33XX)), XXmmLLiissttPPoossTTooBBoouunnddss((33XX)),
          XXmmLLiissttRReeppllaacceeIItteemmss((33XX)), XXmmLLiissttRReeppllaacceeIItteemmssPPooss((33XX)),
          XXmmLLiissttRReeppllaacceeIItteemmssPPoossiittiioonnss((33XX)),
          XXmmLLiissttRReeppllaacceeIItteemmssPPoossUUnnsseelleecctteedd((33XX)),
          XXmmLLiissttRReeppllaacceeIItteemmssUUnnsseelleecctteedd((33XX)), XXmmLLiissttSSeelleeccttIItteemm((33XX)),
          XXmmLLiissttSSeelleeccttPPooss((33XX)), XXmmLLiissttSSeettAAddddMMooddee((33XX)),
          XXmmLLiissttSSeettBBoottttoommIItteemm((33XX)), XXmmLLiissttSSeettBBoottttoommPPooss((33XX)),
          XXmmLLiissttSSeettHHoorriizzPPooss((33XX)), XXmmLLiissttSSeettIItteemm((33XX)),



     1-520                                            (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tSSeettKKbbddIItteemmPPooss((33XX)), XXmmLLiissttSSeettPPooss((33XX)),
          XXmmLLiissttUUppddaatteeSSeelleecctteeddLLiisstt((33XX)), XXmmLLiissttYYTTooPPooss((33XX)),
          XXmmPPrriimmiittiivvee((33XX)) and XXmmSSttrriinnggCCrreeaattee((33XX)).




















































     1-521                                            (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

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

















     1-522                                            (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

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


















     1-523                                            (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

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










     1-524                                            (printed 5/7/92)






     XXmmLLiissttAAddddIItteemmssUUnnsseelleecctteedd((33RRXeXe)f)feerreennccee PPaaggXXememsLsLiissttAAddddIItteemmssUUnnsseelleecctteedd((33XX))



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

     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sUUnnsseelleecctteedd ((_w_i_d_g_e_t, _i_t_e_m_s, _i_t_e_m__c_o_u_n_t, _p_o_s_i_t_i_o_n))
               WWiiddggeett    _w_i_d_g_e_t;;
               XXmmSSttrriinngg  **_i_t_e_m_s;;
               iinntt       _i_t_e_m__c_o_u_n_t;;
               iinntt       _p_o_s_i_t_i_o_n;;


     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sUUnnsseelleecctteedd adds the specified items to the
          list at the given position.  The inserted items remain
          unselected, even if they currently appear in the
          XXmmNNsseelleecctteeddIItteemmss list.


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

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

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

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


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

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











     1-525                                            (printed 5/7/92)



 i
