PpPrintSetPC()

Modify the attributes of a print context

Synopsis:

int PpPrintSetPC( PpPrintContext_t *pc, 
                  int mod_level,
                  int lock,
                  int member, 
                  void const * const data);

Description:

This function provides a mechanism to modify the attributes of a print context.

Don't modify the print context directly, as the appropriate changed bits won't be set and the application may stop working if the print context structure is redefined in future.

The arguments are as follows:

pc

The print context, created by PpPrintCreatePC()

mod_level

A value indicating the modifier of the context. The possible values are:

• PRINTER_GLOBAL-modified based on information in the global printer file (/usr/photon/print/printers)
• PRINTER_LOCAL-modified based on info in the local printer file ($HOME/.photon/print/config)
• INITIAL_PC-modified directly by the application.
• INTERACTIVE_PC-modified based on user input.

Interactive overrides initial, which overrides local, which overrides global.

The PtPrintSel widget reads the Photon printer files and modifies the provided print context with the definitions within those files. The mod_level used for the changes on the print context are dictated by which file the definitions are read from:

• Modifications made to the print context based on information in the global printer definition file, /usr/photon/print/printers, are done with a modification level of PRINTER_GLOBAL.
• Modifications made to the print context based on information in the local print file, $HOME/.photon/print/printers, are done with a modification level of PRINTER_LOCAL.
• When the user interacts with the widget in order to change the print settings, and therefore the print context, the modifications are made with a mod_level of INTERACTIVE_PC.
• When setting defaults on a print context before launching a print dialog via PtPrintSelection() or using the PtPrintSel widget, you'd normally use a modification level of INITIAL_PC. This level prevents the contents of the printer definition files from overriding your default, but still allows the user to modify those print settings interactively in the widget.

If you want to prevent the user from modifying members of the print context you have set, specify a 1 in the lock field when calling PpPrintSetPC().

lock

If nonzero, the PtPrintSel widget and properties applications won't override or allow modification of the member. Its value is locked. Locked members have their controls dimmed and inactive in the PtPrintSel widget or PtPrintSelection() dialog.

data

A pointer to the data to be assigned to the specified print context member.

member

The member of the print context to modify, as given in the table below. (For a description of the members, see the chapter on Printing in the Programmer's Guide.)

In the following table: "String" indicates a char * pointer to a null-terminated sequence of characters "char *" indicates a char * pointer to a value in the range 0x0 to 0xFF

By default, all members are 0 or NULL.

Returns:

0

Success.

-1

An error occurred. See errno for details.

Errors:

EPERM

The specified member was set by a modification level that supersedes mod_level:

• INTERACTIVE_PC supersedes
• INITIAL_PC, which supersedes
• PRINTER_LOCAL, which supersedes
• PRINTER_GLOBAL

For example,

PpPrintSetPC( pc, PRINTER_GLOBAL, 0, 
    Pp_PC_COLLATING_MODE, 
    PaperCollateABCABCABC );
// succeeds as it's the first setting
                
PpPrintSetPC( pc, PRINTER_LOCAL, 0, 
    Pp_PC_COLLATING_MODE, 
    PaperCollateAAABBBCCC );
// succeeds because PRINTER_LOCAL supersedes PRINTER_GLOBAL 

PpPrintSetPC( pc, PRINTER_LOCAL, 0, 
    Pp_PC_COLLATING_MODE, 
    PaperCollateABCABCABC );
// succeeds because changes at the same mod_level 
// are permitted. PRINTER_LOCAL == PRINTER_LOCAL

PpPrintSetPC( pc, PRINTER_GLOBAL, 0, 
    Pp_PC_COLLATING_MODE, 
    PaperCollateAAABBBCCC );
// fails with errno == EPERM because changes by
// a lower  mod_level are NOT permitted.
// PRINTER_GLOBAL < PRINTER_LOCAL
    

EACCES

The specified member couldn't be changed because it's locked.

ESRCH

An unknown member was specified.

Examples:

set_my_apps_Pp_prefs( PpPrintContext_t *pc )
    {
    char do_preview = 1, duplex = some_value;
    PpPrintSetPC( pc, INITIAL_PC, 0, 
                  Pp_PC_DO_PREVIEW, &do_preview );
    PpPrintSetPC( pc, INITIAL_PC, 0, 
                  Pp_PC_DUPLEX, &duplex );
    PpPrintSetPC( pc, INITIAL_PC, 0, 
                  Pp_PC_COMMENT, 
                  "Hey, this is a comment!" );
    // etc...
    }

Classification:

Photon

See also:

PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(), PpPrintNewPage(), PpPrintOpen(), PpPrintReleasePC(), PpPrintStart(), PpPrintStop(), PpPrintWidget()

Printing in the Programmer's Guide