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 :
For information on the particular version of the gadget which supports these new features you should consult the change summaries.
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 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.
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
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
extern _kernel_oserror *scrolllist_get_heading_text ( unsigned int flags, ObjectId window, ComponentId scrolllist, char *buffer, int size, int *nbytes );
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.
R0 = flags : bits 0-7 = property type: 0 = column widths 1-255 = reserved bits 8-31 reserved, must be 0 R1 = Window object id R2 = ScrollList_Base + 20 R3 = Gadget component_id R4 = number of columns specified R5 = pointer to data describing the properties
extern _kernel_oserror *scrolllist_set_column_properties ( unsigned int flags, ObjectId window, ComponentId scrolllist, int number_of_columns, unsigned long *data_list );
This call is not presently implemented.
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.
R0 = flags : bit 0 = use desktop colours rather than real colours (in the form &BBRRGG00) bit 1 = set heading colours, rather than item colours bits 2-31 reserved, must be 0 R1 = Window object id R2 = ScrollList_Base + 8 R3 = Gadget component id R4 = Colour value for foreground text (in the form &BBRRGG00 unless bit 0 of R0 is set) R5 = Colour value for background in the form &BBRRGG00 unless bit 0 of R0 set
extern _kernel_oserror *scrolllist_set_colour(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int foreground, unsigned int background);
R0 = flags : bit 0 reserved, must be 0 bit 1 = read heading colours rather, than item colours bits 2-31 reserved, must be 0 R1 = Window object id R2 = ScrollList_Base + 9 R3 = Gadget component id
R0 = Colour value (in the form &BBRRGG00) of foreground R1 = Colour value (in the form &BBRRGG00) of background
extern _kernel_oserror *scrolllist_get_colour(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int *foreground, unsigned int *background);
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'.
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 the 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 0 = multiple selections are allowed bit 1 = icon selection method should be used bit 2 = gadget is for display only bits 3-4 = vertical scrollbar disposition: 0 = scrollbar will be added if the list requires one 1 = scrollbar will always be added 2 = scrollbar will never be added 3 = invalid bits 5-6 = horizontal scrollbar disposition: 0 = scrollbar will be added if the list requires one 1 = scrollbar will always be added 2 = scrollbar will never be added 3 = invalid bits 7-23 reserved for future gadget use bits 24-29 reserved for future window use bit 30 = gadget appears 'in the background' (has no effect upon this gadget) bit 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.
R0 = flags : bits 0-7 = type of information requested: 0 = count number of rows 1 = count number of columns (N/I) 2 = read width necessary to make all columns visible 3 = read height necessary to make all rows visible 4-255 reserved bits 8-31 reserved, must be 0 R1 = Window object id R2 = ScrollList_Base + 12 R3 = Gadget component_id
R0 = result value
extern _kernel_oserror * scrolllist_count_items(unsigned int flags, ObjectId object_id, ComponentId component_id, unsigned int *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 differentiated items.
R0 = flags : bits 0-1 = type of sprite to use: 0 = wimp sprite pool 1 = user sprite area 2 = sprite is a pointer to sprite 3 = invalid, do not use bit 2 = sprite should be half size bit 3 = make added item visible bits 4-7 = indentation level bits 8-31 = reserved, must be 0 R1 = Window object id R2 = ScrollList_Base + 12 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
All registers preserved
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 );
This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.
HTML document version 1.03 3rd November 2015