


     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



     NNAAMMEE
          XXmmCCaassccaaddeeBBuuttttoonn-The CascadeButton widget class

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//CCaassccaaddeeBB..hh>>


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



     2-148                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



          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 defaults to 6
          if this resource is in a MenuBar; otherwise, it takes
          Label's default, which is 2.

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

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the XXmmNN or XXmmCC
          prefix and use the remaining letters.  To specify one of the
          defined values for a resource in a .Xdefaults file, remove
          the XXmm prefix and use the remaining letters (in either
          lowercase or uppercase, but include any underscores between
          words).  The codes in the access column indicate if the
          given resource can be set at creation time (C), set by using
          XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
          not applicable (N/A).

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











     2-149                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



          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nTToopp may be modified to ensure that
                    room is left for the cascade 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 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 associated with this CascadeButton.  The
                    specified MenuPane is displayed when the
                    CascadeButton 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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.











     2-150                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



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







     2-151                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



     XmNaccelerators                 XmCAccelerators                 XtAccelerators   dynamic                CSG
     XmNancestorSensitive            XmCSensitive                    Boolean          dynamic                G
     XmNbackground                   XmCBackground                   Pixel            dynamic                CSG
     XmNbackgroundPixmap             XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
     XmNborderColor                  XmCBorderColor                  Pixel            XtDefaultForeground    CSG
     XmNborderPixmap                 XmCPixmap                       Pixmap           XmUNSPECIFIED_PIXMAP   CSG
     XmNborderWidth                  XmCBorderWidth                  Dimension        0                      CSG
     XmNcolormap                     XmCColormap                     Colormap         dynamic                CG
     XmNdepth                        XmCDepth                        int              dynamic                CG
     XmNdestroyCallback              XmCCallback                     XtCallbackList   NULL                   C
     XmNheight                       XmCHeight                       Dimension        dynamic                CSG
     XmNinitialResourcesPersistent   XmCInitialResourcesPersistent   Boolean          True                   C
     XmNmappedWhenManaged            XmCMappedWhenManaged            Boolean          True                   CSG
     XmNscreen                       XmCScreen                       Screen *         dynamic                CG
     XmNsensitive                    XmCSensitive                    Boolean          True                   CSG
     XmNtranslations                 XmCTranslations                 XtTranslations   dynamic                CSG
     XmNwidth                        XmCWidth                        Dimension        dynamic                CSG
     XmNx                            XmCPosition                     Position         0                      CSG
     XmNy                            XmCPosition                     Position         0                      CSG

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


        AAccttiioonn RRoouuttiinneess
          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 keyboard focus to the
                    widget that had the focus before the menu was
                    entered.







     2-152                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



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

                    In a Popup MenuPane, unposts the menu and, when
                    the shell's keyboard focus policy is XXmmEEXXPPLLIIC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 CascadeButton 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



     2-153                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonn((33XX))      RReeffeerreennccee PPaaggeess      XXmmCCaassccaaddeeBBuuttttoonn((33XX))



                    is already active, this event disables keyboard
                    traversal for the menu and returns the menu to
                    mouse traversal mode.


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          CCoorree((33XX)), XXmmC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-154                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//CCaassccaaddeeBBGG..hh>>


     DDEESSCCRRIIPPTTIIOONN
          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 controls the behavior of the
          CascadeButtonGadget.  In addition, BBMMeennuu controls the
          behavior of the CascadeButtonGadget if it resides in a
          PopupMenu 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



     2-155                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX))



          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.

          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; otherwise,
          it takes LabelGadget's default, which is 2.

        CCllaasssseess
          CascadeButtonGadget inherits behavior and resources from
          OObbjjeecctt, RReecct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.

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the XXmmNN or XXmmCC
          prefix and use the remaining letters.  To specify one of the
          defined values for a resource in a .Xdefaults file, remove
          the XXmm prefix and use the remaining letters (in either
          lowercase or uppercase, but include any underscores between
          words).  The codes in the access column indicate if the
          given resource can be set at creation time (C), set by using
          XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
          not applicable (N/A).

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



     2-156                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX))



                    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nR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 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 CascadeButtonGadget.  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 submenu.  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 associated 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 systems.


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






     2-157                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX))



     NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                AAcccceessss
     _________________________________________________________________________________________________________
     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
     ___________________________________________________________________________________
     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

        CCaallllbbaacckk IInnffoorrmmaattiioonn
          A pointer to the following structure is passed to each
          callback:




     2-158                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX))



          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.


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          OObbjjeecctt((33XX)), RReeccttOObbjj((33XX)), XXmmC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-159                                            (printed 5/7/92)






     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lRRieiegfgfhehetrtr(e(e3n3nXXXcmXcm)eC)eC aaPsPsacacgagaededses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))



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

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

     HHIISSTTOORRYY//DDIIRREECCTTIIOONN
          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.

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


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

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






     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RRXeXe)f)feerreennccee PPaaggXXememsCs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))



     NNAAMMEE
          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 function that sets the highlight state

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//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;;


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

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






     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))RReeffeerreennccee PPaaggeessXXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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


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



     2-162                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX))



                      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.


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






     XXmmCClliippbbooaarrddCCooppyy((33XX))      RReeffeerreennccee PPaaggeess      XXmmCClliippbbooaarrddCCooppyy((33XX))



     NNAAMMEE
          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 temporary storage for later copying to clipboard

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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





     2-164                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddCCooppyy((33XX))      RReeffeerreennccee PPaaggeess      XXmmCClliippbbooaarrddCCooppyy((33XX))



          _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_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pb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 clipboard.

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


     RREETTUURRNN VVAALLUUEE
          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-165                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddCCooppyy((33XX))      RReeffeerreennccee PPaaggeess      XXmmCClliippbbooaarrddCCooppyy((33XX))



     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmC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-166                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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



     2-167                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX))



                    wants to store with the data item.


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


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






     XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX))   RReeffeerreennccee PPaaggeess   XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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
          applications, 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pbbooaarrddSSttaarrttCCooppyy.


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



     2-169                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX))   RReeffeerreennccee PPaaggeess   XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX))



                      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.


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






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



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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


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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN



     2-171                                            (printed 5/7/92)






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






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



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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

          _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-173                                            (printed 5/7/92)






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



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


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






     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3RRXeXe)f)feerreennccee PPaaggXXememsCs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))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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



     2-175                                            (printed 5/7/92)






     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3RRXeXe)f)feerreennccee PPaaggXXememsCs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))



                       copied to the buffer.  If this argument equals
                       zero, there is no _n_t_h format for the data item.


     RREETTUURRNN VVAALLUUEE
          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
                       clipboard but not in the requested format; or
                       the data in the requested format was passed by
                       name and is no longer available.


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






     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3RRXeXe)f)feerreennccee PPaaggXXememsCs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))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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






     2-177                                            (printed 5/7/92)






     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3RRXeXe)f)feerreennccee PPaaggXXememsCs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))



     RREETTUURRNN VVAALLUUEE
          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 clipboard but not in the
                      requested format; or the data in the requested
                      format was passed by name and is no longer
                      available.


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






     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IRRteteefefmemesrsr(e(e3n3nXXXcmXcm)eC)eC llPiPiapapgbgbeoeosas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))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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



     2-179                                            (printed 5/7/92)






     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IRRteteefefmemesrsr(e(e3n3nXXXcmXcm)eC)eC llPiPiapapgbgbeoeosas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))



                      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.


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


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






     XXmmCClliippbbooaarrddLLoocckk((33XX))      RReeffeerreennccee PPaaggeess      XXmmCClliippbbooaarrddLLoocckk((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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ettrriieevvee.

          If the clipboard is already locked by another application,
          XXmmCClliippb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.












     2-181                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddLLoocckk((33XX))      RReeffeerreennccee PPaaggeess      XXmmCClliippbbooaarrddLLoocckk((33XX))



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


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






     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((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCsls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))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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


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



     2-183                                            (printed 5/7/92)






     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((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCsls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))



                         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.


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






     XXmmCClliippbbooaarrddRReettrriieevvee((33XX))  RReeffeerreennccee PPaaggeess  XXmmCClliippbbooaarrddRReettrriieevvee((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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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 application 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rddRReettrriieevvee.  That way, the application does not
          need to call XXmmCClliippb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



     2-185                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddRReettrriieevvee((33XX))  RReeffeerreennccee PPaaggeess  XXmmCClliippbbooaarrddRReettrriieevvee((33XX))



                      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.

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


     RREETTUURRNN VVAALLUUEE
          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 clipboard but not in the
                      requested format; or the data in the requested
                      format was passed by name and is no longer
                      available.







     2-186                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddRReettrriieevvee((33XX))  RReeffeerreennccee PPaaggeess  XXmmCClliippbbooaarrddRReettrriieevvee((33XX))



     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmC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-187                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)) RReeffeerreennccee PPaaggeess XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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pbbooaarrddCCooppyy to the clipboard functions,
          along with a widget ID and a callback 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



     2-188                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)) RReeffeerreennccee PPaaggeess XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX))



                      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.

          _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 example, in a clipboard
                      viewer.  An example of a label is the name of
                      the application that places the data in the
                      clipboard.

          _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 application 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pb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;;



     2-189                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)) RReeffeerreennccee PPaaggeess XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX))



            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dCCooppyy, which identifies the pass-by-
                      name data.

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


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


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






     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3RRXeXe)f)feerreennccee PPaaggXXememsCs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))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


     DDEESSCCRRIIPPTTIIOONN
          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 application is ready to start copying an item from the
          clipboard.  The clipboard 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et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 application 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rddRReettrriieevvee.  That way, the application does not
          need to call XXmmCClliippb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-191                                            (printed 5/7/92)






     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3RRXeXe)f)feerreennccee PPaaggXXememsCs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))



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


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






     XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX))  RReeffeerreennccee PPaaggeess  XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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


     RREETTUURRNN VVAALLUUEE
          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-193                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX))  RReeffeerreennccee PPaaggeess  XXmmCClliippbbooaarrddUUnnddooCCooppyy((33XX))



     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmC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-194                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddUUnnlloocckk((33XX))    RReeffeerreennccee PPaaggeess    XXmmCClliippbbooaarrddUUnnlloocckk((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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


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





     2-195                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddUUnnlloocckk((33XX))    RReeffeerreennccee PPaaggeess    XXmmCClliippbbooaarrddUUnnlloocckk((33XX))



     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmC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-196                                            (printed 5/7/92)






     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((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCsls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))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##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;;


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


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



     2-197                                            (printed 5/7/92)






     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((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCsls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))



                      the user wants to keep trying or to give up on
                      the operation.


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






     XXmmCCoommmmaanndd((33XX))            RReeffeerreennccee PPaaggeess            XXmmCCoommmmaanndd((33XX))



     NNAAMMEE
          XXmmCCoommmmaanndd-The Command widget class

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//CCoommmmaanndd..hh>>


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

          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
          SelectionBox resources that have been renamed for clarity
          and ease of use.

        CCllaasssseess
          Command inherits behavior and resources from CCoorree,
          CCoommppoossiittee, CCoonnssttrraaiinntt, 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.

        NNeeww RReessoouurrcceess
          The following table defines a set of widget resources used
          by the programmer to specify data.  The programmer can also
          set the resource values for the inherited classes to set
          attributes for this widget.  To reference a resource by name
          or by class in a .Xdefaults file, remove the XXmmNN or XXmmCC
          prefix and use the remaining letters.  To specify one of the
          defined values for a resource in a .Xdefaults file, remove
          the XXmm prefix and use the remaining letters (in either
          lowercase or uppercase, but include any underscores between
          words).  The codes in the access column indicate if the
          given resource can be set at creation time (C), set by using
          XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
          not applicable (N/A).




     2-199                                            (printed 5/7/92)






     XXmmCCoommmmaanndd((33XX))            RReeffeerreennccee PPaaggeess            XXmmCCoommmmaanndd((33XX))



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



     2-200                                            (printed 5/7/92)






     XXmmCCoommmmaanndd((33XX))            RReeffeerreennccee PPaaggeess            XXmmCCoommmmaanndd((33XX))



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


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







     2-201                                            (printed 5/7/92)






     XXmmCCoommmmaanndd((33XX))            RReeffeerreennccee PPaaggeess            XXmmCCoommmmaanndd((33XX))



     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

                                          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







     2-202                                            (printed 5/7/92)






     XXmmCCoommmmaanndd((33XX))            RReeffeerreennccee PPaaggeess            XXmmCCoommmmaanndd((33XX))



     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

        CCaallllbbaacckk IInnffoorrmmaattiioonn
          A pointer to the following structure is passed to each
          callback:

          ttyyppeeddeeff ssttrruucctt
          {{
            iinntt      _r_e_a_s_o_n;;
            XXEEvveenntt   * _e_v_e_n_t;;
            XXmmSSttrriinngg _v_a_l_u_e;;
            iinntt      _l_e_n_g_t_h;;
          }} 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


        AAccttiioonn RRoouuttiinneess
          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)):



     2-203                                            (printed 5/7/92)






     XXmmCCoommmmaanndd((33XX))            RReeffeerreennccee PPaaggeess            XXmmCCoommmmaanndd((33XX))



                    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 argument, 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mmmaannddCChhaannggeeddCCaallllbbaacckk.


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






     XXmmCCoommmmaannddAAppppeennddVVaalluuee((33XX)) RReeffeerreennccee PPaaggeess XXmmCCoommmmaannddAAppppeennddVVaalluuee((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//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;;


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCCoommmmaanndd((33XX)).























     2-205                                            (printed 5/7/92)






     XXmmCCoommmmaannddEErrrroorr((33XX))       RReeffeerreennccee PPaaggeess       XXmmCCoommmmaannddEErrrroorr((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//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;;


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCCoommmmaanndd((33XX)).
























     2-206                                            (printed 5/7/92)






     XXmmCCoommmmaannddGGeettCChhiilldd((33XX))    RReeffeerreennccee PPaaggeess    XXmmCCoommmmaannddGGeettCChhiilldd((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//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;;


     DDEESSCCRRIIPPTTIIOONN
          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  XXmmDDIIAALLOOGG__CCOOMMMMAANNDD__TTEEXXTT

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

                   +o  XXmmDDIIAALLOOGG__HHIISSTTOORRYY__LLIISSTT

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

     RREETTUURRNN VVAALLUUEE
          Returns the widget ID of the specified Command component.
          An application should not assume that the returned widget
          will be of any particular class.

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCCoommmmaanndd((33XX)).








     2-207                                            (printed 5/7/92)






     XXmmCCoommmmaannddSSeettVVaalluuee((33XX))    RReeffeerreennccee PPaaggeess    XXmmCCoommmmaannddSSeettVVaalluuee((33XX))



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

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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//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;;


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCCoommmmaanndd((33XX)).

























     2-208                                            (printed 5/7/92)






     XXmmCCoonnvveerrttUUnniittss((33XX))       RReeffeerreennccee PPaaggeess       XXmmCCoonnvveerrttUUnniittss((33XX))



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

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

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

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


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



     2-209                                            (printed 5/7/92)






     XXmmCCoonnvveerrttUUnniittss((33XX))       RReeffeerreennccee PPaaggeess       XXmmCCoonnvveerrttUUnniittss((33XX))



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

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


     RREETTUURRNN VVAALLUUEE
          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-210                                            (printed 5/7/92)



 
