|
www.riscos.com Technical Support: |
A DCS dialogue object is used to allow the user to save data which has been modified, usually before a document window is closed.
The dialogue box which appears on the screen has a number of components:
The user sees the following behaviour (note that a click with the adjust button is treated in the same way as a select click):
When a DCS object is created, it has a number of optional components:
Just before the DCS dialogue box is shown on the screen, the client is delivered a DCS_AboutToBeShown Toolbox event if enabled by the flags word.
Once the dialogue box is displayed on the screen, the DCS module handles events for it, and raises a number of Toolbox Events to indicate what choice the user has made. These are DCS_Discard, DCS_Cancel and DCS_Save respectively. If the dialogue is closed, then the client receives a DCS_DialogueCompleted event if enabled by the appropriate bit in the flags word (see below).
A DCS 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 | Bit | Meaning |
| 0 | when set, this bit indicates that a DCS_AboutTobeShown event should be raised when SWI Toolbox_ShowObject is called for this object. | |
| 1 | when set, this bit indicates that a DCS_DialogueCompleted event should be raised when the DCS object has been removed from the screen. | |
| DCS title | an alternative string for the title bar other than the client's name (0 means use application name) | |
| max title length | this gives the maximum length in bytes of title text which will be used for this object | |
| message | an alternative message to use in the DCS dialogue box (other than 'This file has been modified') | |
| max message length | this gives the maximum length in bytes of the message which will be used for this object | |
| window | an alternative window template to use instead of the default one (o means use default) | |
A DCS object is created using SWI Toolbox_CreateObject.
When this object is created it has no attached objects (see Attached objects).
A DCS object is deleted using SWI Toolbox_DeleteObject.
The setting of the non-recursive delete bit does not have a meaning for DCS objects.
When a DCS object is displayed on the screen using SWI Toolbox_ShowObject it has the following behaviour:
| Show type | Position | |||
|---|---|---|---|---|
| 0 | (default) | close to the pointer | ||
| 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 DCS dialogue object is created it has a default message warning the user that he has unsaved data which will be lost if he closes the window.
This can be set and read dynamically using the DCS_SetMessage and DCS_GetMessage methods (described on DCS_SetMessage 1).
The window object id of the Window object used to implement the DCS Dialogue can be obtained by using the DCS_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 DCS Dialogue object id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | DCS object id |
| R2 | = | 0 |
| R0 | = | Window object id for this DCS object |
This method returns the id of the underlying Window object used to implement this DCS object.
extern _kernel_oserror *dcs_get_window_id ( unsigned int flags,
ObjectId dcs,
ObjectId *window
);
| R0 | = | flags |
| R1 | = | DCS object id |
| R2 | = | 1 |
| R3 | = | pointer to buffer holding new message (Ctrl-terminated) |
| R1-R9 preserved |
This method sets the message used in the DCS dialogue's window.
extern _kernel_oserror *dcs_set_message ( unsigned int flags,
ObjectId dcs,
char *message
);
| R0 | = | flags |
| R1 | = | DCS 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 DCS object.
extern _kernel_oserror *dcs_get_message ( unsigned int flags,
ObjectId dcs,
char *buffer,
int buff_size,
int *nbytes
);
| R0 | = | flags |
| R1 | = | DCS 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 DCS dialogue.
extern _kernel_oserror *dcs_set_title ( unsigned int flags,
ObjectId dcs,
char *title
);
| R0 | = | flags |
| R1 | = | DCS 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 DCS dialogue's title bar.
extern _kernel_oserror *dcs_get_title ( unsigned int flags,
ObjectId dcs,
char *buffer,
int buff_size,
int *nbytes
);
| + 8 | 0x82a80 |
| + 12 | value which will be passed in R0 to Toolbox_ShowObject (i.e. show flags, such as 'Show as menu') |
| + 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 DCS module is going to show its underlying Window object.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft pos;
WindowShowObjectBlock full;
} info;
} DCSAboutToBeShownEvent;
| + 8 | 0x82a81 |
This Toolbox event is raised when the user clicks on the Discard button.
typedef struct
{
ToolboxEventHeader hdr;
} DCSDiscardEvent;
| + 8 | 0x82a82 |
This Toolbox event is raised when the user clicks on the Save Button or presses Return. It is then the client's responsibility to either save the data directly to file, or to display a SaveAs Dialogue object.
typedef struct
{
ToolboxEventHeader hdr;
} DCSSaveEvent;
| + 8 | 0x82a83 |
This Toolbox event is raised after the DCS object has been hidden, either by a Cancel click, a Save click or a Discard click, or by the user clicking outside the dialogue box (if opened transiently) or pressing Escape. It allows the client to tidy up its own state associated with this dialogue.
typedef struct
{
ToolboxEventHeader hdr;
} DCSDialogueCompletedEvent;
| + 8 | 0x82a84 |
This Toolbox event is raised when the user clicks on the Cancel button or presses the Escape key.
typedef struct
{
ToolboxEventHeader hdr;
} DCSCancelEvent;
The layout of a DCS 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 DCS 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 0x82a800
| Component id | Details |
|---|---|
| 0 | button gadget |
| 1 | action button (Discard) |
| 2 | action button (Cancel) must be marked as a 'Cancel' action button |
| 3 | action button (Save) must be marked as a 'Default' action button |
| Wimp event | Action |
|---|---|
| Mouse Click | on Discard button raise DCS_Discard Toolbox event, then a DCS_DialogueCompleted Toolbox event*
on Cancel button raise DCS_Cancel Toolbox event, then a DCS_DialogueCompleted Toolbox event* on Save button raise DCS_Save Toolbox event, then a DCS_DialogueCompleted Toolbox event* |
| Key Pressed | on Return raise DCS_Save Toolbox event, then a DCS_DialogueCompleted Toolbox event*
on Escape then act as if Cancel had been clicked. |
* if enabled
Note that if opened transiently, DCS_DialogueCompleted may be raised without any of DCS_Cancel, DCS_Discard or DCS_Save being raised. This could arise from the user clicking on the backdrop or opening a menu.