;
; viewer.sh
;
; Filer-like windows with re-arranging icons
;
;  1995-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:
;
;  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

		[	:LNOT::DEF:viewer__dfn
		GBLL	viewer__dfn

; --- 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.

		IMPORT	viewer_create

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

		IMPORT	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.

		IMPORT	viewer_open

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

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	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.

		IMPORT	viewer_dragSelection

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

		IMPORT	viewer_window

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

		IMPORT	viewer_update

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

		IMPORT	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.

		IMPORT	viewer_rescan

;----- Shape function reason codes ------------------------------------------

		^	0
vwShape_size	#	1			;Read an icon's size
						;Entry:	R1 == list item
						;	R2,R3 == std size
						;Exit:	R2,R3 == actual size

vwShape_intersects #	1			;Does icon intersect box?
						;Entry:	R1 == list item
						;	R2 == ptr to icon box
						;	R3 == ptr to box
						;Exit:	CS if intersect

vwShape_slowBit	#	1			;Does icon need slow redraw
						;Entry:	R1 == list item
						;	R2 == ptr to icon box
						;	R3 == ptr to box

;----- Viewer event codes ---------------------------------------------------

		^	0
vwEvent_close	#	1			;User has closed the window

vwEvent_click	#	1			;User has clicked an icon
						;R1 == icon handle (or 0)
						;R2 == mouse status

vwEvent_double	#	1			;User has double-clicked
						;R1 == icon handle (or 0)
						;R2 == mouse status

vwEvent_drag	#	1			;User has dragged the mouse
						;R1 == icon handle (or 0)
						;R2 == mouse status

vwEvent_menu	#	1			;User has clicked menu
						;R1 == icon handle (or 0)
						;R2 == mouse status

vwEvent_redraw	#	1			;Redraw a viewer icon
						;R1 == icon handle
						;R2 == pointer to coords blk
						;R3 == pointer to clip blk
						;R5,R6 == window origin

vwEvent_drop	#	1			;File dropped on the viewer
						;R1 == filetype of data
						;R2 == estimated size
						;R3 == address of filename
						;R4 == drop type

vwEvent_help	#	1			;Help request for the viewer
						;R1 == icon handle, or 0

vwEvent_key	#	1			;Key pressed
						;R1 == key code (translated)
						;Return CS if used, else CC

vwEvent_dragged	#	1			;Icons dropped on a window
						;R1 == destination window
						;R2 == destination icon

vwEvent_sprite	#	1			;Return sprite name to use
						;Entry:	R1 == icon handle
						;	  (-1 for many)
						;Exit:	CS if sprite found,
						;	R0 == ptr to spr area
						;	R1 == pointer to name
						;	else CC

vwEvent_open	#	1			;The viewer has been moved
						;R1 == ptr to open/state blk

vwEvent_draw	#	1			;Fully draw icon
						;R1 == icon handle
						;R2 == pointer to coords blk
						;R3 == pointer to clip blk
						;R5,R6 == window origin
						;(Event only used by gallery)

vwEvent_unDraw	#	1			;Undraw temporary part
						;R1 == icon handle
						;R2 == pointer to coords blk
						;R3 == pointer to clip blk
						;R5,R6 == window origin
						;(Event only used by gallery)

		; --- Drop event subreason codes ---

		^	0
vwDrop_save	#	1			;File from another app
vwDrop_load	#	1			;File from filing system

		]

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

		END
