Functional specification
52
CDE/Motif PST
CDEnext
selection_display
A returned display connection against which the PDM selection should be
made. May be equal to
print_display
or
video_display
, or may
be a new display connection that the caller should close when done.
selection
A returned selection atom against which a PDM selection should be made.
type
A returned type for the PDM Selection Protocol property the caller is
expected to create.
format
A returned format for the PDM Selection Protocol property the caller is
expected to create.
data
A returned data set for the PDM Selection Protocol property the caller is
expected to create. The caller is expected to
XFree(3C)
the data when
finished.
nelements
A returned number of elements for the PDM Selection Protocol property
the caller is expected to create.
RETURN VALUE
NULL status if an error occured, non-NULL otherwise.
DESCRIPTION
XpGetPdmStartParams
is a convenience routine used to construct the necessary property information
and selection display connection information needed to initiate a PDM Selection per the "PDM Selection
Protocol". Once the information is constructed, the caller can manage the creation of a property, the
generation of a
SelectionRequest
, the receipt of a
SelectionNotify
event, and the recept of a
ClientMessage
event, as described in the PDM Selection Protocol.
When finished, the caller is expected to free
data
using
XFree(3C)
.
If
NULL
is returned by
XpGetPdmStartParams
, then an error occured and all return values are invalid.
XpGetPdmStartParams
also implements the concept of an "alternate selection server". By changing
the name of the x-selection or by changing the X-Server upon which the selection is made, an alternate
PDM can be engaged. By default, the PDM owning the
PDM_MANAGER
x-selection on the Print X-Server
is the PDM engaged.
Setting the environment variable XPDMSELECTION causes
XpGetPdmStartParams
to use an
alternate selection name. If not set, the selection name
PDM_MANAGER
is used.
Setting the environment variable XPDMDISPLAY causes
XpGetPdmStartParams
to locate the
selection on an alternate X Server. If not set,
selection_display
(a returned parameter) is set equal
to
print_display
. If set to one of the keywords
"print"
or
"video"
,
selection_display
is
set to
print_display
or
video_display
, respectively. If set to a valid
DISPLAY
-style string,
selection_display
may be set, as appropriate, to one of
print_display
,
video_display
, or
to a new display connection made from within
XpGetPdmStartParams
. Only in the single case where
a new display connection is made should the caller close
selection_display
using
XCloseDisplay(3)
.