Initial revision

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

pendent extension colours.
	   R8=Window block to read from / 0 for default (!Config) settings.
	\X R0=colour value read / old value if writing it. This is of the
	      form &BBGGRRZZ as above.

Zap_FindInput
This call works out the current position of the 'input focus' in a window. If
the input caret is in this window then it returns it's offset. Otherwise it
returns the 'point' position (usually marked by an empty square).
	\E R8/R9
	\X R0=most suitable offset to insert data.

Zap_ClipCache
This call moves the cache reference point (w_cline/coff/clogl etc) to a given
point (using e_clnoff).
	\E R0=Offset in line to move the cache reference point to. R8/R9

Zap_ModeData
This call reads or write the mode dependant options that Zap handles
automatically for you. See also Zap_ModeColour. Currently there is only one
word per mode storing the width and things like whether auto-indent is on or
not. You should use this call with R8=0 to write sensible default values if
your mode starts up and finds its mode word is zero. If you don't then the
default Text mode values will be used.
	\E R0=value to write / -1 to read
	   R1=mode number
	   R2=variable number to read write
	   R8=window concerned / 0 for the default (!Config) settings.
	\X R0=variable value if read / old value if written
	Variables num:	0	b0-b15  stores the "width" for this mode
				b16	auto indent bit (b16 of w_format)
				b17	auto width bit (b6 of w_flags)
				b18	strip spaces bit (b18 of w_format)
				b19-b21 tab mode bits (b9-b11 of w_flags)
					b19-b20 0=Unix 1=Edit 2=Coltab
					b21=insert tabs as spaces
				b22	hex entry mode bit (b5 of w_flags)
				b23	overwrite bit (b1 of w_flags)
				b24-b31	display bits (b8-b15 of w_format)
					b24=line numbers shown
					b25=line numbers as lines (not addr)
					b26=line numbers in hex
					b27=logical line nums (not physical)
					b28-29 0=no tabs 1=spaces 2=> 3=->
					b30=line edit paradigm
					b31=non standard editing
			1	b0-b2	Line number width
				b3	Line number colons
				b4	Internal use : font sub-styles off
				b5	Infinite window wrap
				b6	Use line selection paradigm
				b7	Spell-as-you-type
				b8	Big endian	    (b17 of w_format)
				b9	Reserved
				b10	Reserved
				b11	Reserved
				b12	Set if linewrap mode on	(b26 w_flags)
				b13	Set if wordwrap mode on	(b13 w_flags)
				b14	Reserved
				b15	Reserved
				b21	Free mouse clicks   (b21 of w_format)
				b22	Auto soft wrap	    (b22 of w_format)
				b23	Confined cursor U/D (b23 of w_format)
				b24	Confined cursor ->  (b24 of w_format)
				b25	Smart shift-cursor  (b25 of w_format)
				b26	Window-wrap	    (b26 of w_format)
				b27	Soft-wrap	    (b27 of w_format)
				...other bits reserved...
			2+	reserved.

Zap_WhichMode
This call decides which mode a given file should be displayed in.
	\E R0=load address of file (containing the filetype)
	   R1=filename pointer / 0 if not known
	      b31=flag to determine the meaning of R10 on exit
	\X R0=address of a data block of info about this file mode. 
	   R10=If b31 of R1 was clear on entry then this is the mode number
	       of the default mode the file is loaded into (the mode is
	       loaded if necessary). If is was set then this is a pointer
	       to the mode name (mode not necessarily loaded).

Zap_ModeNumber
This calls turns a mode name (given by a string) into a mode number. The mode
is loaded if not already resident in memory.
	\E R0=mode name string terminated by <= space (&20)
	\X R0=mode number or -1 if not found.

Zap_SendDataSave
This call initiates the save protocol, saving data to another window or
application via RAM transfer or WimpScrap. It sends the data_save message and
all replies are handled automatically.
	\E R2=proposed file/leaf name of the data (or 0 to use the file's)
	   R3=destination window handle or task handle
	   R4=destination icon handle (if R3=-2)
	   R5/R6=destination mouse coords (if applicable)
	   R7=routine to call after save finished (or 0 if none).
	   R8/R9=R8<>0 => Save whole file R8=window block R9=file block
		 R8=0  => Save currently selected region.
		 (or set b1 of R10 to save an arbitrary region).
	   R10=b0-b15 flags:
	       b0 set => External edit flag. In this case R3=ext edit
			 job handle and R4=ext edit task handle and
			 external edit message sent instead.
	       b1 set => R8=start address of data to save
			 R9=size of the data to save
			 b16-b31 of R10=filetype of data to save.
	       b16-b31 = extra data (see b1)
	   R11=data to pass to routine in R7 (if used).
	\X Data transfer protocol initiated.
	Sub pointed to by R7 is called with R11 as passed above and should
	preserve R1+ as usual.

Zap_Warning
Warns the user without generating an error. This opens a window with the
given message and pauses for the message to be seen before returning. Wimp
Poll is not called.
	\E R0=warning message
	   R1=time to leave message open in cs (0 for default delay)
	      + flags:
		b31 => Don't beep when opening the window
	   R8/R9=window in which to show the warning.

Zap_AllWindow
Calls a given subroutine once for each valid Zap window. See also
Zap_EachWindow.
	\E R0-R7=arguments to pass to the sub
	   R10=address of the sub to call (which must preserve all registers
	       except R0, and is called once for each window with R8/R9
	       set up to be that window).

Zap_ReadMenu
Converts a text file of the same format of Zap's 'Menu' file into a Zap menu
structure.
	\E R0=start of a zero terminated menu text file (stored in memory)
	\X R0=pointer to heap block containing the following information
		#0 Number of valid menu handles for this file (first
		   number appearing in the file)
		#4 Pointer to the menu structure (in Zap-Wimp format) for
		   handle 0 (or 0 if handle 0 not used)
		#8 Pointer to structure for handle 1
		#12 Pointer to structure for handle 2 etc.

Zap_LoadMenu
Converts a text menu file to a Zap menu structure.
	\E R0=pointer to filename of the menu file
	\X R0=list of menu handles as for Zap_ReadMenu

Zap_OpenMenu
Opens a menu on the screen. The menu structure is handled automatically once
it has been opened.
	\E R1=pointer to Zap-Wimp menu structure
	   R2=mouse x to open at
	   R3=mouse y to open at
	   R8/R9=window the menu is being opened on or 0's for none (eg the
		 iconbar menu).

Zap_CallBack
Schedules a subroutine to be called again at a certain time but using wimp
null events.
	\E R1=(earliest) monotonic time to call back at (>0)
	      or -(smallest delay before calling back) =< 0.
	   R2=address of routine to call.
	   R3=data to pass to the routine in R11.
	The routine pointed to by R2 has conditions:
	 \E R1=current time R11=value passed in R3
	 \X (must save R1+ as usual)

Zap_DragBox
Starts a wimp drag box making sure you get called when it's finished.
	\E R0=b0 set if you wish to be called repeatedly during the drag
	      b1+ reserved (set to 0)
	   R1=drag box block to be passed to Wimp_DragBox
	   R2=address of routine to call.
	   R3=data to pass to the routine in R11.
	The routine pointed to by R2 has conditions:
	 \E R0=reason code 1=drag in progress 2=drag has just finished
	    R1=drag box posn as returned by wimp if R0=2
	    R11=value passed in R3
	 \X (must save R1+ as usual)

Zap_SendMessage
Sends a wimp message and logs the message number (my_ref) so that any reply
can be forwarded to you. The message reference is held for at least a minute
and only deleted on a null event.
 E R0=b0-b27 message action number (to go in R1,#16)
      b28    set if you are interested in the reply.
      b29    set if you want to be called when message deleted
      b30-31 00 => Just send the message (with code 17)
	     01 => Just acknowledge the message (with code 19)
	     10 => Send the message recorded (with code 18) and call the
		   reply code if the message replied to.
	     11 => Send the message recorded (with code 18) and call the
		   reply code if the message replied to or bounces.
   R1=message block
   R2=dest task handle/window handle
   R3=b31 clear => This is the message length (is rounded up to next word)
      b31 set	=> This is the offset of a string ending the message.
   R4=icon handle if R2=-2 (iconbar) [not used otherwise]
   R5=address of routine to call when message replied to [if b28 of R0]
      (zero as a value means that you want any replies to be dealt with
       as if they were normal messages and not a reply)
   R6=private word to pass to routine on a reply [if b28 of R0]
 X The message is sent as an original message. Hence the my_ref, length
   and message action fields are filled in for you. R0=task handle of the
   dest task (R2 on exit from Wimp_SendMessage)
	Routine in R5 called with:
		;E R0=message type
			0 => message being removed from log list (see b29)
			17 => message replied to as normal
			19 => message bounced
		   R1=message block
		   R2=message number (R1!16) R11=private word R12=Zap's etc
		;X You can corrupt R0-R11 if R0=17,19
		   You should save R1-R11 if R0=0

Zap_Reply
Replies to a message. It copies my_ref to your_ref for you can reads the task
handle of the task to reply to from the message block. The length word is
assumed to be unchanged.
 E R0=message action number (as for SendMessage)
   R1=message block (with ref etc)
   R5/R6=routine to handle the reply if b28 of R0 (as for SendMessage)

Zap_Extend
Changes the size of a heap block, making it smaller or bigger as for OS_Heap
with the extend action code.
 \E R0=pointer to the heap block R1=signed change in the size
 \X R0=new heap block pointer (it may have moved)

Zap_ModeColourNum
Reads/writes the size of the colour palette used by a given mode. Maximum
size of a palette is currently 256 colours. Use R8=0 to read the default
values. NB If you enlarge the palette then please write some sensible values
for the new entries!
 \E R0=new size of palette (in number of colours) / -1 to read
    R1=mode number R8/R9=window or R8=0 for the default options.
 \X R0=old size / read size.

Zap_CreateThrowback
Creates a throwback buffer ready for lines being inserted by Zap_Throwback.
 ;E R0=suggested width of window / 0 to use default width
 ;X R0=window offset of window R8/R9=newly created throwback window

Zap_Throwback
Inserts a line in a throwback file for you.
 \E R0=file offset or line number of line with info on it
       set b31 to suppress this being printed automatically.
    R1=filename (of the file that R0 is an offset in)
    R2=information string to print after the line number (eg "Bad syntax")
    R3=string to precede filename  (eg "Errors in file:")
    R4=file offset of linked file / -1 if may not be loaded
    R5=flags to use for the new entry (see f_links,#12)
    R6=string to precede new info block (eg "Line num  Error")
    R7=string to go after filename (eg 10,"Search string: fred")
    R8/R9=throwback window to add entry to
 \X Throwback entry added and new title block given if file (or flags)
    have changed KB #
    The line number field is 10 characters wide if not suppressed.

Zap_TestModeName
This calls determines whether or not a given mode is loaded. It returns
the mode number of the given mode or -1 if the mode is not loaded.
	\E R0=mode name string terminated by <= space (&20)
	\X R0=mode number or -1 if not loaded.

Zap_UpdateArea
Forces an immediate redraw of a window area. The area in given in x,y
character col, row coordinates.
	\E R1=redraw block (as for Wimp but in character coords -
	      ie window handle, min x col, min y row, max x col, max y row)
	   R8/R9 = window
	\X Coordinates in R1 changed to OS coords and window updated

Zap_UpdateWindow
Forces an immediate redraw of a window area. Entry and exit as for
Zap_UpdateArea except that coordinates are given in Window work area
OS coords. (Internally UpdateArea calls UpdateWindow after coordinate
conversion).

Zap_UpdateWholeWindow
Force immediate redraw of the whole window
	\E R8/R9 = window

Zap_AllFiles
Calls a given subroutine once for each valid Zap file. See also
Zap_AllWindows and Zap_EachWindow.
	\E R0-R7=arguments to pass to the sub
	   R10=address of the sub to call (which must preserve all registers
	       except R0, and is called once for each file with R9 set up
	       and R8 = 0.

Zap_ReadValidateCommand
Translates a string into an executable block of command information.
	 E R10=pointer to string terminated by <&20
	 X R0=-1 => args invalid (only tested if command loaded)
	      0  => all ok
	      1  => args valid for keymaps only (uses n form)
	   R1=parameter
	   R6=parameter type 0=none 1=num 2=usekeynum 3=stringblock 4=data
	   R7=command address
	   R10 updated to next non-white space which is not a ':'
	   CS if an external module has been loaded as a consequence
	   CC otherwise.
	   Error is generated if the command cannot be found.
	   (String of commands concatenated to a single Multicommand)
	   (:<return> skipped so can have multiple lines)

Zap_ProcessKeyCommand
Calls a command using the same routine as used when a command is bound to a
key.  For use mainly with Zap_ReadValidateCommand.
	 \E R0=data => The byte/word if mode 1/2 and ptr to data if mode 3+
	    R2=call type with learn flag (usually 0)
	    R7=command address
	    R8-R10=window/file/cursor or 0
\X Command called once with R1=1

Zap_ReturnWord
Calls the text mode e_returnword entry with given delimiters. This is mostly
of use to commands such as SelectUntil.
	\E R0=flags
	      b0 => list are non-delimiters not delimiters
	      b1 => control characters form an implicit list
	      b2 => control characters are non-delimiters not delimiters
	   R1=list
	\X R0=file offset
	   R1=length

Zap_DoReplaceArea
Acts like Zap_ReplaceArea, only does not involve the mode, i.e. it uses
Zap_DoCommand, rather than Zap_Command.
	\E R1=file offset of original data
	   R2=length of original data
	   R3=address of replacement data
	   R4=length of replacement data R9
Calls Zap_ReplaceArea with R8=0

Zap_LogicalLine
Replaces e_clnlog in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_clnlog:
	\E R0=logical line number R8/R9
	\X R0=file offset of line start
	   R1=physical line number

Zap_PhysicalLine
Replaces e_clnphy in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_clnphy:
	\E R0=physical line number R8/R9
	\X R0=file offset of line start
	   R1=logical line number

Zap_OffsetLine
Replaces e_clnoff in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_clnoff:
	\E R0=file offset R8/R9
	\X R0=physical line number
	   R1=file offset of physical line start
	   R2=logical line number

Zap_NextLine
Replaces e_nextline in a manner which allows processing of the returned
parameters.  Entry and exit conditions are exactly as for e_nextline:
	\E R0=file offset of first 'shiftable' character
	   R1=signed change in file offset of this character R8/R9
	\X R0=file offset of first 'shiftable' line
	   R1=physical line number of this line #
	   You must preserve the split offset and split size of the file.

Note that in the above four calls, the mode called is the mode specified by
the window block in R8.  Calling the entry points of arbitrary modes is
currently only possible with this mechanism by manually poking the mode
number in temporarily.