/*
 * listbox.h
 *
 * [Generated from listbox, 25 September 1996]
 */

#if !defined(__CC_NORCROFT) || !defined(__arm)
  #error You must use the Norcroft ARM Compiler for Sapphire programs
#endif

#pragma include_only_once
#pragma force_top_level

#ifndef __listbox_h
#define __listbox_h

#ifndef __sapphire_h
  #include "sapphire.h"
#endif

/*----- 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
 */

/* --- 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)
 */

extern routine lb_create;

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

extern routine 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.
 */

extern routine 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.
 */

extern routine lb_plotString;

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

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine 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.
 */

extern routine lb_removed;

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

extern routine lb_window;

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

extern routine lb_init;

/*----- List events -------------------------------------------------------*/

#define lbEvent_close 0

#define lbEvent_redraw 1
#define lbEvent_click 2
#define lbEvent_menu 3
#define lbEvent_drag 4
#define lbEvent_help 5
#define lbEvent_drop 6

#define lbDrop_load 0
#define lbDrop_save 1

/*----- That's all, folks -------------------------------------------------*/

#endif