PuiPrintBox(3X)
PuiPrintBox - print spooler interface widget
As shipped in IRIX 6.5.30. Unchanged since IRIX 6.5.
NAME PuiPrintBox - print spooler interface widget SYNOPSIS #include <Sgm/PrintBox.h> Linkage: ... -lprintui -lspool -lXm -lXt -lX11 -lgen ... Instantiation Methods: widget = PuiCreatePrintBox(parent, name, args, nargs); widget = PuiCreatePrintDialog(parent, name, args, nargs); widget = XtCreateWidget(name, puiPrintBoxWidgetClass, parent, args, nargs); DESCRIPTION The PuiPrintBox widget provides a graphical user interface to the lp printing command of the AT&T System V print spooling system. Using the PrintBox widget an application may submit a file or buffer for printing. In addition, the printer and options for the print job may be selected. The PrintBox widget contains six areas: - Filename entry area - Printer selection area - Job option area - Action area - Work area These areas are described below. Filename entry area If the print job is a file, the filename area provides a text field to enter the name(s) of the file(s) to be printed. Multiple files may be specified with each filename being separated by whitespace. Bourne shell filename meta characters may be specified but job control and other meta characters should not be used and may be disallowed by the text field. This area will be displayed only if the PuiNjobType resource (described below) is set to PuiPRINTJOB_FILENAME and the PuiNshowFilename resource is True. When present, the filename entry area is located in the upper left portion of the widget. Printer selection area The left portion of the PrintBox widget contains the printer selection area. This area displays a list of the printers available to the print spooling system. Any printer from the list may be selected for print job submittal. The PuiNdefaultPrinterFont resource can be used to differentiate the default printer from the other printers on the list. Job option area This area on the right side of the widget provides controls for various print job options. Job parameters such as the number of copies and banner page title may be specified in this area. There is also a text field provided for specifying options unique to the printer selected. The job option area will not be displayed if the PuiNshowOptions resource (described below) is set to False. Each option in the job option area can be selectively displayed by setting the appropriate resource (described below) to False. Action area The action area is located at the bottom of the widget and contains the PrintBox action push buttons. There are five action area push buttons, three of which are displayed by default. The following buttons are managed (visible) by default: Print Submits the specified file or buffer for printing by the spooling system. First the functions registered on the PuiNprintCallback list are invoked. Next, if the PuiNprintingPolicy resource is set to PuiWIDGET_PRINTING (the default), the PrintBox widget's internal function is called to submit the print job to the spooling system for printing. If PuiNprintingPolicy is set to PuiAPPLICATION_PRINTING, the widget's internal job submission function is not called, and it becomes the application's responsibility to submit the job for printing. If the print job was successfully submitted, the functions on the PuiNjobInfoCallback list will be invoked. If an error has occurred submitting the job, the functions on the PuiNerrorCallback will be invoked. Finally, if the PrintBox widget's XmNautoUnmanage resource is set to True and the widget is a child of a DialogShell, the PrintBox will be automatically unmanaged (popped down) after the callback and print functions have been called. More Options... Many printers provide specialized, vendor-specific options. The job option area provides a text type-in field for specifying these printer-specific options. However, some printers provide a graphical dialog for specifying the printer-specific options. If such a dialog is available for the selected printer, the More Options... button will have a normal appearance. If no dialog is available, the button will appear grayed out. When the More Options... button is pressed the graphical options dialog for the selected printer will be displayed. At the same time, the printer- specific options type-in field in the job option area will be grayed out and not editable. When the desired options have been selected on the option dialog, the OK button on the dialog should be pressed. This will remove the dialog from the screen and will place text in the printer-specific options field in the job option area. This text represents the options selected on the graphical option dialog. An Apply button is also available for specifying options without dismissing the dialog. Note that the type in field in the job option area becomes ungrayed and editable when the option dialog is no longer displayed. Save Options... Brings up a dialog that allows spooler and printer- specific option settings to be saved to disk. The spooler option settings are written to the file ~/.glprc. Spooler options consist of all settings in the job option area except the printer-specific options type-in values and the number of copies. If printer-specific options have been modified for any listed printer, those printers are listed on the dialog. These options are stored on a per printer basis in files named /var/spool/lp/settings/<printer name>/<username>. Note that the number of copies is not saved to either file since this option is more appropriately specified on the command line or via the job option are control. Printer-specific options cannot be saved for printer classes. If the PrintBox widget is created by either the user root or lp (based on the uid at the time the widget is instantiated), the Save dialog permits the saving of printer-specific options for all users of the selected printer. Cancel Calls the functions registered on the PuiNcancelCallback list. This button normally is used to pop down the PrintBox widget when it is used as a pop up dialog. If the PrintBox widget's XmNautoUnmanage resource is set to True and the widget is a child of a DialogShell, the PrintBox will be automatically unmanaged (popped down) after the callback functions have been invoked. Help Calls the functions registered on the PuiNhelpCallback list. In addition to these five buttons, there are four user- definable action area buttons that are unmanaged (invisible) by default. These buttons, called User1, User2, User3 and User4, are positioned between the Print and Cancel buttons. These buttons may be managed using the XtManageChild function, specifying the widget ID for the desired button. The widget ID can be obtained from the PuiPrintBoxGetChild function. When activated, the User buttons invoke the functions registered on their respective callback lists, PuiNuser1Callback PuiNuser2Callback, PuiNuser3Callback and PuiNuser4Callback. Work area The PrintBox widget allows an application to specify one child widget. This widget would typically be a Manager class widget that would contain application-specific printing controls such as page number range. When present, the work area is placed at the top of the PrintBox and spans the entire width of the widget. Settings Files When the PrintBox widget is created, it will read the file .glprc if it exists in the user's home directory. This file is expected to contain a single line of System V spooler option switches. The switches are the same as those available on the lp command line except that the -d, -o and -n options must not be specified. On creation the PrintBox widget also looks for files named /var/spool/lp/settings/<printer name>/<username> for each printer on the available printer list. For each printer, if the <username> file is not found a file name defaultSettings will be read, if it exists. The file is expected to contain a single line of printer-specific options. The options are listed as they would be typed into the printer-specific options type-in field in the job options area. Any additional lines in the file will be ignored. Any printer-specific options specified on the command line will be appended to the options found in the settings file for the initially selected printer. Note that printer-specific options are maintained on a per printer, per user basis. When a new printer is selected from the list of available printers, any options specified for that printer will be displayed in the job option area. Spooler and printer-specific options can be saved using the Save Options... button in the action area. The PrintBox widget reads the spooler and printer-specific options files when it is instantiated (e.g. when XtCreateWidget is called). The settings from these options files override any resource values for the corresponding options. Therefore, spooler and printer-specific option resources should not be set at the creation of the PrintBox widget. Spooler and printer-specific options resources should be set after widget creation using the XtSetValues function. Classes The PrintBox widget inherits behavior and resources from the Core, Composite, Constraint, XmManager, and XmBulletinBoard widget classes. The class pointer is puiPrintBoxWidgetClass and the class name is PuiPrintBox. New Resources The following table defines a set of widget resources used by the programmer to specify data. The programmer can also set the resource values for the inherited classes to set attributes for this widget. To reference a resource by name or by class in a .Xdefaults file, remove the PuiN or PuiC prefix and use the remaining letters. To specify one of the defined constant values for a resource in a .Xdefaults file, use the constant name as listed (including the Pui prefix, the case and any underscores). The codes in the access column indicate whether the given resource can be set at creation time (C), set by using XtSetValues (S), retrieved by using XtGetValues (G), or is not applicable (N/A). _____________________________________________________ PuiPrintBox Setup Resources ____________________________________________________ Name Default Access Class Type ____________________________________________________ PuiNbuffer NULL CSG PuiCBuffer XtPointer ____________________________________________________ PuiNbufSize 0 CSG PuiCBufSize int ____________________________________________________ PuiNdefPrinter NULL G PuiCDefPrinter char* ____________________________________________________ PuiNfd 0 CSG PuiCFd int ____________________________________________________ PuiNfilename NULL CSG PuiCFilename char* ____________________________________________________ PuiNjobType PuiPRINTJOB_FILENAME CG PuiCJobType int ____________________________________________________ PuiNnumPrinters 0 G PuiCNumPrinters int ____________________________________________________ PuiNprinter dynamic CSG PuiCPrinter char* ____________________________________________________ PuiNprinterList NULL G PuiCPrinterList SLPrinterStruct* ____________________________________________________ PuiNprintingPolicy PuiWIDGET_PRINTING CSG PuiCPrintingPolicy int ____________________________________________________ | | PuiNbuffer Specifies a buffer to be printed. This resource is used when PuiNjobType is set to PuiPRINTJOB_BUFFER and is otherwise ignored. If this resource is read, the value returned is a pointer into widget private storage and must not be deallocated. PuiNbufSize Specifies the number of bytes in the buffer specified by PuiNbuffer. This resource is used when PuiNjobType is set to PuiPRINTJOB_BUFFER and is otherwise ignored. PuiNdefPrinter This read-only resource provides the name of the spooling system default printer. If no default printer is known to the spooling system, this resource will be NULL. If a non-NULL value is returned, it is a pointer into widget private storage and must not be deallocated. PuiNfd Specifies an open file descriptor from which data is to be printed. This resource is used when PuiNjobType is set to PuiPRINTJOB_DESCRIPTOR and is ignored otherwise. PuiNfilename Specifies the name(s) of file(s) to be printed. Multiple filenames may be specified separated by whitespace. Bourne shell filename meta characters may be specified but job control and other meta characters should not be specified and may be disallowed by the widget. This resource is used when PuiNjobType is set to PuiPRINTJOB_FILENAME otherwise it is ignored. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNjobType The PrintBox widget can print data from three sources: files, file descriptors or buffers. PuiNjobType specifies which print source is to be used. The following table indicates the values which this resource may take: Print Source PuiNjobType Also specify ____________________________________________________ File(s) PuiPRINTJOB_FILENAME PuiNfilename Descriptor PuiPRINTJOB_DESCRIPTOR PuiNfd Buffer PuiPRINTJOB_BUFFER PuiNbuffer, PuiNbufSize Note that the filename entry area is displayed only when PuiNjobType is set to PuiPRINTJOB_FILENAME and PuiNshowFilename is True. PuiNnumPrinters This read-only resource indicates the number of printers currently available from the spooling system and listed in the printer selection area of the widget. PuiNprinter Setting this resource selects the specified printer name for printing. If the specified printer is not in the list of available printers, the widget will attempt to select the system default printer. If there is no default printer, the first printer in the printer list will be selected. Reading this resource provides the name of the currently selected printer. If this resource is read, the value returned is a pointer into widget private storage and must not be deallocated. PuiNprinterList This read-only resource provides the list of available printers. The list is an array with PuiNnumPrinters items each of type SLPrinterStruct. Refer to the man pages for libspool(3) and SLGetPrinterList(3X) for more information regarding this structure. If this resource is read, the value returned is a pointer into widget private storage and must not be deallocated. PuiNprintingPolicy Specifies who is responsible for submitting print jobs to the spooling system. The PrintBox widget has an internal routine for submitting jobs. This routine is invoked by activating the Print button or by calling the PuiPrintBoxDoPrint(3X) function. If PuiNprintingPolicy is set to PuiWIDGET_PRINTING (the default) the internal job submittal function will be used. If this resource is set to PuiAPPLICATION_PRINTING the internal routine will not be called and it becomes the responsibility of the application to submit the print job to the spooling system. ____________________________________________ PuiPrintBox Print Job Option Resources ___________________________________________ Name Default Access Class Type ___________________________________________ PuiNcopy dynamic SG PuiCCopy Boolean ___________________________________________ PuiNjobTitle dynamic SG PuiCJobTitle char* ___________________________________________ PuiNmail dynamic SG PuiCMail Boolean ___________________________________________ PuiNmessage dynamic SG PuiNMessage Boolean ___________________________________________ PuiNnumCopies 1 CSG PuiCNumCopies int ___________________________________________ PuiNprinterOptions dynamic SG PuiCPrinterOptions char* ___________________________________________ | | These options are similar to the command line flags for the System V lp command. Refer to the lp(1) man page for additional information on the meaning of these options. The initial values of these resources, with the exception of PuiNnumCopies, is determined at widget creation by the contents of the spooler options file ~/.glprc, if it exists. New values for these resources may be specified after the PrintBox widget has been created. PuiNcopy If True, specifies that the file(s) to be printed should be copied to the printer spooling directory thereby allowing the original file(s) to be modified without affecting the printed versions. If set to False links to the actual files will be created in the spooling directory. In this case, any modifications to the file(s) will be reflected in the printed output. In the absence of a spooler options file, the value of this resource defaults to False. PuiNjobTitle Specifies a title to be printed on the banner page of the print job. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. In the absence of a spooler options file, the value of this resource defaults to NULL. PuiNmail If True a mail message will be sent upon completion of the print job. Otherwise, no mail will be sent. In the absence of a spooler options file, the value of this resource defaults to False. PuiNmessage If True an attempt will be made to print a message on the user's terminal indicating that the print job has completed. If the terminal cannot be found, a mail message will be sent. In the absence of a spooler options file, the value of this resource defaults to False. PuiNnumCopies Specifies the number of copies to be printed. PuiNprinterOptions Specifies a string of printer-specific options. Multiple options may be specified separated by whitespace. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. In the absence of a spooler options file, the value of this resource defaults to NULL. _______________________________________________________________ PuiPrintBox Layout Resources ______________________________________________________________ Name Default Access Class Type ______________________________________________________________ PuiNbusyCursor Watch CSG PuiCCursor Cursor ______________________________________________________________ PuiNbuttonPlacement PuiBUTTONS_CENTER CG PuiCButtonPlacement int ______________________________________________________________ PuiNbuttonSpacing 8 CG PuiCButtonSpacing int ______________________________________________________________ PuiNdefaultPrinterFont [see description below] CG PuiCFont XFontStruct* ______________________________________________________________ PuiNfilenameSensitive True CSG PuiCSensitive Boolean ______________________________________________________________ PuiNinsensitiveBackground SGILightGrey CSG PuiCBackground Pixel ______________________________________________________________ PuiNinsensitiveForeground black CSG PuiCForeground Pixel ______________________________________________________________ PuiNlistVisibleItemCount 8 CG PuiCVisibleItemCount int ______________________________________________________________ PuiNnumCopiesSensitive True CSG PuiCSensitive Boolean ______________________________________________________________ PuiNprinterFont [see description below] CG PuiCFont XFontStruct* ______________________________________________________________ PuiNprinterOptionsSensitive True CSG PuiCSensitive Boolean ______________________________________________________________ PuiNshowBannerTitle True CG PuiCShowBannerTitle Boolean ______________________________________________________________ PuiNshowCompletion True CG PuiCShowCompletion Boolean ______________________________________________________________ PuiNshowFilename dynamic CG PuiCShowFilename Boolean ______________________________________________________________ | | ________________________________________________ PuiPrintBox Layout Resources (cont'd) _______________________________________________ Name Default Access Class Type _______________________________________________ PuiNshowHandling True CG PuiCShowHanding Boolean _______________________________________________ PuiNshowNumCopies True CG PuiCShowNumCopies Boolean _______________________________________________ PuiNshowOptions True CG PuiCShowOptions Boolean _______________________________________________ PuiNshowOptionsButton True CG PuiCShowOptionsButton Boolean _______________________________________________ PuiNshowPrinterOptions True CG PuiCShowPrinterOptions Boolean _______________________________________________ PuiNshowSaveButton True CG PuiCShowSaveButton Boolean _______________________________________________ | | PuiNbusyCursor Specifies the cursor shape to use during the period between the pressing of the More Options... button and the actual appearance on the screen of the option dialog. PuiNbuttonPlacement The action area push buttons can be grouped on the left side, right side or center of the action area by setting this resource to PuiBUTTONS_LEFT, PuiBUTTONS_RIGHT, or PuiBUTTONS_CENTER respectively. By default the buttons area centered in the action area. PuiNbuttonSpacing Specifies the horizontal spacing between the push buttons in the action area. PuiNdefaultPrinterFont Specifies the font in which the default printer should be displayed on the available printers list. Typically, the font selected will be a bold version of the font specified by PuiNprinterFont. The font selected should be a fixed width font. If this resource is read, the value returned is a pointer into widget private storage and must not be deallocated. The default for this resource is -*-screen-bold-r-normal-*-15*. PuiNfilenameSensitive If set to True, the filename text field will permit user input of filenames. If set to False, the field will not accept input, the background of the field will be set to the color specified by the PuiNinsensitiveBackground resource and the foreground will be set to the color specified by PuiNinsensitiveForeground. PuiNinsensitiveBackground Specifies the background color for text entry fields when they are in an insensitive state. PuiNinsensitiveForeground Specifies the foreground color for text entry fields when they are in an insensitive state. PuiNlistVisibleItemCount Specifies the number of lines to display for the available printers list. This resource is ignored if the job option area is displayed (showOptions is True). In this case the number of lines displayed is determined by the height of the job option area. PuiNnumCopiesSensitive If set to True, the copies text field will permit user input for the number of copies. If set to False, the field will not accept input, the background of the field will be set to the color specified by the PuiNinsensitiveBackground resource and the foreground will be set to the color specified by PuiNinsensitiveForeground. PuiNprinterFont Specifies the font in which the available printer list should be displayed. Typically, the font selected will be a non-bold version version of the font used for the default printer. The font selected should be a fixed width font. If this resource is read, the value returned is a pointer into widget private storage and must not be deallocated. The default for this resource is -*-screen-medium-r-normal-*-15*. PuiNprinterOptionsSensitive If set to True, the printer-specific options text field will permit user input. If set to False, the field will not accept input, the background of the field will be set to the color specified by the PuiNinsensitiveBackground resource and the foreground will be set to the color specified by PuiNinsensitiveForeground. PuiNshowBannerTitle If set to False, the banner page title options will not be displayed. PuiNshowCompletion If set to False, the job completion notification options will not be displayed. PuiNshowFilename If set to False the filename entry area will not be displayed. Note that when PuiNjobType is set to PuiNPRINTJOB_BUFFER or PuiPRINTJOB_DESCRIPTOR the filename entry area is not displayed regardless of the value of this resource. PuiNshowHandling If set to False, the print file handling options will not be displayed. PuiNshowNumCopies If set to False, the number of copies option will not be displayed. PuiNshowOptions If set to False, the job option area will not be displayed. PuiNshowOptionsButton If set to False, the More Options... button will not be displayed in the action area. PuiNshowPrinterOptions If set to False, the printer-specific options will not be displayed. PuiNshowSaveButton If set to False, the Save Options... button will not be displayed in the action area. ______________________________________________________________ PuiPrintBox Label Resources _____________________________________________________________ Name Default Access Class Type _____________________________________________________________ PuiNcancelLabelString "Cancel" CSG PuiCCancelLabelString XmString _____________________________________________________________ PuiNcompletionLabelString [see desc. below] CSG PuiCCompletionLabelString XmString _____________________________________________________________ PuiNcopyJobLabelString [see desc. below] CSG PuiCCopyJobLabelString XmString _____________________________________________________________ PuiNfilenameLabelString "Files to print:" CSG PuiCFilenameLabelString XmString _____________________________________________________________ PuiNhandlingLabelString [see desc.below] CSG PuiCHandlingLabelString XmString _____________________________________________________________ PuiNhelpLabelString "Help" CSG PuiCHelpLabelString XmString _____________________________________________________________ PuiNjobDefTitleLabelString "Default" CSG PuiCJobDefTitleLabelString XmString _____________________________________________________________ PuiNjobSpecTitleLabelString "Custom:" CSG PuiCJobSpecTitleLabelString XmString _____________________________________________________________ PuiNjobTitleLabelString "Banner page title:" CSG PuiCJobTitleLabelString XmString _____________________________________________________________ PuiNlinkJobLabelString [see desc. below] CSG PuiCLinkJobLabelString XmString _____________________________________________________________ PuiNmailLabelString "Send mail" CSG PuiCMailLabelString XmString _____________________________________________________________ PuiNmessageLabelString [see desc. below] CSG PuiCMessageLabelString XmString _____________________________________________________________ PuiNnumCopiesLabelString "Number of copies:" CSG PuiCNumCopiesLabelString XmString _____________________________________________________________ PuiNoptionLabelString "Options:" CSG PuiCOptionLabelString XmString _____________________________________________________________ | | ________________________________________________________________ PuiPrintBox Label Resources (cont'd) _______________________________________________________________ Name Default Access Class Type _______________________________________________________________ PuiNoptionsbLabelString "More Options..." CSG PuiCOptionsbLabelString XmString _______________________________________________________________ PuiNprinterLabelString "Available printers:" CSG PuiCPrinterLabelString XmString _______________________________________________________________ PuiNprinterSpecLabelString [see desc. below] CSG PuiCPrinterSpecLabelString XmString _______________________________________________________________ PuiNprintLabelString "Print" CSG PuiCPrintLabelString XmString _______________________________________________________________ PuiNsaveLabelString "Save Options..." CSG PuiCSaveLabelString XmString _______________________________________________________________ PuiNsaveDlgTitleLabelString "Save Settings" CSG PuiCSaveDlgTitleLabelString XmString _______________________________________________________________ PuiNsaveDlgSaveLabelString "Save" CSG PuiCSaveDlgSaveLabelString XmString _______________________________________________________________ PuiNsaveDlgUserLabelString "Save - Personal" CSG PuiCSaveDlgUserLabelString XmString _______________________________________________________________ PuiNsaveDlgAllLabelString "Save - All Users" CSG PuiCSaveDlgAllLabelString XmString _______________________________________________________________ PuiNsaveDlgCancelLabelString "Cancel" CSG PuiCSaveDlgCancelLabelString XmString _______________________________________________________________ PuiNsaveDlgMsgLabelString [see desc. below] CSG PuiCSaveDlgMsgLabelString XmString _______________________________________________________________ PuiNuser1LabelString "User1" CSG PuiCUser1LabelString XmString _______________________________________________________________ PuiNuser2LabelString "User2" CSG PuiCUser2LabelString XmString _______________________________________________________________ | | _______________________________________________ PuiPrintBox Label Resources (cont'd) ______________________________________________ Name Default Access Class Type ______________________________________________ PuiNuser3LabelString "User3" CSG PuiCUser3LabelString XmString ______________________________________________ PuiNuser4LabelString "User4" CSG PuiCUser4LabelString XmString ______________________________________________ | | PuiNcancelLabelString Specifies the label for the Cancel button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNcompletionLabelString Specifies the label for the print job completion notification option. The default value for this option is "When job is complete:". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNcopyJobLabelString Specifies the label for the print file copy handling option. The default value for this option is "Copy to spool directory". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNfilenameLabelString Specifies the section title for the filename entry area. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNhandlingLabelString Specifies the label for the print file handling option. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. The default value for this resource is "Print file handling:". PuiNhelpLabelString Specifies the label for the Help button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNjobDefTitleLabelString Specifies the label for the default banner page title option. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNjobSpecTitleLabelString Specifies the label for the user specified banner page title option. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNjobTitleLabelString Specifies the label for the banner page title options. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNlinkJobLabelString Specifies the label for the link print file handling option. The default value for this option is "Link in spool directory". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNmailLabelString Specifies the label for the send mail upon job completion option. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNmessageLabelString Specifies the label for the console message upon completion option. The default value for this option is "Send message to console". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNnumCopiesLabelString Specifies the label for the number of copies option. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNoptionLabelString Specifies the section title for the job option area. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNoptionsbLabelString Specifies the label for the More Options... button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNprinterLabelString Specifies the section title for the printer selection area. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNprinterSpecLabelString Specifies the label for the printer-specific options. The default value for this option is "Printer-specific options:". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNprintLabelString Specifies the label for the Print button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveLabelString Specifies the label for the Save Options... button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveDlgTitleLabelString Specifies the title of the options save dialog box. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveDlgSaveLabelString Specifies the label for the Save button on the options save dialog box. This label is used when the user is not "root" or "lp". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveDlgUserLabelString Specifies the label for the save personal settings button on the save options dialog box. This button appears when the user is "root" or "lp". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveDlgAllLabelString Specifies the label for the save default settings button on the save options dialog box. This button appears when the user is "root" or "lp". If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveDlgCancelLabelString Specifies the label for the Cancel button on the save options dialog box. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNsaveDlgMsgLabelString Specifies the explanatory message that appears at the top of the save options dialog box. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. The default value for this resource is "Save spooler settings.<nl><nl>In addition, save printer-specific settings for:". PuiNuser1LabelString Specifies the label for the User1 button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNuser2LabelString Specifies the label for the User2 button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNuser3LabelString Specifies the label for the User3 button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. PuiNuser4LabelString Specifies the label for the User4 button. If this resource is read and the value is not NULL, the storage associated with this resource should be freed using XtFree(3Xt) when no longer needed. ________________________________________________________ PuiPrintBox Callback Resources _______________________________________________________ Name Default Access Class Type _______________________________________________________ PuiNcancelCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNerrorCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNhelpCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNjobInfoCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNoptionErrorCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNprintCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNprinterActionCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNprinterSelectCallback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNuser1Callback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNuser2Callback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNuser3Callback NULL C PuiCCallback XtCallbackList _______________________________________________________ PuiNuser4Callback NULL C PuiCCallback XtCallbackList _______________________________________________________ | | PuiNcancelCallback Specifies the list of callback functions called when the user activates the Cancel button. The callback reason is PuiCR_CANCEL. PuiNerrorCallback Specifies the list of callback functions called when an error has occurred in the submittal of a print job. An error can also be triggered by other interactions with the spooling system such as determining the available printers. The callback reason is PuiCR_ERROR. Error caused by executing a printer options dialog are reported on the PuiNoptionErrorCallback. PuiNhelpCallback Specifies the list of callback functions called when the user activates the Help button. The callback reason is PuiCR_HELP. PuiNjobInfoCallback When a print job has been successfully submitted to the spooling system the functions on this callback list will be called. The callback data will provide information on the job. The callback reason is PuiCR_JOB_INFO. PuiNoptionErrorCallback Specifies the list of callback functions called when an error has occurred while executing a printer-specific option panel program. The callback reason is PuiCR_OPT_ERROR. Printing errors are reported on the PuiNerrorCallback. PuiNprintCallback Specifies the list of callback functions called when the user activates the Print button or calls the PuiPrintBoxDoPrint(3X) function. The callback reason is PuiCR_PRINT. This callback provides a number of capabilities. If PuiNprintingPolicy is PuiWIDGET_PRINTING (the default), the functions on this callback are called before any printing is performed by the widget. This allows the application to perform any pre-printing processing such as setting a busy cursor or specifying a buffer for the PuiPrintBox widget to print. Upon return from the last user specified callback function, the widget will submit a print job. If PuiNprintingPolicy is PuiAPPLICATION_PRINTING, this callback would be used by the application to submit a print job using its own printing method. PuiNprinterActionCallback Specifies the list of callback functions called when a printer on the available printer list is double clicked. The callback reason is PuiCR_PR_ACTION. PuiNprinterSelectCallback Specifies the list of callback functions called when a printer is selected from the available printer list. These callbacks are also called when a new printer is selected using the PuiNprinter resource. The callback reason is PuiCR_PR_SELECT. PuiNuser1Callback Specifies the list of callback functions called when the user activates the User1 button. The callback reason is PuiCR_USER1. PuiNuser2Callback Specifies the list of callback functions called when the user activates the User2 button. The callback reason is PuiCR_USER2. PuiNuser3Callback Specifies the list of callback functions called when the user activates the User3 button. The callback reason is PuiCR_USER3. PuiNuser4Callback Specifies the list of callback functions called when the user activates the User4 button. The callback reason is PuiCR_USER4. Inherited Resources The PrintBox widget inherits behavior and resources from the following superclasses. For a complete description of each resource, refer to the man page for that superclass. ___________________________________________________ XmBulletinBoard Resources __________________________________________________ Name Default Access Class Type __________________________________________________ XmNallowOverlap True CSG XmCAllowOverlap Boolean __________________________________________________ XmNautoUnmanage True CG XmCAutoUnmanage Boolean __________________________________________________ XmNbuttonFontList dynamic CSG XmCButtonFontList XmFontList __________________________________________________ XmNcancelButton dynamic SG XmCWidget Widget __________________________________________________ XmNdefaultButton dynamic SG XmCWidget Widget __________________________________________________ XmNdefaultPosition True CSG XmCDefaultPosition Boolean __________________________________________________ XmNdialogStyle dynamic CSG XmCDialogStyle unsigned char __________________________________________________ XmNdialogTitle NULL CSG XmCDialogTitle XmString __________________________________________________ XmNfocusCallback NULL C XmCCallback XtCallbackList __________________________________________________ XmNlabelFontList dynamic CSG XmCLabelFontList XmFontList __________________________________________________ XmNmapCallback NULL C XmCCallback XtCallbackList __________________________________________________ XmNmarginHeight 10 CSG XmCMarginHeight Dimension __________________________________________________ XmNmarginWidth 10 CSG XmCMarginWidth Dimension __________________________________________________ XmNnoResize False CSG XmCNoResize Boolean __________________________________________________ | | __________________________________________________ XmBulletinBoard Resources (cont'd) _________________________________________________ Name Default Access Class Type _________________________________________________ XmNresizePolicy XmRESIZE_ANY CSG XmCResizePolicy unsigned char _________________________________________________ XmNshadowType XmSHADOW_OUT CSG XmCShadowType unsigned char _________________________________________________ XmNtextFontList dynamic CSG XmCTextFontList XmFontList _________________________________________________ XmNtextTranslations NULL C XmCTranslations XtTranslations _________________________________________________ XmNunmapCallbackXt NULL C XmCCallback XtCallbackList _________________________________________________ | | _______________________________________________________________ XmManager Resources ______________________________________________________________ Name Default Access Class Type ______________________________________________________________ XmNbottomShadowColor dynamic CSG XmCBottomShadowColor Pixel ______________________________________________________________ XmNbottomShadowPixmap XmUNSPECIFIED_PIXMAP CSG XmCBottomShadowPixmap Pixmap ______________________________________________________________ XmNforeground dynamic CSG XmCForeground Pixel ______________________________________________________________ XmNhelpCallback NULL C XmCCallback XtCallbackList ______________________________________________________________ XmNhighlightColor dynamic CSG XmCHighlightColor Pixel ______________________________________________________________ XmNhighlightPixmap dynamic CSG XmCHighlightPixmap Pixmap ______________________________________________________________ XmNinitialFocus NULL CSG XmCInitialFocus Widget ______________________________________________________________ XmNnavigationType dynamic CSG XmCNavigationType XmNavigationType ______________________________________________________________ XmNshadowThickness dynamic CSG XmCShadowThickness Dimension ______________________________________________________________ XmNstringDirection dynamic CG XmCStringDirection XmStringDirection ______________________________________________________________ XmNtopShadowColor dynamic CSG XmCBackgroundTopShadowColor Pixel ______________________________________________________________ XmNtopShadowPixmap dynamic CSG XmCTopShadowPixmap Pixmap ______________________________________________________________ XmNtraversalOn True CSG XmCTraversalOn Boolean ______________________________________________________________ | | ___________________________________________ XmManager Resources (cont'd) __________________________________________ Name Default Access Class Type __________________________________________ XmNunitType dynamic CSG XmCUnitType unsigned char __________________________________________ XmNuserData NULL CSG XmCUserData Pointer __________________________________________ | | ______________________________________________ Composite Resources _____________________________________________ Name Default Access Class Type _____________________________________________ XmNchildren NULL G XmCReadOnly WidgetList _____________________________________________ XmNinsertPosition NULL CSG XmCInsertPosition (*)() _____________________________________________ XmNnumChildren 0 G XmCReadOnly Cardinal _____________________________________________ | | ________________________________________________________________ Core Resources _______________________________________________________________ Name Default Access Class Type _______________________________________________________________ XmNaccelerators dynamic N/A XmCAccelerators XtAccelerators _______________________________________________________________ XmNancestorSensitive dynamic G XmCSensitive Boolean _______________________________________________________________ XmNbackground dynamic CSG XmCBackground Pixel _______________________________________________________________ XmNbackgroundPixmap XmUNSPECIFIED_PIXMAP CSG XmCPixmap Pixmap _______________________________________________________________ XmNborderColor XtDefaultForeground CSG XmCBorderColor Pixel _______________________________________________________________ XmNborderPixmap XmUNSPECIFIED_PIXMAP CSG XmCPixmap Pixmap _______________________________________________________________ XmNborderWidth 0 CSG XmCBorderWidth Dimension _______________________________________________________________ XmNcolormap dynamic CG XmCColormap Colormap _______________________________________________________________ XmNdepth dynamic CG XmCDepth int _______________________________________________________________ XmNdestroyCallback NULL C XmCCallback XtCallbackList _______________________________________________________________ XmNheight dynamic CSG XmCHeight Dimension _______________________________________________________________ XmNinitialResourcesPersistent True C XmCInitialResourcesPersistent Boolean _______________________________________________________________ XmNmappedWhenManaged True CSG XmCMappedWhenManaged Boolean _______________________________________________________________ XmNscreen dynamic CG XmCScreen Screen* _______________________________________________________________ | | ________________________________________________ Core Resources (cont'd) _______________________________________________ Name Default Access Class Type _______________________________________________ XmNsensitive True CSG XmCSensitive Boolean _______________________________________________ XmNtranslations dynamic CSG XmCTranslations XtTranslations _______________________________________________ XmNwidth dynamic CSG XmCWidth Dimension _______________________________________________ XmNx 0 CSG XmCPosition Position _______________________________________________ XmNy 0 CSG XmCPosition Position _______________________________________________ | | Callback Information A pointer to the following structure is passed as call_data to each callback function: typedef struct _PuiPrintBoxCallbackStruct { int reason; XEvent *event; SLPrintJob *job_info; char *selected_printer; int selected_position; int error_code; } PuiPrintBoxCallbackStruct; reason Indicates why the callback was invoked. event Points to the X event that triggered the callback. job_info Provides print job submittal information. selected_printer Provides the name of the printer selected from the list of available printers. This string is a pointer to internal storage and must not be deallocated or reallocated by the user. Copy the string to user allocated storage to preserve it across callbacks. selected_position Provides the position of the selected printer in the list of available printers. For consistency with the Motif List widget the position of items start with 1 instead of 0. error_code Provides an error condition code. If the callback reason is PuiCR_ERROR, the error code is the libspool error code reported by SLerrno. Refer to the man pages for libspool(3) and SLPerror(3X) for more information. If the callback reason is PuiCR_OPT_ERROR, the error code is the standard system error code reported by errno. Not all callback fields are relevant for all callback conditions. The reason field indicates which callback structure fields are valid. The valid fields for each reason are summarized in the following table: Reason Valid Fields ___________________________________________ PuiCR_PRINT reason, event PuiCR_CANCEL reason, event PuiCR_HELP reason, event PuiCR_USER1 reason, event PuiCR_USER2 reason, event PuiCR_USER3 reason, event PuiCR_USER4 reason, event PuiCR_JOB_INFO reason, job_info PuiCR_PR_SELECT reason, selected_printer, selected_position PuiCR_PR_ACTION reason, selected_printer, selected_position PuiCR_ERROR reason, error_code PuiCR_OPT_ERROR reason, error_code Translations The PrintBox widget inherits its translations from the XmBulletinBoard widget class. NOTES 1. The PrintBox widget determines what printers are available when it is instantiated. Therefore, the PuiNprinterList, PuiNnumPrinters, and PuiNdefPrinter resources are not updated if the printing environment changes during the PrintBox widget's lifetime. 2. The PrintBox widget can report an error condition on its PuiNerrorCallback during initial management and realization if the System V print spooling scheduler lpsched is not running or if an error occurs determining the list of available printers. Applications with functions registered on this callback list should be prepared to handle errors at this point in the PrintBox widget life cycle. 4. Do not set a new value for the PuiNprinterOptions resource while a printer-specific option panel is displayed. The printer-specific options selected in the option panel will override the options set by the resource. 5. The printer selection list should use fixed width fonts for both the regular printers and the default printer. A fixed width font will preserve the columnar organization of the list items. 6. When the PrintBox widget is instantiated it determines the username based on the current real UID. The username is used for the reading and saving option settings. If the real UID is changed programmatically after the PrintBox has been instantiated, the widget must be destroyed and re-instantiated if it is to save options for the new UID. SEE ALSO PuiCreatePrintBox(3X), PuiCreatePrintDialog(3X), libprintui(3X), libspool(3)