home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / documentation / documents / extedit102 / Text%a0Only / EE-text < prev   
Text File  |  1992-12-31  |  44KB  |  977 lines
  1.                          The External Data Editing Protocol
  2.                       Designed and Moderated by Jason Williams
  3.  
  4.                        Document version 1.02, 1 January 1993
  5.                                   (text version)
  6.  
  7.  
  8. Introduction
  9. ============
  10.  
  11. The right idea
  12. Those people who have used command-line UNIX a bit will have encountered a
  13. very useful  feature of it - when any program needs to edit a text document,
  14. it simply saves that  document to a temporary file, and invokes a text
  15. editor on the file. When the text editor  finishes, the application re-loads
  16. the (changed) temporary file, and continues.
  17.  
  18. The wrong idea
  19. Using Macromind Director and Hypercard on the Macintosh, I noticed that they
  20. both include   their own bitmap editor sections. These editors are both very
  21. bad. SuperPaint 3 is very good, however: It would be nice if Superpaint
  22. could be installed as the  “bitmap editor section” of the other programs.
  23. Superpaint could then be used as a shared  bitmap-editor resource, and the
  24. user gets a good bitmap editor (of their choice) for use within  the other
  25. programs.
  26.  
  27. This is the story of a new protocol for the Archimedes that allows us to do
  28. something very  similar to the UNIX-based idea mentioned above, only on the
  29. desktop... 
  30.  
  31. Using a separate data editor has distinct advantages-
  32. • The main application doesn’t have to include all the editing code
  33.   (very useful,  especially when multitasking several similar applications
  34.   alongside each other - the  editor is a shared code resource)
  35.  
  36. • The editor code need only be resident in memory/executing while it is needed.
  37.  
  38. • The user can choose exactly the editor that they want to use and that one
  39.   is used  globally.
  40.  
  41. • The main application can include support for data types of which it knows
  42.   relatively  little, relying on the editor to provide that support.
  43.   The editor and even the layout of the data file format can therefore be
  44.   improved and  augmented without having to update the main application.
  45.  
  46. • The ‘editor’ does not have to supply editing functions. It could, for
  47.   example, be a  program that simply displays the data − allowing the user to
  48.   read some text, view or  play a sound sample, or watch an ARMovie.
  49.  
  50. This is similar to hotlinking, but much simpler - the data is set out as a
  51. single chunk, and some  time later is brought back in as a single chunk.
  52.  
  53. The following are some examples of uses for the protocol − once you start to
  54. think about it,  more uses become apparent... in fact, you can do some
  55. pretty impressive stuff with such a  simple idea:
  56.  
  57. • A compiler that allows you to edit and re-compile a program from within a
  58.   text-editor  window. This would augment the current “throwback” interface to
  59.   allow the compiler  to actually open the text editor window on the
  60.   file-in-error, and automatically  re­compile the code when the user has
  61.   finished re-editing the file.
  62.  
  63. • A desktop publisher that “farms out” its draw-file illustrations to a
  64.   drawing package  for editing. This can already be done, of course, but this
  65.   protocol would make the inter- application transfers 100% automatic.
  66.   Clicking an ‘edit’ option for a graphic in a DTP  frame would bring up a
  67.   Draw-file editor window containing the graphic, and when the  user is
  68.   finished editing, the graphic will be automatically updated to show the
  69.   changes.
  70.   (I personally feel that this is better than continuous hotlinking as it
  71.   allows the user to  decide if and when they will actually replace the
  72.   DTP-frame data with the new, edited  version − I guess a bit like an undo
  73.   feature).
  74.  
  75. • A drawfile editor that allows you to edit the text from text areas in a
  76.   normal text editor  window. Notice how this could be combined with the last
  77.   point, so you could edit the  text from a drawfile from a DTP doc. Imagine
  78.   selecting a text-area object in draw, and  pressing ctrl-E and having an
  79.   edit window appear with the text in... or selecting a  sprite, pressing
  80.   ctrl-E, and have a paint window containing the sprite appear.
  81.  
  82. • A Sound-Tracker song editor that displays (and possibly allows you to edit
  83.   and/or  play) it’s instrument samples via a digitised sample editors
  84.   windows.
  85.  
  86. • An adventure authoring system that lets you edit descriptions in a
  87.   fully-blown text  editor window, and edit pictures in a fully-blown sprite
  88.   or draw file editor window,  while only having to provide the
  89.   location/object editing functions by itself.
  90.  
  91. • A hypermedia program could allow any type of file to be added into a
  92.   ‘card’, and  simply ask at runtime if there is any application present which
  93.   is able to ‘display’ the  file: Unrecognised sound sample formats would be
  94.   picked up by another application  and played, unrecognised data files
  95.   containing movies could be displayed, etc. without  the hypermedia program
  96.   even knowing what the information in the data files was!
  97.  
  98. • A configuration/preferences application with a special configuration-file
  99.   format could  be used to set all preference options for ALL running
  100.   applications that support this  message system − Thus a central, consistent
  101.   configuration interface system is available,  rather than each application
  102.   including code to supply preference options in its own  (usually different)
  103.   interface style and method.
  104.  
  105. • “True colour” menus such as in paint and draw, for setting palette values
  106.   could be  supplied by an editor: one that would allow users to use HSV or
  107.   CIE or RGB or CMYK  or a rainbow-colour-picker, in order to mix the colour
  108.   that the client application wants  − this would then be returned as (eg) an
  109.   RGB triplet for the client application to use.
  110.  
  111. Some of this can be achieved at present through the use of rather messy and
  112. “hacky” trickery  with Data Transfer messages and file-watching. However, a
  113. proper protocol is very simple  to implement, and yet exceedingly useful and
  114. powerful, as I hope the above examples will  have demonstrated to you.
  115.  
  116. To supply more integrated hotlinking than the above requires large
  117. alterations and/or  additions to the operating system and very complicated
  118. protocols. However, the external  editing protocol gives a very passable
  119. base level of ‘hotlinking’ that is exceedingly quick and  easy to support in
  120. RISC OS applications, (relying mainly on existing data transfer protocols), 
  121. but which can increase the usability of the desktop for certain operations
  122. immensely.
  123.  
  124.  
  125. Overview of the protocol
  126. ========================
  127.  
  128. Two applications are involved in the process:
  129. • An ‘editor’ (which supplies the display window and possibly also editing
  130.   functions),
  131.  
  132. • A ‘client’ (which initiates the edit, and supplies data to the editor
  133.   and/or expects data  back from the editor later). 
  134.  
  135. An application may include support for either/both editor and client ends of
  136. the interface. The ‘user’ is the person using the computer.
  137.  
  138. From the client end:
  139. The client application decides (usually at the request of the user) that
  140. some data needs to be  edited. Unable to supply this function itself, it
  141. broadcasts to all other applications requesting  an External Editing
  142. session.
  143.  
  144. If no reply is recieved, then the client may take any appropriate action
  145. (for example, run an  editor supplied with the application and then
  146. re-broadcast the request), but if the edit is not  possible, the client will
  147. inform the user with an error message indicating that the edit is not 
  148. possible.
  149.  
  150. If a reply is received, then a window will have been opened, and the user
  151. may now edit the  (blank) data in this window. The client now has the
  152. following options:
  153.  
  154. • By starting a data transfer to the editor, the client can insert some data
  155.   at the ‘current  position’ in the edited data; this can be done at any time,
  156.   but is mainly intended to  supply an initial chunk of data to be edited.
  157.   (for example, a compiler might make Edit  display a source code file if an
  158.   error has been found during compilation)
  159.  
  160. • By sending an appropriate message, the client can set a selection or
  161.   cursor position in  the edited data. (for example, the compiler might
  162.   highlight the line of code containing  the error)
  163.  
  164. • Another message may be sent by the client at any time to request that the
  165.   data be  returned. (for example, the compiler could include a button/menu
  166.   option somewhere  which says 'recompile', which will automatically retrieve
  167.   the code being edited and  recompile it)
  168.  
  169. From the editor end:
  170. Upon receipt of an external edit request broadcast, the editor checks the
  171. data type, and if it is  able to edit the data, it opens a suitable window
  172. (on a 'blank' datafile) and replies to the  message.
  173.  
  174. It will allow the user to edit the data (unless the request was for
  175. read-only data, see below),  and can also handle some extra functions:
  176.  
  177. • If a data transfer is started by the client, it will insert the new data
  178.   into the ExtEdit data,  at the current 'cursor' position.
  179.  
  180. • If the client requests the data back, or if the user chooses the 'save'
  181.   menu option or  closes the ExtEdit window, a reverse data transfer will be
  182.   initiated back to the client.
  183.  
  184. This is a very simple protocol at heart, and has been designed to be easy to
  185. implement at the  client end, though it takes a bit of work from the
  186. editor's end in order to provide enough  functionality.
  187.  
  188.  
  189.  
  190. =====================
  191. Protocol message data
  192. =====================
  193.  
  194. Before I detail the messages and protocol itself, I will explain some
  195. ‘global’ data fields that  are contained in most messages. These data fields
  196. always occur at the same position of  messages and always have the same
  197. meaning in messages, to enable quick and easy message  turnaround and
  198. general ease for programming.
  199.  
  200.  
  201. Data type word (&eeee0ttt)
  202. ==========================
  203.  
  204. The least-significant 16 bits (0ttt) of this word contain a normal RISC OS
  205. file type number.
  206.  
  207. The most significant 16 bits (eeee) contain an extension which augments the
  208. file type number  to provide more information on exactly what the data is.
  209. This enables, for example, the text  of an Impression document to be saved
  210. with style information in DDF format to a text (&fff)  file, but still be
  211. differentiated from a normal text file, by using an extension.
  212.  
  213. A hypothetical extension might see the normal text file given the data type
  214. word &00000fff,  while then DDF text might be given the word &20150fff.
  215.  
  216. The extension &0000 is defined as conveying no extra information, i.e. it is
  217. a ‘normal’ file of  the specified type − the RISC OS file type alone conveys
  218. all the necessary/available  information.
  219.  
  220. Extensions &0001 through &04ff are reserved for ‘user’ use. However, it is
  221. preferred that you  request an official allocation anyway, for
  222. future-proofing, to avoid clashes, and to enable all  applications to share
  223. one data type for each specific type of data, and thus improve the 
  224. effectiveness of the protocol.
  225.  
  226. If you have a type of data which can be differentiated to a more precise
  227. level than RISC OS  filetypes allow, then please write requesting an
  228. extension number allocation. Allocations can  also be requested for special
  229. in-house data type numbers for conveyance of specially defined  data chunks.
  230.  
  231.  
  232. Job Handle (&eeeecccc)
  233. ======================
  234.  
  235. This is used in all communication between the client and editor as a
  236. reference to a specific  job. The client and editor both fill in their half
  237. of this word with unique non-zero numbers,  thus making a job handle which
  238. is unique at both 'ends'. Once completed, the job handle for  a session is
  239. never changed. I suggest you use handles as follows:
  240.  
  241. • Each party simply ANDs off the 16 bits containing their own half of the
  242.   job handle.  Thus, other than verifying its correctness, you need not
  243.   concern yourself with the other  applications' half of the handle.
  244.  
  245. • Each application provides a handle value, so can use any handle value that
  246.   is easy for  the programmer. Note however, that all handles should be unique
  247.   so that handles are  not re-used. The suggested method for correctly
  248.   generating/using handles is:
  249.     Split your 16-bits of the job handle into 2 parts (perhaps a 10:6 bit
  250.     split?). The top 10 bits  contain a unique (sequentially generated)
  251.     number, while the bottom 6 bits contain a  re­usable array index.
  252.  
  253.     When a message for an existing session is recieved, mask the array-index
  254.     off the bottom  to get quick-and-easy access to the relevant information.
  255.     Then check the entire 32 bits of the recieved handle against the copy
  256.     you have thoughtfully stored in your array of information on this session,
  257.     to ensure that it is a valid message. (and not, for example,  an attempt
  258.     at communication from a previous (dead) session).
  259.  
  260.  
  261.  
  262. Message flags
  263. =============
  264.  
  265. For the sake of simplicity, only one flagword definition has been made, and
  266. this flagword is  used in all the messages. Some flags are therefore invalid
  267. in the context of some messages,  and are simply ignored (if in doubt,
  268. ignore the flag). This allows easy turnaround of  messages, as most of the
  269. messages are very similar in construction, allowing the programmer  to make
  270. minor alterations to a received message before using it as the contents of a
  271. reply.
  272.  
  273. The flags should be set by the editor when replying to the client in order
  274. to indicate the  current status (e.g. if you are unable to supply read-only,
  275. then clear the read-only bit; if you  are unable to edit the data, then set
  276. the read-only bit): If the client is not happy with the  reported status,
  277. they should report the problem to the user, and (possibly) abort the
  278. session.
  279.  
  280. The defined flags are:
  281.         Bit     Value   Description
  282.         0       &1      Continue editing
  283.                         Messages involving return of the data use this bit
  284.                         to indicate whether the  external edit session
  285.                         should continue (bit = 1) or be abandoned (bit = 0) 
  286.                         once the data has been returned.
  287.  
  288.                         If the user closes the External Edit window, then
  289.                         this flag will be ignored,  as the user has
  290.                         specifically indicated that they wish to end the
  291.                         session.
  292.  
  293.         1       &2      Selection only
  294.                         The EditReturn message uses this bit to indicate
  295.                         that the whole file  (bit = 0) or the selection only
  296.                         (bit = 1) should be returned. When returning  data,
  297.                         this bit indicates whether it is all/selection only
  298.                         being returned.
  299.  
  300.         2       &4      Read-only
  301.                         This flag is used by the client to request that the
  302.                         data be treated as read- only. If the editor
  303.                         supports such a concept, it should not allow the
  304.                         user to  alter the data in any way. In case the
  305.                         editor doesn't support this, the client  should be
  306.                         ready to ignore any attempt to return the data, even
  307.                         though the editor should note the flag and not
  308.                         return the data anyway.
  309.  
  310.         3       &8      Immediate execution
  311.                         Some data types can be 'played' or 'executed' (e.g.
  312.                         sound samples/movies, script files). This flag is
  313.                         used to request that execution of such data should 
  314.                         begin as soon as possible after receipt of the
  315.                         message (this may involve  waiting until all the
  316.                         data has been transferred to the editor).
  317.                         This can be used to make the 'editor' simply a
  318.                         'playback device' that is  called by other
  319.                         multitasking applications.
  320.                         This flag has no effect if the editor does not
  321.                         support it; typically the case  when the data type
  322.                         doesn't allow for any concept of 'playback'.
  323.  
  324.         4       &10     Adjust selection
  325.                         When using the cursor-positioning message protocol,
  326.                         this bit should be  set if the selection range given
  327.                         should replace the current selection (as if  clicked
  328.                         upon with select: bit = 0), or be added to the
  329.                         current selection (as if  clicked upon with adjust:
  330.                         bit = 1).
  331.                         This allows arbitrary selections to be built up for
  332.                         files such as drawfiles,  where the set of selected
  333.                         items doesn't necessarily cover a single  contiguous
  334.                         range of values/objects.
  335.  
  336. 5-31    -       Reserved
  337.                         Must be set to 0 on send, and ignored on recieve.
  338.  
  339.  
  340.  
  341. ============
  342. The Protocol
  343. ============
  344.  
  345. The protocol details and fine-print are explained later in this document.
  346. However, to explain  the basic interactions, as well as give a much clearer
  347. indication of exactly what messages  should be sent/received at any
  348. particular time, I have drawn up some state diagrams. The protocol is based
  349. around these 6 WIMP messages:
  350.  
  351. Message Name            Description                             Number
  352. Message_EditRq          Request external editing session        &45D80
  353. Message_EditAck         Acknowledge external edit               &45D81
  354. Message_EditReturn      Request return of external edit data    &45D82
  355. Message_EditAbort       Close editing session completely        &45D83
  356. Message_EditDataSave    External edit equivalent of DataSave    &45D84
  357. Message_EditCursor      Cursor/Selection placement              &45D85
  358.  
  359. The messages that you can expect to send/receive at any point are shown in
  360. the state diagrams (included as two drawfiles with this document)
  361.  
  362.  
  363. "Client" Drawfile:
  364. This shows all the states you should expect to encounter if you are a client
  365. during a session.  All of the states you should expect to encounter if you
  366. are an editor during a session are  detailed below:
  367.  
  368.  
  369. "Editor" Drawfile:
  370. The only part of the above protocol which is not described in this document
  371. is the 'send data' process. This is initiated by the sending/receiving of
  372. an EditDataSave message (which is in  most ways identical to a normal
  373. DataSave message), followed by normal RAM/disc inter- application data
  374. transfers as detailed in Acorn's data-interchange message protocol.
  375.  
  376. The reason for doing this is to allow you to use existing code (very few
  377. applications don't  already have at least some support for inter-application
  378. transfers) at the heart of this protocol,  which saves effort and code
  379. duplication. It would also be rather silly to define yet another  protocol
  380. if it isn't absolutely necessary.
  381.  
  382.  
  383.  
  384.  
  385. ============
  386. The Messages
  387. ============
  388.  
  389. The messages used in the protocol are described in detail below:
  390.  
  391. ---
  392. Message_EditRq (Request external edit, number &45D80)
  393. This is sent by a client as a broadcast.
  394. Any editor recieving it should check the data type, and if they can supply
  395. the service needed,  they should claim the message with an EditAck, and open
  396. a blank, appropriate editing  window.
  397.  
  398. Notes
  399. This message is always broadcast by the client and received by editors.
  400.  
  401. If your editor is read-only, it should only reply to this message if the
  402. read-only flag is  set. If a client would prefer to allow editing of the
  403. data, it will broadcast with the read- only flag clear, but may re-broadcast
  404. (if no reply is received) with the read-only flag set,  in order to at least
  405. display the information. This will stop read-only editors (displayers)  from
  406. grabbing data when fully-blown editors are available.
  407.  
  408. Definition
  409. R0 = 19
  410. R1 + 20 Data type word
  411.  
  412. R1 + 24 Job handle
  413.         The client should place a unique, non-zero integer job handle into
  414.         the least  significant 16 bits of this word. The most significant
  415.         bits should all be set to  zero. (i.e. 0x0000xxxx where xxxx is > 0)
  416.  
  417. R1 + 28 Flag word
  418.         Flags that are valid and should be supported are Continue-editing (0),
  419.         Read­only (2), Immediate execution (3).
  420.         Note that in the case of some data (sound samples),
  421.         Immediate-Playback  implies that the data should not be displayed in
  422.         a window at all, but just  played. If a display is needed as well as
  423.         playback, use the EditCursor  message to initiate playback after
  424.         data transfer.
  425.  
  426. R1 + 32 Parent name
  427.         A 0-terminated string (max. length 20 characters including the
  428.         terminator)  identifying the parent document/application (it’s file
  429.         leaf-name, generally).
  430.         On receipt, the editor should change the edit-window title to read
  431.         “(Parent)  Filename” to indicate that the file is a temporary edit
  432.         of data from the  document/application “parent”.  If this entry is
  433.         blank (byte @ block+32 = 0)  use the normal title-bar layout
  434.         "Filename", using just the leafname.
  435.  
  436. R1 + 52 Leaf name
  437.         A suggested leaf-name for the edited file. This will be displayed by
  438.         the  editor in the titlebar of the edit-window, and will appear as
  439.         the default in the  save-as box. If this entry is blank (byte @ R1 +
  440.         52 = 0) then use the default  name for this filetype (e.g. Edit
  441.         would use “TextFile” for a text file)
  442.  
  443.         This name can be up to 204 characters long (including terminator),
  444.         but it is  preferred that it is less than 20 characters. If longer,
  445.         then it should appear like  a normal RISC OS filename, i.e.
  446.         subdivided into short (preferably < 20  character) sections using a
  447.         period "." character. Only the 'leaf-name' of this  (the last 20 or
  448.         fewer characters after the final period character) should ever  be
  449.         expected to be used by the editor.
  450.  
  451.  
  452. ---
  453. Message_EditAck (Acknowledge external edit, number &45D81)
  454.  
  455. This is sent by an editor in reply to an EditRq broadcast. If an editor can
  456. supply the requested service it opens an appropriate editing window (on a 
  457. 'blank' data file), and then replies to the client.
  458.  
  459. Notes
  460. This is only sent by an editor in reply to an EditRq message.
  461.  
  462. The flag-word will be updated by the editor to reflect the current status.
  463. e.g. the read- only flag will be set if 'editing' is in read-only mode, or
  464. clear if not.
  465.  
  466. Definition
  467. R0 = 17
  468. R1 + 20 Data type word
  469.         Copied from EditRq message.
  470.  
  471. R1 + 24 Job handle
  472.         Partially copied from EditRq message.
  473.         The editor fills in the top 16 bits with a unique, non-zero integer
  474.         identifier,  and the bottom 16 bits with the number given by the
  475.         client in the EditRq  message.
  476.  
  477. R1 + 28 Flag word
  478.         Copied from EditRq message.
  479.         The editor should note these flags, and if it is unable to supply
  480.         any of the  requested functions (e.g. read-only lock), it should set
  481.         these flags to indicate  its current status.
  482.  
  483.         If this status (e.g. editing is not possible − read only flag set)
  484.         is unacceptable  to the client, it should warn the user, and then
  485.         abort the session (see below).
  486.  
  487.         Valid flags are Continue-editing (0), Read-only (2),
  488.         Immediate-execution (3).
  489.  
  490.  
  491. ---
  492. Message_EditReturn (Request return of external edit data, number &45D82)
  493. This message is sent by the client to the editor, to request the return of
  494. the data. This allows  the client to provide a menu option or a button
  495. somewhere that will retrieve the data or  retrieve it and begin some
  496. operation upon it.
  497.  
  498. Notes
  499. This message is only sent by the client.
  500.  
  501. This is the only way in which a client can initiate return of the data, but
  502. note that the  editor can also initiate the transfer if the editing session
  503. is closed by the user.
  504.  
  505. This should not be sent/should be ignored if 'editing' in read-only mode, as
  506. the data  should not have been changed!
  507.  
  508.  
  509. Definition
  510. R0 = 17
  511. R1 + 20 Data type word
  512.         Included to allow the client to request the data back in a specific
  513.         format, not  necessarily the original format.
  514.         If the editor cannot convert the data to this format for return,
  515.         then it should  ignore the message, and the client must re-try with
  516.         a new data-type until a  compromise can be attained! Note that as a
  517.         last ditch measure the type 'data'  can be used, in which case it is
  518.         up to the client to recognise the format of the  data from its
  519.         content. If no compromise can be attained, then abort the 
  520.         operation, and assume that the editor is dead.
  521.  
  522. R1 + 24 Job handle
  523. R1 + 28 Flag word
  524.         Valid flags are Continue-editing (0), Selection-only (1).
  525.  
  526. ---
  527. Message_EditAbort (Close editing session completely, number &45D83)
  528. This message can be sent by either party. If this message is recieved, then
  529. mark this job handle as defunct − From now on, any  correspondence relating
  530. to this job handle should be ignored.
  531.  
  532. Notes
  533. The editor should close the window and stop editing.
  534. Note that this should be done in all circumstances, even if the data has
  535. been modified.
  536.  
  537. It is up to the client to warn the user and ensure that it’s OK to lose the
  538. data. The client should always treat external data as modified data.
  539.  
  540. The sender of the message is responsible for any error report that may
  541. indicate to the  user that the edit has failed. Thus, the reciever should
  542. not take any error-reporting action.
  543.  
  544. EditAbort should be sent whenever a job must be aborted (fatal error, task
  545. quitting,  etc.) in order to allow the other party to release workspace
  546. allocated to the editing  session. Remove the job handle from your records,
  547. and ignore future references to it.  Note that this means you should not
  548. recycle job handle values.
  549.  
  550. Note, however, that in some fatal cases, it is better to not send an abort,
  551. in order to  allow the user to save their edited data and retrieve at least
  552. some of the data which  would otherwise be lost when your application
  553. unexpectedly quits. This decision is  thus left up to your judgement.
  554.  
  555. If playback of any type is running due to previous use of the
  556. Immediate-Playback flag,  then playback should cease immediately.
  557.  
  558. This message should not be sent before a session is correctly started (i.e.
  559. when no valid  job handle exists!), or during the course of any
  560. inter-application daa transfers.
  561.  
  562.  
  563. Definition
  564. R0 = 17
  565. R1 + 20 Reserved (should be 0).
  566. R1 + 24 Job handle
  567.  
  568.  
  569. ---
  570. Message_EditDataSave (Equivalent of DataSave, number &45D84)
  571. This message is almost identical to Message_DataSave, and may be sent by
  572. either party to  initiate a data transfer (via the normal RAM or disc
  573. transfer protocols). The message is used in exactly the same manner as
  574. Message_DataSave, except instead of  specifying a window/icon destination,
  575. it supplies a job-handle to indicate the destination.  Any followup messages
  576. to an EditDataSave are normal Acorn Data transfer protocol  messages.
  577.  
  578. All fields can/should be filled in as for a normal DataSave message, except
  579. for the job handle  field, which should instead be filled in wih the job
  580. handle. 
  581.  
  582. Notes
  583. Data transfer, as for Message_DataSave, is from the sender of this message
  584. to the  reciever.
  585.  
  586. Normally, this message will follow EditRq, as soon as the client recieves
  587. the EditAck, in  order to supply the initial data for editing. However, it
  588. should be noted that the  message need not be sent if the client wants only
  589. a ‘blank’ editing window.
  590.  
  591. This message may be sent more than once by the client, in which case each
  592. data transfer  will be inserted (if relevant, at the current 'cursor'
  593. position, otherwise at the discretion of  the author), into the ExtEdit
  594. data.
  595.  
  596. If the editor cannot supply this service, either due to limited support for
  597. this protocol,  due to difficulties presented by the data type, or because
  598. of the read-only flag setting,  etc, the EditDataSave should be ignored and
  599. an error should be reported, along the  lines of “This operation is not
  600. supported”.
  601.  
  602. This message is sent by the editor in reply to an EditReturn message, or
  603. when it wishes  to return the data. More discussion on return of data is
  604. given below.
  605.  
  606. If the Immediate-Playback flag was set in the initial EditRq, and the data
  607. is ‘playable’,  then playback should be commenced as soon as this data
  608. transfer is complete. As soon  as playback finishes, the session should be
  609. considered aborted (no extra messages need  be sent).
  610.  
  611. The contents of the 'ignored' fields should be, um..., ignored. Their
  612. contents are up to  the discretion of the sender − if the author feels that
  613. it is easier to call existing code that  fills in these fields in some way,
  614. they may contain some kind of valid data. However,  the contents of these
  615. fields should not be relied upon in any way − do not put extra  'personal'
  616. data items in these words for use between your own programs!
  617.  
  618. Definition
  619. R0 = 17
  620. R1 + 20  Job handle (normally window handle)
  621. R1 + 24  Ignored (normally icon handle)
  622. R1 + 28  Ignored (normally X position)
  623. R1 + 32  Ignored (normally Y position)
  624. R1 + 36  Estimated size of data, in bytes
  625. R1 + 40  File type of data
  626.          (Not data-type, just base file-type, as in normal DataSave message)
  627. R1 + 44  Proposed leaf-name of file, 0-terminated.
  628.  
  629.  
  630. ---
  631. Message_EditCursor (Set cursor/selection position, number &45D85)
  632. This message can be used with some data types to set either a selection (a
  633. range of data items  which are selected) or a cursor position (a single data
  634. item which is selected, or an insertion- point (caret) between data items
  635. (e.g. characters)).
  636.  
  637. It is initially sent by the client to the editor to set new values, and is
  638. immediately returned by  the editor to indicate the success of the
  639. operation.
  640.  
  641. Notes
  642. A data unit is the smallest useful data item represented in a document.
  643.         Examples:
  644.                 text files: units are characters
  645.                 draw files: units are objects
  646.                 sound samples and other binaries: units are bytes
  647.         Currently defined data units are listed below.
  648.  
  649. The cursor is some kind of ‘marker’ which can be placed at meaningful unit
  650. positions  within the document. It is always measured in terms of units from
  651. the start of the data.
  652.  
  653. The cursor position is interpreted as follows:
  654.   The position given indicates a unit of data. The first unit of data is
  655.   given the unit  number 1, the second is 2, etc. In the context of most
  656.   data (e.g. drawfiles), this  unambiguously indicates a single unit.
  657.   Selections between two such unit positions are  inclusive of those
  658.   positions.
  659.  
  660.   In some cases (text files, etc), a caret is used to indicate the cursor
  661.   position, and is placed  between two data units. In this case, the caret
  662.   is placed after the indicated unit.
  663.  
  664.   A special-case resuts from these two definitions, which is placement of
  665.   the caret before  the first data item, in which case a value of 0 should
  666.   be used. (In drawfiles and similar  cases, a value of 0 should be treated
  667.   as a value of 1)
  668.  
  669. The selection is a group of units that can be described by a contiguous
  670. range delimited  by two cursor positions, called the start-of-selection and
  671. end-of-selection. Arbitrary  selections in data such as a drawfile can be
  672. achieved using the 'Adjust-selection' flag in  a series of EditCursor
  673. messages.
  674.         Examples:
  675.                 text files: The selection is a series of adjacent characters
  676.                 draw files: Each selection can be any contiguous linear
  677.                             sequence of objects
  678.  
  679.  
  680. This is intended mainly for cursor positioning in text files. However, the
  681. design should  be sufficiently general to cater for most data types. If you
  682. wish to support the protocol  with an editor, then please contact me so that
  683. we can sort out official details of the  definition of units with that data
  684. type. In all releases of this document, all official  definitions at time of
  685. release will be included below.
  686.  
  687. If in doubt, default to byte offsets.
  688.  
  689.  
  690. Definition
  691. R0 = 17
  692. R1 + 20 Reserved (should be 0)
  693. R1 + 24 Job handle
  694. R1 + 28 Flag word
  695.         Valid flags are Read-only (2), Immediate-playback (3),
  696.         Adjust-selection (4).
  697.  
  698.         The former two flags are used to attempt setting of new values for
  699.         the current state, and are returned to indicate the new status.
  700.         Immediate-playback can thus be used to halt or (re)start playback at
  701.         any time, if playback is multitasking.
  702.  
  703. R1 + 32 New cursor position *
  704. R1 + 36 New start-of-selection position *
  705. R1 + 40 New end-of-selection position *
  706.  
  707. R1 + 44 (reply only) Old cursor *
  708. R1 + 48 (reply only) Old start-of-selection *
  709. R1 + 52 (reply only) Old end-of-selection *
  710.  
  711.  
  712. * Special cursor-position values
  713. As mentioned above, positive unit offsets are used to set the cursor
  714. position and start/end of  the selection. However, in some cases you may not
  715. wish to alter the current value of any of  these settings, in which case,
  716. you should fill the position field with the value -1  (&FFFFFFFF).
  717.  
  718. This allows you to set any or all of the positions individually. By setting
  719. all three ‘new’  positions to -1, you may read the current values without
  720. altering them.
  721.  
  722. Note that the flags will always be set to the new values given, so you can
  723. also alter the flag  settings only, by setting all ‘new’ positions to -1.
  724.  
  725. The special value -2 (&FFFFFFFE) should be used to indicate ‘end-of-data’.
  726. Thus, to select the  entire piece of ExtEdit data, you should set the
  727. selection to the range ‘0’ to ‘-2’.
  728.  
  729. If the editor is unable to return a sensible value for the ‘old’ values
  730. (e.g. there is no concept of  a selection, or the selection can't be
  731. represented as a single contiguous chunk), it will return  values of -1 in
  732. these fields. It should never return -2 (end-of-data), as the editor should
  733. be  capable of determining the correct end-of-data unit position.
  734.  
  735. Note also that in some situations (during movie/sound playback) the returned
  736. cursor value  may not be correct by the time you recieve the message. This
  737. facility is really only useful for  reading the position while paused, or
  738. for less-often updated cursors such as the text cursor in  Edit, and for
  739. ensuring that a cursor-set operation worked. It would be preferable if this 
  740. message were not used on every NULL event to watch/control movie playback or
  741. similar,  except in exceptional (!) circumstances.
  742.  
  743. Current data unit definitions
  744.   Type          Filetype  Unit represents                                                                             
  745.   Text            fff     character
  746.   Command         ffe         "
  747.   TaskObey        fd7         "
  748.   TaskExec        fd6         "
  749.   Obey            feb         "
  750.  
  751.   Data            ffd     byte offset
  752.   BASIC           ffb     byte offset in tokenised data/
  753.                            character offset in text form
  754.  
  755.   Sprite          ff9     sprite number/index
  756.   Palette         fed     colour number, as index into standard file format
  757.   DrawFile        aff     draw object
  758.   ARMovie         ae7     animation frame number
  759.  
  760.  
  761.  
  762. ==============
  763. Sundry Details
  764. ==============
  765.  
  766.  
  767. Return of data
  768. ==============
  769.  
  770. The ExtEdit data return can be initiated by:
  771. Client:
  772.         Sends EditReturn message (usually prompted by a user action)
  773.  
  774. Editor:
  775.         Recieve EditReturn − return the data,
  776.  
  777.         User clicks the ‘save’ option, the save-as OK button, or presses
  778.         RETURN in the save-as  window − return the data, quit if the
  779.         continue flag is clear.
  780.  
  781.         User drags the save-as file icon somewhere − save a copy of the data
  782.         to the indicated  file, but don't take any other action − continue
  783.         editing as if nothing happened.
  784.  
  785.         User clicks the window close icon − Ask with a dialogue box as for a
  786.         normal document  being closed, offering Save/Discard/Cancel options
  787.         (If Save is clicked, return the data  and quit, Discard means just
  788.         quit the session (send an abort), and Cancel will resume  editing as
  789.         if nothing had happened)
  790.  
  791.  
  792. Error handling
  793. ==============
  794. If communications break down, you may assume that the session has been
  795. aborted due to a  bad implementation forgetting to inform you, or loss of
  796. communications (the other  application is confused or dead). However, be
  797. careful about such assumptions: There are  several places where no reply is
  798. a perfectly valid response, and other places (EditCursor  messages) where a
  799. lack of response isn't necessarily a good indication of communication 
  800. breakdown. When in doubt, leave the session open until something definitive
  801. happens to  confirm the fact that communications have broken down.
  802.  
  803. Errors during file transfer should be treated as normal, but will sometimes
  804. also indicate that  the session has to be aborted − note that I have seen
  805. several applications that spuriously  report ‘reciever dead’ and other
  806. similar errors in otherwise correct data transfers, which  indicates that
  807. somebody is failing to send a last ‘ack’ message, rather than an actual
  808. break in  communications... these should not necessarily spell doom for the
  809. ExtEdit session!
  810.  
  811. In all cases when you think communications have broken down, or when you
  812. must  unexpectedly break the connection, you should do your best to send an
  813. EditAbort (to ensure  that the job has really been aborted) and abandon the
  814. job tidily.
  815.  
  816.  
  817. Closing a document containing ExtEdit data
  818. ==========================================
  819.  
  820. If you wish to quit or close a document containing data that is currently
  821. tendered out for  external editing, then the external data should be treated
  822. as modified/unsaved data, i.e.    you should inform the user “There is
  823. unsaved (external) data in this document“, and  allow them to initiate a
  824. return-and-save of the data, or discard the data, much as you  would with
  825. normal unsaved data.
  826.  
  827. Please ensure that you send an abort in the latter case, as it is
  828. undesirable to have unattached  editing windows floating around.
  829.  
  830.  
  831. Multi-file document handling
  832. ============================
  833.  
  834. Some packages (e.g. Impression) use a distributed document format (a
  835. directory containing  several files) which does not conform to ExtEdit’s
  836. idea of a ‘single datafile’. In such cases, it  is up to the designer of the
  837. multi-file document to provide means for the document to be  handled as a
  838. single entity.
  839.  
  840. • With no extra effort, this can be achieved by never using RAMTransfers −
  841.   if a  document is saved to disc, then the editor can detect the type and
  842.   treat it appropriately.
  843.  
  844. • In cases where RAMTransfer is desired, the designer of the data file
  845.   format must  specify some means by which the data can be transferred as a
  846.   single “file”.
  847.  
  848.  
  849. External edits of external edits!
  850. =================================
  851.  
  852. A hypothetical case:
  853. We have a DTP document containing a drawfile, and we ExtEdit the drawfile
  854. out to Draw. From Draw, we ExtEdit out a sprite in the drawfile to Paint,
  855. and a text-area to Edit.
  856.  
  857. When the data in the Drawfile needs to be returned (by user closing the draw
  858. window or  clicking save, or by an EditReturn message),  what should Draw
  859. do?
  860.  
  861. The External Edit protocol is designed to be a “Please edit this data and
  862. tell me when it is  complete“ system. Thus, no editor should attempt to
  863. retrieve data that is being ExtEdit’d  from within an ExtEdit document in
  864. order to update the data it returns to its own client.
  865.  
  866. Draw should therefore treat its own copy of the drawfile as being complete
  867. and disregard  the ExtEdits from within it. Any Abort of this ExtEdit should
  868. pass the Abort on to any 'child'  ExtEdits.
  869.  
  870. However, if the editor-author is feeling particularly keen, you may treat
  871. all external edit data  as ‘modified’ data, and pop up an error box much
  872. like that for closing an unsaved document:  “There is unreturned external
  873. data: Save/Discard/Cancel”. The user clicks one of the buttons:
  874.  
  875. Save
  876.   This should request the return of all ExtEdit data to update the drawfile,
  877.   and then  return the drawfile back to the original client.
  878.  
  879. Discard
  880.   This should return the current data to the client, and send ABORT messages
  881.   to all  related external editors.
  882.  
  883. Cancel
  884.   Editing continues as normal, giving the user the opportunity to (e.g.)
  885.   save the sprite  from paint back into the drawfile, and discard the
  886.   modified edit docment (leaving the  drawfile unchanged) before attempting
  887.   to close the drawfile again.
  888.  
  889. It is preferable that the user should not lose all external-edit data
  890. without a warning. An  ExtEdit data chunk should not be automatically
  891. updated by sucking back ‘child’ ExtEdits, as  this could result in
  892. unintended ‘corruption’ of the document.
  893.  
  894.  
  895. Alias$@EditType_xxx
  896. ===================
  897.  
  898. When requesting an External Edit session and receive no reply, first you
  899. should re-try your  request with different data-types and/or with the
  900. read-only flag cleared in the hope of  finding a suitable, though less ideal
  901. editor for your data.
  902.  
  903. When no acceptable editor has been found by this method, you can attempt to
  904. run a suitable  editor from disc and then re-try your EditRq's (see below).
  905.  
  906. If all of this fails, then you should simply give up − report you inability
  907. to the user, and  suggest the type of editor you would like them to run
  908. before attempting that operation  again.
  909.  
  910.  
  911. Running a suitable editor from disc
  912. ===================================
  913.  
  914. In this case, it is important that the user is able to configure in some way
  915. which editor will be  run. It is also important that any suitable editor
  916. that is available can be run, rather than just  one hard-wired editor that
  917. the author expects to be available.
  918.  
  919. In order to improve this situation, I make the following suggestion which I
  920. strongly urge you  to follow: Editors should, in their !Boot file, set
  921. variables along the lines of RunType, which  indicates the editor to be run
  922. for a particular RISC OS filetype, e.g. !Edit might use:
  923.         Set Alias $@RunType_FFF Run <Obey$Dir>.!Run %%*0
  924.         Set Alias$@EditType_FFF Run <Obey$Dir>.!Run
  925.  
  926. A client wishing to run an editor can then execute the command held in the
  927. most appropriate  Alias$@EditType_??? system variable, and then start
  928. broadcasting EditRq messages again.
  929.  
  930. If no Alias$@EditType_??? variable is set, or if it fails for any reason to
  931. successfully launch an  editor (your retried EditRqs will fail), then you
  932. should give up and report the problem to the  user.
  933.  
  934.  
  935. Current registered users of ExtEdit
  936. ===================================
  937.  
  938. The following applications already support the protocol:
  939.         StrongEd 2, StrongHlp
  940.  
  941. The following applications will soon support the protocol:
  942.         Zap, ZEdit, DSEdit II.
  943.  
  944.  
  945. Requests For Allocations and Other Communications
  946. =================================================
  947. If you wish to use:
  948.  
  949.   •       flag bits
  950.   •       data types
  951.   •       messages or SWI support to augment the protocol
  952.  
  953. that are not defined in this document, then please request an official
  954. allocation in order to  ensure no clashes occur, and to allow others to
  955. support any such new items as well. The  power of this protocol comes from
  956. unhindered sharing of it by as many applications as  possible
  957.  
  958. Please write to the following address indicating the desired allocations,
  959. the product for  which they are to be used, and any details (extra protocol
  960. conventions, data format, etc.) that  will be needed for others who may wish
  961. to support the allocated items.
  962.  
  963. If you wish to request allocations,  or have any suggestions or queries to
  964. put to me, then  please do not hesitate to contact me:
  965.  
  966.         Jason Williams,
  967.         R.D.2, Manuel Road,
  968.         Silverdale,
  969.         North Auckland,
  970.         New Zealand.
  971.  
  972. Post usually takes 1 week between NZ and Europe.
  973.  
  974. My email address will be changing in February/March 1993, but it is currently
  975.         jwil1@cs.aukuni.ac.nz
  976.  
  977.