;
; listbox.sh
;
; Nice listbox handling routines
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  lb_create
;  lb_destroy
;  lb_eventHandler
;  lb_plotString
;  lb_update
;  lb_updateItem
;  lb_select
;  lb_isSelected
;  lb_clearSelection
;  lb_clickS
;  lb_clickM
;  lb_drag
;  lb_inserted
;  lb_removed
;  lb_init

		[	:LNOT::DEF:listbox__dfn
		GBLL	listbox__dfn

; --- lb_create ---
;
; On entry:	R0 == pointer to list manager description block
;		R1 == pointer to the list
;		R2 == pointer to a width function
;		R3 == The height of each item
;		R4 == parent window handle or
;		      pointer to window block if R5 == -1
;		R5 == parent icon handle or -1 if not a pane
;
; On exit:	R0 == listbox handle
;		R1 == window handle of list box
;		May return an error (R1 corrupted)

		IMPORT	lb_create

; --- lb_destroy ---
;
; On entry:	R0 == listbox handle
;
; On exit:	--
;
; Use:		Destroys the given listbox.

		IMPORT	lb_destroy

; --- lb_eventHandler ---
;
; On entry:	R0 == listbox handle
;		R1 == handler function
;		R2 == R10 value to pass
;		R3 == R12 value to pass
;
; On exit:	--
;
; Use:		Registers an event handler for the given listbox.

		IMPORT	lb_eventHandler

; --- lb_plotString ---
;
; On entry:	R0 == pointer to a string
;		R1 == pointer to the list item
;		R2-R5 == window coordinates to plot it
;		R10 == pointer to the listbox
;
; On exit:	--
;
; Use:		Plots a list item consisting of a single string.  It assumes
;		the default selection model.

		IMPORT	lb_plotString

; --- lb_update ---
;
; On entry:	R0 == listbox handle
;
; On exit:	May return an error
;
; Use:		Updates the entire listbox prettily

		IMPORT	lb_update

; --- lb_updateItem ---
;
; On entry:	R0 == list box handle
;		R1 == list item handle
;
; On exit:	--
;
; Use:		Redraws a list item to reflect a change in its state.

		IMPORT	lb_updateItem

; --- lb_select ---
;
; On entry:	R0 == listbox handle
;		R1 == item handle
;		R2 == 0 to unselect, 1 to select, or 2 to toggle
;
; On exit:	--
;
; Use:		Selects or deselects a listbox item, nicely and without
;		flickering it.

		IMPORT	lb_select

; --- lb_isSelected ---
;
; On entry:	R0 == listbox handle
;		R1 == item handle
;
; On exit:	CS if item is selected, else CC
;
; Use:		Informs you whether an item is selected.

		IMPORT	lb_isSelected

; --- lb_clearSelection ---
;
; On entry:	R0 == listbox handle
;		R1 == item handle of item to ignore (or 0 for none)
;
; On exit:	--
;
; Use:		Deselects all items in the listbox.

		IMPORT	lb_clearSelection

; --- lb_clickS ---
;
; On entry:	R0 == listbox handle
;		R1 == pointer to list item
;		R3 == mouse button status
;
; On exit:	--
;
; Use:		Provides a default action for clicking on an item in a
;		list box.
;
;		Only one selection is possible at any one time.

		IMPORT	lb_clickS

; --- lb_clickM ---
;
; On entry:	R0 == listbox handle
;		R1 == pointer to list item
;		R3 == mouse button status
;
; On exit:	--
;
; Use:		Provides a default action for clicking on an item in a
;		list box.
;
;		The multiple selection model is used.

		IMPORT	lb_clickM

; --- lb_drag ---
;
; On entry:	R1 == pointer to list item
;		R2 == window relative y position
;		R3 == mouse button status
;		R10 == listbox handle
;
; On exit:	--
;
; Use:		Starts a drag operation to allow for easy multiple
;		selection.

		IMPORT	lb_drag

; --- lb_inserted ---
;
; On entry:	R0 == pointer to the listbox
;		R1 == pointer to the new item
;
; On exit:	--
;
; Use:		Informs the listbox that an item has been inserted,
;		and causes a flicker free insert to occur if possible.

		IMPORT	lb_inserted

; --- lb_removed ---
;
; On entry:	R0 == pointer to the listbox
;		R1 == index of item removed
;
; On exit:	--
;
; Use:		Informs the listbox that an item has been removed, and
;		causes a flicker free remove to occur, if possible.

		IMPORT	lb_removed

; --- lb_window ---
;
; On entry:	R0 == listbox handle
;
; On exit:	R0 == window handle
;
; Use:		Returns the window handle of the listbox

		IMPORT	lb_window

; --- lb_init ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Initialises the listbox unit.

		IMPORT	lb_init

;----- List events ----------------------------------------------------------

		^	0
lbEvent_close	#	1			;Listbox has been closed

lbEvent_redraw	#	1			;Redraw a list item
						;R1 == pointer to list item
						;R2-R5 == window coords
lbEvent_click	#	1			;Click/Double on listbox
						;R1 == pointer to list item
						;R2 == window relative y pos
						;R3 == button type (10)
lbEvent_menu	#	1			;Menu click
						;R1 == pointer to list item
						;R2 == window relative y pos
						;R3 == button type (10)
lbEvent_drag	#	1			;Drag on listbox
						;R1 == pointer to list item
						;R2 == window relative y pos
						;R3 == button type (10)
lbEvent_help	#	1			;R1 == pointer to list item
lbEvent_drop	#	1			;R1 == pointer to list item
						;R2 == filetype
						;R3 == pointer to filename
						;R4 == estimated file size
						;R5 == subreason cde

		^	0
lbDrop_load	#	1
lbDrop_save	#	1


		]

;----- That's all, folks ----------------------------------------------------

		END