API - Application Interface

BASICS

GoldED offers two message-based application interfaces: ARexx and API.  The  API
interface may be used by third party applications to register with GoldED: after
having registered by sending the API command to GoldED's ARexx  port  they  will
recieve  notify  messages from GoldED. Depending on these messages they can take
approbiate actions (e.g. close their windows  if  GED  is  about  to  close  its
screen,  indicating  this  by sending API_ACTION_HIDE messages to all registered
clients). ARexx usually is used to control a program. The API interface is  used
by GoldED to control the clients.

HOW TO RUN CLIENTS

Clients are launched as programs by GoldED during startup or after usage of  the
API  requester.  The name of GoldED's port is passed as HOST=... argument to the
client. The client is expected to  register  with  GoldED  by  sending  the  API
command  to  this  port,  thus  requesting  notify classes (clients may select a
subset of the available notifys) and providing GoldED with a message port for to
send  notifies  to. The first command sent to the client's port after the client
did register with GoldED will be  API_ACTION_INTRODUCE  (API_CLASS_ROOT  event).
The  client is expected to return a short description of its abilities. The next
command recieved by the client usally is API_ACTION_SHOW (in case the client did
request  API_CLASS_SCREEN  events):  this  is GoldED's request to open a window.
Notifes include a variety of  informations  about  the  editor's  current  state
including  text  of  current  line,  window  dimensions and screen name. Several
example API clients are shipped wiuth GoldED; please have a look at  the  source
codec to understand the basic meachanisms.

RESTRICTIONS

After a client has registered with GoldED it has to be able  to  answer  notifys
immediately  until  the  API_ACTION_DIE command is recieved. It may not exit. It
may not Wait() for signals  unless  the  API  signals  are  included.  To  avoid
deadlock problems, you may not wait for completion of ARexx requests sent to GED
using WaitPort() (thus ignoring incoming API messages).