NAME

       XpCreateContext - Creates and initializes a new print context.

SYNOPSIS

             cc [ flag... ] file... -lXp [ library... ]
             #include <X11/extensions/Print.h>

       XPContext XpCreateContext ( display, printer_name )
             Display *display;
             char *printer_name;

ARGUMENTS

       display
              Specifies a pointer to the Display structure; returned from XOpenDisplay.

       printer_name
              The name of a printer on display. String encoded as COMPOUND_TEXT.

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 is 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 in it can be accessed and modified by calling
       XpGetAttributes  and  XpSetAttributes,  and  the  event  selections  in  it  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.

       The XPContext returned by XpCreateContext is an XID, and can be used to set the print context on  display
       connections  by  calling  XpSetContext.  The  XPContext  id  can  be shared between processes and display
       connections. It is the responsibility of the clients sharing a print context to coordinate their usage of
       the context; for example they must ensure 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,
       the application must query the X Print Server via XpGetScreenOfContext  for  the  screen  that  has  been
       associated  with  the  print context, and then create all server resources that will be used in the print
       job on that screen. Failure to do so will result in undefined behavior.

       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  readable
       XPPrinterAttr  attribute  "descriptor" may be available in several different languages, and the hint will
       be used to select one). If the X Print Server cannot understand the hint, the X Print  Server  chooses  a
       default value.

       This  function  can generate a BadMatch error if the specified printer_name does not exist on display, or
       if the print server could not interpret the code set specified in printer_name.

DIAGNOSTICS

       BadMatch       The value specified for doc_fmt is not valid for the current document type  or  the  value
                      specified for drawable is not valid for the print context and print screen.

SEE ALSO

       XpDestroyContext(3Xp),     XpGetAttributes(3Xp),     XpGetPrinterList(3Xp),    XpGetScreenOfContext(3Xp),
       XpInputSelected(3Xp),        XpSelectInput(3Xp),         XpSetAttributes(3Xp),         XpSetContext(3Xp),
       XpSetLocaleHinter(3Xp), XpStartJob(3Xp)