---

PtPrintPropSelect()

Change the printing options for a selected printer via a modal dialog

Synopsis:

int PtPrintPropSelect(
       PtWidget_t *parent,
       char const *title,
       PtPrintPropSelectionInfo_t *info );

Arguments:

parent

A pointer to the parent widget. If this argument isn't NULL, the parent widget is blocked while the dialog is displayed.

title

The title of the print-properties dialog.

info

A pointer to a PtPrintPropSelectionInfo_t structure (see below).

Library:

ph

Description:

This function displays a dialog for modifying most of the print parameters for a particular printer:

The display is limited to parameters and values that are valid for the selected printer.

A print context is passed to the function in the info argument. This print context is modified according to the state of the dialog when you press the Apply or Done button.

PtPrintPropSelect() also lets you load and save your own preferences, which are stored in personal print configuration files.

The PtPrintSel widget calls PtPrintPropSelect() when you press the Preferences button.

PtPrintPropSelectionInfo_t structure

The PtPrintPropSelectionInfo_t structure includes at least:

PpPrintContext_t *pcontext

A pointer to a PpPrintContext_t structure that describes the print context. You must create this structure by calling PpCreatePC(). Optionally, you can initialize the print context by calling PpLoadPrinter().

PhPoint_t pos

The position of the print-properties dialog; the meaning of this position depends on the parent argument, and on whether the Pt_PSP_CENTER bit is set or cleared in the flags member:

parent	Bit	pos
NULL	Clear	Relative to screen
NULL	Set	Ignored; the dialog is centered on the screen
non-NULL	Clear	Relative to parent
non-NULL	Set	Ignored; the dialog is centered on the parent

int flags

The flag bits are:

• Pt_PSP_CENTER -- center the print-properties dialog with respect to the screen or its parent. The pos argument is ignored if you set this flag.
• Pt_PSP_NO_GRAPHICS -- don't display the Graphics pane.
• Pt_PSP_NO_MARGINS -- don't display the Margins pane.
• Pt_PSP_NO_PAPER -- don't display the Paper pane.
• Pt_PSP_NO_PRINT_ORDER -- don't display the Print Order pane.
• Pt_PSP_NO_PRINTERS -- don't display the Printers pane.
• Pt_PSP_NO_DEFAULTS -- don't display the Defaults pane.
• Pt_PSP_NO_CANCEL_BUTTON -- don't display the Cancel button in the main button pane.
• Pt_PSP_NO_APPLY_BUTTON -- don't display the Apply button in the main button pane.
• Pt_PSP_NO_DONE_BUTTON -- don't display the Done button in the main button pane.
• Pt_PSP_NO_SAVE_DFLT_BUTTON -- don't display the Save Personal Defaults button.
• Pt_PSP_NO_LOAD_DFLT_BUTTON -- don't display the Load Personal Defaults button.
• Pt_PSP_NO_LOAD_GLOBAL_DFLT_BUTTON -- don't display the Load Global Defaults button.

int num_args

The number of resources specified in the args array.

PtArg_t *args

A pointer to an array of resources for the dialog; see below.

Dialog "resources"

You can customize the print-properties dialog as if it were a widget with resources. You can set or get the values of these pseudo-resources for a PtPrintSel widget (see the Widget Reference).

All the resources are of this type:

C type	Pt type	Default
char *	String	See below

Main dialog buttons

Resource	Default
Pt_ARG_PSP_LBL_CANCEL	Cancel
Pt_ARG_PSP_LBL_APPLY	Apply
Pt_ARG_PSP_LBL_DONE	Done

Main dialog titles

Resource	Default
Pt_ARG_PSP_LBL_TITLE	Printer Properties
Pt_ARG_PSP_LBL_TITLE_PAPER	Paper
Pt_ARG_PSP_LBL_TITLE_GRAPHICS	Graphics
Pt_ARG_PSP_LBL_TITLE_MARGINS	Margins
Pt_ARG_PSP_LBL_TITLE_PRINT_ORDER	Print Order
Pt_ARG_PSP_LBL_TITLE_PRINTERS	Printers
Pt_ARG_PSP_LBL_TITLE_DFLT	Defaults

Paper pane

Resource	Default
Pt_ARG_PSP_LBL_PAPERSIZE	Paper Size
Pt_ARG_PSP_LBL_PAPERSOURCE	Paper Source
Pt_ARG_PSP_LBL_PAPERTYPE	Paper Type
Pt_ARG_PSP_LBL_ORIENTATION	Orientation
Pt_ARG_PSP_LBL_PORTRAIT	Portrait
Pt_ARG_PSP_LBL_LANDSCAPE	Landscape

Graphics pane

Resource	Default
Pt_ARG_PSP_LBL_COLORMODE	Color Mode
Pt_ARG_PSP_LBL_DITHERING	Dithering
Pt_ARG_PSP_LBL_RESOLUTION	Resolution
Pt_ARG_PSP_LBL_INTENSITY	Intensity
Pt_ARG_PSP_LBL_DARKEST	Darkest
Pt_ARG_PSP_LBL_LIGHTEST	Lightest

Margins pane

Resource	Default
Pt_ARG_PSP_LBL_TOP	Top
Pt_ARG_PSP_LBL_BOTTOM	Bottom
Pt_ARG_PSP_LBL_LEFT	Left
Pt_ARG_PSP_LBL_RIGHT	Right
Pt_ARG_PSP_LBL_UNITS	Units
Pt_ARG_PSP_LBL_INCHES	1000th inch
Pt_ARG_PSP_LBL_MILLIMETERS	100th mm

Defaults pane

Resource	Default
Pt_ARG_PSP_LBL_SAVE_DFLT	Save Personal Defaults
Pt_ARG_PSP_LBL_LOAD_DFLT	Load Personal Defaults
Pt_ARG_PSP_LBL_LOAD_GLOBAL_DFLT	Load Factory Settings

Printers pane

Resource	Default
Pt_ARG_PSP_LBL_DEFAULT_PRINTER	Default Printer
Pt_ARG_PSP_LBL_CURRENT_PRINTER	Current Printer
Pt_ARG_PSP_LBL_FONTMAP	Font Map

Print Order pane

Resource	Default
Pt_ARG_PSP_LBL_REVERSED	Print Reversed Order
Pt_ARG_PSP_LBL_DOUBLE_SIDED	Print Double Sided
Pt_ARG_PSP_LBL_COLLATED	Print Collated

Returns:

Pt_PSP_ERROR

An error occurred:

• The info argument is NULL or points to an invalid structure.
• The printcontext is NULL.
• No printers have been installed.

Pt_PSP_DONE

You pressed the Done button.

Pt_PSP_CANCEL

You pressed the Cancel button.

Examples:

/*************************************
 *
 * psp.c
 * 
 * Sample program illustrates usage of
 * PtPrintPropSelect() convenience function.
 * 
 * Compile as follows:
 *   $ qcc -lph -o psp psp.c
 * 
 * Run as follows:
 *   $ ./psp
 * 
 *************************************/

#include <stdio.h>
#include <stdlib.h>
#include <Ph.h>
#include <Pt.h>

int main(int argc, char **argv )
{
   PtWidget_t *win;
   PtPrintPropSelectionInfo_t info;
   int r;
   PhDim_t dim;
   PtArg_t args[3];

   // Set base window dimension to 250x250 pixels
   dim.w = dim.h = 250;
   PtSetArg( args, Pt_ARG_DIM, &dim, 0 );
   
   // Connect to Photon, initialize widget lib, and
   // create a base window
   if ( NULL == (win = PtAppInit( NULL, &argc,
                                  argv, 1, args )) ) {
      fprintf( stderr, "\nPtAppInit failed.\n" );
      exit( -1 );
   }

   // Realize the base window
   PtRealizeWidget( win );

   // Initialize the info structure
   memset( &info, 0x0, sizeof( PtPrintPropSelectionInfo_t ) );

   // Modify a couple of string resources
   // Change the 'Apply' button's label
   PtSetArg( &args[0], Pt_ARG_PSP_LBL_APPLY,
             "MyApply", 0 );
   // Change the 'Done' button's label
   PtSetArg( &args[1], Pt_ARG_PSP_LBL_DONE,
             "MyDone", 0 );
   // Change the 'Margins' pane
   PtSetArg( &args[2], Pt_ARG_PSP_LBL_TITLE_MARGINS,
             "MyMargins", 0 );
   
   info.num_args = 3;
   info.args = args;

   // Set up the flags to prevent the display of the
   // 'Cancel' button.
   info.flags = Pt_PSP_NO_CANCEL_BUTTON;
     
   // Create a print-context.
   if ( NULL == (info.pcontext = PpCreatePC()) ) {
      fprintf( stderr, "\nUnable to create print context.\n" );
      PtExit( -1 );
   }

   // PtPrintPropSelect() will be blocked in its own modal loop
   // until the user presses the 'Esc' key, the 'MyDone' button,
   // or closes the dialog.
   // 
   r = PtPrintPropSelect( win, "Adjust Settings", &info );
   
   // If the 'MyApply' button is pressed, then the current
   // settings in the dialog are applied to the print context. 
   
   if ( Pt_PSP_ERROR == r )
     fprintf( stderr,
       "\nPtPrintPropSelect() failed. The print context was not \
modified.\n" );

   else if ( Pt_PSP_DONE == r )
     fprintf( stderr,
       "\n'MyDone' button pressed. The print context may have \
been modified.\n" );

   else // Pt_PSP_CANCEL == r 
     fprintf( stderr,
       "\n'Esc' key pressed or dialog closed. The print \
context may have been modified.\n" );
   
   // Free the resources used by our print context.
   PpReleasePC( info.pcontext );
   
   PtMainLoop();
   return EXIT_SUCCESS;
}

Classification:

Photon

Safety:
Interrupt handler	No
Signal handler	No
Thread	No

See also:

PpCreatePC(), PpPrintContext_t, PpSetPC(), PtPrintSelect(), PtPrintSelection()

PtPrintSel in the Widget Reference

"Dialog modules" in the Working with Modules chapter, and the Printing chapter of the Photon Programmer's Guide

---