Initial revision

[ssr] / StraySrc / Libraries / Sapphire / csapph / h / viewer

/*
 * viewer.h
 *
 * [Generated from viewer, 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 __viewer_h
#define __viewer_h

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

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *  viewer_create
 *  viewer_destroy
 *  viewer_open
 *  viewer_close
 *  viewer_eventHandler
 *  viewer_select
 *  viewer_isSelected
 *  viewer_selectAll
 *  viewer_click
 *  viewer_dragSelection
 *  viewer_window
 *  viewer_update
 *  viewer_setTitle
 *  viewer_rescan
 */

/* --- viewer_create --- *
 *
 * On entry:	R0 == pointer to a viewer definition block
 *		R1 == pointer to a list
 *		R2 == sprite area for window
 *
 * On exit:	R0 == viewer handle
 *		May return an error
 *
 * Use:		Creates a viewer window.  The viewer definition block
 *		contains various interesting bits of information about the
 *		viewer which are likely to be known at assembly time:
 *
 *		(word)	 address of a list manager definition block
 *		(word)	 address of a shape handler function (or 0)
 *		(word)	 standard width of icons
 *		(word)	 standard height of icons
 *		(string) banner text message tag, or empty
 *
 *		The shape function is used to allow viewer icons to have a
 *		non-rectangular shape.  The function is called with a reason
 *		code in R0; entry and exit conditions depend on this:
 *
 *							vwShape_size
 *		On entry
 *		  R1 == pointer to list item
 *		  R2 == standard width of icon
 *		  R3 == standard height of icon
 *
 *		On exit
 *		  R2 == width of this icon
 *		  R3 == height of this icon
 *
 *		Use
 *		  This routine is used to find the actual size of an icon.
 *		  The icons are aligned on a grid according to the largest
 *		  one: this routine is used to find out which one that is.
 *
 *							vwShape_intersects
 *		On entry
 *		  R1 == pointer to list item
 *		  R2 == address of bounding box of this icon
 *		  R3 == address of bounding box to compare
 *
 *		On exit
 *		  CS if boxes intersect, else CC
 *
 *		Use
 *		  For detecting mouse clicks etc. on an icon.  viewer has
 *		  already ensured that the box in R3 intersects with the
 *		  bounding box, so for rectangular icons, you can just return
 *		  with C set always.  This entry is provided so that you
 *		  can check against the sprite and text of a text+sprite
 *		  icon separately.
 *
 *		More reason codes may be added later; it will always be
 *		sensible to return immediately preserving all registers and
 *		flags.
 */

extern routine viewer_create;

/* --- viewer_destroy --- *
 *
 * On entry:	R0 == viewer handle
 *
 * On exit:	--
 *
 * Use:		Destroys a viewer, removing it from the screen etc.
 */

extern routine viewer_destroy;

/* --- viewer_open --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == opening style
 *		R2,R3 == extra arguments
 *
 * On exit:	--
 *
 * Use:		Opens a viewer window on the screen.
 */

extern routine viewer_open;

/* --- viewer_close --- *
 *
 * On entry:	R0 == viewer handle
 *
 * On exit:	--
 *
 * Use:		Closes a viewer window.
 */

extern routine viewer_close;

/* --- viewer_eventHandler --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == pointer to event handler
 *		R2 == value to pass in R10
 *		R3 == value to pass in R12
 *
 * On exit:	R1-R3 == old values
 *
 * Use:		Sets up the event handle for the viewer.
 */

extern routine viewer_eventHandler;

/* --- viewer_select --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == icon handle
 *		R2 == 0 to unselect, 1 to select or 2 to toggle
 *
 * On exit:	--
 *
 * Use:		Selects an icon, or maybe unselects it.  Whatever, it doesn't
 *		flicker if it doesn't need to.
 */

extern routine viewer_select;

/* --- viewer_isSelected --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == icon handle
 *
 * On exit:	CS if icon is selected, else CC
 *
 * Use:		Informs you whether an icon is selected.
 */

extern routine viewer_isSelected;

/* --- viewer_selectAll --- *
 *
 * On entry:	R0 == viewer handle
 *		R2 == 0 to deselect, or 1 to select
 *
 * On exit:	--
 *
 * Use:		Selects or deselects all the icons in a viewer.
 */

extern routine viewer_selectAll;

/* --- viewer_click --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == icon handle (or 0)
 *		R2 == mouse button state
 *
 * On exit:	--
 *
 * Use:		Handles a click, drag etc. according to the standard
 *		selection model.
 */

extern routine viewer_click;

/* --- viewer_dragSelection --- *
 *
 * On entry:	R0 == viewer handle
 *
 * On exit:	--
 *
 * Use:		Starts a drag of the icons within the viewer.  When the drag
 *		is finished, you get sent a vwEvent_dragged event.
 */

extern routine viewer_dragSelection;

/* --- viewer_window --- *
 *
 * On entry:	R0 == viewer handle
 *
 * On exit:	R0 == window handle
 *
 * Use:		Returns the window handle of the viewer.
 */

extern routine viewer_window;

/* --- viewer_update --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == icon handle
 *
 * On exit:	--
 *
 * Use:		Updates (redraws) a given icon.
 */

extern routine viewer_update;

/* --- viewer_setTitle --- *
 *
 * On entry:	R0 == viewer handle
 *		R1 == title string
 *
 * On exit:	--
 *
 * Use:		Sets the viewer window's title.
 */

extern routine viewer_setTitle;

/* --- viewer_rescan --- *
 *
 * On entry:	R0 == viewer handle
 *
 * On exit:	--
 *
 * Use:		Rescans all the icons in the viewer and forces a redraw,
 *		in case icons have been added or deleted (or renamed).  Note
 *		that the redraw is done *anyway* -- it's your responsibility
 *		to avoid calling this routine when you don't need to.
 */

extern routine viewer_rescan;

/*----- Shape function reason codes ---------------------------------------*/

#define vwShape_size 0

#define vwShape_intersects 1

#define vwShape_slowBit 2

/*----- Viewer event codes ------------------------------------------------*/

#define vwEvent_close 0

#define vwEvent_click 1

#define vwEvent_double 2

#define vwEvent_drag 3

#define vwEvent_menu 4

#define vwEvent_redraw 5

#define vwEvent_drop 6

#define vwEvent_help 7

#define vwEvent_key 8

#define vwEvent_dragged 9

#define vwEvent_sprite 10

#define vwEvent_open 11

#define vwEvent_draw 12

#define vwEvent_unDraw 13

#define vwDrop_save 0
#define vwDrop_load 1

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

#endif