🚀 go-pugleaf

Proposed additions to the External-Edit protocol description

There follow some PROPOSED additions to the External Edit protocol, which
should help clear up a few points,as well as add some functionality.

I would like any comments you have on these ideas before they are carved
in stone and added to the existing document.

I'm also re-writing the External edit documents from scratch to hopefully
make them more user-friendly. The result of this and the above will be posted
in a couple of weeks or so...

---

Multi-file-document handling

Some packages (e.g. Impression) use a distributed document format which does
not conform to ExtEdit's idea of a 'single datafile'.
It can be seen that placing a WYSIWYG Impression document including graphics
etc. into another document may happen in the future, and therefore it would
be sensible to have some definition laid down to cope with such an event!

In such cases, it is up to the designer of the multi-file document to provide
means for the document to be handled as a single entity. With no extra effort,
this can be achieved by never using RAMTransfers - if a document is saved to
disc, then the editor can detect the type and treat it appropriately. In cases
where RAMTransfer is desired, the designer of the data file format must
specify some means by which the data can be transferred as a single "file".

---

External edits of External edits!

A hypothetical case:
We have an impression document containing a drawfile.
We ExtEdit the drawfile out to Draw
From Draw, we ExtEdit out a sprite in the drawfile to Paint, and a text-area
to Edit.

When the data in the Drawfile needs to be returned (by user closing the draw
window or clicking save, or by an EditReturn message), what action should
Draw take?

The External Edit protocol is designed to be a "Please edit this data and
tell me when it is complete" system. Thus, no *editor* should attempt to
retrieve data that is being ExtEdit'd from within an ExtEdit document in
order to update the data it returns to it's own client.

If the reason for return will allow continued editing (User has saved, or
the EditReturn requests continued editing), then the current drawfile should
be returned as normal; Draw should *ignore* the fact that part of the data
is currently out being edited.

However, what should be done if the request demands closure of the editing
session?

*  Whatever happens, this should result in closure of all connected sessions.

Draw should:
 1 Pop up an error box much ike that for closing an unsaved document:
   "There is unreturned external data: Save/Discard/Cancel".

 2 The user clicks one of the buttons:
   a) SAVE
     This should request the return of all ExtEdit data to update the drawfile,
     and then save the drawfile back to the original client.

   b) DISCARD
     This should return the current drawfile to the client, and send ABORT
     messages to all related external editors.

   c) CANCEL
     Editing continues as normal, giving the user the opportunity to (e.g.)
     save the sprite from paint back into the drawfile, and discard the
     modified edit docment (leaving the drawfile unchanged) before closing
     the drawfile again.

My main concerns are that
 * The user doesn't lose all external-edit data without a warning,
 * The drawfile isn't automatically updated by sucking back the text and
   sprite - the user may not want to update the drawfile with the edited
   data, and this could result in unintended corruption of their document.

All this means that the user will have to do slightly more of the work
themselves, but at least

---

Cursor/selection positioning addition to ExtEdit protocols.

Definitions:
A data "unit" is the smallest useful data item represented in a document.
  examples:
    text files: units are characters
    draw files: units are objects
    Sound samples and other binaries: units are byte offsets

The "Cursor" is some kind of 'marker' which can be placed at meaningful
unit positions within the document.
  examples:
    text files: The cursor is the caret position
    draw files: The cursor denotes a single draw object (path, textarea, etc)

The "Selection" is a group of units that can be described by a range
delimited by two cursor positions.
  examples:
    text files: The selection is a series of adjacent characters
    draw files: The selection can be any contiguous linear sequence of objects
		in the file. This limits the selection slightly, but see below.

The imperative of this addition to the External Edit protocol is to allow
positioning of a text cursor in a text document (as this is the most common
case where cursor-positioning would be useful), but it is hoped that the
cursor positioning process can be generalised sufficiently that it is
adequate for other data types as well.

My proposal is the following extra message:

Message_EditCursor
  R0 = 17
  R1 + 20  Reserved
  R1 + 24  Job handle
  R1 + 28  Flag word
	   The following flags are relevant-
	     * Adjust selection (NEW flag)
	       In some cases (e.g. drawfiles) it is possible to select
	       an arbitrary number of arbitrary objects. In these cases,
	       this flag will allow an equivalent of 'mouse adjust-selection'
	       to take place.
	       If this flag is clear, then the selection will be cleared
	       and set to the given values (a 'mouse select-selection')

	     * Read-only flag
	       This can be used to alter the read-only status of the file
	       during editing (e.g. a compiler could set read-only on the
	       file during re-compilation to stop the user being able to
	       save the data to an 'open file'.)
	       To affect the read-only flag only, set all the new cursor
	       values to -1.

	     * Immediate playback
	       Exactly the same as the already-defined flag. This allows
	       you to transfer a sound or movie with an EditDataSave, but
	       delay playback until after you have selected the region you
	       want played with an EditCursor message.

  R1 + 32  New absolute cursor position
  R1 + 36  New absolute start-of-selection position
  R1 + 40  New absolute end-of-selection position

  R1 + 44  Old cursor          } These are filled in and returned by the
  R1 + 48  Old selection-start } editor if the cursor-positioning is
  R1 + 52  Old Selection-end   } successful (see below).

The positions are declared in terms of units. (e.g. text characters, or draw
objects, etc), and are *inclusive*.
Unit numbers specify an object index (1, 2, 3), or a caret position (0 = BEFORE unit 1, 1 = AFTER unit 1/BEFORE unit 2, etc)

Special values of cursor/start/end:
  -1 (&FFFFFFFF) indicates "the current value". This allows you to alter only
  one of the three positions. If -1 is used for all three values, you can
  simply read the positions without affecting them.
  In a reply from an editor, -1 indicates an invalid/undefined value.

  -2 (&FFFFFFFE) indicates "end of file". This should be used to set any of
  the three values to point to (after) the last unit of the document.

Examples:
  start =  1, end  -2:       Select entire document
  start = -1, end = 400:     Alter selection to finish at/after unit 400
  cursor = -1, start = end : Clear selection

Reading the cursor value:
Whenever an editor recieves an EditCursor message, it should fill in bytes
44-56 of the message with the current cursor values, alter it's cursor values
to reflect the new settings as closely as possible, and return this modified
message to the sender. Thus, a message with 'NEW' values of -1, -1, -1 can
be sent by the client to read the cursor only.

It won't always be possible to have a defined meaning for selections.
For example, an editor might reply to messages with cursor = <cursor_position>,
start = -1, end = -1, which indicates that either there is no selection or
the editor is incapable of returning a sensible measure of the selection in
these values.

An editor is not required to support cursor positioning or selection, but
it is desirable...

In some cases, the cursor position could be treated slightly differently:
  e.g. In a text file, the selection and caret positions are clearly defined
       entities, and relate exactly to the values used above. However, with
       Macintosh style cut/copy/paste, setting of selection and cursor are
       mutually exclusive. Therefore it is a good idea to set only the
       selections or the cursor positions at a time. An editor which can only
       support one such selection/cursor at a time should always give priority
       to the selection position (e.g. a compiler could select the line in
       error and also set the cursor to the start of the line - the selection
       is more important)

  e.g. In a drawfile, to select a single object you can use start=end. This
       makes the cursor position redundant. In this case, the cursor position
       should be treated differently: It should identify an object which is
       not to be specifically selected, but which should, if possible, be
       displayed in the center of the window by scrolling the draw window.

Thus, in any case where the cursor position is redundant, it should be used
to set a 'display position' by identifying the unit which should appear
at the center of the display window.

If you are writing an editor, please check out the definition of 'unit' for
that data type in the documents, or contact me. If it is a previously undefined
unit-type, then I can add an official meaning...
The currently suggested meanings are:
  Data:          BYTE offset.
		 (This includes data, DOS, utility, module, absolute, etc)
		 The cursor position is the same as for text (i.e. you can
		 have a caret as well as a selection)

  Text:          CHARACTER offset
		 (This includes text, obey, command, exec, etc)
		 Sorry, but to go to a specific line, you'll have to count
		 the number of characters...
		 This operates with a caret and a selection.

  Drawfile:      } Object/sprite index (i.e. "the 5th object in the file")
  Spritefile:    } These operate with a display-position + a selection.

  Sound samples: BYTE offset within the datafile. For stereo samples it will
		 be necessary to use 2 cursor positioning messages if you wish
		 both channels to be selected. 16 bit samples are also
		 accessed bytewise.
		 This operates with a display-position and a selection.

  Palette file:  Colour index (0..15 for colours 0..15, 16 onwards for
		 mouse/border colours, in the order they appear in the file)

  Alarm file:    Alarm index

  Impression:    I suppose a character offset?

  Movie files:   Frame number. A selection indicates the set of frames to be
		 played. The cursor position sets the initial frame to be
		 diplayed (e.g. cursor 1 could be used to show the title frame
		 of a movie, with a selection of 73-168 indicating which
		 portion of the movie should be played when the user clicks
		 the 'play' button.)

-- 
_________________  "I'd like to answer this question in two ways:
  /____ _ _/_ __       First in my normal voice, and then
 // / //_//_ /_/       in a silly, high-pitched whine." (Monty Python)