


   XmScrollVisible(3X)



   NAME
     XXmmSSccrroollllVViissiibbllee-A ScrolledWindow function that makes an invisible
      descendant of a ScrolledWindow work area visible

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSccrroolllleeddWW..hh>>
     vvooiidd XXmmSSccrroollllVViissiibbllee ((_s_c_r_o_l_l_w__w_i_d_g_e_t, _w_i_d_g_e_t, _l_e_f_t__r_i_g_h_t__m_a_r_g_i_n, _t_o_p__b_o_t_t_o_m__m_a_r_g_i_n))
          WWiiddggeett      _s_c_r_o_l_l_w__w_i_d_g_e_t;;
          WWiiddggeett      _w_i_d_g_e_t;;
          DDiimmeennssiioonn   _l_e_f_t__r_i_g_h_t__m_a_r_g_i_n;;
          DDiimmeennssiioonn   _t_o_p__b_o_t_t_o_m__m_a_r_g_i_n;;

   DESCRIPTION
     XXmmSSccrroollllVViissiibbllee makes an obscured or partially obscured widget or gadget
     descendant of a ScrolledWindow work area visible.  The function reposi-
     tions the work area and sets the specified margins between the widget
     and the nearest viewport boundary.  The widget's location relative to
     the viewport determines whether one or both of the margins must be
     adjusted.  This function requires that the XXmmNNssccrroolllliinnggPPoolliiccyy of the
     ScrolledWindow widget be set to XXmmAAUUTTOOMMAATTIICC.

     _s_c_r_o_l_l_w__w_i_d_g_e_t
            Specifies the ID of the ScrolledWindow widget whose work area
            window contains an obscured descendant.

     _w_i_d_g_e_t Specifies the ID of the widget to be made visible.

     _l_e_f_t__r_i_g_h_t__m_a_r_g_i_n
            Specifies the margin to establish between the left or right edge
            of the widget and the associated edge of the viewport.  This mar-
            gin is established only if the widget must be moved horizontally
            to make it visible.

     _t_o_p__b_o_t_t_o_m__m_a_r_g_i_n
            Specifies the margin to establish between the top or bottom edge
            of the widget and the associated edge of the viewport.  This mar-
            gin is established only if the widget must be moved vertically to
            make it visible.

     For a complete definition of ScrolledWindow and its associated
     resources, see XXmmSSccrroolllleeddWWiinnddooww((33XX))

   RELATED INFORMATION
     XXmmSSccrroolllleeddWWiinnddooww((33XX)).











   1-620






                                                         XmScrolledWindow(3X)



   NAME
     XXmmSSccrroolllleeddWWiinnddooww-The ScrolledWindow widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSccrroolllleeddWW..hh>>

   DESCRIPTION
     The ScrolledWindow widget combines one or two ScrollBar widgets and a
     viewing area to implement a visible window onto some other (usually
     larger) data display.  The visible part of the window can be scrolled
     through the larger display by the use of ScrollBars.

     To use ScrolledWindow, an application first creates a ScrolledWindow
     widget, any needed ScrollBar widgets, and a widget capable of displaying
     any desired data as the work area of ScrolledWindow.  ScrolledWindow
     positions the work area widget and displays the ScrollBars if so
     requested.  When the user performs some action on the ScrollBar, the
     application is notified through the normal ScrollBar callback interface.

     ScrolledWindow can be configured to operate automatically so that it
     performs all scrolling and display actions with no need for application
     program involvement.  It can also be configured to provide a minimal
     support framework in which the application is responsible for processing
     all user input and making all visual changes to the displayed data in
     response to that input.

     When ScrolledWindow is performing automatic scrolling it creates a clip-
     ping window and automatically creates the scroll bars.  Conceptually,
     this window becomes the viewport through which the user examines the
     larger underlying data area.  The application simply creates the desired
     data, then makes that data the work area of the ScrolledWindow.  When
     the user moves the slider to change the displayed data, the workspace is
     moved under the viewing area so that a new portion of the data becomes
     visible.

     Sometimes it is impractical for an application to create a large data
     space and simply display it through a small clipping window.  For exam-
     ple, in a text editor, creating a single data area that consisted of a
     large file would involve an undesirable amount of overhead.  The appli-
     cation needs to use a ScrolledWindow (a small viewport onto some larger
     data), but needs to be notified when the user scrolled the viewport so
     it could bring in more data from storage and update the display area.
     For these cases the ScrolledWindow can be configured so that it provides
     only visual layout support.  No clipping window is created, and the
     application must maintain the data displayed in the work area, as well
     as respond to user input on the ScrollBars.

     The user can specify resources in a resource file for the automatically
     created widgets that contain the horizontal and vertical scrollbars of
     the ScrolledWindow widget.  The names of these widgets are
     "HorScrollBar" and "VertScrollBar", and remain consistent whether
     created by XXmmCCrreeaatteeSSccrroolllleeddLLiisstt, XXmmCCrreeaatteeSSccrroolllleeddTTeexxtt or XXmmCCrreeaatteeSSccrrooll--
     lleeddWWiinnddooww.


   1-621






   XmScrolledWindow(3X)



     Classes

     ScrolledWindow inherits behavior and resources from CCoorree, CCoommppoossiittee,
     CCoonnssttrraaiinntt, and XXmmMMaannaaggeerr Classes.

     The class pointer is xxmmSSccrroolllleeddWWiinnddoowwWWiiddggeettCCllaassss.

     The class name is XXmmSSccrroolllleeddWWiinnddooww.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                                            XXmmSSccrroolllleeddWWiinnddooww 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
   _______________________________________________________________________________________________________________
   XmNclipWindow                   XmCClipWindow                   Widget           dynamic                 G
   XmNhorizontalScrollBar          XmCHorizontalScrollBar          Widget           dynamic                 CSG
   XmNscrollBarDisplayPolicy       XmCScrollBarDisplayPolicy       unsigned char    dynamic                 CSG
   XmNscrollBarPlacement           XmCScrollBarPlacement           unsigned char    XmBOTTOM_RIGHT          CSG
   XmNscrolledWindowMarginHeight   XmCScrolledWindowMarginHeight   Dimension        0                       CSG
   XmNscrolledWindowMarginWidth    XmCScrolledWindowMarginWidth    Dimension        0                       CSG
   XmNscrollingPolicy              XmCScrollingPolicy              unsigned char    XmAPPLICATION_DEFINED   CG
   XmNspacing                      XmCSpacing                      Dimension        4                       CSG
   XmNtraverseObscuredCallback     XmCCallback                     XtCallbackList   NULL                    CSG
   XmNverticalScrollBar            XmCVerticalScrollBar            Widget           dynamic                 CSG
   XmNvisualPolicy                 XmCVisualPolicy                 unsigned char    dynamic                 G
   XmNworkWindow                   XmCWorkWindow                   Widget           NULL                    CSG

     XXmmNNcclliippWWiinnddooww
               Specifies the widget ID of the clipping area.  This is
               automatically created by ScrolledWindow when the XXmmNNvviissuuaallPPooll--
               iiccyy resource is set to XXmmCCOONNSSTTAANNTT and can only be read by the
               application.  Any attempt to set this resource to a new value
               causes a warning message to be printed by the scrolled window.
               If the XXmmNNvviissuuaallPPoolliiccyy resource is set to XXmmVVAARRIIAABBLLEE, this
               resource is set to NULL, and no clipping window is created.

     XXmmNNhhoorriizzoonnttaallSSccrroollllBBaarr
               Specifies the widget ID of the horizontal ScrollBar.  This is
               automatically created by ScrolledWindow when the XXmmNNssccrroolllliinngg--
               PPoolliiccyy is initialized to XXmmAAUUTTOOMMAATTIICC; otherwise, the default
               is NULL.



   1-622






                                                         XmScrolledWindow(3X)


     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 automatic placement of the ScrollBars.  If it is
               set to XXmmAASS__NNEEEEDDEEDD and if XXmmNNssccrroolllliinnggPPoolliiccyy is set to XXmmAAUU--
               TTOOMMAATTIICC, ScrollBars are displayed only if the workspace
               exceeds the clip area in one or both dimensions.  A resource
               value of XXmmSSTTAATTIICC causes the ScrolledWindow to display the
               ScrollBars whenever they are managed, regardless of the rela-
               tionship between the clip window and the work area.  This
               resource must be XXmmSSTTAATTIICC when XXmmNNssccrroolllliinnggPPoolliiccyy is
               XXmmAAPPPPLLIICCAATTIIOONN__DDEEFFIINNEEDD.  The default is XXmmAASS__NNEEEEDDEEDD when
               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 XXmmSSTTAATTIICC otherwise.

     XXmmNNssccrroollllBBaarrPPllaacceemmeenntt
               Specifies the positioning of the ScrollBars in relation to the
               work window.  The following are the values:

                 ++oo  XXmmTTOOPP__LLEEFFTT-The horizontal ScrollBar is placed above the
                    work window; the vertical ScrollBar to the left.

                 ++oo  XXmmBBOOTTTTOOMM__LLEEFFTT-The horizontal ScrollBar is placed below
                    the work window; the vertical ScrollBar to the left.

                 ++oo  XXmmTTOOPP__RRIIGGHHTT-The horizontal ScrollBar is placed above the
                    work window; the vertical ScrollBar to the right.

                 ++oo  XXmmBBOOTTTTOOMM__RRIIGGHHTT-The horizontal ScrollBar is placed below
                    the work window; the vertical ScrollBar to the right.
               The default value may depend on the value of the XXmmNNssttrriinngg--
               DDiirreeccttiioonn resource.

     XXmmNNssccrroolllleeddWWiinnddoowwMMaarrggiinnHHeeiigghhtt
               Specifies the margin height on the top and bottom of the
               ScrolledWindow.

     XXmmNNssccrroolllleeddWWiinnddoowwMMaarrggiinnWWiiddtthh
               Specifies the margin width on the right and left sides of the
               ScrolledWindow.

     XXmmNNssccrroolllliinnggPPoolliiccyy
               Performs automatic scrolling of the work area with no applica-
               tion interaction.  If the value of this resource is XXmmAAUU--
               TTOOMMAATTIICC, ScrolledWindow automatically creates the ScrollBars;
               attaches callbacks to the ScrollBars; sets the visual policy
               to XXmmCCOONNSSTTAANNTT; and automatically moves the work area through
               the clip window in response to any user interaction with the
               ScrollBars.  An application can also add its own callbacks to
               the ScrollBars.  This allows the application to be notified of
               a scroll event without having to perform any layout pro-
               cedures.
               NNOOTTEE:  Since the ScrolledWindow adds callbacks to the
               ScrollBars, an application should not perform an XXttRReemmoovveeAAllll--
               CCaallllbbaacckkss on any of the ScrollBar widgets.
               When XXmmNNssccrroolllliinnggPPoolliiccyy is set to XXmmAAPPPPLLIICCAATTIIOONN__DDEEFFIINNEEDD, the
               application is responsible for all aspects of scrolling.  The


   1-623






   XmScrolledWindow(3X)


               ScrollBars must be created by the application, and it is
               responsible for performing any visual changes in the work area
               in response to user input.
               This resource must be set to the desired policy at the time
               the ScrolledWindow is created.  It cannot be changed through
               SSeettVVaalluueess.

     XXmmNNssppaacciinngg
               Specifies the distance that separates the ScrollBars from the
               work window.

     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
               Specifies a list of callbacks that is called when traversing
               to a widget or gadget that is obscured due to its position in
               the work area relative to the location of the ScrolledWindow
               viewport.  This resource is valid only when 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.  If this resource is NULL, an obscured widget
               cannot be traversed to.  The callback reason is
               XXmmCCRR__OOBBSSCCUURREEDD__TTRRAAVVEERRSSAALL.

     XXmmNNvveerrttiiccaallSSccrroollllBBaarr
               Specifies the widget ID of the vertical ScrollBar.  This is
               automatically created by ScrolledWindow when the XXmmNNssccrroolllliinngg--
               PPoolliiccyy is initialized to XXmmAAUUTTOOMMAATTIICC; otherwise, the default
               is NULL.

     XXmmNNvviissuuaallPPoolliiccyy
               Grows the ScrolledWindow to match the size of the work area,
               or it can be used as a static viewport onto a larger data
               space.  If the visual policy is XXmmVVAARRIIAABBLLEE, the ScrolledWindow
               forces the ScrollBar display policy to XXmmSSTTAATTIICC and allow the
               work area to grow or shrink at any time and adjusts its layout
               to accommodate the new size.  When the policy is XXmmCCOONNSSTTAANNTT,
               the work area grows or shrinks as requested, but a clipping
               window forces the size of the visible portion to remain con-
               stant.  The only time the viewing area can grow is in response
               to a resize from the ScrolledWindow's parent.  The default is
               XXmmCCOONNSSTTAANNTT when 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 XXmmVVAARRII--
               AABBLLEE otherwise.
               NNOOTTEE:  This resource must be set to the desired policy at the
               time the ScrolledWindow is created.  It cannot be changed
               through SSeettVVaalluueess.

     XXmmNNwwoorrkkWWiinnddooww
               Specifies the widget ID of the viewing area.

     Inherited Resources

     ScrolledWindow inherits behavior and resources from the following
     superclasses.  For a complete description of each resource, refer to the






   1-624






                                                         XmScrolledWindow(3X)


     man page for that superclass.
                                        XXmmMMaannaaggeerr 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
   XmNhighlightPixmap      XmCHighlightPixmap      Pixmap              dynamic                CSG
   XmNinitialFocus         XmCInitialFocus         Widget              NULL                   CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType    XmTAB_GROUP            CSG
   XmNshadowThickness      XmCShadowThickness      Dimension           dynamic                CSG
   XmNstringDirection      XmCStringDirection      XmStringDirection   dynamic                CG
   XmNtopShadowColor       XmCTopShadowColor       Pixel               dynamic                CSG
   XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap              dynamic                CSG
   XmNtraversalOn          XmCTraversalOn          Boolean             True                   CSG
   XmNunitType             XmCUnitType             unsigned char       dynamic                CSG
   XmNuserData             XmCUserData             XtPointer           NULL                   CSG
                              CCoommppoossiitte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
      ______________________________________________________________________
      XmNchildren         XmCReadOnly         WidgetList    NULL      G
      XmNinsertPosition   XmCInsertPosition   XtOrderProc   NULL      CSG
      XmNnumChildren      XmCReadOnly         Cardinal      0         G
                                                 CCoorree RReessoouurrccee SSeett
   NNaammee                            CCllaassss                           TTyyppee             DDeeffaauulltt                AAcccceessss
   ______________________________________________________________________________________________________________
   XmNaccelerators                 XmCAccelerators                 XtAccelerators   dynamic                CSG
   XmNancestorSensitive            XmCSensitive                    Boolean          dynamic                G
   XmNbackground                   XmCBackground                   Pixel            dynamic                CSG
   XmNbackgroundPixmap             XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
   XmNborderColor                  XmCBorderColor                  Pixel            XtDefaultForeground    CSG
   XmNborderPixmap                 XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
   XmNborderWidth                  XmCBorderWidth                  Dimension        0                      CSG
   XmNcolormap                     XmCColormap                     Colormap         dynamic                CG
   XmNdepth                        XmCDepth                        int              dynamic                CG
   XmNdestroyCallback              XmCCallback                     XtCallbackList   NULL                   C
   XmNheight                       XmCHeight                       Dimension        dynamic                CSG
   XmNinitialResourcesPersistent   XmCInitialResourcesPersistent   Boolean          True                   C
   XmNmappedWhenManaged            XmCMappedWhenManaged            Boolean          True                   CSG
   XmNscreen                       XmCScreen                       Screen *         dynamic                CG
   XmNsensitive                    XmCSensitive                    Boolean          True                   CSG
   XmNtranslations                 XmCTranslations                 XtTranslations   dynamic                CSG
   XmNwidth                        XmCWidth                        Dimension        dynamic                CSG
   XmNx                            XmCPosition                     Position         0                      CSG
   XmNy                            XmCPosition                     Position         0                      CSG

     Callback Information

     The application must use the ScrollBar callbacks to be notified of user
     input.




   1-625






   XmScrolledWindow(3X)


     ScrolledWindow defines a callback structure for use with XXmmNNttrraavveerrsseeOObb--
     ssccuurreeddCCaallllbbaacckk callbacks. The 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 resource pro-
     vides a mechanism for traversal to obscured widgets (or gadgets) due to
     their position in the work area of a ScrolledWindow.  The XXmmNNttrraavveerrsseeOObb--
     ssccuurreeddCCaallllbbaacckk routine has responsibility for adjusting the position of
     the work area such that the specified traversal destination widget is
     positioned within the viewport of the ScrolledWindow.  A NULL XXmmNNttrraavveerr--
     sseeOObbssccuurreeddCCaallllbbaacckk resource causes obscured widgets within the Scrol-
     ledWindow to be non-traversable.

     Traversal to an obscured widget or gadget requires these conditions to
     be met: the widget or gadget can be obscured only due to its position in
     the work area of a ScrolledWindow relative to the viewport; the viewport
     of the associated ScrolledWindow is fully visible, or can be made so by
     virtue of ancestral 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 routines; and the
     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 resource must be non-NULL.

     When ScrolledWindow widgets are nested, the 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
     routine for each ScrolledWindow that obscures the traversal destination
     is called in ascending order within the given hierarchy.

     A pointer to the following structure is passed to callbacks for
     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.
     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::
             WWiiddggeett   _t_r_a_v_e_r_s_a_l__d_e_s_t_i_n_a_t_i_o_n;;
             XXmmTTrraavveerrssaallDDiirreeccttiioonn_d_i_r_e_c_t_i_o_n;;
     }} XXmmTTrraavveerrsseeOObbssccuurreeddC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.

     _t_r_a_v_e_r_s_a_l__d_e_s_t_i_n_a_t_i_o_n
            Specifies the widget or gadget to traverse to, which will be a
            descendant of the work window.

     _d_i_r_e_c_t_i_o_n
            Specifies the direction of traversal.  See the description of the
            _d_i_r_e_c_t_i_o_n parameter in the XXmmPPrroocceessssTTrraavveerrssaall man page for an
            explanation of the valid values.

     Translations

     XmScrolledWindow includes the translations from XmManager.

     Additional Behavior







   1-626






                                                         XmScrolledWindow(3X)


     This widget has the additional behavior described below:

     KKPPaaggeeUUpp:  If 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, scrolls the window up
               the height of the viewport.  The distance scrolled may be
               reduced to provide some overlap.  The actual distance scrolled
               depends on the XXmmNNppaaggeeIInnccrreemmeenntt resource of the vertical
               ScrollBar.

     KKPPaaggeeDDoowwnn:
               If 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, scrolls the window down
               the height of the viewport.  The distance scrolled may be
               reduced to provide some overlap.  The actual distance scrolled
               depends on the XXmmNNppaaggeeIInnccrreemmeenntt resource of the vertical
               ScrollBar.

     KKPPaaggeeLLeefftt:
               If 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, scrolls the window left
               the width of the viewport.  The distance scrolled may be
               reduced to provide some overlap.  The actual distance scrolled
               depends on the XXmmNNppaaggeeIInnccrreemmeenntt resource of the horizontal
               ScrollBar.

     KKPPaaggeeRRiigghhtt:
               If 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, scrolls the window right
               the width of the viewport.  The distance scrolled may be
               reduced to provide some overlap.  The actual distance scrolled
               depends on the XXmmNNppaaggeeIInnccrreemmeenntt resource of the horizontal
               ScrollBar.

     KKBBeeggiinnLLiinnee:
               If 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, scrolls the window hor-
               izontally to the edge corresponding to the horizontal
               ScrollBar's minimum value.

     KKEEnnddLLiinnee: If 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, scrolls the window hor-
               izontally to the edge corresponding to the horizontal




















   1-627






   XmScrolledWindow(3X)


               ScrollBar's maximum value.

     KKBBeeggiinnDDaattaa:
               If 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, scrolls the window vert-
               ically to the edge corresponding to the vertical ScrollBar's
               minimum value.

     KKEEnnddDDaattaa: If 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, scrolls the window vert-
               ically to the edge corresponding to the vertical ScrollBar's
               maximum value.

     Certain applications will want to replace the page bindings with ones
     that are specific to the content of the scrolled area.

     Virtual Bindings

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

   RELATED INFORMATION
     CCoommppoossiittee((33XX)), CCoonnssttrraaiinntt((33XX)), CCoorree((33XX)), XXmmCCrreeaatteeSSccrroolllleeddWWiinnddooww((33XX)),
     XXmmMMaannaaggeerr((33XX)), XXmmPPrroocceessssTTrraavveerrssaall((33XX)), XXmmSSccrroollllBBaarr((33XX)),
     XXmmSSccrroollllVViissiibbllee((33XX)), and XXmmSSccrroolllleeddWWiinnddoowwSSeettAArreeaass((33XX)).

































   1-628






                                                 XmScrolledWindowSetAreas(3X)



   NAME
     XXmmSSccrroolllleeddWWiinnddoowwSSeettAArreeaass-A ScrolledWindow function that adds or changes
     a window work region and a horizontal or vertical ScrollBar widget to
     the ScrolledWindow widget

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSccrroolllleeddWW..hh>>
     vvooiidd XXmmSSccrroolllleeddWWiinnddoowwSSeettAArreeaass ((_w_i_d_g_e_t, _h_o_r_i_z_o_n_t_a_l__s_c_r_o_l_l_b_a_r, _v_e_r_t_i_c_a_l__s_c_r_o_l_l_b_a_r, _w_o_r_k__r_e_g_i_o_n))
          WWiiddggeett    _w_i_d_g_e_t;;
          WWiiddggeett    _h_o_r_i_z_o_n_t_a_l__s_c_r_o_l_l_b_a_r;;
          WWiiddggeett    _v_e_r_t_i_c_a_l__s_c_r_o_l_l_b_a_r;;
          WWiiddggeett    _w_o_r_k__r_e_g_i_o_n;;

   DESCRIPTION
     XXmmSSccrroolllleeddWWiinnddoowwSSeettAArreeaass adds or changes a window work region and a hor-
     izontal or vertical ScrollBar widget to the ScrolledWindow widget for
     the application.  Each widget is optional and may be passed as NULL.

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

     _h_o_r_i_z_o_n_t_a_l__s_c_r_o_l_l_b_a_r
                    Specifies the ScrollBar widget ID for the horizontal
                    ScrollBar to be associated with the ScrolledWindow
                    widget.  Set this ID only after creating an instance of
                    the ScrolledWindow widget.  The resource name associated
                    with this argument is XXmmNNhhoorriizzoonnttaallSSccrroollllBBaarr.

     _v_e_r_t_i_c_a_l__s_c_r_o_l_l_b_a_r
                    Specifies the ScrollBar widget ID for the vertical
                    ScrollBar to be associated with the ScrolledWindow
                    widget.  Set this ID only after creating an instance of
                    the ScrolledWindow widget.  The resource name associated
                    with this argument is XXmmNNvveerrttiiccaallSSccrroollllBBaarr.

     _w_o_r_k__r_e_g_i_o_n    Specifies the widget ID for the work window to be associ-
                    ated with the ScrolledWindow widget.  Set this ID only
                    after creating an instance of the ScrolledWindow widget.
                    The attribute name associated with this argument is
                    XXmmNNwwoorrkkWWiinnddooww.

     For a complete definition of ScrolledWindow and its associated
     resources, see XXmmSSccrroolllleeddWWiinnddooww((33XX)).

   RELATED INFORMATION
     XXmmSSccrroolllleeddWWiinnddooww((33XX)).










   1-629






   XmSelectionBox(3X)



   NAME
     XXmmSSeelleeccttiioonnBBooxx-The SelectionBox widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSeelleeccttiiooBB..hh>>

   DESCRIPTION
     SelectionBox is a general dialog widget that allows the user to select
     one item from a list.  By default a SelectionBox includes the following:

       ++oo  A scrolling list of alternatives

       ++oo  An editable text field for the selected alternative

       ++oo  Labels for the list and text field

       ++oo  Three or four buttons

     The default button labels are OOKK, CCaanncceell, and HHeellpp.  By default an AAppppllyy
     button is also created; if the parent of the SelectionBox is a Dialog-
     Shell it is managed, and otherwise it is unmanaged.  Additional children
     may be added to the SelectionBox after creation.  The first child is
     used as a work area.  The value of XXmmNNcchhiillddPPllaacceemmeenntt determines if the
     work area is placed above or below the Text area, or above or below the
     List area.  Additional children are laid out in the following manner:

       ++oo  Menubar-The first menu bar child is placed at the top of the win-
          dow.

       ++oo  Buttons-All XXmmPPuusshhBBuuttttoonn widgets or gadgets, and their subclasses
          are placed after the OOKK button in the order of their creation.

       ++oo  The layout of additional children which are not in the above
          categories is undefined.

     The user can select an item in two ways: by scrolling through the list
     and selecting the desired item or by entering the item name directly
     into the text edit area.  Selecting an item from the list causes that
     item name to appear in the selection text edit area.

     The user may select a new item as many times as desired.  The item is
     not actually selected until the user presses the OOKK PushButton.

     The default value for the XXmmBBuulllleettiinnBBooaarrdd resource XXmmNNccaanncceellBBuuttttoonn is
     the Cancel button unless XXmmNNddiiaallooggTTyyppee is XXmmDDIIAALLOOGG__CCOOMMMMAANNDD, when the
     default is NULL.  The default value for the XXmmBBuulllleettiinnBBooaarrdd resource
     XXmmNNddeeffaauullttBBuuttttoonn is the OK button unless XXmmNNddiiaallooggTTyyppee is
     XXmmDDIIAALLOOGG__CCOOMMMMAANNDD, when the default is NULL.

     For SelectionBox and its subclasses, the default value for XXmmNNiinniittiiaall--
     FFooccuuss is the text edit area.




   1-630






                                                           XmSelectionBox(3X)


     The user can specify resources in a resource file for the automatically
     created widgets and gadgets of SelectionBox.  The following list identi-
     fies the names of these widgets (or gadgets) and the associated Selec-
     tionBox areas.

       ++oo  List Items Label-"Items"

       ++oo  List Items-"ItemsList"

       ++oo  Selection Label-"Selection"

       ++oo  Selection Text-"Text"

       ++oo  Selection Separator-"Separator"

     Classes

     SelectionBox inherits behavior and resources from CCoorree, CCoommppoossiittee, CCoonn--
     ssttrraaiinntt, XXmmMMaannaaggeerr, and XXmmBBuulllleettiinnBBooaarrdd Classes.

     The class pointer is xxmmSSeelleeccttiioonnBBooxxWWiiddggeettCCllaassss.

     The class name is XXmmSSeelleeccttiioonnBBooxx.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                                        XXmmSSeelleeccttiioonnBBooxx 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
   _____________________________________________________________________________________________________
   XmNapplyCallback          XmCCallback               XtCallbackList   NULL                      C
   XmNapplyLabelString       XmCApplyLabelString       XmString         dynamic                   CSG
   XmNcancelCallback         XmCCallback               XtCallbackList   NULL                      C
   XmNcancelLabelString      XmCCancelLabelString      XmString         dynamic                   CSG
   XmNchildPlacement         XmCChildPlacement         unsigned char    XmPLACE_ABOVE_SELECTION   CSG
   XmNdialogType             XmCDialogType             unsigned char    dynamic                   CG
   XmNhelpLabelString        XmCHelpLabelString        XmString         dynamic                   CSG
   XmNlistItemCount          XmCItemCount              int              0                         CSG
   XmNlistItems              XmCItems                  XmStringTable    NULL                      CSG
   XmNlistLabelString        XmCListLabelString        XmString         dynamic                   CSG
   XmNlistVisibleItemCount   XmCVisibleItemCount       int              dynamic                   CSG
   XmNminimizeButtons        XmCMinimizeButtons        Boolean          False                     CSG
   XmNmustMatch              XmCMustMatch              Boolean          False                     CSG
   XmNnoMatchCallback        XmCCallback               XtCallbackList   NULL                      C


   1-631






   XmSelectionBox(3X)


   XmNokCallback             XmCCallback               XtCallbackList   NULL                      C
   XmNokLabelString          XmCOkLabelString          XmString         dynamic                   CSG
   XmNselectionLabelString   XmCSelectionLabelString   XmString         dynamic                   CSG
   XmNtextAccelerators       XmCTextAccelerators       XtAccelerators   default                   C
   XmNtextColumns            XmCColumns                short            dynamic                   CSG
   XmNtextString             XmCTextString             XmString         ""                        CSG

     XXmmNNaappppllyyCCaallllbbaacckk
               Specifies the list of callbacks called when the user activates
               the AAppppllyy button.  The callback reason is XXmmCCRR__AAPPPPLLYY.

     XXmmNNaappppllyyLLaabbeellSSttrriinngg
               Specifies the string label for the AAppppllyy button.  The default
               for this resource depends on the locale.  In the C locale the
               default is "Apply".

     XXmmNNccaanncceellCCaallllbbaacckk
               Specifies the list of callbacks called when the user activates
               the CCaanncceell button.  The callback reason is XXmmCCRR__CCAANNCCEELL.

     XXmmNNccaanncceellLLaabbeellSSttrriinngg
               Specifies the string label for the CCaanncceell button.  The default
               for this resource depends on the locale.  In the C locale the
               default is "Cancel".

     XXmmNNcchhiillddPPllaacceemmeenntt
               Specifies the placement of the work area child.  The possible
               values are:

                 ++oo  XXmmPPLLAACCEE__AABBOOVVEE__SSEELLEECCTTIIOONN-places the work area child above
                    the Text area

                 ++oo  XXmmPPLLAACCEE__BBEELLOOWW__SSEELLEECCTTIIOONN-places the work area child below
                    the Text area

                 ++oo  XXmmPPLLAACCEE__TTOOPP-places the work area child above the List
                    area, and below a menubar, if one is present

     XXmmNNddiiaallooggTTyyppee
               Determines the set of SelectionBox children widgets that are
               created and managed at initialization.  The following are pos-
               sible values:

                 ++oo  XXmmDDIIAALLOOGG__PPRROOMMPPTT-all standard children except the list and
                    list label are created, and all except the AAppppllyy button
                    are managed

                 ++oo  XXmmDDIIAALLOOGG__CCOOMMMMAANNDD-only the list, the selection label, and
                    the text field are created and managed

                 ++oo  XXmmDDIIAALLOOGG__SSEELLEECCTTIIOONN-all standard children are created and
                    managed

                 ++oo  XXmmDDIIAALLOOGG__FFIILLEE__SSEELLEECCTTIIOONN-all standard children are created


   1-632






                                                           XmSelectionBox(3X)


                    and managed

                 ++oo  XXmmDDIIAALLOOGG__WWOORRKK__AARREEAA-all standard children are created, and
                    all except the AAppppllyy button are managed
               If the parent of the SelectionBox is a DialogShell, the
               default is XXmmDDIIAALLOOGG__SSEELLEECCTTIIOONN; otherwise, the default is
               XXmmDDIIAALLOOGG__WWOORRKK__AARREEAA.  XXmmCCrreeaatteePPrroommppttDDiiaalloogg and XXmmCCrreeaatteeSSeelleecc--
               ttiioonnDDiiaalloogg set and append this resource to the creation
               _a_r_g_l_i_s_t supplied by the application.  This resource cannot be
               modified after creation.

     XXmmNNhheellppLLaabbeellSSttrriinngg
               Specifies the string label for the HHeellpp button.  The default
               for this resource depends on the locale.  In the C locale the
               default is "Help".

     XXmmNNlliissttIItteemmss
               Specifies the items in the SelectionBox list.  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tIItteemmCCoouunntt
               Specifies the number of items in the SelectionBox list.  The
               value must not be negative.

     XXmmNNlliissttLLaabbeellSSttrriinngg
               Specifies the string label to appear above the SelectionBox
               list containing the selection items.  The default for this
               resource depends on the locale.  In the C locale the default
               is "Items" unless XXmmNNddiiaallooggTTyyppee is XXmmDDIIAALLOOGG__PPRROOMMPPTT; in that
               case the default is NULL.

     XXmmNNlliissttVViissiibblleeIItteemmCCoouunntt
               Specifies the number of items displayed in the SelectionBox
               list.  The value must be greater than 0 unless XXmmNNddiiaallooggTTyyppee
               is XXmmDDIIAALLOOGG__PPRROOMMPPTT; in that case the value is always 0.  The
               default is dynamic based on the height of the list.

     XXmmNNmmiinniimmiizzeeBBuuttttoonnss
               Sets the buttons to the width of the widest button and height
               of the tallest button if False.  If True, button width and
               height are not modified.

     XXmmNNmmuussttMMaattcchh
               Specifies whether the selection widget should check if the
               user's selection in the text edit field has an exact match in
               the SelectionBox list when the OOKK button is activated.  If the
               selection does not have an exact match, and XXmmNNmmuussttMMaattcchh is
               True, the XXmmNNnnooMMaattcchhCCaallllbbaacckk callbacks are called.  If the
               selection does have an exact match or if XXmmNNmmuussttMMaattcchh is
               False, XXmmNNookkCCaallllbbaacckk callbacks are called.

     XXmmNNnnooMMaattcchhCCaallllbbaacckk


   1-633






   XmSelectionBox(3X)


               Specifies the list of callbacks called when the user makes a
               selection from the text edit field that does not have an exact
               match with any of the items in the list box.  The callback
               reason is XXmmCCRR__NNOO__MMAATTCCHH.  Callbacks in this list are called
               only if XXmmNNmmuussttMMaattcchh is true.

     XXmmNNookkCCaallllbbaacckk
               Specifies the list of callbacks called when the user activates
               the OOKK button.  The callback reason is XXmmCCRR__OOKK.  If the selec-
               tion text does not match a list item, and XXmmNNmmuussttMMaattcchh is
               True, the XXmmNNnnooMMaattcchhCCaallllbbaacckk callbacks are called instead.

     XXmmNNookkLLaabbeellSSttrriinngg
               Specifies the string label for the OOKK button.  The default for
               this resource depends on the locale.  In the C locale the
               default is "OK".

     XXmmNNsseelleeccttiioonnLLaabbeellSSttrriinngg
               Specifies the string label for the selection text edit field.
               The default for this resource depends on the locale.  In the C
               locale the default is "Selection".

     XXmmNNtteexxttAAcccceelleerraattoorrss
               Specifies translations added to the Text widget child of the
               SelectionBox.  The default includes bindings for the up and
               down keys for auto selection of list items.  This resource is
               ignored if XXmmNNaacccceelleerraattoorrss is initialized to a nondefault
               value.

     XXmmNNtteexxttCCoolluummnnss
               Specifies the number of columns in the Text widget.  The value
               must be greater than 0.

     XXmmNNtteexxttSSttrriinngg
               Specifies the text in the text edit selection field.

     Inherited Resources

     SelectionBox inherits behavior and resources from the following superc-
     lasses.  For a complete description of each resource, refer to the man
     page for that superclass.
                             XXmmBBuulllleettiinnBBooaarrdd 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
   _________________________________________________________________________________
   XmNallowOverlap       XmCAllowOverlap      Boolean          True           CSG
   XmNautoUnmanage       XmCAutoUnmanage      Boolean          True           CG
   XmNbuttonFontList     XmCButtonFontList    XmFontList       dynamic        CSG
   XmNcancelButton       XmCWidget            Widget           dynamic        SG
   XmNdefaultButton      XmCWidget            Widget           dynamic        SG
   XmNdefaultPosition    XmCDefaultPosition   Boolean          True           CSG
   XmNdialogStyle        XmCDialogStyle       unsigned char    dynamic        CSG
   XmNdialogTitle        XmCDialogTitle       XmString         NULL           CSG
   XmNfocusCallback      XmCCallback          XtCallbackList   NULL           C
   XmNlabelFontList      XmCLabelFontList     XmFontList       dynamic        CSG


   1-634






                                                           XmSelectionBox(3X)


   XmNmapCallback        XmCCallback          XtCallbackList   NULL           C
   XmNmarginHeight       XmCMarginHeight      Dimension        10             CSG
   XmNmarginWidth        XmCMarginWidth       Dimension        10             CSG
   XmNnoResize           XmCNoResize          Boolean          False          CSG
   XmNresizePolicy       XmCResizePolicy      unsigned char    XmRESIZE_ANY   CSG
   XmNshadowType         XmCShadowType        unsigned char    XmSHADOW_OUT   CSG
   XmNtextFontList       XmCTextFontList      XmFontList       dynamic        CSG
   XmNtextTranslations   XmCTranslations      XtTranslations   NULL           C
   XmNunmapCallback      XmCCallback          XtCallbackList   NULL           C
                                        XXmmMMaannaaggeerr 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
   XmNhighlightPixmap      XmCHighlightPixmap      Pixmap              dynamic                CSG
   XmNinitialFocus         XmCInitialFocus         Widget              dynamic                CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType    XmTAB_GROUP            CSG
   XmNshadowThickness      XmCShadowThickness      Dimension           dynamic                CSG
   XmNstringDirection      XmCStringDirection      XmStringDirection   dynamic                CG
   XmNtopShadowColor       XmCTopShadowColor       Pixel               dynamic                CSG
   XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap              dynamic                CSG
   XmNtraversalOn          XmCTraversalOn          Boolean             True                   CSG
   XmNunitType             XmCUnitType             unsigned char       dynamic                CSG
   XmNuserData             XmCUserData             XtPointer           NULL                   CSG
                              CCoommppoossiitte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
      ______________________________________________________________________
      XmNchildren         XmCReadOnly         WidgetList    NULL      G
      XmNinsertPosition   XmCInsertPosition   XtOrderProc   NULL      CSG
      XmNnumChildren      XmCReadOnly         Cardinal      0         G
                                                 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                N/A
   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


   1-635






   XmSelectionBox(3X)


   XmNy                            XmCPosition                     Position         0                      CSG

     Callback Information

     A pointer to the following structure is passed to each callback:
     ttyyppeeddeeff ssttrruucctt
     {{
       iinntt          _r_e_a_s_o_n;;
       XXEEvveenntt       * _e_v_e_n_t;;
       XXmmSSttrriinngg     _v_a_l_u_e;;
       iinntt          _l_e_n_g_t_h;;
     }} XXmmSSeelleeccttiioonnBBooxxC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

     _v_a_l_u_e  Indicates the XXmmSSttrriinngg value selected by the user from the Selec-
            tionBox list or entered into the SelectionBox text field

     _l_e_n_g_t_h Indicates the size in bytes of the XXmmSSttrriinngg value

     Translations

     XmSelectionBox inherits translations from XmBulletinBoard.

     Accelerators

     The XXmmNNtteexxttAAcccceelleerraattoorrss are added to the Text descendant of XmSelection-
     Box.  The default accelerators are listed below.  These accelerators may
     not directly correspond to a translation table.
     KKUUpp::           SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((00))
     KKDDoowwnn::         SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((11))
     KKBBeeggiinnDDaattaa::    SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((22))
     KKEEnnddDDaattaa::      SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((33))
     KKRReessttoorree::      SSeelleeccttiioonnBBooxxRReessttoorree(())

     Action Routines

     The XmSelectionBox action routines are described below:

     SSeelleeccttiioonnBBooxxUUppOOrrDDoowwnn((00||11||22||33)):
               When called with a 0 argument, selects the previous item in
               the list and replaces the text with that item.  When called
               with a 1 argument, selects the next item in the list and
               replaces the text with that item.  When called with a 2 argu-
               ment, selects the first item in the list and replaces the text
               with that item.  When called with a 3 argument, selects the
               last item in the list and replaces the text with that item.

     SSeelleeccttiioonnBBooxxRReessttoorree(()):
               Replaces the text value with the list selection.  If no item




   1-636






                                                           XmSelectionBox(3X)


               in the list is selected, clears the text.

     Additional Behavior

     The SelectionBox widget has the additional behavior described below:

     MMAAnnyy KKCCaanncceell:
               Calls the activate callbacks for the cancel button if it is
               sensitive.  If no cancel button exists and the parent of the
               SelectionBox is a manager, passes the event to the parent.

     KKAAccttiivvaattee:
               Calls the activate callbacks for the button with the keyboard
               focus.  If no button has the keyboard focus, calls the
               activate callbacks for the default button if it is sensitive.
               In a List widget or single-line Text widget, the List or Text
               action associated with KKAAccttiivvaattee is called before the Selec-
               tionBox actions associated with KKAAccttiivvaattee.  In a multi-line
               Text widget, any KKAAccttiivvaattee event except KKEEnntteerr calls the Text
               action associated with KKAAccttiivvaattee, then the SelectionBox
               actions associated with KKAAccttiivvaattee.  If no button has the
               focus, no default button exists, and the parent of the Selec-
               tionBox is a manager, passes the event to the parent.

     <<OOKK BBuuttttoonn AAccttiivvaatteedd>>:
               If XXmmNNmmuussttMMaattcchh is True and the text does not match an item in
               the file list, calls the XXmmNNnnooMMaattcchhCCaallllbbaacckk callbacks with
               reason XXmmCCRR__NNOO__MMAATTCCHH.  Otherwise, calls the XXmmNNookkCCaallllbbaacckk
               callbacks with reason XXmmCCRR__OOKK.

     <<AAppppllyy BBuuttttoonn AAccttiivvaatteedd>>:
               Calls the XXmmNNaappppllyyCCaallllbbaacckk callbacks with reason XXmmCCRR__AAPPPPLLYY.

     <<CCaanncceell BBuuttttoonn AAccttiivvaatteedd>>:
               Calls the XXmmNNccaanncceellCCaallllbbaacckk callbacks with reason XXmmCCRR__CCAANNCCEELL.

     <<HHeellpp BBuuttttoonn AAccttiivvaatteedd>>:
               Calls the XXmmNNhheellppCCaallllbbaacckk callbacks with reason XXmmCCRR__HHEELLPP.

     <<MMaappWWiinnddooww>>:
               Calls the callbacks for XXmmNNmmaappCCaallllbbaacckk if the SelectionBox is
               a child of a Dialog shell.

     <<UUnnmmaappWWiinnddooww>>:
               Calls the callbacks for XXmmNNuunnmmaappCCaallllbbaacckk if the SelectionBox
               is the child of a DialogShell.

     Virtual Bindings

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





   1-637






   XmSelectionBox(3X)


   RELATED INFORMATION
     CCoommppoossiittee((33XX)), CCoonnssttrraaiinntt((33XX)), CCoorree((33XX)), XXmmBBuulllleettiinnBBooaarrdd((33XX)),
     XXmmCCrreeaatteeSSeelleeccttiioonnBBooxx((33XX)), XXmmCCrreeaatteeSSeelleeccttiioonnDDiiaalloogg((33XX)),
     XXmmCCrreeaatteePPrroommppttDDiiaalloogg((33XX)), XXmmMMaannaaggeerr((33XX)), and XXmmSSeelleeccttiioonnBBooxxGGeettCChhiilldd((33XX)).




















































   1-638






                                                   XmSelectionBoxGetChild(3X)



   NAME
     XXmmSSeelleeccttiioonnBBooxxGGeettCChhiilldd-A SelectionBox function that is used to access a
     component

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSeelleeccttiiooBB..hh>>
     WWiiddggeett XXmmSSeelleeccttiioonnBBooxxGGeettCChhiilldd ((_w_i_d_g_e_t, _c_h_i_l_d))
          WWiiddggeett    _w_i_d_g_e_t;;
          uunnssiiggnneedd cchhaarr_c_h_i_l_d;;

   DESCRIPTION
     XXmmSSeelleeccttiioonnBBooxxGGeettCChhiilldd is used to access a component within a Selection-
     Box.  The parameters given to the function are the SelectionBox widget
     and a value indicating which component to access.

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

     _c_h_i_l_d  Specifies a component within the SelectionBox.  The following are
            legal values for this parameter:

              ++oo  XXmmDDIIAALLOOGG__AAPPPPLLYY__BBUUTTTTOONN

              ++oo  XXmmDDIIAALLOOGG__CCAANNCCEELL__BBUUTTTTOONN

              ++oo  XXmmDDIIAALLOOGG__DDEEFFAAUULLTT__BBUUTTTTOONN

              ++oo  XXmmDDIIAALLOOGG__HHEELLPP__BBUUTTTTOONN

              ++oo  XXmmDDIIAALLOOGG__LLIISSTT

              ++oo  XXmmDDIIAALLOOGG__LLIISSTT__LLAABBEELL

              ++oo  XXmmDDIIAALLOOGG__OOKK__BBUUTTTTOONN

              ++oo  XXmmDDIIAALLOOGG__SSEELLEECCTTIIOONN__LLAABBEELL

              ++oo  XXmmDDIIAALLOOGG__SSEEPPAARRAATTOORR

              ++oo  XXmmDDIIAALLOOGG__TTEEXXTT

              ++oo  XXmmDDIIAALLOOGG__WWOORRKK__AARREEAA

     For a complete definition of SelectionBox and its associated resources,
     see XXmmSSeelleeccttiioonnBBooxx((33XX)).

   RETURN VALUE
     Returns the widget ID of the specified SelectionBox component.  An
     application should not assume that the returned widget will be of any
     particular class.






   1-639






   XmSelectionBoxGetChild(3X)


   RELATED INFORMATION
     XXmmSSeelleeccttiioonnBBooxx((33XX)).






















































   1-640






                                                              XmSeparator(3X)



   NAME
     XXmmSSeeppaarraattoorr-The Separator widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSeeppaarraattoorr..hh>>

   DESCRIPTION
     Separator is a primitive widget that separates items in a display.
     Several different line drawing styles are provided, as well as horizon-
     tal or vertical orientation.

     The Separator line drawing is automatically centered within the height
     of the widget for a horizontal orientation and centered within the width
     of the widget for a vertical orientation.  An XXttSSeettVVaalluueess with a new
     XXmmNNsseeppaarraattoorrTTyyppee resizes the widget to its minimal height (for horizon-
     tal orientation) or its minimal width (for vertical orientation) unless
     height or width is explicitly set in the XXttSSeettVVaalluueess call.

     Separator does not draw shadows around the separator.  The Primitive
     resource XXmmNNsshhaaddoowwTThhiicckknneessss is used for the Separator's thickness when
     XXmmNNsseeppaarraattoorrTTyyppee is XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN, XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN__DDAASSHH,
     XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT, or XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT__DDAASSHH.

     Separator does not highlight and allows no traversing.  The primitive
     resource XXmmNNttrraavveerrssaallOOnn is forced to False.

     The XXmmNNsseeppaarraattoorrTTyyppee of XXmmNNOO__LLIINNEE provides an escape to the application
     programmer who needs a different style of drawing.  A pixmap the height
     of the widget can be created and used as the background pixmap by build-
     ing an argument list using the XXmmNNbbaacckkggrroouunnddPPiixxmmaapp argument type as
     defined by CCoorree.  Whenever the widget is redrawn, its background is
     displayed containing the desired separator drawing.

     Classes

     Separator 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mSSeeppaarraattoorrWWiiddggeettCCllaassss.

     The class name is XXmmSSeeppaarraattoorr.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),


   1-641






   XmSeparator(3X)


     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mSSeeppaarraattoorr 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
   _________________________________________________________________________________
   XmNmargin          XmCMargin          Dimension       0                    CSG
   XmNorientation     XmCOrientation     unsigned char   XmHORIZONTAL         CSG
   XmNseparatorType   XmCSeparatorType   unsigned char   XmSHADOW_ETCHED_IN   CSG

     XXmmNNmmaarrggiinn For horizontal orientation, specifies the space on the left
               and right sides between the border of the Separator and the
               line drawn.  For vertical orientation, specifies the space on
               the top and bottom between the border of the Separator and the
               line drawn.

     XXmmNNoorriieennttaattiioonn
               Displays Separator vertically or horizontally.  This resource
               can have values of XXmmVVEERRTTIICCAALL and XXmmHHOORRIIZZOONNTTAALL.

     XXmmNNsseeppaarraattoorrTTyyppee
               Specifies the type of line drawing to be done in the Separator
               widget.

                 ++oo  XXmmSSIINNGGLLEE__LLIINNEE-single line.

                 ++oo  XXmmDDOOUUBBLLEE__LLIINNEE-double line.

                 ++oo  XXmmSSIINNGGLLEE__DDAASSHHEEDD__LLIINNEE-single-dashed line.

                 ++oo  XXmmDDOOUUBBLLEE__DDAASSHHEEDD__LLIINNEE-double-dashed line.

                 ++oo  XXmmNNOO__LLIINNEE-no line.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN-a line whose shadows give the effect
                    of a line etched into the window.  The thickness of the
                    line is equal to the value of XXmmNNsshhaaddoowwTThhiicckknneessss.  For
                    horizontal orientation, the top shadow is drawn in
                    XXmmNNttooppSShhaaddoowwCCoolloorr and the bottom shadow is drawn in
                    XXmmNNbboottttoommSShhaaddoowwCCoolloorr.  For vertical orientation, the left
                    edge is drawn in XXmmNNttooppSShhaaddoowwCCoolloorr and the right edge is
                    drawn in XXmmNNbboottttoommSShhaaddoowwCCoolloorr.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT-a line whose shadows give the effect
                    of an etched line coming out of the window.  The thick-
                    ness of the line is equal to the value of XXmmNNsshhaaddoowwTThhiicckk--
                    nneessss.  For horizontal orientation, the top shadow is
                    drawn in XXmmNNbboottttoommSShhaaddoowwCCoolloorr and the bottom shadow is
                    drawn in XXmmNNttooppSShhaaddoowwCCoolloorr.  For vertical orientation,
                    the left edge is drawn in XXmmNNbboottttoommSShhaaddoowwCCoolloorr and the
                    right edge is drawn in XXmmNNttooppSShhaaddoowwCCoolloorr.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN__DDAASSHH-identical to XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN
                    except a series of lines creates a dashed line.



   1-642






                                                              XmSeparator(3X)


                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT__DDAASSHH-identical to XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT
                    except a series of lines creates a dashed line.

     Inherited Resources

     Separator inherits behavior and resources from the following superc-
     lasses.  For a complete description of each resource, refer to the man
     page for that superclass.
                                       XXm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          2                      CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic                CSG
   XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap             dynamic                CSG
   XmNtraversalOn          XmCTraversalOn          Boolean            False                  G
   XmNunitType             XmCUnitType             unsigned char      dynamic                CSG
   XmNuserData             XmCUserData             XtPointer          NULL                   CSG
                                                 CCoorree RReessoouurrccee SSeett
   NNaammee                            CCllaassss                           TTyyppee             DDeeffaauulltt                AAcccceessss
   ______________________________________________________________________________________________________________
   XmNaccelerators                 XmCAccelerators                 XtAccelerators   dynamic                CSG
   XmNancestorSensitive            XmCSensitive                    Boolean          dynamic                G
   XmNbackground                   XmCBackground                   Pixel            dynamic                CSG
   XmNbackgroundPixmap             XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
   XmNborderColor                  XmCBorderColor                  Pixel            XtDefaultForeground    CSG
   XmNborderPixmap                 XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
   XmNborderWidth                  XmCBorderWidth                  Dimension        0                      CSG
   XmNcolormap                     XmCColormap                     Colormap         dynamic                CG
   XmNdepth                        XmCDepth                        int              dynamic                CG
   XmNdestroyCallback              XmCCallback                     XtCallbackList   NULL                   C
   XmNheight                       XmCHeight                       Dimension        dynamic                CSG
   XmNinitialResourcesPersistent   XmCInitialResourcesPersistent   Boolean          True                   C
   XmNmappedWhenManaged            XmCMappedWhenManaged            Boolean          True                   CSG
   XmNscreen                       XmCScreen                       Screen *         dynamic                CG
   XmNsensitive                    XmCSensitive                    Boolean          True                   CSG
   XmNtranslations                 XmCTranslations                 XtTranslations   dynamic                CSG
   XmNwidth                        XmCWidth                        Dimension        dynamic                CSG
   XmNx                            XmCPosition                     Position         0                      CSG
   XmNy                            XmCPosition                     Position         0                      CSG

     Translations

     There are no translations for XmSeparator.




   1-643






   XmSeparator(3X)


   RELATED INFORMATION
     CCoorree((33XX)), XXmmCCrreeaatteeSSeeppaarraattoorr((33XX)), and XXmmPPrriimmiittiivvee((33XX)).






















































   1-644






                                                        XmSeparatorGadget(3X)



   NAME
     XXmmSSeeppaarraattoorrGGaaddggeett-The SeparatorGadget widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//SSeeppaarraattooGG..hh>>

   DESCRIPTION
     SeparatorGadget separates items in a display.  Several line drawing
     styles are provided, as well as horizontal or vertical orientation.

     Lines drawn within the SeparatorGadget are automatically centered within
     the height of the gadget for a horizontal orientation and centered
     within the width of the gadget for a vertical orientation.  An XXttSSeett--
     VVaalluueess with a new XXmmNNsseeppaarraattoorrTTyyppee resizes the widget to its minimal
     height (for horizontal orientation) or its minimal width (for vertical
     orientation) unless height or width is explicitly set in the XXttSSeettVVaalluueess
     call.

     SeparatorGadget does not draw shadows around the separator.  The Gadget
     resource XXmmNNsshhaaddoowwTThhiicckknneessss is used for the SeparatorGadget's thickness
     when XXmmNNsseeppaarraattoorrTTyyppee is XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN, XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN__DDAASSHH,
     XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT, or XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT__DDAASSHH.

     SeparatorGadget does not highlight and allows no traversing.  The Gadget
     resource XXmmNNttrraavveerrssaallOOnn is forced to False.

     Classes

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

     The class pointer is xxmmSSeeppaarraattoorrGGaaddggeettCCllaassss.

     The class name is XXmmSSeeppaarraattoorrGGaaddggeett.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                            XXmmSSeeppaarraattoorrG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
   _________________________________________________________________________________
   XmNmargin          XmCMargin          Dimension       0                    CSG
   XmNorientation     XmCOrientation     unsigned char   XmHORIZONTAL         CSG


   1-645






   XmSeparatorGadget(3X)


   XmNseparatorType   XmCSeparatorType   unsigned char   XmSHADOW_ETCHED_IN   CSG

     XXmmNNmmaarrggiinn For horizontal orientation, specifies the space on the left
               and right sides between the border of SeparatorGadget and the
               line drawn.  For vertical orientation, specifies the space on
               the top and bottom between the border of SeparatorGadget and
               the line drawn.

     XXmmNNoorriieennttaattiioonn
               Specifies whether SeparatorGadget is displayed vertically or
               horizontally.  This resource can have values of XXmmVVEERRTTIICCAALL and
               XXmmHHOORRIIZZOONNTTAALL.

     XXmmNNsseeppaarraattoorrTTyyppee
               Specifies the type of line drawing to be done in the Separator
               widget.

                 ++oo  XXmmSSIINNGGLLEE__LLIINNEE-single line.

                 ++oo  XXmmDDOOUUBBLLEE__LLIINNEE-double line.

                 ++oo  XXmmSSIINNGGLLEE__DDAASSHHEEDD__LLIINNEE-single-dashed line.

                 ++oo  XXmmDDOOUUBBLLEE__DDAASSHHEEDD__LLIINNEE-double-dashed line.

                 ++oo  XXmmNNOO__LLIINNEE-no line.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN-a line whose shadows give the effect
                    of a line etched into the window.  The thickness of the
                    line is equal to the value of XXmmNNsshhaaddoowwTThhiicckknneessss.  For
                    horizontal orientation, the top shadow is drawn in
                    XXmmNNttooppSShhaaddoowwCCoolloorr and the bottom shadow is drawn in
                    XXmmNNbboottttoommSShhaaddoowwCCoolloorr.  For vertical orientation, the left
                    edge is drawn in XXmmNNttooppSShhaaddoowwCCoolloorr and the right edge is
                    drawn in XXmmNNbboottttoommSShhaaddoowwCCoolloorr.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT-a line whose shadows give the effect
                    of an etched line coming out of the window.  The thick-
                    ness of the line is equal to the value of XXmmNNsshhaaddoowwTThhiicckk--
                    nneessss.  For horizontal orientation, the top shadow is
                    drawn in XXmmNNbboottttoommSShhaaddoowwCCoolloorr and the bottom shadow is
                    drawn in XXmmNNttooppSShhaaddoowwCCoolloorr.  For vertical orientation,
                    the left edge is drawn in XXmmNNbboottttoommSShhaaddoowwCCoolloorr and the
                    right edge is drawn in XXmmNNttooppSShhaaddoowwCCoolloorr.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN__DDAASSHH-identical to XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN
                    except a series of lines creates a dashed line.

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT__DDAASSHH-identical to XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT
                    except a series of lines creates a dashed line.






   1-646






                                                        XmSeparatorGadget(3X)


     Inherited Resources

     SeparatorGadget 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          2         CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic   G
   XmNtraversalOn          XmCTraversalOn          Boolean            False     G
   XmNunitType             XmCUnitType             unsigned char      dynamic   CSG
   XmNuserData             XmCUserData             XtPointer          NULL      CSG
                               RReeccttOObbjj RReessoouurrccee SSeett
       NNaammee                   CCllaassss            TTyyppee        DDeeffaauulltt   AAcccceessss
       ____________________________________________________________________
       XmNancestorSensitive   XmCSensitive     Boolean     dynamic   G
       XmNborderWidth         XmCBorderWidth   Dimension   0         CSG
       XmNheight              XmCHeight        Dimension   dynamic   CSG
       XmNsensitive           XmCSensitive     Boolean     True      CSG
       XmNwidth               XmCWidth         Dimension   dynamic   CSG
       XmNx                   XmCPosition      Position    0         CSG
       XmNy                   XmCPosition      Position    0         CSG
                               OObbjjeecctt RReessoouurrccee SSeett
       NNaammee                 CCllaassss         TTyyppee             DDeeffaauulltt   AAcccceessss
       ____________________________________________________________________
       XmNdestroyCallback   XmCCallback   XtCallbackList   NULL      C

     Behavior

     XmSeparatorGadget has no behavior.

   RELATED INFORMATION
     OObbjjeecctt((33XX)), RReeccttOObbjjeecctt((33XX)), XXmmCCrreeaatteeSSeeppaarraattoorrGGaaddggeett((33XX)), and
     XXmmGGaaddggeett((33XX)).















   1-647






   XmSetColorCalculation(3X)



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

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmCCoolloorrPPrroocc XXmmSSeettCCoolloorrCCaallccuullaattiioonn ((_c_o_l_o_r__p_r_o_c))
          XXmmCCoolloorrPPrroocc_c_o_l_o_r__p_r_o_c;;

   DESCRIPTION
     XXmmSSeettCCoolloorrCCaallccuullaattiioonn sets the procedure to calculate default colors.
     This procedure is used to calculate the foreground, top shadow, bottom
     shadow, and select colors on the basis of a given background color.  If
     called with an argument of NULL, it restores the default procedure used
     to calculate colors.

     _c_o_l_o_r__p_r_o_c
            Specifies the procedure to use for color calculation.

     Following is a description of the XXmmCCoolloorrPPrroocc type used by XXmmSSeettCCoolloorr--
     CCaallccuullaattiioonn:

     vvooiidd ((**_c_o_l_o_r__p_r_o_c)) ((_b_a_c_k_g_r_o_u_n_d__c_o_l_o_r, _f_o_r_e_g_r_o_u_n_d__c_o_l_o_r, _s_e_l_e_c_t__c_o_l_o_r, _t_o_p__s_h_a_d_o_w__c_o_l_o_r, _b_o_t_t_o_m__s_h_a_d_o_w__c_o_l_o_r))
          XXCCoolloorr    *_b_a_c_k_g_r_o_u_n_d__c_o_l_o_r;;
          XXCCoolloorr    *_f_o_r_e_g_r_o_u_n_d__c_o_l_o_r;;
          XXCCoolloorr    *_s_e_l_e_c_t__c_o_l_o_r;;
          XXCCoolloorr    *_t_o_p__s_h_a_d_o_w__c_o_l_o_r;;
          XXCCoolloorr    *_b_o_t_t_o_m__s_h_a_d_o_w__c_o_l_o_r;;

     Specifies the procedure used to calculate default colors.  The procedure
     is passed a pointer to an XXCCoolloorr structure representing the background
     color.  The _p_i_x_e_l, _r_e_d, _g_r_e_e_n, and _b_l_u_e members of this structure are
     filled in with values that are valid for the current colormap.

     The procedure is passed pointers to XXCCoolloorr structures representing the
     foreground, select, top shadow, and bottom shadow colors to be calcu-
     lated.  The procedure calculates and fills in the _r_e_d, _g_r_e_e_n, and _b_l_u_e
     members of these structures.  The procedure should not allocate color
     cells for any of these colors.

     _b_a_c_k_g_r_o_u_n_d__c_o_l_o_r
            Specifies the background color.

     _f_o_r_e_g_r_o_u_n_d__c_o_l_o_r
            Specifies the foreground color to be calculated.

     _s_e_l_e_c_t__c_o_l_o_r
            Specifies the select color to be calculated.

     _t_o_p__s_h_a_d_o_w__c_o_l_o_r
            Specifies the top shadow color to be calculated.

     _b_o_t_t_o_m__s_h_a_d_o_w__c_o_l_o_r


   1-648






                                                    XmSetColorCalculation(3X)


            Specifies the bottom shadow color to be calculated.

   RETURN VALUE
     Returns the color calculation procedure that was used at the time this
     routine was called.

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
















































   1-649






   XmSetFontUnit(3X)



   NAME
     XXmmSSeettFFoonnttUUnniitt-A function that sets the font unit value for a display

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSeettFFoonnttUUnniitt ((_d_i_s_p_l_a_y, _f_o_n_t__u_n_i_t__v_a_l_u_e))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          iinntt       _f_o_n_t__u_n_i_t__v_a_l_u_e;;

   DESCRIPTION
     XXmmSSeettFFoonnttUUnniitt provides an external function to initialize font unit
     values.  Applications may want to specify resolution-independent data
     based on a global font size. See the XXmmNNuunniittTTyyppee resource description in
     the manual pages for XXmmGGaaddggeett, XXmmMMaannaaggeerr, and XXmmPPrriimmiittiivvee for more
     information on resolution independence.

     This function sets the font units for all screens on the display.
     XXmmSSeettFFoonnttUUnniitt is obsolete and exists for compatibility with previous
     releases.  Instead of using this function, provide initial values or
     call XXttSSeettVVaalluueess for 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.

     _d_i_s_p_l_a_y     Defines the display for which this font unit value is to be
                 applied.

     _f_o_n_t__u_n_i_t__v_a_l_u_e
                 Specifies the value to be used for both horizontal and vert-
                 ical font units in the conversion calculations.

   RELATED INFORMATION
     XXmmCCoonnvveerrttUUnniittss((33XX)), XXmmSSeettFFoonnttUUnniittss((33XX)), XXmmGGaaddggeett((33XX)), XXmmMMaannaaggeerr((33XX)),
     XXmmPPrriimmiittiivvee((33XX)), and XXmmSSccrreeeenn((33XX)).























   1-650






                                                           XmSetFontUnits(3X)



   NAME
     XXmmSSeettFFoonnttUUnniittss-A function that sets the font unit value for a display

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSeettFFoonnttUUnniittss ((_d_i_s_p_l_a_y, _h__v_a_l_u_e, _v__v_a_l_u_e))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          iinntt       _h__v_a_l_u_e;;
          iinntt       _v__v_a_l_u_e;;

   DESCRIPTION
     XXmmSSeettFFoonnttUUnniittss provides an external function to initialize font unit
     values.  Applications may want to specify resolution-independent data
     based on a global font size.  This function must be called before any
     widgets with resolution-independent data are created.  See the XXmmNNuunniitt--
     TTyyppee resource description in the manual pages for XXmmGGaaddggeett, XXmmMMaannaaggeerr,
     and XXmmPPrriimmiittiivvee for more information on resolution independence.

     This function sets the font units for all screens on the display.
     XXmmSSeettFFoonnttUUnniittss is obsolete and exists for compatibility with previous
     releases.  Instead of using this function, provide initial values or
     call XXttSSeettVVaalluueess for 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.

     _d_i_s_p_l_a_y     Defines the display for which this font unit value is to be
                 applied.

     _h__v_a_l_u_e     Specifies the value to be used for horizontal units in the
                 conversion calculations.

     _h__v_a_l_u_e     Specifies the value to be used for vertical units in the
                 conversion calculations.

   RELATED INFORMATION
     XXmmCCoonnvveerrttUUnniittss((33XX)), XXmmSSeettFFoonnttUUnniitt((33XX)), XXmmGGaaddggeett((33XX)), XXmmMMaannaaggeerr((33XX)),
     XXmmPPrriimmiittiivvee((33XX)), and XXmmSSccrreeeenn((33XX)).



















   1-651






   XmSetMenuCursor(3X)



   NAME
     XXmmSSeettMMeennuuCCuurrssoorr-A function that modifies the menu cursor for a client

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSeettMMeennuuCCuurrssoorr ((_d_i_s_p_l_a_y, _c_u_r_s_o_r_I_d))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          CCuurrssoorr    _c_u_r_s_o_r_I_d;;

   DESCRIPTION
     XXmmSSeettMMeennuuCCuurrssoorr programmatically modifies the menu cursor for a client;
     after the cursor has been created by the client, this function registers
     the cursor with the menu system.  After calling this function, the
     specified cursor is displayed whenever this client displays a Motif menu
     on the indicated display.  The client can then specify different cursors
     on different displays.

     This function sets the menu cursor for all screens on the display.
     XXmmSSe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, provide initial values or
     call XXttSSe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 to which the cursor is to be associated

     _c_u_r_s_o_r_I_d
            Specifies the XX cursor ID

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


























   1-652






                                                       XmSetProtocolHooks(3X)



   NAME
     XXmmSSeettPPrroottooccoollHHooookkss-A VendorShell function that allows pre and post
     actions to be executed when a protocol message is received from MWM

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//PPrroottooccoollss..hh>>
     vvooiidd XXmmSSeettPPrroottooccoollHHooookkss ((_s_h_e_l_l, _p_r_o_p_e_r_t_y, _p_r_o_t_o_c_o_l, _p_r_e_h_o_o_k, _p_r_e__c_l_o_s_u_r_e,
               _p_o_s_t_h_o_o_k, _p_o_s_t__c_l_o_s_u_r_e))
          WWiiddggeett         _s_h_e_l_l;;
          AAttoomm           _p_r_o_p_e_r_t_y;;
          AAttoomm           _p_r_o_t_o_c_o_l;;
          XXttCCaallllbbaacckkPPrroocc _p_r_e_h_o_o_k;;
          XXttPPooiinntteerr      _p_r_e__c_l_o_s_u_r_e;;
          XXttCCaallllbbaacckkPPrroocc _p_o_s_t_h_o_o_k;;
          XXttPPooiinntteerr      _p_o_s_t__c_l_o_s_u_r_e;;
     vvooiidd XXmmSSeettWWMMPPrroottooccoollHHooookkss ((_s_h_e_l_l, _p_r_o_t_o_c_o_l, _p_r_e_h_o_o_k, _p_r_e__c_l_o_s_u_r_e,
               _p_o_s_t_h_o_o_k, _p_o_s_t__c_l_o_s_u_r_e))
          WWiiddggeett         _s_h_e_l_l;;
          AAttoomm           _p_r_o_t_o_c_o_l;;
          XXttCCaallllbbaacckkPPrroocc _p_r_e_h_o_o_k;;
          XXttPPooiinntteerr      _p_r_e__c_l_o_s_u_r_e;;
          XXttCCaallllbbaacckkPPrroocc _p_o_s_t_h_o_o_k;;
          XXttPPooiinntteerr      _p_o_s_t__c_l_o_s_u_r_e;;

   DESCRIPTION
     XXmmSSeettPPrroottooccoollHHooookkss is used by shells that want to have pre and post
     actions executed when a protocol message is received from MWM.  Since
     there is no guaranteed ordering in execution of event handlers or call-
     back lists, this allows the shell to control the flow while leaving the
     protocol manager structures opaque.

     XXmmSSeettWWMMPPrroottooccoollHHooookkss is a convenience interface.  It calls XXmmSSeettPPrroottoo--
     ccoollHHooookkss with the property value set to the atom returned by interning
     WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l     Specifies the widget with which the protocol property is asso-
               ciated

     _p_r_o_p_e_r_t_y  Specifies the protocol property

     _p_r_o_t_o_c_o_l  Specifies the protocol atom (or an int cast to Atom)

     _p_r_e_h_o_o_k   Specifies the procedure to call before calling entries on the
               client callback-list

     _p_r_e__c_l_o_s_u_r_e
               Specifies the client data to be passed to the prehook when it
               is invoked

     _p_o_s_t_h_o_o_k  Specifies the procedure to call after calling entries on the
               client callback-list



   1-653






   XmSetProtocolHooks(3X)


     _p_o_s_t__c_l_o_s_u_r_e
               Specifies the client data to be passed to the posthook when it
               is invoked

     For a complete definition of VendorShell and its associated resources,
     see VVeennddoorrSShheellll((33XX)).

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmIInntteerrnnAAttoomm((33XX)), and XXmmSSeettWWMMPPrroottooccoollHHooookkss((33XX)).















































   1-654






                                                     XmSetWMProtocolHooks(3X)



   NAME
     XXmmSSeettWWMMPPrroottooccoollHHooookkss-A VendorShell convenience interface that allows pre
     and post actions to be executed when a protocol message is received from
     the window manager

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//PPrroottooccoollss..hh>>
     vvooiidd XXmmSSeettWWMMPPrroottooccoollHHooookkss ((_s_h_e_l_l, _p_r_o_t_o_c_o_l, _p_r_e_h_o_o_k, _p_r_e__c_l_o_s_u_r_e, _p_o_s_t_h_o_o_k, _p_o_s_t__c_l_o_s_u_r_e))
          WWiiddggeett      _s_h_e_l_l;;
          AAttoomm        _p_r_o_t_o_c_o_l;;
          XXttCCaallllbbaacckkPPrroocc_p_r_e_h_o_o_k;;
          XXttPPooiinntteerr   _p_r_e__c_l_o_s_u_r_e;;
          XXttCCaallllbbaacckkPPrroocc_p_o_s_t_h_o_o_k;;
          XXttPPooiinntteerr   _p_o_s_t__c_l_o_s_u_r_e;;

   DESCRIPTION
     XXmmSSeettWWMMPPrroottooccoollHHooookkss is a convenience interface.  It calls XXmmSSeettPPrroottoo--
     ccoollHHooookkss with the property value set to the atom returned by interning
     WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l     Specifies the widget with which the protocol property is asso-
               ciated

     _p_r_o_t_o_c_o_l  Specifies the protocol atom (or an int cast to Atom)

     _p_r_e_h_o_o_k   Specifies the procedure to call before calling entries on the
               client callback-list

     _p_r_e__c_l_o_s_u_r_e
               Specifies the client data to be passed to the prehook when it
               is invoked

     _p_o_s_t_h_o_o_k  Specifies the procedure to call after calling entries on the
               client callback-list

     _p_o_s_t__c_l_o_s_u_r_e
               Specifies the client data to be passed to the posthook when it
               is invoked

     For a complete definition of VendorShell and its associated resources,
     see VVeennddoorrSShheellll((33XX)).

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmIInntteerrnnAAttoomm((33XX)), and XXmmSSeettPPrroottooccoollHHooookkss((33XX)).










   1-655






   XmString(3X)



   NAME
     XXmmSSttrriinngg-Data type for a compound string

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

   DESCRIPTION
     XXmmSSttrriinngg is the data type for a compound string.  Compound strings
     include one or more segments, each of which may contain a font list ele-
     ment tag, string direction, and text component.  When a compound string
     is displayed, the font list element tag and the direction are used to
     determine how to display the text.  Whenever a font list element tag is
     set to XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG the text is handled as a locale text seg-
     ment.

     Calling XXttGGeettVVaalluueess for a resource whose type is XmString yields a copy
     of the compound string resource value.  The application is responsible
     for using XXmmSSttrriinnggFFrreeee to free the memory allocated for the copy.

     Refer to the XXmmFFoonnttLLiisstt man page for a description of the algorithm that
     associates the font list element tag of a compound string segment with a
     font list entry in a font list.

     The compound string interface consists of the routines listed under
     "Related Information."

   RELATED INFORMATION
     XXmmSSttrriinnggBBaasseelliinnee((33XX)), XXmmSSttrriinnggBByytteeCCoommppaarree((33XX)), XXmmSSttrriinnggCCoommppaarree((33XX)),
     XXmmSSttrriinnggCCoonnccaatt((33XX)), XXmmSSttrriinnggCCooppy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)), XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd((33XX)),
     XXmmSSttrriinnggCCrreeaatteeSSiimmppllee((33XX)), XXmmSSttrriinnggDDiirreeccttiioonn((33XX)),
     XXmmSSttrriinnggDDiirreeccttiioonnCCrreeaattee((33XX)), XXmmSSttrriinnggDDrraaww((33XX)), XXmmSSttrriinnggDDrraawwIImmaaggee((33XX)),
     XXmmSSttrriinnggDDrraawwUUnnddeerrlliinnee((33XX)), XXmmSSttrriinnggEEmmppttyy((33XX)), XXmmSSttrriinnggEExxtteenntt((33XX)),
     XXmmSSttrriinnggFFrreeee((33XX)), XXmmSSttrriinnggFFrreeeeCCoonntteexxtt((33XX)), XXmmSSttrriinnggGGeettLLttooRR((33XX)),
     XXmmSSttrriinnggGGeettNNeexxttCCoommppoonneenntt((33XX)), XXmmSSttrriinnggGGeettNNeexxttSSeeggmmeenntt((33XX)),
     XXmmSSttrriinnggHHaassSSuubbssttrriinngg((33XX)), XXmmSSttrriinnggHHeeiigghhtt((33XX)), XXmmSSttrriinnggIInniittCCoonntteexxtt((33XX)),
     XXmmSSttrriinnggLLeennggtthh((33XX)), XXmmSSttrriinnggLLiinneeCCoouunntt((33XX)), XXmmSSttrriinnggNNCCoonnccaatt((33XX)),
     XXmmSSttrriinnggNNCCooppyy((33XX)), XXmmSSttrriinnggPPeeeekkNNeexxttCCoommppoonneenntt((33XX)),
     XXmmSSttrriinnggSSeeggmmeennttCCrreeaattee((33XX)), XXmmSSttrriinnggSSeeppaarraattoorrCCrreeaattee((33XX)),
     XXmmSSttrriinnggTTaabbllee((33XX)), and XXmmSSttrriinnggWWiiddtthh((33XX)).















   1-656






                                                         XmStringBaseline(3X)



   NAME
     XXmmSSttrriinnggBBaasseelliinnee-A compound string function that returns the number of
     pixels between the top of the character box and the baseline of the
     first line of text

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     DDiimmeennssiioonn XXmmSSttrriinnggBBaasseelliinnee ((_f_o_n_t_l_i_s_t, _s_t_r_i_n_g))
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggBBaasseelliinnee returns the number of pixels between the top of the
     character box and the baseline of the first line of text in the provided
     compound string.

     _f_o_n_t_l_i_s_t
            Specifies the font list

     _s_t_r_i_n_g Specifies the string

   RETURN VALUE
     Returns the number of pixels between the top of the character box and
     the baseline of the first line of text.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).




























   1-657






   XmStringByteCompare(3X)



   NAME
     XXmmSSttrriinnggBByytteeCCoommppaarree-A compound string function that indicates the
     results of a byte-by-byte comparison

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggBByytteeCCoommppaarree ((_s_1, _s_2))
          XXmmSSttrriinngg  _s_1;;
          XXmmSSttrriinngg  _s_2;;

   DESCRIPTION
     XXmmSSttrriinnggBByytteeCCoommppaarree returns a Boolean indicating the results of a byte-
     by-byte comparison of two compound strings.

     In general, if two compound strings are created with the same (char *)
     string using XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd in the same language environment,
     the compound strings compare as equal.  If two compound strings are
     created with the same (char *) string and the same font list element tag
     set other than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG using XXmmSSttrriinnggCCrreeaattee, the strings
     compare as equal.

     In some cases, once a compound string is put into a widget, that string
     is converted into an internal form to allow faster processing.  Part of
     the conversion process strips out unnecessary or redundant information.
     If an application then does an XXttGGeettVVaalluueess to retrieve a compound string
     from a widget (specifically, Label and all of its subclasses), it is not
     guaranteed that the compound string returned is byte-for-byte the same
     as the string given to the widget originally.

     _s_1     Specifies a compound string to be compared with _s_2

     _s_2     Specifies a compound string to be compared with _s_1

   RETURN VALUE
     Returns True if two compound strings are identical byte-by-byte.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd((33XX)).

















   1-658






                                                          XmStringCompare(3X)



   NAME
     XXmmSSttrriinnggCCoommppaarree-A compound string function that compares two strings

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggCCoommppaarree ((_s_1, _s_2))
          XXmmSSttrriinngg  _s_1;;
          XXmmSSttrriinngg  _s_2;;

   DESCRIPTION
     XXmmSSttrriinnggCCoommppaarree returns a Boolean value indicating the results of a
     semantically equivalent comparison of two compound strings.

     Semantically equivalent means that the strings have the same text com-
     ponents, font list element tags, directions, and separators.  In gen-
     eral, if two compound strings are created with the same (char *) string
     using XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd in the same language environment, the com-
     pound strings compare as equal.  If two compound strings are created
     with the same (char *) string and the same font list element tag other
     than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG using XXmmSSttrriinnggCCrreeaattee, the strings compare as
     equal.

     _s_1     Specifies a compound string to be compared with _s_2

     _s_2     Specifies a compound string to be compared with _s_1

   RETURN VALUE
     Returns True if two compound strings are equivalent.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd((33XX)).
























   1-659






   XmStringConcat(3X)



   NAME
     XXmmSSttrriinnggCCoonnccaatt-A compound string function that appends one string to
     another

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggCCoonnccaatt ((_s_1, _s_2))
          XXmmSSttrriinngg  _s_1;;
          XXmmSSttrriinngg  _s_2;;

   DESCRIPTION
     XXmmSSttrriinnggCCoonnccaatt copies _s_2 to the end of _s_1 and returns a copy of the
     resulting compound string.  The original strings are preserved.  The
     space for the resulting compound string is allocated within the func-
     tion.  After using this function, free this space by calling XXmmSSttrriinngg--
     FFrreeee.

     _s_1     Specifies the compound string to which a copy of _s_2 is appended

     _s_2     Specifies the compound string that is appended to the end of _s_1

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggFFrreeee((33XX)).





























   1-660






                                                             XmStringCopy(3X)



   NAME
     XXmmSSttrriinnggCCooppyy-A compound string function that makes a copy of a string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggCCooppyy ((_s_1))
          XXmmSSttrriinngg  _s_1;;

   DESCRIPTION
     XXmmSSttrriinnggCCooppyy makes a copy of a compound string.  The space for the
     resulting compound string is allocated within the function.  The appli-
     cation is responsible for managing the allocated space.  The memory can
     be recovered by calling XXmmSSttrriinnggFFrreeee.

     _s_1     Specifies the compound string to be copied

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggFFrreeee((33XX)).


































   1-661






   XmStringCreate(3X)



   NAME
     XXmmSSttrriinnggCCrreeaattee-A compound string function that creates a compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggCCrreeaattee ((_t_e_x_t, _t_a_g))
          cchhaarr      **_t_e_x_t;;
          cchhaarr      **_t_a_g;;

   DESCRIPTION
     XXmmSSttrriinnggCCrreeaattee creates a compound string with two components: text and a
     font list element tag.

     _t_e_x_t   Specifies a null-terminated string to be used as the text com-
            ponent of the compound string.

     _t_a_g    Specifies the font list element tag to be associated with the
            given text.  The value XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG identifies a locale
            text segment.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmFFoonnttLLiisstt((33XX)), XXmmFFoonnttLLiissttAAdddd((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mFFoonnttLLiissttCCooppyy((33XX)), XXmmFFoonnttLLiissttCCrreeaattee((33XX)), XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee((33XX)),
     XXmmFFoonnttLLiissttEEnnttrryyFFrreeee((33XX)), XXmmFFoonnttLLiissttEEnnttrryyGGeettFFoonntt((33XX)),
     XXmmFFoonnttLLiissttEEnnttrryyGGeettTTaagg((33XX)), XXmmFFoonnttLLiissttEEnnttrryyLLooaadd((33XX)), XXmmFFoonnttLLiissttFFrreeee((33XX)),
     XXmmFFoonnttLLiissttFFrreeeeFFoonnttCCoonntteexxtt((33XX)), XXmmFFoonnttLLiissttGGeettNNeexxttFFoonntt((33XX)),
     XXmmFFoonnttLLiissttIInniittFFoonnttCCoonntteexxtt((33XX)), XXmmFFoonnttLLiissttNNeexxttEEnnttrryy((33XX)),
     XXmmFFoonnttLLiissttRReemmoovveeEEnnttrryy((33XX)), XXmmSSttrriinngg((33XX)), XXmmSSttrriinnggBBaasseelliinnee((33XX)),
     XXmmSSttrriinnggBByytteeCCoommppaarree((33XX)), XXmmSSttrriinnggCCoommppaarree((33XX)), XXmmSSttrriinnggCCoonnccaatt((33XX)),
     XXmmSSttrriinnggCCooppyy((33XX)), XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd((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)),
     XXmmSSttrriinnggCCrreeaatteeSSiimmppllee((33XX)), XXmmSSttrriinnggDDiirreeccttiioonn((33XX)),
     XXmmSSttrriinnggDDiirreeccttiioonnCCrreeaattee((33XX)), XXmmSSttrriinnggDDrraaww((33XX)), XXmmSSttrriinnggDDrraawwIImmaaggee((33XX)),
     XXmmSSttrriinnggDDrraawwUUnnddeerrlliinnee((33XX)), XXmmSSttrriinnggEEmmppttyy((33XX)), XXmmSSttrriinnggEExxtteenntt((33XX)),
     XXmmSSttrriinnggFFrreeee((33XX)), XXmmSSttrriinnggFFrreeeeCCoonntteexxtt((33XX)), XXmmSSttrriinnggGGeettLLttooRR((33XX)),
     XXmmSSttrriinnggGGeettNNeexxttCCoommppoonneenntt((33XX)), XXmmSSttrriinnggGGeettNNeexxttSSeeggmmeenntt((33XX)),
     XXmmSSttrriinnggHHaassSSuubbssttrriinngg((33XX)), XXmmSSttrriinnggHHeeiigghhtt((33XX)), XXmmSSttrriinnggIInniittCCoonntteexxtt((33XX)),
     XXmmSSttrriinnggLLeennggtthh((33XX)), XXmmSSttrriinnggLLiinneeCCoouunntt((33XX)), XXmmSSttrriinnggNNCCoonnccaatt((33XX)),
     XXmmSSttrriinnggNNCCooppyy((33XX)), XXmmSSttrriinnggPPeeeekkNNeexxttCCoommppoonneenntt((33XX)),
     XXmmSSttrriinnggSSeeggmmeennttCCrreeaattee((33XX)), XXmmSSttrriinnggSSeeppaarraattoorrCCrreeaattee((33XX)),
     XXmmSSttrriinnggTTaabbllee((33XX)), and XXmmSSttrriinnggWWiiddtthh((33XX)).












   1-662






                                                  XmStringCreateLocalized(3X)



   NAME
     XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd-A compound string function that creates a com-
     pound string in the current locale

   SYNOPSIS
     ##iinncclluuddee <<XXmm//TTeexxtt..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd ((_t_e_x_t))
          cchhaarr **_t_e_x_t;;

   DESCRIPTION
     XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd creates a compound string containing the speci-
     fied text and assigns XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG as the font list entry tag.
     An identical compound string would result from the function
     XXmmSSttrriinnggCCrreeaattee called with XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG explicitly as the font
     list entry tag.

     _t_e_x_t   Specifies a null-terminated string of text encoded in the current
            locale to be used as the text component of the compound string

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).































   1-663






   XmStringCreateLtoR(3X)



   NAME
     XXmmSSttrriinnggCCrreeaatteeLLttooRR-A compound string function that creates a compound
     string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggCCrreeaatteeLLttooRR ((_t_e_x_t, _t_a_g))
          cchhaarr   **_t_e_x_t;;
          cchhaarr   **_t_a_g;;

   DESCRIPTION
     XXmmSSttrriinnggCCrreeaatteeLLttooRR creates a compound string with two components: text
     and a font list element tag.  This function imposes the semantic of
     scanning for \\nn characters in the text.  When one is found, the text up
     to that point is put into a segment followed by a separator component.
     No final separator component is appended to the end of the compound
     string.  The direction defaults to left-to-right.  This function assumes
     that the encoding is single octet rather than double octet per character
     of text.

     _t_e_x_t   Specifies a null-terminated string to be used as the text com-
            ponent of the compound string.

     _t_a_g    Specifies the font list element tag to be associated with the
            given text.  The value XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG identifies a locale
            text segment.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).























   1-664






                                                     XmStringCreateSimple(3X)



   NAME
     XXmmSSttrriinnggCCrreeaatteeSSiimmppllee-A compound string function that creates a compound
     string in the language environment of a widget

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggCCrreeaatteeSSiimmppllee ((_t_e_x_t))
          cchhaarr   * _t_e_x_t;;

   DESCRIPTION
     XXmmSSttrriinnggCCrreeaatteeSSiimmppllee creates a compound string with two components: text
     and a character set.  It derives the character set from the current
     language environment.

     The routine attempts to derive a character set from the value of the
     LANG environment variable.  If this does not result in a valid character
     set, the routine uses a vendor-specific default.  If the vendor has not
     specified a different value, this default is ISO8859-1.

     NOTE:  This routine is obsolete and exists for compatibility with previ-
     ous releases.  It has been replaced by XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd.

     _t_e_x_t   Specifies a null-terminated string to be used as the text com-
            ponent of the compound string.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd((33XX)).

























   1-665






   XmStringDirection(3X)



   NAME
     XXmmSSttrriinnggDDiirreeccttiioonn-Data type for the direction of display in a string

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

   DESCRIPTION
     XXmmSSttrriinnggDDiirreeccttiioonn is the data type for specifying the direction in which
     the system displays characters of a string, or characters of a segment
     of a compound string.  This is an enumeration with two possible values:

     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
                    Specifies left to right display

     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
                    Specifies right to left display

   RELATED INFORMATION
     XXmmSSttrriinngg((33XX)).




































   1-666






                                                  XmStringDirectionCreate(3X)



   NAME
     XXmmSSttrriinnggDDiirreeccttiioonnCCrreeaattee-A compound string function that creates a com-
     pound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggDDiirreeccttiioonnCCrreeaattee ((_d_i_r_e_c_t_i_o_n))
          XXmmSSttrriinnggDDiirreeccttiioonn_d_i_r_e_c_t_i_o_n;;

   DESCRIPTION
     XXmmSSttrriinnggDDiirreeccttiioonnCCrreeaattee creates a compound string with a single com-
     ponent, a direction with the given value.

     _d_i_r_e_c_t_i_o_n
            Specifies the value of the directional component

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).


































   1-667






   XmStringDraw(3X)



   NAME
     XXmmSSttrriinnggDDrraaww-A compound string function that draws a compound string in
     an X window

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSttrriinnggDDrraaww ((_d, _w, _f_o_n_t_l_i_s_t, _s_t_r_i_n_g, _g_c, _x, _y, _w_i_d_t_h, _a_l_i_g_n_m_e_n_t, _l_a_y_o_u_t__d_i_r_e_c_t_i_o_n, _c_l_i_p))
          DDiissppllaayy   * _d;;
          WWiinnddooww    _w;;
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;
          GGCC        _g_c;;
          PPoossiittiioonn  _x;;
          PPoossiittiioonn  _y;;
          DDiimmeennssiioonn _w_i_d_t_h;;
          uunnssiiggnneedd cchhaarr_a_l_i_g_n_m_e_n_t;;
          uunnssiiggnneedd cchhaarr_l_a_y_o_u_t__d_i_r_e_c_t_i_o_n;;
          XXRReeccttaannggllee* _c_l_i_p;;

   DESCRIPTION
     XXmmSSttrriinnggDDrraaww draws a compound string in an X Window.  If a compound
     string segment uses a font list entry that defines a font set, the
     graphic context passed to this routine will have the GC font member left
     in an undefined state.  The underlying XXmmbbSSttrriinnggDDrraaww function called by
     this routine modifies the font id field of the GC passed into it and
     does not attempt to restore the font id to the incoming value.  If the
     compound string segment is not drawn using a font set, the graphic con-
     text must contain a valid font member.  Graphic contexts created by
     XXttGGeettGGCC are not valid for this routine; instead, use XXttAAllllooccaatteeGGCC to
     create a graphic context.

     _d           Specifies the display.

     _w           Specifies the window.

     _f_o_n_t_l_i_s_t    Specifies the font list.

     _s_t_r_i_n_g      Specifies the string.

     _g_c          Specifies the graphics context to use.

     _x           Specifies a coordinate of the rectangle that will contain
                 the displayed compound string.

     _y           Specifies a coordinate of the rectangle that will contain
                 the displayed compound string.

     _w_i_d_t_h       Specifies the width of the rectangle that will contain the
                 displayed compound string.

     _a_l_i_g_n_m_e_n_t   Specifies how the string will be aligned within the speci-
                 fied rectangle.  It is either XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG,
                 XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR, or XXmmAALLIIGGNNMMEENNTT__EENNDD.


   1-668






                                                             XmStringDraw(3X)



     _l_a_y_o_u_t__d_i_r_e_c_t_i_o_n
                 Controls the direction in which the segments of the compound
                 string will be laid out.  It also determines the meaning of
                 the _a_l_i_g_n_m_e_n_t parameter.

     _c_l_i_p        Allows the application to restrict the area into which the
                 compound string will be drawn.  If NULL, no clipping will be
                 done.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).












































   1-669






   XmStringDrawImage(3X)



   NAME
     XXmmSSttrriinnggDDrraawwIImmaaggee-A compound string function that draws a compound
     string in an X Window and creates an image

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSttrriinnggDDrraawwIImmaaggee ((_d, _w, _f_o_n_t_l_i_s_t, _s_t_r_i_n_g, _g_c, _x, _y, _w_i_d_t_h, _a_l_i_g_n_m_e_n_t,
               _l_a_y_o_u_t__d_i_r_e_c_t_i_o_n, _c_l_i_p))
          DDiissppllaayy   * _d;;
          WWiinnddooww    _w;;
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;
          GGCC        _g_c;;
          PPoossiittiioonn  _x;;
          PPoossiittiioonn  _y;;
          DDiimmeennssiioonn _w_i_d_t_h;;
          uunnssiiggnneedd cchhaarr_a_l_i_g_n_m_e_n_t;;
          uunnssiiggnneedd cchhaarr_l_a_y_o_u_t__d_i_r_e_c_t_i_o_n;;
          XXRReeccttaannggllee* _c_l_i_p;;

   DESCRIPTION
     XXmmSSttrriinnggDDrraawwIImmaaggee draws a compound string in an X Window and paints both
     the foreground and background bits of each character.  If a compound
     string segment uses a font list entry that defines a font set, the
     graphic context passed to this routine will have the GC font member left
     in an undefined state.  The underlying XXmmbbSSttrriinnggDDrraaww function called by
     this routine modifies the font id field of the GC passed into it and
     does not attempt to restore the font id to the incoming value.  If the
     compound string segment is not drawn using a font set, the graphic con-
     text must contain a valid font member.  Graphic contexts created by
     XXttGGeettGGCC are not accepted by this routine; instead, use XXttAAllllooccaatteeGGCC to
     create a graphic context.

     _d           Specifies the display.

     _w           Specifies the window.

     _f_o_n_t_l_i_s_t    Specifies the font list.

     _s_t_r_i_n_g      Specifies the string.

     _g_c          Specifies the graphics context to use.

     _x           Specifies a coordinate of the rectangle that will contain
                 the displayed compound string.

     _y           Specifies a coordinate of the rectangle that will contain
                 the displayed compound string.

     _w_i_d_t_h       Specifies the width of the rectangle that will contain the
                 displayed compound string.

     _a_l_i_g_n_m_e_n_t   Specifies how the string will be aligned within the


   1-670






                                                        XmStringDrawImage(3X)


                 specified rectangle.  It is either XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG,
                 XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR, or XXmmAALLIIGGNNMMEENNTT__EENNDD.

     _l_a_y_o_u_t__d_i_r_e_c_t_i_o_n
                 Controls the direction in which the segments of the compound
                 string will be laid out.  It also determines the meaning of
                 the _a_l_i_g_n_m_e_n_t parameter.

     _c_l_i_p        Allows the application to restrict the area into which the
                 compound string will be drawn.  If NULL, no clipping will be
                 done.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).










































   1-671






   XmStringDrawUnderline(3X)



   NAME
     XXmmSSttrriinnggDDrraawwUUnnddeerrlliinnee-A compound string function that underlines a
     string drawn in an X Window

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSttrriinnggDDrraawwUUnnddeerrlliinnee ((_d, _w, _f_o_n_t_l_i_s_t, _s_t_r_i_n_g, _g_c, _x, _y, _w_i_d_t_h, _a_l_i_g_n_m_e_n_t, _l_a_y_o_u_t__d_i_r_e_c_t_i_o_n, _c_l_i_p, _u_n_d_e_r_l_i_n_e))
          DDiissppllaayy   * _d;;
          WWiinnddooww    _w;;
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;
          GGCC        _g_c;;
          PPoossiittiioonn  _x;;
          PPoossiittiioonn  _y;;
          DDiimmeennssiioonn _w_i_d_t_h;;
          uunnssiiggnneedd cchhaarr_a_l_i_g_n_m_e_n_t;;
          uunnssiiggnneedd cchhaarr_l_a_y_o_u_t__d_i_r_e_c_t_i_o_n;;
          XXRReeccttaannggllee* _c_l_i_p;;
          XXmmSSttrriinngg  _u_n_d_e_r_l_i_n_e;;

   DESCRIPTION
     XXmmSSttrriinnggDDrraawwUUnnddeerrlliinnee draws a compound string in an X Window.  If the
     substring identified by _u_n_d_e_r_l_i_n_e can be matched in _s_t_r_i_n_g, the sub-
     string will be underlined.  Once a match has occurred, no further
     matches or underlining will be done.

     If a compound string segment uses a font list entry that defines a font
     set, the graphic context passed to this routine will have the GC font
     member left in an undefined state.  The underlying XXmmbbSSttrriinnggDDrraaww func-
     tion called by this routine modifies the font id field of the GC passed
     into it and does not attempt to restore the font id to the incoming
     value.  If the compound string segment is not drawn using a font set,
     the graphic context must contain a valid font member.  Graphic contexts
     created by XXttGGeettGGCC are not accepted by this routine; instead, use XXttAAll--
     llooccaatteeGGCC to create a graphic context.

     _d           Specifies the display.

     _w           Specifies the window.

     _f_o_n_t_l_i_s_t    Specifies the font list.

     _s_t_r_i_n_g      Specifies the string.

     _g_c          Specifies the graphics context to use.

     _x           Specifies a coordinate of the rectangle that will contain
                 the displayed compound string.

     _y           Specifies a coordinate of the rectangle that will contain
                 the displayed compound string.

     _w_i_d_t_h       Specifies the width of the rectangle that will contain the


   1-672






                                                    XmStringDrawUnderline(3X)


                 displayed compound string.

     _a_l_i_g_n_m_e_n_t   Specifies how the string will be aligned within the speci-
                 fied rectangle.  It is one of XXmmAALLIIGGNNMMEENNTT__BBEEGGIINNNNIINNGG,
                 XXmmAALLIIGGNNMMEENNTT__CCEENNTTEERR, or XXmmAALLIIGGNNMMEENNTT__EENNDD.

     _l_a_y_o_u_t__d_i_r_e_c_t_i_o_n
                 Controls the direction in which the segments of the compound
                 string will be laid out.  It also determines the meaning of
                 the _a_l_i_g_n_m_e_n_t parameter.

     _c_l_i_p        Allows the application to restrict the area into which the
                 compound string will be drawn.  If NULL, no clipping will be
                 done.

     _u_n_d_e_r_l_i_n_e   Specifies the substring to be underlined.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).





































   1-673






   XmStringEmpty(3X)



   NAME
     XXmmSSttrriinnggEEmmppttyy-A compound string function that provides information on
     the existence of non-zero length text components

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggEEmmppttyy ((_s_1))
          XXmmSSttrriinngg  _s_1;;

   DESCRIPTION
     XXmmSSttrriinnggEEmmppttyy returns a Boolean value indicating whether any non-zero
     length text components exist in the provided compound string.  It
     returns True if there are no text segments in the string.  If this rou-
     tine is passed NULL as the string, it returns True.

     _s_1     Specifies the compound string

   RETURN VALUE
     Returns True if there are no text segments in the string.  If this rou-
     tine is passed NULL as the string, it returns True.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).
































   1-674






                                                           XmStringExtent(3X)



   NAME
     XXmmSSttrriinnggEExxtteenntt-A compound string function that determines the size of
     the smallest rectangle that will enclose the compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSttrriinnggEExxtteenntt ((_f_o_n_t_l_i_s_t, _s_t_r_i_n_g, _w_i_d_t_h, _h_e_i_g_h_t))
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;
          DDiimmeennssiioonn *_w_i_d_t_h;;
          DDiimmeennssiioonn *_h_e_i_g_h_t;;

   DESCRIPTION
     XXmmSSttrriinnggEExxtteenntt determines the width and height, in pixels, of the smal-
     lest rectangle that will enclose the provided compound string.

     _f_o_n_t_l_i_s_t
            Specifies the font list

     _s_t_r_i_n_g Specifies the string

     _w_i_d_t_h  Specifies a pointer to the width of the rectangle

     _h_e_i_g_h_t Specifies a pointer to the height of the rectangle

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).




























   1-675






   XmStringFree(3X)



   NAME
     XXmmSSttrriinnggFFrreeee-A compound string function that recovers memory

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSttrriinnggFFrreeee ((_s_t_r_i_n_g))
          XXmmSSttrriinngg  _s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggFFrreeee recovers memory used by a compound string.

     _s_t_r_i_n_g Specifies the compound string to be freed

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).








































   1-676






                                                      XmStringFreeContext(3X)



   NAME
     XXmmSSttrriinnggFFrreeeeCCoonntteexxtt-A compound string function that instructs the
     toolkit that the context is no longer needed

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmSSttrriinnggFFrreeeeCCoonntteexxtt ((_c_o_n_t_e_x_t))
          XXmmSSttrriinnggCCoonntteexxtt_c_o_n_t_e_x_t;;

   DESCRIPTION
     XXmmSSttrriinnggFFrreeeeCCoonntteexxtt instructs the toolkit that the context is no longer
     needed and will not be used without reinitialization.

     _c_o_n_t_e_x_tSpecifies the string context structure that was allocated by the
            XXmmSSttrriinnggIInniittCCoonntteexxtt function

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggIInniittCCoonntteexxtt((33XX)).





































   1-677






   XmStringGetLtoR(3X)



   NAME
     XXmmSSttrriinnggGGeettLLttooRR-A compound string function that searches for a text seg-
     ment in the input compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggGGeettLLttooRR ((_s_t_r_i_n_g, _t_a_g, _t_e_x_t))
          XXmmSSttrriinngg  _s_t_r_i_n_g;;
          XXmmSSttrriinnggCChhaarrSSeett_t_a_g;;
          cchhaarr      ****_t_e_x_t;;

   DESCRIPTION
     XXmmSSttrriinnggGGeettLLttooRR searches for a text segment in the input compound string
     that matches the given font list element tag.

     _s_t_r_i_n_g Specifies the compound string.

     _t_a_g    Specifies the font list element tag associated with the text.  A
            value of XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG identifies a locale text segment.

     _t_e_x_t   Specifies a pointer to a null terminated string.

   RETURN VALUE
     Returns True if the matching text segment can be found.  On return, _t_e_x_t
     will have a null terminated octet sequence containing the matched seg-
     ment.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).


























   1-678






                                                 XmStringGetNextComponent(3X)



   NAME
     XXmmSSttrriinnggGGeettNNeexxttCCoommppoonneenntt-A compound string function that returns the
     type and value of the next component in a compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinnggCCoommppoonneennttTTyyppee XXmmSSttrriinnggGGeettNNeexxttCCoommppoonneenntt ((_c_o_n_t_e_x_t, _t_e_x_t, _t_a_g, _d_i_r_e_c_t_i_o_n, _u_n_k_n_o_w_n__t_a_g,
     _u_n_k_n_o_w_n__l_e_n_g_t_h, _u_n_k_n_o_w_n__v_a_l_u_e))
          XXmmSSttrriinnggCCoonntteexxtt     _c_o_n_t_e_x_t;;
          cchhaarr                ****_t_e_x_t;;
          XXmmSSttrriinnggCChhaarrSSeett     **_t_a_g;;
          XXmmSSttrriinnggDDiirreeccttiioonn   **_d_i_r_e_c_t_i_o_n;;
          XXmmSSttrriinnggCCoommppoonneennttTTyyppee**_u_n_k_n_o_w_n__t_a_g;;
          uunnssiiggnneedd sshhoorrtt      **_u_n_k_n_o_w_n__l_e_n_g_t_h;;
          uunnssiiggnneedd cchhaarr       ****_u_n_k_n_o_w_n__v_a_l_u_e;;

   DESCRIPTION
     XXmmSSttrriinnggGGeettNNeexxttCCoommppoonneenntt returns the type and value of the next com-
     ponent in the compound string identified by _c_o_n_t_e_x_t.  It is a low-level
     component function.  Components are returned one at a time.  On return,
     only some output parameters will be valid; which ones can be determined
     by examining the return status.  In the case of _t_e_x_t, _t_a_g, and _d_i_r_e_c_t_i_o_n
     components, only one output parameter is valid.  If the return status
     indicates an unknown component was encountered, the font list element
     tag, length, and value are returned.  This function allocates the space
     necessary to hold returned values; freeing this space is the caller's
     responsibility.

     _c_o_n_t_e_x_t     Specifies the string context structure which was allocated
                 by the XXmmSSttrriinnggIInniittCCoonntteexxtt function.

     _t_e_x_t        Specifies a pointer to a null terminated string.

     _t_a_g         Specifies a pointer to the font list element tag associated
                 with the text.  The value XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG identifies
                 a locale text segment.

     _d_i_r_e_c_t_i_o_n   Specifies a pointer to the direction of the text.

     _u_n_k_n_o_w_n__t_a_g Specifies a pointer to the tag of an unknown component.

     _u_n_k_n_o_w_n__l_e_n_g_t_h
                 Specifies a pointer to the length of an unknown component.

     _u_n_k_n_o_w_n__v_a_l_u_e










   1-679






   XmStringGetNextComponent(3X)


                 Specifies a pointer to the value of an unknown component.

   RETURN VALUE
     Returns the type of component found.  Following are the possible values:

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__CCHHAARRSSEETT
          This component is obsolete and remains for compatibility with pre-
          vious releases.  It has been replaced by
          XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__FFOONNTTLLIISSTT__EELLEEMMEENNTT__TTAAGG.

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__FFOONNTTLLIISSTT__EELLEEMMEENNTT__TTAAGG

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__LLOOCCAALLEE__TTEEXXTT

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__TTAAGG

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__TTEEXXTT

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__DDIIRREECCTTIIOONN

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__SSEEPPAARRAATTOORR

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__EENNDD

       ++oo  XXmmSSTTRRIINNGG__CCOOMMPPOONNEENNTT__UUNNKKNNOOWWNN

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggIInniittCCoonntteexxtt((33XX)).




























   1-680






                                                   XmStringGetNextSegment(3X)



   NAME
     XXmmSSttrriinnggGGeettNNeexxttSSeeggmmeenntt-A compound string function that fetches the
     octets in the next segment of a compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggGGeettNNeexxttSSeeggmmeenntt ((_c_o_n_t_e_x_t, _t_e_x_t, _t_a_g, _d_i_r_e_c_t_i_o_n, _s_e_p_a_r_a_t_o_r))
          XXmmSSttrriinnggCCoonntteexxtt_c_o_n_t_e_x_t;;
          cchhaarr           ****_t_e_x_t;;
          XXmmSSttrriinnggCChhaarrSSeett**_t_a_g;;
          XXmmSSttrriinnggDDiirreeccttiioonn**_d_i_r_e_c_t_i_o_n;;
          BBoooolleeaann        **_s_e_p_a_r_a_t_o_r;;

   DESCRIPTION
     XXmmSSttrriinnggGGeettNNeexxttSSeeggmmeenntt fetches the octets in the next segment; repeated
     calls fetch sequential segments.  The _t_e_x_t, _t_a_g, and _d_i_r_e_c_t_i_o_n of the
     fetched segment are returned each time.  A Boolean status is returned to
     indicate whether a valid segment was successfully parsed.

     _c_o_n_t_e_x_t   Specifies the string context structure which was allocated by
               the XXmmSSttrriinnggIInniittCCoonntteexxtt function.

     _t_e_x_t      Specifies a pointer to a null terminated string.

     _t_a_g       Specifies a pointer to the font list element tag associated
               with the text.

     _d_i_r_e_c_t_i_o_n Specifies a pointer to the direction of the text.

     _s_e_p_a_r_a_t_o_r Specifies whether the next component of the compound string is
               a separator.

   RETURN VALUE
     Returns True if a valid segment is found.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggIInniittCCoonntteexxtt((33XX)).


















   1-681






   XmStringHasSubstring(3X)



   NAME
     XXmmSSttrriinnggHHaassSSuubbssttrriinngg-A compound string function that indicates whether
     one compound string is contained within another

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggHHaassSSuubbssttrriinngg ((_s_t_r_i_n_g, _s_u_b_s_t_r_i_n_g))
          XXmmSSttrriinngg  _s_t_r_i_n_g;;
          XXmmSSttrriinngg  _s_u_b_s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggHHaassSSuubbssttrriinngg indicates whether or not one compound string is
     contained within another.

     _s_t_r_i_n_g Specifies the compound string to be searched

     _s_u_b_s_t_r_i_n_g
            Specifies the compound string to be searched for

   RETURN VALUE
     Returns True if _s_u_b_s_t_r_i_n_g has a single segment and if its text is com-
     pletely contained within any single segment of _s_t_r_i_n_g; otherwise,
     returns False.  If two compound strings created using XXmmSSttrriinnggCCrreeaatteeLLoo--
     ccaalliizzeedd in the same language environment satisfy this condition, the
     function returns True.  If two compound strings created with the same
     character set using XXmmSSttrriinnggCCrreeaattee satisfy this condition, the function
     returns True.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd((33XX))..

























   1-682






                                                           XmStringHeight(3X)



   NAME
     XXmmSSttrriinnggHHeeiigghhtt-A compound string function that returns the line height
     of the given compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     DDiimmeennssiioonn XXmmSSttrriinnggHHeeiigghhtt ((_f_o_n_t_l_i_s_t, _s_t_r_i_n_g))
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggHHeeiigghhtt returns the height, in pixels, of the sum of all the line
     heights of the given compound string.  Separator components delimit
     lines.

     _f_o_n_t_l_i_s_t
            Specifies the font list

     _s_t_r_i_n_g Specifies the string

   RETURN VALUE
     Returns the height of the specified string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).






























   1-683






   XmStringInitContext(3X)



   NAME
     XXmmSSttrriinnggIInniittCCoonntteexxtt-A compound string function that allows applications
     to read out the content segment by segment

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     BBoooolleeaann XXmmSSttrriinnggIInniittCCoonntteexxtt ((_c_o_n_t_e_x_t, _s_t_r_i_n_g))
          XXmmSSttrriinnggCCoonntteexxtt* _c_o_n_t_e_x_t;;
          XXmmSSttrriinngg    _s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggIInniittCCoonntteexxtt maintains a context to allow applications to read
     out the contents of a compound string segment by segment.  This function
     establishes the context for this read out. This context is used when
     reading subsequent segments out of the string.  A Boolean status is
     returned to indicate if the input string could be parsed.

     _c_o_n_t_e_x_tSpecifies a pointer to the allocated context

     _s_t_r_i_n_g Specifies the string.

   RETURN VALUE
     Returns True if the context was allocated

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).





























   1-684






                                                           XmStringLength(3X)



   NAME
     XXmmSSttrriinnggLLeennggtthh-A compound string function that obtains the length of a
     compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     iinntt XXmmSSttrriinnggLLeennggtthh ((_s_1))
          XXmmSSttrriinngg  _s_1;;

   DESCRIPTION
     XXmmSSttrriinnggLLeennggtthh obtains the length of a compound string.  It returns the
     number of bytes in _s_1 including all tags, direction indicators, and
     separators.  If the compound string has an invalid structure, zero is
     returned.

     _s_1     Specifies the compound string

   RETURN VALUE
     Returns the length of the compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).

































   1-685






   XmStringLineCount(3X)



   NAME
     XXmmSSttrriinnggLLiinneeCCoouunntt-A compound string function that returns the number of
     separators plus one in the provided compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     iinntt XXmmSSttrriinnggLLiinneeCCoouunntt ((_s_t_r_i_n_g))
          XXmmSSttrriinngg  _s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggLLiinneeCCoouunntt returns the number of separators plus one in the pro-
     vided compound string.  In effect, it counts the lines of text.

     _s_t_r_i_n_g Specifies the string.

   RETURN VALUE
     Returns the number of lines in the compound string

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).



































   1-686






                                                          XmStringNConcat(3X)



   NAME
     XXmmSSttrriinnggNNCCoonnccaatt-A compound string function that appends a specified
     number of bytes to a compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggNNCCoonnccaatt ((_s_1, _s_2, _n_u_m__b_y_t_e_s))
          XXmmSSttrriinngg  _s_1;;
          XXmmSSttrriinngg  _s_2;;
          iinntt       _n_u_m__b_y_t_e_s;;

   DESCRIPTION
     XXmmSSttrriinnggNNCCoonnccaatt appends a specified number of bytes from _s_2 to the end
     of _s_1, including tags, directional indicators, and separators.  It then
     returns the resulting compound string.  The original strings are
     preserved.  The space for the resulting compound string is allocated
     within the function.  The application is responsible for managing the
     allocated space.  The memory can be recovered by calling XXmmSSttrriinnggFFrreeee.

     _s_1     Specifies the compound string to which a copy of _s_2 is appended.

     _s_2     Specifies the compound string that is appended to the end of _s_1.

     _n_u_m__b_y_t_e_s
            Specifies the number of bytes of _s_2 to append to _s_1.  If this
            value is less than the length of _s_2, as many bytes as possible,
            but possibly fewer than this value, will be appended to _s_1 such
            that the resulting string is still a valid compound string.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggFFrreeee((33XX)).





















   1-687






   XmStringNCopy(3X)



   NAME
     XXmmSSttrriinnggNNCCooppyy-A compound string function that creates a copy of a com-
     pound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggNNCCooppyy ((_s_1, _n_u_m__b_y_t_e_s))
          XXmmSSttrriinngg  _s_1;;
          iinntt       _n_u_m__b_y_t_e_s;;

   DESCRIPTION
     XXmmSSttrriinnggNNCCooppyy creates a copy of _s_1 that contains a specified number of
     bytes, including tags, directional indicators, and separators.  It then
     returns the resulting compound string.  The original strings are
     preserved.  The space for the resulting compound string is allocated
     within the function.  The application is responsible for managing the
     allocated space.  The memory can be recovered by calling XXmmSSttrriinnggFFrreeee.

     _s_1     Specifies the compound string.

     _n_u_m__b_y_t_e_s
            Specifies the number of bytes of _s_1 to copy.  If this value is
            less than the length of _s_1, as many bytes as possible, but possi-
            bly fewer than this value, will be appended to _s_1 such that the
            resulting string is still a valid compound string.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)) and XXmmSSttrriinnggFFrreeee((33XX)).
























   1-688






                                                XmStringPeekNextComponent(3X)



   NAME
     XXmmSSttrriinnggPPeeeekkNNeexxttCCoommppoonneenntt-A compound string function that returns the
     component type of the next component fetched

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinnggCCoommppoonneennttTTyyppee XXmmSSttrriinnggPPeeeekkNNeexxttCCoommppoonneenntt ((_c_o_n_t_e_x_t))
          XXmmSSttrriinnggCCoonntteexxtt_c_o_n_t_e_x_t;;

   DESCRIPTION
     XXmmSSttrriinnggPPeeeekkNNeexxttCCoommppoonneenntt examines the next component that would be
     fetched by XXmmSSttrriinnggGGeettNNeexxttCCoommppoonneenntt and returns the component type.

     _c_o_n_t_e_x_tSpecifies the string context structure that was allocated by the
            XXmmSSttrriinnggIInniittCCoonntteexxtt function

   RETURN VALUE
     Returns the type of component found.

   RELATED INFORMATION
     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gGGeettNNeexxttCCoommppoonneenntt((33XX)), and
     XXmmSSttrriinnggIInniittCCoonntteexxtt((33XX)).

































   1-689






   XmStringSegmentCreate(3X)



   NAME
     XXmmSSttrriinnggSSeeggmmeennttCCrreeaattee-A compound string function that creates a compound
     string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggSSeeggmmeennttCCrreeaattee ((_t_e_x_t, _t_a_g, _d_i_r_e_c_t_i_o_n, _s_e_p_a_r_a_t_o_r))
          cchhaarr        * _t_e_x_t;;
          cchhaarr        **_t_a_g;;
          XXmmSSttrriinnggDDiirreeccttiioonn_d_i_r_e_c_t_i_o_n;;
          BBoooolleeaann     _s_e_p_a_r_a_t_o_r;;

   DESCRIPTION
     XXmmSSttrriinnggSSeeggmmeennttCCrreeaattee is a high-level function that assembles a compound
     string consisting of a font list element tag, a direction component, a
     text component, and an optional separator component.

     _t_e_x_t   Specifies a null-terminated string to be used as the text com-
            ponent of the compound string.

     _t_a_g    Specifies the font list element tag to be associated with the
            text.  The value XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG identifies a locale text
            segment.

     _d_i_r_e_c_t_i_o_n
            Specifies the direction of the text.

     _s_e_p_a_r_a_t_o_r
            Specifies separator addition.  If False, the compound string does
            not have a separator at the end.  If True, a separator immedi-
            ately follows the text component.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).


















   1-690






                                                  XmStringSeparatorCreate(3X)



   NAME
     XXmmSSttrriinnggSSeeppaarraattoorrCCrreeaattee-A compound string function that creates a com-
     pound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     XXmmSSttrriinngg XXmmSSttrriinnggSSeeppaarraattoorrCCrreeaattee (())

   DESCRIPTION
     XXmmSSttrriinnggSSeeppaarraattoorrCCrreeaattee creates a compound string with a single com-
     ponent, a separator.

   RETURN VALUE
     Returns a new compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).






































   1-691






   XmStringTable(3X)



   NAME
     XXmmSSttrriinnggTTaabbllee-Data type for an array of compound strings

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

   DESCRIPTION
     XXmmSSttrriinnggTTaabbllee is the data type for an array of compound strings (objects
     of type XXmmSSttrriinngg).

   RELATED INFORMATION
     XXmmSSttrriinngg((33XX)).











































   1-692






                                                            XmStringWidth(3X)



   NAME
     XXmmSSttrriinnggWWiiddtthh-A compound string function that returns the width of the
     longest sequence of text components in a compound string

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     DDiimmeennssiioonn XXmmSSttrriinnggWWiiddtthh ((_f_o_n_t_l_i_s_t, _s_t_r_i_n_g))
          XXmmFFoonnttLLiisstt_f_o_n_t_l_i_s_t;;
          XXmmSSttrriinngg  _s_t_r_i_n_g;;

   DESCRIPTION
     XXmmSSttrriinnggWWiiddtthh returns the width, in pixels, of the longest sequence of
     text components in the provided compound string.  Separator components
     are used to delimit sequences of text components.

     _f_o_n_t_l_i_s_t
            Specifies the font list

     _s_t_r_i_n_g Specifies the string

   RETURN VALUE
     Returns the width of the compound string.

   RELATED INFORMATION
     XXmmSSttrriinnggCCrreeaattee((33XX)).






























   1-693






   XmTargetsAreCompatible(3X)



   NAME
     XXmmTTaarrggeettssAArreeCCoommppaattiibbllee-A function that tests whether the target types
     match between a drop site and source object

   SYNOPSIS
     ##iinncclluuddee <<XXmm//DDrraaggDDrroopp..hh>>
     BBoooolleeaann XXmmTTaarrggeettssAArreeCCoommppaattiibbllee ((_d_i_s_p_l_a_y, _e_x_p_o_r_t__t_a_r_g_e_t_s, _n_u_m__e_x_p_o_r_t__t_a_r_g_e_t_s,
                    _i_m_p_o_r_t__t_a_r_g_e_t_s, _n_u_m__i_m_p_o_r_t__t_a_r_g_e_t_s))
          DDiissppllaayy   **_d_i_s_p_l_a_y;;
          AAttoomm      **_e_x_p_o_r_t__t_a_r_g_e_t_s;;
          CCaarrddiinnaall  _n_u_m__e_x_p_o_r_t__t_a_r_g_e_t_s;;
          AAttoomm      **_i_m_p_o_r_t__t_a_r_g_e_t_s;;
          CCaarrddiinnaall  _n_u_m__i_m_p_o_r_t__t_a_r_g_e_t_s;;

   DESCRIPTION
     XXmmTTaarrggeettssAArreeCCoommppaattiibbllee determines whether the import targets of the des-
     tination match any of the export targets of a source.  If there is at
     least one target in common, the function returns True.

     _d_i_s_p_l_a_ySpecifies the display connection.

     _e_x_p_o_r_t__t_a_r_g_e_t_s
            Specifies the list of target atoms associated with the source
            object.  This resource identifies the selection targets the
            source can convert to.

     _n_u_m__e_x_p_o_r_t__t_a_r_g_e_t_s
            Specifies the number of entries in the list of export targets.

     _i_m_p_o_r_t__t_a_r_g_e_t_s
            Specifies the list of targets to be checked against the XXmmNNeexx--
            ppoorrttTTaarrggeettss of the source associated with the specified DragCon-
            text

     _n_u_m__i_m_p_o_r_t__t_a_r_g_e_t_s
            Specifies the number of entries in the _i_m_p_o_r_t__t_a_r_g_e_t_s list.

   RETURN VALUE
     Returns a Boolean value that indicates whether the destination targets
     are compatible with the source targets.  If there is at least one target
     in common, the routine returns True; otherwise, returns False.

   RELATED INFORMATION
     XXmmDDrraaggCCoonntteexxtt((33XX)) and XXmmDDrrooppSSiittee((33XX)).











   1-694



 m
