| Previous | Contents | Index |
This implementation allows the application to determine the initial color for the Color Display subwidget. If you set the DXmNorigRedValue, DXmNorigGreenValue, and DXmNorigBlueValue values through UIL, you must hard-code RGB values to match the background of the main window widget. |
This chapter describes how to use the print widget in an application
program. It includes a description of the print widget resources and
also provides both UIL and Toolkit print widget programming examples.
7.1 Overview of the Print Widget
The print widget is a modeless widget that provides DECwindows applications with a fast, convenient method of printing one or more files in multiple formats. As an application programmer, you need only to create an instance of the print widget, using either the UIL DXmPrintDialog object type or the Toolkit DXmCreatePrintDialog routine, and then submit the print job by calling the DXmPrintWgtPrintJob routine.
Your application can also use the UIL DXmPrintBox object type or the DXmCreatePrintBox routine to create a print widget without a dialog shell. You might want to use this object type or routine to add a print widget inside one of your existing widgets.
Because the print widget uses a graphical interface to prompt users for print options, users do not have to know the syntax of the UNIX print command or the OpenVMS PRINT command to print files. In addition, because the print widget uses OpenVMS logical names to determine and display the available print queues, users do not have to know about the print queues on a given OpenVMS system.
The print widget lets application programmers determine how the print widget first appears to the user. The user can then change the resources based on the file and print queue being used.
The print widget does not format or convert files for printing; your application must provide the files in a suitable print format. |
This section describes a walk-through of how to use the print widget in an application. Subsequent sections describe this process in more detail.
To use the print widget, an application performs the following steps:
The main print widget dialog box contains the primary print options. When the Options... push button is selected, a secondary dialog box containing additional printer options is fetched and managed. The options shown on the secondary dialog box are tailored to the kind of file being submitted and the printer on which it is to be printed.
The components of the print widget created by the OpenVMS DECburger example program are shown in Figure 7-1 and Figure 7-2.
Figure 7-1 Print Widget Main Dialog Box
Figure 7-2 Print Widget Secondary Dialog Box
The print widget supports the callbacks described in Table 7-1.
| Callback | Description |
|---|---|
| XmNokCallback |
The user clicked on the OK push button in the print widget main dialog
box. If the DXmNunmanageOnOk resource is set, the print widget
automatically unmanages itself when the OK button in the main box is
pressed.
Your application can use the XmNokCallback callback to perform other functions, such as calling the XtGetValues routine to get and store the user's print choices, or calling DXmPrintWgtPrintJob to submit the print job. |
| XmNcancelCallback |
The user clicked on the Cancel push button in the print widget main
dialog box. If the DXmNunmanageOnCancel resource is set, the print
widget automatically unmanages itself when the Cancel button in the
main box is pressed.
Your application can use the XmNcancelCallback callback to perform other functions. |
If your application program specifies the DXmNfileNameList resource, the print widget uses the file extension, when one exists, to guess the type and the associated print format of the first file to be printed. The print widget then establishes some print defaults based on this file type. Therefore, if you use the DXmNfileNameList resource to specify a list of files, those files should all be of one type; that is, they should all be text files, or they should all be PostScript files, and so forth.
Applications that do not know the attributes of the files to be printed
should use the DXmNfileNameList resource and rely on the print widget
file-type guesser. If the print widget incorrectly guesses the format
of the file to be printed, the user can select the correct print format.
7.6 Print Widget Resources
You can specify print widget resources, described in the DECwindows Extensions to Motif manual, that define how the print widget first appears to the user. The user then has the option to modify the print options as needed.
The print widget resources contained in the main dialog box are grouped as follows:
The print widget resources contained in the secondary dialog box are grouped as follows:
The print widget gets the appropriate printer and print forms information from the operating system and creates compound strings for use in the following resources.
Your application should not attempt to set these resources. If your application needs the value of this resource, call the XtGetValues routine to obtain the value. |
Example 7-1 shows a UIL example of setting print widget resources.
| Example 7-1 Setting Print Widget Resources Through UIL |
|---|
.
.
.
object myprint_widget : DXmPrintDialog
{
arguments
{
XmNnoResize = true;
DXmNnumberCopies = 13;
DXmNpageRangeFrom = compound_string("3");
DXmNpageRangeTo = compound_string("20");
DXmNprintFormatList = compound_string_table
("PostScript(R)",
"DDIF",
"ANSI");
DXmNprintFormatCount = 3;
DXmNprintFormatChoice = compound_string("ANSI");
DXmNorientation = DXmORIENTATION_PORTRAIT;
DXmNprintAfter = compound_string("23-JUN-1990 17:30");
DXmNdeleteFile = true;
DXmNpageSize = DXmSIZE_LEDGER;
DXmNsides = DXmSIDES_SIMPLEX_ONE;
DXmNnumberUp = 0;
DXmNsheetCount = 1;
DXmNfileStartSheet = DXmFILE_SHEET_NONE;
DXmNfileEndSheet = DXmFILE_SHEET_ONE;
DXmNfileBurstSheet = DXmFILE_SHEET_ALL;
DXmNmessageLog = DXmMESSAGE_LOG_DEFAULT;
DXmNholdJob = true;
DXmNnotify = false;
DXmNsheetSize = DXmSIZE_LEGAL;
DXmNinputTray = DXmINPUT_TRAY_DEFAULT;
DXmNoutputTray = DXmOUTPUT_TRAY_DEFAULT;
DXmNjobName = compound_string("This is the Job Name");
DXmNoperatorMessage = compound_string("This is the Operator Message");
DXmNheader = true;
DXmNdoubleSpacing = true;
DXmNstartSheetComment = compound_string("This is the Start Sheet Comment");
DXmNpriority = 12;
DXmNunmanageOnOk = true;
DXmNunmanageOnCancel = true;
DXmNfileNameList = compound_string_table
("order.txt",
"test.txt");
DXmNfileNameCount = 2;
DXmNsuppressOptionsMask = DXmSUPPRESS_NUMBER_COPIES;
DXmNoptionsDialogTitle = compound_string("Secondary Dialog Box");
};
.
.
.
|
Generally, you should not set user-choice and default resources such as
DXmNprinterChoice and DXmNdefaultPrinter in the UIL file because they
vary from system to system. As described in the OSF/Motif Programmer's Guide, your
application can use application-specific default files to specify
resources that are not explicitly set in the C or UIL modules. You
might want to specify user-choice and printer default resources in a
defaults file.
7.6.1 Suppressing Print Widget Features
The print widget includes a DXmNsuppressOptionsMask argument that you can use to suppress print widget features. As an applications programmer, you might want to use the DXmNsuppressOptionsMask argument to limit the print choices available to the user.
The DXmNsuppressOptionsMask argument is a bitmask; you perform a logical OR operation on the resources you want to suppress. When using the Toolkit routines, this means that you would OR the resources in a call to XtSetArg, as shown in the following C example:
XtSetArg (arglist[ac], DXmNsuppressOptionsMask,
DXmSUPPRESS_DELETE_FILE | DXmSUPPRESS_OPERATOR_MESSAGE); ac++;
|
From UIL, you also OR the resources you want to suppress, as shown in the following UIL code fragment:
object main_print : DXmPrintDialog
{
arguments
{
XmNdialogTitle = "DECburger: Print";
DXmNoptionsDialogTitle = "DECburger: Print Options";
DXmNnumberCopies = 2;
DXmNunmanageOnOk = true;
DXmNunmanageOnCancel = true;
DXmNsuppressOptionsMask = DXmSUPPRESS_DELETE_FILE +
DXmSUPPRESS__OPERATOR_MESSAGE;
};
callbacks
{
XmNhelpCallback = procedure sens_help_proc(k_print_help);
};
};
|
The possible values for DXmNsuppressOptionsMask are as follows:
Applications can call the DXmPrintWgtAugmentList routine to define additional print formats as well as to add new options to the print widget option menus. The format of the DXmPrintWgtAugmentList routine is as follows:
unsigned long int DXmPrintWgtAugmentList(pw,list,data)
Widget pw;
int list;
caddr_t data;
|
The DXmPrintWgtAugmentList pw argument identifies the print widget. You must choose the DXmPrintWgtAugmentList list argument from the following constants:
The data argument is a data structure (passed by reference) of type DXmPrintFormatStruct or DXmPrintOptionMenuStruct. The DXmPrintFormatStruct data structure is declared as follows:
typedef struct _DXmPrintFormatStruct
{
XmString ui_string;
XmString os_string;
XmString var_string;
} DXmPrintFormatStruct;
|
The ui_string field is the label displayed in the user interface. The os_string field is passed to the operating system to identify the print format. The var_string field is the OpenVMS logical or UNIX environment variable that identifies the printer list to use for the print format.
The DXmPrintOptionMenuStruct is declared as follows:
typedef struct _DXmPrintOptionMenuStruct
{
XmString ui_string;
XmString os_string;
} DXmPrintOptionMenuStruct;
|
The ui_string field is the label displayed in the user interface and the os_string field identifies the print option to the operating system.
DXmPrintWgtAugmentList returns NULL if the request fails. If the request is successful, DXmPrintWgtAugmentList returns an integer that identifies the new element. This integer is not needed when adding print formats. However, the integer can be used in subsequent XtGetValues and XtSetValues calls on the option menus.
For example, if an application added an option to an option menu and
wanted to select the added option, it would use the returned integer in
an XtSetValues call.
7.6.2.1 Adding Print Formats
When adding print formats, use the constant DXmPRINT_FORMAT for the list argument and a variable of type DXmPrintFormatStruct for the data argument. All fields in the DXmPrintFormatStruct structure must contain valid compound strings; null compound strings are not allowed.
The DXmNpassAll resource is set to FALSE (off) and DXmNautoPagination is set to TRUE (on) if the added format is selected. If this is not the desired behavior, your application must set DXmNpassAll and DXmNautoPagination to the desired settings in the XmNokCallback callback.
Example 7-2 shows an example of adding print formats.
| Example 7-2 Adding Print Formats |
|---|
.
.
.
DXmPrintFormatStruct r_my_struct;
r_my_struct.ui_string = XmStringCreateLtoR("User String",
XmSTRING_DEFAULT_CHARSET);
r_my_struct.os_string = XmStringCreateLtoR("OS String",
XmSTRING_DEFAULT_CHARSET);
r_my_struct.var_string = XmStringCreate("Logical",
XmSTRING_DEFAULT_CHARSET);
DXmPrintWgtAugmentList(print_widget, DXmPRINT_FORMAT, &r_my_struct));
.
.
.
|
When adding options to print widget option menus, use one of the constants (other than DXmPRINT_FORMAT) for the list argument and a variable of type DXmPrintOptionMenuStruct for the data argument.
The ui_string field of the DXmPrintOptionMenuStruct data structure must contain a valid compound string. The os_string field of the DXmPrintOptionMenuStruct data structure must be either a valid compound string or NULL.
If the field is not NULL, the print widget sends the os_string field string to the operating system when the option is selected by the user.
If the field is NULL, the print widget does not send anything to the operating system if the option is selected by the user. That is, the print widget functions as though the default had been selected.
Applications can add only a limited number of options to each option menu. If an application tries to add more options than allowed, DXmPrintWgtAugmentList returns a status of 0.
Example 7-3 shows an example of adding options to the menu.
| Example 7-3 Adding Print Options |
|---|
.
.
.
DXmPrintOptionMenuStruct r_my_struct;
r_my_struct.ui_string = XmStringCreateLtoR("User String",
XmSTRING_DEFAULT_CHARSET);
r_my_struct.os_string = XmStringCreateLtoR("OS String",
XmSTRING_DEFAULT_CHARSET);
DXmPrintWgtAugmentList(print_widget, DXmPAGE_SIZE, &r_my_struct));
.
.
.
|
Example 7-4 and Example 7-5 show how the OpenVMS DECburger example program creates the print widget.
| Example 7-4 Creating the Print Widget Through UIL |
|---|
.
.
.
!The print widget object
(1)object main_print : DXmPrintDialog
{
arguments
{
XmNdialogTitle = "DECburger: Print";
DXmNoptionsDialogTitle = "DECburger: Print Options";
DXmNnumberCopies = 2;
DXmNunmanageOnOk = true;
DXmNunmanageOnCancel = true;
};
callbacks
{
XmNhelpCallback = procedure sens_help_proc(k_print_help);
};
};
.
.
.
|
| Previous | Next | Contents | Index |