;
; writable.sh
;
; Writable dialogue boxes
;
; © 1994-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:
;
;   writable
;   wrt_init
;
; Macros provided:
;
;   WRTABLE

		[	:LNOT::DEF:writable__dfn
		GBLL	writable__dfn

;+		LIB	sapphire:^.bsh.stdDbox

; --- writable ---
;
; On entry:	R0 == pointer to writable dialogue block
;		R1 == pointer to default string to display, or 0 for null
;		R2 == pointer to routine to call when string set
;		R3 == value to pass to routine in R10
;		R4 == value to pass to routine in R12
;
; On exit:	R0 == dialogue handle of created dialogue box
;		May return an error
;
; Use:		Displays a writable dialogue box, i.e. one with a writable
;		icon and OK button, used instead of writable menu items,
;		for reasons to do with caret blinking and pointer changing.
;
;		The writable dialogue block consists of:
;
;		Size	Meaning
;		~~~~	~~~~~~~
;		4	Flags (see below)
;		n	Validation string to use, may be null
;		m	Title string (message tag) to display
;
;		The flags are:
;
;		Bit	Meaning
;		~~~	~~~~~~~
;		0-7	Maximum string length
;		8	Right align text in writable icon
;		9-31	Reserved; must be 0
;
;		The routine returns a dialogue handle because you may want
;		to attach a numWrite control to the writable icon, which
;		is icon number 0.
;
;		The handler routine is passed:
;
;		R0 == pointer to string typed in
;		R1 == dialogue box handle (for numWrite again)
;		R10, R12 as set up here
;
;		It must preserve all registers.  If the carry flag is set
;		on exit, the dialogue box will not be closed.  If it is
;		clear, the dialogue may be closed depending on the button
;		status.
;
;		Note that this routine does *not* require a template --
;		a suitable window is generated at run-time.

		IMPORT	writable

; --- wrt_init ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Initialises the writable dialogue box for use.

		IMPORT	wrt_init

; --- Useful constants ---

wrtFlag_rAlign	EQU	(1<<8)			;Right align text in icon

; --- Macro: WRTABLE ---
;
; Arguments:	len == maximum string length to allow
;		flags == other flags to set
;		valid == (optional) validation string
;		title == title message tag string
;
; Use:		Builds a writable definition block.

		MACRO
$label		WRTABLE	$len,$flags,$valid,$title
		ALIGN
$label
		DCD	$len :OR: $flags
		DCB	"$valid",0
		DCB	"$title",0
		MEND

		]

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

		END