RISCOS.com
www.riscos.com Technical Support:
Toolbox

Print Dialogue box class

A Print dialogue object is used to allow the user to set a number of print options (e.g. number of pages, number of copies etc), and then to request that a document be printed given these options.

User interface

When a Print dialogue is created, it has the following components:

a set of buttons and writable fields giving a page range to print (optional)
a number range giving the number of copies to print (optional)
a radio group consisting of two buttons, indicating whether the printing is to be done Upright or Sideways (optional).
an action button Save which saves the current print options (optional)
an action button Set Up... which brings up a dialogue box allowing further print options to be set (optional)
an action button Cancel which closes the dialogue box without printing
a default action button Print which causes a print operation to take place using these print options
an option button Draft indicating that draft standard printing is to be used
a number range giving a percentage scale factor to apply during printing (optional).

Pressing Escape cancels the dialogue (as well as clicking on the Cancel button).

The title bar of the dialogue box displays the name of the currently selected printer or 'Unknown printer' if there is no such printer.

Application Program Interface

All processing of the dialogue box is handled by the Print module, and the client is informed of any user actions via Toolbox events (PrintDbox_Print, PrintDbox_SetUp, PrintDbox_DialogueCompleted and PrintDbox_Save).

Attributes

A Print Dialogue object has the following attributes which are specified in its object template and can be manipulated at run-time by the client application:

Attributes	Description
flags word	Bit	Meaning
	0	when set, this bit indicates that a PrintDbox_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this object.
	1	when set, this bit indicates that a PrintDbox_DialogueCompleted event should be raised when the Print Dialogue object has been removed from the screen.
	2	when set, this bit indicates generate PrintDbox_SetUpAboutToBeShown event before the underlying SetUp object is shown
	3	when set, dialogue box has the All/From/To Page Range options
	4	when set, dialogue box has the Copies writable field
	5	when set, dialogue box has the Scale writable field
	6	when set, dialogue box has the Orientation options (i.e. Upright and Sideways)
	7	when set, dialogue box has Save action button
	8	when set, dialogue box has Set Up ... action button
	9	when set, dialogue box has Draft option button
	10	when set, dialogue box has From/to set from All/From/to
	11	when set, dialogue box has Sideways (and not Upright) selected
	12	when set, dialogue box has Draft selected
from	initial value to put in the From writable field
to	initial value to put in the to writable field
copies	initial value to put in the Copies number range
scale	initial value to put in the Scale number range
further options	name of the template for a Window object to be displayed when Setup... is clicked
window	name of the template for an alternative window to use instead of the default one (0 means use default)

Manipulating a Print Dialogue object

Creating and deleting a Print Dialogue object

A Print Dialogue object is created using SWI Toolbox_CreateObject.

When a Print Dialogue object is created, the following attached object (see Attached objects) will be created (if specified):

further options.

A Print Dialogue object is deleted using SWI Toolbox_DeleteObject. If it has any attached objects (see above), these are also deleted, unless the non-recursive bit is set for this SWI.

The setting of the non-recursive delete bit means that the SetUp dialogue box will not be deleted.

Showing a Print Dialogue object

When a Print Dialogue object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:

Show type	Position
0 (default)	the underlying window is shown at the last place shown on the screen, or the coordinates given in its template, if it has not already been shown
1 (full spec)	R3 + 0	visible area minimum x coordinate
	R3 + 4	visible area minimum y coordinate
	R3 + 8	visible area maximum x coordinate
	R3 + 12	visible area maximum y coordinate
	R3 + 16	scroll x offset relative to work area
	R3 + 20	scroll y offset relative to work area
	R3 + 24	Wimp window handle of window to open behind
		-1	means top of stack
		-2	means bottom of stack
		-3	means the window behind the Wimp's backwindow
2 (topleft)	R3 + 0	visible area minimum x coordinate
2 (topleft)	R3 + 4	visible area minimum y coordinate

Before the Print Dialogue box is shown

When the client (or the Toolbox) calls Toolbox_ShowObject on a Print Dialogue object, a PrintDbox_AboutToBeShown Toolbox event is raised before the dialogue box becomes visible on the screen (if the appropriate flags bit is set).

This allows the client to set up the contents of the dialogue box appropriately.

Getting and setting printing options

A Print dialogue box contains many fields which are either options or writable fields. These are:

page range
number of copies
scale factor
orientation
draft.

Each of these components can be read and set dynamically using the following methods:

PrintDbox_SetPageRange
PrintDbox_GetPageRange
PrintDbox_SetCopies
PrintDbox_GetCopies
PrintDbox_SetScale
PrintDbox_GetScale
PrintDbox_SetOrientation
PrintDbox_GetOrientation
PrintDbox_SetDraft
PrintDbox_GetDraft

Responding to action button clicks

When the user clicks a particular action button (or presses Return or Escape), the client receives one of the following Toolbox events:

PrintDbox_Save if Save has been clicked.
PrintDbox_Print if Print has been clicked or Return has been pressed.
PrintDbox_SetUp if Set Up... has been clicked and there is no specified Window to be shown.

Getting the Print Dialogue's title

The string appearing in the Print Dialogue's title bar is the currently selected printer (or 'unknown printer' if there is no such printer). This string can be read using the PrintDbox_GetTitle method.

If the Print Dialogue is persistent, and the currently selected Printer is changed, then the Title Bar will change to reflect this.

Getting the id of the underlying Window object

The object id of the Window used to implement a Print Dialogue can be obtained using the PrintDbox_GetWindowID method.

The SetUp Window

It is possible to specify the name of a template to be used for showing an object when the SetUp... button is pressed. This object is shown in its default place persistently.

Print Dialogue Methods

The following methods are all invoked by calling SWI Toolbox_ObjectMiscOp with:

R0	holding a flags word
R1	being a Print Dialogue object id
R2	being the method code which distinguishes this method
R3-R9	potentially holding method-specific data

PrintDbox_GetWindowID 0

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	0

On exit

Window object id for this Print object

Use

This method returns the id of the underlying Window object used to implement this Print object.

C veneer

extern _kernel_oserror *printdbox_get_window_id ( unsigned int flags,
                                                  ObjectId printdbox,
                                                  ObjectId *window
                                                );

PrintDbox_SetPageRange 1

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	1
R3	=	start of page range
R4	=	end of page range

On exit

R1-R9 preserved

Use

This method is used to set the page range for a Print Dialogue.
A 'start' value of -1 means 'All'.

C veneer

extern _kernel_oserror *printdbox_set_page_range ( unsigned int flags,
                                                   ObjectId printdbox,
                                                   int start,
                                                   int end
                                                 );

PrintDbox_GetPageRange 2

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	2

On exit

R0	=	start of page range (a 'start' value of -1 means 'All')
R1	=	end of page range

Use

This method is used to return the page range for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_get_page_range ( unsigned int flags,
                                                   ObjectId printdbox,
                                                   int *start,
                                                   int *end
                                                 );

PrintDbox_SetCopies 3

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	3
R3	=	number of copies

On exit

R1-R9 preserved

Use

This method is used to set the number of copies field for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_set_copies ( unsigned int flags,
                                               ObjectId printdbox,
                                               int copies
                                             );

PrintDbox_GetCopies 4

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	4

On exit

number of copies to be printed

Use

This method returns the value of the Copies field for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_get_copies ( unsigned int flags,
                                               ObjectId printdbox,
                                               int *copies
                                             );

PrintDbox_SetScale 5

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	5
R3	=	percentage value to scale by

On exit

R1-R9 preserved

Use

This method is used to set the scale factor for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_set_scale ( unsigned int flags,
                                              ObjectId printdbox,
                                              int scale_factor
                                            );

PrintDbox_GetScale 6

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	6

On exit

percentage scale factor

Use

This method returns the value of the scale factor for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_get_scale ( unsigned int flags,
                                              ObjectId printdbox,
                                              int *scale_factor
                                            );

PrintDbox_SetOrientation 7

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	7
R3	=	non-zero means Sideways, 0 means Upright

On exit

R1-R9 preserved

Use

This method is used to set the orientation for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_set_orientation ( unsigned int flags,
                                                    ObjectId printdbox,
                                                    int orientation
                                                  );

PrintDbox_GetOrientation 8

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	8

On exit

orientation non-zero means Sideways, 0 means Upright

Use

This method returns the orientation for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_get_orientation ( unsigned int flags,
                                                    ObjectId printdbox,
                                                    int *orientation
                                                  );

PrintDbox_GetTitle 9

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	9
R3	=	pointer to buffer to hold title string
R4	=	size of buffer to hold title string

On exit

size of buffer required to hold title string (if R3 was 0)
else buffer pointed at by R3 holds title string
R4 holds number of bytes written to buffer

Use

This method returns the current string used in a Print object's title bar.

C veneer

extern _kernel_oserror *printdbox_get_title ( unsigned int flags,
                                              ObjectId printdbox,
                                              char *buffer,
                                              int buff_size,
                                              int *nbytes
                                            );

PrintDbox_SetDraft 10

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	10
R3	=	non-zero means Draft, 0 means 'non-draft'

On exit

R1-R9 preserved

Use

This method is used to set whether draft printing is used for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_set_draft ( unsigned int flags,
                                              ObjectId printdbox,
                                              int draft
                                            );

PrintDbox_GetDraft 11

On entry

R0	=	flags
R1	=	Print Dbox object id
R2	=	11

On exit

draft non-zero means Draft, 0 means 'non-draft'

Use

This method returns whether draft printing is used for a Print Dialogue.

C veneer

extern _kernel_oserror *printdbox_get_draft ( unsigned int flags,
                                              ObjectId printdbox,
                                              int *draft
                                            );

Print Dialogue events

The Print module generates the following Toolbox events:

PrintDbox_AboutToBeShown (0x82b00)

Block

+ 8	0x82b00
+ 12	flags (as passed in to Toolbox_ShowObject)
+ 16	value which will be passed in R2 to ToolBox_ShowObject
+ 20...	block which will be passed in R3 to ToolBox_ShowObject for the underlying dialogue box

Use

This Toolbox event is raised just before the Print module is going to show its underlying Window object.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                show_type;
  union
  {
    TopLeft               pos;
    WindowShowObjectBlock full;
  } info;
} PrintDboxAboutToBeShownEvent;

PrintDbox_DialogueCompleted (0x82b01)

Block

+ 8	0x82b01
+ 12	flags

Use

This Toolbox event is raised after the Print object has been hidden, either by a Cancel click, or after a successful print, or by the user clicking outside the dialogue box (if it is transient) or pressing Escape. It allows the client to tidy up its own state associated with this dialogue.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} PrintDboxDialogueCompletedEvent;

PrintDbox_SetUpAboutToBeShown (0x82b02)

Block

+ 8	0x82b02
+ 16	object id of the object about to be shown (note that the 'self' id in the id block will be for the Print Dialogue object, not the object which will be shown)
+ 20	value which will be passed in R2 to ToolBox_ShowObject
+ 24...	block which will be passed in R3 to ToolBox_ShowObject for the underlying dialogue box

Use

This Toolbox event is raised just before the Print module is going to show its underlying Window object.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  ObjectId           object_id;
  int                show_type;
  union
  {
    TopLeft               pos;
    WindowShowObjectBlock full;
  } info;
} PrintDboxSetUpAboutToBeShownEvent;

PrintDbox_Save (0x82b03)

Block

+ 8	0x82b03
+ 12	flags bit 0 set means print Sideways (default is Upright) bit 1 set means print Draft (default is non-draft)
+ 16	page range start (-1 means All)
+ 20	page range end
+ 24	number of copies
+ 28	value to scale by (a percentage)

Use

This Toolbox event is raised when the user clicks on the Save button. The client should save any options associated with this Print Dialogue (usually in a document which is being edited).

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                start_page;
  int                finish_page;
  int                copies;
  int                scale_factor;
} PrintDboxSaveEvent;

PrintDbox_SetUp (0x82b04)

Block

+ 8

0x82b04

Use

This Toolbox event is raised when the user clicks on the Set Up... button, if there is no dialogue box associated with this button.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} PrintDboxSetUpEvent;

PrintDbox_Print (0x82b05)

Block

+ 8	0x82b05
+ 12	flags bit 0 set means print Sideways (default is Upright) bit 1 set means print Draft (default is non-draft)
+ 16	page range start (-1 means All)
+ 20	page range end
+ 24	number of copies
+ 28	value to scale by (a percentage)

Use

This Toolbox event is raised when the user clicks on the Print button or presses Return.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
  int                start_page;
  int                finish_page;
  int                copies;
  int                scale_factor;
} PrintDboxPrintEvent;

Print Dialogue templates

The layout of a Print template is shown below. Fields which have types MsgReference and StringReference are those which will require relocation when they are loaded from a resource file. If the template is being constructed in memory, then these fields should be real pointers (i.e. they do not require relocation).

For more details on relocation, see Resource File Formats.

Field	Size in bytes	Type
flags	4	word
from	4	word
to	4	word
copies	4	word
scale	4	word
further_options	4	StringReference
window	4	StringReference

Underlying window template

The Window object used to implement a Print dialogue, has the following characteristics. These must be reproduced if the Window is replaced by a client-specified alternative Window template:

Title bar must be indirected.

Gadgets

Component ids are derived by adding to 0x82b000.

Component id	Details
0	action button (Print)	this should be marked as the 'default' action button
1	action button (Save)	this should be marked as a 'local' action button
2	action button (Cancel)	this should be marked as the 'cancel' action button
3	radio button (From/To)	this is selected to allow page ranges to be printed
4	radio button (All)	selected for all page print
5 & 6	writable field (From) writable field (To)	these are used by the user to enter a page range
7	number range (Copies)	these are used by the user to enter the number of copies
8	number range (Scale)	these are used by the user to specify a scale
9	radio button (Upright)	selected for portrait
10	radio button (Sideways)	selected for landscape
11	option button (Draft)	selected for draft
12	action button (SetUp...)	this is used to bring up a Window of further options
13	label (To)
14	label (Copies)
15	label (Scale)
16	label (%)

Print Dialogue Wimp event handling

Wimp event	Action
Mouse Click	on Print button then raise PrintDbox_Print Toolbox event on Cancel button then raise PrintDbox_DialogueCompleted Toolbox event on Save button then raise PrintDbox_Save Toolbox event on Setup... then raise a PrintDbox_SetUpAboutToBeShown, then show the specified Window object, or raise a PrintDbox_SetUp Toolbox event if there is no such Window on All (pages) and All is off then set All on set From off and shade the writable fields on From and From is off then set From on set All to off and unshade the writable fields on Copies or Scale up/down arrows then increment/decrement values on Upright then set Upright on and Sideways off on Sideways then set Sideways on and Upright off on Draft then toggle state of option button
Key Pressed	if key is Return raise PrintDbox_Print Toolbox event if key is Escape act as if Cancel has been clicked
User Message	Window_HasBeenHidden Toolbox event hide the dialogue box, and raise a PrintDbox_DialogueCompleted Toolbox event Message_HelpRequest return help message to sender

Wimp event

Action

Mouse Click

on Print button then raise PrintDbox_Print Toolbox event

on Cancel button then raise

PrintDbox_DialogueCompleted Toolbox event

on Save button then raise PrintDbox_Save Toolbox event

on Setup... then raise a

PrintDbox_SetUpAboutToBeShown,
then show the specified Window object, or raise a
PrintDbox_SetUp Toolbox event if there is no such
Window

on All (pages) and All is off then

set All on
set From off
and shade the writable fields

on From and From is off then

set From on
set All to off
and unshade the writable fields

on Copies or Scale up/down arrows then

increment/decrement values

on Upright then set Upright on and Sideways off

on Sideways then set Sideways on and Upright off

on Draft then toggle state of option button

Key Pressed

if key is Return raise PrintDbox_Print Toolbox event

if key is Escape act as if Cancel has been clicked

User Message

Window_HasBeenHidden Toolbox event
hide the dialogue box, and raise a PrintDbox_DialogueCompleted Toolbox event

Message_HelpRequest
return help message to sender

www.riscos.com Technical Support:Toolbox

Print Dialogue box class

User interface

Application Program Interface

Attributes

Manipulating a Print Dialogue object

Creating and deleting a Print Dialogue object

Showing a Print Dialogue object

Before the Print Dialogue box is shown

Getting and setting printing options

Responding to action button clicks

Getting the Print Dialogue's title

Getting the id of the underlying Window object

The SetUp Window

Print Dialogue Methods

PrintDbox_GetWindowID 0

On entry

On exit

Use

C veneer

PrintDbox_SetPageRange 1

On entry

On exit

Use

C veneer

PrintDbox_GetPageRange 2

On entry

On exit

Use

C veneer

PrintDbox_SetCopies 3

On entry

On exit

Use

C veneer

PrintDbox_GetCopies 4

On entry

On exit

Use

C veneer

PrintDbox_SetScale 5

On entry

On exit

Use

C veneer

PrintDbox_GetScale 6

On entry

On exit

Use

C veneer

PrintDbox_SetOrientation 7

On entry

On exit

Use

C veneer

PrintDbox_GetOrientation 8

On entry

On exit

Use

C veneer

PrintDbox_GetTitle 9

On entry

On exit

Use

C veneer

PrintDbox_SetDraft 10

On entry

On exit

Use

C veneer

PrintDbox_GetDraft 11

On entry

On exit

Use

C veneer

Print Dialogue events

PrintDbox_AboutToBeShown (0x82b00)

Block

Use

C data type

www.riscos.com Technical Support:
Toolbox