|
ScrollList
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.
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.
ScrollList_SetHeadingText
On entry
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
C veneer
extern _kernel_oserror *scrolllist_set_heading_text ( unsigned int flags,
ObjectId window,ComponentId scrolllist,const char *new_text );
ScrollList_GetHeadingText
On entry
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
On exit
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
C veneer
extern _kernel_oserror *scrolllist_get_heading_text ( unsigned int flags,
ObjectId window, ComponentId scrolllist,
char *buffer, int size, int *nbytes );
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.
ScrollList_GetColumnProperties
On entry
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
C veneer
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.
ScrollList_SetColour
On entry
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
On exit
R1-R9 preserved
C veneer
extern _kernel_oserror *scrolllist_set_colour(unsigned int flags,
ObjectId object_id, ComponentId component_id,
unsigned int foreground, unsigned int background);
ScrollList_GetColour
On entry
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
On exit
R0 = Colour value (in the form &BBRRGG00) of foreground
R1 = Colour value (in the form &BBRRGG00) of background
C veneer
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'.
- 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 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.
ScrollList_CountItems
On entry:
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
On exit:
R0 = result value
C Veneer
extern _kernel_oserror * scrolllist_count_items(unsigned int flags,
ObjectId object_id, ComponentId component_id,
unsigned int *items);
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 differentiated items.
ScrollList_AddItem
On entry:
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
On exit:
All registers preserved
C Veneer
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
);
|
![[Select]](../imgs/seldoc.png)
