|
www.riscos.com Technical Support: |
The Scale class provides a dialogue box from which a scale factor can be chosen:
The default Scale dialogue box has the following attributes:
The user can:
When a Scale object is created it has the following components:
When the Scale dialogue is showing, the Scale module deals with all relevant Wimp events and reports user actions back to the client via Toolbox events. If there are any standard size action buttons in the dialogue box, then the Scale module deals with clicks on them, and inserts the correct percentage value into the writable field.
The client is guaranteed to receive a Scale_DialogueCompleted Toolbox event when the dialogue is over (i.e. the user has clicked on Cancel, or clicked outside the dialogue box (if it were transient), or clicked on Scale, or on Scale To Fit).
A Scale 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 Scale_AboutToBeShown event should be raised when SWI Toolbox_ShowObject is called for this object. | |
| 1 | when set, this bit indicates that a Scale_DialogueCompleted event should be raised when the Scale object has been removed from the screen. | |
| 2 | when set, dialogue box has a Scale To Fit button | |
| min val | alternative minimum value for the writable field | |
| max val | alternative maximum value for the writable field | |
| step size | alternative step size for up/down arrows | |
| Scale title | alternative title for the dialogue rather than 'Scale View' (0 means use default) | |
| max title length | this gives the maximum length in bytes of title text which will be used for this object | |
| window | the name of an alternative window template to use instead of the default one (0 means use default) | |
| std1 value | value of first std scale button | |
| std2 value | value of second std scale button | |
| std3 value | value of third std scale button | |
| std4 value | value of fourth std scale button | |
A Scale object is created using SWI Toolbox_CreateObject.
When this object is created it has no attached objects (see Attached objects).
A Scale object is deleted using SWI Toolbox_DeleteObject.
The setting of the non-recursive delete bit does not have a meaning for Scale objects.
When a Scale 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 SWI Toolbox_ShowObject is called on a Scale object, the Scale Class raises a Scale_AboutToBeShown Toolbox event (if enabled), just before it shows the underlying Window object which implements this dialogue. This will allow the client to set an initial suitable value in the Scale dialogue's Writable Field.
When the user clicks on the Scale button, or on the Scale To Fit button if it is present, the Scale module delivers a Scale_ApplyFactor to the client, giving the percentage factor to apply. A special value of 0xffffffff is delivered if the Scale To Fit button is clicked.
If the user clicks on the Cancel Button (or clicks outside the Scale dialogue box), then the Scale module delivers a Scale_DialogueCompleted Toolbox event to the client application. This allows the client to update any of its data structures and to clean up any state associated with this dialogue.
When the Scale module has hidden its dialogue box at the end of a dialogue, it delivers a Scale_DialogueCompleted Toolbox event to the client (if enabled), with an indication of whether a scale factor was reported to the client during the dialogue.
Normally a client will only need to respond to the Scale_ApplyFactor Toolbox event in order to allow the user to set scale factors. If, however, the client wishes to read the current value in the writable field, or to set it explicitly (to a suitable start value when the dialogue box is first shown), then it can use the Scale_SetValue/Scale_GetValue methods.
Normally a client will specify the bounds and step size of the writable field in the template description for the Scale object.
These can however be read and set dynamically using the Scale_SetBounds/ Scale_getBounds and Scale_GetStepSize/Scale_SetStepSize methods.
The following methods are all invoked by calling SWI Toolbox_ObjectMiscOp with:
| R0 | holding a flags word |
| R1 | being a Scale Dialogue object id |
| R2 | being the method code which distinguishes this method |
| R3-R9 | potentially holding method-specific data |
| R0 | = | flags |
| R1 | = | Scale object id |
| R2 | = | 0 |
| R0 | = | Window object id for this Scale object |
This method returns the id of the underlying Window object used to implement this Scale object.
extern _kernel_oserror *scale_get_window_id ( unsigned int flags,
ObjectId scale,
ObjectId *window
);
| R0 | = | flags |
| R1 | = | Scale object id |
| R2 | = | 1 |
| R3 | = | value |
| R1-R9 preserved |
This method is used to set the value displayed in the writable field for this Scale object.
extern _kernel_oserror *scale_set_value ( unsigned int flags,
ObjectId scale,
int value
);
| R0 | = | flags |
| R1 | = | Scale object id |
| R2 | = | 2 |
| R0 | = | value |
This method returns the value in the writable field of this Scale object.
extern _kernel_oserror *scale_get_value ( unsigned int flags,
ObjectId scale,
int *value
);
| R0 | = | flags
bit 0 set means set the lower bound to the given value bit 1 set means set the upper bound to the given value bit 2 set means set step size |
| R1 | = | Scale object id |
| R2 | = | 3 |
| R3 | = | value of the lower bound |
| R4 | = | value of the upper bound |
| R5 | = | step size |
| R1-R9 preserved |
This method sets the lower and upper bounds and step size of the writable field in the Scale object.
extern _kernel_oserror *scale_set_bounds ( unsigned int flags,
ObjectId scale,
int lower_bound,
int upper_bound,
int step_size
);
| R0 | = | flags
bit 0 set means return the lower bound bit 1 set means return the upper bound bit 2 set means return step size |
| R1 | = | Scale object id |
| R2 | = | 4 |
| R0 | = | value of the lower bound |
| R1 | = | value of the upper bound |
| R2 | = | value of the step size |
This method returns either the lower and upper bounds and step size of the writable field in the Scale object.
extern _kernel_oserror *scale_get_bounds ( unsigned int flags,
ObjectId scale,
int *lower_bound,
int *upper_bound,
int *step_size
);
| R0 | = | flags |
| R1 | = | Scale 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 Scale dialogue.
extern _kernel_oserror *scale_set_title ( unsigned int flags,
ObjectId scale,
char *title
);
| R0 | = | flags |
| R1 | = | Scale object id |
| R2 | = | 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 Scale dialogue's title bar.
extern _kernel_oserror *scale_get_title ( unsigned int flags,
ObjectId scale,
char *buffer,
int buff_size,
int *nbytes
);
| + 8 | 0x82c00 |
| + 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 Scale module is going to show its underlying Window object, to enable the client to set its initial value appropriately.
typedef struct
{
ToolboxEventHeader hdr;
int show_type;
union
{
TopLeft pos;
WindowShowObjectBlock full;
} info;
} ScaleAboutToBeShownEvent;
| + 8 | 0x82c01 |
| + 12 | flags |
This Toolbox event is raised after the Scale object has been hidden, either by a Cancel click, or by a click on Scale or Scale To Fit, or by the user clicking outside the dialogue box (if it is transient). It allows the client to tidy up its own state associated with this dialogue.
Note that if the dialogue was cancelled, a scale factor may still have been applied, for example if the user clicked Adjust on Scale, and then cancelled the dialogue.
typedef struct
{
ToolboxEventHeader hdr;
} ScaleDialogueCompletedEvent;
| + 8 | 0x82c02 |
| + 16 | unsigned integer scale factor to apply |
This Toolbox event is raised when the user clicks on the Scale button or the Scale To Fit button (if present), or presses Return.
The scale factor to apply is a percentage; 0xffffffff means Scale To Fit.
typedef struct
{
ToolboxEventHeader hdr;
unsigned int factor;
} ScaleApplyFactorEvent;
The layout of a Scale 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 |
| min_val | 4 | word |
| max_val | 4 | word |
| step_size | 4 | word |
| title | 4 | MsgReference |
| max_title | 4 | word |
| window | 4 | StringReference |
| std1_value | 4 | word |
| std2_value | 4 | word |
| std3_value | 4 | word |
| std4_value | 4 | word |
The Window object used to implement a Scale 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 0x82c000.
| Component id | Details | |
|---|---|---|
| 0 | number range (Scale) | must have adjuster arrows, and be writable |
| 1-4 | action buttons (standard scale factors) | these should have the text 33%, 80%, 100% and 120% |
| 5 | action button (Cancel) | this must be marked as a Cancel action button |
| 6 | action button (Scale) | this must be marked as the default action button |
| 7 | label (%) | |
| 8 | label (Scale) | |
| 9 | action button (Scale to fit) |
| Wimp event | Action |
|---|---|
| Mouse Click | on Scale or Scale to Fit buttons, then deliver a Scale_ApplyFactor Toolbox event
on a standard size button then enter its value into the Writable Field on Cancel button then hide the dialogue box, and deliver a Scale_DialogueCompleted Toolbox event. |
| Key Pressed | if key is Return then act as if Scale button had been clicked
if key is Escape then act as if Cancel button had been clicked. |
| User Message User Message Recorded | Message_MenusDeleted deliver a Scale_DialogueCompleted Toolbox event. |