Functional specification
19
CDE/Motif PST
CDEnext
RETURN VALUE
context_id
for the new print context.
DESCRIPTION
XpCreateContext
creates a new print context that is initialized with the default printer attributes and
other information available for
printer_name
on
display
. A print context maintains the printer
name, print attributes, font capabilities, print (rendering) state and results, and is the object upon which the
Xp calls act.
If the library fails to generate a new print context id, a value of
None
is returned, otherwise a print context
id is always returned. If
printer_name
is invalid, a
BadMatch
will be generated later by the X Print
Server.
A call to
XpGetPrinterList
will return a valid list of values for
printer_name
. All printer name
values in the X Print Service are encoded as
COMPOUND_TEXT
(of which the ISO-8859-1 code-set is a
proper subset).
As soon as a print context is created, the print attributes within can be accessed and modified by calling
XpGetAttributes
and
XpSetAttributes
, and the event selections within can be modified by
calling
XpSelectInput
and
XpInputSelected
. Other Xp calls that explicitly take a print context
id as a parameter will operate directly on that print context. All Xp and X calls without a print context id
parameter (for example, all rendering oriented calls like
XpStartJob
and
XDrawLine
) require that a
print context be set on the display connection (see
XpSetContext
). Failure to set a print context prior to
calling a print-context-dependent call will result in the generation of an
XPBadContext
error.
A
context_id
for the print context is returned by
XpCreateContext
, and can be used to set the
print context on display connections by calling
XpSetContext
. These display connections can be made
from the same client (process) that called
XpCreateContext
, and from other clients (processes) that
have acquired the
context_id
(for example, by inter-process communication). It is the responsibility of
the clients sharing a print context to coordinate their usage of
XpDestroyContext
so that in-use print
contexts are not prematurely destroyed.
The
context_id
remains valid for all clients until 1) the client creating the print context closes its
display
connection, or 2) any client calls
XpDestroyContext
. The
context_id
can be kept
valid after the creating client's
display
connection closes if
XSetCloseDownMode
is called on
display
with
RetainPermanent
or
RetainTemporary
.
After creating a print context, and possibly modifying the
XPDocAttr
attribute
document-format
using a value from the list of available formats shown in the
XPPrinterAttr
attribute
document-
formats-supported
, it is important to ask the X Print Server via
XpGetScreenOfContext
which
screen has been associated with the print context, and create all X-resources that will be used in the print
job on that screen. Failure to do so will result in undefined behavior. Once
XpStartDoc
is called, it is
guaranteed that the screen returned by
XpGetScreenOfContext
will not change, hence this become
the best time to call
XpGetScreenOfContext
and to start creating X-resources for the print job.
When
XpCreateContext
is called, the client's locale (see
XpSetLocaleHinter
) is included in the
request as a "hint" to the X Print Server. If supported by the implementation, the X Print Server will use
the hint to initialize the attribute pools with any localized attribute values (for example, the human