


     XXmmAAccttiivvaatteePPrroottooccooll((33XX))   RReeffeerreennccee PPaaggeess   XXmmAAccttiivvaatteePPrroottooccooll((33XX))



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

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


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

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

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






     XXmmAAccttiivvaatteeWWMMPPrroottooccooll((33XX)) RReeffeerreennccee PPaaggeess XXmmAAccttiivvaatteeWWMMPPrroottooccooll((33XX))



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

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


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

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

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






     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))RReeffeerreennccee PPaaggeessXXmmAAddddPPrroottooccoollCCaallllbbaacckk((33XX))



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

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


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

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





     1-145                                            (printed 5/7/92)






     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))RReeffeerreennccee PPaaggeessXXmmAAddddPPrroottooccoollCCaallllbbaacckk((33XX))



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

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






     XXmmAAddddPPrroottooccoollss((33XX))       RReeffeerreennccee PPaaggeess       XXmmAAddddPPrroottooccoollss((33XX))



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

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


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

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






     XXmmAAddddTTaabbGGrroouupp((33XX))        RReeffeerreennccee PPaaggeess        XXmmAAddddTTaabbGGrroouupp((33XX))



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

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

          vvooiidd XXm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;;


     DDEESSCCRRIIPPTTIIOONN
          This function is obsolete and its behavior is replaced by
          setting XXmmNNnnaav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.


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






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



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

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


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

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

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






     XXmmAAddddWWMMPPrroottooccoollss((33XX))     RReeffeerreennccee PPaaggeess     XXmmAAddddWWMMPPrroottooccoollss((33XX))



     NNAAMMEE
          XXmmAAddddWWMMPPrroottooccoollss-A VendorShell convenience interface that
          adds the protocols to the protocol manager and allocates the
          internal tables

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


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

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






     XXmmAArrrroowwBBuuttttoonn((33XX))        RReeffeerreennccee PPaaggeess        XXmmAArrrroowwBBuuttttoonn((33XX))



     NNAAMMEE
          XXmmAArrrroowwBBuuttttoonn-The ArrowButton widget class

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//AArrrroowwBB..hh>>


     DDEESSCCRRIIPPTTIIOONN
          ArrowButton consists of a directional arrow surrounded by a
          border shadow.  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 ArrowButton is released, or
          out.

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

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

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



     1-151                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonn((33XX))        RReeffeerreennccee PPaaggeess        XXmmAArrrroowwBBuuttttoonn((33XX))



                    pointer is inside the ArrowButton widget.
                    Activating the ArrowButton also disarms it.  The
                    reason 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 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  XXmmAARRRROOWW__UUPP.

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

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

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


        IInnhheerriitteedd RReessoouurrcceess
          ArrowButton inherits behavior and resources from the
          following superclasses.  For a complete description of each
          resource, refer to the man page for that superclass.

                                         XXmmPPrriimmiittiivvee RReessoouurrccee SSeett





     1-152                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonn((33XX))        RReeffeerreennccee PPaaggeess        XXmmAArrrroowwBBuuttttoonn((33XX))



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

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

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




     1-153                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonn((33XX))        RReeffeerreennccee PPaaggeess        XXmmAArrrroowwBBuuttttoonn((33XX))



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


        TTrraannssllaattiioonnss
          XmArrowButton includes translations for XmPrimitive.
          Additional XmArrowButton 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(())
          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(())

























     1-154                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonn((33XX))        RReeffeerreennccee PPaaggeess        XXmmAArrrroowwBBuuttttoonn((33XX))



        AAccttiioonn RRoouuttiinneess
          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eC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 callbacks 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lb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-155                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonn((33XX))        RReeffeerreennccee PPaaggeess        XXmmAArrrroowwBBuuttttoonn((33XX))



        AAddddiittiioonnaall BBeehhaavviioorr
          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.


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

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






     XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))  RReeffeerreennccee PPaaggeess  XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//AArrrroowwBBGG..hh>>


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

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

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

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



     1-157                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))  RReeffeerreennccee PPaaggeess  XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))



                    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.

          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  XXmmAARRRROOWW__UUPP.

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

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

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


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






     1-158                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))  RReeffeerreennccee PPaaggeess  XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))



     NNaammee                    CCllaassss                   TTyyppee               DDeeffaauulltt   AAcccceessss
     ___________________________________________________________________________________
     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
      ____________________________________________________________________
      XmNancestorSensitive   XmCSensitive     Boolean     dynamic   G
      XmNborderWidth         XmCBorderWidth   Dimension   0         CSG
      XmNheight              XmCHeight        Dimension   dynamic   CSG
      XmNsensitive           XmCSensitive     Boolean     True      CSG
      XmNwidth               XmCWidth         Dimension   dynamic   CSG
      XmNx                   XmCPosition      Position    0         CSG
      XmNy                   XmCPosition      Position    0         CSG

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

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

          ttyyppeeddeeff ssttrruucctt
          {{
            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



     1-159                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))  RReeffeerreennccee PPaaggeess  XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))



                 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.


        BBeehhaavviioorr
          XmArrowButtonGadget includes behavior from XmGadget.
          Additional XmArrowButtonGadget 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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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.

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



     1-160                                            (printed 5/7/92)






     XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))  RReeffeerreennccee PPaaggeess  XXmmAArrrroowwBBuuttttoonnGGaaddggeett((33XX))



                    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.


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

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






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



     NNAAMMEE
          XXmmBBuulllleettiinnBBooaarrdd-The BulletinBoard widget class

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//BBuulllleettiinnBB..hh>>


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

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

          The class pointer is xxm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.

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




     1-162                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



                               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
     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 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
                    XmBulletinBoard, VendorShell, or XmMenuShell



     1-163                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



                    widget class.  If such an ancestor is found, the
                    font list is initialized to the XXmmNNbbuuttttoonnFFoonnttLLiisstt
                    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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 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 BulletinBoard is a
                    DialogShell, the BulletinBoard is centered within
                    or around the parent of the DialogShell when the
                    BulletinBoard 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  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 application

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







     1-164                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



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

                      +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  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  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, BulletinBoard 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 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 BulletinBoard 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.














     1-165                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



          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 descendants (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
                    subclass of the XmBulletinBoard, VendorShell, or
                    XmMenuShell widget class.  If such an ancestor is
                    found, the font list is initialized to the
                    XXmmN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
                    BulletinBoard 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-166                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



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


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

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

                      +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  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  XXmmSSHHAADDOOWW__OOUUTT-draws the BulletinBoard shadow
                         so that it appears outset

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




















     1-167                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



          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
                    XmBulletinBoard or VendorShell widget class.  If
                    such an ancestor is found, the font list is
                    initialized to the XXmmNNtteexxttFFoonnttLLiisstt of the ancestor
                    widget.  If no such ancestor is found, the default
                    is implementation  dependent.  Refer to
                    XXmmFFoonnttLLiisstt((33XX)) for more information on 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.


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







     1-168                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



     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

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

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


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

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


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



     1-169                                            (printed 5/7/92)






     XXmmBBuulllleettiinnBBooaarrdd((33XX))      RReeffeerreennccee PPaaggeess      XXmmBBuulllleettiinnBBooaarrdd((33XX))



          XmBulletinBoard includes the translations from XmManager.

        AAddddiittiioonnaall BBeehhaavviioorr
          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 BulletinBoard 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 BulletinBoard 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 policy 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.


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

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






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



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

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


     DDEESSCCRRIIPPTTIIOONN
          CascadeButton links two MenuPanes or a MenuBar to a
          MenuPane.

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

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

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

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

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

          CascadeButton provides a single mechanism for activating the
          widget from the keyboard.  This mechanism is referred to as
          a keyboard mnemonic.  If a mnemonic has been specified for
          the widget, the user may activate the CascadeButton by
          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



     1-171                                            (printed 5/7/92)






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



          pressed with the mnemonic.  Mnemonics are typically used to
          interact with a menu via the keyboard interface.

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

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

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

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

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

                            XXmmCCaassccaaddeeBBuuttttoonn RReessoouurrccee SSeett
     NNaammee                   CCllaassss             TTyyppee             DDeeffaauulltt   AAcccceessss
     __________________________________________________________________________
     XmNactivateCallback    XmCCallback       XtCallbackList   NULL      C
     XmNcascadePixmap       XmCPixmap         Pixmap           dynamic   CSG
     XmNcascadingCallback   XmCCallback       XtCallbackList   NULL      C
     XmNmappingDelay        XmCMappingDelay   int              180 ms    CSG
     XmNsubMenuId           XmCMenuWidget     Widget           NULL      CSG


          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.



     1-172                                            (printed 5/7/92)






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



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

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

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

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


        IInnhheerriitteedd RReessoouurrcceess
          CascadeButton inherits behavior and resources from the
          following superclasses.  For a complete description of each
          resource, refer to the man page for that superclass.

                                                XXmmLLaabbeell RReessoouurrccee SSeett
     NNaammee                        CCllaassss                       TTyyppee                DDeeffaauulltt                  AAcccceessss
     ___________________________________________________________________________________________________________
     XmNaccelerator              XmCAccelerator              String              NULL                     N/A
     XmNacceleratorText          XmCAcceleratorText          XmString            NULL                     N/A
     XmNalignment                XmCAlignment                unsigned char       dynamic                  CSG
     XmNfontList                 XmCFontList                 XmFontList          dynamic                  CSG







     1-173                                            (printed 5/7/92)






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



     XmNlabelInsensitivePixmap   XmCLabelInsensitivePixmap   Pixmap              XmUNSPECIFIED_PIXMAP     CSG
     XmNlabelPixmap              XmCLabelPixmap              Pixmap              XmUNSPECIFIED_PIXMAP     CSG
     XmNlabelString              XmCXmString                 XmString            dynamic                  CSG
     XmNlabelType                XmCLabelType                unsigned char       XmSTRING                 CSG
     XmNmarginBottom             XmCMarginBottom             Dimension           dynamic                  CSG
     XmNmarginHeight             XmCMarginHeight             Dimension           2                        CSG
     XmNmarginLeft               XmCMarginLeft               Dimension           0                        CSG
     XmNmarginRight              XmCMarginRight              Dimension           dynamic                  CSG
     XmNmarginTop                XmCMarginTop                Dimension           dynamic                  CSG
     XmNmarginWidth              XmCMarginWidth              Dimension           dynamic                  CSG
     XmNmnemonic                 XmCMnemonic                 KeySym              NULL                     CSG
     XmNmnemonicCharSet          XmCMnemonicCharSet          String              XmFONTLIST_DEFAULT_TAG   CSG
     XmNrecomputeSize            XmCRecomputeSize            Boolean             True                     CSG
     XmNstringDirection          XmCStringDirection          XmStringDirection   dynamic                  CSG

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







     1-174                                            (printed 5/7/92)






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



     XmNinitialResourcesPersistent   XmCInitialResourcesPersistent   Boolean          True                   C
     XmNmappedWhenManaged            XmCMappedWhenManaged            Boolean          True                   CSG
     XmNscreen                       XmCScreen                       Screen *         dynamic                CG
     XmNsensitive                    XmCSensitive                    Boolean          True                   CSG
     XmNtranslations                 XmCTranslations                 XtTranslations   dynamic                CSG
     XmNwidth                        XmCWidth                        Dimension        dynamic                CSG
     XmNx                            XmCPosition                     Position         0                      CSG
     XmNy                            XmCPosition                     Position         0                      CSG

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

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


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

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


        TTrraannssllaattiioonnss
          XmCascadeButton includes translations from Primitive.
          XmCascadeButton includes the menu traversal translations
          from XmLabel.  These translations may not directly
          correspond to a translation table.

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

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



     1-175                                            (printed 5/7/92)






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



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


        AAccttiioonn RRoouuttiinneess
          The XmCascadeButton action routines are described below:


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

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

                    In a Popup MenuPane, unposts the menu and, when
                    the shell's keyboard focus policy is XXmmEEXXPPLLIICCTT,
                    restores keyboard focus to the widget from which
                    the menu was posted.

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

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

          KKeeyySSeelleecctt(()):



     1-176                                            (printed 5/7/92)






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



                    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.


        AAddddiittiioonnaall BBeehhaavviioorr
          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 submenu 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.


        VViirrttuuaall BBiinnddiinnggss



     1-177                                            (printed 5/7/92)






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



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

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






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



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

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


     DDEESSCCRRIIPPTTIIOONN
          CascadeButtonGadget links two MenuPanes, a MenuBar to a
          MenuPane, or an OptionMenu to a MenuPane.

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

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

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

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

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

          CascadeButtonGadget provides a single mechanism for
          activating the gadget from the keyboard.  This mechanism is
          referred to as a keyboard mnemonic.  If a mnemonic has been
          specified for the gadget, the user may activate it by simply
          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



     1-179                                            (printed 5/7/92)






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



          pressed with the mnemonic.  Mnemonics are typically used to
          interact with a menu via the keyboard.

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

        CCllaasssseess
          CascadeButtonGadget inherits behavior and resources from
          OObbjjeecctt, RReeccttOObbjj, XXmmGGaaddggeett, and XXmmLLaabbeellGGaaddggeett classes.

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

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

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

                               XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett
     NNaammee                   CCllaassss             TTyyppee             DDeeffaauulltt   AAcccceessss
     __________________________________________________________________________
     XmNactivateCallback    XmCCallback       XtCallbackList   NULL      C
     XmNcascadePixmap       XmCPixmap         Pixmap           dynamic   CSG
     XmNcascadingCallback   XmCCallback       XtCallbackList   NULL      C
     XmNmappingDelay        XmCMappingDelay   int              180 ms    CSG
     XmNsubMenuId           XmCMenuWidget     Widget           NULL      CSG


          XXmmNNaaccttiivvaatteeCCaallllbbaacckk
                    Specifies the list of callbacks that is called
                    when the user activates the CascadeButtonGadget,
                    and there is no submenu attached to pop up.  The
                    activation occurs by releasing a mouse button or
                    by typing the mnemonic associated with the gadget.
                    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.



     1-180                                            (printed 5/7/92)






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



          XXmmNNccaassccaaddeePPiixxmmaapp
                    Specifies the cascade pixmap displayed on one end
                    of the gadget when a CascadeButtonGadget is used
                    within a Popup or Pulldown MenuPane and a submenu
                    is attached.  The LabelGadget class resources
                    XXmmNNmmaarrggiinnBBoottttoomm, XXmmNNmmaarrggiinnLLeefftt, XXmmNNmmaarrggiinnRRiigghhtt,
                    and XXmmNNmmaarrggiinnTToopp may be modified to ensure that
                    room is left for the cascade pixmap.  The default
                    cascade pixmap in menus other than option menus is
                    an arrow pointing to the side of the menu where
                    the submenu will appear.  The default for the
                    CascadeButtonGadget in an option menu is
                    XXmmUUNNSSPPEECCIIFFIIEEDD__PPIIXXMMAAPP.

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

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

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


        IInnhheerriitteedd RReessoouurrcceess
          CascadeButtonGadget inherits behavior and resources from the
          following superclasses.  For a complete description of each
          resource, refer to the man page for that superclass.

                                            XXmmLLaabbeellGGaaddggeett RReessoouurrccee SSeett
     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







     1-181                                            (printed 5/7/92)






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



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

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



     1-182                                            (printed 5/7/92)






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



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


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

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


        BBeehhaavviioorr
          XmCascadeButtonGadget includes behavior from XmGadget.
          XmCascadeButton includes the menu traversal behavior from
          XmLabel.  Additional XmCascadeButtonGadget 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 CascadeButtonGadget, 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 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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 PopupMenus.  For a



     1-183                                            (printed 5/7/92)






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



                    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 MenuBar entry, arms the
                    CascadeButtonGadget, and posts the associated
                    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.




     1-184                                            (printed 5/7/92)






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



          <<LLeeaavvee>>:  If keyboard traversal is enabled does nothing.
                    Otherwise, in 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
                    CascadeButtonGadget.

                    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.


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

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






     XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhllRRieiegfgfhehetrtr(e(e3n3nXXXcmXcm)eC)eC aaPsPsacacgagaededseseBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt((33XX))



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

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

          vvooiidd XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt ((_c_a_s_c_a_d_e_B_u_t_t_o_n_G_a_d_g_e_t, _h_i_g_h_l_i_g_h_t))
               WWiiddggeett    _c_a_s_c_a_d_e_B_u_t_t_o_n_G_a_d_g_e_t;;
               BBoooolleeaann   _h_i_g_h_l_i_g_h_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt either draws or erases the
          shadow highlight around the CascadeButtonGadget.


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

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


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCCaassccaaddeeBBuuttttoonn((33XX)), XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)), and
          XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33XX)).
























     1-186                                            (printed 5/7/92)






     XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33RRXeXe)f)feerreennccee PPaaggXXememsCsCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt((33XX))



     NNAAMMEE
          XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt-A CascadeButton and
          CascadeButtonGadget function that sets the highlight state

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

          vvooiidd XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt ((_c_a_s_c_a_d_e_B_u_t_t_o_n, _h_i_g_h_l_i_g_h_t))
               WWiiddggeett    _c_a_s_c_a_d_e_B_u_t_t_o_n;;
               BBoooolleeaann   _h_i_g_h_l_i_g_h_t;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmCCaassccaaddeeBBuuttttoonnHHiigghhlliigghhtt either draws or erases the shadow
          highlight around the CascadeButton or the
          CascadeButtonGadget.


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

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


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

     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCCaassccaaddeeBBuuttttoonn((33XX)), XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeett((33XX)) and
          XXmmCCaassccaaddeeBBuuttttoonnGGaaddggeettHHiigghhlliigghhtt((33XX)).





















     1-187                                            (printed 5/7/92)






     XXmmCChhaannggeeCCoolloorr((33XX))        RReeffeerreennccee PPaaggeess        XXmmCChhaannggeeCCoolloorr((33XX))



     NNAAMMEE
          XXmmCChhaannggeeCCoolloorr-Recalculates all associated colors of a widget

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

          vvooiidd XXm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;;


     DDEESSCCRRIIPPTTIIOONN
          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 recalculates the foreground,
          select, and shadow colors based on the new background 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at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


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






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddCCaanncceellCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _i_t_e_m__i_d))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;
               lloonngg      _i_t_e_m__i_d;;


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


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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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



     1-189                                            (printed 5/7/92)






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



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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCooppyy((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), and
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).









































     1-190                                            (printed 5/7/92)






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



     NNAAMMEE
          XXmmCClliippbbooaarrddCCooppyy-A clipboard function that copies a data item
          to temporary storage for later copying to clipboard

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


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

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

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

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


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



     1-191                                            (printed 5/7/92)






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



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

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

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

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

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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCooppyyBByyNNaammee((33XX)), XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), and
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).



     1-192                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


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


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

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

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

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

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

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





     1-193                                            (printed 5/7/92)






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



     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCooppyy((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), and XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).






































     1-194                                            (printed 5/7/92)






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



     NNAAMMEE
          XXmmCClliippbbooaarrddEEnnddCCooppyy-A clipboard function that ends a copy to
          the clipboard

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddEEnnddCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _i_t_e_m__i_d))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;
               lloonngg      _i_t_e_m__i_d;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddEEnnddCCooppyy locks the clipboard from access by other
          applications, places data in the clipboard data structure,
          and unlocks the clipboard.  Data items copied to the
          clipboard by XXmmCClliippbbooaarrddCCooppyy are not actually entered in the
          clipboard data structure until the call to
          XXmmCClliippbbooaarrddEEnnddCCooppyy.

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


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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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



     1-195                                            (printed 5/7/92)






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



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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX)), XXmmCClliippbbooaarrddCCooppyy((33XX)) and
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).










































     1-196                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddEEnnddRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;


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


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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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


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






     XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XXRR)e)effeerreennccee PPaaggeeXXsmsmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt returns the number of data item
          formats available for the data item in the clipboard.  This
          function also returns the maximum name-length for all
          formats in which the data item is stored.


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

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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessssThe function is successful.

          CClliippbbooaarrddLLoocckkeedd The function failed because the clipboard
                          was locked by another application.  The



     1-198                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XXRR)e)effeerreennccee PPaaggeeXXsmsmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XX))



                          application can continue to call the
                          function again with the same parameters
                          until the lock goes away.  This gives the
                          application the opportunity to ask if the
                          user wants to keep trying or to give up on
                          the operation.

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).





































     1-199                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33RRXeXe)f)feerreennccee PPaaggXXememsCsClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt returns a specified format name for
          the data item in the clipboard.  If the name must be
          truncated, the function returns a warning status.


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

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

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

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

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

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




     1-200                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33RRXeXe)f)feerreennccee PPaaggXXememsCsClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX))



     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                       The function is successful.

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

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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).

























     1-201                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33RRXeXe)f)feerreennccee PPaaggXXememsCsClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


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

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


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

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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.




     1-202                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33RRXeXe)f)feerreennccee PPaaggXXememsCsClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX))



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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCooppyy((33XX)) and XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).


































     1-203                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIIRRteteefefmemesrsr(e(e3n3nXXXcmXcm)eC)eC llPiPiapapgbgbeoeosasarrddIInnqquuiirreePPeennddiinnggIItteemmss((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


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

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


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

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

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

          _i_t_e_m__l_i_s_t   Specifies the address of the array of data
                      ID/private ID pairs for the specified format
                      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



     1-204                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIIRRteteefefmemesrsr(e(e3n3nXXXcmXcm)eC)eC llPiPiapapgbgbeoeosasarrddIInnqquuiirreePPeennddiinnggIItteemmss((33XX))



                      this function for storing the list.

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).































     1-205                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddLLoocckk ((_d_i_s_p_l_a_y, _w_i_n_d_o_w))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;


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

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


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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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



     1-206                                            (printed 5/7/92)






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



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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)),
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)), and
          XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).















































     1-207                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCslsliippbbooaarrddRReeggiisstteerrFFoorrmmaatt((33XX))



     NNAAMMEE
          XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt-A clipboard function that
          registers a new format

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


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


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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddBBaaddFFoorrmmaatt
                         The _f_o_r_m_a_t__n_a_m_e must not be NULL, and the
                         _f_o_r_m_a_t__l_e_n_g_t_h must be 8, 16, or 32.

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

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



     1-208                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddRReeggiisstteerrFFoorrmmaatt((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCslsliippbbooaarrddRReeggiisstteerrFFoorrmmaatt((33XX))



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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).













































     1-209                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddRReettrriieevvee retrieves the current data item from
          clipboard storage.  It returns a warning if the clipboard is
          locked; if there is no data on the clipboard; or if the data
          needs to be truncated because the buffer length is too
          short.

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

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


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

          _w_i_n_d_o_w      Specifies a widget's window ID that relates the
                      application window to the clipboard.  The
                      widget's window ID can be obtained by using
                      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.



     1-210                                            (printed 5/7/92)






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



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

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

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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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

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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX)), and
          XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).





     1-211                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

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


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddSSttaarrttCCooppyy sets up storage and data structures to
          receive clipboard data.  An application calls this function
          during a cut or copy operation.  The data item that these
          structures receive then becomes the next data item in the
          clipboard.

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

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

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


          _d_i_s_p_l_a_y     Specifies a pointer to the DDiissppllaayy structure
                      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.




     1-212                                            (printed 5/7/92)






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



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

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

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

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

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

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


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

          The _w_i_d_g_e_t and _c_a_l_l_b_a_c_k arguments must be present in order
          to pass data by name. The callback format is as follows:

          vvooiidd ((**_c_a_l_l_b_a_c_k) ((_w_i_d_g_e_t, _d_a_t_a__i_d, _p_r_i_v_a_t_e, _r_e_a_s_o_n))
            WWiiddggeett    _w_i_d_g_e_t;;
            iinntt       **_d_a_t_a__i_d;;
            iinntt       **_p_r_i_v_a_t_e;;
            iinntt       **_r_e_a_s_o_n;;




     1-213                                            (printed 5/7/92)






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



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

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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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


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

















     1-214                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33RRXeXe)f)feerreennccee PPaaggXXememsCsClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _t_i_m_e_s_t_a_m_p))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;
               TTiimmee      _t_i_m_e_s_t_a_m_p;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee tells the clipboard routines that
          the application is ready to start copying an item from the
          clipboard.  The clipboard is locked by this routine and
          stays locked until XXmmCClliippbbooaarrddEEnnddRReettrriieevvee is called.
          Between a call to XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee and a call to
          XXmmCClliippbbooaarrddEEnnddRReettrriieevvee, multiple calls to
          XXmmCClliippbbooaarrddRReettrriieevvee with the same format name result in data
          being incrementally copied from the clipboard until the data
          in that format has all been copied.

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


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

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

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


     RREETTUURRNN VVAALLUUEE



     1-215                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddSSttaarrttRReettrriieevvee((33RRXeXe)f)feerreennccee PPaaggXXememsCsClliippbbooaarrddSSttaarrttRReettrriieevvee((33XX))



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

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt((33XX)),
          XXmmCClliippbbooaarrddIInnqquuiirreeFFoorrmmaatt((33XX)), XXmmCClliippbbooaarrddIInnqquuiirreeLLeennggtthh((33XX)),
          XXmmCClliippbbooaarrddIInnqquuiirreePPeennddiinnggIItteemmss((33XX)), XXmmCClliippbbooaarrddLLoocckk((33XX)),
          XXmmCClliippbbooaarrddRReettrriieevvee((33XX)), XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)), and
          XXmmCClliippbbooaarrddUUnnlloocckk((33XX)).




































     1-216                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddUUnnddooCCooppyy ((_d_i_s_p_l_a_y, _w_i_n_d_o_w))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;


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


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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddLLoocckk((33XX)) and XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).




     1-217                                            (printed 5/7/92)






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



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddUUnnlloocckk ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _r_e_m_o_v_e__a_l_l__l_o_c_k_s))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;
               BBoooolleeaann   _r_e_m_o_v_e__a_l_l__l_o_c_k_s;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddUUnnlloocckk unlocks the clipboard, enabling it to be
          accessed by other applications.

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


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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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


     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCaanncceellCCooppyy((33XX)), XXmmCClliippbbooaarrddCCooppyy((33XX)),
          XXmmCClliippbbooaarrddEEnnddCCooppyy((33XX)), XXmmCClliippbbooaarrddEEnnddRReettrriieevvee((33XX)),



     1-218                                            (printed 5/7/92)






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



          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-219                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCslsliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((33XX))



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

     SSYYNNOOPPSSIISS
          ##iinncclluuddee <<XXmm//XXmm..hh>>
          ##iinncclluuddee <<XXmm//CCuuttPPaassttee..hh>>

          iinntt XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt ((_d_i_s_p_l_a_y, _w_i_n_d_o_w, _d_a_t_a__i_d))
               DDiissppllaayy   * _d_i_s_p_l_a_y;;
               WWiinnddooww    _w_i_n_d_o_w;;
               lloonngg      _d_a_t_a__i_d;;


     DDEESSCCRRIIPPTTIIOONN
          XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt indicates that the application no
          longer supplies a data item to the clipboard that the
          application had previously passed by name.


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

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

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


     RREETTUURRNN VVAALLUUEE
          CClliippbbooaarrddSSuucccceessss
                      The function is successful.

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




     1-220                                            (printed 5/7/92)






     XXmmCClliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((RR3e3eXfXf)e)erreennccee PPaaXXgmgmeCeCslsliippbbooaarrddWWiitthhddrraawwFFoorrmmaatt((33XX))



     RREELLAATTEEDD IINNFFOORRMMAATTIIOONN
          XXmmCClliippbbooaarrddCCooppyy((33XX)) and XXmmCClliippbbooaarrddSSttaarrttCCooppyy((33XX)).





















































     1-221                                            (printed 5/7/92)



 b
