Chapter 4. Printer Graphical Options Panel
Prev |  | Next

## Chapter 4. Printer Graphical Options Panel

This chapter discusses the graphical options panel, which visually showcases a printer's features.

The following major topics are discussed in this chapter:

- “Graphical Options Panel Layout”

- “Options Handling”

- “Graphical Options Panel Development”

- “Graphical Options Panel Naming”

- “Graphical Options Panel Installation”

- “Invocation by the PrintBox Widget”

- “Standalone Invocation for Testing”

- “Termination by the PrintBox Widget”

## Overview

Impressario provides the PrintBox widget for submitting print jobs from Motif applications. This widget is contained in the library `libprintui(3X)`. The PrintBox widget is used by the `glp` or `PrintPanel` command and a number of other applications to provide their printing capability. In addition to providing graphical selection of System V print job submission options, the widget provides the graphical options panel for graphical selection of printer-specific options.

A graphical options panel allows the printer-driver developer to showcase the unique features of a printer in an intuitive graphical panel. The graphical options panel program is invoked by the PrintBox widget in applications, by the end user via `glp`, or by the Printer Manager in the System Toolchest. The Graphical Options Panel Specification located in the `/usr/impressario/doc` directory provides the information necessary to create and integrate a graphical options panel. Graphical options panels are standalone executable programs that are stored in a standard directory known to the Impressario printing tools. Therefore, the graphical options panels are automatically available to users of Impressario printing tools. The rules for developing a graphical options panel are straightforward and do not require any interprocess communication or similar complex procedures. In fact, we strongly discourage any network dependencies because not every Impressario printer is on a network.

## Graphical Options Panel Layout

A graphical options panel most often consists of a single window. This window usually contains two sections, an options section and an action area. We strongly recommend that you keep options panels simple to avoid both complex code and complicated documentation.

The options section contains all printer-specific option controls. This area is often divided into groups of option controls, where each group represents a specific input file type. Most options sections contain controls for text files, bitmap image files, and PostScript files. The options section also contains a general options section. Because there are often a large number of controls in the options section, you should use a scrolled window to limit the graphical options panel window to a reasonable size. Figure 4-1 shows an example of a graphical printer options panel.

Figure 4-1. Graphical Printer Options Panel

The action area is located at the bottom of the graphical options panel window and consists of a number of push buttons. The first three are required:

OK |  | Output the option string to standard out and terminate the program.
Apply |  | Output the option string to standard out; do not terminate the program.
Cancel |  | Terminate the program without any option string output.
Help |  | Provide printer-specific options help.

Group buttons together on the right side of the action area. The width of all buttons should be equal. The leftmost button should be OK followed by Apply, Cancel, and Help. Place any additional buttons between the Apply and Cancel buttons. Note that the supplied template makes this happen automatically.

## Options Handling

If printer-specific options have been passed to the graphical options panel on the command line, the program must interpret these options and initialize its options-section controls to reflect the command-line options. Options not recognized by the graphical options panel must be preserved and prepended to the output option string.

When the OK or Apply button is activated, the graphical options panel program must form a valid System V printer option string based on its GUI settings, and print this string to its standard output.

## Graphical Options Panel Development

The directory `/usr/impressario/src/gui_models` contains example source code for a graphical options panel. Begin with this code and add your printer-specific options. Do not start from scratch! You will waste valuable development time and may create inconsistencies. Benefit from others' experience and begin with the template.

Create the graphical options panel with the OSF/Motif UI™ toolkit. Starting with Impressario 1.2, your graphical model file can have its own application resource file. While the resource file can be given any name, Silicon Graphics recommends that the name represent the printer model name and have its first letter capitalized. For example, the application resource file for the HP LaserJet graphical model file is called `LaserJetPJL`. The name chosen for the resource file must be specified in the `gui_class.h` header file and must also be specified in the printer model file as the value of the GUI_CLASS variable. Your installation media must place the resource file in the directory `/usr/lib/X11/app-defaults`.

To match the look and feel of the `PrintPanel` program (`glp`) and other graphical options panels, the application resource file should include the following resources:

*useSchemes: | all
*schemeFileList: | SgiSpec
*sgiMode: | True

To facilitate localization of the options panel for international customers, all label strings and messages should be placed in the application resource file rather than being hard-coded into the program.

The graphical model files must consist of a single executable program and its application resource file. The model files are restricted to these because the printer installation tools install only an executable and its resource file during network printer installation.

## Graphical Options Panel Naming

The graphical options panel must be given the exact same name as its printer's model file, followed by the suffix .`gui`. For example, if the printer model file for an HP DeskJet 500C printer is called `deskjet_model`, then the graphical options panel must be given the name `deskjet_model.gui`. If the graphical options panel is given a name that differs from the model filename, it will not be installed by the printer install tools when a new printer is installed on a system.

## Graphical Options Panel Installation

All graphical options panel programs must be installed by your installation media in the directory `/var/spool/lp/gui_model` or `/var/spool/lp/gui_model/ELF`[1] . These directories are where the printer installation software searches for the programs. COFF executables must be installed in the directory `/var/spool/lp/gui_model`. The executable should be owned by lp and should be a member of the group lp. The file permissions of the executable should be set to 0755.

| Note: You must always supply an ELF executable. COFF executables are not supported in IRIX 6.2, and are necessary only if you wish to support IRIX 4.0.5 systems.

## Invocation by the PrintBox Widget

The graphical options panel is invoked by the PrintBox widget or the Printer Manager. The graphical options panel is always invoked with the command-line arguments listed in Table 4-1. Note that the options are almost identical to those passed to your spooler model file.

Table 4-1. Command-Line Arguments

Argument | Description
--- | ---
argv[0] | Printer name
argv[1] | User name
argv[2] | Filename(s) string
argv[3] | Printer-specific option string (optional)
argv[4-n] | Xt options (optional)

Any `Xt` options may be specified as argv[4] or greater. If there are no printer-specific options for argv[3], the empty string ("") is passed as argv[3]. If no filenames are specified, the empty string is also passed as argv[2].

## Standalone Invocation for Testing

To test a graphical options panel during development, it may be run as a standalone executable from the UNIX command line. Invoke the graphical options panel by entering

    [executable name] [any valid user name] ""

For example, if the executable program is called laser`jetPJL_model.gui`, and “joe” is a valid user name on the system, then the program can be executed from the command line by entering:

    laserjetPJL_model.gui joe ""

When debugging, it often helps to invoke the graphical options panel from the shell and repeatedly test the options string that is generated when the Apply button is pushed. Once the options string is properly generated, test for proper parsing of the input options by invoking the graphical options panel with various options strings, especially those output by your panel. Be especially careful that all widgets are set properly when, upon startup, the panel is passed a string that sets options to non-default values.

## Termination by the PrintBox Widget

Applications terminate the graphical options panel using a SIGHUP signal. The graphical options panel should exit promptly upon receipt of this signal.

## Additional Information

For additional information, please read the online specification found in `/usr/impressario/doc/gui_model.spec`.

The template was intended to make the creation of these panels easier. If you find the process difficult, please check the template documentation and the convenience routines in the support files. There may be a solution already provided.

[1] All programs compiled on systems running IRIX 5.0 or later are ELF executables.

Prev | Table of Contents | Next
Chapter 3. Printer Model Files |  | Chapter 5. Printing Libraries