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:

Main dialog buttons

Main dialog titles

Paper pane

Graphics pane

Margins pane

Defaults pane

Printers pane

Print Order pane

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.

---

If you press the Apply button, the contents of the print context might change, no matter which button you ultimately use to close the dialog. If PtPrintPropSelect() returns Pt_PSP_CANCEL, your application shouldn't assume that nothing changed.

---

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

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