A ScrollList is a gadget used to provide a scrolling list.

Bits in the flags word for a ScrollList have the following meaning:

	Bit	Meaning when set
	0	gadget can have multiple selected items

The ScrollList gadget requires the Window module, version 1.33 or greater.
ScrollList_Base is currently defined as &401A.

ScrollList methods
==================

ScrollList_GetState
-------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 0
	R3 = Gadget component id

On exit
	R0 = state
		bit 0 set means gadget can have multiple selected items

C veneer
extern _kernel_oserror *scrolllist_get_state(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			unsigned int *state);

ScrollList_SetState
-------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 1
	R3 = Gadget component id
	R4 = state
		bit 0 set means gadget can have multiple selected items

On exit
	R1-R9 preserved

C veneer
extern _kernel_oserror *scrolllist_set_state(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			unsigned int state);

ScrollList_AddItem
------------------
On entry
	R0 = flags
		bits 0 and 1 determine how the sprite is specified
		by R5 and R6:
			bits	meaning
			00	R5 unused
				R6 = sprite name in wimp sprite pool
			01	R5 = sprite area, R6 = sprite name
			10	R5 = sprite area, R6 = pointer to sprite
			11	reserved
		bit 2 set means plot sprite (if any) at half size
		bit 3 set means ensure new item is visible in gadget (try
			to scroll to place it at top of display), else
			preserve y scroll position (visible display thus
			may or may not move depending on whether or not
			the new item was above or below/within those
			items currently within the visible area).
	R1 = Window object id
	R2 = ScrollList_Base + 2
	R3 = Gadget component id
	R4 = text
	R5 = pointer to sprite area if bits 0 & 1 of R0 = 2_01 or 2_10;
		else unused
	R6 = sprite name if bits 0 & 1 of R0 = 2_00 or 2_01;
		else pointer to sprite if bits 0 & 1 of R0 = 2_10
	R7 = index

On exit
	R1-R9 preserved

Use
	Bits 0 and 1 of R0 behave similarly to OS_SpriteOp:
	R0 bits 0 & 1	R5 effect		R6 effect
	00		not used (wimp pool)	pointer to sprite name
	01		pointer to sprite area	pointer to sprite name
	10		pointer to sprite area	pointer to sprite
	11 is invalid

C veneer
extern _kernel_oserror *scrolllist_add_item(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			const char *text, const char *sprite_area,
			const void *sprite_name, int index);

ScrollList_DeleteItems
----------------------
On entry
	R0 = flags
		bit 0 set means sent ScrollList_Selection event when complete
			- item number in this event will be -1
		bit 1 set means try to preserve y scroll position, else jump
			to top of display
	R1 = Window object id
	R2 = ScrollList_Base + 3
	R3 = Gadget component id
	R4 = start index
	R5 = end index

On exit
	R1-R9 preserved

C veneer
extern _kernel_oserror *scrolllist_delete_items(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			int start_index, int end_index);

ScrollList_SelectItem
---------------------
On entry
	R0 = flags
		bit 0 set means sent ScrollList_Selection event when complete
		bit 1 set means select all items - if bit 0 is also set, item
			number in ScrollList_Selection event will be 0
	R1 = Window object id
	R2 = ScrollList_Base + 4
	R3 = Gadget component id
	R4 = index

On exit
	R1-R9 preserved

C veneer
extern _kernel_oserror *scrolllist_select_item(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			int index);

ScrollList_DeselectItem
-----------------------
On entry
	R0 = flags
		bit 0 set means sent ScrollList_Selection event when complete
		bit 1 set means deselect all items - if bit 0 is also set,
			item number in ScrollList_Selection event will be 0
	R1 = Window object id
	R2 = ScrollList_Base + 5
	R3 = Gadget component id
	R4 = index

On exit
	R1-R9 preserved

C veneer
extern _kernel_oserror *scrolllist_deselect_item(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			int index);

ScrollList_GetSelected
----------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 6
	R3 = Gadget component id
	R4 = offset (-1 to start)

On exit
	R0 = next selected item, -1 to finish

C veneer
extern _kernel_oserror *scrolllist_get_selected(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			int offset, int *new_offset);

ScrollList_MakeVisible
----------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 7
	R3 = Gadget component id
	R4 = index

On exit
	R1-R9 preserved

C veneer
extern _kernel_oserror *scrolllist_make_visible(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			int index);

ScrollList_SetColour
--------------------
On entry
	R0 = flags
		bit 0 set means use desktop colours rather than
			real colours (in the form &BBGGRR00)
	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 is 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
	R1 = Window object id
	R2 = ScrollList_Base + 9
	R3 = Gadget component id

On exit
	R0 = Colour value (in the form &BBGGRR00) of foreground
	R1 = Colour value (in the form &BBGGRR00) 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);

ScrollList_SetFont
------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 10
	R3 = Gadget component id
	R4 = pointer to font name to use
	R5 = width in 16th of a point
	R6 = height in 16th of a point

On exit
	R1-R9 preserved

Use

This method makes the scrolling list use an anti-aliased font. If the font
name is NULL, then the text area will use the current desktop font (or
system font if unset)

C veneer
extern _kernel_oserror *scrolllist_set_font(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			const char *font, unsigned int width,
			unsigned int height);

ScrollList_GetItemText
----------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 11
	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_item_text(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			char *text, int buffer_size, int index, int *nbytes);

ScrollList_CountItems
---------------------

On entry:
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 12
	R3 = Gadget component_id

On exit:
	R0 = Number of items


C Veneer (tboxlibs 0.04 or later):
extern _kernel_oserror * scrolllist_count_items(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			unsigned int *items);

ScrollList_SetItemText
----------------------
On entry
	R0 = flags
	R1 = Window object id
	R2 = ScrollList_Base + 11
	R3 = Gadget component_id
	R4 = Pointer to buffer holding new string
	R5 = index


C veneer (tboxlibs 0.05 or later):
extern _kernel_oserror *scrolllist_set_item_text(unsigned int flags,
			ObjectId object_id, ComponentId component_id,
			char *new_text, int index);


Bugs
----

Whilst the gadget reads the current mode's scale factors and the size of
the current Wimp tool sprites to accurately position its embedded window
within the defined gadget bounding box at create-time, it does not notice
if these values change. If tools or Desktop scaling alter, the gadget
will only notice when a new instance of a ScrollList is created. At this
point, existing ScrollLists will not resize, but will start using the new
values (since they're global to the module). At such a time as an interface
exists which allows external gadget modules to be told about Wimp messages,
this all gets fixed, as all gadgets can be resized appropriately - hence a
gadget-global record of the relevant details is OK.
