🚀 go-pugleaf

The following is an outline of an idea I am working on for inclusion into
DSEdit II. It is very useful for DSEdit, but it can be easily generalised to
work with proctically any editor application.

Thus, I am posting this outline so that you may offer any helpful
suggestions and ideas for improvement before I fix the message data
format, and request the message numbers from Acorn.

It currently lies in the format I need for DSEdit, plus a couple of extra
bits of functionality that sound nice. I do not want to complicate it any
more if it can be helped!

(In fact, I may remove bits such as the menu system to simplify it a bit)

---

XEdit external data editing protocol
====================================

Those people who have used UNIX a bit will have encountered a very
useful feature of it - when any program needs to edit a text document,
it simply saves that document to a temporary file, and invokes a text
editor on the file. When the text editor finishes, the application
re-loads the (changed) temp. file, and continues.

This has two distinct advantages-
  * The main application doesn't have to include all the text-editing code
  * The user can choose exactly the text editor that they want to use
    and that one is used *globally*.

(Anybody who has used programs like Macromind Director and Hypercard on
the Macintosh may have noticed that BOTH of them include their OWN bitmap
editors, NEITHER of which are very good - many people would far prefer
to edit their bitmaps with the functionality of SuperPaint 3 but without
having to then "export/import" the data from Superpaint to MM director
by hand...)

On the Archimedes, a similar concept would be useful: if you have some data
in a standard format (text, sprite, drawfile, etc) that needs to be edited,
then you should just be able to invoke another application to go away
and edit that data, and return the data to you when the editing is finished.

This is *similar* to hotlinking, but much simpler - the data is set out
as a single chunk, and _some_time_later_ is brought back in as a single
chunk. This can be used in ways like the following:

 * A compiler that allows you to edit and re-compile a program from within a
   text-editor window.
 * A desktop publisher that "farms out" it's draw-file illustrations to
   a drawing package for editing.
 * A Sound-Tracker song editor that displays (and allows you to edit) it's
   instrument samples via a digitised sample editor's windows.
 * A drawfile editor that allows you to edit the text from text areas in
   a normal text editor window.
 * An adventure authoring system that lets you edit descriptions in a
   fully-blown text editor window, and edit pictures in a fully-blown
   sprite or draw file editor window, while only having to provide the
   location/object editing functions by itself.
 * A configuration/preferences application with a special configuration-file
   format could be used to set all preference options for ALL running
   applications that support this message system - Thus a central,
   consistent configuration interface system is available, rather than
   each application including code to supply preference options in its
   own (usually different) interface style and method.
 * "True colur" menus such as in paint and draw, for setting palette values
   could be supplied by an editor: One that would allow users to
   use HSV or CIE or RGB or CMYK or a rainbow-colour-picker, in order to
   mix the RGB colour that the client application wants.

To so this properly would require large alterations and additions to the
operating system and each application that used the new system. However,
a simpler method is possible, which gives a very usable amount of
functionality, without requiring too much extra effort by application
authors.

Two applications are involved in the process: An editor (which supplies the
window and editing functions), and a client (which initiates the edit, and
possibly supplies data to the editor and/or expects data back from the editor
later)

*  When the user drags a text file to (eg) the compiler icon, it needs to
   load and display the text in an editor window. It broadcasts a message
   requesting an editor (for text).

*  The text editor, if present, opens a window, and replies to the client
   (compiler) giving the window handle of the new editor window.

*  The client can, if it wishes, now send a DataLoad or RAMtransmit message
   to that window to load the initial file for editing.

*  The user edits the file, and when finished, indicates to the compiler
   that they wish to recompile the file, at which time a RAMtransfer is
   started TO the client, *as if* to the window handle returned during
   setup.
   Alternately, the user can click on the editor window's close icon,
   in which case the editor saves the data back to the client either
   with a RAMtransfer or file transfer.

Although the UNIX concept of "Take this file, edit it and then give it back"
is very useful, we can pretty simply extend the functionality slightly to
allow the client to get a bit more control.

In order to allow the client to add functions to the editor within the
shared window, we allow it to add a menu tree to the main menu that the
editor displays in the editing window.
  For example, we might add:
    Compile => Check Syntax
	       Compile
  to the bottom of the Editor menu, allowing the user to indicate to the
  compiler that editing is finished and the action to apply to the
  completed data is to Check its syntax or compile it completely.

This is achieved in the following way:
  When initiating the xedit, the client specifies the name of its submenu.
  Whenever the editor creates a menu over the shared window, it adds this
  submenu name to the bottom of the menu (with a dotted line above), and
  turns on "Menu Sublink warning" messages.
  (The submenu is an optional device which can be ignored by either party,
  though it is preferable that the editor supports it)

  When a MenuWarn message is recieved for this option by the editor, it
  echoes the message to the client, so that the client may construct the
  remainder of the menu tree.
  When a menu choice is made on this submenu, the editor echoes the message
  to the client, so that the client may decide on the action to perform.

The message protocol that I suggest is the following:

XEdit_OpenWindow
  Broadcast from client to all editors, requesting a window
  This message would include the following data:
    * A word containing the type of editor window to be supplied - these
      values will be allocated to editor applications on request.
      For example,
       text files: 0xfff, draw files: 0xaff, sprite files: 0xff9, etc.
      (Special types of files, i.e. FooApp internal FooData file can be
      given unique (centrally-registered) values above 0xffff)

    * The name of the parent document (the document which contains the
      data being edited), and the suggested leaf filename of this file.
      Ideally, the editor will make a title-bar string of
	(Parent) Filename
      and put "Filename" into the save-as dialogue.
      This indicates to the user where the data they are editing belongs
      (e.g. Inside the DTP document "Thesis" as a drawing called "Figure1")
      -of course, the editor can just use the leafname as normal if it
      doesn't wish to support the full protocol.

    * The title to place at the end of the main editor menu. A blank
      title indicates that no submenu is required.

XEdit_OpenWindowAck
  If an editor can supply the requested service it opens a window, and then
  replies to the client, indicating in the message:
    * The window handle of the window involved. This is used as a unique
      "job identifier" in all following transactions. It also allows the
      client to move the window over the parent document window or something
      if that is desired. (It is also a good value to use, as the client
      can detect if the window has been deleted and stop expecting the
      edited data to be returned)

    * Possibly some information on where the client's menu structure starts
      in the editor's menu structure, so that a normal menu hit can be
      correctly decoded by the client (i.e. it can find where the hit
      details for it's own menu structure start). I think that this menu
      option should always be the last option on the main (root) menu, so
      this will probably be a single word indicating the main-menu item
      from which the client menu stems.

  If the client does not recieve an OpenWindowAck, then they can:
    * Open their own window with perhaps a limited editing service
    * Give an error like "Text editor needed for this operation"
    * Broadcast another OpenWindow message requesting an editor for a more
      general form of the data (e.g. you could request that your text-file
      be edited as C source code, and failing that, simply request any text
      editor that is available)

Loading Initial data:
  The client sends a normal RAMtransfer or DataLoad message to the editor
  window (as if the user has dragged and dropped an icon into it).
  This will cause the editor to load the file as normal.

Saving data back to client:
  The editor can initiate this (for example, if "save" is clicked to save the
  file back to "where it is", rather than dragging the icon to a filer window)
  by initiating a RAMtrnsfer/DataLoad to the client, with the destination
  window handle being the shared window handle.
  If the editor window is closed (or document removed in situations like
  Impression doc's where window-closing doesn't close the document) then
  the editor will start a RAM/disc transfer of the file back to the client.

  The client can also request that the editor save back to it with
XEdit_RequestData
  Which may include a flag indicating "Request whole file" and "request
  selection", so that operations (e.g. help) can be performed on a selected
  item.
  It will also include a "transfer only" or "transfer and close" flag.

  This is intended so that the client can get a *copy* of the data
  when a menu item is clicked (e.g. a copy of the data to "check syntax" on)
  without necessarily also closing the window.

MenuWarn and MenuChoice events for the client submenu (if any) will simply
be echoed to the client by the editor. The client can then create a submenu
or decode their submenu, and take appropriate action. (I think this will
work OK, but I've never tried having 2 app.s creating parts of the menu tree
- will it work?)

Closing the connection
  If either party wishes to close the window (thus ending the shared editing
  session), they send a normal CloseWindow event to their opposite. (So if
  the client recieves a closewindow event, it must check if it actually owns
  the window before deciding whether to call Wimp_CloseWindow)

  If either party wishes to close the connection they should:
  (to pass back the edited data and close): Send a RequestData (client) or
  RAM/disc transmit (editor), followed by a normal CloseWindow request msg.
  (to close window and discard changes): Send a closewindow.

---

So does anyone have any interesting comments or suggestions? (Bearing in
mind, of course, that I intend to go ahead with at least the base level of
this protocol that I require for DSEdit II... so don't bother trying to
dissuade me! ;-)

Note: I realise that this sort of thing *might* be easier using Impulse II.
However, I do not want to rely on 3rd party modules to implement things
if it can be helped, and the message passing system in RISC OS Lib is
perfectly adequate for the protocol I wish to add.

Oh, and the last comment: Once designed, this protocol will be "freeware",
i.e. you won't have to pay some large company some awful price to use
their proprietary (and incompatible with everyone else's proprietary)
hotlinking system, as I believe may be the case with one hotlinking protocol
that comes to mind... These things should be freey usable, so that we get
ONE standard system for doing them if at all possible. It really needs
Acorn to support ONE GOOD system for these things (i.e. in ROM) I guess...

-- 
_________________  "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)