#ifndef APILIB_H #define APILIB_H /* ** $Filename: developer/api/include/apilib.h ** $Release: 5 ** ** API definitions ** ** (C) Copyright 1998 Dietmar Eilert ** All Rights Reserved */ #ifndef EXEC_TYPES_H #include #endif #ifndef EXEC_LISTS_H #include #endif #ifndef EXEC_LISTS_H #include #endif #ifndef INTUITION_INTUITION_H #include #endif #ifndef UTILITY_TAGITEM_H #include #endif #ifndef WORKBENCH_WORKBENCH_H #include #endif #ifndef MAKE_ID #define MAKE_ID(a,b,c,d) ((ULONG) (a)<<24 | (ULONG) (b)<<16 | (ULONG) (c)<<8 | (ULONG) (d)) #endif #define API_MAGIC MAKE_ID('A','P','I','5') /* library base */ struct APIBase { struct Library Library; /* standard library */ UWORD pad; /* we are now longwod aligned */ ULONG Magic; /* used to recognize API libraries */ }; /* -------------------------------- APIMessage --------------------------------- API messages are sent from a host (or an instance of the host) to clients. API messages are linked (api_Next; may be NULL). The client has to check the api_State field before processing the message (must be API_STATE_NOTIFY). Check the api_Class field to determine the basic message type (e.g. API_CLASS_SCREEN if the message is related to screen handling). Check the api_Action field to determine the actual command (e.g. API_ACTION_HIDE if the host wants you to close your windows). A client should update the api_Error field after having processed the message. */ struct APIMessage { /* info slots */ ULONG api_State; /* message state (see below); set by host, updated by client */ struct APIMessage *api_Next; /* next message */ struct APIInstance *api_Instance; /* host instance */ /* command slots */ ULONG api_Class; /* set by host: notify class (see below) */ ULONG api_Action; /* set by host: notify code (see below) */ ULONG api_Qualifier; /* set by host: intuition qualifier of last input event */ APTR api_Data; /* set by host: all-purpose slot; usage depends on api_Class */ UBYTE *api_Command; /* set by host: command string passed to client (read-only), command part uppercase */ /* return code slots */ LONG api_RC; /* set by client: client's primary return code */ UBYTE *api_CommandResult; /* set by client: command result string */ UBYTE *api_CommandError; /* set by client: command error string */ ULONG api_Error; /* set by client: return code (see below) */ ULONG api_Refresh; /* set by client: display refresh request */ struct APIOrder *api_Order; /* set by client: orders (depends on command set of host) */ UBYTE *api_Status; /* set by client: status message */ }; /* supported api_State values */ #define API_STATE_IGNORE 0 /* this messages should be ignored */ #define API_STATE_NOTIFY 1 /* this is a standard notify message */ #define API_STATE_CONSUMED 2 /* message consumed (not to be passed to other clients) */ /* api action classes */ #define API_CLASS_SCREEN (1L<<1) /* screen handling */ #define API_CLASS_KEY (1L<<2) /* keyboard event */ #define API_CLASS_COMMAND (1L<<3) /* command event */ #define API_CLASS_SYSTEM (1L<<6) /* notifies */ #define API_CLASS_IO (1L<<7) /* IO */ #define API_CLASS_CONTAINER (1L<<8) /* container events */ /* Supported api_Action values for API_CLASS_KEY */ #define API_ACTION_VANILLAKEY 1 /* vanillakey event; key code passed in api_Data */ #define API_ACTION_RAWKEY 2 /* rawkey event; key code passed in api_Data */ /* Supported api_Action values for API_CLASS_SCREEN */ #define API_ACTION_HIDE 1 /* close your output (host is about to close display) */ #define API_ACTION_SHOW 2 /* show your output */ /* Supported api_Action values for API_CLASS_COMMAND */ #define API_ACTION_COMMAND 1 /* command passed to client (api_Command) */ /* Supported api_Action values for API_CLASS_SYSTEM */ #define API_ACTION_WELCOME 1 /* first message sent to client */ #define API_ACTION_EXIT 2 /* announces pending termination of client */ #define API_ACTION_SAVEPREFS 3 /* request to save preferences */ /* Supported api_Action values for API_CLASS_IO */ #define API_ACTION_SAVE 1 /* save operation pending (pointer to file name in api_Data) */ #define API_ACTION_CREATED 2 /* file saved (pointer to file name in api_Data) */ #define API_ACTION_READ 4 /* file read (pointer to file name in api_Data) */ /* Supported api_Action values for API_CLASS_CONTAINER */ #define API_ACTION_SIZEVERIFY 1 /* container resize pending */ #define API_ACTION_RESIZED 2 /* container has been resized (dimensions can be found in APIClient->api_Area) */ #define API_ACTION_REFRESH 4 /* container refresh request */ #define API_ACTION_INPUTEVENT 8 /* container input event (pointer to APIInputEvent in api_Data) */ /* Supported api_Error values (set by client) */ #define API_ERROR_OK 0 /* notify successfully processed */ #define API_ERROR_FAIL 1 /* processing of notify failed */ #define API_ERROR_UNKNOWN 2 /* unknown api_Code/api_Class detected */ /* supported api_Refresh types (requested by client) */ #define API_REFRESH_DISPLAY (1L<<1) /* redraw display */ #define API_REFRESH_LINE (1L<<2) /* redraw current line */ #define API_REFRESH_SYNC (1L<<3) /* sync view */ #define API_REFRESH_NOMARKER (1L<<4) /* hide selection */ #define API_REFRESH_MARKER (1L<<8) /* refresh marker */ /* ---------------------------------- APIHost ---------------------------------- Host description (read-only); provided by host */ struct APIHost { ULONG api_APIVersion; /* interface standard supported by host */ ULONG api_Version; /* release code */ ULONG api_Serial; /* serial code of host */ UBYTE *api_Name; /* application name */ UBYTE *api_Info; /* application info */ APTR api_Environment; /* configuration (host-specific) */ APTR api_Reserved; /* reserved for future use */ /* private host data may follow */ }; #define API_INTERFACE_VERSION 3 /* -------------------------------- APIInstance -------------------------------- Instance description (read-only); provided by host instance */ struct APIInstance { struct APIHost *api_Host; /* host application */ UBYTE *api_Name; /* instance name */ APTR api_Environment; /* configuration (host-specific) */ struct Screen *api_Screen; /* screen used by instance */ struct Window *api_Window; /* window used by instance */ struct APIContainer *api_Area; /* reserved container area provided by host instance for client */ APTR api_Reserved; /* reserved for future use */ /* private host data may follow */ }; /* --------------------------------- APIClient --------------------------------- Client description; provided by client */ struct APIClient { ULONG api_APIVersion; /* interface standard supported by client */ ULONG api_Version; /* release code */ UBYTE *api_Name; /* client name */ UBYTE *api_Info; /* client info */ UBYTE **api_Commands; /* command list (NULL-terminated) */ ULONG api_Serial; /* serial code of client */ ULONG api_Classes; /* class request */ struct APIContainer *api_Area; /* client's container request (updated by host) */ APTR api_Reserved; /* reserved for future use */ /* private client data may follow */ }; /* ------------------------------------ APIOrder ------------------------------- Orders are created by clients and attached to APIMessages after a message has been processed to send orders to the host. The contents of the data block and the meaning of the flags - which should describe what is in the data block - are host specific (see developer/include/editor.h for GoldED, definition of APIModifyrequest). The host will return the orders by calling the client's APIFree() function so that the client can free memory allocated for the order. */ struct APIOrder { struct APIOrder *api_Next; /* next order or NULL */ APTR api_Data; /* host specific data (see developer/include/editor.h for GoldED) */ ULONG api_Flags; /* host specific flags (see developer/include/editor.h for GoldED) */ /* client-allocated data may be included here */ }; /* ------------------------------- APIContainer -------------------------------- Container description. Containers are reserved window areas provided by host instances (typically host windows) to clients. */ struct APIContainer { struct APIContainer *api_Next; /* next container (not yet supported) */ struct Window *api_Window; /* window */ struct Screen *api_Screen; /* screen */ struct RastPort api_RPort; /* rastport */ ULONG api_Style; /* container style (see below) */ ULONG api_Align; /* alignment flags (see below) */ UWORD api_Width; /* requested dimensions (width) */ UWORD api_Height; /* requested dimensions (height) */ UWORD api_Units; /* unit flags (see below) */ struct Rectangle api_Rectangle; /* current dimensions */ ULONG api_Signals; /* client's signals the host should Wait() for */ APTR api_Reserved; /* reserved for future use */ }; /* container style */ #define API_STYLE_NOBORDER 0 /* border style flag */ #define API_STYLE_DEFAULT 1 /* border style flag */ /* container alignment flags */ #define API_ALIGN_TOP 0 #define API_ALIGN_BOTTOM 1 #define API_ALIGN_LEFT 2 #define API_ALIGN_RIGHT 4 /* unit flags */ #define API_UNITS_RELWITDH 0 /* relative size (0-100%) */ #define API_UNITS_RELHEIGHT 1 /* relative size (0-100%) */ #define API_UNITS_PIXELWIDTH 2 /* absolute size [pixel] */ #define API_UNITS_PIXELHEIGHT 4 /* absolute size [pixel] */ #define API_UNITS_FONTWIDTH 8 /* font-relative size [characters] */ #define API_UNITS_FONTHEIGHT 16 /* font-relative size [characters] */ /* ------------------------------- APIInputEvent ------------------------------- Input event description (clients requesting API_CLASS_CONTAINER notifications see all input events of the host instance but should process only input events directly related to the container). */ struct APIInputEvent { ULONG api_IDCMPClass; /* idcmp class */ UWORD api_IDCMPCode; /* idcmp code */ APTR api_IDCMPAddress; /* idcmp address */ UWORD api_IDCMPQualifier; /* idcmp qualifier */ ULONG api_IDCMPSeconds; /* idcmp time stamp */ ULONG api_IDCMPMicros; /* idcmp time stamp */ UWORD api_IDCMPX; /* mouse position (relative to host window) */ UWORD api_IDCMPY; /* mouse position (relative to host window) */ UWORD api_Signals; /* task signals */ }; #endif