DTPRINTSETUPBOX(3)

💖 NAME 💖

DtPrintSetupBox — application print setup widget. (library call, bestie ✨)

✨ SYNOPSIS ✨

Caret#include &<Dt/Print.h>

🦋 DESCRIPTION 🦋

okay so DtPrintSetupBox is a widget that is typically the initial window used to set various options prior to printing from an application. It 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 🌸

DtPrintSetupBox creates the descendants shown in the following list. An application can use XtNameToWidget to gain access to the named descendant. In addition, a user or an application can use the descendant name when specifying resource values. 💖

• BottomWorkAreaSeparator — class: XmSeparatorGadget; identity: separator above the bottom work area.
• ButtonSeparator — class: XmSeparatorGadget; identity: separator above the pushbuttons.
• Cancel — class: XmPushButtonGadget; identity: Cancel button.
• Copies — class: XmSimpleSpinBox; identity: SpinBox containing the number of copies.
• CopiesLabel — class: XmLabelGadget; identity: label for the Copies SpinBox.
• DescriptionLabel — class: XmLabelGadget; identity: label for the printer description.
• FileName — class: XmTextField; identity: file name field.
• FileNameCheckBox — class: XmRowColumn; identity: check box (includes label) for file name field.
• Help — class: XmPushButtonGadget; identity: Help button.
• Info — class: XmPushButtonGadget; identity: printer information button.
• Name — class: XmComboBox; identity: printer name.
• NameLabel — class: XmLabelGadget; identity: label for the printer name field.
• Print — class: XmPushButtonGadget; identity: Print button.
• SelectFile — class: XmPushButtonGadget; identity: Select File button.
• SelectPrinter — class: XmPushButtonGadget; identity: Select Printer button.
• Setup — class: XmPushButtonGadget; identity: Setup button.
• TopWorkAreaSeparator — class: XmSeparatorGadget; identity: separator below the top work area.

👑 Classes 👑

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 🎀

The following list is the whole resource table, and yes, every single one is here, bestie 💖

• DtNcancelCallback — class/type: DtCCancelCallback/XtCallbackList; access: C; default value: NULL.
• DtNclosePrintDisplayCallback — class/type: DtCCloseDisplayCallback/XtCallbackList; access: C; default value: NULL.
• DtNcopies — class/type: DtCCopies/int; access: CSG; default value: 1.
• DtNdescription — class/type: DtCDescription/XmString; access: CSG; default value: dynamic.
• DtNfileName — class/type: DtCPrintToFileName/String; access: CSG; default value: NULL.
• DtNgetAttributesCallback — class/type: DtCGetAttributesCallback/XtCallbackList; access: C; default value: NULL.
• DtNminimizeButtons — class/type: DtCminimizeButtons/Boolean; access: CSG; default value: False.
• DtNprintCallback — class/type: DtCPrintCallback/XtCallbackList; access: C; default value: NULL.
• DtNprintDestination — class/type: DtCPrintDestination/XtEnum; access: CSG; default value: DtPRINT_TO_PRINTER.
• DtNprinterInfoProc — class/type: DtCPrinterInfoProc/DtPrintSetupProc; access: CSG; default value: dynamic.
• DtNprinterName — class/type: DtCPrinter/String; access: CSG; default value: dynamic.
• DtNprintSetupMode — class/type: DtCPrintSetupMode/XtEnum; access: CG; default value: DtPRINT_SETUP_XP.
• DtNselectFileProc — class/type: DtCSelectFileProc/DtPrintSetupProc; access: CSG; default value: default procedure.
• DtNselectPrinterProc — class/type: DtCSelectPrinterProc/DtPrintSetupProc; access: CSG; default value: dynamic.
• DtNsetAttributesCallback — class/type: DtCSetAttributesCallback/XtCallbackList; access: C; default value: NULL.
• DtNsetupProc — class/type: DtCSetupProc/DtPrintSetupProc; access: CSG; default value: dynamic.
• DtNsetupProc — class/type: DtCSetupProc/DtPrintSetupProc; access: CSG; default value: dynamic. (yes, it is listed twice in the original table, so here it is twice 🙈)
• DtNverifyPrinterProc — class/type: DtCVerifyPrinterProc/DtPrintSetupProc; access: CSG; default value: dynamic.
• DtNworkAreaLocation — class/type: DtCworkAreaLocation/XtEnum; access: CSG; default value: DtWORK_AREA_BOTTOM.

The DtPrintSetupBox resources are defined as follows:

• DtNcancelCallback — specifies the list of callbacks that is called when the Cancel button is activated. The callback reason is DtPRINT_CR_CANCEL. 💅
• DtNclosePrintDisplayCallback — 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 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 — a description of the printer as provided by the system administrator.
• DtNfileName — specifies the name of the destination file. Setting this resource will update the value of the File Name text field.
• DtNgetAttributesCallback — 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 — 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 establishing a new X printer connection. Additionally, subsequent immediate action to be taken by DtPrintSetupBox will result in the DtNsetAttributesCallback list being called followed by either the DtNprintCallback list or the DtNsetupProc. If the application were to 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 — the application should update all static and dynamic controls. This reason is set in response to DtPrintSetupBox 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 — 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 — 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 — indicates where the print output should be directed. Valid values for this resource are:
  • DtPRINT_TO_FILE — 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 — 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 💅

Okay bestie, so this resource specifies the procedure that will be used to present printer information when the Printer Information button gets activated. The printer selection dialog presented by the default DtNselectPrinterProc will also 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 🌸

This one is literally 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 ✨

This resource 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 — This widget will be used by an application that performs its own print document format generation and print job submission.
• DtPRINT_SETUP_XP — This widget will be used by an application that utilizes the X Print Service to perform print document format generation and print job submission.

🎀 DtNselectFileProc 🎀

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. Slay, file picker behavior. 📁

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 🦋

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. Ngl, async callbacks really be doing the most. 😭

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 🍓

This resource specifies the list of callbacks that is called whenever DtPrintSetupBox is about to perform an operation that will 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. Iconic. 👑

⭐ DtNsetupProc ⭐

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 🔥

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 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. Vibe check: success or failure, no in-between. 💀

🌈 DtNworkAreaLocation 🌈

Indicates how to position work area children within the DtPrintSetupBox. Possible values are:

• DtWORK_AREA_BOTTOM — 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 — 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 — 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. Bestie, do not test this unless you enjoy chaos. 😭

🌱 Inherited Resources 🌱

DtPrintSetupBox inherits resources from the XmBulletinBoard, XmManager, Constraint, Composite, and Core superclasses. Refer to the reference pages for these superclasses for inherited resources and their descriptions. Family tree behavior, fr fr. 🫶

💖 Callback And Procedure Resource Information 💖

Okay so DtPrintSetupBox defines a whole new structure, DtPrintSetupData, and it gets passed to callbacks and procedure resource values. For callbacks only, it also defines a callback structure, DtPrintSetupCallbackStruct. And bestie, not every field in these structures is valid for every callback or procedure. For callbacks, the app has to look at the reason field first and use only the structure members valid for that particular reason. For each procedure, the app should only reference structure members that are defined as valid for that particular procedure. The DtPrintSetupData and DtPrintSetupCallbackStruct structures are defined like this:

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, this holds 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, this holds 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 info 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 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.

So for each callback reason, here are the valid members of DtPrintSetupCallbackStruct / DtPrintSetupData — no guessing, bestie:

• DtPRINT_CR_CANCEL — valid fields: reason, event.
• DtPRINT_CR_CLOSE_PRINT_DISPLAY — valid fields: reason, printer_name, print_display, print_context.
• DtPRINT_CR_GET_ATTRIBUTES — valid fields: reason, event, printer_name, print_display, print_context.
• DtPRINT_CR_GET_STATIC_ATTRIBUTES — valid fields: reason, event, printer_name, print_display, print_context.
• DtPRINT_CR_PRINT — valid fields: reason, event, printer_name, print_display, print_context, destination, dest_info.
• DtPRINT_CR_SET_ATTRIBUTES — valid fields: reason, event, printer_name, print_display, print_context.

And for each procedure resource, these are the valid DtPrintSetupData members:

• DtNprinterInfoProc — valid fields: printer_name, print_display, print_context.
• DtNselectFileProc — valid fields: destination, dest_info.
• DtNsetupProc — valid fields: printer_name, print_display, print_context.
• DtNverifyPrinterProc — valid fields: printer_name, print_display, print_context.

🎀 Translations 🎀

DtPrintSetupBox inherits translations from XmBulletinBoard. Slay, inherited behavior.

🪄 Virtual Bindings 🪄

The bindings for virtual keys are implementation-dependent. For info about bindings for virtual buttons and keys, see VirtualBindings(3).

🌍 EXTERNAL INFLUENCES 🌍

This section specifies application resources and environment variables that will influence the behavior of DtPrintSetupBox. If a given resource is defined, it has precedence over the corresponding environment variable. And there is no corresponding environment variable for the XpPrinterNameMode resource. Noted. 💅

🗂️ XRM Application Resources 🗂️

• 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 — this resource indicates how an X Printer Specifier shall be shown in the Printer Name combo box text. Valid values are:
  • DtSHORT_NAME — display only the printerName portion of the X Printer Specifier.
  • DtMEDIUM_NAME — 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 — display the fully qualified X Printer Specifier. For example:

printer@host:6

If this resource is not specified, DtPrintSetupBox assumes a default of DtSHORT_NAME.

• XpPrinterList — 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 — 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 🌿

• PDPRINTER, LPDEST, PRINTER — if the XPRINTER environment variable and the XpPrinter resource are not specified, DtPrintSetupBox checks 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 — the specification of the XPRINTERLIST environment variable is the same as the XpPrinterList resource.
• XPSERVERLIST — the specification of the XPSERVERLIST environment variable is the same as the XpServerList resource.

💻 EXAMPLES 💻

Sample code can be found in the /proj/cde/examples/dtprint directory. Go look, bestie ✨

👀 SEE ALSO 👀

• DtPrintSetupProc(3)
• DtCreatePrintSetupDialog(3)
• DtPrintSetupProc(3)
• DtPrinterSelectionDialog(3)

---

And that's the whole page, bestie 💖 — signing off from the DtPrintSetupBox(library call) page. The footer metadata situation is just that source tag, with no separate version or date printed here, so that's all the footer tea we've got. Periodt. 💅✨