Initial revision

[ssr] / StraySrc / Libraries / Steel / h / listbox

/*
 * ListBox
 *  Provides handling for list boxes
 *
 * v. 1.00 (27 July 1991)
 *
 * © 1991-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel 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.
 *
 * Steel 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 Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __listbox_h
#define __listbox_h

#ifndef __wimp_h
#include "wimp.h"
#endif

/*
 * Abstract listbox handle
 */
typedef struct list__liststr *list;

#ifndef __pane_h
#include "pane.h"
#endif

/*
 * An abstraction for list items
 */
typedef struct list__item *list_item;

#define list_NOITEM ((list_item)0)
#define list_CLOSE ((list_item)-2)
#define list_HELP ((list_item)-3)

typedef void (*list_eventhandler)(list l,list_item item,void *handle);
typedef BOOL (*list_raweventhandler)(list l,wimp_eventstr *e,void *handle);
typedef void (*list_redrawhandler)(list l,
                                   list_item i,
                                   wimp_redrawstr *r,
                                   wimp_box *b,
                                   char *text,
                                   BOOL selected,
                                   void *handle);

typedef enum
{
  list_RESETSTATE,
  list_SETSTATE,
  list_READSTATE,
  list_TOGGLESTATE
}
list_action;

/*
 * void list_isPane(list l,pane p)
 *
 * Use
 *  This routine is part of the private interface between the listbox and
 *  pane segments.  Do *NOT* try to call it in your own code.
 */

void list_isPane(list l,pane p);

/*
 * list list_create(char *name,BOOL alterSize)
 *
 * Use
 *  Creates a new list box window, and returns a handle to it.  Initially,
 *  there are no items, and the list box is not shown.  The function returns
 *  0 if the call fails for one reason or another (not enough windows or
 *  memory).
 *
 * Parameters
 *  char *name == the name to match in the template file
 *  BOOL alterSize == TRUE if we are allowed to change the box's visible
 *    size.
 *
 * Returns
 *  An abstract handle for the list box.
 */

list list_create(char *name,BOOL alterSize);

/*
 * void list_selectItem(list l,list_item item)
 *
 * Use
 *  Makes the item the currently selected one.
 *
 * Parameters
 *  list l == the list handle
 *  list_item item == the item number
 */

void list_selectItem(list l,list_item item);

/*
 * list_item list_selected(list l)
 *
 * Use
 *  Returns the currently selected item of the list.
 *
 * Parameters
 *  list l == the list handle
 *
 * Returns
 *  The item number of the currently selected item.
 */

list_item list_selected(list l);

/*
 * char *list_itemData(list l,list_item i)
 *
 * Use
 *  Returns the string for an item
 *
 * Parameters
 *  list l == the list handle
 *  list_item i == the item's handle
 *
 * Returns
 *  A pointer to the item's data
 */

char *list_itemData(list l,list_item i);

/*
 * list_item list_addItem(list l,char *data,BOOL inOrder)
 *
 * Use
 *  Adds a new piece of data into the list.
 *
 * Parameters
 *  list l == the list handle
 *  char *data == the data (as a char *, because most of the time you'll
 *    want to be using character strings).
 *
 * Returns
 *  A handle for the list item.
 */

list_item list_addItem(list l,char *data,BOOL inOrder);

/*
 * list_item list_findItem(list l,char *data)
 *
 * Use
 *  Searches through a list and returns the item number of the item whose
 *  data matches that given in the function.
 *
 * Parameters
 *  list l == the list handle
 *  char *data == the data to compare with
 *
 * Returns
 *  The item number of the item, or list_NOITEM if no match.
 */

list_item list_findItem(list l,char *data);

/*
 * void list_removeItem(list l,list_item i)
 *
 * Use
 *  Removes an item from the list.
 *
 * Parameters
 *  list l == the list's handle
 *  list_item i == the item number
 */

void list_removeItem(list l,list_item i);

/*
 * void list_delete(list l)
 *
 * Use
 *  Destroys a list totally.
 *
 * Parameters
 *  list l == the list handle
 */

void list_delete(list l);

/*
 * void list_updatePosition(list l)
 *
 * Use
 *  Writes the position of the listbox back into the template, so any new
 *  list boxes created from the template open at that position.
 *
 * Parameters
 *  list l == the list handle
 */

void list_updatePosition(list l);

/*
 * BOOL list_link(list l)
 *
 * Use
 *  Links a list box to a WIMP window.  If the list is already linked,
 *  nothing happens.  The list box is not displayed.
 *
 * Parameters
 *  list l == the list handle
 *
 * Returns
 *  TRUE if the link succeeded (may run out of windows!)
 */

BOOL list_link(list l);

/*
 * void list_unlink(list l)
 *
 * Use
 *  Unlinks the list box from its window and deletes the window.
 *
 * Parameters
 *  list l == the list handle
 */

void list_unlink(list l);

/*
 * void list_unlinkNoUpdate(list l)
 *
 * Use
 *  Unlinks a list from its window without storing its final position  back
 *  in memory.  Note that list_delete() calls list_unlink(), so make sure
 *  you call this routine before deleting the listbox it you want to prevent
 *  the position being written back.
 *
 * Parameters
 *  list l == the list handle
 */

void list_unlinkNoUpdate(list l);

/*
 * void list_update(list l,BOOL really)
 *
 * Use
 *  Enables or disables list updating (i.e. whether the listbox resizes and
 *  redraws itself between every operation).  If you're going to do some
 *  lengthy operation, it would be a good idea to turn update off first,
 *  and then turn it on again afterwards.
 *
 *  Note that this is an all-or-nothing thing -- no counter is kept.
 *
 * Parameters
 *  list l == the listbox which we're messing about with
 *  BOOL really == whether to turn the update on or off
 */

void list_update(list l,BOOL really);

/*
 * void list_display(list l)
 *
 * Use
 *  Displays a list box on-screen
 *
 * Parameters
 *  list l == the list
 */

void list_display(list l);

/*
 * void list_openDisplaced(list l)
 *
 * Use
 *  Opens the listbox on-screen displaced from its previous position by
 *  the normal 48 OS units.  It must be unlinked using list_unlinkNoUpdate()
 *  before deletion.
 *
 * Parameters
 *  list l == the list handle.
 */

void list_openDisplaced(list l);

/*
 * void list_hide(list l)
 *
 * Use
 *  Stops the list box being displayed
 *
 * Parameters
 *  list l == the list handle
 */

void list_hide(list l);

/*
 * wimp_w list_syshandle(list l)
 *
 * Use
 *  Returns the WIMP window handle being used for the list box.
 *
 * Parameters
 *  list l == the list
 *
 * Returns
 *  The window handle (a wimp_w).
 */

wimp_w list_syshandle(list l);


/*
 * void list_eventHandler(list l,list_eventhandler proc,void *handle)
 *
 * Use
 *  Attaches an event handler to the list box.  Most won't actually need
 *  this, just the stand-alone ones, or ones that do clever-dick things.
 *
 * Parameters
 *  list l == the list handle
 *  list_eventhandler proc == the procedure to handle events
 *  void *handle == the jolly olde pointer to the user-defined data
 */

void list_eventHandler(list l,list_eventhandler proc,void *handle);

/*
 * void list_rawEventHandler(list l,list_raweventhandler proc,void *handle)
 *
 * Use
 *  Attaches the raw event handler procedure to the list box.  You can then
 *  vet any events coming into the list box and have your wicked way with
 *  them. 
 *
 * Parameters
 *  list l == the list handle
 *  list_raweventhandler proc == the raw event handler routine
 *  void *handle == the (now-famous) caller defined handle.
 */

void list_rawEventHandler(list l,list_raweventhandler proc,void *handle);

/*
 * void list_redrawHandler(list l,list_redrawhandler rdr,void *handle)
 *
 * Use
 *  Attaches a replacement redraw handler to the list box.  The new handler
 *  redraws individual items in the list.  It must fill in the box it is
 *  passed, because the WIMP does not fill in the background.  The part of
 *  the list box not populated by items is filled in the window background
 *  colour automatically.  Using this, you can achieve quite a pleasing
 *  effect by making the background grey (colour 1) and the actual item
 *  backgrounds white (colour 0), indicating clearly the bottom of the list.
 *
 *  You can also implement other things like items being shaded etc.
 *
 * Parameters
 *  list l == the list to which the redraw handler is to be attached
 *  list_redrawhandler == the replacement redraw routine (or 0 to cancel)
 *  void *handle == a pointer to pass the redraw routine
 */

void list_redrawHandler(list l,list_redrawhandler rdr,void *handle);

/* 
 * void list_widthAdd(list l,int extra)
 *
 * Use
 *  Since redraw handlers can basically do whatever they want to for each
 *  items, the list manager no longer really has any idea about how wide an
 *  item is.  Since the main thing displayed in lists is text, it is assumed
 *  that the width of an item is the width of the longest piece of text plus
 *  a constant (e.g. for a sprite on the side).  If this is not so, I'll
 *  have to rethink this bit...
 *
 * Parameters
 *  list l == the list we're setting the width of
 *  int extra == the constant to add to each item
 */

void list_widthAdd(list l,int extra);

/*
 * void list_setItemHeight(list l,int height)
 *
 * Use
 *  Sets the height of items in the specified list box.  By default, the
 *  height is 44 OS units (the height of menu items).  This should be 
 *  sufficient for most purposes.
 *
 * Parameters
 *  list l == the list to set
 *  int height == the new height of each item, in OS units
 */

void list_setItemHeight(list l,int height);

/*
 * int list_items(list l)
 *
 * Use
 *  Informs the caller how many items there are in a list
 *
 * Parameters
 *  list l == the list handle
 *
 * Returns
 *  The number of items in a list
 */

int list_items(list l);

/*
 * void list_doForItems
 * (
 *   list l,
 *   void (*proc)(list l,list_item i,void *handle),
 *   void *handle
 * )
 *
 * Use
 *  Performs an operation on all of the items in a list box.
 *
 * Parameters
 *  list l == the list handle
 *  void (*proc)(list l,list_item i,void *handle) == the procedure to use
 *  void *handle == a handle to pass to the procedure.
 */

void list_doForItems
(
  list l,
  void (*proc)(list l,list_item i,void *handle),
  void *handle
);

/*
 * void list_attachData(list l,list_item i,void *data)
 *
 * Use
 *  Attaches a data structure to a list item.  This is a bit of an
 *  afterthought really.
 *
 * Parameters
 *  list l == the list
 *  list_item i == the list item
 *  void *data == a pointer to the data structure
 */

void list_attachData(list l,list_item i,void *data);

/*
 * void *list_getData(list l,list_item i)
 *
 * Use
 *  Returns the data attached to a list item.  The item number
 *  may have changed etc. with items deleted and added.
 *
 * Parameters
 *  list l == the list
 *  list_item i == the list item number
 *
 * Returns
 *  A pointer to the data structure attached using list_attachData().
 */

void *list_getData(list l,list_item i);

/*
 * void list_multipleSelection(list l)
 *
 * Use
 *  Makes a list able to handle a multiple selection.
 *
 * Parameters
 *  list l == the list handle
 */

void list_multipleSelection(list l);

/*
 * BOOL list_addToSelection(list l,list_item i,list_action a)
 *
 * Use
 *  Adds an item to the current selection.
 *
 * Parameters
 *  list l == the list
 *  list_item i == the list item
 *  list_action a == what to do with the state
 *
 * Returns
 *  The previous state of the item
 */

BOOL list_addToSelection(list l,list_item i,list_action a);

/*
 * void list_doForSelected
 * (
 *   list l,
 *   void (*proc)(list l,list_item i,void *handle),
 *   void *handle
 * )
 *
 * Use
 *  Performs a user-specified action for each selected list item.
 *
 * Parameters
 *  list l == the list box
 *  void (*proc)(list l,list_item i,void *handle) == the procedure to do the
 *    thing
 *  void *handle == a handle to pass to the routine.
 */

void list_doForSelected
(
  list l,
  void (*proc)(list l,list_item i,void *handle),
  void *handle
);


/*
 * void list_selectAll(list l,list_action a)
 *
 * Use
 *  Selects all the items in a list.
 *
 * Parameters
 *  list l == the list
 *  list_action a == what to do with the icons (list_READSTATE ain't all
 *    that useful, and list_TOGGLESTATE is downright wierd).
 */

void list_selectAll(list l,list_action a);

/*
 * int list_numSelected(list l)
 *
 * Use
 *  Informs the caller how many items are selected.
 *
 * Parameters
 *  list l == the list handle
 *
 * Returns
 *  An integer indicating the number of selected items
 */

int list_numSelected(list l);

/*
 * int list_itemToIndex(list l,list_item i)
 *
 * Use
 *  Translates a list_item into the index of the item.  This avoids
 *  assumptions about the mapping of indices to item numbers.  In the
 *  future, for example, the list_item data type may be used as a pointer to
 *  the list item data structure in memory.  Most of the time this will be
 *  irrelevant anyway.
 *
 * Parameters
 *  list l == the list handle
 *  list_item i == the list item to translate
 *
 * Returns
 *  An integer giving the index of the item.  The first item has index 0, as
 *  for C arrays.
 */

int list_itemToIndex(list l,list_item i);

/*
 * list_item list_indexToItem(list l,int index)
 *
 * Use
 *  Performs the reverse operation to the previous routine.  It will
 *  translate an index to a list_item.
 *
 * Parameters
 *  list l == the list handle
 *  int index == the index of the item required
 *
 * Returns
 *  The equivalent list_item for the item.
 */

list_item list_indexToItem(list l,int index);

/*
 * list_item list_helpItem(list l)
 *
 * Use
 *  Returns the item that Help is interested in.
 *
 * Parameters
 *  list l == the list's handle
 *
 * Returns
 *  A list_item
 */

list_item list_helpItem(list l);

#endif