AES

Editable object functions

Window-dialogs

8.7 Event library

This library makes functions available with whose aid events can be recognized and processed. As a rule, program control is released to the operating system until the specified event has occurred. The following routines are available for this purpose:

Note: 'event' in this case should be understood as a message, key press, mouse movement and button activation, timer events etc.

See also: About the AES   GEM   Style guidelines

8.7.1 evnt_button

8.7.1.1 Bindings for evnt_button

int16_t evnt_button (int16_t ev_bclicks, int16_t ev_bmask,
                     int16_t ev_bstate,  int16_t *ev_bmx,
                     int16_t *ev_bmy, int16_t *ev_bbutton,
                     int16_t *ev_bkstate )
{
   int_in[0] = ev_bclicks;
   int_in[1] = ev_bmask;
   int_in[2] = ev_bstate;

   crys_if (21);

   *ev_bmx     = int_out[1];
   *ev_bmy     = int_out[2];
   *ev_bbutton = int_out[3];
   *ev_bkstate = int_out[4];

   return ( int_out[0] );
}

8.7.2 evnt_dclick

8.7.2.1 Bindings for evnt_dclick

int16_t evnt_dclick (int16_t ev_dnew, int16_t ev_dgetset)
{
   int_in[0] = ev_dnew;
   int_in[1] = ev_dgetset;

   return ( crys_if(26) );
}

8.7.3 evnt_keybd

8.7.3.1 Bindings for evnt_keybd

int16_t evnt_keybd (void)
{
   return ( crys_if (20) );
}

8.7.4 evnt_mesag

8.7.4.1 Bindings for evnt_mesag

int16_t evnt_mesag (int16_t *msg)
{
   addr_in[0] = msg;
   return ( crys_if (23) );
}

8.7.5 evnt_mouse

8.7.5.1 Bindings for evnt_mouse

int16_t evnt_mouse (int16_t ev_moflags, int16_t ev_mox,
                    int16_t ev_moy, int16_t ev_mowidth,
                    int16_t ev_moheight, int16_t *ev_momx,
                    int16_t *ev_momy, int16_t *ev_mobutton,
                    int16_t *ev_mokstate)
{
   int_in[0] = ev_moflags;
   int_in[1] = ev_mox;
   int_in[2] = ev_moy;
   int_in[3] = ev_mowidth;
   int_in[4] = ev_moheight;

   crys_if (22);

   *ev_momx     = int_out[1];
   *ev_momy     = int_out[2];
   *ev_mobutton = int_out[3];
   *ev_mokstate = int_out[4];

   return (int_out[0]);
}

8.7.6 evnt_multi

8.7.6.1 Bindings for evnt_multi

int16_t evnt_multi (int16_t ev_mflags,  int16_t ev_mbclicks,
                    int16_t ev_mbmask,  int16_t ev_mbstate,
                    int16_t ev_mm1flags, int16_t ev_mm1x,
                    int16_t ev_mm1y, int16_t ev_mm1width,
                    int16_t ev_mm1height, int16_t ev_mm2flags,
                    int16_t ev_mm2x, int16_t ev_mm2y,
                    int16_t ev_mm2width, int16_t ev_mm2height,
                    int16_t *ev_mmgpbuff,
                    int16_t ev_mtlocount,
                    int16_t ev_mthicount, int16_t *ev_mmox,
                    int16_t *ev_mmoy, int16_t *ev_mmbutton,
                    int16_t *ev_mmokstate,
                    int16_t *ev_mkreturn,
                    int16_t *ev_mbreturn)
{
   int_in[0]  = ev_mflags;
   int_in[1]  = ev_mbclicks;
   int_in[2]  = ev_mbmask;
   int_in[3]  = ev_mbstate;
   int_in[4]  = ev_mm1flags;
   int_in[5]  = ev_mm1x;
   int_in[6]  = ev_mm1y;
   int_in[7]  = ev_mm1width;
   int_in[8]  = ev_mm1height;
   int_in[9]  = ev_mm2flags;
   int_in[10] = ev_mm2x;
   int_in[11] = ev_mm2y;
   int_in[12] = ev_mm2width;
   int_in[13] = ev_mm2height;
   int_in[14] = ev_mtlocount;
   int_in[15] = ev_mthicount;
   addr_in[0] = ev_mmgpbuff;

   crys_if (25);

   *ev_mmox      = int_out[1];
   *ev_mmoy      = int_out[2];
   *ev_mmbutton  = int_out[3];
   *ev_mmokstate = int_out[4];
   *ev_mkreturn  = int_out[5];
   *ev_mbreturn  = int_out[6];

   return (intout[0]);
}

8.7.7 evnt_timer

8.7.7.1 Bindings for evnt_timer

int16_t evnt_timer (int16_t ev_tlocount, int16_t ev_thicount)
{
   int_in[0] = ev_tlocount;
   int_in[1] = ev_thicount;

   return ( crys_if (24) );
}

8.7.8 Messages

Standard messages of the screen-manager are built up as follows:

Types of standard messages:

Support of the newer message types can be inquired with appl_getinfo (opcode 12). Incidentally, for user-defined messages Digital Research has suggested message numbers beyond 1024.

About the size of the message buffer:

An individual application should not use more than 16 windows under MagiC 2.0, as otherwise the message buffer of the system can overflow and possibly redraws can no longer be performed.

See also: evnt_multi   evnt_mesag   AV protocol   OLGA protocol   Drag&Drop

8.7.9 Message-list

8.7.9.1 The CAB protocol

The CAB protocol consists of a series of AES messages with whose aid any GEM programs can devolve certain tasks to CAB, or coordinate certain actions with CAB.

The contents of the environmental variable BROWSER= (if defined) holds CAB's access path. If CAB is not already in memory, then a program can launch CAB subsequently via this variable.

A possible application: If one offers further current information or updates for one's own programs on the internet, one could use the CAB protocol to provide access to this information from within these programs with little effort. CAB then takes care of the download of the data and its presentation.

Description of the messages

CAB_HELLO (0xCAB8) (message from CAB)
CAB transmits after its launch the following message to all running programs:

msg[0] = 0xCAB8
msg[1] = Id von CAB
msg[2] = 0
msg[3] = Version of the CAB protocol (0x0100 corresponds to V1.00)
msg[4] = Bit-vector with the internet protocols supported by CAB
         (CAB.OVL):
             Bit 0: HTTP
             Bit 1: FTP
             Bit 2: GOPHER
             Bit 3: WAIS
             Bit 4: MAILTO
             Bit 5: NNTP
             Bit 6: TELNET
             Bit 7-15: 0 (reserved)
msg[5] = Bit-vector with the CAB protocol messages supported by CAB:
             Bit 0: CAB_VIEW
             Bit 1: CAB_MAIL, CAB_MAILSENT
             Bit 2: CAB_REQUESTSTATUS, CAB_RELEASESTATUS, CAB_STATUS,
                    CAB_EXIT
             Bit 3-15: 0 (reserved)
msg[6] = 0
msg[7] = 0

CAB_SUPPORT (0xCABB) (message to CAB)
If this message is sent to CAB, then CAB sends back the message CAB_HELLO. If CAB_HELLO is not returned, then an old version of CAB is being used that does not yet support the CAB protocol. All programs that are interested in the information that CAB_HELLO delivers should send CAB_SUPPORT to CAB after their launch. If CAB is only launched later, then CAB_HELLO is sent automatically to the program.

msg[0] = 0xCABB
msg[1] = Id des PRGs
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_VIEW (0xCAB3) (message to CAB)
Similar to VA_START, but instead of a fielname a URL is passed. CAB then displays this file.

msg[0] = 0xCAB3
msg[1] = ID of the PRG
msg[2] = 0
msg[3] = \ Pointer to the URL
msg[4] = /
msg[5] = If a 1 was entered here CAB displays the URL in a new window;
         if a 0 was entered, the top CAB window will be used
msg[6] = 0
msg[7] = 0

CAB_REQUESTSTATUS (0xCAB5) (message to CAB)
This can be sent to CAB to check whether CAB is currently online or offline. CAB subsequently sends the message CAB_STATUS at each change of the online/offline state.

msg[0] = 0xCAB5
msg[1] = ID of the PRG
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_RELEASESTATUS (0xCAB7) (message to CAB)
This should be sent to CAB when a program is no longer interested in the on/offline information that was requested with CAB_REQUESTSTATUS (e.g. because it terminates itself).

msg[0] = 0xCAB7
msg[1] = ID of the PRG
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_STATUS (0xCAB6) (message from CAB)
This is sent by CAB to all programs that have registered themselves with CAB_REQUESTSTATUS.

msg[0] = 0xCAB6
msg[1] = ID of the PRG
msg[2] = 0
msg[3] = 1 if CAB online; 0 if CAB offline
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_EXIT (0xCAB1) (message from CAB)
This is sent by CAB as soon as CAB terminates to all programs that have registered themselves with CAB_REQUESTSTATUS. Before this a CAB_STATUS is sent in which the offline state is reported.

msg[0] = 0xCAB1
msg[1] = ID of the PRG
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_MAIL (0xCAB9) (message to CAB)
This can be sent to CAB to transmit mails.

msg[0] = 0xCAB9
msg[1] = ID of the PRG
msg[2] = 0

msg[3] = \ Pointer to the URL; a subject can be appended directly to
msg[4] = / the URL, separated by a question mark

msg[5] = \ Pointer to a file holding the mail contents, or NULL (in
msg[6] = / which case CAB opens an editor into which the mail can be
           entered)

msg[7] = Bit-vector with further options:
             Bit 0: 0 if the mail file is to be sent immediately, or 1
                    if the mail file is still to be edited/altered in
                    CAB by the user
             Bit 1: With 1 the mail file will be deleted after it has
                    been sent, while 0 means it will be retained
             Bit 2-15: 0 (reserved)

CAB_MAILSENT (0xCABA) (message from CAB)
This is sent by CAB to the program that has sent CAB_MAIL and contains infomation whether sending of the mail worked correctly or not.

msg[0] = 0xCABA
msg[1] = ID of CAB
msg[2] = 0
msg[3] = 1 if the mail was sent without error; 0 if an error occurred
         (in which case one can find the cause of the error in msg[4])
msg[4] = Contains an error number if msg[3]=0
              0: No URL specified
              1: Offline, net connection failed, server not accessible
              2: User has aborted the action (if the mail is to be
                 modified in CAB, the user has the option of aborting
                 the action)
              3: GEMDOS error on accessing the mail file
              4: Editor for modifying the file could not be called
msg[5] = 0
msg[6] = 0
msg[7] = 0

Special messages for 'Cache-Tools'

CAB_CHANGED (0xCAB0) (message to/from CAB)
The cache (or CACHE.CAB) has been changed and should be read in anew.

msg[0] = 0xCAB0
msg[1] = ID of CAB/the PRG
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_EXIT (0xCAB1) (message to/from CAB)
CAB or the Cache-Tool terminates itself (as information for the other PRG in each case).

msg[0] = 0xCAB1
msg[1] = ID of CAB/the PRG
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_PATH (0xCAB2) (message from CAB)
The local HTML directory and/or the cache directory was altered. Further information is available in the Cache-Tools documentation.

msg[0] = 0xCAB2
msg[1] = ID of CAB
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

CAB_TERM (0xCAB4) (message from CAB)
The Cache-Tool should terminate itself.

msg[0] = 0xCAB4
msg[1] = ID of CAB
msg[2] = 0
msg[3] = 0
msg[4] = 0
msg[5] = 0
msg[6] = 0
msg[7] = 0

8.7.9.2 Messages from Geneva

X_MN_SELECTED (0xE000)

This message is either accompanied by the MU_MESAG bit of an evnt_multi return, or is returned by the evnt_mesag call. When this message occurs, the message buffer contains:
 

Portion	Contents
msg[0]	0xE000
msg[3]	The object index of the menu title selected
msg[4]	The object index of the selected menu item
msg[5], [6]	The object tree of the menu item selected
msg[7]	The handle of the window containing the menu

This feature is used in conjunction with the wind_set option X_WF_MENU, described in detail, below.
 

X_WM_SELECTED (0xE100)

This message is received when the user clicks on a window gadget in a window whose flags were modified with the wind_tree function. It only occurs when the X_WTFL_CLICKS attribute is off. If the user clicks on one of the normal scroll gadgets or arrows, a standard WM_ARROWED message is sent to the application. However, when the user clicks on any other gadget, an X_WM_SELECTED message is sent:
 

Portion	Contents
msg[0]	0xE100
msg[3]	The handle of the window containing the gadget
msg[4]	The object index of the window tree object the user
	clicked on

This feature is used by the Task Manager's "Keyboard..." dialog.
 

X_GET_HELP (0xE200)

This message is sent to the Help display program when the user requests help on a certain topic. The message is actually comprised of two parts. When the application sees the X_GET_HELP message, it must then use the appl_read function to get the entire remainder of the message, whether it intends to use the whole thing or not. The first part of the message is comprised of the following values:
 

Portion	Contents
msg[0]	0xE200
msg[1]	Application ID
msg[2]	Length of the second part ofthe message
msg[3]	Length of the topic portion of the message, including
	the NUL terminator
msg[4]	Length of the filename portion of the message, including
	the NUL terminator
msg[5]	Upper/lowercase sensitivity. If non-zero, the topic is
	case-sensitive.

The second part of the message contains the actual text of the topic and filename fields. This can be read with one or more calls to appl_read.
 
Example:
 

    void read_string( char *s, int max, int size )
    {
      char dummy;

      if( size<=max )               /* the whole string fits */
        appl_read( my_application_id, size, s );
      else
      {
        /* read what we can */
        appl_read( my_application_id, max-1, s);
        s[max-1] = '\0';            /* terminate the string   */
        /* now, get the remaining bytes of the string         */
        for( size=size-(max-1); size>0; size-- )
           appl_read( my_application_id, 1, &dummy );
      }
    }

    main()
    {
      int msg[8], caps_sens;
      char topic[20], filename[100];

      evnt_mesag( msg );
      switch( msg[0] )
      {
        case X_GET_HELP:
           caps_sens = msg[5];
          /* Read the topic portion */
           read_string( topic, sizeof(topic), msg[3] );
          /* Read the filename portion */
            read_string( filename, sizeof(filename). msg[4] );
          /* Do whatever with it... */

X_WM_HSPLIT (0xE400)

This message is sent to an application when the position of the horizontal split bar has changed:
 

Portion	Contents
msg[0]	0xE400
msg[1]	Application ID
msg[2]	0
msg[3]	Handle of the window being affected
msg[4]	The new offset (in pixels) of the split bar

The application is then free to either act upon this message and change the split bar position with wind_set(X_WF_HSPLIT), or to ignore the message completely.
 
See the x_wind_create function for more information.
 

X_WM_ARROWED2 (0xE600)

This message is sent to an application when the user has licked on one of the arrow or scroll bar gadgets which are not reported by the normal WM_ARROWED message. X_WM_ARROWED2 reports changes in gadgets which are below a vertical split bar and/or to the right of a horizontal split bar. The format of a X_WM_ARROWED2 message is identical to that of WM_ARROWED.
 
See the x_wind_create function for more information.
 

X_WM_HSLID2 (0xE700)

This message is sent to an application when the user has dragged the second horizontal scroll gadget, which appears to the right of a horizontal split bar. The format of this message is identical to that of WM_HSLID.
 
See the x_wind_create function for more information.
 

X_WM_VSLID2 (0xE800)

This message is sent to an application when the user has dragged the second vertical scroll gadget, which appears below a vertical split bar. The format of this message is identical to that of WM_VSLID.
 
See the x_wind_create function for more information.
 

X_WM_OBJECT (0xE900) (since Release 003)

This message type is returned to an application when it uses wind_set mode X_WF_OBJHAND to affect the manner in which window gadgets are handled.
 
If an application receives this message, it is because the object tree handler routine instructed Geneva not to process the mouse click on a window gadget as a normal event. Instead, a special message is returned to the application:
 

Portion	Contents
msg[0]	0xE900
msg[1]	Application ID
msg[2]	0
msg[3]	Handle of the window containing the object
msg[4]	Object tree index of the object which was clicked

Note that in order for Geneva to determine that the mouse has been clicked on an object in a window's tree structure, it must be of type EXIT or TOUCHEXIT. Geneva's default window gadgets already have these attributes set correctly.
 
See also: wind_set mode   X_WF_OBJHAND.
 

8.7.9.3 RSDAEMON_MSG

The RSDAEMON is a parallel-running application which assumes the task of the resolver with an AES message. It's intended as a kind of non-blocking gethostbyname, although the RSDAEMON only returns an IP, not a complete hostent-struct.

The RSDAEMON is normally started and terminated automatically by IConnect.

Utilization:

With appl_find("RSDAEMON") the App ID is to be obtained. In case of error one should fall back to the blocking gethostbyname, and only if nothing else is possible, break off with an error-message.

Now the RSDAEMON can be sent an AES message:

#include <rsdaemon.h>

pbuf[0]=RSDAEMON_MSG
pbuf[1]=<eigene App-ID>
pbuf[2]=0
pbuf[3]=RSD_REQUEST_IP
pbuf[4]=<Own freely choosable ID, to be able to assign the reply>
pbuf[5/6]=<Pointer to the string that contains the nname of the host>
           (Pay attention to possible memory protection!)

The RSDAEMON returns a reply of the following form:

pbuf[0]=RSDAEMON_MSG
pbuf[1]=<RSDAEMON ID>
pbuf[2]=0

pbuf[3]=RSD_IP_UNKNOWN = IP could not be obtained. This may be due to
                         various causes (user has not entered a DNS,
                         the DNS does not recognize the host etc.)
pbuf[4]=<Here the ID of the request is returned>

or:

pbuf[3]=RSD_IP_FOUND
pbuf[4]=<Here the ID of the request is returned>
pbuf[5/6]=<IP of the host as ulong>

And here still the RSDAEMON.H:

#ifndef __RSDAEMON__
#define __RSDAEMON__

#define RSDAEMON_MSG    0x995

#define RSD_REQUEST_IP  1
#define RSD_IP_FOUND    2
#define RSD_IP_UNKNOWN  3

#endif

AES

Editable object functions

Window-dialogs