Programmer's guide

1) Foreword

Since 1.40 version, you can add modules to Joe. These can be tags generators
or others which will facilitate HTML coding and Web editing.

You can, without my authorisation, program your own module.
You can make Everyware : Public domain (with source code), Freeware (I would
appreciate). You can distribute also your module as shareware or commercial
program.
If you want an example
of source code for a module, just snail- or e-mail me. I will send you freely
GFA code of some modules in LST format.
But there are restrictions upon this source code :
- do not spread this code without my authorisation.
- do not distribute your module as expensive shareware (>70 Francs, 10 euros)
or commercial program if created basicaly on my source code. Contact me if
you you think your work on my source code is worth an expensive shareware or
a commercial software.

The sending of my source code is a moral agreement.

The following is recommendations, you don't have to subscribe at these words,
but I would appreciate if you do. Your module-program should :

be compatible with all the AtariOS (MagiC, MiNT, TOS...) and respect porperly
AES and VDI. run in only one window (as small as possible, "windows-like"
with several form-dials in the same window), with a minimum of blocking
extern form-dials, and the menu (if present) be included in the window.
run without Joe, ie with another HTML designer program or freely.


2) Be called by Joe

If you want your module-program to be launched under Joe application, it
MUST :
- have the *.PRG filename extension
- be in directory declared in the options of Joe
have a text file besides the *.PRG file. This texte file has the same
filename of the module and has the *.JXM extension.
- The text must contain :
in the first line : a text (30 caracters) which will be integrated in the
modules launching pop-up.
in the second line : a number (WORD, INT). Only the first bit is used now, but the
others bits may be used in the future with next versions of Joe.
Bit 0 at 1 : ability to be called in the pop-up.if at 0 : the module doesn't
appear in the pop-up.


3) Exchange protocol

a. The command line

Parameter given when launching a module is a Pascal string (1 byte describing
the lenght of the line, the data-caracters, and the null-byte terminator).
Data are structured like this :

8 caracters corresponding to the application wihch has called the module.
This 8 caracters will be given with no transformation to APPL_FIND function.
If Joe is the caller, then the 8 caracters are : "JOE     "
The next caracters (to the ending null-byte) describe a filename the HTML
file the caller is editing.

The module should get the first 8 caracters of the command line, and
APPL_FIND. If there's an error or the caller doesn't exist, the module should
not take the rest of the line or consider the command line does not applies
to Joe exchange protocol.

b. Monotasking mode

The module, before quitting, saves the tag or whatever data for the caller,
in the clipboard. Joe accepts *.HTM (text with all lines terminates by LF+CR)
and *.STG (C string format, considered as a macro, so you can use "|" and
"~") files. Therefore SCRAP.HTM or SCRAP.STG .
When quitting, the module returns a value (QUIT ret&) :
If 0 : the caller loads nothing
If 1 : the caller loads SCRAP.HTM
If 2 : the caller loads SCRAP.STG
If esle : no yet supported

You can return for others callers than Joe others values. Please, tell me
about what values you have added to normalize this.

c. Multitasking mode

NB : this applies also for accessories in monotasling mode.

Joe supports VA_START message and Drag and Drop protocol.

The exchanges with modules use the GEM pipe ("Tube GEM" in French). The
following decribes the calls. X_adr% is a 16 bytes buffer, mem% is a buffer
located in the global memory (X_mem%=GEMDOS(68,L:len%,W:32)) if possible
(else: GEMDOS(72,...). 16 bytes buffers are managed by EVNT_MULTI.

* SEND TEXT TO THE CALLER

caller_id&=APPL_FIND("????????")
' "????????" is the 8 caracter string read in the command line.
IF caller_id&>0
  INT{module_adr%}=20140
  INT{module_adr%+2}=module_id&
  INT{module_adr%+4}=0
  INT{module_adr%+6}=0
  INT{module_adr%+8}=0
  INT{module_adr%+10}=format&
  ' (1=*.HTM or *.TXT, 2=*.STG, 0 or else=Joe reads nothing)
  LONG{module_adr%+12}=module_mem%
  ' (address in the global memory where the module has put the text)
  ~APPL_WRITE(caller_id&,16,module_adr%)
ENDIF

When reading this in his 16 bytes buffers, the caller wil or will not read
the memory, and respond to the module with :

* CALLER RESPOND TO MODULE, TEXT RETRIEVED

module_id&=INT{caller_adr%+6}
INT{caller_adr%}=20141
INT{caller_adr%+2}=caller_id&
INT{caller_adr%+4}=0
INT{caller_adr%+6}=0
INT{caller_adr%+8}=0
INT{caller_adr%+10}=0
INT{caller_adr%+12}=0
INT{caller_adr%+14}=0
~APPL_WRITE(module_id&,16,caller_adr%)

To facilite the manipulation of the entire file edited by the caller, the
module can ask to the caller an automatic save of the text :

* REQUEST AUTOMATIC SAVE TO CALLER

caller_id&=APPL_FIND("????????")
' "????????" is the 8 caracter string read in the command line.
IF caller_id&>0
  INT{module_adr%}=20142
  INT{module_adr%+2}=module_id&
  INT{module_adr%+4}=0
  INT{module_adr%+6}=0
  INT{module_adr%+8}=0
  INT{module_adr%+10}=0
  INT{module_adr%+12}=0
  INT{module_adr%+14}=0
  ~APPL_WRITE(caller_id&,16,module_adr%)
ENDIF

The caller will save its data and tell next the module it's done, give the
address buffer of filename, and the handle of the window if not iconified and
existing :

* CALLER RESPOND TO MODULE, (OWN DATA SAVED) AND INFORMATION

module_id&=INT{caller_adr%+6}
INT{caller_adr%}=20144
INT{caller_adr%+2}=caller_id&
INT{caller_adr%+4}=0
INT{caller_adr%+6}=window_handle_of_caller&
INT{caller_adr%+8}=0
INT{caller_adr%+10}=0
LONG{caller_adr%+12}=caller_mem%
' the caller has put the filename in a 256 bytes buffer, in global memory.
' The filename buffer is permanent, so the module has no need to respond
' to the caller. But the module must ask the caller the address
' filename : the caller may quit, clean his memory and not respond.
~APPL_WRITE(module_id&,16,caller_adr%)

Be carefull with the widow handle : it's given to close, or shadow, the
caller window to avoid caller data manipulation during module computing. DO
NOT WIND_SET or whatever else the caller window directly, use GEM pipe and
fill the 16 bytes buffer as the Screen manager do.
You can freeze and unfreeze the caller if you know how to do it (See MagiC
developpers documention).

In some cases, you don't need the caller data to be saved. You just only want
informations, so :

* REQUEST INORMATION TO CALLER

caller_id&=APPL_FIND("????????")
' "????????" is the 8 caracter string read in the command line.
IF caller_id&>0
  INT{module_adr%}=20143
  INT{module_adr%+2}=module_id&
  INT{module_adr%+4}=0
  INT{module_adr%+6}=0
  INT{module_adr%+8}=0
  INT{module_adr%+10}=0
  INT{module_adr%+12}=0
  INT{module_adr%+14}=0
  ~APPL_WRITE(caller_id&,16,module_adr%)
ENDIF

The caller will respond to the module with the same message if there was an
automatic save. Therefore with the 20144 code, the window handle, and the
data filename in the caller buffer.