Documentation from list.h


Introduction	[top]

ROV - Easy applications from C

Copyright - © Jason Tribbeck / 7th ARM 1994-2001

Contributing authors - Jason Tribbeck

File - list.h

Type - helper

Description

The list helper maintains a tree-based list of items within a canvas. It can be used to display a tree of a filing system, or a threaded news service viewer.

A list tree consists of one tree, which has a number of branches attached. Each node on a branch corresponds to an individual item in the tree. Nodes can have other branches attached to create a heirarchical arrangement.

To display a node, each branch has a 'print' function whose function is to render the node in a suitable format. Each node can have a handle, which the print function can use to display the node's information.

By default, all nodes are text and sprite pairs, and a default printer is available to display these.

Maintenance of the list (opening and closing of branches) is performed automatically by the list helper.

Note - This is one of the most complex helpers in the ROVLib library, and was only really used by one program. As this was written some time ago, this documentation may be incorrect in places.

Note - Since documenting, the naming of the structures is probably incorrect. Parameters to functions have been altered in this header file, but the name of the definitions remains. This will probably change.


list_tree (type definition)	[top]

Definition of a tree list
typedef void *list_tree;


list_print (function pointer)	[top]

Definition of a branch printer
Parameters:
- list_tree branch - the branch to display.
- int i - the index into the branch.
- int x - the x offset.
- int y - the y offset.
- void *h - the handle to the node's data.
- int wimpflags - standard WIMP flags for displaying the node (selected, faded).
- int fore - the foreground colour.
- int back - the background colour.
typedef void (* list_print)(list_tree branch,
			    int i,
			    int x,
			    int y,
			    void *h,
			    int wimpflags,
			    int fore,
			    int back);
See also: Introduction, draw_printf.h


list_main (type definition)	[top]

Definition of the head list.
typedef void *list_main;


list_foundlist (external variable)	[top]

The found list when clicking on a list.
extern list_tree list_foundlist;


list_founditem (external variable)	[top]

The found item when clicking on a list.
extern int list_founditem;


list_create	[top]

Create a list branch.
Parameters:
- int items - the number of items in the list.
- int flags - the flags for this list (unused)
list_tree list_create(int items,
		      int flags);


list_remove	[top]

Remove a list branch.
Parameters:
- list_tree branch - the branch to remove.
void list_remove(list_tree branch);
See also: list_clear()


list_clear	[top]

Clear a branch list
Parameters:
- list_tree branch - the branch to clear.
Note - This does not remove the memory for this branch, rather setting the number of added items to zero.
void list_clear(list_tree branch);
See also: list_remove()


list_attachlist	[top]

Attach a branch to a node in another branch.
Parameters:
- list_tree parent - the parent branch.
- int index - the node index in the parent.
- list_tree child - the child branch.
void list_attachlist(list_tree parent,
		     int index,
		     list_tree child);


list_add	[top]

Add a node to a branch.
Parameters:
- list_tree branch - the branch.
- char *text - the pointer to the text.
- void *spr_area - the pointer to the sprite area.
- char *spr_name - the pointer to the sprite name.
- void *handle - the handle for the node.
void list_add(list_tree branch,
	      char *text,
	      void *spr_area,
	      char *spr_name,
	      void *handle);


list_open	[top]

Open/close a node.
Parameters:
- list_tree branch - the branch with the node to open.
- int index - the node to open.
- int open - non-zero to open, zero for close.
void list_open(list_tree branch,
	       int index,
	       int open);


list_opened	[top]

Find out if a node is open or not.
Parameters:
- list_tree branch - the branch.
- int index - the node to check.
Returns:
- non-zero for open node.
int list_opened(list_tree branch,
		int index);


list_select	[top]

Select/deselect a node.
Parameters:
- list_tree branch - the branch with the node to open.
- int index - the node to open.
- int select - non-zero to select, zero to deselect.
void list_select(list_tree branch,
		 int index,
		 int select);


list_selected	[top]

Find out if a node is selected.
Parameters:
- int index - the node to check.
Returns:
- non-zero for selected node.
int list_selected(list_tree branch,
		  int index);


list_fade	[top]

Fade a node.
Parameters:
- list_tree branch - the branch with the node to open.
- int index - the node to open.
- int fade - non-zero to fade, zero to unfade
int list_fade(list_tree branch,
	      int index,
	      int fade);


list_faded	[top]

Find out if a node is faded.
Parameters:
- int index - the node to check.
Returns:
- non-zero for faded node.
void list_faded(list_tree branch,
		int index);


list_findselected	[top]

Find a selected node.
Parameters:
- list_tree branch - the branch to check.
- int index - to start searching from (-1 to start).
Returns:
- the next selected node index, or -1 for no more.
int list_findselected(list_tree branch,
		      int index);


list_selecteditems	[top]

Count the selected items in a tree.
Parameters:
- list_main tree - the tree to scan.
Returns:
- the number of selected nodes.
int list_selecteditems(list_main tree);


list_redrawitem	[top]

Redraw a node.
Parameters:
- list_tree branch - the branch containing the node.
- int index - the index of the node.
void list_redrawitem(list_tree branch,
		     int index);


list_changesprite	[top]

Change the sprite of a node.
Parameters:
- list_tree branch - the branch to change.
- int index - the index of the node.
- void *spr_area - the sprite area.
- char *spr_name - the sprite name.
void list_changesprite(list_tree branch,
		       int index,
		       void *spr_area,
		       char *spr_name);


list_setprintproc	[top]

Set a list print function.
Parameters:
- list_tree branch - the branch.
- list_print printer - the list printer.
void list_setprintproc(list_tree branch,
		       list_print printer);
See also: list_print


list_sethandle	[top]

Set the handle for a node.
Parameters:
- list_tree branch - the branch.
- int index - the node index.
- void *handle - the handle.
void list_sethandle(list_tree branch,
		    int index,
		    void *handle);


list_height	[top]

Get the height of the list.
Parameters:
- list_main tree - the tree to get the height of.
Returns:
- the height of the tree in OS units.
int list_height(list_main tree);


Attach a list to a canvas.	[top]

Parameters:
- branch - the main branch.
- c - the canvas.
- name - the name of the tree.
- spr_area - the sprite area.
- spr_name - the name of the title sprite.
- fore - the foreground colour.
- back - the background colour.
- grey - the greyed out colour.
- x - the (canvas) left hand coordinate of the list.
- y - the (canvas) top coordinate of the list.
Returns:
- the created tree.


list_reattach	[top]

Change the attachment of a list
Parameters:
- list_main tree - the tree to change.
- list_tree branch - the new parent branch.
void list_reattach(list_main tree,
		   list_tree branch);


list_draw	[top]

Draw a portion of a list.
Parameters:
- list_main tree - the tree to redraw.
- int x0 - the (canvas) left hand coordinate.
- int y0 - the (canvas) bottom coordinate,
- int x1 - the (canvas) right hand coordinate.
- int y1 - the (canvas) top coordinate.
Note - this is done during the canvas redraw.
void list_draw(list_main tree,
	       int x0,
	       int y0,
	       int x1,
	       int y1);


list_findlist	[top]

Find the branch of an item.
Parameters:
- list_main tree - the tree.
- int y - the (canvas) y coordinate.
Returns:
- the branch.
list_tree list_findlist(list_main tree,
			int y);
See also: list_finditem(), list_handle()


list_finditem	[top]

Find the node in a branch.
Parameters:
- list_tree branch - the branch..
- int y - the (canvas) y coordinate.
Returns:
- the node index.
Note - Normally called after list_findlist().
int list_finditem(list_tree branch,
		  int y);
See also: list_findlist(), list_handle()


list_handle	[top]

Get the handle of an item.
Parameters:
- list_tree branch - the branch.
- int index - the node index.
Returns:
- the handle.
Note - Normally called after list_finditem().
void *list_handle(list_tree branch,
		  int index);
See also: list_finditem(), list_findlist()


list_handleclick	[top]

Handle a canvas click event.
Parameters:
- list_main tree - the tree.
- canvas_mousestr *mouse_str - the mouse event.
Returns:
- how the list handler handled the event.
Note - Normally called in a canvas click event handler.
int list_handleclick(list_main tree,
		     canvas_mousestr *mouse_str);
See also: List click handler event codes, canvas.h


list_items	[top]

Return the number of items in a branch.
Parameters:
- list_tree branch - the branch.
Returns:
- the number of nodes.
int list_items(list_tree branch);


list_ycoordinate	[top]

Get the y coordinate of a node.
Parameters:
- list_tree branch - the branch.
- int index - the node index.
Returns:
- the bottom y coordinate offset from the top of the list.
int list_ycoordinate(list_tree branch,
		     int index);


list_deselectall	[top]

Deselect all items in a branch.
Parameters:
- list_tree branch - the branch to deselect.
void list_deselectall(list_tree branch);


List click handler event codes	[top]

#define LIST_NOTHANDLED (-1)
#define LIST_HANDLED (0)
#define LIST_OPEN (1)
#define LIST_CLOSE (2)
#define LIST_LOAD (3)
#define LIST_SELECTED (4)
#define LIST_UNSELECTED (5)
#define LIST_FORCEOPEN (6)

Generated Thu Feb 7 23:22:51 2002

Documentation from list.h

Introduction

ROV - Easy applications from C

Description

list_tree (type definition)

list_print (function pointer)

list_main (type definition)

list_foundlist (external variable)

list_founditem (external variable)

list_create

list_remove

list_clear

list_attachlist

list_add

list_open

list_opened

list_select

list_selected

list_fade

list_faded

list_findselected

list_selecteditems

list_redrawitem

list_changesprite

list_setprintproc

list_sethandle

list_height

Attach a list to a canvas.

list_reattach

list_draw

list_findlist

list_finditem

list_handle

list_handleclick

list_items

list_ycoordinate

list_deselectall

List click handler event codes