www.riscos.com Technical Support: |
|
A Prog Info Dialogue has the following information held in its dialogue box:
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.
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) |
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.
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 |
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.
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:
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 |
R0 | = | flags |
R1 | = | Prog Info object id |
R2 | = | 0 |
R0 | = | Window object id for this Prog Info object |
This method returns the id of the underlying Window object used to implement this Prog Info object.
extern _kernel_oserror *proginfo_get_window_id ( unsigned int flags, ObjectId proginfo, ObjectId *window );
R0 | = | flags |
R1 | = | Prog Info object id |
R2 | = | 1 |
R3 | = | pointer to buffer holding version string (Ctrl-terminated) |
R1-R9 preserved |
This method sets the version string used in the Prog Info Dialogue's Window.
extern _kernel_oserror *proginfo_set_version ( unsigned int flags, ObjectId proginfo, char *version_string );
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 |
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 |
This method returns the current version string used in a Prog Info object.
extern _kernel_oserror *proginfo_get_version ( unsigned int flags, ObjectId proginfo, char *buffer, int buff_size, int *nbytes );
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 |
R1-R9 preserved |
This method sets the licence type used in the Prog Info Dialogue's Window.
extern _kernel_oserror *proginfo_set_licence_type ( unsigned int flags, ObjectId proginfo, int licence_type );
R0 | = | flags |
R1 | = | Prog Info object id |
R2 | = | 4 |
R0 | = | licence type of application
0 public domain 1 single user 2 single machine 3 site 4 network 5 authority |
This method returns the current licence type used in a Prog Info object.
extern _kernel_oserror *proginfo_get_licence_type ( unsigned int flags, ObjectId proginfo, int *licence_type );
R0 | = | flags |
R1 | = | Prog Info object id |
R2 | = | 5 |
R3 | = | pointer to text string to use |
R1-R9 preserved |
This method sets the text which is to be used in the title bar of the given Prog Info dialogue.
extern _kernel_oserror *proginfo_set_title ( unsigned int flags, ObjectId proginfo, char *title );
R0 | = | flags 6 |
R3 | = | pointer to buffer to return the text in (or 0) |
R4 | = | size of buffer |
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 |
This method returns the text string used in a Prog Info dialogue's title bar.
extern _kernel_oserror *proginfo_get_title ( unsigned int flags, ObjectId proginfo, char *buffer, int buff_size, int *nbytes );
The Prog Info module generates the following Toolbox events:
+ 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 |
This Toolbox event is raised just before the Prog Info module is going to show its underlying Window object.
typedef struct { ToolboxEventHeader hdr; int show_type; union { TopLeft pos; WindowShowObjectBlock full; } info; } ProgInfoAboutToBeShownEvent;
+ 8 | 0x82b41 |
+ 12 | flags
(none yet defined) |
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.
typedef struct { ToolboxEventHeader hdr; } ProgInfoDialogueCompletedEvent;
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 |
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.
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) |
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 |