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)