


   XmActivateProtocol(3X)



   NAME
     XXmmAAccttiivvaatteePPrroottooccooll-A VendorShell function that activates a protocol

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//PPrroottooccoollss..hh>>
     vvooiidd XXmmAAccttiivvaatteePPrroottooccooll ((_s_h_e_l_l, _p_r_o_p_e_r_t_y, _p_r_o_t_o_c_o_l))
          WWiiddggeett    _s_h_e_l_l;;
          AAttoomm      _p_r_o_p_e_r_t_y;;
          AAttoomm      _p_r_o_t_o_c_o_l;;
     vvooiidd XXmmAAccttiivvaatteeWWMMPPrroottooccooll ((_s_h_e_l_l, _p_r_o_t_o_c_o_l))
          WWiiddggeett    _s_h_e_l_l;;
          AAttoomm      _p_r_o_t_o_c_o_l;;

   DESCRIPTION
     XXmmAAccttiivvaatteePPrroottooccooll activates a protocol.  It updates the handlers and
     the _p_r_o_p_e_r_t_y if the _s_h_e_l_l is realized.  It is sometimes useful to allow
     a protocol's state information (callback lists, and so on) to persist,
     even though the client may choose to temporarily resign from the
     interaction.  This is supported by allowing a _p_r_o_t_o_c_o_l to be in one of
     two states:  active or inactive.  If the _p_r_o_t_o_c_o_l is active and the
     _s_h_e_l_l is realized, the _p_r_o_p_e_r_t_y contains the _p_r_o_t_o_c_o_l AAttoomm.  If the _p_r_o_-
     _t_o_c_o_l is inactive, the AAttoomm is not present in the _p_r_o_p_e_r_t_y.

     XXmmAAccttiivvaatteeWWMMPPrroottooccooll is a convenience interface.  It calls XXmmAAccttiivvaa--
     tteePPrroottooccooll with the property value set to the atom returned by interning
     WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l  Specifies the widget with which the protocol property is associ-
            ated.

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

     _p_r_o_t_o_c_o_l
            Specifies the protocol AAttoomm (or an iinntt type cast to AAttoomm).

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

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmAAccttiivvaatteeWWMMPPrroottooccooll((33XX)) and XXmmIInntteerrnnAAttoomm((33XX)).













   1-124






                                                     XmActivateWMProtocol(3X)



   NAME
     XXmmAAccttiivvaatteeWWMMPPrroottooccooll-A VendorShell convenience interface that activates
     a protocol

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//PPrroottooccoollss..hh>>
     vvooiidd XXmmAAccttiivvaatteeWWMMPPrroottooccooll ((_s_h_e_l_l, _p_r_o_t_o_c_o_l))
          WWiiddggeett    _s_h_e_l_l;;
          AAttoomm      _p_r_o_t_o_c_o_l;;

   DESCRIPTION
     XXmmAAccttiivvaatteeWWMMPPrroottooccooll is a convenience interface.  It calls XXmmAAccttiivvaa--
     tteePPrroottooccooll with the property value set to the atom returned by interning
     WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l  Specifies the widget with which the protocol property is associ-
            ated.

     _p_r_o_t_o_c_o_l
            Specifies the protocol AAttoomm (or an iinntt type cast to AAttoomm).

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

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmAAccttiivvaatteePPrroottooccooll((33XX)), and XXmmIInntteerrnnAAttoomm((33XX)).




























   1-125






   XmAddProtocolCallback(3X)



   NAME
     XXmmAAddddPPrroottooccoollCCaallllbbaacckk-A VendorShell function that adds client callbacks
     for a protocol

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

   DESCRIPTION
     XXmmAAddddPPrroottooccoollCCaallllbbaacckk adds client callbacks for a protocol.  It checks
     if the protocol is registered, and if it is not, calls XXmmAAddddPPrroottooccoollss.
     It then adds the callback to the internal list.  These callbacks are
     called when the corresponding client message is received.

     XXmmAAddddWWMMPPrroottooccoollCCaallllbbaacckk is a convenience interface.  It calls XXmmAAddddPPrroo--
     ttooccoollCCaallllbbaacckk with the property value set to the atom returned by
     interning WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l  Specifies the widget with which the protocol property is associ-
            ated.

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

     _p_r_o_t_o_c_o_l
            Specifies the protocol AAttoomm (or an iinntt type cast to AAttoomm).

     _c_a_l_l_b_a_c_k
            Specifies the procedure to call when a protocol message is
            received.

     _c_l_o_s_u_r_eSpecifies the client data to be passed to the callback when it is
            invoked.

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

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmAAddddPPrroottooccoollss((33XX)), XXmmAAddddWWMMPPrroottooccoollCCaallllbbaacckk((33XX)), and
     XXmmIInntteerrnnAAttoomm((33XX)).




   1-126






                                                           XmAddProtocols(3X)



   NAME
     XXmmAAddddPPrroottooccoollss-A VendorShell function that adds the protocols to the
     protocol manager and allocates the internal tables

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//PPrroottooccoollss..hh>>
     vvooiidd XXmmAAddddPPrroottooccoollss ((_s_h_e_l_l, _p_r_o_p_e_r_t_y, _p_r_o_t_o_c_o_l_s, _n_u_m__p_r_o_t_o_c_o_l_s))
          WWiiddggeett    _s_h_e_l_l;;
          AAttoomm      _p_r_o_p_e_r_t_y;;
          AAttoomm      * _p_r_o_t_o_c_o_l_s;;
          CCaarrddiinnaall  _n_u_m__p_r_o_t_o_c_o_l_s;;
     vvooiidd XXmmAAddddWWMMPPrroottooccoollss ((_s_h_e_l_l, _p_r_o_t_o_c_o_l_s, _n_u_m__p_r_o_t_o_c_o_l_s))
          WWiiddggeett    _s_h_e_l_l;;
          AAttoomm      * _p_r_o_t_o_c_o_l_s;;
          CCaarrddiinnaall  _n_u_m__p_r_o_t_o_c_o_l_s;;

   DESCRIPTION
     XXmmAAddddPPrroottooccoollss adds the protocols to the protocol manager and allocates
     the internal tables.

     XXmmAAddddWWMMPPrroottooccoollss is a convenience interface.  It calls XXmmAAddddPPrroottooccoollss
     with the property value set to the atom returned by interning
     WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l       Specifies the widget with which the protocol property is
                 associated.

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

     _p_r_o_t_o_c_o_l_s   Specifies the protocol AAttoommss (or iinntt types cast to AAttoomm).

     _n_u_m__p_r_o_t_o_c_o_l_s
                 Specifies the number of elements in _p_r_o_t_o_c_o_l_s.

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

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmAAddddWWMMPPrroottooccoollss((33XX)), and XXmmIInntteerrnnAAttoomm((33XX)).















   1-127






   XmAddTabGroup(3X)



   NAME
     XXmmAAddddTTaabbGGrroouupp-A function that adds a manager or a primitive widget to
     the list of tab groups

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmAAddddTTaabbGGrroouupp ((_t_a_b__g_r_o_u_p))
          WWiiddggeett    _t_a_b__g_r_o_u_p;;

   DESCRIPTION
     This function is obsolete and its behavior is replaced by setting XXmmNNnnaa--
     vviiggaattiioonnTTyyppee to XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP.  When using the keyboard to
     traverse through a widget hierarchy, primitive or manager widgets are
     grouped together into what are known as ttaabb ggrroouuppss.  Any manager or
     primitive widget can be a tab group.  Within a tab group, move the focus
     to the next widget within the tab group by using the arrow keys.  To
     move to another tab group, use KKNNeexxttFFiieelldd or KKPPrreevvFFiieelldd.

     Tab groups are ordinarily specified by the XXmmNNnnaavviiggaattiioonnTTyyppee resource.
     XXmmAAddddTTaabbGGrroouupp is called to control the order of traversal of tab groups.
     The widget specified by _t_a_b__g_r_o_u_p is appended to the list of tab groups
     to be traversed, and the widget's XXmmNNnnaavviiggaattiioonnTTyyppee is set to
     XXmmEEXXCCLLUUSSIIVVEE__TTAABB__GGRROOUUPP.

     _t_a_b__g_r_o_u_p
            Specifies the manager or primitive widget ID.

   RELATED INFORMATION
     XXmmMMaannaaggeerr((33XX)), XXmmGGeettTTaabbGGrroouupp((33XX)), XXmmPPrriimmiittiivvee((33XX)), and
     XXmmRReemmoovveeTTaabbGGrroouupp((33XX)).

























   1-128






                                                  XmAddWMProtocolCallback(3X)



   NAME
     XXmmAAddddWWMMPPrroottooccoollCCaallllbbaacckk-A VendorShell convenience interface that adds
     client callbacks for a protocol

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

   DESCRIPTION
     XXmmAAddddWWMMPPrroottooccoollCCaallllbbaacckk is a convenience interface.  It calls XXmmAAddddPPrroo--
     ttooccoollCCaallllbbaacckk with the property value set to the atom returned by
     interning WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l  Specifies the widget with which the protocol property is associ-
            ated.

     _p_r_o_t_o_c_o_l
            Specifies the protocol AAttoomm (or an iinntt type cast to AAttoomm).

     _c_a_l_l_b_a_c_k
            Specifies the procedure to call when a protocol message is
            received.

     _c_l_o_s_u_r_eSpecifies the client data to be passed to the callback when it is
            invoked.

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

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmAAddddPPrroottooccoollCCaallllbbaacckk((33XX)), and XXmmIInntteerrnnAAttoomm((33XX)).



















   1-129






   XmAddWMProtocols(3X)



   NAME
     XXmmAAddddWWMMPPrroottooccoollss-A VendorShell convenience interface that adds the pro-
     tocols to the protocol manager and allocates the internal tables

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     ##iinncclluuddee <<XXmm//PPrroottooccoollss..hh>>
     vvooiidd XXmmAAddddWWMMPPrroottooccoollss ((_s_h_e_l_l, _p_r_o_t_o_c_o_l_s, _n_u_m__p_r_o_t_o_c_o_l_s))
          WWiiddggeett    _s_h_e_l_l;;
          AAttoomm      * _p_r_o_t_o_c_o_l_s;;
          CCaarrddiinnaall  _n_u_m__p_r_o_t_o_c_o_l_s;;

   DESCRIPTION
     XXmmAAddddWWMMPPrroottooccoollss is a convenience interface.  It calls XXmmAAddddPPrroottooccoollss
     with the property value set to the atom returned by interning
     WWMM__PPRROOTTOOCCOOLLSS.

     _s_h_e_l_l       Specifies the widget with which the protocol property is
                 associated.

     _p_r_o_t_o_c_o_l_s   Specifies the protocol AAttoommss (or iinntt types cast to AAttoomm).

     _n_u_m__p_r_o_t_o_c_o_l_s
                 Specifies the number of elements in _p_r_o_t_o_c_o_l_s.

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

   RELATED INFORMATION
     VVeennddoorrSShheellll((33XX)), XXmmAAddddPPrroottooccoollss((33XX)), and XXmmIInntteerrnnAAttoomm((33XX)).

























   1-130






                                                            XmArrowButton(3X)



   NAME
     XXmmAArrrroowwBBuuttttoonn-The ArrowButton widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//AArrrroowwBB..hh>>

   DESCRIPTION
     ArrowButton consists of a directional arrow surrounded by a border sha-
     dow.  When it is selected, the shadow changes to give the appearance
     that the ArrowButton has been pressed in.  When the ArrowButton is
     unselected, the shadow reverts to give the appearance that the ArrowBut-
     ton is released, or out.

     Classes

     ArrowButton inherits behavior and resources from CCoorree and XXmmPPrriimmiittiivvee
     classes.

     The class pointer is xxmmAArrrroowwBBuuttttoonnWWiiddggeettCCllaassss.

     The class name is XXmmAArrrroowwBBuuttttoonn.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                             XXmmAArrrroowwB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
   XmNarmCallback        XmCCallback         XtCallbackList   NULL         C
   XmNarrowDirection     XmCArrowDirection   unsigned char    XmARROW_UP   CSG
   XmNdisarmCallback     XmCCallback         XtCallbackList   NULL         C
   XmNmultiClick         XmCMultiClick       unsigned char    dynamic      CSG

     XXmmNNaaccttiivvaatteeCCaallllbbaacckk
               Specifies a list of callbacks that is called when the
               ArrowButton is activated.  To activate the button, press and
               release BBSSeelleecctt while the pointer is inside the ArrowButton
               widget.  Activating the ArrowButton also disarms it.  The rea-
               son sent by this callback is XXmmCCRR__AACCTTIIVVAATTEE.

     XXmmNNaarrmmCCaallllbbaacckk
               Specifies a list of callbacks that is called when the


   1-131






   XmArrowButton(3X)


               ArrowButton is armed.  To arm this widget, press BBSSeelleecctt while
               the pointer is inside the ArrowButton.  The reason sent by
               this callback is XXmmCCRR__AARRMM.

     XXmmNNaarrrroowwDDiirreeccttiioonn
               Sets the arrow direction.  The following are values for this
               resource:

                 ++oo  XXmmAARRRROOWW__UUPP.

                 ++oo  XXmmAARRRROOWW__DDOOWWNN.

                 ++oo  XXmmAARRRROOWW__LLEEFFTT.

                 ++oo  XXmmAARRRROOWW__RRIIGGHHTT.

     XXmmNNddiissaarrmmCCaallllbbaacckk
               Specifies a list of callbacks that is called when the
               ArrowButton is disarmed.  To disarm this widget, press and
               release BBSSeelleecctt while the pointer is inside the ArrowButton.
               The reason for this callback is XXmmCCRR__DDIISSAARRMM.

     XXmmNNmmuullttiiCClliicckk
               If a button click is followed by another button click within
               the time span specified by the display's multi-click time, and
               this resource is set to XXmmMMUULLTTIICCLLIICCKK__DDIISSCCAARRDD, do not process
               the second click.  If this resource is set to
               XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, process the event and increment _c_l_i_c_k__c_o_u_n_t
               in the callback structure.  When the button is not in a menu,
               the default value is XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP.

     Inherited Resources

     ArrowButton inherits behavior and resources from the following superc-
     lasses.  For a complete description of each resource, refer to the man
     page for that superclass.
                                       XXmmPPrriimmiittiivvee RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt                AAcccceessss
   ________________________________________________________________________________________________
   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic                CSG
   XmNbottomShadowPixmap   XmCBottomShadowPixmap   Pixmap             XmUNSPECIFIED_PIXMAP   CSG
   XmNforeground           XmCForeground           Pixel              dynamic                CSG
   XmNhelpCallback         XmCCallback             XtCallbackList     NULL                   C
   XmNhighlightColor       XmCHighlightColor       Pixel              dynamic                CSG
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False                  CSG
   XmNhighlightPixmap      XmCHighlightPixmap      Pixmap             dynamic                CSG
   XmNhighlightThickness   XmCHighlightThickness   Dimension          2                      CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE                 CSG
   XmNshadowThickness      XmCShadowThickness      Dimension          2                      CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic                CSG
   XmNtopShadowPixmap      XmCTopShadowPixmap      Pixmap             dynamic                CSG
   XmNtraversalOn          XmCTraversalOn          Boolean            True                   CSG
   XmNunitType             XmCUnitType             unsigned char      dynamic                CSG
   XmNuserData             XmCUserData             XtPointer          NULL                   CSG


   1-132






                                                            XmArrowButton(3X)


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

     Callback Information

     A pointer to the following structure is passed to each callback:
     ttyyppeeddeeff ssttrruucctt
     {{
       iinntt      _r_e_a_s_o_n;;
       XXEEvveenntt   * _e_v_e_n_t;;
       iinntt      _c_l_i_c_k__c_o_u_n_t;;
     }} XXmmAArrrroowwBBuuttttoonnC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.

     _c_l_i_c_k__c_o_u_n_t
            This value is valid only when the reason is XXmmCCRR__AACCTTIIVVAATTEE.  It
            contains the number of clicks in the last multiclick sequence if
            the XXmmNNmmuullttiiCClliicckk resource is set to XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP; otherwise
            it contains 11.  The activate callback is invoked for each click
            if XXmmNNmmuullttiiCClliicckk is set to XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP.

     Translations

     XmArrowButton includes translations for XmPrimitive.  Additional XmAr-
     rowButton translations are listed below.  These translations may not
     directly correspond to a translation table.
     BBSSeelleecctt PPrreessss:: AArrmm(())
     BBSSeelleecctt CClliicckk:: AAccttiivvaattee(())
                    DDiissaarrmm(())
     BBSSeelleecctt RReelleeaassee::AAccttiivvaattee(())
                    DDiissaarrmm(())


   1-133






   XmArrowButton(3X)


     BBSSeelleecctt PPrreessss 22++::MMuullttiiAArrmm(())
     BBSSeelleecctt RReelleeaassee 22++::MMuullttiiAAccttiivvaattee(())
     KKSSeelleecctt::       AArrmmAAnnddAAccttiivvaattee(())
     KKHHeellpp::         HHeellpp(())

     Action Routines

     The XmArrowButton action routines are described below:

     AAccttiivvaattee(()):
               Draws the shadow in the unselected state.  If the pointer is
               within the ArrowButton, calls the callbacks for XXmmNNaaccttiivvaattee--
               CCaallllbbaacckk.

     AArrmm(()):    Draws the shadow in the selected state and calls the callbacks
               for XXmmNNaarrmmCCaallllbbaacckk.

     AArrmmAAnnddAAccttiivvaattee(()):
               Draws the shadow in the selected state and calls the callbacks
               for XXmmNNaarrmmCCaallllbbaacckk.  Arranges for the shadow to be drawn in
               the unselected state and the callbacks for XXmmNNaaccttiivvaatteeCCaallllbbaacckk
               and XXmmNNddiissaarrmmCCaallllbbaacckk to be called, either immediately or at a
               later time.

     DDiissaarrmm(()): Draws the shadow in the unselected state and calls the call-
               backs for XXmmNNddiissaarrmmCCaallllbbaacckk.

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

     MMuullttiiAAccttiivvaattee(()):
               If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__DDIISSCCAARRDD, this action does
               nothing.  If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, this action
               does the following: Increments _c_l_i_c_k__c_o_u_n_t in the callback
               structure.  Draws the shadow in the unselected state.  If the
               pointer is within the ArrowButton, calls the callbacks for
               XXmmNNaaccttiivvaatteeCCaallllbbaacckk.  Calls the callbacks for XXmmNNddiissaarrmmCCaallll--
               bbaacckk.

     MMuullttiiAArrmm(()):
               If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__DDIISSCCAARRDD, this action does
               nothing.  If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, this action
               draws the shadow in the selected state and calls the callbacks
               for XXmmNNaarrmmCCaallllbbaacckk.











   1-134






                                                            XmArrowButton(3X)



     Additional Behavior

     This widget has the additional behavior described below:

     <<EEnntteerrWWiinnddooww>>:
               Draws the ArrowButton shadow in its selected state if the
               pointer leaves and re-enters the window while BSelect is
               pressed.

     <<LLeeaavveeWWiinnddooww>>:
               Draws the ArrowButton shadow in its unselected state if the
               pointer leaves the window while BSelect is pressed.

     Virtual Bindings

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

   RELATED INFORMATION
     CCoorree((33XX)), XXmmCCrreeaatteeAArrrroowwBBuuttttoonn((33XX)), and XXmmPPrriimmiittiivvee((33XX)).



































   1-135






   XmArrowButtonGadget(3X)



   NAME
     XXmmAArrrroowwBBuuttttoonnGGaaddggeett-The ArrowButtonGadget widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//AArrrroowwBBGG..hh>>

   DESCRIPTION
     ArrowButtonGadget consists of a directional arrow surrounded by a border
     shadow.  When it is selected, the shadow changes to give the appearance
     that the ArrowButtonGadget has been pressed in.  When it is unselected,
     the shadow reverts to give the appearance that the button is released,
     or out.

     Classes

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

     The class pointer is xxmmAArrrroowwBBuuttttoonnGGaaddggeettCCllaassss.

     The class name is XXmmAArrrroowwBBuuttttoonnGGaaddggeett.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                           AArrrroowwBBuuttttoonnG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
   ______________________________________________________________________________
   XmNactivateCallback   XmCCallback         XtCallbackList   NULL         C
   XmNarmCallback        XmCCallback         XtCallbackList   NULL         C
   XmNarrowDirection     XmCArrowDirection   unsigned char    XmARROW_UP   CSG
   XmNdisarmCallback     XmCCallback         XtCallbackList   NULL         C
   XmNmultiClick         XmCMultiClick       unsigned char    dynamic      CSG

     XXmmNNaaccttiivvaatteeCCaallllbbaacckk
               Specifies a list of callbacks that is called when the
               ArrowButtonGadget is activated.  To activate the button, press
               and release BBSSeelleecctt while the pointer is inside the ArrowBut-
               tonGadget.  Activating the ArrowButtonGadget also disarms it.
               The reason sent by this callback is XXmmCCRR__AACCTTIIVVAATTEE.





   1-136






                                                      XmArrowButtonGadget(3X)



     XXmmNNaarrmmCCaallllbbaacckk
               Specifies a list of callbacks that is called when the
               ArrowButtonGadget is armed.  To arm this widget, press BBSSeelleecctt
               while the pointer is inside the ArrowButtonGadget.  The reason
               sent by this callback is XXmmCCRR__AARRMM.

     XXmmNNaarrrroowwDDiirreeccttiioonn
               Sets the arrow direction.  The values for this resource are:

                 ++oo  XXmmAARRRROOWW__UUPP.

                 ++oo  XXmmAARRRROOWW__DDOOWWNN.

                 ++oo  XXmmAARRRROOWW__LLEEFFTT.

                 ++oo  XXmmAARRRROOWW__RRIIGGHHTT.

     XXmmNNddiissaarrmmCCaallllbbaacckk
               Specifies a list of callbacks that is called when the
               ArrowButtonGadget is disarmed.  To disarm this widget, press
               and release BBSSeelleecctt while the pointer is inside the ArrowBut-
               tonGadget.  The reason sent by this callback is XXmmCCRR__DDIISSAARRMM.

     XXmmNNmmuullttiiCClliicckk
               If a button click is followed by another button click within
               the time span specified by the display's multi-click time, and
               this resource is set to XXmmMMUULLTTIICCLLIICCKK__DDIISSCCAARRDD, do not process
               the second click.  If this resource is set to
               XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, process the event and increment _c_l_i_c_k__c_o_u_n_t
               in the callback structure.  When the ArrowButtonGadget is not
               in a menu, the default value is XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP.

     Inherited Resources

     ArrowButtonGadget inherits behavior and resources from the following
     superclasses.  For a complete description of each resource, refer to the
     man page for that superclass.
                                  XXmmGGaaddggeett RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt   AAcccceessss
   ___________________________________________________________________________________
   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic   G
   XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
   XmNhighlightColor       XmCHighlightColor       Pixel              dynamic   G
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG
   XmNhighlightThickness   XmCHighlightThickness   Dimension          2         CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE    CSG
   XmNshadowThickness      XmCShadowThickness      Dimension          2         CSG
   XmNtopShadowColor       XmCTopShadowColor       Pixel              dynamic   G
   XmNtraversalOn          XmCTraversalOn          Boolean            True      CSG
   XmNunitType             XmCUnitType             unsigned char      dynamic   CSG
   XmNuserData             XmCUserData             XtPointer          NULL      CSG
                               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


   1-137






   XmArrowButtonGadget(3X)


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

     Callback Information

     A pointer to the following structure is passed to each callback:
     ttyyppeeddeeff ssttrruucctt
     {{
       iinntt      _r_e_a_s_o_n;;
       XXEEvveenntt   * _e_v_e_n_t;;
       iinntt      _c_l_i_c_k__c_o_u_n_t;;
     }} XXmmAArrrroowwBBuuttttoonnC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.

     _c_l_i_c_k__c_o_u_n_t
            This value is valid only when the reason is XXmmCCRR__AACCTTIIVVAATTEE.  It
            contains the number of clicks in the last multiclick sequence if
            the XXmmNNmmuullttiiCClliicckk resource is set to XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, otherwise
            it contains 11.  The activate callback is invoked for each click
            if XXmmNNmmuullttiiCClliicckk is set to XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP.

     Behavior

     XmArrowButtonGadget includes behavior from XmGadget.  Additional XmAr-
     rowButtonGadget behavior is described below:

     BBSSeelleecctt PPrreessss:
               Draws the shadow in the selected state and calls the callbacks
               for XXmmNNaarrmmCCaallllbbaacckk.

     BBSSeelleecctt CClliicckk oorr BBSSeelleeccttRReelleeaassee:
               Draws the shadow in the unselected state.  If the pointer is
               within the ArrowButtonGadget, calls the callbacks for XXmmNNaacc--
               ttiivvaatteeCCaallllbbaacckk.  Calls the callbacks for XXmmNNddiissaarrmmCCaallllbbaacckk.

     BBSSeelleecctt PPrreessss 22++:
               If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__DDIISSCCAARRDD, this action does
               nothing.  If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, this action
               draws the shadow in the selected state and calls the callbacks
               for XXmmNNaarrmmCCaallllbbaacckk.



   1-138






                                                      XmArrowButtonGadget(3X)



     BBSSeelleecctt RReelleeaassee 22++:
               If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__DDIISSCCAARRDD, this action does
               nothing.  If XXmmNNmmuullttiiCClliicckk is XXmmMMUULLTTIICCLLIICCKK__KKEEEEPP, this action
               does the following: Increments _c_l_i_c_k__c_o_u_n_t in the callback
               structure.  Draws the shadow in the unselected state.  If the
               pointer is within the ArrowButtonGadget, calls the callbacks
               for XXmmNNaaccttiivvaatteeCCaallllbbaacckk.  Calls the callbacks for XXmmNNddiissaarrmm--
               CCaallllbbaacckk.

     KKSSeelleecctt:  Draws the shadow in the selected state and calls the callbacks
               for XXmmNNaarrmmCCaallllbbaacckk.  Arranges for the shadow to be drawn in
               the unselected state and the callbacks for XXmmNNaaccttiivvaatteeCCaallllbbaacckk
               and XXmmNNddiissaarrmmCCaallllbbaacckk to be called, either immediately or at a
               later time.

     KKHHeellpp:    Calls the callbacks for XXmmNNhheellppCCaallllbbaacckk if any exist.  If
               there are no help callbacks for this widget, this calls the
               help callbacks for the nearest ancestor that has them.

     <<EEnntteerr>>:  Draws the ArrowButtonGadget shadow in its selected state if
               the pointer leaves and re-enters the gadget while BSelect is
               pressed.

     <<LLeeaavvee>>:  Draws the ArrowButtonGadget shadow in its unselected state if
               the pointer leaves the gadget while BSelect is pressed.

     Virtual Bindings

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

   RELATED INFORMATION
     OObbjjeecctt((33XX)), RReeccttOObbjj((33XX)), XXmmCCrreeaatteeAArrrroowwBBuuttttoonnGGaaddggeett((33XX)), and
     XXmmGGaaddggeett((33XX)).





















   1-139






   XmBulletinBoard(3X)



   NAME
     XXmmBBuulllleettiinnBBooaarrdd-The BulletinBoard widget class

   SYNOPSIS
     ##iinncclluuddee <<XXmm//BBuulllleettiinnBB..hh>>

   DESCRIPTION
     BulletinBoard is a composite widget that provides simple geometry
     management for children widgets.  It does not force positioning on its
     children, but can be set to reject geometry requests that result in
     overlapping children.  BulletinBoard is the base widget for most dialog
     widgets and is also used as a general container widget.

     Modal and modeless dialogs are implemented as collections of widgets
     that include a DialogShell, a BulletinBoard (or subclass) child of the
     shell, and various dialog components (buttons, labels, etc.) that are
     children of BulletinBoard.  BulletinBoard defines callbacks useful for
     dialogs (focus, map, unmap), which are available for application use.
     If its parent is a DialogShell, BulletinBoard passes title and input
     mode (based on dialog style) information to the parent, which is respon-
     sible for appropriate communication with the window manager.

     The default value for XXmmNNiinniittiiaallFFooccuuss is the value of XXmmNNddeeffaauullttBBuuttttoonn.

     Classes

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

     The class pointer is xxmmBBuulllleettiinnBBooaarrddWWiiddggeettCCllaassss.

     The class name is XXmmBBuulllleettiinnBBooaarrdd.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                             XXmmBBuulllleettiinnBBooaarrdd RReessoouurrccee SSeett
   NNaammee                  CCllaassss                TTyyppee             DDeeffaauulltt        AAcccceessss
   _________________________________________________________________________________
   XmNallowOverlap       XmCAllowOverlap      Boolean          True           CSG
   XmNautoUnmanage       XmCAutoUnmanage      Boolean          True           CG
   XmNbuttonFontList     XmCButtonFontList    XmFontList       dynamic        CSG
   XmNcancelButton       XmCWidget            Widget           NULL           SG


   1-140






                                                          XmBulletinBoard(3X)


   XmNdefaultButton      XmCWidget            Widget           NULL           SG
   XmNdefaultPosition    XmCDefaultPosition   Boolean          True           CSG
   XmNdialogStyle        XmCDialogStyle       unsigned char    dynamic        CSG
   XmNdialogTitle        XmCDialogTitle       XmString         NULL           CSG
   XmNfocusCallback      XmCCallback          XtCallbackList   NULL           C
   XmNlabelFontList      XmCLabelFontList     XmFontList       dynamic        CSG
   XmNmapCallback        XmCCallback          XtCallbackList   NULL           C
   XmNmarginHeight       XmCMarginHeight      Dimension        10             CSG
   XmNmarginWidth        XmCMarginWidth       Dimension        10             CSG
   XmNnoResize           XmCNoResize          Boolean          False          CSG
   XmNresizePolicy       XmCResizePolicy      unsigned char    XmRESIZE_ANY   CSG
   XmNshadowType         XmCShadowType        unsigned char    XmSHADOW_OUT   CSG
   XmNtextFontList       XmCTextFontList      XmFontList       dynamic        CSG
   XmNtextTranslations   XmCTranslations      XtTranslations   NULL           C
   XmNunmapCallback      XmCCallback          XtCallbackList   NULL           C

     XXmmNNaalllloowwOOvveerrllaapp
               Controls the policy for overlapping children widgets.  If
               True, BulletinBoard allows geometry requests that result in
               overlapping children.

     XXmmNNaauuttooUUnnmmaannaaggee
               Controls whether or not BulletinBoard is automatically
               unmanaged after a button is activated.  If this resource is
               True on initialization and if the BulletinBoard's parent is a
               DialogShell, BulletinBoard adds a callback to button children
               (PushButtons, PushButtonGadgets, and DrawnButtons) that
               unmanages the BulletinBoard when a button is activated.  If
               this resource is False on initialization or if the
               BulletinBoard's parent is not a DialogShell, the BulletinBoard
               is not automatically unmanaged.  For BulletinBoard subclasses
               with Apply or Help buttons, activating those buttons does not
               automatically unmanage the BulletinBoard.

     XXmmNNbbuuttttoonnFFoonnttLLiisstt
               Specifies the font list used for BulletinBoard's button des-
               cendants.  If this value is NULL at initialization, the font
               list is initialized by looking up the parent hierarchy of the
               widget for an ancestor that is a subclass of the XmBulletin-
               Board, VendorShell, or XmMenuShell widget class.  If such an
               ancestor is found, the font list is initialized to the XXmmNNbbuutt--
               ttoonnFFoonnttLLiisstt of the ancestor widget.  If no such ancestor is
               found, the default is implementation dependent.  Refer to
               XXmmFFoonnttLLiisstt((33XX)) for more information on the creation and struc-
               ture of a font list.

     XXmmNNccaanncceellBBuuttttoonn
               Specifies the widget ID of the CCaanncceell button.  BulletinBoard's
               subclasses, which define a CCaanncceell button, set this resource.
               BulletinBoard does not directly provide any behavior for that
               button.

     XXmmNNddeeffaauullttBBuuttttoonn
               Specifies the widget ID of the default button.  Some


   1-141






   XmBulletinBoard(3X)


               BulletinBoard subclasses, which define a default button, set
               this resource.  BulletinBoard defines translations and
               installs accelerators that activate that button when KKAAccttiivvaattee
               is pressed and the keyboard focus is not in another button.

     XXmmNNddeeffaauullttPPoossiittiioonn
               Controls whether or not the BulletinBoard is automatically
               positioned by its parent.  If True, and the parent of the Bul-
               letinBoard is a DialogShell, the BulletinBoard is centered
               within or around the parent of the DialogShell when the Bul-
               letinBoard is mapped and managed.  If False, the BulletinBoard
               is not automatically positioned.

     XXmmNNddiiaallooggSSttyyllee
               Indicates the dialog style associated with the BulletinBoard.
               If the parent of the BulletinBoard is a DialogShell, the
               parent's XXmmNNmmwwmmIInnppuuttMMooddee is set according to the value of this
               resource.  This resource can be set only if the BulletinBoard
               is unmanaged.  Possible values for this resource include the
               following:

                 ++oo  XXmmDDIIAALLOOGG__SSYYSSTTEEMM__MMOODDAALL-used for dialogs that must be
                    responded to before any other interaction in any applica-
                    tion

                 ++oo  XXmmDDIIAALLOOGG__PPRRIIMMAARRYY__AAPPPPLLIICCAATTIIOONN__MMOODDAALL-used for dialogs that
                    must be responded to before some other interactions in
                    ancestors of the widget

                 ++oo  XXmmDDIIAALLOOGG__AAPPPPLLIICCAATTIIOONN__MMOODDAALL-used for dialogs that must be
                    responded to before some other interactions in ancestors
                    of the widget.  This value is the same as
                    XXmmDDIIAALLOOGG__PPRRIIMMAARRYY__AAPPPPLLIICCAATTIIOONN__MMOODDAALL, and remains for com-
                    patibility.

                 ++oo  XXmmDDIIAALLOOGG__FFUULLLL__AAPPPPLLIICCAATTIIOONN__MMOODDAALL-used for dialogs that
                    must be responded to before some other interactions in
                    the same application

                 ++oo  XXmmDDIIAALLOOGG__MMOODDEELLEESSSS-used for dialogs that do not interrupt
                    interaction of any application.  This is the default when
                    the parent of the BulletinBoard is a DialogShell.

                 ++oo  XXmmDDIIAALLOOGG__WWOORRKK__AARREEAA-used for BulletinBoard widgets whose
                    parents are not DialogShells.  XXmmNNddiiaallooggSSttyyllee is forced
                    to have this value when the parent of the BulletinBoard
                    is not a DialogShell.

     XXmmNNddiiaallooggTTiittllee
               Specifies the dialog title.  If this resource is not NULL, and
               the parent of the BulletinBoard is a subclass of WMShell, Bul-
               letinBoard sets the XXmmNNttiittllee and XXmmNNttiittlleeEEnnccooddiinngg of its
               parent.  If the only character set in XXmmNNddiiaallooggTTiittllee is
               ISO8859-1, XXmmNNttiittllee is set to the string of the title, and


   1-142






                                                          XmBulletinBoard(3X)


               XXmmNNttiittlleeEEnnccooddiinngg is set to SSTTRRIINNGG.  If XXmmNNddiiaallooggTTiittllee contains
               character sets other than ISO8859-1, XXmmNNttiittllee is set to the
               string of the title converted to a compound text string, and
               XXmmNNttiittlleeEEnnccooddiinngg is set to CCOOMMPPOOUUNNDD__TTEEXXTT.

     XXmmNNffooccuussCCaallllbbaacckk
               Specifies the list of callbacks that is called when the Bul-
               letinBoard widget or one of its descendants accepts the input
               focus.  The callback reason is XXmmCCRR__FFOOCCUUSS.

     XXmmNNllaabbeellFFoonnttLLiisstt
               Specifies the font list used for BulletinBoard's label descen-
               dants (Labels and LabelGadgets).  If this value is NULL at
               initialization, the font list is initialized by looking up the
               parent hierarchy of the widget for an ancestor that is a sub-
               class of the XmBulletinBoard, VendorShell, or XmMenuShell
               widget class.  If such an ancestor is found, the font list is
               initialized to the XXmmNNllaabbeellFFoonnttLLiisstt of the ancestor widget.
               If no such ancestor is found, the default is implementation
               dependent.  Refer to XXmmFFoonnttLLiisstt((33XX)) for more information on
               the creation and structure of a font list.

     XXmmNNmmaappCCaallllbbaacckk
               Specifies the list of callbacks that is called only when the
               parent of the BulletinBoard is a DialogShell; in which case,
               this callback list is invoked when the BulletinBoard widget is
               mapped.  The callback reason is XXmmCCRR__MMAAPP.  DialogShells are
               usually mapped when the DialogShell is managed.

     XXmmNNmmaarrggiinnHHeeiigghhtt
               Specifies the minimum spacing in pixels between the top or
               bottom edge of BulletinBoard and any child widget.

     XXmmNNmmaarrggiinnWWiiddtthh
               Specifies the minimum spacing in pixels between the left or
               right edge of BulletinBoard and any child widget.

     XXmmNNnnooRReessiizzee
               Controls whether or not resize controls are included in the
               window manager frame around the BulletinBoard's parent.  If
               set to True, the mmwwmm does not include resize controls in the
               window manager frame containing the parent of the Bulletin-
               Board if the parent is a subclass of VendorShell.  If set to
               False, the window manager frame does include resize controls.
               Other controls provided by mmwwmm can be included or excluded
               through the mmwwmm resources provided by VendorShell.










   1-143






   XmBulletinBoard(3X)



     XXmmNNrreessiizzeePPoolliiccyy
               Controls the policy for resizing BulletinBoard widgets.  Pos-
               sible values include the following:

                 ++oo  XXmmRREESSIIZZEE__NNOONNEE-fixed size

                 ++oo  XXmmRREESSIIZZEE__AANNYY-shrink or grow as needed

                 ++oo  XXmmRREESSIIZZEE__GGRROOWW-grow only

     XXmmNNsshhaaddoowwTTyyppee
               Describes the shadow drawing style for BulletinBoard.  This
               resource can have the following values:

                 ++oo  XXmmSSHHAADDOOWW__IINN-draws the BulletinBoard shadow so that it
                    appears inset.  This means that the bottom shadow visuals
                    and top shadow visuals are reversed.

                 ++oo  XXmmSSHHAADDOOWW__OOUUTT-draws the BulletinBoard shadow so that it
                    appears outset

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__IINN-draws the BulletinBoard shadow using a
                    double line giving the effect of a line etched into the
                    window, similar to the Separator widget

                 ++oo  XXmmSSHHAADDOOWW__EETTCCHHEEDD__OOUUTT-draws the BulletinBoard shadow using
                    a double line giving the effect of a line coming out of
                    the window, similar to the Separator widget

     XXmmNNtteexxttFFoonnttLLiisstt
               Specifies the font list used for BulletinBoard's Text and List
               descendants.  If this value is NULL at initialization, the
               font list is initialized by looking up the parent hierarchy of
               the widget for an ancestor that is a subclass of the XmBul-
               letinBoard or VendorShell widget class.  If such an ancestor
               is found, the font list is initialized to the XXmmNNtteexxttFFoonnttLLiisstt
               of the ancestor widget.  If no such ancestor is found, the
               default is implementation  dependent.  Refer to XXmmFFoonnttLLiisstt((33XX))
               for more information on the creation and structure of a font
               list.

     XXmmNNtteexxttTTrraannssllaattiioonnss
               Adds translations to any Text widget or Text widget subclass
               that is added as a child of BulletinBoard.

     XXmmNNuunnmmaappCCaallllbbaacckk
               Specifies the list of callbacks that is called only when the
               parent of the BulletinBoard is a DialogShell.  In that case,
               this callback list is invoked when the BulletinBoard widget is
               unmapped.  The callback reason is XXmmCCRR__UUNNMMAAPP.  DialogShells
               are usually unmapped when the DialogShell is unmanaged.




   1-144






                                                          XmBulletinBoard(3X)


     Inherited Resources

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





   1-145






   XmBulletinBoard(3X)


     Callback Information

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

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

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

     Translations

     XmBulletinBoard includes the translations from XmManager.

     Additional Behavior

     The XmBulletinBoard widget has the additional behavior described below:

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

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

     <<FFooccuussIInn>>:
               Calls the callbacks for XXmmNNffooccuussCCaallllbbaacckk.  When the focus pol-
               icy is XXmmPPOOIINNTTEERR, this happens when the pointer enters the
               window.  When the focus policy is XXmmEEXXPPLLIICCIITT, this happens
               when the user traverses to the widget.

     <<MMaapp>>:    Calls the callbacks for XXmmNNmmaappCCaallllbbaacckk.

     <<UUnnmmaapp>>:  Calls the callbacks for XXmmNNuunnmmaappCCaallllbbaacckk.

     Virtual Bindings

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


   1-146






                                                          XmBulletinBoard(3X)



   RELATED INFORMATION
     CCoommppoossiittee((33XX)), CCoonnssttrraaiinntt((33XX)), CCoorree((33XX)), XXmmCCrreeaatteeBBuulllleettiinnBBooaarrdd((33XX)),
     XXmmCCrreeaatteeBBuulllleettiinnBBooaarrddDDiiaalloogg((33XX)), XXmmDDiiaallooggSShheellll((33XX)),, and XXmmMMaannaaggeerr((33XX))..




















































   1-147






   XmCascadeButton(3X)



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

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

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

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

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

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

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

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

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

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



   1-148






                                                          XmCascadeButton(3X)


     Classes

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

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

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

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                           XXmmCCaassccaaddeeBBuuttttoonn RReessoouurrccee SSeett
    NNaammee                   CCllaassss             TTyyppee             DDeeffaauulltt   AAcccceessss
    __________________________________________________________________________
    XmNactivateCallback    XmCCallback       XtCallbackList   NULL      C
    XmNcascadePixmap       XmCPixmap         Pixmap           dynamic   CSG
    XmNcascadingCallback   XmCCallback       XtCallbackList   NULL      C
    XmNmappingDelay        XmCMappingDelay   int              180 ms    CSG
    XmNsubMenuId           XmCMenuWidget     Widget           NULL      CSG

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

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

     XXmmNNccaassccaaddiinnggCCaallllbbaacckk
               Specifies the list of callbacks that is called just prior to
               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.



   1-149






   XmCascadeButton(3X)


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

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

     Inherited Resources

     CascadeButton inherits behavior and resources from the following superc-
     lasses.  For a complete description of each resource, refer to the man
     page for that superclass.
                                              XXmmLLaabbeell RReessoouurrccee SSeett
   NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                  AAcccceessss
   ___________________________________________________________________________________________________________
   XmNaccelerator              XmCAccelerator              String              NULL                     N/A
   XmNacceleratorText          XmCAcceleratorText          XmString            NULL                     N/A
   XmNalignment                XmCAlignment                unsigned char       dynamic                  CSG
   XmNfontList                 XmCFontList                 XmFontList          dynamic                  CSG
   XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP     CSG
   XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP     CSG
   XmNlabelString              XmCXmString                 XmString            dynamic                  CSG
   XmNlabelType                XmCLabelType                unsigned char       XmSTRING                 CSG
   XmNmarginBottom             XmCMarginBottom             Dimension           dynamic                  CSG
   XmNmarginHeight             XmCMarginHeight             Dimension           2                        CSG
   XmNmarginLeft               XmCMarginLeft               Dimension           0                        CSG
   XmNmarginRight              XmCMarginRight              Dimension           dynamic                  CSG
   XmNmarginTop                XmCMarginTop                Dimension           dynamic                  CSG
   XmNmarginWidth              XmCMarginWidth              Dimension           dynamic                  CSG
   XmNmnemonic                 XmCMnemonic                 KeySym              NULL                     CSG
   XmNmnemonicCharSet          XmCMnemonicCharSet          String              XmFONTLIST_DEFAULT_TAG   CSG
   XmNrecomputeSize            XmCRecomputeSize            Boolean             True                     CSG
   XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                  CSG
                                       XXmmPPrriimmiittiivvee RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt                AAcccceessss
   ________________________________________________________________________________________________
   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic                CSG
   XmNbottomShadowPixmap   XmCBottomShadowPixmap   Pixmap             XmUNSPECIFIED_PIXMAP   CSG
   XmNforeground           XmCForeground           Pixel              dynamic                CSG
   XmNhelpCallback         XmCCallback             XtCallbackList     NULL                   C
   XmNhighlightColor       XmCHighlightColor       Pixel              dynamic                CSG
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False                  CSG
   XmNhighlightPixmap      XmCHighlightPixmap      Pixmap             dynamic                CSG
   XmNhighlightThickness   XmCHighlightThickness   Dimension          0                      CSG
   XmNnavigationType       XmCNavigationType       XmNavigationType   XmNONE                 CSG
   XmNshadowThickness      XmCShadowThickness      Dimension          2                      CSG


   1-150






                                                          XmCascadeButton(3X)


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

     Callback Information

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

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

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

     Translations

     XmCascadeButton includes translations from Primitive.  XmCascadeButton
     includes the menu traversal translations from XmLabel.  These transla-
     tions may not directly correspond to a translation table.









   1-151






   XmCascadeButton(3X)


     Note that altering translations in ##oovveerrrriiddee or ##aauuggmmeenntt mode is unde-
     fined.

     The translations for a CascadeButton in a MenuBar are listed below.
     These translations may not directly correspond to a translation table.
     BBSSeelleecctt PPrreessss:: MMeennuuBBaarrSSeelleecctt(())
     BBSSeelleecctt RReelleeaassee::DDooSSeelleecctt(())
     KKAAccttiivvaattee::     KKeeyySSeelleecctt(())
     KKSSeelleecctt::       KKeeyySSeelleecctt(())
     KKHHeellpp::         HHeellpp(())
     MMAAnnyy KKCCaanncceell::  CClleeaannuuppMMeennuuBBaarr(())

     The translations for a CascadeButton in a PullDown or Popup MenuPane are
     listed below.  In a Popup menu system, BBMMeennuu also performs the BBSSeelleecctt
     actions.  These translations may not directly correspond to a transla-
     tion table.
     BBSSeelleecctt PPrreessss:: SSttaarrttDDrraagg(())
     BBSSeelleecctt RReelleeaassee::DDooSSeelleecctt(())
     KKAAccttiivvaattee::     KKeeyySSeelleecctt(())
     KKSSeelleecctt::       KKeeyySSeelleecctt(())
     KKHHeellpp::         HHeellpp(())
     MMAAnnyy KKCCaanncceell::  CClleeaannuuppMMeennuuBBaarr(())

     Action Routines

     The XmCascadeButton action routines are described below:

     CClleeaannuuppMMeennuuBBaarr(()):
               In a MenuBar, disarms the CascadeButton and the menu and, when
               the shell's keyboard focus policy is XXmmEEXXPPLLIICCTT, restores key-
               board focus to the widget that had the focus before the menu
               was entered.  In a toplevel Pulldown MenuPane from a MenuBar,
               unposts the menu, disarms the MenuBar CascadeButton and the
               MenuBar, and, when the shell's keyboard focus policy is XXmmEEXX--
               PPLLIICCTT, restores keyboard focus to the widget that had the
               focus before the MenuBar was entered.  In other Pulldown Menu-
               Panes, unposts the menu.  In a Popup MenuPane, unposts the
               menu and, when the shell's keyboard focus policy is XXmmEEXXPPLLIICCTT,
               restores keyboard focus to the widget from which the menu was
               posted.

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

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


   1-152






                                                          XmCascadeButton(3X)


               action calls the help callbacks for the nearest ancestor that
               has them.

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

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

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

     Additional Behavior

     Posting a submenu calls the XXmmNNccaassccaaddiinnggCCaallllbbaacckk callbacks.  This widget
     has the additional behavior described below:

     <<EEnntteerrWWiinnddooww>>:
               If keyboard traversal is enabled does nothing.  Otherwise, in
               a MenuBar that is armed, unposts any MenuPanes associated with
               another MenuBar entry, arms the CascadeButton, and posts the
               associated submenu.  In other menus, arms the CascadeButton
               and posts the associated submenu after the delay specified by
               XXmmNNmmaappppiinnggDDeellaayy.

     <<LLeeaavveeWWiinnddooww>>:
               If keyboard traversal is enabled does nothing.  Otherwise, in
               a MenuBar that is armed, disarms the CascadeButton if the sub-
               menu associated with the CascadeButton is not currently posted
               or if there is no submenu associated with the CascadeButton.
               In other menus, if the pointer moves anywhere except into a
               submenu associated with the CascadeButton, the CascadeButton
               is disarmed and its submenu is unposted.

     Virtual Bindings

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






   1-153






   XmCascadeButton(3X)


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



















































   1-154






                                                    XmCascadeButtonGadget(3X)



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

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

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

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

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

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

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

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

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

     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;


   1-155






   XmCascadeButtonGadget(3X)


     otherwise, it takes LabelGadget's default, which is 2.

     Classes

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

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

     The class name is XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett.

     New Resources

     The following table defines a set of widget resources used by the pro-
     grammer to specify data.  The programmer can also set the resource
     values for the inherited classes to set attributes for this widget.  To
     reference a resource by name or by class in a .Xdefaults file, remove
     the XXmmNN or XXmmCC prefix and use the remaining letters.  To specify one of
     the defined values for a resource in a .Xdefaults file, remove the XXmm
     prefix and use the remaining letters (in either lowercase or uppercase,
     but include any underscores between words).  The codes in the access
     column indicate if the given resource can be set at creation time (C),
     set by using XXttSSeettVVaalluueess (S), retrieved by using XXttGGeettVVaalluueess (G), or is
     not applicable (N/A).
                              XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett
    NNaammee                   CCllaassss             TTyyppee             DDeeffaauulltt   AAcccceessss
    __________________________________________________________________________
    XmNactivateCallback    XmCCallback       XtCallbackList   NULL      C
    XmNcascadePixmap       XmCPixmap         Pixmap           dynamic   CSG
    XmNcascadingCallback   XmCCallback       XtCallbackList   NULL      C
    XmNmappingDelay        XmCMappingDelay   int              180 ms    CSG
    XmNsubMenuId           XmCMenuWidget     Widget           NULL      CSG

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

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



   1-156






                                                    XmCascadeButtonGadget(3X)


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

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

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

     Inherited Resources

     CascadeButtonGadget inherits behavior and resources from the following
     superclasses.  For a complete description of each resource, refer to the
     man page for that superclass.
                                          XXmmLLaabbeellGGaaddggeett RReessoouurrccee SSeett
   NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                AAcccceessss
   _________________________________________________________________________________________________________
   XmNaccelerator              XmCAccelerator              String              NULL                   N/A
   XmNacceleratorText          XmCAcceleratorText          XmString            NULL                   N/A
   XmNalignment                XmCAlignment                unsigned char       dynamic                CSG
   XmNfontList                 XmCFontList                 XmFontList          dynamic                CSG
   XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP   CSG
   XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP   CSG
   XmNlabelString              XmCXmString                 XmString            dynamic                CSG
   XmNlabelType                XmCLabelType                unsigned char       XmSTRING               CSG
   XmNmarginBottom             XmCMarginBottom             Dimension           dynamic                CSG
   XmNmarginHeight             XmCMarginHeight             Dimension           2                      CSG
   XmNmarginLeft               XmCMarginLeft               Dimension           0                      CSG
   XmNmarginRight              XmCMarginRight              Dimension           dynamic                CSG
   XmNmarginTop                XmCMarginTop                Dimension           dynamic                CSG
   XmNmarginWidth              XmCMarginWidth              Dimension           dynamic                CSG
   XmNmnemonic                 XmCMnemonic                 KeySym              NULL                   CSG
   XmNmnemonicCharSet          XmCMnemonicCharSet          String              dynamic                CSG
   XmNrecomputeSize            XmCRecomputeSize            Boolean             True                   CSG
   XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                CSG
                                  XXmmGGaaddggeett RReessoouurrccee SSeett
   NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt   AAcccceessss
   ___________________________________________________________________________________
   XmNbottomShadowColor    XmCBottomShadowColor    Pixel              dynamic   G
   XmNhelpCallback         XmCCallback             XtCallbackList     NULL      C
   XmNhighlightColor       XmCHighlightColor       Pixel              dynamic   G
   XmNhighlightOnEnter     XmCHighlightOnEnter     Boolean            False     CSG


   1-157






   XmCascadeButtonGadget(3X)


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

     Callback Information

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

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

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

     Behavior

     XmCascadeButtonGadget includes behavior from XmGadget.  XmCascadeButton
     includes the menu traversal behavior from XmLabel.  Additional XmCas-
     cadeButtonGadget behavior is described below (in a Popup menu system,
     BBMMeennuu also performs the BBSSeelleecctt actions):

     BBSSeelleecctt PPrreessss:
               Unposts any menus posted by the parent menu.  Arms the Cas-
               cadeButtonGadget, posts the associated submenu, enables mouse
               traversal, and, in a MenuBar, arms the MenuBar.  If the menu
               is already active, this event disables keyboard traversal for
               the menu and returns the menu to mouse traversal mode.

     BBSSeelleecctt RReelleeaassee:
               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 CascadeButtonGadget and enables keyboard
               traversal within the menu.  If the CascadeButtonGadget does


   1-158






                                                    XmCascadeButtonGadget(3X)


               not have a submenu attached, calls the callbacks in XXmmNNaacc--
               ttiivvaatteeCCaallllbbaacckk, the CascadeButtonGadget is activated and all
               posted menus in the cascade are unposted.

     KKAAccttiivvaattee:
               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 CascadeButtonGadget if keyboard
               traversal is enabled in the menu.  If the CascadeButtonGadget
               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 CascadeButtonGadget is activated and
               all posted menus in the cascade are unposted.  This action
               applies only to gadgets in MenuBars, PulldownMenus, and Popup-
               Menus.  For a CascadeButtonGadget in an OptionMenu, if the
               parent is a manager, this action passes the event to the
               parent.

     KKS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 CascadeButtonGadget if keyboard
               traversal is enabled in the menu.  If the CascadeButtonGadget
               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 CascadeButtonGadget is activated and
               all posted menus in the cascade are unposted.

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

     MMAAnnyy KKCCaanncceell:
               In a MenuBar, disarms the CascadeButtonGadget 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.  For a CascadeButtonGadget in an
               OptionMenu, if the parent is a manager, this action passes the
               event to the parent.  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 restores keyboard focus to the widget from which the
               menu was posted.

     <<EEnntteerr>>:  If keyboard traversal is enabled does nothing.  Otherwise, in
               a MenuBar, unposts any MenuPanes associated with another Menu-
               Bar entry, arms the CascadeButtonGadget, and posts the associ-
               ated submenu.  In other menus, arms the CascadeButtonGadget
               and posts the associated submenu after the delay specified by
               XXmmNNmmaappppiinnggDDeellaayy.

     <<LLeeaavvee>>:  If keyboard traversal is enabled does nothing.  Otherwise, in


   1-159






   XmCascadeButtonGadget(3X)


               a MenuBar, disarms the CascadeButtonGadget if the submenu
               associated with the CascadeButtonGadget is not currently
               posted or if there is no submenu associated with the Cascade-
               ButtonGadget.  In other menus, if the pointer moves anywhere
               except into a submenu associated with the CascadeButtonGadget,
               the CascadeButtonGadget is disarmed and its submenu is
               unposted.

     Virtual Bindings

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

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






































   1-160






                                           XmCascadeButtonGadgetHighlight(3X)



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

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

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

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

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

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

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




























   1-161






   XmCascadeButtonHighlight(3X)



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

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

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

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

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

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

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



























   1-162






                                                            XmChangeColor(3X)



   NAME
     XXmmCChhaannggeeCCoolloorr-Recalculates all associated colors of a widget

   SYNOPSIS
     ##iinncclluuddee <<XXmm//XXmm..hh>>
     vvooiidd XXmmCChhaannggeeCCoolloorr ((_w_i_d_g_e_t, _b_a_c_k_g_r_o_u_n_d))
          WWiiddggeett    _w_i_d_g_e_t;;
          PPiixxeell     _b_a_c_k_g_r_o_u_n_d;;

   DESCRIPTION
     XXmmCChhaannggeeCCoolloorr handles all color modifications for the specified widget
     when a new background pixel value is specified.  The function recalcu-
     lates the foreground, select, and shadow colors based on the new back-
     ground color and sets the corresponding resources for the widget.  If a
     color calculation procedure has been set by a call to XXmmSSeettCCoolloorrCCaallccuullaa--
     ttiioonn, XXmmCChhaannggeeCCoolloorr uses that procedure to calculate the new colors.
     Otherwise, the routine uses a default procedure.

     _w_i_d_g_e_t Specifies the widget ID whose colors will be updated

     _p_i_x_e_l  Specifies the background color pixel value

   RELATED INFORMATION
     XXmmGGeettCCoolloorrCCaallccuullaattiioonn((33XX)), XXmmGGeettCCoolloorrss((33XX)), and
     XXmmSSeettCCoolloorrCCaallccuullaattiioonn((33XX)).






























   1-163






   XmClipboardCancelCopy(3X)



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

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

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

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

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

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

   RETURN VALUE

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

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

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





   1-164






                                                    XmClipboardCancelCopy(3X)


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





















































   1-165






   XmClipboardCopy(3X)



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

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

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

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

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

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

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

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

     _i_t_e_m__i_d     Specifies the number assigned to this data item.  This


   1-166






                                                          XmClipboardCopy(3X)


                 number was returned by a previous call to XXmmCClliipp--
                 bbooaarrddSSttaarrttCCooppyy.

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

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

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

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

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

   RETURN VALUE

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

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

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

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
















   1-167






   XmClipboardCopyByName(3X)



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

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

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

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

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

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

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

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

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

   RETURN VALUE

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

     CClliippbbooaarrddLLoocckkeedd
                 The function failed because the clipboard was locked by
                 another application.  The application can continue to call
                 the function again with the same parameters until the lock


   1-168






                                                    XmClipboardCopyByName(3X)


                 goes away.  This gives the application the opportunity to
                 ask if the user wants to keep trying or to give up on the
                 operation.

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

















































   1-169






   XmClipboardEndCopy(3X)



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

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

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

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

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

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

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

   RETURN VALUE

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

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

     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.


   1-170






                                                       XmClipboardEndCopy(3X)



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




















































   1-171






   XmClipboardEndRetrieve(3X)



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

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

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

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

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

   RETURN VALUE

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

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

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












   1-172






                                                  XmClipboardInquireCount(3X)



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

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

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

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

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

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

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

   RETURN VALUE

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

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

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


   1-173






   XmClipboardInquireCount(3X)


                     in the requested format was passed by name and is no
                     longer available.

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



















































   1-174






                                                 XmClipboardInquireFormat(3X)



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

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

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

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

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

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

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

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

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

   RETURN VALUE

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

     CClliippbbooaarrddLLoocckkeedd
                  The function failed because the clipboard was locked by
                  another application.  The application can continue to call
                  the function again with the same parameters until the lock


   1-175






   XmClipboardInquireFormat(3X)


                  goes away.  This gives the application the opportunity to
                  ask if the user wants to keep trying or to give up on the
                  operation.

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

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

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






































   1-176






                                                 XmClipboardInquireLength(3X)



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

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

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

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

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

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

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

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

   RETURN VALUE

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

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

     CClliippbbooaarrddNNooDDaattaa


   1-177






   XmClipboardInquireLength(3X)


                 The function could not find data on the clipboard
                 corresponding to the format requested.  This could occur
                 because the clipboard is empty; there is data on the clip-
                 board but not in the requested format; or the data in the
                 requested format was passed by name and is no longer avail-
                 able.

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















































   1-178






                                           XmClipboardInquirePendingItems(3X)



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

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

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

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

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

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

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

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

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

   RETURN VALUE

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


   1-179






   XmClipboardInquirePendingItems(3X)



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

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













































   1-180






                                                          XmClipboardLock(3X)



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

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

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

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

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

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

   RETURN VALUE

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

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

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





   1-181






   XmClipboardRegisterFormat(3X)



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

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

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

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

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

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

   RETURN VALUE

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

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

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

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






   1-182






                                                XmClipboardRegisterFormat(3X)


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






















































   1-183






   XmClipboardRetrieve(3X)



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

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

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

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

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

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

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

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

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

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



   1-184






                                                      XmClipboardRetrieve(3X)


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

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

   RETURN VALUE

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

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

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

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

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



















   1-185






   XmClipboardStartCopy(3X)



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

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

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

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

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

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

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

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

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


   1-186






                                                     XmClipboardStartCopy(3X)


                 name of the application that places the data in the clip-
                 board.

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

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

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

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

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

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

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

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

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











   1-187






   XmClipboardStartCopy(3X)



   RETURN VALUE

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

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

   RELATED INFORMATION
     XXmmCClliippbbooaarrddC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)).

































   1-188






                                                 XmClipboardStartRetrieve(3X)



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

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

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

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

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

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

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

   RETURN VALUE

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

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


   1-189






   XmClipboardStartRetrieve(3X)


     operation.

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
















































   1-190






                                                      XmClipboardUndoCopy(3X)



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

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

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

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

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

   RETURN VALUE

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

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

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












   1-191






   XmClipboardUnlock(3X)



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

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

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

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

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

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

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

   RETURN VALUE

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

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

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





   1-192






                                                XmClipboardWithdrawFormat(3X)



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

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

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

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

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

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

   RETURN VALUE

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

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

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









   1-193



 n
