NAME

       XpGetPdmStartParams  -  Builds up parameters in accordance with the PDM Selection Protocol
       as a standard convenience function.

SYNOPSIS

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

       Status  XpGetPdmStartParams  (  print_display  print_window  print_context   video_display
       video_window    selection_display_return    selection_return   type_return   format_return
       data_return nelements_return )
             Display *print_display;
             Window print_window;
             XPContext print_context;
             Display *video_display;
             Window video_window;
             Display **selection_display_return;
             Atom *selection_return;
             Atom *type_return;
             int *format_return;
             unsigned char **data_return;
             int *nelements_return;

ARGUMENTS

       print_display
              Specifies a pointer to the print Display structure; returned from  XOpenDisplay  on
              the X Print Server.

       print_window
              Specifies  a  client  window  on  any screen of print_display long-lived enough for
              ICCCM communications of the final PDM status ("OK" or "CANCEL" ClientMessage)  sent
              to print_window.

       print_context
              An existing print context that the PDM should reference.

       video_display
              Specifies  a  pointer to the video Display structure; returned from XOpenDisplay on
              the Video X-Server.

       video_window
              Specifies the window on video_display near which the transient dialogs from the PDM
              should be posted.

       selection_display_return
              Returns  the  display  connection on 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_return
              Returns the selection atom for which a PDM selection should be made.

       type_return
              Returns  the type for the PDM Selection Protocol property the caller is expected to
              create.

       format_return
              Returns the format for the PDM Selection Protocol property the caller  is  expected
              to create.

       data_return
              Returns the data set for the PDM Selection Protocol property the caller is expected
              to create. The caller is expected to XFree the data when finished.

       nelements_return
              Returns the number of elements for the PDM Selection Protocol property  the  caller
              is expected to create.

DESCRIPTION

       This request returns a zero status if an error occurred, non-zero otherwise.

       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  is  responsible  for  the  creation  of  a   property,   the   generation   of   a
       SelectionRequest,   the  receipt  of  a  SelectionNotify  event,  and  the  receipt  of  a
       ClientMessage event, as described in the PDM Selection Protocol.

       When finished, the caller is expected  to  free  data  using  XFree.   XpGetPdmStartParams
       returns  zero  if  an  error  occurred, else non-zero. If an error occurs all other_return
       values are undefined.

       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_return
        is set equal to print_display.  If XPDMDISPLAY is set to one of the keywords  "print"  or
       "video",  selection_display_return is set to print_display or video_display, respectively.
       If XPDMDISPLAY is set to a valid DISPLAY-style  string,  selection_display_return  may  be
       set,  as  appropriate,  to  one  of  print_display,  video_display,  or  to  a new display
       connection opened from within XpGetPdmStartParams. Only in the single  case  where  a  new
       display  connection  is  made  should  the  caller  close  selection_display_return  using
       XCloseDisplay.

       When XpGetPdmStartParams  is  called,  the  caller's  locale  (see  XpSetLocaleHinter)  is
       included in the information as a "hint" to the Print Dialog Manager (PDM). If supported by
       the implementation, the PDM will use  the  hint  to  display  dialogs  more  appropriately
       labeled  for  the  locale of the client. If the Print Dialog Manager cannot understand the
       hint, the PDM will choose a default. Note that the locale of the print attributes that the
       PDM  will  subsequently  access,  will already have been determined when the client called
       XpCreateContext.

       The  environment  variables  XPDMDISPLAY  and  XPDMSELECTION   are   re-read   each   time
       XpGetPdmStartParams is called.

SEE ALSO

       XpCreateContext(3Xp), XpSetLocaleHinter(3Xp)