|
www.riscos.com Technical Support: |
A Quit Dialogue object is used to warn the user of quitting without saving unsaved data.
The dialogue box which appears on the screen has a number of components:
The user sees the following behaviour:
When a Quit object is created, it has a number of optional components:
If the dialogue box is opened as a transient dialogue box, then it closes when the user clicks outside the box.
Just before the Quit dialogue box is shown on the screen, the client is delivered a Quit_AboutToBeShown Toolbox event (if enabled by the appropriate bit in the flags).
Once the dialogue box is displayed on the screen, the Quit module handles events for it, and raises a number of Toolbox events to indicate what choice the user has made. These are Quit_DialogueCompleted, Quit_Cancel and Quit_Quit (respectively).
A Quit 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 Quit_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this object. | ||
| 1 | when set, this bit indicates that a Quit_DialogueCompleted event should be raised when the Quit object has been removed from the screen. | ||
| title | alternative title to use instead of client's name (0 means default title) | ||
| max title length | this gives the maximum length in bytes of title text which will be used for this object | ||
| message | the string to use as the message in the Quit dialogue box (0 means default message) | ||
| max message | maximum length of string used in dialogue's message field | ||
| window | alternative window template to use instead of the default one | ||
A Quit object is created using SWI Toolbox_CreateObject.
When this object is created it has no attached objects (see Attached objects).
A Quit object is deleted using SWI Toolbox_DeleteObject.
The setting of the non-recursive delete bit does not have a meaning for Quit objects.
When a Quit 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 | |
| R3 + 4 | visible area minimum y coordinate | ||
When a Quit Dialogue object is created it has a default message warning the user that he has unsaved data which will be lost if he quits the application.
This can be set and read dynamically using the Quit_SetMessage and Quit_GetMessage methods.
The Window object id of the Window object used to implement the Quit Dialogue can be obtained by using the Quit_GetWindowID method.
The following methods are all invoked by calling SWI Toolbox_ObjectMiscOp with:
| R0 | holding a flags word (which is zero unless otherwise stated) |
| R1 | being a Quit Dialogue object id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | Quit object id |
| R2 | = | 0 |
| R0 | = | Window object id for this Quit object |
This method returns the id of the underlying Window object used to implement this Quit object.
extern _kernel_oserror *quit_get_window_id ( unsigned int flags,
ObjectId quit,
ObjectId *window
);
| R0 | = | flags |
| R1 | = | Quit object id |
| R2 | = | 1 |
| R3 | = | pointer to buffer holding new message (Ctrl-terminated) |
| R1-R9 preserved |
This method sets the message used in the Quit Dialogue's Window.
extern _kernel_oserror *quit_set_message ( unsigned int flags,
ObjectId quit,
char *message
);
| R0 | = | flags |
| R1 | = | Quit object id |
| R2 | = | 2 |
| R3 | = | pointer to buffer to hold message |
| R4 | = | size of buffer to hold message |
| R4 | = | size of buffer required to hold message (if R3 was 0)
else buffer pointed at by R3 holds message R4 holds number of bytes written to buffer |
This method returns the current message used in a Quit object.
extern _kernel_oserror *quit_get_message ( unsigned int flags,
ObjectId quit,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | Quit object id |
| R2 | = | 3 |
| 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 Quit dialogue.
extern _kernel_oserror *quit_set_title ( unsigned int flags,
ObjectId quit,
char *title
);
| R0 | = | flags |
| R1 | = | Quit object id |
| R2 | = | 4 |
| 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 Quit dialogue's title bar.
extern _kernel_oserror *quit_get_title ( unsigned int flags,
ObjectId quit,
char *buffer,
int buff_size,
int *nbytes
);
| + 8 | 0x82a90 |
| + 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 Quit module is going to show its underlying Window object.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft pos;
WindowShowObjectBlock full;
} info;
} QuitAboutToBeShownEvent;
| + 8 | 0x82a91 |
This Toolbox event is raised when the user clicks on the Quit Button.
typedef struct
{
ToolboxEventHeader hdr;
} QuitQuitEvent;
| + 8 | 0x82a92 |
| + 12 | flags
(none yet defined) |
This Toolbox event is raised after the Quit object has been hidden, either by a Cancel click, or a Quit click, or by the user clicking outside the dialogue box (if it was opened transiently) or pressing Escape. It allows the client to tidy up its own state associated with this dialogue.
typedef struct
{
ToolboxEventHeader hdr;
} QuitDialogueCompletedEvent;
| + 8 | 0x82a93 |
This Toolbox event is raised when the user clicks on the Cancel button or presses Return or Escape.
typedef struct
{
ToolboxEventHeader hdr;
} QuitCancelEvent;
The layout of a Quit 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 |
| message | 4 | MsgReference |
| max_message | 4 | word |
| window | 4 | StringReference |
The Window object used to implement a Quit 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 0x82a900:
| Component id | Details | |
|---|---|---|
| 0 | button | |
| 1 | action button (Quit) | |
| 2 | action button (Cancel) | must be marked as default and Cancel action button |
| Wimp event | Action |
|---|---|
| Mouse Click | on Quit button raise Quit_Quit and Quit_DialogueCompleted (if enabled) Toolbox event
on Cancel button raise Quit_Cancel and Quit_DialogueCompleted (if enabled) Toolbox event |
| Key Pressed | if key is Return raise Quit_Cancel Toolbox event
if key is Escape act as if Cancel had been pressed |