


                                                          XmCascadeButton(3X)



   NAME
     XXmmCCaassccaaddeeBBuuttttoonn-The CascadeButton widget class

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCaassccaaddeeBB..hh>>

   DESCRIPTION
     CascadeButton links two MenuPanes or a MenuBar to a MenuPane.

     It is used in menu systems and must have a RowColumn parent with its
     XXmmNNrroowwCCoolluummnnTTyyppee resource set to XXmmMMEENNUU__BBAARR, XXmmMMEENNUU__PPOOPPUUPP or
     XXmmMMEENNUU__PPUULLLLDDOOWWNN.

     It is the only widget that can have a Pulldown MenuPane attached to it
     as a submenu.  The submenu is displayed when this widget is activated
     within a MenuBar, a PopupMenu, or a PulldownMenu.  Its visuals can
     include a label or pixmap and a cascading indicator when it is in a
     Popup or Pulldown MenuPane; or, it can include only a label or a pixmap
     when it is in a MenuBar.

     The default behavior associated with a CascadeButton depends on the type
     of menu system in which it resides.  By default, BBSSeelleecctt controls the
     behavior of the CascadeButton.  In addition, BBMMeennuu controls the behavior
     of the CascadeButton if it resides in a PopupMenu system.  The actual
     mouse button used is determined by its RowColumn parent.

     A CascadeButton's visuals differ from most other button gadgets.  When
     the button becomes armed, its visuals change from a 2-D to a 3-D look,
     and it displays the submenu that has been attached to it.  If no submenu
     is attached, it simply changes its visuals.

     When a CascadeButton within a Pulldown or Popup MenuPane is armed as the
     result of the user moving the mouse pointer into the widget, it does not
     immediately display its submenu.  Instead, it waits a short amount of
     time to see if the arming was temporary (that is, the user was simply
     passing through the widget), or whether the user really wanted the sub-
     menu posted.  This time delay is configurable via XXmmNNmmaappppiinnggDDeellaayy.

     CascadeButton provides a single mechanism for activating the widget from
     the keyboard.  This mechanism is referred to as a keyboard mnemonic.  If
     a mnemonic has been specified for the widget, the user may activate the
     CascadeButton by simply typing the mnemonic while the CascadeButton is
     visible.  If the CascadeButton is in a MenuBar and the MenuBar does not
     have the focus, the MMAAlltt modifier must be pressed with the mnemonic.
     Mnemonics are typically used to interact with a menu via the keyboard
     interface.

     If in a Pulldown or Popup MenuPane and there is a submenu attached, the
     XXmmNNmmaarrggiinnBBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt, and XXmmNNmmaarrggiinnTToopp
     resources may enlarge to accommodate XXmmNNccaassccaaddeePPiixxmmaapp.  XXmmNNmmaarrggiinnWWiiddtthh


   2-129






   XmCascadeButton(3X)


     defaults to 6 if this resource is in a MenuBar; otherwise, it takes
     Label's default, which is 2.

     Classes

     CascadeButton inherits behavior and resources from CCoorree, XXmmPPrriimmiittiivvee,
     and XXmmLLaabbeell classes.

     The class pointer is xxmmCCaassccaaddeeBBuuttttoonnWWiiddggeettCCllaassss.

     The class name is XXmmCCaassccaaddeeBBuuttttoonn.

     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mCCaassccaaddeeBBuuttttoonn 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
    __________________________________________________________________________
    XmNactivateCallback    XmCCallback       XtCallbackList   NULL      C
    XmNcascadePixmap       XmCPixmap         Pixmap           dynamic   CSG
    XmNcascadingCallback   XmCCallback       XtCallbackList   NULL      C
    XmNmappingDelay        XmCMappingDelay   int              180 ms    CSG
    XmNsubMenuId           XmCMenuWidget     Widget           NULL      CSG

     XXmmNNaaccttiivvaatteeCCaallllbbaacckk
               Specifies the list of callbacks that is called when the user
               activates the CascadeButton widget, and there is no submenu
               attached to pop up.  The activation occurs by releasing a
               mouse button or by typing the mnemonic associated with the
               widget.  The specific mouse button depends on information in
               the RowColumn parent.  The reason sent by the callback is
               XXmmCCRR__AACCTTIIVVAATTEE.

     XXmmNNccaassccaaddeePPiixxmmaapp
               Specifies the cascade pixmap displayed on one end of the
               widget when a CascadeButton is used within a Popup or Pulldown
               MenuPane and a submenu is attached.  The Label class resources
               XXmmNNmmaarrggiinnBBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt, and XXmmNNmmaarrggiinn--
               TToopp may be modified to ensure that room is left for the cas-
               cade pixmap.  The default cascade pixmap is an arrow pointing
               to the side of the menu where the submenu will appear.

     XXmmNNccaassccaaddiinnggCCaallllbbaacckk
               Specifies the list of callbacks that is called just prior to


   2-130






                                                          XmCascadeButton(3X)


               the mapping of the submenu associated with CascadeButton.  The
               reason sent by the callback is XXmmCCRR__CCAASSCCAADDIINNGG.

     XXmmNNmmaappppiinnggDDeellaayy
               Specifies the amount of time, in milliseconds, between when a
               CascadeButton becomes armed and when it maps its submenu.
               This delay is used only when the widget is within a Popup or
               Pulldown MenuPane.  The value must not be negative.

     XXmmNNssuubbMMeennuuIIdd
               Specifies the widget ID for the Pulldown MenuPane to be asso-
               ciated with this CascadeButton.  The specified MenuPane is
               displayed when the CascadeButton becomes armed.  The MenuPane
               must have been created with the appropriate parentage depend-
               ing on the type of menu used.  See XXmmCCrreeaatteeMMeennuuBBaarr((33XX)),
               XXmmCCrreeaatteePPuullllddoowwnnMMeennuu((33XX)), and XXmmCCrreeaatteePPooppuuppMMeennuu((33XX)) for more
               information on the menu systems.

     Inherited Resources

     CascadeButton 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mLLaabbeell RReessoouurrccee SSeett
   NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                  AAcccceessss
   ___________________________________________________________________________________________________________
   XmNaccelerator              XmCAccelerator              String              NULL                     N/A
   XmNacceleratorText          XmCAcceleratorText          XmString            NULL                     N/A
   XmNalignment                XmCAlignment                unsigned char       dynamic                  CSG
   XmNfontList                 XmCFontList                 XmFontList          dynamic                  CSG
   XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP     CSG
   XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP     CSG
   XmNlabelString              XmCXmString                 XmString            dynamic                  CSG
   XmNlabelType                XmCLabelType                unsigned char       XmSTRING                 CSG
   XmNmarginBottom             XmCMarginBottom             Dimension           dynamic                  CSG
   XmNmarginHeight             XmCMarginHeight             Dimension           2                        CSG
   XmNmarginLeft               XmCMarginLeft               Dimension           0                        CSG
   XmNmarginRight              XmCMarginRight              Dimension           dynamic                  CSG
   XmNmarginTop                XmCMarginTop                Dimension           dynamic                  CSG
   XmNmarginWidth              XmCMarginWidth              Dimension           dynamic                  CSG
   XmNmnemonic                 XmCMnemonic                 KeySym              NULL                     CSG
   XmNmnemonicCharSet          XmCMnemonicCharSet          String              XmFONTLIST_DEFAULT_TAG   CSG
   XmNrecomputeSize            XmCRecomputeSize            Boolean             True                     CSG
   XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                  CSG
                                       XXm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


   2-131






   XmCascadeButton(3X)


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

     Callback Information

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

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

     _e_v_e_n_t  Points to the XXEEvveenntt that triggered the callback or is NULL if
            this callback was not triggered due to an XXEEvveenntt.

     Action Routines

     The XmCascadeButton action routines are described below:

     CClleeaannuuppMMeennuuBBaarr(()):
               In a MenuBar, disarms the CascadeButton and the menu and, when
               the shell's keyboard focus policy is XXmmEEXXPPLLIICCTT, restores key-
               board focus to the widget that had the focus before the menu




   2-132






                                                          XmCascadeButton(3X)


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

     DDooSSeelleecctt(()):
               Calls the callbacks in XXmmNNccaassccaaddiinnggCCaallllbbaacckk, posts the submenu
               attached to the CascadeButton and enables keyboard traversal
               within the menu.  If the CascadeButton does not have a submenu
               attached, calls the callbacks in XXmmNNaaccttiivvaatteeCCaallllbbaacckk, the Cas-
               cadeButton is activated and all posted menus in the cascade
               are unposted.

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

     KKeeyySSeelleecctt(()):
               Calls the callbacks in XXmmNNccaassccaaddiinnggCCaallllbbaacckk, and posts the
               submenu attached to the CascadeButton if keyboard traversal is
               enabled in the menu.  If the CascadeButton does not have a
               submenu attached, calls the callbacks in XXmmNNaaccttiivvaatteeCCaallllbbaacckk,
               the CascadeButton is activated and all posted menus in the
               cascade are unposted.

     MMeennuuBBaarrSSeelleecctt(()):
               Unposts any menus posted by the parent menu.  Arms both the
               CascadeButton and the MenuBar, posts the associated submenu,
               and enables mouse traversal.  If the menu is already active,
               this event disables keyboard traversal for the menu and
               returns the menu to mouse traversal mode.

     SSttaarrttDDrraagg(()):
               Arms the CascadeButton, posts the associated submenu, and
               enables mouse traversal.  If the menu is already active, this
               event disables keyboard traversal for the menu and returns the
               menu to mouse traversal mode.

   RELATED INFORMATION
     CCoorree((33XX)), XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33XX)),
     XXmmCCrreeaatteeCCaassccaaddeeBBuuttttoonn((33XX)),,XXmmCCrreeaatteeMMeennuuBBaarr((33XX)), XXmmCCrreeaatteePPuullllddoowwnnMMeennuu((33XX)),
     XXmmCCrreeaatteePPooppuuppMMeennuu((33XX)), XXmmLLaabbeell((33XX)), XXmmPPrriimmiittiivvee((33XX)), and
     XXmmRRoowwCCoolluummnn((33XX)).




   2-133






   XmCascadeButtonGadget(3X)



   NAME
     XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett-The CascadeButtonGadget widget class

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCaassccaaddeeBBGG..hh>>

   DESCRIPTION
     CascadeButtonGadget links two MenuPanes, a MenuBar to a MenuPane, or an
     OptionMenu to a MenuPane.

     It is used in menu systems and must have a RowColumn parent with its
     XXmmNNrroowwCCoolluummnnTTyyppee resource set to XXmmMMEENNUU__BBAARR, XXmmMMEENNUU__PPOOPPUUPP,
     XXmmMMEENNUU__PPUULLLLDDOOWWNN, or XXmmMMEENNUU__OOPPTTIIOONN.

     It is the only gadget that can have a Pulldown MenuPane attached to it
     as a submenu.  The submenu is displayed when this gadget is activated
     within a PopupMenu, a PulldownMenu, or an OptionMenu.  Its visuals can
     include a label or pixmap and a cascading indicator when it is in a
     Popup or Pulldown MenuPane; or it can include only a label or a pixmap
     when it is in an OptionMenu.

     The default behavior associated with a CascadeButtonGadget depends on
     the type of menu system in which it resides.  By default, BBSSeelleecctt con-
     trols the behavior of the CascadeButtonGadget.  In addition, BBMMeennuu con-
     trols the behavior of the CascadeButtonGadget if it resides in a Popup-
     Menu system.  The actual mouse button used is determined by its
     RowColumn parent.

     A CascadeButtonGadget's visuals differ from most other button gadgets.
     When the button becomes armed, its visuals change from a 2-D to a 3-D
     look, and it displays the submenu that has been attached to it.  If no
     submenu is attached, it simply changes its visuals.

     When a CascadeButtonGadget within a Pulldown or Popup MenuPane is armed
     as the result of the user moving the mouse pointer into the gadget, it
     does not immediately display its submenu.  Instead, it waits a short
     time to see if the arming was temporary (that is, the user was simply
     passing through the gadget), or the user really wanted the submenu
     posted.  This delay is configurable via XXmmNNmmaappppiinnggDDeellaayy.

     CascadeButtonGadget provides a single mechanism for activating the
     gadget from the keyboard.  This mechanism is referred to as a keyboard
     mnemonic.  If a mnemonic has been specified for the gadget, the user may
     activate it by simply typing the mnemonic while the CascadeButtonGadget
     is visible.  If the CascadeButtonGadget is in a MenuBar and the MenuBar
     does not have the focus, the MMAAlltt modifier must be pressed with the
     mnemonic.  Mnemonics are typically used to interact with a menu via the
     keyboard.




   2-134






                                                    XmCascadeButtonGadget(3X)


     If a CascadeButtonGadget is in a Pulldown or Popup MenuPane and there is
     a submenu attached, the XXmmNNmmaarrggiinnBBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt,
     and XXmmNNmmaarrggiinnTToopp resources may enlarge to accommodate XXmmNNccaassccaaddeePPiixxmmaapp.
     XXmmNNmmaarrggiinnWWiiddtthh defaults to 6 if this resource is in a MenuBar; other-
     wise, it takes LabelGadget's default, which is 2.

     Classes

     CascadeButtonGadget inherits behavior and resources from OObbjjeecctt, RReecc--
     ttOObbjj, XXmmGGaaddggeett, and XXmmLLaabbeellGGaaddggeett classes.

     The class pointer is xxmmCCaassccaaddeeBBuuttttoonnGGaaddggeettCCllaassss.

     The class name is XXmmCCaassccaaddeeBBuuttttoonnG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mCCaassccaaddeeBBuuttttoonnGGaaddgge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
    __________________________________________________________________________
    XmNactivateCallback    XmCCallback       XtCallbackList   NULL      C
    XmNcascadePixmap       XmCPixmap         Pixmap           dynamic   CSG
    XmNcascadingCallback   XmCCallback       XtCallbackList   NULL      C
    XmNmappingDelay        XmCMappingDelay   int              180 ms    CSG
    XmNsubMenuId           XmCMenuWidget     Widget           NULL      CSG

     XXmmNNaaccttiivvaatteeCCaallllbbaacckk
               Specifies the list of callbacks that is called when the user
               activates the CascadeButtonGadget, and there is no submenu
               attached to pop up.  The activation occurs by releasing a
               mouse button or by typing the mnemonic associated with the
               gadget.  The specific mouse button depends on information in
               the RowColumn parent.  The reason sent by the callback is
               XXmmCCRR__AACCTTIIVVAATTEE.

     XXmmNNccaassccaaddeePPiixxmmaapp
               Specifies the cascade pixmap displayed on one end of the
               gadget when a CascadeButtonGadget is used within a Popup or
               Pulldown MenuPane and a submenu is attached.  The LabelGadget
               class resources XXmmNNmmaarrggiinnBBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinn--
               RRiigghhtt, and XXmmNNmmaarrggiinnTToopp may be modified to ensure that room is
               left for the cascade pixmap.  The default cascade pixmap in
               menus other than option menus is an arrow pointing to the side


   2-135






   XmCascadeButtonGadget(3X)


               of the menu where the submenu will appear.  The default for
               the CascadeButtonGadget in an option menu is
               XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP.

     XXmmNNccaassccaaddiinnggCCaallllbbaacckk
               Specifies the list of callbacks that is called just prior to
               the mapping of the submenu associated with the CascadeBut-
               tonGadget.  The reason sent by the callback is XXmmCCRR__CCAASSCCAADDIINNGG.

     XXmmNNmmaappppiinnggDDeellaayy
               Specifies the amount of time, in milliseconds, between when a
               CascadeButtonGadget becomes armed and when it maps its sub-
               menu.  This delay is used only when the gadget is within a
               Popup or Pulldown MenuPane.  The value must not be negative.

     XXmmNNssuubbMMeennuuIIdd
               Specifies the widget ID for the Pulldown MenuPane to be asso-
               ciated with this CascadeButtonGadget.  The specified MenuPane
               is displayed when the CascadeButtonGadget becomes armed.  The
               MenuPane must have been created with the appropriate parentage
               depending on the type of menu used.  See
               XXmmCCrreeaatteePPuullllddoowwnnMMeennuu((33XX)), XXmmCCrreeaatteePPooppuuppMMeennuu((33XX)), and
               XXmmCCrreeaatteeOOppttiioonnMMeennuu((33XX)) for more information on the menu sys-
               tems.

     Inherited Resources

     CascadeButtonGadget 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mLLaabbeellGGaaddggeett RReessoouurrccee SSeett
   NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                AAcccceessss
   _________________________________________________________________________________________________________
   XmNaccelerator              XmCAccelerator              String              NULL                   N/A
   XmNacceleratorText          XmCAcceleratorText          XmString            NULL                   N/A
   XmNalignment                XmCAlignment                unsigned char       dynamic                CSG
   XmNfontList                 XmCFontList                 XmFontList          dynamic                CSG
   XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP   CSG
   XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP   CSG
   XmNlabelString              XmCXmString                 XmString            dynamic                CSG
   XmNlabelType                XmCLabelType                unsigned char       XmSTRING               CSG
   XmNmarginBottom             XmCMarginBottom             Dimension           dynamic                CSG
   XmNmarginHeight             XmCMarginHeight             Dimension           2                      CSG
   XmNmarginLeft               XmCMarginLeft               Dimension           0                      CSG
   XmNmarginRight              XmCMarginRight              Dimension           dynamic                CSG
   XmNmarginTop                XmCMarginTop                Dimension           dynamic                CSG
   XmNmarginWidth              XmCMarginWidth              Dimension           dynamic                CSG
   XmNmnemonic                 XmCMnemonic                 KeySym              NULL                   CSG
   XmNmnemonicCharSet          XmCMnemonicCharSet          String              dynamic                CSG
   XmNrecomputeSize            XmCRecomputeSize            Boolean             True                   CSG
   XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                CSG
                                  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
   ___________________________________________________________________________________


   2-136






                                                    XmCascadeButtonGadget(3X)


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

     Callback Information

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

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

     _e_v_e_n_t  Points to the XXEEvveenntt that triggered the callback or is NULL if
            this callback was not triggered by an XXEEvveenntt.

   RELATED INFORMATION
     OObbjjeecctt((33XX)), RReeccttOObbjj((33XX)), XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33)),
     XXmmCCrreeaatteeCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)), XXmmCCrreeaatteePPuullllddoowwnnMMeennuu((33XX)),
     XXmmCCrreeaatteePPooppuuppMMeennuu((33XX)), XXmmCCrreeaatteeOOppttiioonnMMeennuu((33XX)),,XXmmGGaaddggeett((33XX)),
     XXmmLLaabbeellGGaaddggeett((33XX)), and XXmmRRoowwCCoolluummnn((33XX)).















   2-137






   XmCascadeButtonGadgetHighlight(3X)



   NAME
     XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt-A CascadeButtonGadget function that sets
     the highlight state

   AES SUPPORT LEVEL
     Trial-use

   HISTORY/DIRECTION
     The XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt function is scheduled for removal in
     revision D.  The function is redundant with XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt.

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCaassccaaddeeBBGG..hh>>
     vvooiidd XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt ((_c_a_s_c_a_d_e_B_u_t_t_o_n_G_a_d_g_e_t, _h_i_g_h_l_i_g_h_t))
          WWiiddggeett    _c_a_s_c_a_d_e_B_u_t_t_o_n_G_a_d_g_e_t;;
          BBoooolleeaann   _h_i_g_h_l_i_g_h_t;;

   DESCRIPTION
     XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt either draws or erases the shadow
     highlight around the CascadeButtonGadget.

     _c_a_s_c_a_d_e_B_u_t_t_o_n_G_a_d_g_e_t
                    Specifies the CascadeButtonGadget to be highlighted or
                    unhighlighted.

     _h_i_g_h_l_i_g_h_t      Specifies whether to highlight (True) or to unhighlight
                    (False).

     For a complete definition of CascadeButtonGadget and its associated
     resources, see XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)).

   RELATED INFORMATION
     XXmmCCaassccaaddeeBBuuttttoonn((33XX)), XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)), and
     XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33XX)).





















   2-138






                                                 XmCascadeButtonHighlight(3X)



   NAME
     XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt-A CascadeButton and CascadeButtonGadget func-
     tion that sets the highlight state

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCaassccaaddeeBB..hh>>
     ##iinncclluuddee <<XXmm//CCaassccaaddeeBBGG..hh>>
     vvooiidd XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt ((_c_a_s_c_a_d_e_B_u_t_t_o_n, _h_i_g_h_l_i_g_h_t))
          WWiiddggeett    _c_a_s_c_a_d_e_B_u_t_t_o_n;;
          BBoooolleeaann   _h_i_g_h_l_i_g_h_t;;

   DESCRIPTION
     XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt either draws or erases the shadow highlight
     around the CascadeButton or the CascadeButtonGadget.

     _c_a_s_c_a_d_e_B_u_t_t_o_n  Specifies the CascadeButton or CascadeButtonGadget to be
                    highlighted or unhighlighted.

     _h_i_g_h_l_i_g_h_t      Specifies whether to highlight (True) or to unhighlight
                    (False).

     For a complete definition of CascadeButton or CascadeButtonGadget and
     their associated resources, see XXmmCCaassccaaddeeBBuuttttoonn((33XX)) or
     XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)).

   RELATED INFORMATION
     XXmmCCaassccaaddeeBBuuttttoonn((33XX)), XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)) and
     XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt((33XX)).
























   2-139






   XmClipboardCancelCopy(3X)



   NAME
     XXmmCClliippbbooaarrddCCaanncceellCCooppyy-A clipboard function that cancels a copy to the
     clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddCCaanncceellCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _i_t_e_m__i_d))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          lloonngg      _i_t_e_m__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddCCaanncceellCCooppyy cancels the copy to clipboard that is in progress
     and frees up temporary storage.  When a copy is to be performed, XXmmCClliipp--
     bbooaarrddSSttaarrttCCooppyy allocates temporary storage for the clipboard data.
     XXmmCClliippbbooaarrddCCooppyy copies the appropriate data into the the temporary
     storage.  XXmmCClliippbbooaarrddEEnnddCCooppyy copies the data to the clipboard structure
     and frees up the temporary storage structures.  If XXmmCClliippbbooaarrddCCaanncceellCCooppyy
     is called, the XXmmCClliippbbooaarrddEEnnddCCooppyy function does not have to be called.
     A call to XXmmCClliippbbooaarrddCCaanncceellCCooppyy is valid only after a call to XXmmCClliipp--
     bbooaarrddSSttaarrttCCooppyy and before a call to XXmmCClliippbbooaarrddEEnnddCCooppyy.

     _d_i_s_p_l_a_ySpecifies a pointer to the DDiissppllaayy structure that was returned in
            a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w Specifies a widget's window ID that relates the application win-
            dow to the clipboard.  The widget's window ID can be obtained by
            using XXttWWiinnddooww.  The same application instance should pass the
            same window ID to each of the clipboard functions that it calls.

     _i_t_e_m__i_dSpecifies the number assigned to this data item.  This number was
            returned by a previous call to XXmmCClliippbbooaarrddSSttaarrttCCooppyy.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

     CClliippbbooaarrddFFaaiill
                 The function failed because XXmmCClliippbbooaarrddSSttaarrttCCooppyy was not
                 called or because the data item contains too many formats.


   2-140






                                                    XmClipboardCancelCopy(3X)



   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCooppyy((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), and
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).




















































   2-141






   XmClipboardCopy(3X)



   NAME
     XXmmCClliippbbooaarrddCCooppyy-A clipboard function that copies a data item to tem-
     porary storage for later copying to clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _i_t_e_m__i_d, _f_o_r_m_a_t__n_a_m_e,
               _b_u_f_f_e_r, _l_e_n_g_t_h, _p_r_i_v_a_t_e__i_d, _d_a_t_a__i_d))
          DDiissppllaayy    * _d_i_s_p_l_a_y;;
          WWiinnddooww     _w_i_n_d_o_w;;
          lloonngg       _i_t_e_m__i_d;;
          cchhaarr       * _f_o_r_m_a_t__n_a_m_e;;
          XXttPPooiinntteerr  _b_u_f_f_e_r;;
          uunnssiiggnneedd lloonngg_l_e_n_g_t_h;;
          lloonngg       _p_r_i_v_a_t_e__i_d;;
          lloonngg       * _d_a_t_a__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddCCooppyy copies a data item to temporary storage.  The data item
     is moved from temporary storage to the clipboard data structure when a
     call to XXmmCClliippbbooaarrddEEnnddCCooppyy is made.  Additional calls to XXmmCClliippbbooaarrddCCooppyy
     before a call to XXmmCClliippbbooaarrddEEnnddCCooppyy add additional data item formats to
     the same data item or append data to an existing format.  Formats are
     described in the _I_n_t_e_r-_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l (ICCCM)
     as targets.

     NNOOTTEE::  Do not call XXmmCClliippbbooaarrddCCooppyy before a call to XXmmCClliippbbooaarrddSSttaarrttCCooppyy
     has been made.  The latter function allocates temporary storage required
     by XXmmCClliippbbooaarrddCCooppyy.

     If the _b_u_f_f_e_r argument is NULL, the data is considered to be passed by
     name.  When data that has been passed by name is later requested by
     another application, the application that owns the data receives a call-
     back with a request for the data.  The application that owns the data
     must then transfer the data to the clipboard with the XXmmCClliippbbooaarrddCCooppyy--
     BByyNNaammee function.  When a data item that was passed by name is deleted
     from the clipboard, the application that owns the data receives a call-
     back stating that the data is no longer needed.

     For information on the callback function, see the callback argument
     description for XXmmCClliippbbooaarrddSSttaarrttCCooppyy.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard


   2-142






                                                          XmClipboardCopy(3X)


                 functions that it calls.

     _i_t_e_m__i_d     Specifies the number assigned to this data item.  This
                 number was returned by a previous call to XXmmCClliipp--
                 bbooaarrddSSttaarrttCCooppyy.

     _f_o_r_m_a_t__n_a_m_e Specifies the name of the format in which the data item is
                 stored on the clipboard.  Format is known as target in the
                 ICCCM.

     _b_u_f_f_e_r      Specifies the buffer from which the clipboard copies the
                 data.

     _l_e_n_g_t_h      Specifies the length of the data being copied to the clip-
                 board.

     _p_r_i_v_a_t_e__i_d  Specifies the private data that the application wants to
                 store with the data item.

     _d_a_t_a__i_d     Specifies an identifying number assigned to the data item
                 that uniquely identifies the data item and the format.  This
                 argument is required only for data that is passed by name.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

     CClliippbbooaarrddFFaaiill
                 The function failed because XXmmCClliippbbooaarrddSSttaarrttCCooppyy was not
                 called or because the data item contains too many formats.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), and
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).













   2-143






   XmClipboardCopyByName(3X)



   NAME
     XXmmCClliippbbooaarrddCCooppyyBByyNNaammee-A clipboard function that copies a data item
     passed by name

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddCCooppyyBByyNNaammee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _d_a_t_a__i_d,
               _b_u_f_f_e_r, _l_e_n_g_t_h, _p_r_i_v_a_t_e__i_d))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          lloonngg      _d_a_t_a__i_d;;
          XXttPPooiinntteerr _b_u_f_f_e_r;;
          uunnssiiggnneedd lloonngg_l_e_n_g_t_h;;
          lloonngg      _p_r_i_v_a_t_e__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddCCooppyyBByyNNaammee copies the actual data for a data item that was
     previously passed by name to the clipboard.  Data is considered to be
     passed by name when a call to XXmmCClliippbbooaarrddCCooppyy is made with a NULL buffer
     parameter.  Additional calls to this function append new data to the
     existing data.

     _d_i_s_p_l_a_y   Specifies a pointer to the DDiissppllaayy structure that was returned
               in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w    Specifies a widget's window ID that relates the application
               window to the clipboard.  The widget's window ID can be
               obtained by using XXttWWiinnddooww.  The same application instance
               should pass the same window ID to each clipboard function it
               calls.

     _d_a_t_a__i_d   Specifies an identifying number assigned to the data item that
               uniquely identifies the data item and the format.  This number
               was assigned by XXmmCClliippbbooaarrddCCooppyy to the data item.

     _b_u_f_f_e_r    Specifies the buffer from which the clipboard copies the data.

     _l_e_n_g_t_h    Specifies the number of bytes in the data item.

     _p_r_i_v_a_t_e__i_d
               Specifies the private data that the application wants to store
               with the data item.









   2-144






                                                    XmClipboardCopyByName(3X)



   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCooppyy((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)), XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), and
     XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).







































   2-145






   XmClipboardEndCopy(3X)



   NAME
     XXmmCClliippbbooaarrddEEnnddCCooppyy-A clipboard function that ends a copy to the clip-
     board

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddEEnnddCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _i_t_e_m__i_d))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          lloonngg      _i_t_e_m__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddEEnnddCCooppyy locks the clipboard from access by other applica-
     tions, places data in the clipboard data structure, and unlocks the
     clipboard.  Data items copied to the clipboard by XXmmCClliippbbooaarrddCCooppyy are
     not actually entered in the clipboard data structure until the call to
     XXmmCClliippbbooaarrddEEnnddCCooppyy.

     This function also frees up temporary storage that was allocated by
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy, which must be called before XXmmCClliippbbooaarrddEEnnddCCooppyy.
     The latter function should not be called if XXmmCClliippbbooaarrddCCaanncceellCCooppyy has
     been called.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each clipboard function it
                 calls.

     _i_t_e_m__i_d     Specifies the number assigned to this data item.  This
                 number was returned by a previous call to XXmmCClliipp--
                 bbooaarrddSSttaarrttCCooppyy.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.



   2-146






                                                       XmClipboardEndCopy(3X)


     CClliippbbooaarrddFFaaiill
                 The function failed because XXmmCClliippbbooaarrddSSttaarrttCCooppyy was not
                 called.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX)), XXmmCClliippbbooaarrddCCooppyy((33XX)) and
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).

















































   2-147






   XmClipboardEndRetrieve(3X)



   NAME
     XXmmCClliippbbooaarrddEEnnddRReettrriieevvee-A clipboard function that ends a copy from the
     clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddEEnnddRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;

   DESCRIPTION
     XXmmCClliippbbooaarrddEEnnddRReettrriieevvee suspends copying data incrementally from the
     clipboard.  It tells the clipboard routines that the application is
     through copying an item from the clipboard.  Until this function is
     called, data items can be retrieved incrementally from the clipboard by
     calling XXmmCClliippbbooaarrddRReettrriieevvee.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), and
     XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)).









   2-148






                                                  XmClipboardInquireCount(3X)



   NAME
     XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt-A clipboard function that returns the number of
     data item formats

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _c_o_u_n_t,
               _m_a_x__f_o_r_m_a_t__n_a_m_e__l_e_n_g_t_h))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          iinntt       * _c_o_u_n_t;;
          uunnssiiggnneedd lloonngg* _m_a_x__f_o_r_m_a_t__n_a_m_e__l_e_n_g_t_h;;

   DESCRIPTION
     XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt returns the number of data item formats avail-
     able for the data item in the clipboard.  This function also returns the
     maximum name-length for all formats in which the data item is stored.

     _d_i_s_p_l_a_y         Specifies a pointer to the DDiissppllaayy structure that was
                     returned in a previous call to XXOOppeennDDiissppllaayy or
                     XXttDDiissppllaayy.

     _w_i_n_d_o_w          Specifies a widget's window ID that relates the applica-
                     tion window to the clipboard.  The widget's window ID
                     can be obtained by using XXttWWiinnddooww.  The same application
                     instance should pass the same window ID to each of the
                     clipboard functions that it calls.

     _c_o_u_n_t           Returns the number of data item formats available for
                     the data item in the clipboard.  If no formats are
                     available, this argument equals zero.  The count
                     includes the formats that were passed by name.

     _m_a_x__f_o_r_m_a_t__n_a_m_e__l_e_n_g_t_h
                     Specifies the maximum length of all format names for the
                     data item in the clipboard.















   2-149






   XmClipboardInquireCount(3X)



   RETURN VALUE

     CClliippbbooaarrddSSuucccceessssThe function is successful.

     CClliippbbooaarrddLLoocckkeedd The function failed because the clipboard was locked by
                     another application.  The application can continue to
                     call the function again with the same parameters until
                     the lock goes away.  This gives the application the
                     opportunity to ask if the user wants to keep trying or
                     to give up on the operation.

     CClliippbbooaarrddNNooDDaattaa The function could not find data on the clipboard
                     corresponding to the format requested.  This could occur
                     because the clipboard is empty; there is data on the
                     clipboard but not in the requested format; or the data
                     in the requested format was passed by name and is no
                     longer available.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).



































   2-150






                                                 XmClipboardInquireFormat(3X)



   NAME
     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt-A clipboard function that returns a specified
     format name

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _i_n_d_e_x, _f_o_r_m_a_t__n_a_m_e__b_u_f,
               _b_u_f_f_e_r__l_e_n, _c_o_p_i_e_d__l_e_n))
          DDiissppllaayy    * _d_i_s_p_l_a_y;;
          WWiinnddooww     _w_i_n_d_o_w;;
          iinntt        _i_n_d_e_x;;
          XXttPPooiinntteerr  _f_o_r_m_a_t__n_a_m_e__b_u_f;;
          uunnssiiggnneedd lloonngg_b_u_f_f_e_r__l_e_n;;
          uunnssiiggnneedd lloonngg* _c_o_p_i_e_d__l_e_n;;

   DESCRIPTION
     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt returns a specified format name for the data
     item in the clipboard.  If the name must be truncated, the function
     returns a warning status.

     _d_i_s_p_l_a_y      Specifies a pointer to the DDiissppllaayy structure that was
                  returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w       Specifies a widget's window ID that relates the application
                  window to the clipboard.  The widget's window ID can be
                  obtained by using XXttWWiinnddooww.  The same application instance
                  should pass the same window ID to each of the clipboard
                  functions that it calls.

     _i_n_d_e_x        Specifies which of the ordered format names to obtain.  If
                  this index is greater than the number of formats for the
                  data item, this function returns a zero in the _c_o_p_i_e_d__l_e_n
                  argument.

     _f_o_r_m_a_t__n_a_m_e__b_u_f
                  Specifies the buffer that receives the format name.

     _b_u_f_f_e_r__l_e_n   Specifies the number of bytes in the format name buffer.

     _c_o_p_i_e_d__l_e_n   Specifies the number of bytes in the string copied to the
                  buffer.  If this argument equals zero, there is no _n_t_h for-
                  mat for the data item.









   2-151






   XmClipboardInquireFormat(3X)



   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                  The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                  The function failed because the clipboard was locked by
                  another application.  The application can continue to call
                  the function again with the same parameters until the lock
                  goes away.  This gives the application the opportunity to
                  ask if the user wants to keep trying or to give up on the
                  operation.

     CClliippbbooaarrddTTrruunnccaattee
                  The data returned is truncated because the user did not
                  provide a buffer large enough to hold the data.

     CClliippbbooaarrddNNooDDaattaa
                  The function could not find data on the clipboard
                  corresponding to the format requested.  This could occur
                  because the clipboard is empty; there is data on the clip-
                  board but not in the requested format; or the data in the
                  requested format was passed by name and is no longer avail-
                  able.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).




























   2-152






                                                 XmClipboardInquireLength(3X)



   NAME
     XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh-A clipboard function that returns the length of
     the stored data

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _f_o_r_m_a_t__n_a_m_e, _l_e_n_g_t_h))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          cchhaarr      * _f_o_r_m_a_t__n_a_m_e;;
          uunnssiiggnneedd lloonngg* _l_e_n_g_t_h;;

   DESCRIPTION
     XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh returns the length of the data stored under a
     specified format name for the clipboard data item.  If no data is found
     for the specified format, or if there is no item on the clipboard, this
     function returns a value of zero.

     Any format passed by name is assumed to have the _l_e_n_g_t_h passed in a call
     to XXmmCClliippbbooaarrddCCooppyy, even though the data has not yet been transferred to
     the clipboard in that format.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

     _f_o_r_m_a_t__n_a_m_e Specifies the name of the format for the data item.

     _l_e_n_g_t_h      Specifies the length of the next data item in the specified
                 format.  This argument equals zero if no data is found for
                 the specified format, or if there is no item on the clip-
                 board.














   2-153






   XmClipboardInquireLength(3X)



   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

     CClliippbbooaarrddNNooDDaattaa
                 The function could not find data on the clipboard
                 corresponding to the format requested.  This could occur
                 because the clipboard is empty; there is data on the clip-
                 board but not in the requested format; or the data in the
                 requested format was passed by name and is no longer avail-
                 able.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCooppyy((33XX)) and XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).
































   2-154






                                           XmClipboardInquirePendingItems(3X)



   NAME
     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss-A clipboard function that returns a list
     of _d_a_t_a__i_d/_p_r_i_v_a_t_e__i_d pairs

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _f_o_r_m_a_t__n_a_m_e,
               _i_t_e_m__l_i_s_t, _c_o_u_n_t))
          DDiissppllaayy          * _d_i_s_p_l_a_y;;
          WWiinnddooww           _w_i_n_d_o_w;;
          cchhaarr             * _f_o_r_m_a_t__n_a_m_e;;
          XXmmCClliippbbooaarrddPPeennddiinnggLLiisstt* _i_t_e_m__l_i_s_t;;
          uunnssiiggnneedd lloonngg    * _c_o_u_n_t;;

   DESCRIPTION
     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss returns a list of _d_a_t_a__i_d/_p_r_i_v_a_t_e__i_d
     pairs for the specified format name.  A data item is considered pending
     if the application originally passed it by name, the application has not
     yet copied the data, and the item has not been deleted from the clip-
     board.  The application is responsible for freeing the memory provided
     by this function to store the list.  To free the memory, call XXttFFrreeee.

     This function is used by an application when exiting, to determine if
     the data that is passed by name should be sent to the clipboard.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

     _f_o_r_m_a_t__n_a_m_e Specifies a string that contains the name of the format for
                 which the list of data ID/private ID pairs is to be
                 obtained.

     _i_t_e_m__l_i_s_t   Specifies the address of the array of data ID/private ID
                 pairs for the specified format name.  This argument is a
                 type XXmmCClliippbbooaarrddPPeennddiinnggLLiisstt.  The application is responsible
                 for freeing the memory provided by this function for storing
                 the list.

     _c_o_u_n_t       Specifies the number of items returned in the list.  If
                 there is no data for the specified format name, or if there
                 is no item on the clipboard, this argument equals zero.




   2-155






   XmClipboardInquirePendingItems(3X)



   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).








































   2-156






                                                          XmClipboardLock(3X)



   NAME
     XXmmCClliippbbooaarrddLLoocckk-A clipboard function that locks the clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddLLoocckk ((_d_i_s_p_l_a_y, _w_i_n_d_o_w))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;

   DESCRIPTION
     XXmmCClliippbbooaarrddLLoocckk locks the clipboard from access by another application
     until XXmmCClliippbbooaarrddUUnnlloocckk is called.  All clipboard functions lock and
     unlock the clipboard to prevent simultaneous access.  This function
     allows the application to keep the clipboard data from changing between
     calls to IInnqquuiirree and other clipboard functions.  The application does
     not need to lock the clipboard between calls to XXmmCClliippbbooaarrddSSttaarrttCCooppyy and
     XXmmCClliippbbooaarrddEEnnddCCooppyy or to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and XXmmCClliippbbooaarrddEEnnddRRee--
     ttrriieevvee.

     If the clipboard is already locked by another application, XXmmCClliipp--
     bbooaarrddLLoocckk returns an error status.  Multiple calls to this function by
     the same application increases the lock level.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.







   2-157






   XmClipboardLock(3X)



   RELATED INFORMATION
     XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)),
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)), and
     XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).



















































   2-158






                                                XmClipboardRegisterFormat(3X)



   NAME
     XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt-A clipboard function that registers a new for-
     mat

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt ((_d_i_s_p_l_a_y, _f_o_r_m_a_t__n_a_m_e, _f_o_r_m_a_t__l_e_n_g_t_h))
          DDiissppllaayy     * _d_i_s_p_l_a_y;;
          cchhaarr        * _f_o_r_m_a_t__n_a_m_e;;
          iinntt         _f_o_r_m_a_t__l_e_n_g_t_h;;

   DESCRIPTION
     XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt registers a new format.  Each format stored on
     the clipboard should have a length associated with it; this length must
     be known to the clipboard routines.  Formats are known as targets in the
     _I_n_t_e_r-_C_l_i_e_n_t _C_o_m_m_u_n_i_c_a_t_i_o_n _C_o_n_v_e_n_t_i_o_n_s _M_a_n_u_a_l (ICCCM).  All of the for-
     mats specified by the ICCCM conventions are preregistered.  Any other
     format that the application wants to use must either be 8-bit data or be
     registered via this routine.  Failure to register the length of the data
     results in incompatible applications across platforms having different
     byte-swapping orders.

     _d_i_s_p_l_a_y        Specifies a pointer to the DDiissppllaayy structure that was
                    returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _f_o_r_m_a_t__n_a_m_e    Specifies the string name for the new format (target).

     _f_o_r_m_a_t__l_e_n_g_t_h  Specifies the format length in bits (8, 16, or 32).

   RETURN VALUE

     CClliippbbooaarrddBBaaddFFoorrmmaatt
                    The _f_o_r_m_a_t__n_a_m_e must not be NULL, and the _f_o_r_m_a_t__l_e_n_g_t_h
                    must be 8, 16, or 32.

     CClliippbbooaarrddSSuucccceessss
                    The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                    The function failed because the clipboard was locked by
                    another application.  The application can continue to
                    call the function again with the same parameters until
                    the lock goes away.  This gives the application the
                    opportunity to ask if the user wants to keep trying or to
                    give up on the operation.

     CClliippbbooaarrddFFaaiill  The function failed because the format was already
                    registered with this length.



   2-159






   XmClipboardRegisterFormat(3X)


   RELATED INFORMATION
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).






















































   2-160






                                                      XmClipboardRetrieve(3X)



   NAME
     XXmmCClliippbbooaarrddRReettrriieevvee-A clipboard function that retrieves a data item from
     the clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _f_o_r_m_a_t__n_a_m_e,
               _b_u_f_f_e_r, _l_e_n_g_t_h, _n_u_m__b_y_t_e_s, _p_r_i_v_a_t_e__i_d))
          DDiissppllaayy    * _d_i_s_p_l_a_y;;
          WWiinnddooww     _w_i_n_d_o_w;;
          cchhaarr       * _f_o_r_m_a_t__n_a_m_e;;
          XXttPPooiinntteerr  _b_u_f_f_e_r;;
          uunnssiiggnneedd lloonngg_l_e_n_g_t_h;;
          uunnssiiggnneedd lloonngg* _n_u_m__b_y_t_e_s;;
          lloonngg       * _p_r_i_v_a_t_e__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddRReettrriieevvee retrieves the current data item from clipboard
     storage.  It returns a warning if the clipboard is locked; if there is
     no data on the clipboard; or if the data needs to be truncated because
     the buffer length is too short.

     Between a call to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and a call to XXmmCClliippbbooaarrddEEnn--
     ddRReettrriieevvee, multiple calls to XXmmCClliippbbooaarrddRReettrriieevvee with the same format
     name result in data being incrementally copied from the clipboard until
     the data in that format has all been copied.

     The return value CClliippbbooaarrddTTrruunnccaattee from calls to XXmmCClliippbbooaarrddRReettrriieevvee
     indicates that more data remains to be copied in the given format.  It
     is recommended that any calls to the IInnqquuiirree functions that the applica-
     tion needs to make to effect the copy from the clipboard be made between
     the call to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and the first call to XXmmCClliippbbooaarr--
     ddRReettrriieevvee.  That way, the application does not need to call XXmmCClliipp--
     bbooaarrddLLoocckk and XXmmCClliippbbooaarrddUUnnlloocckk.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

     _f_o_r_m_a_t__n_a_m_e Specifies the name of a format in which the data is stored
                 on the clipboard.

     _b_u_f_f_e_r      Specifies the buffer to which the application wants the
                 clipboard to copy the data.


   2-161






   XmClipboardRetrieve(3X)



     _l_e_n_g_t_h      Specifies the length of the application buffer.

     _n_u_m__b_y_t_e_s   Specifies the number of bytes of data copied into the appli-
                 cation buffer.

     _p_r_i_v_a_t_e__i_d  Specifies the private data stored with the data item by the
                 application that placed the data item on the clipboard.  If
                 the application did not store private data with the data
                 item, this argument returns zero.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

     CClliippbbooaarrddTTrruunnccaattee
                 The data returned is truncated because the user did not pro-
                 vide a buffer large enough to hold the data.

     CClliippbbooaarrddNNooDDaattaa
                 The function could not find data on the clipboard
                 corresponding to the format requested.  This could occur
                 because the clipboard is empty; there is data on the clip-
                 board but not in the requested format; or the data in the
                 requested format was passed by name and is no longer avail-
                 able.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)), and
     XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).
















   2-162






                                                     XmClipboardStartCopy(3X)



   NAME
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy-A clipboard function that sets up a storage and
     data structure

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddSSttaarrttCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _c_l_i_p__l_a_b_e_l,
               _t_i_m_e_s_t_a_m_p, _w_i_d_g_e_t, _c_a_l_l_b_a_c_k, _i_t_e_m__i_d))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          XXmmSSttrriinngg  _c_l_i_p__l_a_b_e_l;;
          TTiimmee      _t_i_m_e_s_t_a_m_p;;
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmCCuuttPPaasstteePPrroocc_c_a_l_l_b_a_c_k;;
          lloonngg      * _i_t_e_m__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy sets up storage and data structures to receive
     clipboard data.  An application calls this function during a cut or copy
     operation.  The data item that these structures receive then becomes the
     next data item in the clipboard.

     Copying a large piece of data to the clipboard can take a long time.  It
     is possible that, once copied, no application will ever request that
     data.  The Motif Toolkit provides a mechanism so that an application
     does not need to actually pass data to the clipboard until the data has
     been requested by some application.

     Instead, the application passes format and length information in XXmmCClliipp--
     bbooaarrddCCooppyy to the clipboard functions, along with a widget ID and a call-
     back function address that is passed in XXmmCClliippbbooaarrddSSttaarrttCCooppyy.  The
     widget ID is needed for communications between the clipboard functions
     in the application that owns the data and the clipboard functions in the
     application that requests the data.

     The callback functions are responsible for copying the actual data to
     the clipboard via XXmmCClliippbbooaarrddCCooppyyBByyNNaammee.  The callback function is also
     called if the data item is removed from the clipboard, and the actual
     data is therefore no longer needed.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.



   2-163






   XmClipboardStartCopy(3X)


     _c_l_i_p__l_a_b_e_l  Specifies the label to be associated with the data item.
                 This argument is used to identify the data item, for exam-
                 ple, in a clipboard viewer.  An example of a label is the
                 name of the application that places the data in the clip-
                 board.

     _t_i_m_e_s_t_a_m_p   Specifies the time of the event that triggered the copy.  A
                 valid timestamp must be supplied; it is not sufficient to
                 use CCuurrrreennttTTiimmee.

     _w_i_d_g_e_t      Specifies the ID of the widget that receives messages
                 requesting data previously passed by name.  This argument
                 must be present in order to pass data by name.  Any valid
                 widget ID in your application can be used for this purpose
                 and all the message handling is taken care of by the cut and
                 paste functions.

     _c_a_l_l_b_a_c_k    Specifies the address of the callback function that is
                 called when the clipboard needs data that was originally
                 passed by name.  This is also the callback to receive the
                 ddeelleettee message for items that were originally passed by
                 name.  This argument must be present in order to pass data
                 by name.

     _i_t_e_m__i_d     Specifies the number assigned to this data item.  The appli-
                 cation uses this number in calls to XXmmCClliippbbooaarrddCCooppyy, XXmmCClliipp--
                 bbooaarrddEEnnddCCooppyy, and XXmmCClliippbbooaarrddCCaanncceellCCooppyy.

     For more information on passing data by name, see XXmmCClliippbbooaarrddCCooppyy((33XX))
     and XXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX)).

     The _w_i_d_g_e_t and _c_a_l_l_b_a_c_k arguments must be present in order to pass data
     by name. The callback format is as follows:
     vvooiidd ((**_c_a_l_l_b_a_c_k) ((_w_i_d_g_e_t, _d_a_t_a__i_d, _p_r_i_v_a_t_e, _r_e_a_s_o_n))
       WWiiddggeett    _w_i_d_g_e_t;;
       iinntt       **_d_a_t_a__i_d;;
       iinntt       **_p_r_i_v_a_t_e;;
       iinntt       **_r_e_a_s_o_n;;

     _w_i_d_g_e_t      Specifies the ID of the widget passed to this function.

     _d_a_t_a__i_d     Specifies the identifying number returned by XXmmCClliippbbooaarrdd--
                 CCooppyy, which identifies the pass-by-name data.













   2-164






                                                     XmClipboardStartCopy(3X)



     _p_r_i_v_a_t_e     Specifies the private information passed to XXmmCClliippbbooaarrddCCooppyy.

     _r_e_a_s_o_n      Specifies the reason, which is either
                 XXmmCCRR__CCLLIIPPBBOOAARRDD__DDAATTAA__DDEELLEETTEE or XXmmCCRR__CCLLIIPPBBOOAARRDD__DDAATTAA__RREEQQUUEESSTT.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX)), XXmmCClliippbbooaarrddCCooppyy((33XX)),
     XXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)),
     XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XX)),
     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX)),
     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
     XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt((33XX)), XXmmCClliippbbooaarrddRReettrriieevvee((33XX)),
     XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX)),
     XXmmCClliippbbooaarrddUUnnlloocckk((33XX)), and XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((33XX)).




























   2-165






   XmClipboardStartRetrieve(3X)



   NAME
     XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee-A clipboard function that starts a copy from
     the clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _t_i_m_e_s_t_a_m_p))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          TTiimmee      _t_i_m_e_s_t_a_m_p;;

   DESCRIPTION
     XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee tells the clipboard routines that the applica-
     tion is ready to start copying an item from the clipboard.  The clip-
     board is locked by this routine and stays locked until XXmmCClliippbbooaarrddEEnnddRRee--
     ttrriieevvee is called.  Between a call to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and a call
     to XXmmCClliippbbooaarrddEEnnddRReettrriieevvee, multiple calls to XXmmCClliippbbooaarrddRReettrriieevvee with
     the same format name result in data being incrementally copied from the
     clipboard until the data in that format has all been copied.

     The return value CClliippbbooaarrddTTrruunnccaattee from calls to XXmmCClliippbbooaarrddRReettrriieevvee
     indicates that more data remains to be copied in the given format.  It
     is recommended that any calls to the IInnqquuiirree functions that the applica-
     tion needs to make to effect the copy from the clipboard be made between
     the call to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and the first call to XXmmCClliippbbooaarr--
     ddRReettrriieevvee.  That way, the application does not need to call XXmmCClliipp--
     bbooaarrddLLoocckk and XXmmCClliippbbooaarrddUUnnlloocckk.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

     _t_i_m_e_s_t_a_m_p   Specifies the time of the event that triggered the copy.  A
                 valid timestamp must be supplied; it is not sufficient to
                 use CCuurrrreennttTTiimmee.











   2-166






                                                 XmClipboardStartRetrieve(3X)



   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XX)),
     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX)),
     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
     XXmmCClliippbbooaarrddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), and
     XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).




































   2-167






   XmClipboardUndoCopy(3X)



   NAME
     XXmmCClliippbbooaarrddUUnnddooCCooppyy-A clipboard function that deletes the last item
     placed on the clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddUUnnddooCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;

   DESCRIPTION
     XXmmCClliippbbooaarrddUUnnddooCCooppyy deletes the last item placed on the clipboard if the
     item was placed there by an application with the passed _d_i_s_p_l_a_y and _w_i_n_-
     _d_o_w arguments.  Any data item deleted from the clipboard by the original
     call to XXmmCClliippbbooaarrddCCooppyy is restored.  If the _d_i_s_p_l_a_y or _w_i_n_d_o_w IDs do
     not match the last copied item, no action is taken, and this function
     has no effect.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each clipboard function it
                 calls.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddLLoocckk((33XX)) and XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).









   2-168






                                                        XmClipboardUnlock(3X)



   NAME
     XXmmCClliippbbooaarrddUUnnlloocckk-A clipboard function that unlocks the clipboard

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddUUnnlloocckk ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _r_e_m_o_v_e__a_l_l__l_o_c_k_s))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          BBoooolleeaann   _r_e_m_o_v_e__a_l_l__l_o_c_k_s;;

   DESCRIPTION
     XXmmCClliippbbooaarrddUUnnlloocckk unlocks the clipboard, enabling it to be accessed by
     other applications.

     If multiple calls to XXmmCClliippbbooaarrddLLoocckk have occurred, the same number of
     calls to XXmmCClliippbbooaarrddUUnnlloocckk is necessary to unlock the clipboard, unless
     _r_e_m_o_v_e__a_l_l__l_o_c_k_s is set to True.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each of the clipboard
                 functions that it calls.

     _r_e_m_o_v_e__a_l_l__l_o_c_k_s
                 When True, indicates that all nested locks should be
                 removed.  When False, indicates that only one level of lock
                 should be removed.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddFFaaiill
                 The function failed because the clipboard was not locked or
                 was locked by another application.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX)), XXmmCClliippbbooaarrddCCooppyy((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)),
     XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XX)),
     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX)),
     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
     XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt((33XX)), XXmmCClliippbbooaarrddRReettrriieevvee((33XX)),
     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)),
     XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX)), and XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((33XX)).


   2-169






   XmClipboardWithdrawFormat(3X)



   NAME
     XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt-A clipboard function that indicates that the
     application no longer wants to supply a data item

   AES SUPPORT LEVEL
     Full-use

   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//CCuuttPPaassttee..hh>>
     iinntt XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _d_a_t_a__i_d))
          DDiissppllaayy   * _d_i_s_p_l_a_y;;
          WWiinnddooww    _w_i_n_d_o_w;;
          lloonngg      _d_a_t_a__i_d;;

   DESCRIPTION
     XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt indicates that the application no longer sup-
     plies a data item to the clipboard that the application had previously
     passed by name.

     _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure that was
                 returned in a previous call to XXOOppeennDDiissppllaayy or XXttDDiissppllaayy.

     _w_i_n_d_o_w      Specifies a widget's window ID that relates the application
                 window to the clipboard.  The widget's window ID can be
                 obtained by using XXttWWiinnddooww.  The same application instance
                 should pass the same window ID to each clipboard function it
                 calls.

     _d_a_t_a__i_d     Specifies an identifying number assigned to the data item
                 that uniquely identifies the data item and the format.  This
                 was assigned to the item when it was originally passed by
                 XXmmCClliippbbooaarrddCCooppyy.

   RETURN VALUE

     CClliippbbooaarrddSSuucccceessss
                 The function is successful.

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock
                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

   RELATED INFORMATION
     XXmmCClliippbbooaarrddCCooppyy((33XX)) and XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).






   2-170






                                                                XmCommand(3X)



   NAME
     XXmmCCoommmmaanndd-The Command widget class

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>

   DESCRIPTION
     Command is a special-purpose composite widget for command entry that
     provides a built-in command-history mechanism.  Command includes a
     command-line text-input field, a command-line prompt, and a command-
     history list region.

     One additional WWoorrkkAArreeaa child may be added to the Command after crea-
     tion.

     Whenever a command is entered, it is automatically added to the end of
     the command-history list and made visible.  This does not change the
     selected item in the list, if there is one.

     Many of the new resources specified for Command are actually Selection-
     Box resources that have been renamed for clarity and ease of use.

     Classes

     Command 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, XXmmBBuulllleettiinnBBooaarrdd, and XXmmSSeelleeccttiioonnBBooxx classes.

     The class pointer is xxmmCCoommmmaannddWWiiddggeettCCllaassss.

     The class name is XXmmCCoommmmaanndd.

     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mCCoommmmaannd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
   ____________________________________________________________________________________
   XmNcommand                   XmCTextString         XmString         ""        CSG
   XmNcommandChangedCallback    XmCCallback           XtCallbackList   NULL      C
   XmNcommandEnteredCallback    XmCCallback           XtCallbackList   NULL      C


   2-171






   XmCommand(3X)


   XmNhistoryItems              XmCItems              XmStringTable    NULL      CSG
   XmNhistoryItemCount          XmCItemCount          int              0         CSG
   XmNhistoryMaxItems           XmCMaxItems           int              100       CSG
   XmNhistoryVisibleItemCount   XmCVisibleItemCount   int              dynamic   CSG
   XmNpromptString              XmCPromptString       XmString         dynamic   CSG

     XXmmNNccoommmmaanndd
               Contains the current command-line text.  This is the XXmmNNtteexxtt--
               SSttrriinngg resource in SelectionBox, renamed for Command.  This
               resource can also be modified via XXmmCCoommmmaannddSSeettVVaalluuee and XXmmCCoomm--
               mmaannddAAppppeennddVVaalluuee functions.  The command area is a Text widget.

     XXmmNNccoommmmaannddCChhaannggeeddCCaallllbbaacckk
               Specifies the list of callbacks that is called when the value
               of the command changes.  The callback reason is
               XXmmCCRR__CCOOMMMMAANNDD__CCHHAANNGGEEDD.  This is equivalent to the
               XXmmNNvvaalluueeCChhaannggeeddCCaallllbbaacckk of the Text widget, except that a
               pointer to an XXmmCCoommmmaannddCCaallllbbaacckkSSttrruuccttuurree is passed, and the
               structure's _v_a_l_u_e member contains the XXmmSSttrriinngg.

     XXmmNNccoommmmaannddEEnntteerreeddCCaallllbbaacckk
               Specifies the list of callbacks that is called when a command
               is entered in the Command.  The callback reason is
               XXmmCCRR__CCOOMMMMAANNDD__EENNTTEERREEDD.  A pointer to an XXmmCCoommmmaannddCCaallllbbaacckk
               structure is passed.

     XXmmNNhhiissttoorryyIItteemmss
               Lists XXmmSSttrriinngg items that make up the contents of the history
               list.  This is the XXmmNNlliissttIItteemmss resource in SelectionBox,
               renamed for Command.

     XXmmNNhhiissttoorryyIItteemmCCoouunntt
               Specifies the number of XXmmSSttrriinnggss in XXmmNNhhiissttoorryyIItteemmss.  This is
               the XXmmNNlliissttIItteemmCCoouunntt resource in SelectionBox, renamed for
               Command.  The value must not be negative.

     XXmmNNhhiissttoorryyMMaaxxIItteemmss
               Specifies the maximum number of items allowed in the history
               list.  Once this number is reached, an existing list item must
               be removed before a new item can be added to the list.  For
               each command entered, the first list item is removed from the
               list, so the new command can be added to the list.  The value
               must be greater than 0.

     XXmmNNhhiissttoorryyVViissiibblleeIItteemmCCoouunntt
               Specifies the number of items in the history list that should
               be visible at one time.  In effect, it sets the height (in
               lines) of the history list window.  This is the XXmmNNlliissttVViissii--
               bblleeIItteemmCCoouunntt resource in SelectionBox, renamed for Command.
               The value must be greater than 0.  The default is dynamic
               based on the height of the list.

     XXmmNNpprroommppttSSttrriinngg
               Specifies a prompt for the command line.  This is the


   2-172






                                                                XmCommand(3X)


               XXmmNNsseelleeccttiioonnLLaabbeellSSttrriinngg resource in SelectionBox, renamed for
               Command.  The default may vary depending on the value of the
               XXmmNNssttrriinnggDDiirreeccttiioonn resource and the locale.  In the C locale
               the default is ">".

     Inherited Resources

     Command 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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                N/A
   XmNapplyLabelString       XmCApplyLabelString       XmString         dynamic             N/A
   XmNcancelCallback         XmCCallback               XtCallbackList   NULL                N/A
   XmNcancelLabelString      XmCCancelLabelString      XmString         dynamic             N/A
   XmNdialogType             XmCDialogType             unsigned char    XmDIALOG_COMMAND    G
   XmNhelpLabelString        XmCHelpLabelString        XmString         dynamic             N/A
   XmNlistItemCount          XmCItemCount              int              0                   CSG
   XmNlistItems              XmCItems                  XmStringTable    NULL                CSG
   XmNlistLabelString        XmCListLabelString        XmString         NULL                N/A
   XmNlistVisibleItemCount   XmCVisibleItemCount       int              dynamic             CSG
   XmNminimizeButtons        XmCMinimizeButtons        Boolean          False               N/A
   XmNmustMatch              XmCMustMatch              Boolean          False               N/A
   XmNnoMatchCallback        XmCCallback               XtCallbackList   NULL                N/A
   XmNokCallback             XmCCallback               XtCallbackList   NULL                N/A
   XmNokLabelString          XmCOkLabelString          XmString         dynamic             N/A
   XmNselectionLabelString   XmCSelectionLabelString   XmString         dynamic             CSG
   XmNtextAccelerators       XmCTextAccelerators       XtAccelerators   default             C
   XmNtextColumns            XmCColumns                short            dynamic             CSG
   XmNtextString             XmCTextString             XmString         ""                  CSG
                              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          False           N/A
   XmNbuttonFontList     XmCButtonFontList    XmFontList       dynamic         N/A
   XmNcancelButton       XmCWidget            Widget           NULL            N/A
   XmNdefaultButton      XmCWidget            Widget           NULL            N/A
   XmNdefaultPosition    XmCDefaultPosition   Boolean          False           CSG
   XmNdialogStyle        XmCDialogStyle       unsigned char    dynamic         CSG
   XmNdialogTitle        XmCDialogTitle       XmString         NULL            CSG
   XmNfocusCallback      XmCCallback          XtCallbackList   NULL            C
   XmNlabelFontList      XmCLabelFontList     XmFontList       dynamic         CSG
   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_NONE   CSG
   XmNshadowType         XmCShadowType        unsigned char    XmSHADOW_OUT    CSG
   XmNtextFontList       XmCTextFontList      XmFontList       dynamic         CSG
   XmNtextTranslations   XmCTranslations      XtTranslations   NULL            C
   XmNunmapCallback      XmCCallback          XtCallbackList   NULL            C


   2-173






   XmCommand(3X)


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


   2-174






                                                                XmCommand(3X)


     }} XXmmCCoommmmaannd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

     _v_a_l_u_e  Specifies the XXmmSSttrriinngg in the CommandArea

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

     Action Routines

     The XmCommand 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 history list and replaces the text with that item.  When
               called with a 1 argument, selects the next item in the history
               list and replaces the text with that item.  When called with a
               2 argument, selects the first item in the history list and
               replaces the text with that item.  When called with a 3 argu-
               ment, selects the last item in the history list and replaces
               the text with that item.  Calls the callbacks for XXmmNNccoomm--
               mmaannddCChhaannggeeddCCaallllbbaacckk.

   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CoommmmaannddAAppppeennddVVaalluuee((33XX)), XXmmCCoommmmaannddEErrrroorr((33XX)), XXmmCCoommmmaannddGGeettCChhiilldd((33XX)),
     XXmmCCoommmmaannddSSeettVVaalluuee((33XX)), XXmmCCrreeaatteeCCoommmmaanndd((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x((33XX)).


























   2-175






   XmCommandAppendValue(3X)



   NAME
     XXmmCCoommmmaannddAAppppeennddVVaalluuee-A Command function that appends the passed XmString
     to the end of the string displayed in the command area of the widget

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>
     vvooiidd XXmmCCoommmmaannddAAppppeennddVVaalluuee ((_w_i_d_g_e_t, _c_o_m_m_a_n_d))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  _c_o_m_m_a_n_d;;

   DESCRIPTION
     XXmmCCoommmmaannddAAppppeennddVVaalluuee appends the passed XXmmSSttrriinngg to the end of the
     string displayed in the command area of the Command widget.

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

     _c_o_m_m_a_n_dSpecifies the passed XXmmSSttrriinngg

     For a complete definition of Command and its associated resources, see
     XXmmCCoommmmaanndd((33XX)).

   RELATED INFORMATION
     XXmmCCoommmmaanndd((33XX)).





























   2-176






                                                           XmCommandError(3X)



   NAME
     XXmmCCoommmmaannddEErrrroorr-A Command function that displays an error message

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>
     vvooiidd XXmmCCoommmmaannddEErrrroorr ((_w_i_d_g_e_t, _e_r_r_o_r))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  _e_r_r_o_r;;

   DESCRIPTION
     XXmmCCoommmmaannddEErrrroorr displays an error message in the history area of the Com-
     mand widget.  The XXmmSSttrriinngg error is displayed until the next command
     entered occurs.

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

     _e_r_r_o_r  Specifies the passed XXmmSSttrriinngg

     For a complete definition of Command and its associated resources, see
     XXmmCCoommmmaanndd((33XX)).

   RELATED INFORMATION
     XXmmCCoommmmaanndd((33XX)).





























   2-177






   XmCommandGetChild(3X)



   NAME
     XXmmCCoommmmaannddGGeettCChhiilldd-A Command function that is used to access a component

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>
     WWiiddggeett XXmmCCoommmmaannddG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mCCoommmmaannddGGeettCChhiilldd is used to access a component within a Command.  The
     parameters given to the function are the Command widget and a value
     indicating which component to access.

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

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

              ++oo  XXmmDDIIAALLOOGG__CCOOMMMMAANNDD__TTEEXXTT

              ++oo  XXmmDDIIAALLOOGG__PPRROOMMPPTT__LLAABBEELL

              ++oo  XXmmDDIIAALLOOGG__HHIISSTTOORRYY__LLIISST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 Command and its associated resources, see
     XXmmCCoommmmaanndd((33XX)).

   RETURN VALUE
     Returns the widget ID of the specified Command component.  An applica-
     tion should not assume that the returned widget will be of any particu-
     lar class.

   RELATED INFORMATION
     XXmmCCoommmmaanndd((33XX)).















   2-178






                                                        XmCommandSetValue(3X)



   NAME
     XXmmCCoommmmaannddSSeettVVaalluuee-A Command function that replaces a displayed string

   AES SUPPORT LEVEL
     Full-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>
     vvooiidd XXmmCCoommmmaannddSSeettVVaalluuee ((_w_i_d_g_e_t, _c_o_m_m_a_n_d))
          WWiiddggeett    _w_i_d_g_e_t;;
          XXmmSSttrriinngg  _c_o_m_m_a_n_d;;

   DESCRIPTION
     XXmmCCoommmmaannddSSeettVVaalluuee replaces the string displayed in the command area of
     the Command widget with the passed XXmmSSttrriinngg.

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

     _c_o_m_m_a_n_dSpecifies the passed XXmmSSttrriinngg

     For a complete definition of Command and its associated resources, see
     XXmmCCoommmmaanndd((33XX)).

   RELATED INFORMATION
     XXmmCCoommmmaanndd((33XX)).






























   2-179






   XmConvertUnits(3X)



   NAME
     XXmmCCoonnvveerrttUUnniittss-A function that converts a value in one unit type to
     another unit type

   AES SUPPORT LEVEL
     Trial-use

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     iinntt XXmmCCoonnvveerrttUUnniittss ((_w_i_d_g_e_t, _o_r_i_e_n_t_a_t_i_o_n, _f_r_o_m__u_n_i_t__t_y_p_e,
               _f_r_o_m__v_a_l_u_e, _t_o__u_n_i_t__t_y_p_e))
          WWiiddggeett    _w_i_d_g_e_t;;
          iinntt       _o_r_i_e_n_t_a_t_i_o_n;;
          iinntt       _f_r_o_m__u_n_i_t__t_y_p_e;;
          iinntt       _f_r_o_m__v_a_l_u_e;;
          iinntt       _t_o__u_n_i_t__t_y_p_e;;

   DESCRIPTION
     XXmmCCoonnvveerrttUUnniittss converts the value and returns it as the return value
     from the function.

     _w_i_d_g_e_t      Specifies the widget for which the data is to be converted

     _o_r_i_e_n_t_a_t_i_o_n Specifies whether the converter uses the horizontal or vert-
                 ical screen resolution when performing the conversions.
                 _o_r_i_e_n_t_a_t_i_o_n can have values of XXmmHHOORRIIZZOONNTTAALL or XXmmVVEERRTTIICCAALL.

     _f_r_o_m__u_n_i_t__t_y_p_e
                 Specifies the current unit type of the supplied value

     _f_r_o_m__v_a_l_u_e  Specifies the value to be converted

     _t_o__u_n_i_t__t_y_p_e
                 Converts the value to the unit type specified

     The parameters _f_r_o_m__u_n_i_t__t_y_p_e and _t_o__u_n_i_t__t_y_p_e can have the following
     values:

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

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

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

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





   2-180






                                                           XmConvertUnits(3X)


   RETURN VALUE
     Returns the converted value.  If a NULL widget, incorrect _o_r_i_e_n_t_a_t_i_o_n,
     or incorrect _u_n_i_t__t_y_p_e is supplied as parameter data, 0 is returned.





















































   2-181



 d
