Introduction and Overview
The scrolling list gadget has been extended since its original release. These changes have been made to provide a much more functional gadget and to improve its performance where larger numbers of rows are used.
Significant changes :
- It is now possible to display item data within aligned columns.
- Row selection can now follow the methods used by standard RISC OS option, or radio icons.
- Static headings can be applied to the scrolling list.
- Scroll bars on the gadget can be controlled.
For information on the particular version of the gadget which supports these new features you should consult the change summaries.
Technical Details
Adding aligned column data
Previous versions of the ScrollList gadget only allowed single lines of text and a sprite to be placed within the list. The items have been extended to allow columns to be used. Each column should be separated by a tab (code 9, C escape '\t') character. By default these columns will be automatically sized to the widest text within that column.
Row selection methods
In order to fit better with the standard RISC OS selection methods for options the gadget allows 'icon-style' selection. This means that the rows of the list will be preceded by the standard 'option' or 'radio' icons, just as they would within normal dialogue boxes. The selection methods employed by this style matches with that of the standard RISC OS selection method.
In order to use this method of selection bit 1 of the scrolling list flags should be set. When enabled, bit 0 (multiple selections) indicates whether radio or option icons should be used. The relevant icon is added to the start of the row, before any sprite.
Display only lists
In order to allow the gadget to purely display information a new flag has been allocated. When bit 2 is set, the display list will never act upon selections of rows within the gadget.
Column headings
Column headings are placed at the top of the gadget and will be present no matter where the gadget is scrolled to. The specification of column headings is identical to that of the text items, using tab characters to separate columns. To remove the column headings, a null string should be used.
The headings are set with ScrollList_SetHeadingText and read with ScrollList_GetHeadingText.
Column properties
In order to allow more control over the columns, a pair of new methods - ScrollList_SetColumnProperties and ScrollList_GetColumnProperties - are provided. These allow information about the columns to be set and read. When dealing with column properties, column 0 is the 'sprite' column, column 1 is the first column of text, column 2 is the second column of text, etc.
Column widths can be selected using property type 0. By default no column widths are specified. This state can be restored by using '0' as the number of columns specified. The width of each column is specified in OS units. Any column given a width of 0 will be effectively removed from the list. Any column given a width of -1 will be automatically sized by the gadget (as normal). Any column not described by the column data (that is, any column higher than that specified by the 'number of columns') will be treated as having a width of 0 - removed from the list.
Scrolling list colours
In order to allow the gadget to be tailored to the users' requirements the colour selection has been improved. ScrollList gadgets which have been faded now follow more closely the fading scheme used by the WindowManager. The colour methods have been extended to provide more control over the list's appearance.
Scrollbar disposition flags
To ensure that the ScrollList is functional regardless of its size it is now possible to directly control the use of the scrollbars upon the gadget. Previous versions of the gadget would always provide a vertical scrollbar, allowing the length of the list to be traversed, but preventing 'long' rows from being visible if they extended beyond the window bounds. The gadget has changed to allow the disposition of the scrollbars to be controlled. There are three possible dispositions for the scrollbars - 'optional', 'on' and 'off'.
- When set to 'optional', the scrollbar will be used only if it is necessary to make parts of the ScrollList accessible to the user. No scrollbar will be present if the list is fully visible.
- When set to 'on', the scrollbar will be used regardless of the content of the gadget.
- When set to 'off', the scrollbar will never be used.
The default state of the gadget now is that both scrollbars are optional. Effectively this means that most pre-existing uses of the ScrollList gadget will lose their vertical scrollbar unless it is necessary for the rows to be accessible. Some lists may, additionally, gain a horizontal scrollbar, allowing previously inaccessible sections of the gadget to become visible.
Gadget flags summary
The flags have been updated, as described above, and are now provided as follows :
| Bit(s) | Meaning | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Multiple selections are allowed | |||||||||||
| 1 | Icon selection method should be used | |||||||||||
| 2 | Gadget is for display only | |||||||||||
| 3-4 | Vertical scrollbar disposition:
| |||||||||||
| 5-6 | Horizontal scrollbar disposition:
| |||||||||||
| 7-23 | Reserved for future gadget use | |||||||||||
| 24-29 | Reserved for future window use | |||||||||||
| 30 | Gadget appears 'in the background' (has no effect upon this gadget) | |||||||||||
| 31 | Gadget is faded | |||||||||||
These bits may be set on the gadget within the ResEd editor, or manipulated once the gadget has been loaded using the ScrollList_SetState method. Core window bits (bits 24-31) should be manipulated using the Gadget_SetState method.
Gadget physical size
In order to allow users to size the ScrollList gadget to allow all the items to be visible, the ScrollList_CountItems method has been extended. It now allows other information about the gadget to be read.
Indented items
It is possible to indent items within the scrolling list through extra flags on the ScrollList_AddItem method. The indent consists of 32 OS units per indent and can be used to differentiate items.
Toolbox Methods
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Window object id |
| R2 | = | ScrollList_Base + 14 |
| R3 | = | Gadget component_id |
| R4 | = | Pointer to new text to use for the column headings |
Sets the text of the column headings. See the Column headings section.
extern _kernel_oserror *scrolllist_set_heading_text ( unsigned int flags,
ObjectId window,ComponentId scrolllist,const char *new_text );
| R0 | = | Flags (reserved, must be 0) |
| R1 | = | Window object id |
| R2 | = | ScrollList_Base + 15 |
| R3 | = | Gadget component_id |
| R4 | = | Pointer to buffer for text (or NULL) |
| R5 | = | Size of buffer |
| R6 | = | Index |
| R5 | = | Size of buffer required (if R4 was 0) else buffer pointed at by R4 contains text, R5 holds number of bytes written to buffer |
Reads the text of the column headings.
extern _kernel_oserror *scrolllist_get_heading_text ( unsigned int flags,
ObjectId window, ComponentId scrolllist,
char *buffer, int size, int *nbytes );
| R0 | = | Flags:
| |||||||||||||||
| R1 | = | Window object id | |||||||||||||||
| R2 | = | ScrollList_Base + 20 | |||||||||||||||
| R3 | = | Gadget component_id | |||||||||||||||
| R4 | = | Number of columns specified | |||||||||||||||
| R5 | = | Pointer to data describing the properties | |||||||||||||||
Sets the properties of the columns. This call is not presently implemented.
extern _kernel_oserror *scrolllist_set_column_properties
( unsigned int flags, ObjectId window, ComponentId scrolllist,
int number_of_columns, unsigned long *data_list );
| R0 | = | Flags:
| ||||||||||||
| R1 | = | Window object id | ||||||||||||
| R2 | = | ScrollList_Base + 8 | ||||||||||||
| R3 | = | Gadget component_id | ||||||||||||
| R4 | = | Colour value for foreground text (in the form &BBGGRR00 unless bit 0 of R0 is set) | ||||||||||||
| R5 | = | Colour value for background in the form &BBGGRR00 unless bit 0 of R0 set | ||||||||||||
| R1 - R9 | = | Preserved |
Sets the colours used by the list.
extern _kernel_oserror *scrolllist_set_colour(unsigned int flags,
ObjectId object_id, ComponentId component_id,
unsigned int foreground, unsigned int background);
| R0 | = | Flags:
| ||||||||||||
| R1 | = | Window object id | ||||||||||||
| R2 | = | ScrollList_Base + 9 | ||||||||||||
| R3 | = | Gadget component_id | ||||||||||||
| R0 | = | Colour value (in the form &BBGGRR00) of foreground |
| R1 | = | Colour value (in the form &BBGGRR00) of background |
Reads the colours used by the list.
extern _kernel_oserror *scrolllist_get_colour(unsigned int flags,
ObjectId object_id, ComponentId component_id,
unsigned int *foreground, unsigned int *background);
| R0 | = | Flags:
| |||||||||||||||||||||
| R1 | = | Window object id | |||||||||||||||||||||
| R2 | = | ScrollList_Base + 12 | |||||||||||||||||||||
| R3 | = | Gadget component_id | |||||||||||||||||||||
| R0 | = | Result value |
Reads information about the list.
extern _kernel_oserror * scrolllist_count_items(unsigned int flags,
ObjectId object_id, ComponentId component_id,
unsigned int *items);
| R0 | = | Flags:
| ||||||||||||||||||||||||||||
| R1 | = | Window object id | ||||||||||||||||||||||||||||
| R2 | = | ScrollList_Base + 2 | ||||||||||||||||||||||||||||
| R3 | = | Gadget component_id | ||||||||||||||||||||||||||||
| R4 | = | Pointer to text string to add | ||||||||||||||||||||||||||||
| R5 | = | Pointer to sprite area | ||||||||||||||||||||||||||||
| R6 | = | Pointer to sprite name (or pointer to sprite if sprite type in R0 bits 0-1 is 2) | ||||||||||||||||||||||||||||
| R7 | = | Index to add at | ||||||||||||||||||||||||||||
| R0 - R7 | = | Preserved |
Adds an item to the list. The indent consists of 32 OS units per indent and can be used to differentiate items.
extern _kernel_oserror *scrolllist_add_item ( unsigned int flags,
ObjectId window,
ComponentId scrolllist,
const char *text,
const void *sprite_area,
const char *sprite_name,
int index
);