















        Chapter 16.  IInntteerrcclliieenntt CCoommmmuunniiccaattiioonn








             A Motif application can communicate with another
             application in a variety of circumstances:

                +o When negotiating with a window manager such as MWM

                +o When the user makes or transfers a primary,
                  secondary, or clipboard selection

                +o When the user drags data from one application and
                  drops it in another

                +o When the application deals with a resource that is
                  shared with other clients on the display, such as
                  input focus, the pointer, grabs, and colormaps

             The X Consortium Standard _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) defines standards by which X
             clients should communicate with each other.  The Motif
             toolkit and MWM comply with ICCCM.  Applications may
             define private protocols for communicating with other
             applications that share those protocols.  If they do
             so, they should also conform to ICCCM standards.












        May 9, 1992                                             16-1








        OSF/Motif Programmer's Guide


        16.1  WWiinnddooww MMaannaaggeerrss,, IICCCCCCMM,, aanndd SShheellllss



             ICCCM defines protocols for communication between
             clients and window managers.  Most of the communication
             takes place via properties on an application's top-
             level windows.  The window manager can also generate
             events that are available to the application.

             In Motif and Xt, shells handle most communication
             between an application and a window manager.  An
             application seldom has to deal directly with properties
             or events.  The application can usually specify
             properties by setting resources of a shell.  Shells
             also select for and handle most events from the window
             manager.

             This section discusses the relations between some shell
             resources, properties, and events concerned with
             communication between an application and any window
             manager.  The following section discusses resources,
             properties, and events that apply to MWM in particular.



        16.1.1  AApppplliiccaattiioonn SSttaarrttuupp



             When a top-level window is mapped, the window manager
             may search the resource database for information about
             the window.  The resource name and class come from the
             WM_CLASS property for the window.  This property
             contains two consecutive strings that identify the
             instance and class names.

             Xt sets the WM_CLASS property when a shell that is a
             subclass of WWMMSShheellll is realized.  The instance name is
             the name of the shell.  For an ApplicationShell, this
             is generally the name of the application passed to
             XXttDDiissppllaayyIInniittiiaalliizzee.  The class name is the application
             class from the highest-level widget in the hierarchy.
             For an ApplicationShell, this is generally the
             application class passed to XXttDDiissppllaayyIInniittiiaalliizzee.  If
             the root widget is not an ApplicationShell, the class
             name is the widget's class name.

             Most window managers display a name for a top-level
             window, often in a title bar.  The window name comes
             from the WM_NAME property.  This property is a string



        16-2                                             May 9, 1992








                                           Interclient Communication


             whose encoding is identified by the type of the
             property.

             A Motif application specifies a window name via the
             WMShell resources 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.  If
             the shell is a TopLevelShell subclass and the
             XXmmNNiiccoonnNNaammee resource is not NULL, the value of that
             resource is the default for XXmmNNttiittllee.  Otherwise, the
             default title is the name of the shell.  For a dialog,
             an application can supply a title as the value of the
             BulletinBoard resource XXmmNNddiiaallooggTTiittllee.

             XXmmNNttiittlleeEEnnccooddiinngg is an atom representing the encoding
             of the name.  The default title encoding depends on
             whether or not a language procedure has been set.  If
             no language procedure has been set, the default is
             STRING.  If a language procedure has been set, the
             title is assumed to be in the encoding of the locale
             and is passed to XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy with an
             encoding style of XXSSttddIICCCCTTeexxttSSttyyllee.  The returned
             property is used as the WM_NAME property.  If the title
             is fully convertible to type STRING, the encoding is
             STRING; otherwise, the encoding is COMPOUND_TEXT.



        16.1.2  WWiinnddooww CCoonnffiigguurraattiioonn



             A window manager can assign any position and size to a
             window.  The user and application can supply preferred
             positions and sizes, but the window manager is free to
             use or ignore these as it wishes.

             The user generally specifies position and size via the
             --ggeeoommeettrryy option when invoking the command that starts
             the application.  In Motif, the value specified for
             --ggeeoommeettrryy becomes the value of the Shell XXmmNNggeeoommeettrryy
             resource.  An application should never set this
             resource itself; it should reserve it for the user.  An
             application specifies size and position by supplying
             values for the Core resources XXmmNNxx, XXmmNNyy, XXmmNNhheeiigghhtt,
             XXmmNNwwiiddtthh, and XXmmNNbboorrddeerrWWiiddtthh.  When an x, y, width, or
             height value is specified for both XXmmNNggeeoommeettrryy and one
             of the specific geometry resources, the value from
             XXmmNNggeeoommeettrryy takes precedence.

             The MWM ppoossiittiioonnIIssFFrraammee resource determines whether MWM
             interprets x and y values as referring to the upper
             left corner of the client window itself or the upper



        May 9, 1992                                             16-3








        OSF/Motif Programmer's Guide


             left corner of the frame that MWM puts around the
             client window.  By default x and y values refer to the
             frame.

             When a top-level window is mapped, MWM uses the
             following order of precedence in determining size and
             position:

                +o If the user specifies position and size via the
                  --ggeeoommeettrryy option, MWM uses those values.

                +o If the MWM iinntteerraaccttiivveePPllaacceemmeenntt resource is True,
                  MWM waits for the user to select a position using
                  a button press for the upper left corner of the
                  window.  If the user drags the pointer down and to
                  the right with the mouse button pressed, the user
                  can then determine the size of the window by
                  releasing the mouse button.  If the user does not
                  determine a size in this way, MWM uses the
                  window's XXmmNNwwiiddtthh and XXmmNNhheeiigghhtt.

                +o If the MWM uusseePPPPoossiittiioonn resource is True, or if
                  uusseePPPPoossiittiioonn is nnoonnzzeerroo and the window's XXmmNNxx or
                  XXmmNNyy is nonzero, MWM uses the window's XXmmNNxx and
                  XXmmNNyy to position the window.  MWM uses the
                  window's XXmmNNwwiiddtthh and XXmmNNhheeiigghhtt for the window's
                  size.  If the MWM ppoossiittiioonnOOnnSSccrreeeenn resource is
                  True and if the window would be completely off the
                  screen, MWM alters the window position so that at
                  least part of the window is on the screen.

                +o If the MWM cclliieennttAAuuttooPPllaaccee resource is True, MWM
                  positions the window with its top left corner
                  offset horizontally and vertically from the last
                  client mapped.  MWM uses the window's XXmmNNwwiiddtthh and
                  XXmmNNhheeiigghhtt for the window's size.

                +o MWM positions the window in the upper left corner
                  of the screen.  MWM uses the window's XXmmNNwwiiddtthh and
                  XXmmNNhheeiigghhtt for the window's size.

             Before a window is mapped, the application communicates
             additional position and size information to the window
             manager via the WM_NORMAL_HINTS property on the window.
             This property is of type WM_SIZE_HINTS and contains a
             number of fields derived from WMShell resources:

             XXmmNNmmiinnHHeeiigghhtt, XXmmNNmmiinnWWiiddtthh
                       Specifies the minimum height and width that
                       the application wishes the widget's window to
                       have.  If an initial value is supplied for



        16-4                                             May 9, 1992








                                           Interclient Communication


                       one of these resources but not for the other,
                       the value of the unspecified resource is set
                       to 1 when the widget is realized.  If no
                       value is specified for either resource, MWM
                       uses the values from XXmmNNbbaasseeHHeeiigghhtt and
                       XXmmNNbbaasseeWWiiddtthh if specified.  Otherwise, MWM
                       uses a minimum height and width of at least
                       1.

             XXmmNNmmaaxxHHeeiigghhtt, XXmmNNmmaaxxWWiiddtthh
                       Specifies the maximum height and width that
                       the application wishes the widget's window to
                       have.  If an initial value is supplied for
                       one of these resources but not for the other,
                       the value of the unspecified resource is set
                       to 32767 when the widget is realized.  If the
                       MWM resource mmaaxxiimmuummCClliieennttSSiizzee is specified,
                       MWM uses that value to determine the maximum
                       window size.  Otherwise, MWM uses the maximum
                       height and width from the WM_NORMAL_HINTS
                       property, except that the window size may not
                       exceed the height and width specified by the
                       MWM mmaaxxiimmuummMMaaxxiimmuummSSiizzee resource.

             XXmmNNbbaasseeHHeeiigghhtt, XXmmNNbbaasseeWWiiddtthh
                       Specifies the base for a progression of
                       preferred heights and widths for the window
                       manager to use in sizing the widget.  The
                       preferred heights are XXmmNNbbaasseeHHeeiigghhtt plus
                       integral multiples of XXmmNNhheeiigghhttIInncc, with a
                       minimum of XXmmNNmmiinnHHeeiigghhtt and a maximum of
                       XXmmNNmmaaxxHHeeiigghhtt.  The preferred widths are
                       XXmmNNbbaasseeWWiiddtthh plus integral multiples of
                       XXmmNNwwiiddtthhIInncc, with a minimum of XXmmNNmmiinnWWiiddtthh
                       and a maximum of XXmmNNmmaaxxWWiiddtthh.  If an initial
                       value is supplied for one of these resources
                       but not for the other, the value of the
                       unspecified resource is set to 0 when the
                       widget is realized.  If no value is specified
                       for either resource, MWM uses the values from
                       XXmmNNmmiinnHHeeiigghhtt and XXmmNNmmiinnWWiiddtthh if specified.
                       Otherwise, MWM uses a base height and width
                       of at least 1.

             XXmmNNhheeiigghhttIInncc, XXmmNNwwiiddtthhIInncc
                       Specifies the increment for a progression of
                       preferred heights and widths for the window
                       manager to use in sizing the widget.  The
                       preferred heights are XXmmNNbbaasseeHHeeiigghhtt plus
                       integral multiples of XXmmNNhheeiigghhttIInncc, with a
                       minimum of XXmmNNmmiinnHHeeiigghhtt and a maximum of



        May 9, 1992                                             16-5








        OSF/Motif Programmer's Guide


                       XXmmNNmmaaxxHHeeiigghhtt.  The preferred widths are
                       XXmmNNbbaasseeWWiiddtthh plus integral multiples of
                       XXmmNNwwiiddtthhIInncc, with a minimum of XXmmNNmmiinnWWiiddtthh
                       and a maximum of XXmmNNmmaaxxWWiiddtthh.  If an initial
                       value is supplied for one of these resources
                       but not for the other, the value of the
                       unspecified resource is set to 1 when the
                       widget is realized.  If no value is specified
                       for either resource, MWM uses an increment of
                       1.

             XXmmNNmmiinnAAssppeeccttXX, XXmmNNmmiinnAAssppeeccttYY
                       Specifies the numerator and denominator of
                       the minimum aspect ratio (X/Y) that the
                       application wishes the widget's window to
                       have.  If no value is specified for either
                       resource, MWM imposes no minimum aspect
                       ratio.

             XXmmNNmmaaxxAAssppeeccttXX, XXmmNNmmaaxxAAssppeeccttYY
                       Specifies the numerator and denominator of
                       the maximum aspect ratio (X/Y) that the
                       application wishes the widget's window to
                       have.  If no value is specified for either
                       resource, MWM imposes no maximum aspect
                       ratio.

             XXmmNNwwiinnGGrraavviittyy
                       Specifies the window gravity for use by the
                       window manager in positioning the widget.  If
                       no initial value is specified, the value is
                       set when the widget is realized.  If
                       XXmmNNggeeoommeettrryy is not NULL, XXmmNNwwiinnGGrraavviittyy is set
                       to the window gravity returned by
                       XXWWMMGGeeoommeettrryy.  Otherwise, XXmmNNwwiinnGGrraavviittyy is set
                       to NNoorrtthhWWeessttGGrraavviittyy.

             After a window is mapped, an application can request
             changes to window size or position by calling
             XXttSSeettVVaalluueess for one or more of the Core geometry
             resources.  A user can generally employ window manager
             facilities to move or resize a top-level window.

             Calling XXttSSeettVVaalluueess for a geometry resource generates a
             geometry request that may propagate up the widget
             hierarchy to the shell.  This may cause the shell to
             make its own geometry request, and this invokes the
             shell's rroooott__ggeeoommeettrryy__mmaannaaggeerr procedure.  This
             procedure uses XXCCoonnffiigguurreeWWiinnddooww to ask the window
             manager to change the window's size or position.




        16-6                                             May 9, 1992








                                           Interclient Communication


             If a window manager responds to a configuration request
             by denying it or by moving the window without resizing
             it, the window manager sends a synthetic
             CCoonnffiigguurreeNNoottiiffyy event.  If the window is resized, the
             window receives a real CCoonnffiigguurreeNNoottiiffyy event.

             These events may be handled by either the
             rroooott__ggeeoommeettrryy__mmaannaaggeerr procedure or a Shell event
             handler.  If the VendorShell resource
             XXmmNNuusseeAAssyynnccGGeeoommeettrryy is True, the rroooott__ggeeoommeettrryy__mmaannaaggeerr
             procedure does not wait for the window manager to
             respond to the configuration request, but instead
             returns XXttGGeeoommeettrryyYYeess.  If the WMShell resource
             XXmmNNwwaaiittFFoorrWWmm is True and if the window manager grants
             the configuration request within the XXmmNNwwmmTTiimmeeoouutt
             interval, the rroooott__ggeeoommeettrryy__mmaannaaggeerr procedure updates
             the widget's geometry resources and returns
             XXttGGeeoommeettrryyYYeess.  Otherwise, the rroooott__ggeeoommeettrryy__mmaannaaggeerr
             procedure returns XXttGGeeoommeettrryyNNoo and relies on the event
             handler to reconfigure the widget when it receives a
             subsequent CCoonnffiigguurreeNNoottiiffyy event.

             The shell's CCoonnffiigguurreeNNoottiiffyy event handler is invoked
             when the user reconfigures a top-level window or when
             the application reconfigures a window and this
             reconfiguration is not handled by the
             rroooott__ggeeoommeettrryy__mmaannaaggeerr procedure.  The event handler
             updates the shell's core geometry fields with the
             values allowed by the window manager.  If the size of
             the shell changes, the event handler calls the shell's
             rreessiizzee procedure.  This procedure calls XXttRReessiizzeeWWiiddggeett
             to change the height, width, and border width of the
             child to be the same as those of the shell.



        16.1.3  IIccoonnss



             An application uses several properties to communicate
             with the window manager about icons associated with
             top-level windows.  A Motif application can use
             resources of several Shell subclasses to specify values
             for these properties.

             When a window is first mapped, it can appear in either
             its normal state or iconic state.  An application uses
             a field in the WM_HINTS property to tell the window
             manager which initial state it prefers.  A Motif
             application specifies the initial state by setting the



        May 9, 1992                                             16-7








        OSF/Motif Programmer's Guide


             WMShell resource XXmmNNiinniittiiaallSSttaattee or the TopLevelShell
             resource XXmmNNiiccoonniicc.  XXmmNNiiccoonniicc takes precedence over
             XXmmNNiinniittiiaallSSttaattee.  After a window is realized, an
             application can use XXttSSeettVVaalluueess for XXmmNNiiccoonniicc to either
             iconify or deiconify the window.

             An application can supply a name, a bitmap, or a window
             for the window manager to use as an icon.  When a top-
             level window is in iconic state, the window manager
             usually displays the icon window if one is supplied, or
             else the icon pixmap if one is supplied, or else the
             icon name.  MWM uses the iiccoonnDDeeccoorraattiioonn resource in
             determining what aspects of an icon to display.

             The icon name comes from the WM_ICON_NAME property.
             Like WM_NAME, this property is a string whose encoding
             is identified by the type of the property.

             A Motif application specifies a icon name via the
             TopLevelShell resources XXmmNNiiccoonnNNaammee and
             XXmmNNiiccoonnNNaammeeEEnnccooddiinngg.  The default icon name is the name
             of the shell.  XXmmNNiiccoonnNNaammeeEEnnccooddiinngg is an atom
             representing the encoding of the name.  The default
             encoding depends on whether or not a language procedure
             has been set.  If no language procedure has been set,
             the default is STRING.  If a language procedure has
             been set, the icon name is assumed to be in the
             encoding of the locale and is passed to
             XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy with an encoding style of
             XXSSttddIICCCCTTeexxttSSttyyllee.  The returned property is used as the
             WM_ICON_NAME property.  If the icon name is fully
             convertible to type STRING, the encoding is STRING;
             otherwise, the encoding is COMPOUND_TEXT.

             An application uses fields in the WM_HINTS property to
             supply an icon bitmap and an optional mask for
             displaying the bitmap in a nonrectangular shape.  A
             Motif application specifies an icon bitmap as the value
             of the WMShell resource XXmmNNiiccoonnPPiixxmmaapp, and it specifies
             the mask as the value of the WMShell resource
             XXmmNNiiccoonnMMaasskk.

             An application uses a field in the WM_HINTS property to
             supply an icon window.  A Motif application specifies
             an icon window as the value of the WMShell resource
             XXmmNNiiccoonnWWiinnddooww.  The icon window must be an InputOutput
             child of the root window.  It must also use the root
             visual and the default colormap of the screen.  The
             application must not map, unmap, or configure this
             window.  It must, however, select for Expose events on
             the window and redisplay the contents when it receives



        16-8                                             May 9, 1992








                                           Interclient Communication


             these events.

             The window manager may specify preferred maximum and
             minimum sizes and size increments for icon bitmaps and
             windows.  To do this it puts a WM_ICON_SIZE property on
             the root window.  MWM uses the iiccoonnIImmaaggeeMMaaxxiimmuumm and
             iiccoonnIImmaaggeeMMiinniimmuumm resources, with increments of 1, in
             setting this property.  Before an application specifies
             an icon bitmap or window, it should use the Xlib
             routine XXGGeettIIccoonnSSiizzeess to check these constraints and
             then supply a bitmap or window that is of one of the
             preferred sizes.

             An application can use two fields of the WM_HINTS
             property to supply preferred x and y root coordinates
             for the icon location.  A Motif application specifies
             these coordinates as the values of the WMShell
             resources XXmmNNiiccoonnXX and XXmmNNiiccoonnYY.  The window manager
             may ignore these values.  MWM uses the uusseeIIccoonnBBooxx,
             iiccoonnPPllaacceemmeenntt, and iiccoonnPPllaacceemmeennttMMaarrggiinn resources in
             determining where to place icons.



        16.1.4  WWiinnddooww GGrroouuppss



             An application can use a field of the WM_HINTS property
             to supply the window ID of a window to serve as the
             "leader" for a group of windows.  The window manager
             may treat all windows in this group as a whole for
             certain purposes, such as showing a single icon when
             the entire group is iconified.

             A Motif application specifies a window group leader as
             the value of the WMShell resource XXmmNNwwiinnddoowwGGrroouupp.  For
             VendorShell and its subclasses, if the shell has a
             parent, Motif sets the XXmmNNwwiinnddoowwGGrroouupp to the parent's
             window at the time that the shell and its parent are
             both realized.  Otherwise, the default value is
             XXttUUnnssppeecciiffiieeddWWiinnddoowwGGrroouupp, which means that no window
             group is set.











        May 9, 1992                                             16-9








        OSF/Motif Programmer's Guide


        16.1.5  MMeennuuss aanndd DDiiaallooggss



             A window manager may treat dialogs differently from
             other top-level windows, and it must not interfere with
             menus at all.

             An application tells a window manager not to decorate
             or otherwise interfere with a window by setting the
             oovveerrrriiddee__rreeddiirreecctt attribute of the window to True.  A
             Motif application does this by setting the SShheellll
             resource XXmmNNoovveerrrriiddeeRReeddiirreecctt resource to True, or by
             using an OOvveerrrriiddeeSShheellll, which has a default value of
             True for this resource.  XXmmMMeennuuSShheellll is a subclass of
             OOvveerrrriiddeeSShheellll, and MenuShells are the only widgets that
             should have a value of True for XXmmNNoovveerrrriiddeeRReeddiirreecctt.
             An application normally does not supply a value other
             than the default for this resource.

             An application tells a window manager to treat a window
             as transient or secondary by setting the window's
             WM_TRANSIENT_FOR property.  This property contains the
             window ID of another top-level window, usually the
             window from which the transient window was popped up.
             A Motif application generally specifies this property
             by creating a DialogShell, a subclass of
             TransientShell, which has an XXmmNNttrraannssiieennttFFoorr resource.
             The value is a widget, and the default is set to the
             shell's parent at the time that both the shell and its
             parent are realized.  The window of the XXmmNNttrraannssiieennttFFoorr
             widget is used for the WM_TRANSIENT_FOR property.  For
             a shell that is not a subclass of TransientShell, an
             application can set the WMShell XXmmNNttrraannssiieenntt resource
             to True.  The XXmmNNwwiinnddoowwGGrroouupp is then used for the
             WM_TRANSIENT_FOR property.  An application normally
             does not supply a value other than the default for
             XXmmNNttrraannssiieenntt or XXmmNNttrraannssiieennttFFoorr.

             MWM treats transient windows differently from other
             top-level windows.  By default it keeps transient
             windows stacked on top of their primary windows and
             does not allow transient windows to be iconified
             separately from their primary windows.  The MWM
             ttrraannssiieennttDDeeccoorraattiioonn and ttrraannssiieennttFFuunnccttiioonnss resources
             determine which decorations and functions apply to
             transient windows.  An application can further specify
             these decorations and functions by using the
             VendorShell XXmmNNmmwwmmDDeeccoorraattiioonnss and XXmmNNmmwwmmFFuunnccttiioonnss
             resources, explained in a later section.




        16-10                                            May 9, 1992








                                           Interclient Communication


        16.1.6  IInnppuutt FFooccuuss



             ICCCM recognizes four models for the relationship
             between clients and window managers in setting input
             focus:

             No input
                       The client does not expect keyboard input and
                       does not want the window manager to set focus
                       to any of its windows.

             Passive input
                       The client expects keyboard input and wants
                       the window manager to set focus to its top-
                       level window.  It does not set focus itself.

             Locally active input
                       The client expects keyboard input and wants
                       the window manager to set focus to its top-
                       level window.  It may also set focus to one
                       of its subwindows when one of its windows
                       already has the focus.  It does not set focus
                       itself when the current focus is in a window
                       that the client does not own.

             Globally active input
                       The client expects keyboard input but does
                       not want the window manager to set focus to
                       any of its windows.  Instead, it sets focus
                       itself, even when the current focus is in a
                       window that the client does not own.

             An application tells the window which model it prefers
             by using two properties:

                +o If the iinnppuutt field of the WM_HINTS property is
                  True, the application wants the window manager to
                  set focus to its top-level window.  If this field
                  is False, the application does not want the window
                  manager to set focus.

                +o If the WM_PROTOCOLS property contains a
                  WM_TAKE_FOCUS atom, the application sometimes sets
                  focus itself.  If the WM_PROTOCOLS property does
                  not contain a WM_TAKE_FOCUS atom, the application
                  does not set focus itself.

             These combinations are summarized in the following
             table:



        May 9, 1992                                            16-11








        OSF/Motif Programmer's Guide


                  IInnppuutt MMooddeell       IInnppuutt ffiieelldd   WWMM__TTAAKKEE__FFOOCCUUSS
                  _____________________________________________
                  No input          False         Absent
                  Passive           True          Absent
                  Locally active    True          Present
                  Globally active   False         Present

             A window manager generally does not set input focus to
             a window when the WM_HINTS iinnppuutt field is False.  A
             window with a WM_TAKE_FOCUS protocol may receive a
             ClientMessage when the window manager wants the window
             to accept keyboard focus.  The window may respond by
             setting the input focus or by ignoring the message.

             A Motif application can set the iinnppuutt field of the
             WM_HINTS property by specifying a value for the WMShell
             resource XXmmNNiinnppuutt.  The application can install the
             WM_TAKE_FOCUS atom on the WM_PROTOCOLS property by
             calling XXmmAAddddWWMMPPrroottooccoollss or XXmmAAddddWWMMPPrroottooccoollCCaallllbbaacckk,
             explained in a later section.

             A Motif application normally should avoid setting input
             focus itself.  The application can control the location
             of focus within its subwindows by using the VendorShell
             resource XXmmNNkkeeyybbooaarrddFFooccuussPPoolliiccyy, the Gadget, Primitive,
             and Manager resource XXmmNNttrraavveerrssaallOOnn, and the
             XXmmPPrroocceessssTTrraavveerrssaall routine.  If the application wants a
             widget to receive no input at all it can use
             XXttSSeettSSeennssiittiivvee to make the widget insensitive.  If the
             application needs to set focus directly, it should
             usually use XXttSSeettKKeeyybbooaarrddFFooccuuss and avoid using
             XXSSeettIInnppuuttFFooccuuss.  For more information see chapter 13.

             A number of MWM resources influence keyboard focus.
             When kkeeyybbooaarrddFFooccuussPPoolliiccyy is "explicit" (the default),
             the user must press BBSSeelleecctt on a window or its
             decoration to give it focus.  When kkeeyybbooaarrddFFooccuussPPoolliiccyy
             is "pointer", the window that contains the pointer has
             the focus.  With an explicit policy, other resources
             determine whether a window has focus when it is first
             mapped (ssttaarrttuuppKKeeyyFFooccuuss), deiconified
             (ddeeiiccoonniiffyyKKeeyyFFooccuuss), or raised (rraaiisseeKKeeyyFFooccuuss).  When
             aauuttooKKeeyyFFooccuuss is True and the window with focus is
             iconified or withdrawn, focus passes to the window that
             last had focus.  When eennffoorrcceeKKeeyyFFooccuuss is True, MWM sets
             focus to globally active windows.








        16-12                                            May 9, 1992








                                           Interclient Communication


        16.1.7  CCoolloorrmmaappss



             An application can create and set colormaps for its
             windows, but only the window manager should install
             colormaps.  Each window manager has a colormap focus
             policy that determines which top-level window has the
             colormap focus at a given time.  When a window has
             colormap focus, the window manager installs one or more
             colormaps associated with that window.

             If all windows in an application use the same colormap,
             the application need take no special action to tell the
             window manager to use that colormap.  The window
             manager keeps track of the colormap attribute for each
             top-level window and installs that colormap when the
             window has colormap focus.

             If an application uses different colormaps for some
             windows in its hierarchy, it must tell the window
             manager about those colormaps by setting a
             WM_COLORMAP_WINDOWS property on the top-level window.
             This property is a list of windows whose colormaps the
             window manager should install when the top-level window
             has colormap focus.  The list should be in order of
             priority, with the windows whose colormaps the
             application would most like to have installed listed
             first.  The application can use XXSSeettWWMMCCoolloorrmmaappWWiinnddoowwss
             to set this property.

             On many servers only one hardware colormap can be
             installed at a time.  This may cause colors in windows
             that use different colormaps to be displayed
             incorrectly when their own colormaps are not installed.
             To reduce contention for colormaps, applications should
             use the facilities for standard colormaps described in
             _X_l_i_b-_C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e.

             The MWM ccoolloorrmmaappFFooccuussPPoolliiccyy resource determines the
             colormap focus policy.  When the value is "keyboard",
             the window with keyboard focus has the colormap focus.
             When the value if "pointer", the window under the
             pointer has the colormap focus, regardless of whether
             that window also has keyboard focus.  When the value is
             "explicit", the colormap focus changes only when the
             user invokes the ff..ffooccuuss__ccoolloorr function.

             When a window with colormap focus has a
             WM_COLORMAP_WINDOWS property, the user can install the
             next and previous colormaps on the list by invoking the



        May 9, 1992                                            16-13








        OSF/Motif Programmer's Guide


             ff..nneexxtt__ccmmaapp and ff..pprreevv__ccmmaapp functions.



        16.1.8  AApppplliiccaattiioonn SShhuuttddoowwnn aanndd RReessttaarrtt



             An application may run under a session manager with
             facilities for saving and restoring the state of the
             application.  An application communicates with a
             session manager by placing WM_COMMAND and
             WM_CLIENT_MACHINE properties on its top-level windows.
             WM_COMMAND contain a string that would restart the
             client in its current state.

             A Motif application should have only one non-NULL
             WM_COMMAND property for each logical application (i.e.,
             for each ApplicationShell hierarchy).  Xt sets the
             WM_COMMAND property for an ApplicationShell when the
             shell is realized, using the command that started the
             application.  Note that if an application is using an
             unrealized ApplicationShell with multiple TopLevelShell
             popup children, Xt will not place a WM_COMMAND property
             on any window, and the application must put this
             property on some (possibly unmapped) window in the
             application.

             WM_CLIENT_MACHINE contains a string that represents the
             name of the host on which the application is running.
             Xt sets the WM_CLIENT_MACHINE for a WMShell or subclass
             when the shell is realized.

             A session manager can inform an application when a
             top-level window is about to be deleted or when the
             application should try to save its state.  An
             application expresses interest in these notifications
             by adding a WM_DELETE_WINDOW atom or a WM_SAVE_YOURSELF
             atom to the WM_PROTOCOLS property.

             If a WM_DELETE_WINDOW protocol exists, the session
             manager sends a ClientMessage when it wants to delete a
             top-level window.  The application may ask for user
             confirmation and may decide to comply or not comply
             with the request.  If it decides to comply, the
             application can either unmap or destroy the window.

             If a WM_SAVE_YOURSELF protocol exists, the session
             manager sends a ClientMessage when it wants the
             application to save its current state in such a way
             that it could be restored.  The application should do



        16-14                                            May 9, 1992








                                           Interclient Communication


             whatever is necessary to save its internal state and
             then update the non-NULL WM_COMMAND property with a
             command that will restart the application in its
             current state.  Finally, the application updates the
             WM_COMMAND property on the window that has the
             WM_SAVE_YOURSELF protocol if it has not already done
             so.  This informs the session manager that the
             application has finished saving its state.

             Motif installs a WM_DELETE_WINDOW protocol for
             VendorShell and its subclasses.  It also installs a
             procedure to be called after any application-supplied
             WM_DELETE_WINDOW handlers are invoked.  This procedure
             destroys the widget, unmaps the window, or does
             nothing, depending on the value of the VendorShell
             resource XXmmNNddeelleetteeRReessppoonnssee.  If the procedure destroys
             an ApplicationShell, it then exits the application.

             An application can add its own WM_DELETE_WINDOW and
             WM_SAVE_YOURSELF protocols by using XXmmAAddddWWMMPPrroottooccoollss or
             XXmmAAddddWWMMPPrroottooccoollCCaallllbbaacckk, explained in a later section.

             When the user invokes the ff..kkiillll command, MWM sends a
             ClientMessage if an application has a WM_DELETE_WINDOW
             protocol and a separate ClientMessage if an application
             has a WM_SAVE_YOURSELF protocol.  If the application
             has no WM_DELETE_WINDOW protocol, the ff..kkiillll command
             kills the client.  In this case, if a WM_SAVE_YOURSELF
             protocol exists, MWM sends the ClientMessage and then
             waits for the time specified by the qquuiittTTiimmeeoouutt
             resource before killing the client.



        16.2  MMWWMM PPrrooppeerrttiieess aanndd RReessoouurrcceess



             In addition to the properties and protocols described
             in ICCCM, Motif uses properties and protocols of its
             own.  A Motif application usually specifies these
             properties via VendorShell and BulletinBoard resources.












        May 9, 1992                                            16-15








        OSF/Motif Programmer's Guide


        16.2.1  DDeeccoorraattiioonnss



             An application expresses preferences for MWM window
             decorations by supplying a value for the ddeeccoorraattiioonnss
             field of the _MOTIF_WM_HINTS property on the window.  A
             Motif application does this by supplying a value for
             the VendorShell resource XXmmNNmmwwmmDDeeccoorraattiioonnss.  The value
             is the bitwise inclusive OR of one or more flag bit
             constants, each of which indicates a preference for or
             against a particular decoration.  If a value has been
             supplied for this resource, MWM displays only those
             decorations specified by both XXmmNNmmwwmmDDeeccoorraattiioonnss and the
             MWM cclliieennttDDeeccoorraattiioonn resource (for primary windows) or
             specified by both XXmmNNmmwwmmDDeeccoorraattiioonnss and the MWM
             ttrraannssiieennttDDeeccoorraattiioonn resource (for transient windows).
             If no value has been supplied for XXmmNNmmwwmmDDeeccoorraattiioonnss,
             MWM displays the decorations specified by the
             cclliieennttDDeeccoorraattiioonn or ttrraannssiieennttDDeeccoorraattiioonn resource.



        16.2.2  FFuunnccttiioonnss



             An application expresses preferences for MWM window
             functions by supplying a value for the ffuunnccttiioonnss field
             of the _MOTIF_WM_HINTS property on the window.  A Motif
             application does this by supplying a value for the
             VendorShell resource XXmmNNmmwwmmFFuunnccttiioonnss.  The value is the
             bitwise inclusive OR of one or more flag bit constants,
             each of which indicates a preference for or against a
             particular function.  If a value has been supplied for
             this resource, MWM displays only those functions
             specified by both XXmmNNmmwwmmFFuunnccttiioonnss and the MWM
             cclliieennttFFuunnccttiioonnss resource (for primary windows) or
             specified by both XXmmNNmmwwmmFFuunnccttiioonnss and the MWM
             ttrraannssiieennttFFuunnccttiioonnss resource (for transient windows).
             If no value has been supplied for XXmmNNmmwwmmFFuunnccttiioonnss, MWM
             displays the functions specified by the cclliieennttFFuunnccttiioonnss
             or ttrraannssiieennttFFuunnccttiioonnss resource.

             BulletinBoard may change the initial value of
             XXmmNNmmwwmmFFuunnccttiioonnss if its parent is a subclass of
             VendorShell.  The BulletinBoard resource XXmmNNnnooRReessiizzee
             determines whether the decorations of the VendorShell
             parent include resize controls.





        16-16                                            May 9, 1992








                                           Interclient Communication


        16.2.3  IInnppuutt MMooddee



             An application can inform MWM that it should impose
             constraints on which windows can obtain input.  It does
             so by setting the iinnppuutt__mmooddee field of the
             _MOTIF_WM_HINTS property on a window.  A Motif
             application does this by supplying a value for the
             VendorShell resource XXmmNNmmwwmmIInnppuuttMMooddee.  For a
             BulletinBoard whose parent is a DialogShell, the
             application can set XXmmNNmmwwmmIInnppuuttMMooddee indirectly by
             specifying a value for the BulletinBoard resource
             XXmmNNddiiaallooggSSttyyllee.

             The possible modes are as follows:

                +o Modeless-Input goes to any window.

                +o Primary application modal-Input does not go to
                  ancestors of this window or their descendants.

                +o Full application modal-Input goes to this window
                  or its descendants and to other applications but
                  not to other windows in this application.

                +o System modal-Input goes only to this window or its
                  descendants.



        16.2.4  WWiinnddooww MMeennuu



             An application can supply items for MWM to add to the
             end of the window menu for a window by specifying a
             value for the _MOTIF_WM_MENU property.  A Motif
             application does this by supplying a value for the
             VendorShell resource XXmmNNmmwwmmMMeennuu.  The window menu
             itself is the value of the MWM wwiinnddoowwMMeennuu resource.



        16.2.5  MMWWMM MMeessssaaggeess



             An application can specify a message for MWM to send
             the application when the user invokes the ff..sseenndd__mmssgg
             function.  The application places a _MOTIF_WM_MESSAGES



        May 9, 1992                                            16-17








        OSF/Motif Programmer's Guide


             atom on the WM_PROTOCOLS property for the window.  The
             application also places an atom on the
             _MOTIF_WM_MESSAGES property.  When the ff..sseenndd__mmssgg
             function is invoked with this atom as the argument, MWM
             sends the application a ClientMessage.  The application
             can use XXmmAAddddWWMMPPrroottooccoollss to place a _MOTIF_WM_MESSAGES
             atom on the WM_PROTOCOLS property, and it can use
             XXmmAAddddPPrroottooccoollCCaallllbbaacckk to place an atom on the
             _MOTIF_WM_MESSAGES property and associate it with a
             routine to be called when MWM sends the ClientMessage.



        16.2.6  MMWWMM IInnffoorrmmaattiioonn



             MWM maintains a _MOTIF_WM_INFO property on the root
             window of each screen it manages.  This property is
             available for applications to inspect but not to
             change.  The XXmmIIssMMoottiiffWWMMIInnffoo routine examines this
             property when determining whether or not MWM is
             running.



        16.3  AAttoomm aanndd PPrroottooccooll MMaannaaggeemmeenntt



             Motif has two routines that can reduce overhead for
             applications that use atoms.  XXmmIInntteerrnnAAttoomm returns an
             existing atom or (if the third argument is False)
             creates and returns an atom that matches the given
             string.  XXmmGGeettAAttoommNNaammee returns the string that matches
             the given atom.  These functions parallel XXIInntteerrnnAAttoomm
             and XXGGeettAAttoommNNaammee, but they cache the atoms and names on
             the client side and avoid unnecessary trips to the
             server.

             Motif has a number of routines to help an application
             install protocol atoms and handle ClientMessages sent
             when the protocols are invoked.  These routines
             maintain an internal registry of properties, protocol
             atoms associated with the properties, and callback
             routines associated with the protocol atoms.  The
             application can use these routines with shells that are
             subclasses of VendorShell.

             XXmmAAddddPPrroottooccoollss associates one or more protocol atoms
             with a property for a given shell.  If the shell is



        16-18                                            May 9, 1992








                                           Interclient Communication


             realized, it adds those protocols to the property for
             the shell's window.  If the shell is not realized, it
             arranges for the protocols to be added to the property
             and for a ClientMessage event handler to be added at
             the time the shell is realized.  XXmmAAddddWWMMPPrroottooccoollss is a
             specialized version that adds protocols for the
             WM_PROTOCOLS property.

             XXmmAAddddPPrroottooccoollCCaallllbbaacckk adds a callback routine to a
             callback list associated with a protocol.  It calls
             XXmmAAddddPPrroottooccoollss if the protocol has not yet been
             registered.  When the protocol manager's ClientMessage
             event handler receives a ClientMessage for the
             protocol, it invokes the procedures on the associated
             callback list.  The first argument to each callback
             procedure is the shell associated with the protocol.
             The second argument is the client data, if any,
             specified in the call to XXmmAAddddPPrroottooccoollCCaallllbbaacckk.  The
             third argument is a pointer to an XXmmAAnnyyCCaallllbbaacckkSSttrruucctt
             structure whose rreeaassoonn member is XXmmCCRR__PPRROOTTOOCCOOLLSS and
             whose eevveenntt member is a pointer to the ClientMessage
             event.  In the ClientMessage event, the mmeessssaaggee__ttyyppee
             member is the property that contains the protocol, the
             ffoorrmmaatt member is 32, and the ddaattaa..ll[[00]] member is the
             protocol atom.  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
             specialized version of XXmmAAddddPPrroottooccoollCCaallllbbaacckk that adds
             a callback for a protocol on the WM_PROTOCOLS property.

             An application can also use XXmmSSeettPPrroottooccoollHHooookkss to
             specify a routine to be called before or after a
             callback list is invoked for a protocol.
             XXmmSSeettWWMMPPrroottooccoollHHooookkss is a specialized version that adds
             pre- and posthooks for a protocol on the WM_PROTOCOLS
             property.

             Once an application has registered a protocol and
             optional callback routines, it can make the protocol
             active or inactive.  A protocol is active if it has
             been added to the associated property for the window.
             A protocol is inactive if it has been removed from the
             associated property.  XXmmAAccttiivvaatteePPrroottooccooll makes a
             registered protocol active, and XXmmDDeeaaccttiivvaatteePPrroottooccooll
             makes a protocol inactive.  XXmmAAccttiivvaatteeWWMMPPrroottooccooll and
             XXmmDDeeaaccttiivvaatteeWWMMPPrroottooccooll are specialized versions that
             activate or inactivate a protocol on the WM_PROTOCOLS
             property.

             XXmmRReemmoovveePPrroottooccoollCCaallllbbaacckk removes a callback routine
             from the callback list associated with the protocol.
             XXmmRReemmoovveePPrroottooccoollss removes one or more protocols and all
             callbacks associated with those protocols from the



        May 9, 1992                                            16-19








        OSF/Motif Programmer's Guide


             internal registry.  If the shell is realized, it
             removes those protocols from the associated property.
             XXmmRReemmoovveeWWMMPPrroottooccoollCCaallllbbaacckk and XXmmRReemmoovveeWWMMPPrroottooccoollss are
             specialized versions that remove callbacks or protocols
             for the WM_PROTOCOLS property.



        16.4  SSeelleeccttiioonnss



             Selections are the standard ICCCM mechanism for
             transferring data from one application to another on
             the same display.  Each selection is represented by an
             atom.  The display contains only one selection of each
             type.  It is owned by a client or by no one and, if
             owned, is attached to a window of the owning client.
             Any client may assert or remove ownership of a
             selection.

             The data represented by the selection is internal to
             the client that owns the selection.  If another client
             wants to obtain the data in the selection, it asks the
             owner to convert the selection to some target type.
             Each target type is represented by an atom.  The owner
             may or may not be able to convert the selection to the
             requested type or to some other type.  If it can
             convert the selection, the owner places the converted
             data into a property on the requesting client's window,
             using the actual target as the type of the property.
             The owner sends the requestor a SelectionNotify event
             when the conversion (whether successful or not) is
             complete.  For a successful transfer, this event
             includes the property on the requestor's window that
             contains the converted selection.  When the requestor
             receives a SelectionNotify event for a successful
             conversion, it retrieves the contents of the specified
             property from its window and then deletes the property.



        16.4.1  SSeelleeccttiioonn TTyyppeess



             ICCCM defines three selections that all clients should
             support, although clients may support other selections
             as well:





        16-20                                            May 9, 1992








                                           Interclient Communication


             PRIMARY   The principal selection.

             SECONDARY A means of exchanging data without disturbing
                       the primary selection.

             CLIPBOARD The selection often used to "cut" or "copy"
                       data from one client and "paste" it into
                       another.  A client transfers data to the
                       clipboard by asserting ownership of this
                       selection.  A client transfers data from the
                       clipboard by requesting conversion of the
                       selection.

                       A separate client may also represent the
                       clipboard.  This client can notice when it
                       loses the selection (because another client
                       wants to transfer data to the clipboard),
                       then request a conversion of the selection
                       and finally reassert ownership.

             The Motif Text and TextField widgets support all three
             of these selections.  The List widget supports only
             copying of selected items to the clipboard.  Motif also
             makes use of other selections, notably for the
             destination widget and for drag and drop.  For more
             information on drag and drop selections, see chapter
             15.



        16.4.2  TTaarrggeettss



             ICCCM lists a number of suggested target atoms that
             clients may support.  Clients are free to request and
             perform conversion to these and to other targets as
             well.  Clients that follow ICCCM must support only
             three targets:

             TARGETS   When a selection owner is asked to convert
                       the selection to this type, it returns a list
                       of the target types to which it can convert
                       the selection.  By first requesting a
                       conversion to TARGETS, a client can determine
                       whether a conversion request of a particular
                       type is likely to succeed or fail.

             MULTIPLE  This target signifies a request for a series
                       of conversions.  The requestor places in its
                       specified window property a list of pairs of



        May 9, 1992                                            16-21








        OSF/Motif Programmer's Guide


                       atoms.  Each pair names a target and a
                       property.  The selection owner processes each
                       pair in order, converting the selection to
                       the specified target and placing the results
                       in the specified property.  It sends the
                       requestor a SelectionNotify event when all
                       conversions are complete.

             TIMESTAMP The owner returns the timestamp it used to
                       obtain ownership of the selection.

             Some targets have side-effects for the owner.  Among
             these targets are the following:

             DELETE    The owner deletes the selection and, if
                       successful, returns a zero-length property of
                       type NULL.

             INSERT_SELECTION
                       The requestor places in its specified window
                       property a pair of atoms that names a
                       selection and a target.  The owner requests
                       conversion of the specified selection to the
                       specified target and places the result at the
                       location of the selection named in the
                       INSERT_SELECTION request.  The owner then
                       returns a zero-length property of type NULL.
                       The Motif Text widget uses this target with
                       the destination selection when it asks the
                       owner of the destination selection to insert
                       the secondary selection at the destination.

             INSERT_PROPERTY
                       The requestor places in its specified window
                       property some data to be inserted at the
                       location of the selection named in the
                       request.  The owner then returns a zero-
                       length property of type NULL.



        16.4.3  TTeexxtt CCoonnvveerrssiioonn



             Conversion of textual selections raises problems
             because the requesting client and the selection owner
             may be in different locales.  A requestor may specify a
             target type of TEXT, but the owner may then convert the
             selection into any encoding that is convenient.  The
             type of the returned property indicates what this



        16-22                                            May 9, 1992








                                           Interclient Communication


             encoding is; the type will never be TEXT.  The
             requestor may or may not be able to convert the value
             into a useful form.

             Converted text is generally of one of three types:

             STRING    The text includes only characters in
                       ISO8859-1 plus TAB and NEWLINE.

             COMPOUND_TEXT
                       The text is in compound text format as
                       specified by the X Consortium Standard
                       _C_o_m_p_o_u_n_d _T_e_x_t _E_n_c_o_d_i_n_g.

             _l_o_c_a_l_e _e_n_c_o_d_i_n_g
                       The text is in the encoding of the selection
                       owner's locale.  The encoding is represented
                       by the atom used as the type of the returned
                       property.

             A selection owner can use XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy or
             XXwwccTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy to convert text in its own
             locale to a text property.  The type of the property is
             determined by the composition of the text and by the
             encoding style passed to XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy.
             Encoding styles exist for converting text to STRING,
             COMPOUND_TEXT, and the encoding of the locale.  Another
             encoding style specifies conversion to STRING if all
             the characters in the text can be so converted, or
             otherwise to COMPOUND_TEXT.

             A Motif application that has text in compound strings
             can use XXmmCCvvttXXmmSSttrriinnggTTooCCTT to convert a compound string
             to compound text.  The application can then place the
             compound text in the requestor's property using type
             COMPOUND_TEXT.

             STRING, COMPOUND_TEXT, and the locale encoding can also
             be selection targets.  To obtain a text selection in
             its own locale, an application can request conversion
             to one of these targets and can then call
             XXmmbbTTeexxttPPrrooppeerrttyyTTooTTeexxttLLiisstt or XXwwccTTeexxttPPrrooppeerrttyyTTooTTeexxttLLiisstt
             to convert the returned property to text in the current
             locale.  An application can also request conversion to
             TEXT, but there is no guarantee that it can convert the
             returned property to text in the current locale.

             One possible strategy is first to request conversion to
             TARGETS.  If one of the returned targets is the
             encoding of the current locale (as determined by a call
             to XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy with an encoding style of



        May 9, 1992                                            16-23








        OSF/Motif Programmer's Guide


             XXTTeexxttSSttyyllee), the application can request conversion to
             that target.  Otherwise, if one of the returned targets
             is COMPOUND_TEXT, the application can request
             conversion to that target.  If neither the locale
             encoding nor COMPOUND_TEXT is one of the returned
             targets, the application can request conversion to
             STRING or TEXT if the selection owner supports one of
             those targets.

             A Motif application that has text in compound strings
             can request conversion of a selection to COMPOUND_TEXT
             and can then use XXmmCCvvttCCTTTTooXXmmSSttrriinngg to convert the
             returned property to a compound string.



        16.4.4  IInnccrreemmeennttaall TTrraannssffeerrss



             When a selection contains a large quantity of data, the
             selection owner may place converted data into the
             returned property incrementally.  It signals the
             requestor that it intends to do this by setting the
             type of the returned property to INCR and placing into
             the property an integer that represents the minimum
             number of bytes of data to be transferred.  The owner
             and requestor must then cooperate in transferring the
             data.

             The requestor starts the interaction by deleting the
             returned property.  The owner then appends the first
             chunk of data to the same property, giving the property
             the type of the converted data.  The requestor receives
             a PropertyNotify event for the new value of the
             property, retrieves the data in the property, and
             deletes the property.  The owner receives a
             PropertyNotify event for the deletion of the property
             and then appends the next chunk of data to the
             property.  This interaction continues until all that
             data has been transferred.  The owner then writes
             zero-length data to the property, and the requestor
             deletes the property to terminate the interaction.











        16-24                                            May 9, 1992








                                           Interclient Communication


        16.4.5  TThhee XXtt SSeelleeccttiioonn IInntteerrffaaccee



             Xlib provides routines to set the owner of a selection
             (XXSSeettSSeelleeccttiioonnOOwwnneerr, get the owner of a selection
             (XXGGeettSSeelleeccttiioonnOOwwnneerr), and convert a selection
             (XXCCoonnvveerrttSSeelleeccttiioonn).  Applications that use only the
             Xlib interface must do additional work to support
             selections, such as providing a handler for
             SelectionRequest events to convert selections that the
             application owns.

             Xt provides a richer interface for handling selections.
             This interface consists of two parallel sets of
             routines, one for transferring data atomically and the
             other for transferring data incrementally.  In an
             atomic data transfer, the owner converts all data for
             one selection request before responding to another
             request to convert the same selection.  In an
             incremental data transfer, the owner may need to start
             a second conversion before finishing the first
             conversion for a given selection.  The selection owner
             and the requestor need not use the same (atomic or
             incremental) interface.  This distinction is
             independent of whether the actual transfer uses the
             ICCCM incremental (INCR) protocol.  For an atomic
             transfer of a large amount of data, Xt automatically
             uses the ICCCM incremental protocol when necessary.

             An application asserts ownership of a selection by
             calling XXttOOwwnnSSeelleeccttiioonn for atomic transfers or
             XXttOOwwnnSSeelleeccttiioonnIInnccrreemmeennttaall for incremental transfers.
             In this call the application can supply a procedure to
             convert the selection and procedures to be called when
             the requestor has retrieved the data and when the
             application loses ownership of the selection.  For an
             incremental transfer, the conversion routine can be
             called multiple times for the same request and can be
             called to begin a new conversion before it has
             transferred all data for the first request.  The
             conversion routine can obtain the SelectionRequest
             event by calling XXttGGeettSSeelleeccttiioonnRReeqquueesstt.  When calling
             XXttOOwwnnSSeelleeccttiioonnIInnccrreemmeennttaall the application can also
             provide a routine to be called to cancel a conversion
             in progress.  With either atomic or incremental
             transfer, an application relinquishes ownership of the
             selection by calling XXttDDiissoowwnnSSeelleeccttiioonn.

             An application requests conversion of a selection by
             calling XXttGGeettSSeelleeccttiioonnVVaalluuee or XXttGGeettSSeelleeccttiioonnVVaalluueess for



        May 9, 1992                                            16-25








        OSF/Motif Programmer's Guide


             atomic transfers or XXttGGeettSSeelleeccttiioonnVVaalluueeIInnccrreemmeennttaall or
             XXttGGeettSSeelleeccttiioonnVVaalluueessIInnccrreemmeennttaall for incremental
             transfers.  The difference between the "Value" and
             "Values" form of each routine is that the "Values" form
             allows multiple conversions while guaranteeing that the
             selection owner does not change during the call.  When
             invoking one of these routines, the requestor supplies
             a routine to be called to deliver the data from the
             returned property.

             Xt provides a timeout for the period in which a
             requestor and a selection owner must respond to each
             other.  The initial value comes from the
             sseelleeccttiioonnTTiimmeeoouutt application resource.  An application
             can use XXttAAppppSSeettSSeelleeccttiioonnTTiimmeeoouutt to set a new value,
             and it can use XXttAAppppGGeettSSeelleeccttiioonnTTiimmeeoouutt to retrieve the
             value.

             The Motif drag and drop interface uses the Xt selection
             mechanism.  A drag source supplies a single procedure
             to convert the selection, and a drop site supplies a
             procedure to receive the transferred data.  The drag
             source and the receiver can determine independently
             whether or not to use atomic or incremental transfer.
             The drag source does this by specifying a value for the
             DragContext resource XXmmNNiinnccrreemmeennttaall, and the receiver
             does this by specifying a value for the DropTransfer
             resource XXmmNNiinnccrreemmeennttaall.  When the drag source uses
             atomic transfer, it ignores the arguments to the
             conversion routine that pertain to incremental
             transfers.



        16.5  TThhee MMoottiiff CClliippbbooaarrdd



             Motif provides a set of routines for dealing with the
             CLIPBOARD selection.  The Motif clipboard interface
             allows an application to assert ownership of the
             selection and request conversion of the selection.  The
             interface stores the data in the selection and other
             information about the selection on the server.  The
             owner can place the selection value in these server
             data structures either at the time it asserts ownership
             or at the time a client requests conversion.

             By copying the selection value at the time it asserts
             ownership, an application can simplify conversion and
             make the data available for retrieval even if the owner



        16-26                                            May 9, 1992








                                           Interclient Communication


             is killed.  By copying the selection value when a
             client requests it, an application can avoid converting
             data that no client may request.  However, in this case
             the application may need to make a copy of the data to
             be transferred.  With either copying mechanism, the
             data is stored in the Motif clipboard's server data
             structures the first time a client requests the data.



        16.5.1  CCooppyyiinngg DDaattaa ttoo tthhee CClliippbbooaarrdd



             To assert ownership and copy data to the clipboard, an
             application takes these steps:

                +o It calls XXmmCClliippbbooaarrddSSttaarrttCCooppyy to begin the
                  interaction

                +o It makes one or more calls to XXmmCClliippbbooaarrddCCooppyy to
                  place data on the clipboard

                +o It terminates the interaction by calling
                  XXmmCClliippbbooaarrddEEnnddCCooppyy or XXmmCClliippbbooaarrddCCaanncceellCCooppyy

             An application begins an interaction to copy data to
             the clipboard by calling XXmmCClliippbbooaarrddSSttaarrttCCooppyy.  The
             application passes a display pointer and timestamp; the
             ID of a window in the application; a compound string
             that could be used to label the data; and, if the
             application intends to delay copying the data until it
             is requested, a widget ID and a function to be called
             to convert the data.  XXmmCClliippbbooaarrddSSttaarrttCCooppyy returns in
             one of the arguments a data ID that the application
             must later pass to XXmmCClliippbbooaarrddEEnnddCCooppyy or
             XXmmCClliippbbooaarrddCCaanncceellCCooppyy.  The application must also pass
             the same window ID to subsequent clipboard calls in
             this sequence that it uses in the call to
             XXmmCClliippbbooaarrddSSttaarrttCCooppyy.

             After calling XXmmCClliippbbooaarrddSSttaarrttCCooppyy, the application
             makes one or more calls to XXmmCClliippbbooaarrddCCooppyy to place
             data on the clipboard.  Each call associates the data
             with a single target (called a format in the clipboard
             interface).  The application can associate the same
             data or different data with more than one target, but
             it must do so by making separate calls to
             XXmmCClliippbbooaarrddCCooppyy.





        May 9, 1992                                            16-27








        OSF/Motif Programmer's Guide


             If the application passes a NULL data buffer to
             XXmmCClliippbbooaarrddCCooppyy, it asserts that it intends to transfer
             the actual data for that target when a client requests
             it.  Otherwise, XXmmCClliippbbooaarrddCCooppyy transfers data to be
             stored on the clipboard by XXmmCClliippbbooaarrddEEnnddCCooppyy.  If the
             application makes more than one call to XXmmCClliippbbooaarrddCCooppyy
             for the same target, the data is appended to the
             previously transferred data for that target.

             XXmmCClliippbbooaarrddCCooppyy returns in one of its arguments a data
             ID that identifies the data and target specified in
             this call.  An application that provides actual data at
             the time a client requests it uses this ID in its
             conversion routine to identify the data and target to
             be converted.  Such an application must store a mapping
             of the data ID to the data and target after
             XXmmCClliippbbooaarrddCCooppyy returns.

             The application terminates the interaction by calling
             XXmmCClliippbbooaarrddEEnnddCCooppyy or XXmmCClliippbbooaarrddCCaanncceellCCooppyy.
             XXmmCClliippbbooaarrddEEnnddCCooppyy stores in the server data structures
             the data transferred by the calls to XXmmCClliippbbooaarrddCCooppyy
             during this interaction sequence.  It also asserts
             ownership of the CLIPBOARD selection.  If the
             application calls XXmmCClliippbbooaarrddCCaanncceellCCooppyy instead of
             XXmmCClliippbbooaarrddEEnnddCCooppyy, the interaction is terminated
             without storing any of the transferred data or
             asserting ownership of the selection.

             If a client later requests data that the owner has
             declared it would provide at the time of the request,
             the clipboard interface invokes the conversion routine
             that the owner registered in the call to
             XXmmCClliippbbooaarrddSSttaarrttCCooppyy.  This routine receives as
             arguments the widget ID passed to XXmmCClliippbbooaarrddSSttaarrttCCooppyy;
             the data ID for this data and target returned by
             XXmmCClliippbbooaarrddCCooppyy; a private ID the application may have
             supplied in the call to XXmmCClliippbbooaarrddCCooppyy; and a reason
             for invoking the routine.

             The conversion routine is responsible for converting
             the data to the requested target.  In order to do this
             it must consult the mapping it established between the
             data ID or the private ID and the data and target when
             it called XXmmCClliippbbooaarrddCCooppyy.  Once the conversion routine
             has determined the proper target, it copies the data to
             the clipboard.  To do this it calls
             XXmmCClliippbbooaarrddCCooppyyBByyNNaammee, using the data ID passed to the
             conversion routine.  The application can call
             XXmmCClliippbbooaarrddCCooppyyBByyNNaammee more than once if necessary to
             convert all the data for this target.



        16-28                                            May 9, 1992








                                           Interclient Communication


             Once an application has copied data to the clipboard in
             this way, it no longer asserts that it will convert the
             same data to the same target in the future.  It can
             remove the data ID from its mapping of data IDs to data
             and targets, and it can free any data it has associated
             with this ID if it is not needed for any other purpose.

             The clipboard interface calls the conversion routine
             when a data item intended for later conversion has been
             removed from the clipboard and is no longer needed.
             For example, another application may have copied new
             data to the clipboard.  In this case the conversion
             routine can remove the data ID from its mapping of data
             IDs to data and targets, and it can free any data it
             has associated with this ID if it is not needed for any
             other purpose.  If the conversion routine is being
             called because an item has been removed from the
             clipboard, the _r_e_a_s_o_n argument to the conversion
             routine is 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.  If the
             conversion routine is being called because a client has
             requested data conversion, the _r_e_a_s_o_n argument is
             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.

             An application can use 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 to
             rescind its assertion that it will convert data to a
             particular target on request.

             XXmmCClliippbbooaarrddUUnnddooCCooppyy removes the last item placed on the
             clipboard by an application using the same _d_i_s_p_l_a_y and
             _w_i_n_d_o_w arguments.  This function also restores to the
             clipboard the item that was on the clipboard before the
             cancelled copy was done.  If the application calls
             XXmmCClliippbbooaarrddUUnnddooCCooppyy a second time, the function
             restores to the clipboard the item that was removed by
             the first call to XXmmCClliippbbooaarrddUUnnddooCCooppyy.



        16.5.2  RReettrriieevviinngg DDaattaa ffrroomm tthhee CClliippbbooaarrdd



             To retrieve data from the clipboard, an application
             takes these steps:

                +o It calls 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 to begin the
                  interaction

                +o It makes one or more calls to XXmmCClliippbbooaarrddRReettrriieevvee
                  to retrieve data from the clipboard




        May 9, 1992                                            16-29








        OSF/Motif Programmer's Guide


                +o It terminates the interaction by calling
                  XXmmCClliippbbooaarrddEEnnddRReettrriieevvee

             An application begins an interaction to retrieve data
             from the clipboard by calling 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.
             The application passes a display pointer, a timestamp,
             and the ID of a window in the application.  The
             application must pass the same window ID to subsequent
             clipboard calls in this sequence that it uses in 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.
             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 locks the clipboard.

             After calling 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, the application
             makes one or more calls to XXmmCClliippbbooaarrddRReettrriieevvee to
             retrieve data from the clipboard, converted to a given
             target.  The application passes XXmmCClliippbbooaarrddRReettrriieevvee a
             buffer to receive the data.  If this buffer is not
             large enough to contain all the data for the given
             target, XXmmCClliippbbooaarrddRReettrriieevvee returns
             XXmmCClliippbbooaarrddTTrruunnccaattee.  The application can make repeated
             calls to XXmmCClliippbbooaarrddRReettrriieevvee to retrieve the remainder
             of the data.  The function 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 on the clipboard for the
             given target.  This allows the application to allocate
             a buffer of the correct size.

             XXmmCClliippbbooaarrddEEnnddRReettrriieevvee unlocks the clipboard and ends
             the interaction.



        16.5.3  UUttiilliittyy RRoouuttiinneess



             The Motif clipboard interface has routines to lock and
             unlock the clipboard, to make inquiries about its
             contents, and to register new targets.

             XXmmCClliippbbooaarrddLLoocckk prevents another application from
             gaining access to the Motif clipboard.
             XXmmCClliippbbooaarrddUUnnlloocckk allows other applications to gain
             access.  The clipboard interface automatically locks
             the clipboard during calls 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.  At other times an
             application can use 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 to lock the clipboard explicitly.

             The clipboard interface includes four routines for
             making inquiries about the clipboard contents:




        16-30                                            May 9, 1992








                                           Interclient Communication


                +o 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
                  targets for which data exists on the clipboard.

                +o 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 the name of the
                  target for a given index of targets on the
                  clipboard.  An application could retrieve the
                  names of all the targets associated with data on
                  the clipboard by first calling
                  XXmmCClliippbbooaarrddIInnqquuiirreeCCoouunntt to find out how many such
                  targets exist and then calling
                  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 with indices from 1 to
                  the number of targets, inclusive.  Note that the
                  first index for 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 is 1, not
                  0.

                +o 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 number of
                  bytes of data associated with a given target on
                  the clipboard.

                +o 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
                  pairs of data ID and private ID for a given target
                  if that target exists on the clipboard and if the
                  owner has asserted that it will supply the actual
                  data on request (but has not yet done so).

             An application that makes more than one call to an
             inquiry function at a time should use 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 to lock the clipboard for the
             duration of the interaction.

             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 target with
             the clipboard interface.  The application supplies the
             length of the data in bits along with the name of the
             target so that the correct byte order will be
             maintained when transferring data across platforms.
             All targets defined in ICCCM are preregistered; the
             application does not have to call
             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 for these.
















        May 9, 1992                                            16-31






 p
