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

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

/*----- Overview ----------------------------------------------------------*
 *
 * Functions provided:
 *
 *   writable
 *   wrt_init
 *
 * Macros provided:
 *
 *   WRTABLE
 */

/* --- 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.
 */

extern routine writable;

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

extern routine wrt_init;

/* --- Useful constants --- */

#define wrtFlag_rAlign ((1<<8))

/* --- 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.
 */

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

#endif