XpCreateContext

XpCreateContext(3Xp)	       XPRINT FUNCTIONS		 XpCreateContext(3Xp)



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	 COM-
	      POUND_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  XpSetAt-
       tributes,  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  XpSetCon-
       text.  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 cre-
       ating 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-sup-
       ported,	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 unde-
       fined behavior.

       When XpCreateContext is called, the client’s locale (see	 XpSetLocale-
       Hinter)	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  under-
       stand 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	draw-
		      able  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)









							 XpCreateContext(3Xp)