www.riscos.com Technical Support: Toolbox

Prog Info Dialogue box class

A Prog Info dialogue object is used to display information about the client application in a dialogue box.

User interface

A Prog Info Dialogue has the following information held in its dialogue box:

• the name of the application (taken from the message whose tag is '_TaskName')
• the purpose of the application
• the author of the application
• the licence type of the application (optional)
• the version of the application.

All of the above are display field gadgets.

The last of these fields can be set dynamically by the client at run-time.

This gives the simplest of Prog Info Dialogue boxes. If the client wishes to use further fields, or wishes to customise the dialogue box, then there is a facility for including the name of a different template to use rather than the standard Prog Info one.

Application Program Interface

Attributes

A Prog Info 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 ProgInfo_AboutTobeShown event should be raised when SWI Toolbox_ShowObject is called for this object.
	1	when set, this bit indicates that a ProgInfo_DialogueCompleted event should be raised when the ProgInfo object has been removed from the screen.
	2	when set, include a licence type field in the dialogue box
title	alternative title bar string to 'About this program' (0 means use default title)
max title length	this gives the maximum length in bytes of title text which will be used for this Prog Info dialogue's title bar
purpose	a string giving the purpose of this application
author	a string giving the author of this application
licence type	an integer giving the licence type of the application
version	a string giving version information for this application
window	the name of an alternative window template to use instead of the default one (0 means use default)

Manipulating a Prog Info object

Creating and deleting a Prog Info object

A Prog Info object is created using SWI Toolbox_CreateObject.

When this object is created it has no attached objects (see Attached objects).

A Prog Info object is deleted using SWI Toolbox_DeleteObject.

The setting of the non-recursive delete bit does not have a meaning for Prog Info objects.

Showing a Prog Info object

When a Prog Info 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'sbackwindow
2 (topleft)	R3 + 0	visible area minimum x coordinate
	R3 + 4	visible area minimum y coordinate

Changing the version string

Most of the fields in a Prog Info object will remain unchanged at run-time.

The client may wish to set and read the version string field at run-time. This is done using the ProgInfo_SetVersion/ProgInfo_GetVersion methods.

Setting the licence type

If the client wishes to set and read the licence type displayed in the Prog Info dialogue box, then it can use the ProgInfo_SetLicenceType and ProgInfo_GetLicenceType methods (described on ProgInfo_SetLicenceType 3).

Licence types are one of:

• public domain
• single user
• single machine
• site
• network
• authority.

Prog Info methods

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

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

ProgInfo_GetWindowID 0

On entry

R0	=	flags
R1	=	Prog Info object id
R2	=	0

On exit

R0

=

Window object id for this Prog Info object

Use

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

C veneer

extern _kernel_oserror *proginfo_get_window_id ( unsigned int flags,
                                                 ObjectId proginfo,
                                                 ObjectId *window
                                               );

ProgInfo_SetVersion 1

On entry

R0	=	flags
R1	=	Prog Info object id
R2	=	1
R3	=	pointer to buffer holding version string (Ctrl-terminated)

On exit

R1-R9 preserved

Use

This method sets the version string used in the Prog Info Dialogue's Window.

C veneer

extern _kernel_oserror *proginfo_set_version ( unsigned int flags,
                                               ObjectId proginfo,
                                               char *version_string
                                             );

ProgInfo_GetVersion 2

On entry

R0	=	flags
R1	=	Prog Info object id
R2	=	2
R3	=	pointer to buffer to hold version string
R4	=	size of buffer to hold version string

On exit

R4

=

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

Use

This method returns the current version string used in a Prog Info object.

C veneer

extern _kernel_oserror *proginfo_get_version ( unsigned int flags,
                                               ObjectId proginfo,
                                               char *buffer,
                                               int buff_size,
                                               int *nbytes
                                             );

ProgInfo_SetLicenceType 3

On entry

R0	=	flags
R1	=	Prog Info object id
R2	=	3
R3	=	licence type 0 public domain 1 single user 2 single machine 3 site 4 network 5 authority

On exit

R1-R9 preserved

Use

This method sets the licence type used in the Prog Info Dialogue's Window.

C veneer

extern _kernel_oserror *proginfo_set_licence_type ( unsigned int flags,
                                                    ObjectId proginfo,
                                                    int licence_type
                                                  );

ProgInfo_GetLicenceType 4

On entry

R0	=	flags
R1	=	Prog Info object id
R2	=	4

On exit

R0

=

licence type of application 0 public domain 1 single user 2 single machine 3 site 4 network 5 authority

Use

This method returns the current licence type used in a Prog Info object.

C veneer

extern _kernel_oserror *proginfo_get_licence_type ( unsigned int flags,
                                                    ObjectId proginfo,
                                                    int *licence_type
                                                  );

ProgInfo_SetTitle 5

On entry

R0	=	flags
R1	=	Prog Info object id
R2	=	5
R3	=	pointer to text string to use

On exit

R1-R9 preserved

Use

This method sets the text which is to be used in the title bar of the given Prog Info dialogue.

C veneer

extern _kernel_oserror *proginfo_set_title ( unsigned int flags,
                                             ObjectId proginfo,
                                             char *title
                                           );

ProgInfo_GetTitle 6

On entry

R0	=	flags 6
R3	=	pointer to buffer to return the text in (or 0)
R4	=	size of buffer

On exit

R4

=

size of buffer required to hold the text (if R3 was 0) else Buffer pointed to by R3 contains title text R4 holds number of bytes written to buffer

Use

This method returns the text string used in a Prog Info dialogue's title bar.

C veneer

extern _kernel_oserror *proginfo_get_title ( unsigned int flags,
                                             ObjectId proginfo,
                                             char *buffer,
                                             int buff_size,
                                             int *nbytes
                                           );

Prog Info events

The Prog Info module generates the following Toolbox events:

ProgInfo_AboutToBeShown (0x82b40)

Block

+ 8	0x82b40
+ 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 Prog Info 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;
} ProgInfoAboutToBeShownEvent;

ProgInfo_DialogueCompleted (0x82b41)

Block

+ 8	0x82b41
+ 12	flags (none yet defined)

Use

This Toolbox event is raised after the Prog Info object has been hidden, either by the user clicking outside the dialogue box or pressing Escape. It allows the client to tidy up its own state associated with this dialogue.

C data type

typedef struct
{
  ToolboxEventHeader hdr;
} ProgInfoDialogueCompletedEvent;

Prog Info templates

The layout of a Prog Info 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
title	4	MsgReference
max-title	4	word
purpose	4	MsgReference
author	4	MsgReference
licence_type	4	word
version	4	MsgReference
window	4	StringReference

Underlying window template

The Window object used to implement a Prog Info 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 0x82b400.

Component id	Details
0	display field (Name of Application)
1	display field (Purpose)
2	display field (Author)
3	display field (Licence Type)
4	display field (Version)
5	label (name)
6	label (purpose)
7	label (author)
8	label (licence)
9	label (version)

Prog Info Wimp event handling

Wimp event	Action
Open Window	request show the dialogue box
Key Click	if Escape then cancel dialogue
User Message	Message_MenusDeleted hide the dialogue box