RISCOS.com

www.riscos.com Technical Support:
Toolbox

 


Quit Dialogue box class


A Quit Dialogue box is used by the client application when the user attempts to quit the application or shut down the computer whilst there is still unsaved data.

User interface

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:

QUIT-2.GIF

  • a title bar (by default containing the name of the application, i.e. the message whose tag is '_TaskName')
  • a message stating (by default) that there is unsaved data
  • two action buttons:
    • a Cancel button (default action button)
    • a Quit button.

The user sees the following behaviour:

  • if they click on Quit, the application quits
  • if they click on Cancel (or press Return or Escape), the application returns to normal operation.

Application Program Interface

When a Quit object is created, it has a number of optional components:

  • an alternative title bar string instead of the client's name
  • an alternative message to use in the dialogue box
  • the name of an alternative template to use for the underlying Window object.

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).

Attributes

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
Manipulating a Quit object
Creating and deleting a Quit object

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.

Showing a Quit object

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
Changing the Quit Dialogue's message

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.

Getting the id of the underlying window for a Quit Dialogue

The Window object id of the Window object used to implement the Quit Dialogue can be obtained by using the Quit_GetWindowID method.

Quit methods

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
Quit_GetWindowID 0
On entry
R0 = flags
R1 = Quit object id
R2 = 0
On exit
R0 = Window object id for this Quit object
Use

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

C veneer

extern _kernel_oserror *quit_get_window_id ( unsigned int flags,
                                             ObjectId quit,
                                             ObjectId *window
                                           );

Quit_SetMessage 1
On entry
R0 = flags
R1 = Quit object id
R2 = 1
R3 = pointer to buffer holding new message (Ctrl-terminated)
On exit
R1-R9 preserved
Use

This method sets the message used in the Quit Dialogue's Window.

C veneer

extern _kernel_oserror *quit_set_message ( unsigned int flags,
                                           ObjectId quit,
                                           char *message
                                         );

Quit_GetMessage 2
On entry
R0 = flags
R1 = Quit object id
R2 = 2
R3 = pointer to buffer to hold message
R4 = size of buffer to hold message
On exit
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
Use

This method returns the current message used in a Quit object.

C veneer

extern _kernel_oserror *quit_get_message ( unsigned int flags,
                                           ObjectId quit,
                                           char *buffer,
                                           int buff_size,
                                           int *nbytes
                                         );

Quit_SetTitle 3
On entry
R0 = flags
R1 = Quit object id
R2 = 3
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 Quit dialogue.

C veneer

extern _kernel_oserror *quit_set_title ( unsigned int flags,
                                         ObjectId quit,
                                         char *title
                                       );

Quit_GetTitle 4
On entry
R0 = flags
R1 = Quit object id
R2 = 4
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 Quit dialogue's title bar.

C veneer

extern _kernel_oserror *quit_get_title ( unsigned int flags,
                                         ObjectId quit,
                                         char *buffer,
                                         int buff_size,
                                         int *nbytes
                                       );

Quit events

The Quit module generates the following Toolbox events:

Quit_AboutToBeShown (0x82a90)
Block
+ 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
Use

This Toolbox event is raised just before the Quit 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;

} QuitAboutToBeShownEvent;

Quit_Quit (0x82a91)
Block
+ 8 0x82a91
Use

This Toolbox event is raised when the user clicks on the Quit Button.

C data type

typedef struct
{
  ToolboxEventHeader hdr;

} QuitQuitEvent;

Quit_DialogueCompleted (0x82a92)
Block
+ 8 0x82a92
+ 12 flags
(none yet defined)
Use

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.

C data type

typedef struct
{
  ToolboxEventHeader hdr;

} QuitDialogueCompletedEvent;

Quit_Cancel (0x82a93)
Block
+ 8 0x82a93
Use

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

C data type

typedef struct
{
  ToolboxEventHeader hdr;

} QuitCancelEvent;

Quit templates

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
Underlying window template

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.

Gadgets

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

Quit Wimp event handling

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

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015