This chapter discusses the graphical options panel that visually showcases a printer's features.
The major topics discussed in this chapter are:
The Impressario PrintBox widget is provided for submitting print jobs from a Motif application. This widget is contained in the library libprintui(3X). The PrintBox widget is used by glp (PrintPanel) and a number of other applications to provide their printing capability. In addition to providing graphical selection of System V print job submittal options, PrintBox provides a mechanism for graphical selection of printer-specific options.[1] This mechanism is the graphical options panel.
A graphical options panel allows the printer vendor and 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 (PrintPanel), and by the Printer Manager. 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. They 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 as not every Impressario printer is on a network.
A graphical options panel almost always consists of a single window. This window usually contains two main sections, an options section and an action area. We strongly recommend that vendors 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 keep the graphical options panel window to a reasonable size. Figure 5-1 shows an example of a 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:
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.
 | Note: Do not include the action area inside the scrollable options area. The action buttons must be available to the user at all times. |
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. Those 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 (stdout).
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 create consistency issues. Benefit from our experience and at least begin with the template.
Create the graphical options panel with the OSF/Motif UI[tm] 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, it is highly recommended 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 LaserJet. 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. The resource file must be installed by your installation media 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 file must consist of a single executable program and its application resource file. The graphical model files are restricted to a single executable and resource file because the printer installation tools install only these two files during network printer installation.
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 file name, it will not be installed by the printer install tools when a new printer is installed on a system.
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. These directories are where the printer installation software searches for the programs. COFF-executables must be installed in the directory /usr/spool/lp/gui_model, and ELF-executables must be installed in /usr/spool/lp/gui_model/ELF.[2] 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.
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 5-1 . Note that the options are almost identical to those passed to your spooler model file.
Table 5-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) |
Note that 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].
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 deskjet_model.gui, and "joe" is a valid user name on the system, then the program can be executed from the command line by typing:
deskjet500_model.gui joe "" |
While debugging, it is often helpful to invoke the graphical options panel from the shell, repeatedly testing the options string that is generated when the Apply button is pushed. Once the options string is properly generated, test for proper performance of input options parsing by invoking the graphical options panel with various options strings, especially the strings output by your panel. Be especially sure that all widgets are set properly upon panel startup when passed a string that sets options to non-default values.
Applications will terminate the graphical options panel using a SIGHUP signal. The graphical options panel should exit promptly upon receipt of this signal.
For additional information, please read the online specification found in /usr/impressario/doc/gui_model.spec.
These panels should be very easy to create when you start from the template. If you find them difficult, take another look at the template documentation and the convenience routines in the support files. You may have overlooked something we have already solved for you.