HomeAESAES function listXCONTROL

8.22 AES structures

8.22.1 ANI_MOUSE

This structure is defined as follows:

typedef struct
{
   int16_t frames;
   int16_t delay;
   MFORM form[32];
} ANI_MOUSE;

See also: graf_mouse

8.22.2 APPFLAGS

This structure is defined as follows:

typedef struct
{
   int8_t  name[13];
   int8_t  desc[17];
   APFLG   flags;
   KEYCODE open_key;
   KEYCODE reserve_key[3];
}  APPFLAGS;

See also: x_appl_flags

8.22.3 APFLG

typedef union
{
   struct
   {
     unsigned multitask    :1;
     unsigned special_types:1;
     unsigned round_buttons:1;
     unsigned kbd_equivs   :1;
     unsigned undo_equivs  :1;
     unsigned off_left     :1;
     unsigned exit_redraw  :1;
     unsigned AES40_msgs   :1;
     unsigned limit_handles:1;
     unsigned limit_memory :1;
     unsigned keep_deskmenu:1;
     unsigned clear_memory :1;
     unsigned maximize_wind:1;
     unsigned unused       :3;   /* Reserved for future use       */
     unsigned mem_limit    :16;  /* Kb to limit memory allocation */
   } s;
   unsigned long l;
} APFLG;

See also: x_appl_flags   APPFLAGS

8.22.4 APPLRECORD

This structure is defined as follows:

typedef struct
{
    int32_t type;      /* Type of event                  */
    int32_t what;      /* Exact description of the event */
} APPLRECORD

For the components the following apply:

type Meaning what
   
0   Timer event Number of 50-millisecond ticks
1   Button event (high-WORD) Status of mouse buttons (0 = not depressed, 1 = depressed):
Left button: 0x0001
Right button: 0x0002

(low-WORD) Always 1
2   Mouse event X-coordinate (high-WORD), Y-coordinate (low-WORD) of hotspot
3   Keyboard event
High-Word Scancode
Low-Word State of 'special' keys (0 = not depressed, 1 = depressed):
Right [Shift]: 0x0001
Left [Shift]: 0x0002
[Control]: 0x0004
[Alternate]: 0x0008

Note: Under PC-GEM each event occupies only 6 bytes, as the component type of APPLRECORD is defined as a int16_t there.

See also: appl_tplay   appl_trecord

8.22.5 The bit-block structure

A bit-image can always be used wherever a non-selectable icon could be placed; the crucial difference is that no mask exists for a bit-image. This structure is defined as follows:

typedef struct
{
  int16_t  *bi_pdata;     /* Pointer to the graphics data  */
  int16_t  bi_wb;         /* Width of the image in bytes   */
  int16_t  bi_hl;         /* Height in lines               */
  int16_t  bi_x;          /* X-position, and               */
  int16_t  bi_y;          /* Y-position of top left corner */
  int16_t  bi_color;      /* Colour                        */
} BITBLK;

Note: The width of a bit-image (component bi_wb) must always be divisible by 2.

See also: OBJECT   AES object types

8.22.6 CICON

This structure is defined as follows:

typedef struct cicon_data
{
  int16_t num_planes;   /* Number of planes for the following data    */
  int16_t *col_data;    /* Pointer to colour bitmap in standard form  */
  int16_t *col_mask;    /* Pointer to individual colour plane mask    */
  int16_t *sel_data;    /* Pointer to colour bitmap of selected icon  */
  int16_t *sel_mask;    /* Pointer to individual plane mask of the icon */
  struct cicon_data *next_res; /* Pointer to icon of other resolution */
} CICON;

See also: CICONBLK   ICONBLK   OBJECT

8.22.7 CICONBLK

This structure is defined as follows:

typedef struct cicon_blk
{
   ICONBLK monoblk;    /* Default: monochrome icons            */
   CICON   *mainlist;  /* Colour icons for various resolutions */
} CICONBLK;

See also: OBJECT   AES object structure

8.22.8 CLRCAT

typedef struct clrcat
{
  int16_t cc_foreground     /* Foreground colour    */
  int16_t cc_background     /* Background colour    */
  int16_t cc_style          /* Fill style           */
  int16_t cc_pattern        /* Fill pattern         */
} CLRCAT;

The CLRCAT is used internally by ViewMAX/2 and later to store the colour categories.

See also: X_BUF_V2

8.22.9 DIALOG

typedef void *DIALOG;

8.22.10 DITHER_MODE

typedef struct _dither_mode
{
   struct _dither_mode  *next;    /* Pointer to successor       */
   int32_t       length;          /* Structure length           */
   int32_t       format;          /* Data format                */
   int32_t       reserved;        /* Reserved                   */
   int32_t       dither_id;       /* Dither ID                  */
   int32_t       color_modes;     /* Colour depths supported    */
   int32_t       reserved1;       /* Reserved                   */
   int32_t       reserved2;       /* Reserved                   */
   int8_t        name[32];        /* Name of the dither process */
} DITHER_MODE;

See also: Print dialogs   pdlg_add_printers

8.22.11 DRV_ENTRY

typedef struct _drv_entry
{
   struct _drv_entry *next; /* Pointer to successor  */
} DRV_ENTRY;

8.22.12 DRV_INFO

typedef struct
{
   int32_t     magic;           /* 'pdnf'                           */
   int32_t     length;          /* Structure length                 */
   int32_t     format;          /* Data format                      */
   int32_t     reserved;        /* Reserved                         */
   int16_t     driver_id;       /* Driver number for the VDI        */
   int16_t     driver_type;     /* Driver type                      */
   int32_t     reserved1;       /* Reserved                         */
   int32_t     reserved2;       /* Reserved                         */
   int32_t     reserved3;       /* Reserved                         */
   PRN_ENTRY   *printers;       /* List of printers belonging to    */
                                /* the driver                       */
   DITHER_MODE *dither_modes;   /* List of dither processes         */
                                /* supported by the driver          */
   int32_t     reserved4;       /* Reserved                         */
   int32_t     reserved5;       /* Reserved                         */
   int32_t     reserved6;       /* Reserved                         */
   int32_t     reserved7;       /* Reserved                         */
   int32_t     reserved8;       /* Reserved                         */
   int32_t     reserved9;       /* Reserved                         */
   int8_t      device[128];     /* Printer driver output file       */
} DRV_INFO;

See also: Print dialogs   pdlg_add_printers

8.22.13 EVNT

typedef struct
{
    int16_t mwhich;         /* Type of events                     */
    int16_t mx;             /* X-coordinate of the mouse pointer  */
    int16_t my;             /* Y-coordinate of the mouse pointer  */
    int16_t mbutton;        /* Pressed mouse button               */
    int16_t kstate;         /* Status of 'special' keys (kbshift) */
    int16_t key;            /* Scancode of pressed key            */
    int16_t mclicks;        /* Number of mouse clicks             */
    int16_t reserved[9];    /* Reserved                           */
    int16_t msg[16];        /* Message buffer                     */
} EVNT;

See also: fnts_evnt   fslx_evnt   wdlg_evnt

8.22.14 FNTS_ITEM

typedef struct _fnts_item
{
  struct   _fnts_item  *next; /* Pointer to next font, or 0L (end of list)  */
  UTXT_FN  display;           /* Pointer to display function for user fonts */
  int32_t  id;                /* Font ID, >= 65536 for user fonts     */
  int16_t  index;             /* Must be 0, as not a VDI font         */
  int8_t   mono;              /* Flag for mono-spaced font            */
  int8_t   outline;           /* Flag for vector font                 */
  int16_t  npts;              /* Number of predefined point sizes     */
  int8_t   *full_name;        /* Pointer to the complete name         */
  int8_t   *family_name;      /* Pointer to the family name           */
  int8_t   *style_name;       /* Pointer to the style name            */
  int8_t   *pts;              /* Pointer to field with point sizes    */
  int32_t  reserved[4];       /* Reserved, must be 0                  */
} FNTS_ITEM;

See also: fnts_add   Font selection

8.22.15 FNT_DIALOG

typedef void *FNT_DIALOG;

8.22.16 HNDL_OBJ

typedef int16_t (cdecl *HNDL_OBJ) ( void *dialog, EVNT *events, int16_t obj,
                                 int16_t clicks, void *data );
Parameter Meaning
dialog Pointer to a dialog structure. One should not access the structure directly; the wdlg_xx functions should be used!
events If obj is an object number (>= 0), then events points to the EVNT structure that was passed by wdlg_evnt; otherwise events is basically 0L and can not be used for addressing
obj
>=0: Object number
<0: Function number:
 -1 = HNDL_INIT    // Initialize dialog
 -2 = HNDL_MESG    //
 -3 = HNDL_CLSD    // Dialog window was closed
 -5 = HNDL_OPEN    // Conclude dialog initialisation
 -6 = HNDL_EDIT    // Check character for an edit field
 -7 = HNDL_EDDN    // Character was set in edit field
 -8 = HNDL_EDCH    // Edit field was changed
 -9 = HNDL_MOVE    // Dialog was moved
-10 = HNDL_TOPW    // Dialog window was topped
-11 = HNDL_UNTP    // Dialog window is not active

Of these function numbers one only has to react to HNDL_CLSD; all other events need only be paid attention to when needed
clicks Number of mouse clicks (if obj is an object number).
data If the parameter obj is a positive object number, then the variable user_data from the wdlg_create function will be passed here; otherwise the value depends on the corresponding function number

Note: The function is called when an EXIT or TOUCHEXIT object has been clicked on (in this case obj is a positive object number) or when an event pertinent to the dialog has occurred (in that case obj is negative and contains a corresponding function number (see above)).

The parameters are passed via the stack and the routine may alter registers d0-d2/a0-a2. If the function is called with an unknown function number in obj, or one of the above function numbers is to be ignored, the value 1 must be returned.

See also: Sample implementation   wdlg_create

8.22.16.1 Example for HNDL_OBJ

/* The following code is an example for an implementation of the
   handle_exit function, such as that used as a parameter for
   wdlg_create, for instance. */

int16_t cdecl handle_exit( void *dialog, EVNT *events, int16_t obj,
                         int16_t clicks, void *data )
{
    /*
     * Event or object number?
     * All events except HNDL_CLSD are ignored in this example
     */

    if( obj < 0 )
    {
        if( obj == HNDL_CLSD )     /* Closer activated? */
            return( 0 );            /* Finish */
        if( obj == HNDL_EDIT )
        {
                 /* In window-dialogs it may be useful to ignore key
                 combinations with [Control] in input fields, so that
                 keyboard shortcuts such as [Ctrl]-[U], [Ctrl]-[W] or
                 [Ctrl]-[Q] for instance may be evaluated in the event
                 loops of a program. In that case a 0 should be
                 returned after HNDL_EDIT so that the key is not
                 evaluated by objc_edit.
                 */
        }
    }
    else
    {                         /* An object has been selected */
        switch( obj )         /* Initiate action (if needed) */
        {
            case ...
              .
              .
              .
            case MY_EXIT_OBJECT:    ..... return( 0 );  /* Finish */
        }
    }
    return( 1 ); /* Continue */
}

8.22.16.2 HNDL_INIT

data is the variable passed by wdlg_create.

If handle_exit returns 0, wdlg_create does not create a dialog structure (error).

The variable code is passed in clicks.

See also: HNDL_OBJ   wdlg_create

8.22.16.3 HNDL_MESG

data is user_data.

If handle_exit returns 0, the dialog will be closed - wdlg_evnt returns 0.

events points to the EVNT structure passed by wdlg_evnt.

HNDL_MESG is only passed if a message code between 20 and 39 was received that is not processed by other opcodes. Is required for iconification, for instance.

Warning: This opcode is only present from MagiC 4.5 of 18.4.96

See also: HNDL_OBJ   wdlg_create

8.22.16.4 HNDL_OPEN

data is the variable passed by wdlg_open.

The variable code is passed in clicks.

See also: HNDL_OBJ   wdlg_create

8.22.16.5 HNDL_CLSD

data is user_data.

If handle_exit returns 0, the dialog will be closed - wdlg_evnt returns 0.

events points to the EVNT structure passed by wdlg_evnt.

See also: HNDL_OBJ   wdlg_create

8.22.16.6 HNDL_MOVE

data is user_data.

If handle_exit returns 0, the dialog will be closed - wdlg_evnt returns 0.

events points to the EVNT structure passed by wdlg_evnt.

See also: HNDL_OBJ   wdlg_create

8.22.16.7 HNDL_TOPW

data is user_data.

If handle_exit returns 0, the dialog will be closed - wdlg_evnt returns 0.

events points to the EVNT structure passed by wdlg_evnt.

See also: HNDL_OBJ   wdlg_create

8.22.16.8 HNDL_UNTP

data is user_data.

If handle_exit returns 0, the dialog will be closed - wdlg_evnt returns 0.

events points to the EVNT structure passed by wdlg_evnt.

See also: HNDL_OBJ   wdlg_create

8.22.16.9 HNDL_EDIT

data points to a WORD with the key-code.

If handle_exit returns 1, the key press will be evaluated, if the return value is 0 it will be ignored.

events points to the EVNT structure passed by wdlg_evnt.

See also: HNDL_OBJ   wdlg_create

8.22.16.10 HNDL_EDDN

data points to a WORD with the key-code.

events points to the EVNT structure passed by wdlg_evnt.

See also: HNDL_OBJ   wdlg_create

8.22.16.11 HNDL_EDCH

data points to a WORD with the object number of the new editable field.

See also: HNDL_OBJ   wdlg_create

8.22.17 ICONBLK

typedef struct
{
  uint16_t  *ib_pmask;    /* Pointer to the icon mask           */
  uint16_t  *ib_pdata;    /* Pointer to the icon image          */
  int8_t    *ib_ptext;    /* Pointer to the icon text           */
  uint16_t  ib_char;      /* Character that is to appear in the
                             icon, as well as the foreground
                             and background colour of the Icon  */
  uint16_t  ib_xchar;     /* X-coordinate of the character      */
  uint16_t  ib_ychar;     /* Y-coordinate of the character      */
  uint16_t  ib_xicon;     /* X-coordinate of the icon           */
  uint16_t  ib_yicon;     /* Y-coordinate of the icon           */
  uint16_t  ib_wicon;     /* Width of the icon                  */
  uint16_t  ib_hicon;     /* Height of the icon                 */
  int16_t   ib_xtext;     /* X-coordinate of the text           */
  int16_t   ib_ytext;     /* Y-coordinate of the text           */
  uint16_t  ib_wtext;     /* Width of the text                  */
  uint16_t  ib_htext;     /* Height of the text                 */
  uint16_t  ib_resvd;     /* Reserved                           */
} ICONBLK;

Notes about individual components:

For a colour icon under PC-GEM the following applies: In a colour icon, ib_pdata and ib_pmask point to MFDB objects. Otherwise, they point to the lines of the bitmap.

See also: CICONBLK   OBJECT

8.22.18 LBOX_ITEM

typedef struct _lbox_item
{
   struct _lbox_item *next;  /* Pointer to the next entry in the list    */
   int16_t  selected;        /* Specifies whether the object is selected */
   int16_t  data1;           /* Data for the program...                  */
   void     *data2;
   void     *data3;
} LBOX_ITEM;

However the structure can well look like the following example with appropriate casting during the call:

typedef struct
{
   void     *next;
   int16_t   selected;

   ... From here on to suit the application ...
} LB_EXAMPLE;

One only has to ensure that as the first element a pointer to the successor, and as the second element a WORD specifying whether the corresponding entry is selected are present.

See also:
lbox_create   lbox_free_list   lbox_get_idx   lbox_get_item   lbox_get_items

8.22.19 LIST_BOX

typedef void *LIST_BOX;

8.22.20 MEDIA_SIZE

Description of a paper format.

typedef struct _media_size
{
   struct _media_size *next;   /* Pointer to successor      */
   int32_t       size_id;      /* Paper format size ID      */
   int8_t        name[32];     /* Name of the paper format  */
} MEDIA_SIZE;

See also: Print dialogs   pdlg_add_printers

8.22.21 MEDIA_TYPE

Description of a paper type/print medium.

typedef struct _media_type
{
   struct _media_type   *next;    /* Pointer to successor      */
   int32_t              type_id;  /* Paper format type ID      */
   int8_t               name[32]; /* Name of the paper format  */
} MEDIA_TYPE;

See also: Print dialogs   pdlg_add_printers

8.22.22 MENU

typedef struct
{
    OBJECT  *mn_tree;    /* The object tree of the menu             */
    int16_t mn_menu;     /* The parent object of the menu items     */
    int16_t mn_item;     /* The starting menu item                  */
    int16_t mn_scroll;   /* The scroll field status of the menu:    */
                         /*  0  - The menu will not scroll          */
                         /*  >0 - The menu will scroll              */
    int16_t mn_keystate; /* The [CTRL], [ALT], [SHIFT] key state at */
                         /* the time the mouse button was pressed   */
} MENU;

See also: About the AES   menu_attach   menu_popup

8.22.23 MFORM

The structure MFORM sets the appearance of the mouse pointer, and is defined as follows:

typedef struct mfstr
{
    int16_t  mf_xhot;       /* X-position hot-spot */
    int16_t  mf_yhot;       /* Y-position hot-spot */
    int16_t  mf_nplanes;    /* Number of planes    */
    int16_t  mf_fg;         /* Mask colour         */
    int16_t  mf_bg;         /* Pointer colour      */
    int16_t  mf_mask[16];   /* Mask form           */
    int16_t  mf_data[16];   /* Pointer form        */
} MFORM;

See also: About the AES   graf_mouse

8.22.24 MN_SET

typedef struct
{
    int32_t display;    /* Submenu display delay          */
    int32_t drag;       /* Submenu drag delay             */
    int32_t delay;      /* Single-click scroll delay      */
    int32_t speed;      /* Continuous scroll delay        */
    int16_t height;     /* Menu scroll height (in items)  */
} MN_SET;

The delay values are measured in milliseconds.

See also: About the AES   menu_settings

8.22.25 OBJECT

typedef struct
{
   int16_t    ob_next;   /* The next object               */
   int16_t    ob_head;   /* First child                   */
   int16_t    ob_tail;   /* Last child                    */
   uint16_t   ob_type;   /* Object type                   */
   uint16_t   ob_flags;  /* Manipulation flags            */
   uint16_t   ob_state;  /* Object status                 */
   void       *ob_spec;  /* More under object type        */
   int16_t    ob_x;      /* X-coordinate of the object    */
   int16_t    ob_y;      /* Y-coordinate of the object    */
   int16_t    ob_width;  /* Width of the object           */
   int16_t    ob_height; /* Height of the object          */
} OBJECT;
ob_next: Number of the following object of the same generation or - if it is the last element of the generation - of the parent object
ob_head: Number of the first child of the object, if none -1
ob_next: Number of the last child of the object, if none -1
ob_type: Object type of the AES
ob_flags: Object flags of the AES
ob_state: AES object stati

See also: AES object structure

8.22.26 PARMBLK

typedef struct
{
   OBJECT   *pb_tree;        /* Pointer to the object tree         */
   int16_t  pb_obj;          /* Index of the object                */
   int16_t  pb_prevstate;    /* Previous object status             */
   int16_t  pb_currstate;    /* New object status                  */
   int16_t  pb_x;            /* X-position of the object           */
   int16_t  pb_y;            /* Y-position of the object           */
   int16_t  pb_w;            /* Width of the object                */
   int16_t  pb_h;            /* Height of the object               */
   int16_t  pb_xc;           /* X-position of the clipping region  */
   int16_t  pb_yc;           /* Y-position of the clipping region  */
   int16_t  pb_wc;           /* Width of the clipping region       */
   int16_t  pb_hc;           /* Height of the clipping region      */
   int32_t  pb_parm;         /* Parameter of USERBLK structure     */
} PARMBLK;

Note: The object only needs to be redrawn if the old and new states are identical; otherwise an 'update' of the object tree suffices. Furthermore, the following points should be respected:

See also: About the AES   GEM   USERBLK

8.22.27 PDLG_HNDL

typedef int32_t (cdecl *PDLG_HNDL)( struct _prn_settings *settings,
                                 struct _pdlg_sub *sub,
                                 int16_t exit_obj );

See also: Print dialogs   pdlg_add_sub_dialogs   PDLG_SUB

8.22.28 PDLG_INIT

typedef int32_t (cdecl *PDLG_INIT) (struct _prn_settings *settings,
                                 struct _pdlg_sub *sub );

See also: Print dialogs   pdlg_add_sub_dialogs   PDLG_SUB

8.22.29 PDLG_RESET

typedef int32_t (cdecl *PDLG_RESET) ( struct _prn_settings *settings,
                                   struct _pdlg_sub *sub );

See also: Print dialogs   pdlg_add_sub_dialogs   PDLG_SUB

8.22.30 PDLG_SUB

Sub-dialog for setting device.

typedef struct _pdlg_sub
{
   struct _pdlg_sub *next;      /* Pointer to successor in the list */
   int32_t     length;          /* Structure length                 */
   int32_t     format;          /* Data format                      */
   int32_t     reserved;        /* Reserved                         */
   void        *drivers;        /* Only for internal dialogs        */
   int16_t     option_flags;    /* Flags                            */
   int16_t     sub_id;          /* Sub-dialog ID                    */
   DIALOG      *dialog;         /* Pointer to structure of window
                                   dialog, or 0L                    */
   OBJECT      *tree;           /* Pointer to assembled object tree */
   int16_t     index_offset;    /* Index offset of the sub-dialog   */
   int16_t     reserved1;       /* Reserved                         */
   int32_t     reserved2;       /* Reserved                         */
   int32_t     reserved3;       /* Reserved                         */
   int32_t     reserved4;       /* Reserved                         */
   PDLG_INIT   init_dlg;        /* Initialisation function          */
   PDLG_HNDL   do_dlg;          /* Handling function                */
   PDLG_RESET  reset_dlg;       /* Reset function                   */
   int32_t     reserved5;       /* Reserved                         */
   OBJECT      *sub_icon;       /* Pointer to icon for the list box */
   OBJECT      *sub_tree;       /* Pointer to object tree of sub-dialog */
   int32_t     reserved6;       /* Reserved                         */
   int32_t     reserved7;       /* Reserved                         */
   int32_t     private1;        /* Dialog's private information 1   */
   int32_t     private2;        /* Dialog's private information 2   */
   int32_t     private3;        /* Dialog's private information 3   */
   int32_t     private4;        /* Dialog's private information 4   */
} PDLG_SUB;

See also: Print dialogs   pdlg_add_sub_dialogs

8.22.31 POPINFO

typedef struct
{
    OBJECT  *tree;     /* Popup menu               */
    int16_t  obnum;    /* Current object of  */
} POPINFO;

Note: The component tree points to an object tree which might serve as input for form_popup, for instance. This means that the box should contain as object 0 a G_BOX or G_IBOX which is covered completely by the other objects. Objects that are not selectable should be assigned a DISABLED state, as in a dropdown menu.

All selectable objects must have the state SELECTABLE. In addition, for using with G_POPUP, all selectable objects must be of the type G_STRING (or G_SHORTCUT) or G_BUTTON, and start with two spaces, the latter due to the tick that is set automatically by form_button or form_do!

It is important that ob_x and ob_y of object 0 of the menu is specified relative to the G_POPUP object, i.e. usually they will both be 0. It is recommended that a shadow or a frame of width -1 is specified.

See also: MagiC   G_POPUP

8.22.32 PRN_DIALOG

typedef void *PRN_DIALOG;

8.22.33 PRN_ENTRY

typedef struct _prn_entry
{
   struct _prn_entry *next;          /* Pointer to next device description*/
   int32_t     length;               /* Structure length                  */
   int32_t     format;               /* Data format                       */
   int32_t     reserved;             /* Reserved                          */
   int16_t     driver_id;            /* Driver ID                         */
   int16_t     driver_type;          /* Driver type                       */
   int32_t     printer_id;           /* Printer ID                        */
   int32_t     printer_capabilities; /* Printer capabilities              */
   int32_t     reserved1;            /* Reserved                          */
   int32_t     flags;                /* Various flags                     */
   struct _pdlg_sub  *sub_dialogs;   /* Pointer to list of sub-dialogs    */
                                     /* for this printer                  */
   PRN_SWITCH  setup_panel;          /* Initialize sub-dialog at printer  */
                                     /* change                            */
   PRN_SWITCH  close_panel;          /* Close sub-dialog at printer change*/
   PRN_MODE    *modes;               /* List of available resolutions     */
   MEDIA_SIZE  *papers;              /* List of available paper formats   */
   PRN_TRAY    *input_trays;         /* List of feed trays                */
   PRN_TRAY    *output_trays;        /* List of output trays              */
   int8_t      name[32];             /* Name of the printer               */
} PRN_ENTRY;

See also: Print dialogs   pdlg_add_printers

8.22.34 PRN_MODE

Description of a print mode.

typedef struct _prn_mode
{
   struct _prn_mode *next;         /* Pointer to the next print mode  */
   int32_t     mode_id;            /* Mode ID (index within the file) */
   int16_t     hdpi;               /* Horizontal resolution in dpi    */
   int16_t     vdpi;               /* Vertical resolution in dpi      */
   int32_t     mode_capabilities;  /* Mode capabilities               */
   int32_t     color_capabilities; /* Colour capabilities             */
   int32_t     dither_flags;       /* Flags specifying whether the
                                      corresponding colour mode is
                                      accessible with or without
                                      dithering                        */
   MEDIA_TYPE  *paper_types;       /* Suitable paper types             */
   int32_t     reserved;           /* Reserved                         */
   int8_t      name[32];           /* Mode name                        */
} PRN_MODE;

See also: Print dialogs   pdlg_add_printers

8.22.35 PRN_SETTINGS

typedef struct _prn_settings
{
   int32_t  magic;            /* 'pset'                              */
   int32_t  length;           /* (+) Structure length                */
   int32_t  format;           /* Structure type                      */
   int32_t  reserved;         /* Reserved                            */
   int32_t  page_flags;       /* (+) Flags, inc. even/odd pages:
                                  0x0001 = Only pages with even number
                                  0x0002 = Only pages with odd number*/
   int16_t  first_page;       /* (+) First page to print (min. 1)    */
   int16_t  last_page;        /* (+) Last page to print (max. 9999)  */
   int16_t  no_copies;        /* (+) Number of copies                */
   int16_t  orientation;      /* (+) Page orientation:
                                  0x0000 =  Orientation unknown and
                                            not adjustable
                                  0x0001 = Output in portrait format
                                  0x0002 = Output in landscape format*/
   int32_t  scale;            /* (+) Scaling: 0x10000L = 100%        */
   int16_t  driver_id;        /* (+) VDI device number               */
   int16_t  driver_type;      /* Type of the selected driver         */
   int32_t  driver_mode;      /* Flags, inc. for background printing */
   int32_t  reserved1;        /* Reserved                            */
   int32_t  reserved2;        /* Reserved                            */
   int32_t  printer_id;       /* Printer ID number                   */
   int32_t  mode_id;          /* Mode ID number                      */
   int16_t  mode_hdpi;        /* Horizontal resolution in dpi        */
   int16_t  mode_vdpi;        /* Vertical resolution in dpi          */
   int32_t  quality_id;       /* Printing mode (hardware-dependent
                                 quality, e.g. Microweave or Econofast)*/
   int32_t  color_mode;       /* Colour mode                         */
   int32_t  plane_flags;      /* Flags for colour planes to be output
                                 (e.g. cyan only)                    */
   int32_t  dither_mode;      /* Rasterizing (dithering) process     */
   int32_t  dither_value;     /* Parameter for the dithering process */
   int32_t  size_id;          /* Paper format                        */
   int32_t  type_id;          /* Paper type (normal, glossy)         */
   int32_t  input_id;         /* Paper feed tray                     */
   int32_t  output_id;        /* Paper output tray                   */
   int32_t  contrast;         /* Contrast:   0x10000L = normal       */
   int32_t  brightness;       /* Brightness: 0x1000L  = normal       */
   int32_t  reserved3;        /* Reserved                            */
   int32_t  reserved4;        /* Reserved                            */
   int32_t  reserved5;        /* Reserved                            */
   int32_t  reserved6;        /* Reserved                            */
   int32_t  reserved7;        /* Reserved                            */
   int32_t  reserved8;        /* Reserved                            */
   int8_t   device[128];      /* Filename for the printout           */
   #ifdef __PRINTING__
   TPrint   mac_settings;     /* Setting of the Mac printer driver   */
   #else
   struct
   {
      uint8_t inside[120];
   } mac_settings;
   #endif
} PRN_SETTINGS;

Note: The structure elements marked with (+) can be read out by the application. All other entries should not be accessed. Data such as the printer resolution or number of colours should not be taken from the setting structure, but inquired for from the printer at the start of the printout (it would be possible, for instance, that due to a memory shortage the printer driver is forced to use a lower resolution compared to that entered in PRN_SETTINGS).

See also: Print dialogs   pdlg_open

8.22.36 PRN_SWITCH

typedef int32_t (cdecl *PRN_SWITCH) ( struct _drv_entr *drivers,
                                   struct _prn_settings *settings,
                                   struct _prn_entry *old_printer,
                                   struct _prn_entry *new_printer );

Note: The component old_printer can also be 0L!

See also: Print dialogs   pdlg_add_printers

8.22.37 PRN_TRAY

Description of a feed/output tray.

typedef struct _prn_tray
{
   struct _prn_tray  *next;    /* Pointer to successor              */
   int32_t           tray_id;  /* Number of the feed or output tray */
   int8_t            name[32]; /* Name of the tray                  */
} PRN_TRAY;

See also: Print dialogs   pdlg_add_printers

8.22.38 RSHDR

typedef struct
{
   uint16_t rsh_vrsn;      /* Null                              */
   uint16_t rsh_object;    /* Position of the object field      */
   uint16_t rsh_tedinfo;   /* Position of the TEDINFO structs   */
   uint16_t rsh_iconblk;   /* Position of the ICONBLK structs   */
   uint16_t rsh_bitblk;    /* Position of the BITBLK structs    */
   uint16_t rsh_frstr;     /* Position of the free strings      */
   uint16_t rsh_string;    /* Unused                            */
   uint16_t rsh_imdata;    /* Position of image data            */
   uint16_t rsh_frimg;     /* Position of the free images       */
   uint16_t rsh_trindex;   /* Position of the object tree table */
   uint16_t rsh_nobs;      /* Total number of objects           */
   uint16_t rsh_ntree;     /* Total number of trees             */
   uint16_t rsh_nted;      /* Total number of TEDINFO structs   */
   uint16_t rsh_nib;       /* Total number of ICONBLK structs   */
   uint16_t rsh_nbb;       /* Total number of BITBLK structs    */
   uint16_t rsh_nstring;   /* Total number of strings           */
   uint16_t rsh_nimages;   /* Total number of images            */
   uint16_t rsh_rssize;    /* Total bytes in resource           */
} RSHDR;

Note: All position specifications are to be understood as relative to the start of the file.

A word about the 'free strings': These include not just the character strings containing the data for alert boxes etc., but also all other strings that a program uses for its work. An example of this would be the filename or a file to be read in, or an entry that is altered with menu_text in a menu.

This header is followed by the actual resource data. One should note here that a resource file can have a total size of 64 kbyte maximum, due to the use of 16-bit values as pointers. Files of this format can be saved by all RCS (Resource Construction Set) programs.

Users of the programs Interface and RSM (Resource Master) can also work with resource files > 64 kbyte. The operating system MagiC as of version 3 also supports resource files larger than 64 kbyte; loading of the resource is performed with rsrc_load as usual, the rest is handled quite transparently by the system.

See also: rsrc_rcfix   RSXHDR

8.22.39 RSXHDR

typedef struct
{
  uint16_t rsh_vrsn;     /* Version number, should be 3 for new format  */
  uint16_t rsh_extvrsn;  /* Not used,                                   */
                         /* initialized to 'IN' for Interface,          */
                         /* 'RM' for ResourceMaster                     */
  uint32_t rsh_object;   /* Offset to OBJECT structures from file start */
  uint32_t rsh_tedinfo;  /* Offset to TEDINFO structures                */
  uint32_t rsh_iconblk;  /* Offset to ICONBLK structures                */
  uint32_t rsh_bitblk;   /* Offset to BITBLK structures                 */
  uint32_t rsh_frstr;    /* Offset to string pointer table              */
  uint32_t rsh_string;   /* Offset to string data                       */
  uint32_t rsh_imdata;   /* Offset to image data                        */
  uint32_t rsh_frimg;    /* Offset to image pointer table               */
  uint32_t rsh_trindex;  /* Offset to tree pointer table                */
  uint32_t rsh_nobs;     /* Number of OBJECTs in the file               */
  uint32_t rsh_ntree;    /* Number of object trees in the file          */
  uint32_t rsh_nted;     /* Number of TEDINFOs in the file              */
  uint32_t rsh_nib;      /* Number of ICONBLKs in the file              */
  uint32_t rsh_nbb;      /* Number of BITBLKs in the file               */
  uint32_t rsh_nstring;  /* Number of free strings in the file          */
  uint32_t rsh_nimages;  /* Number of free images in the file           */
  uint32_t rsh_rssize;   /* In the newer format files this value can be
                            used as an offset to the extension array    */
} RSXHDR;

See also: rsrc_load   RSHDR

8.22.40 SCANX

typedef struct
{
    int8_t   scancode;
    int8_t   nclicks;
    int16_t  objnr;
} SCANX;

Note: The structure contains the assignment for the key with the scancode scancode, which when pressed performs an nclicks times mouse click on the object with the index objnr. The end of the table is marked by a scancode of NULL.

See also: About the AES   MagiC   XDO_INF   Scancode table

8.22.41 SET_ITEM

typedef int16_t (cdecl *SET_ITEM)( LIST_BOX *box, OBJECT *tree,
                                struct _lbox_item *item,
                                int16_t obj_index, void *user_data,
                                GRECT *rect, int16_t first );
Parameter Meaning
box points to the list box structure
tree points to the object tree of the dialog
item points to the LBOX_ITEM structure of the entry to be set
obj_index is the number of the object to be set
user_data is the pointer passed by lbox_create
rect is the pointer to the GRECT for the object redraw or 0L
first contains the number of the first visible item for Slider B

For a list box that only contains text strings, is typically a function that copies a string pointed to by the LBOX_ITEM structure into the object obj_index.

rect is 0L when a redraw of the dialog box is executed or when lbox_update has been called. rect is not 0L when the user has selected or deselected an object, and points to the GRECT for the redraw.

The return value is the number of the start object for objc_draw/wdlg_redraw.

For entries in the list box that consist of several objects it is sometimes sensible to reduce the redraw rectangle when selecting/ deselecting an object, or to alter the start object, to prevent unnecessary drawing operations and/or unnecessary flicker. In most cases the list box routines call the function objc_draw/wdlg_redraw after to display the altered contents.

first contains the number of the first visible item for Slider B if the list box has two sliders. For a (vertical) list box with text strings and two sliders, when calling lbox_create, for instance, one enters the number of visible characters in visible_b, the total string length in entries_b and the index of the first visible character in first_b. If the text is scrolled horizontally, is called for all visible strings and the affected parts of the screen are redrawn or moved. If the list box has only one slider, first is always 0.

See also: List boxes   lbox_create

8.22.42 SHELTAIL

typedef struct
{
    int16_t dummy;       /* A NULL-WORD                 */
    int32_t magic;       /* 'SHEL', if it's a shell     */
    int16_t isfirst;     /* First call of the shell     */
    int32_t lasterr;     /* Last error                  */
    int16_t wasgr;       /* Program was a graphic-app.  */
} SHELTAIL;

Note: This information is conveyed to an alternative desktop by MagiC at program launch (can be obtained by shel_read). If the shell returns a negative error code, then MAGXDESK will be reactivated.

If isfirst is set then the status is to be read from something like DESKTOP.INF, if isfirst is not set then one takes the temporary file or shell-buffer.

lasterr is the return value of the program running previously. If this was a GEM program then the error will already have been displayed in an alert box. It is well known that the LONGword is negative if the error occurred with Pexec itself; a program return value always has the high-WORD 0.

See also: About the AES   GEM   shel_wdef

8.22.43 SLCT_ITEM

typedef void (cdecl *SLCT_ITEM)( LIST_BOX *box, OBJECT *tree,
                                 struct _lbox_item *item,
                                 void *user_data, int16_t obj_index,
                                 int16_t last_state );

The following apply:

Parameter Meaning
box points to the list box structure
tree points to the object tree of the dialog
item points to the LBOX_ITEM-structure of the selected entry
user_data is the pointer passed by lbox_create
obj_index is the number of the selected object. For a double-click the top bit is set, similar to form_do. If it is 0, it signifies that no object is assigned to this entry; it is not visible. Normally this is only the case when one is scrolling and by selecting a new object the (now no longer visible) selection has to be cleared.
last_state is the previous status of the object. last_state can also have the same value as item->selected. In that case one can normally quit the function immediately.

See also: lbox_create

8.22.44 SWINFO

typedef struct
{
    int8_t  *string;     /* Perhaps 'TOS|KAOS|MAG!X'            */
    int16_t  num;        /* Index of current character string   */
    int16_t  maxnum;     /* Maximum permitted num               */
} SWINFO;

See also: About the AES   GEM   G_SWBUTTON

8.22.45 TEDINFO

The TEDINFO structure is used to describe a text object more exactly, and is defined as follows:

typedef struct
{
    int8_t    *te_ptext;          /* Pointer to a string              */
    int8_t    *te_ptmplt;         /* Pointer to the string template   */
    int8_t    *te_pvalid;         /* Pointer to the validation string */
    int16_t    te_font;           /* Font type                        */
    int16_t    te_fontid;         /* GDOS Font ID                     */
    int16_t    te_just;           /* Text alignment:
                                      0 = Ranged left
                                      1 = Ranged right
                                      2 = Centred                     */
    int16_t    te_color;          /* Colour                           */
    int16_t    te_fontsize;       /* GDOS font size in points         */
    int16_t    te_thickness;      /* Border width                     */
    int16_t    te_txtlen;         /* Maximum length of the text       */
    int16_t    te_tmplen;         /* Length of the string template    */
} TEDINFO;

The following matters should be noted for this:

Note: The components te_fontid and te_fontsize were previously reserved. As of AES Version 4.1 it is possible to use any GDOS fonts for TEDINFO objects.

For this one should specify with the component te_font the type of the font. The following apply:

te_font Meaning
0 SpeedoGDOS font
1 SpeedoGDOS font (monospaced)
2 GDOS bitmap font
3 Normal system font
5 Small system font

To use values 0 and 1 of te_font, SpeedoGDOS or a substitute (such as NVDI) has to be installed on the system.

For values in the region 0..2 of te_font one can then set with the components te_fontid or te_fontsize the desired font and the desired point size.

The simplest way to check the presence of the new possibilities is to call appl_getinfo (opcode 13).

See also:
About the AES   GEM   OBJECT   XTED   Scrollable input fields

8.22.46 USERBLK

typedef struct
{
   int16_t cdecl (*ub_code)(PARMBLK *parmblock);
   int32_t ub_parm;
} USERBLK;

Note: The function ub_code is called for each call of objc_draw and objc_change for the corresponding object. The component ub_parm can be looked on as an optional parameter.

8.22.47 UTXT_FN

This function is declared as follows:

typedef void (cdecl *UTXT_FN) (int16_t x, int16_t y, int16_t *clip_rect,
                               int32_t id, int32_t pt, int32_t ratio,
                               int8_t *string);

See also: About the AES   fnts_add   FNTS_ITEM   Font selection

8.22.48 WINFRAME_HANDLER

Passing structure for linking in

typedef struct {
  int16_t   version;                  /* Version number of structure  */
  int32_t   wsizeof;                  /* Size of the WINDOW-structure */
  int16_t   whshade;                  /* Height of the shaded window  */
  void      (*wbm_create)( WININFO *w );
  void      (*wbm_skind) ( WININFO *w );
  void      (*wbm_ssize) ( WININFO *w );
  void      (*wbm_sslid) ( WININFO *w, int16_t vertical );
  void      (*wbm_sstr)  ( WININFO *w );
  void      (*wbm_sattr) ( WININFO *w, int16_t chbits );
  void      (*wbm_calc)  ( int16_t kind, int16_t *fg );
  int16_t   (*wbm_obfind)( WININFO *w, int16_t x, int16_t y );
} WINFRAME_HANDLER;

See also:
sys_set_winframe_manager   WININFO   WINFRAME_SETTINGS

8.22.49 WINFRAME_SETTINGS

Passing structure for global window settings

typedef struct {
  int16_t   flags;
  int16_t   h_inw;
  void      *finfo_inw;
} WINFRAME_SETTINGS;

Bits of flags:
#define NO_BDROP 1

See also:
sys_set_winframe_manager   WINFRAME_HANDLER   WININFO

8.22.50 WININFO

WINDOW-structure for MagiC-kernel

typedef struct {
  int16_t   state;
  int16_t   attr;
  void      *own;         /* (APPL *)                     */
  int16_t   kind;         /* from wind_create()           */
  char      *name;        /* Pointer to title line        */
  char      *info;        /* Pointer to Info line         */
  GRECT     curr;
  GRECT     prev;
  GRECT     full;
  GRECT     work;
  GRECT     overall;      /* Outline                      */
  GRECT     unic;
  GRECT     min;          /* Minimum size                 */
  int16_t   oldheight;    /* Old height of shading        */
  int16_t   hslide;       /* Horizontal slider position   */
  int16_t   vslide;       /* Vertical slider position     */
  int16_t   hslsize;      /* Horizontal slider size       */
  int16_t   vslsize;      /* Vertical slider size         */
  void      *wg;          /* Rectangle list               */
  void      *nextwg;      /* Next rectangle of the list   */
  int16_t   whdl;
  OBJECT    tree[N_OBJS];
  int16_t   is_sizer;
  int16_t   is_info;
  int16_t   is_rgtobjects;
  int16_t   is_botobjects;
  TEDINFO   ted_name;
  TEDINFO   ted_info;
} WININFO;

Bits of state:
#define OPENED 1
#define COVERED 2
#define ACTIVE 4
#define LOCKED 8
#define ICONIFIED 32
#define SHADED 64

See also:
sys_set_winframe_manager   WINFRAME_HANDLER   WINFRAME_SETTINGS

8.22.51 XAESMSG

This structure is defined as follows:

typedef struct
{
   int16_t  dst_apid;       /* ID of target application  */
   int16_t  unique_flg;     /* Overwrite messages?       */
   void     *attached_mem;  /* Pointer to memory block   */
   int16_t  *msgbuf;        /* Message buffer            */
} XAESMSG;

Note: The component unique_flg specifies if kindred messages (i.e. those with the same message type msgbuf[0]) are to be overwritten by the new message.

If attached_mem is not NULL, it is used to specify a memory block allocated with Malloc that contains the extended message information. The length of this block is arbitrary and is of no interest to the system - for instance it could be passed as the first LONGword of the block, or in msgbuf [4,5]. The system allocates the memory block to the destination application and passes its address in msgbuf[6,7].

Important: The called application must assume that msgbuf[6,7] are destroyed after a call of appl_write. The system reserves the right to copy the contents of the memory block elsewhere and to release the passed block. The caller may no longer access the block after an appl_write call, and may on no account release it!

If appl_write returns an error code, then the block has not been passed and still belongs to the calling application. An error arises when:

See also: About the AES   appl_write   GEM

8.22.52 XDO_INF

typedef struct
{
    SCANX *unsh;    /* Tables for non-[Shift] combinations   */
    SCANX *shift;   /* Tables for [Shift] combinations       */
    SCANX *ctrl;    /* Tables for [Control] combinations     */
    SCANX *alt;     /* Tables for [Alternate] combinations   */
    void  *resvd;   /* Reserved   */
} XDO_INF;

Note: This structure contains pointers to tables that assign to a scancode an object index of the dialog box. This makes it simple to service dialogs completely via the keyboard. The parameter resvd is reserved for future use, and must always be NULL.

See also:
About the AES   form_keybd   form_xdo   MagiC   Scancode table

8.22.53 XFONTINFO

typedef struct
{
   int16_t font_id;
   int16_t point_size;
   int16_t gadget_wid;
   int16_t gadget_ht;
} XFONTINFO;

See also: x_appl_font

8.22.54 XFSL_FILTER

typedef int16_t (cdecl XFSL_FILTER) (int8_t *path, int8_t *name, XATTR *xa);

See also: fslx_do   fslx_open

8.22.55 XSHW_COMMAND

typedef struct
{
   int8_t  *command;
   int32_t limit;
   int32_t nice;
   int8_t  *defdir;
   int8_t  *env;
} XSHW_COMMAND;

See also: shel_write

8.22.56 XTED

This structure is required in connection with scroll-capable editable text fields.

typedef struct _xted
{
   int8_t  *xte_ptmplt;
   int8_t  *xte_pvalid;
   int16_t xte_vislen;
   int16_t xte_scroll;
} XTED;

See also: Scrollable input fields   TEDINFO

8.22.57 X_BUF_V2

typedef struct x_buf_v2
{
int16_t  buf_len   /* Length of the structure, including this WORD       */
                   /* Future versions of this structure (X_BUF_V3 etc.)  */
                   /* may be bigger                                      */
int16_t  arch      /* 16 for 16-bit AES, 32 for hypothetical 32-bit AES  */
CLRCAT   *cc       /* Address of an array of 16 CLRCAT structures -      */
                   /* this is so that they can be read by a program; in  */
                   /* ViewMAX, the colours could be set but not reread   */
OBJECT   *w_active /* Address of an object tree (19 elements) used to    */
                   /* draw window elements; included so a program can    */
                   /* change symbols on window buttons                   */
int8_t   *info     /* Address of a 0-terminated ASCII string (at most    */
                   /* 40 characters, no newlines) describing the AES     */
int32_t  abilities /* A bitmapped field describing what optional         */
                   /* functions this AES provides:                       */
/* ABLE_GETINFO  1    bit 0 : xapp_getinfo supported                     */
/* ABLE_PROP     2    bit 1 : prop_get, prop_put and prop_del supported  */
/* ABLE_WTREE    4    bit 2 : wind_get and wind_set can change glyphs    */
/* ABLE_X3D      8    bit 3 : GEM/5 3D using DRAW3D                      */
/* ABLE_XSHL    16    bit 4 : xshl_getshell & xshl_putshell              */
/* ABLE_PROP2   32    bit 5 : prop_gui_get, prop_gui_set                 */
/* ABLE_EMSDESK 64    bit 6 : xgrf_dtimage supports EMS                  */
/* ABLE_XBVSET 128    bit 7 : Supports 32 disc drives                    */
} X_BUF_V2;

An initialized X_BUF_V2 is one in which all members are 0 except buf_len. This initialized buffer is then passed to appl_init. On return, if arch is 0 then the structure was not filled in by the AES; otherwise it was. The buf_len field may be reduced if the AES was expecting an earlier version of the structure (i.e. X_BUF_V1); this should not be a problem because the structures are forward and backward compatible.

See also: appl_init


HomeAESAES function listXCONTROL