DtPrintSetupBox(library call) DtPrintSetupBox(library call)
NAME [Toc] [Back]
DtPrintSetupBox - application print setup widget
SYNOPSIS [Toc] [Back]
#include <Dt/Print.h>
DESCRIPTION [Toc] [Back]
DtPrintSetupBox is a widget that is typically the initial window used
to set various options prior to printing from an application. This
widget is designed primarily for use by applications that utilize the
X Print Service. However, it can also be used by applications
employing other printing methods.
DtPrintSetupBox is organized based on generic print options and
application specific print options. The sections are clearly
demarcated with separators to set off the generic section from the
application specific section(s). By utilizing the DtNworkAreaLocation
resource, the application developer can choose to utilize an area
above the generic section, below the generic section, or both above
and below the generic section.
The four default buttons (Print, Setup, Cancel, and Help) are
considered generic buttons. Applications can create additional
pushbuttons as children of DtPrintSetupBox. These buttons will be laid
out following the Print button.
The Printer Name combo box contains the X printer specifier of the
printer to be used for the print job. The X printer specifier is an
identifier that uniquely identifies an X printer. The format of this
specifier is printerName@host: display.
Descendants [Toc] [Back]
DtPrintSetupBox creates the descendants shown in the following table.
An application can use XtNameToWidget to gain access to the named
descendent. In addition, a user or an application can use the
descendant name when specifying resource values.
Named Descendant Class Identity
BottomWorkAreaSeparator XmSeparatorGadget Separator above the bottom work
area
ButtonSeparator XmSeparatorGadget Separator above the pushbuttons
Cancel XmPushButtonGadget Cancel button
Copies XmSimpleSpinBox SpinBox containing the number of
copies
CopiesLabel XmLabelGadget Label for the Copies SpinBox
DescriptionLabel XmLabelGadget Label for the printer description
FileName XmTextField File name field
FileNameCheckBox XmRowColumn Check box (includes label) for
file name field
Help XmPushButtonGadget Help button
Info XmPushButtonGadget Printer information button
Name XmComboBox Printer name
- 1 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
NameLabel XmLabelGadget Label for the printer name field
Print XmPushButtonGadget Print button
SelectFile XmPushButtonGadget Select File button
SelectPrinter XmPushButtonGadget Select Printer button
Setup XmPushButtonGadget Setup button
TopWorkAreaSeparator XmSeparatorGadget Separator below the top work area
Classes [Toc] [Back]
DtPrintSetupBox inherits behavior and resources from the Core,
Composite, Constraint, XmManager, and XmBulletinBoard superclasses.
The class pointer is dtPrintSetupBoxWidgetClass.
The class name is DtPrintSetupBox.
Resources [Toc] [Back]
The following table lists the DtPrintSetupBox resources.
Name Class/Type Access Default Value
DtNcancelCallback DtCCancelCallback/XtCallbackList C NULL
DtNclosePrintDisplayCallback DtCCloseDisplayCallback/XtCallbackList C NULL
DtNcopies DtCCopies/int CSG 1
DtNdescription DtCDescription/XmString CSG dynamic
DtNfileName DtCPrintToFileName/String CSG NULL
DtNgetAttributesCallback DtCGetAttributesCallback/XtCallbackList C NULL
DtNminimizeButtons DtCminimizeButtons/Boolean CSG False
DtNprintCallback DtCPrintCallback/XtCallbackList C NULL
DtNprintDestination DtCPrintDestination/XtEnum CSG DtPRINT_TO_PRINTER
DtNprinterInfoProc DtCPrinterInfoProc/DtPrintSetupProc CSG dynamic
DtNprinterName DtCPrinter/String CSG dynamic
DtNprintSetupMode DtCPrintSetupMode/XtEnum CG DtPRINT_SETUP_XP
DtNselectFileProc DtCSelectFileProc/DtPrintSetupProc CSG default procedure
DtNselectPrinterProc DtCSelectPrinterProc/DtPrintSetupProc CSG dynamic
DtNsetAttributesCallback DtCSetAttributesCallback/XtCallbackList C NULL
DtNsetupProc DtCSetupProc/DtPrintSetupProc CSG dynamic
DtNsetupProc DtCSetupProc/DtPrintSetupProc CSG dynamic
DtNverifyPrinterProc DtCVerifyPrinterProc/DtPrintSetupProc CSG dynamic
DtNworkAreaLocation DtCworkAreaLocation/XtEnum CSG DtWORK_AREA_BOTTOM
The DtPrintSetupBox resources are defined as follows:
DtNcancelCallback [Toc] [Back]
Specifies the list of callbacks that is called when the
Cancel button is activated. The callback reason is
DtPRINT_CR_CANCEL.
DtNclosePrintDisplayCallback [Toc] [Back]
When the value of the DtNprintSetupMode resource is
DtPRINT_SETUP_XP, DtPrintSetupBox will manage the X printing
display connection and print context. As such,
DtNclosePrintDisplayCallback is provided to allow an
application to perform any desired processing (such as
- 2 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
destroying windows created on the print display) before
DtPrintSetupBox destroys the current print context and
closes the current print display connection.
This callback list will not be called if the value of the
DtNprintSetupMode resource is anything other than
DtPRINT_SETUP_XP.
The callback reason is DtPRINT_CR_CLOSE_PRINT_DISPLAY.
DtNcopies The number of copies of the document to print. This is a
spin box into which the user may enter a positive integer.
DtNdescription [Toc] [Back]
A description of the printer as provided by the system
administrator.
DtNfileName [Toc] [Back]
Specifies the name of the destination file. Setting this
resource will update the value of the File Name text field.
DtNgetAttributesCallback [Toc] [Back]
Specifies the list of callbacks that is called whenever
DtPrintSetupBox receives an XPAttributeNotify event, or
immediately after a new X printer connection is established.
This callback list will only be called if the value of the
DtNprintSetupMode resource is DtPRINT_SETUP_XP.
This callback is intended to be used by applications that
utilize X Print Service attributes directly. These
applications will be interested in changes made to the
printing attributes by DtPrintSetupBox or by other
processes, such as the Print Dialog Manager (PDM).
One of two callback reason codes will be set for this
callback. The two reasons are of particular interest to
applications that elect to present information in their GUI
based on X Print Service attributes. The following indicates
how such applications should respond to each code:
DtPRINT_CR_GET_STATIC_ATTRIBUTES [Toc] [Back]
The application should update only those controls
that cannot be modified by the user. This reason
is set in response to encountering a new set of
attributes as the result of DtPrintSetupBox's
establishing a new X printer connection.
Additionally, subsequent immediate action to be
taken by DtPrintSetupBox's will result in the
DtNsetAttributesCallback list being called
followed by either the DtNprintCallback list or
the DtNsetupProc. If the application were to
- 3 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
update dynamic GUI controls within this
DtNgetAttributesCallback, any input the user
provided would be overridden by the printer
defaults in the resulting print job or setup
dialog.
DtPRINT_CR_GET_ATTRIBUTES [Toc] [Back]
The application should update all static and
dynamic controls. This reason is set in response
to DtPrintSetupBox's receiving an
XpAttributeNotify event, or if a new X printer
connection was established as the result of the
user activating the Printer Info button.
DtNminimizeButtons [Toc] [Back]
If false, sets the dimensions of all of the buttons at the
bottom of the widget to the width of the widest button and
the height of the tallest button. If true, the dimensions of
the buttons are not altered.
DtNprintCallback [Toc] [Back]
Specifies the list of callbacks that is called when the
Print button is activated. The callback reason is
DtPRINT_CR_PRINT. This callback is used to initiate the
print job.
DtNprintDestination [Toc] [Back]
Indicates where the print output should be directed. Valid
values for this resource are:
DtPRINT_TO_FILE [Toc] [Back]
Direct print output to a file. The destination
file name is indicated by the DtNfileName
resource. Setting this value will cause the Print
To File checkbox to be selected, enable the File
Name text field, and enable the Select File
button.
DtPRINT_TO_PRINTER [Toc] [Back]
Direct print output to a printer. The destination
printer is indicated by the DtNprinterName
resource. Setting this value will cause the Print
To File checkbox to be deselected, disable the
File Name text field, and disable the Select File
button.
DtNprinterInfoProc [Toc] [Back]
This resource specifies the procedure that will be used to
present printer information in response to activation of the
Printer Information button. The printer selection dialog
presented by the default DtNselectPrinterProc will also call
- 4 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
this procedure in response to activation of its Printer
Information button.
If the value of the DtNprintSetupMode resource is
DtPRINT_SETUP_XP, a default procedure that presents a
printer information dialog is used. For other values of
DtNprintSetupMode, the default value of DtNprinterInfoProc
is NULL.
Typically, this procedure does not update DtPrintSetupBox
resources nor X Print Service attributes. The return value
of this procedure is ignored by DtPrintSetupBox. However, it
is recommended that the procedure follow the conventions
presented in the "DtPrintSetupProc" section to ensure future
compatibility.
DtNprinterName [Toc] [Back]
The name of the printer to send the print job to.
If the value of the DtNprintSetupMode resource is
DtPRINT_SETUP_XP, setting this resource will update the
Printer Name field based on the value of the
XpPrinterNameMode XRM resource. See the "EXTERNAL
INFLUENCES" section in this man page for more information.
If the value of the DtNprintSetupMode resource is
DtPRINT_SETUP_PLAIN, setting this resource will update the
value of the Printer Name text field with the value of this
resource.
DtNprintSetupMode [Toc] [Back]
Instructs the widget as to whether or not it is being used
in an application that utilizes the X Print Service. If so,
then the widget will manage the X printing display
connection and print context, and provide defaults for a
number of X printing operations, such as printer selection
and information dialogs, and printer verification. Refer to
individual resource descriptions to determine if and how
they are affected by the value of this resource. Valid
values for this resource are:
DtPRINT_SETUP_PLAIN [Toc] [Back]
This widget will be used by an application that
performs its own print document format generation
and print job submission.
DtPRINT_SETUP_XP [Toc] [Back]
This widget will be used by an application that
utilizes the X Print Service to perform print
document format generation and print job
submission.
- 5 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
DtNselectFileProc [Toc] [Back]
This resource specifies the procedure that will be used in
response to activation of the Select File button. The
default value for this resource is a pointer to a procedure
which will invoke an XmFileSelectionBox dialog to select a
file name.
If the user cancels the file selection dialog, no
DtPrintSetupBox components will be updated. If the user
selects a file name, the file name will be set as the value
for the DtNfileName resource. This procedure communicates
the newly selected file name to DtPrintSetupBox by setting
the DtNfileName resource.
Since the default procedure presents a File Selection
Dialog, the resource is actually set after the procedure
returns, due to the asynchronous nature of widgets and
callbacks. The return value of this procedure is ignored by
DtPrintSetupBox. However, it is recommended that the
procedure follow the conventions presented in the
"DtPrintSetupProc" section to ensure future compatibility.
DtNselectPrinterProc [Toc] [Back]
This resource specifies the procedure that will be used in
response to activation of the Select Printer button. If the
value of the DtNprintSetupMode resource is DtPRINT_SETUP_XP,
a default procedure that invokes a DtPrinterSelectionDialog
is used. If the user cancels the printer selection dialog no
DtPrintSetupBox components will be updated. If the user
selects a printer, the printer will be set as the value for
the DtNprinterName resource.
This procedure communicates the newly selected printer name
to DtPrintSetupBox by setting the DtNprinterName resource.
Since the default procedure presents a Printer Selection
Dialog, the resource is actually set after the procedure
returns, due to the asynchronous nature of widgets and
callbacks.
If the value of the DtNprintSetupMode resource is anything
other than DtPRINT_SETUP_XP, the default value of
DtNselectPrinterProc is NULL.
The return value of this procedure is ignored by
DtPrintSetupBox. However, it is recommended that the
procedure follow the conventions presented in the
"DtPrintSetupProc" section to ensure future compatibility.
DtNsetAttributesCallback [Toc] [Back]
Specifies the list of callbacks that is called whenever
DtPrintSetupBox is about to perform an operation that will
- 6 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
utilize X Print Service attributes. This callback list will
only be called if the value of the DtNprintSetupMode
resource is DtPRINT_SETUP_XP.
This callback is intended to be used by applications that
utilize X Print Service attributes directly. This callback
provides these applications with a chance to set attributes
whenever a subsequent DtPrintSetupBox operation will utilize
the current set of attributes (for example, prior to calling
the DtNprintCallback list).
The callback reason is DtPRINT_CR_SET_ATTRIBUTES.
DtNsetupProc [Toc] [Back]
This resource specifies the procedure that will be used in
response to activation of the Setup button. If the value of
the DtNprintSetupMode resource is DtPRINT_SETUP_XP, a
default procedure is provided that will call XpNotifyPDM in
order to present the setup dialog provided by the Print
Dialog Manager.
If the value of the DtNprintSetupMode resource is anything
other than DtPRINT_SETUP_XP, the default value of
DtNsetupProc is NULL.
This procedure typically updates X Print Service attributes,
and does not set any DtPrintSetupBox resources.
The return value of this procedure is ignored by
DtPrintSetupBox. However, it is recommended that the
procedure follow the conventions presented in the
"DtPrintSetupProc" section to ensure future compatibility.
DtNverifyPrinterProc [Toc] [Back]
This resource specifies the procedure that will be used to
verify the current value of the DtNprinterName resource
before any operation requiring a valid printer is performed.
If the current value of the DtNprinterName resource is NULL,
this procedure will set a default printer as the value of
the DtNprinterName resource.
If this procedure provides a default printer name, or a
fully qualified X printer name, it should communicate the
new name to DtPrintSetupBox by setting the DtNprinterName
resource before returning.
If the value of the DtNprintSetupMode resource is
DtPRINT_SETUP_XP, a default procedure will be set as the
value of the DtNverifyPrinterProc resource. This default
procedure will verify the X printer, and establish a print
display connection and print context for the printer. The
- 7 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
procedure communicates the new print display and context to
DtPrintSetupBox by updating the print_data->print_display
and print_data->print_context elements of the callback
structure prior to returning.
If the value of the DtNprintSetupMode resource is anything
other than DtPRINT_SETUP_XP, the default value of
DtNverifyPrinterProc is NULL.
If the value of the DtNverifyPrinterProc resource is NULL,
the printer name is always considered valid.
If this procedure determines the printer name is valid or
sets a valid printer name (and X printer connection
information), it should return DtPRINT_SUCCESS. If the
printer name is invalid or no valid default can be
determined, this procedure should return DtPRINT_FAILURE.
DtNworkAreaLocation [Toc] [Back]
Indicates how to position work area children within the
DtPrintSetupBox. Possible values are:
DtWORK_AREA_BOTTOM [Toc] [Back]
A single work area child may be added, and will be
placed below the generic controls and above the
pushbuttons at the bottom of the window. A managed
separator will be placed between the work area and
the generic controls. This is the default.
DtWORK_AREA_TOP [Toc] [Back]
A single work area child may be added, and will be
placed above the generic controls and below the
top of the window. A managed separator will be
placed between the work area and the generic
controls.
DtWORK_AREA_TOP_AND_BOTTOM [Toc] [Back]
Two work area children may be added. The first
work area created will become the top work area,
positioned with a separator as for
DtWORK_AREA_TOP, and the second will become the
bottom work area, positioned with a separator as
for DtWORK_AREA_BOTTOM.
The effect of adding more work area children than indicated
by the value of DtNworkAreaLocation is undefined.
Inherited Resources [Toc] [Back]
DtPrintSetupBox inherits resources from the XmBulletinBoard,
XmManager, Constraint, Composite, and Core superclasses. Refer to the
reference pages for these superclasses for inherited resources and
- 8 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
their descriptions.
Callback And Procedure Resource Information [Toc] [Back]
DtPrintSetupBox defines a new structure, DtPrintSetupData, that is
passed to callbacks and procedure resource values. For callbacks only,
DtPrintSetupBox defines a new callback structure,
DtPrintSetupCallbackStruct. Not all fields in these structures are
valid for all callbacks and procedures. For callbacks, the application
must first look at the reason field, and use only the structure
members that are valid for that particular reason. For each
procedure, the application should only reference structure members
that are defined as valid for that particular procedure. The
DtPrintSetupData and DtPrintSetupCallbackStruct structures are defined
as follows:
typedef struct
{
String printer_name;
Display *print_display;
XPContext print_context;
XtEnum destination;
String dest_info;
} DtPrintSetupData;
printer_name
Contains the current value of the DtNprinterName resource.
print_display
If DtNprintSetupMode is DtPRINT_SETUP_XP, print_display
contains a pointer to the Display structure for the current
X Printer. For other values of DtNprintSetupMode, this field
is NULL.
print_context
If DtNprintSetupMode is DtPRINT_SETUP_XP, print_context
contains the print context handle for the current X Printer.
For other values of DtNprintSetupMode, this field is NULL.
destination
Contains the current value of the DtNprintDestination
resource.
dest_info Additional information about the print destination as
indicated by the destination field.
If destination is DtPRINT_TO_FILE, this field contains the
name of the file to print to.
If destination is DtPRINT_TO_PRINTER, this field contains
the name of the currently selected printer as determined by
the current value of the XpPrinterNameMode resource. This is
- 9 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
useful for display within dialogs displaying print status,
etc. because it is the printer name as presented to the user
in DtPrintSetupBox.
typedef struct
{
int reason;
XEvent *event;
DtPrintSetupData *print_data;
} DtPrintSetupCallbackStruct;
reason Indicates why the callback was invoked.
event Points to the XEvent that triggered the callback. It can be
NULL.
print_data
Points to a DtPrintSetupData structure containing additional
callback information.
The following table indicates for each callback reason which
DtPrintSetupCallbackStruct and DtPrintSetupData members are valid.
Reason Valid Fields
DtPRINT_CR_CANCEL reason, event
DtPRINT_CR_CLOSE_PRINT_DISPLAY reason, printer_name,
print_display, print_context
DtPRINT_CR_GET_ATTRIBUTES reason, event, printer_name,
print_display, print_context
DtPRINT_CR_GET_STATIC_ATTRIBUTES reason, event, printer_name,
print_display, print_context
DtPRINT_CR_PRINT reason, event, printer_name,
print_display, print_context,
destination, dest_info
DtPRINT_CR_SET_ATTRIBUTES reason, event, printer_name,
print_display, print_context
The following table indicates for each procedure resource which
DtPrintSetupData members are valid:
Procedure Valid Fields
DtNprinterInfoProc printer_name, print_display,
print_context
DtNselectFileProc destination, dest_info
DtNsetupProc printer_name, print_display,
print_context
DtNverifyPrinterProc printer_name, print_display,
print_context
Translations [Toc] [Back]
DtPrintSetupBox inherits translations from XmBulletinBoard.
- 10 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
Virtual Bindings [Toc] [Back]
The bindings for virtual keys are implementation-dependent. For
information about bindings for virtual buttons and keys, see
VirtualBindings(3).
EXTERNAL INFLUENCES [Toc] [Back]
This section specifies application resources and environment variables
that will influence the behavior of DtPrintSetupBox. If a given
resource is defined, it will have precedence over the corresponding
environment variable. There is no corresponding environment variable
for the XpPrinterNameMode resource.
XRM Application Resources [Toc] [Back]
XpPrinter This variable defines the default destination X Printer
Specifier for DtPrintSetupBox. If the specifier is just a
printerName, the host:display portion of the specifier is
obtained by checking if the X Server to which the client
application is connected is an X Print Server managing
printerName. Otherwise, the first server in the
XpServerList or XPSERVERLIST that manages the printer will
be used. If the :display number is omitted, :0 is assumed.
Example:
Dtmail*XpPrinter: laser_1@callisto:6
XpPrinterNameMode [Toc] [Back]
This resource indicates how an X Printer Specifier shall be
shown in the Printer Name combo box text. Valid values for
this resource are:
DtSHORT_NAME [Toc] [Back]
Display only the printerName portion of the X
Printer Specifier.
DtMEDIUM_NAME [Toc] [Back]
Display the printer name as a combination of the
printerName and the host portions of the X Printer
Specifier with an intervening "at" (@) symbol. For
example:
printer@host
DtLONG_NAME [Toc] [Back]
Display the fully qualified X Printer Specifier.
For example:
printer@host:6
If this resource is not specified, DtPrintSetupBox will
assume a default of DtSHORT_NAME.
- 11 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
XpPrinterList [Toc] [Back]
This resource defines the initial set of X Printer
Specifiers shown in the Printer Name combo box list.
The resource value is a whitespace-delimited list of
partially or fully specified X Printer Specifiers. When the
user selects a specifier from this list, if the specifier is
just a printerName, the host:display portion of the
specifier is obtained by checking if the X Server to which
the client application is connected is an X Print Server
managing printerName. Otherwise the first server in the
XpServerList or XPSERVERLIST that manages the printer will
be used. If the: display number is omitted, :0 is assumed.
Example:
*xpPrinterList: laser laser2@argon:3 laser7@xenon
XpServerList [Toc] [Back]
This resource contains a list of X Print Server specifiers.
Each entry in the list is of the form host:display, and is
separated from other entries by whitespace. DtPrintSetupBox
uses this list to fully qualify partial X Printer Specifiers
consisting of just the printerName.
Example:
*.XpServerList: hanz:6 franz:6 ahnold:6
Environment Variables [Toc] [Back]
PDPRINTER, LPDEST, PRINTER
If the XPRINTER, environment variable and the XpPrinter
resource are not specified, DtPrintSetupBox will check the
environment variables (in order) PDPRINTER, LPDEST, and
PRINTER to obtain' a printerName that can be used to
generate an X Printer Specifier to use for the default X
Printer shown in the Printer Name combo box text field. The
host:display portion of the specifier is obtained by
checking if the X Server to which the client application is
connected is an X Print Server managing printerName. If not,
the list of X Print Servers specified in the XpServerList or
XPSERVERLIST is queried, until the first X Printer with a
matching printerName is found.
XPRINTER The specification of the XPRINTER environment variable is
the same as the XpPrinter resource.
XPRINTERLIST [Toc] [Back]
The specification of the XPRINTERLIST environment variable
is the same as the the XpPrinterList resource.
- 12 - Formatted: January 24, 2005
DtPrintSetupBox(library call) DtPrintSetupBox(library call)
XPSERVERLIST [Toc] [Back]
The specification of the XPSERVERLIST environment variable
is the same as the the XpServerList resource.
EXAMPLES [Toc] [Back]
Sample code can be found in the /proj/cde/examples/dtprint directory.
SEE ALSO [Toc] [Back]
DtPrintSetupProc(3), DtCreatePrintSetupDialog(3), DtPrintSetupProc(3),
DtPrinterSelectionDialog(3)
- 13 - Formatted: January 24, 2005 [ Back ] |
