#ifndef APILIB_H #define APILIB_H /* ** $Filename: developer/api/include/apilib.h ** $Release: 5.1.6 ** ** API definitions; this file does not include any GoldED-specific ** code (see developer/include/editor.h for GoldED-specific code). ** ** (C) Copyright 1999 Dietmar Eilert ** All Rights Reserved */ #ifndef EXEC_TYPES_H #include #endif #ifndef EXEC_LISTS_H #include #endif #ifndef EXEC_LIBRARIES_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 */ }; #define API_INTERFACE_VERSION 5 /* -------------------------------- 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 and possibly set api_State to API_STATE_CONSUMED (if the message has been processed and should not be passed to other clients). */ 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; /* client-related data */ /* 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 state values (api_State) */ #define API_STATE_IGNORE 0 /* this message should be ignored */ #define API_STATE_NOTIFY 1 /* this message should be processed */ #define API_STATE_CONSUMED 2 /* message has been processed and consumed (not to be processed by other clients) */ /* api action classes the client listens to (api_Class) */ #define API_CLASS_SCREEN (1L<<1) /* screen handling */ #define API_CLASS_KEY (1L<<2) /* keyboard events */ #define API_CLASS_COMMAND (1L<<3) /* command execution */ #define API_CLASS_SYSTEM (1L<<6) /* standard events */ #define API_CLASS_IO (1L<<7) /* input and output */ #define API_CLASS_CONTAINER (1L<<8) /* container events */ #define API_CLASS_WORKSPACE (1L<<9) /* workspace events */ /* Supported qualifiers for API_CLASS_KEY events received by client (api_Action) */ #define API_ACTION_VANILLAKEY 1 /* request to process a key (key code in api_Data) */ #define API_ACTION_RAWKEY 2 /* request to process a key (key code in api_Data) */ /* Supported qualifiers for API_CLASS_SCREEN events received by client */ #define API_ACTION_HIDE 1 /* request to close the output (host is about to close the screen) */ #define API_ACTION_SHOW 2 /* request to show the output */ /* Supported qualifiers for API_CLASS_COMMAND events received by client (api_Action) */ #define API_ACTION_COMMAND 1 /* request to process a command (command string in api_Command) */ /* Supported qualifiers for API_CLASS_SYSTEM events received by client (api_Action) */ #define API_ACTION_WELCOME 1 /* notification: welcome */ #define API_ACTION_EXIT 2 /* notification: termination pending */ #define API_ACTION_SAVEPREFS 4 /* request to save preferences */ #define API_ACTION_SIGNAL 8 /* request to process signal(s) (signal mask in api_Data) */ /* Supported qualifiers for API_CLASS_IO events received by client (api_Action) */ #define API_ACTION_SAVE 1 /* notification: save operation pending (pointer to file name in api_Data) */ #define API_ACTION_CREATED 2 /* notification: a file has been saved (pointer to file name in api_Data) */ #define API_ACTION_READ 4 /* notification: a file has been loaded (pointer to file name in api_Data) */ #define API_ACTION_MODIFIED 8 /* notification: the document status has changed (status in api_Data: 0=unmodified, other values: modified) */ /* Supported qualifiers for API_CLASS_CONTAINER events received by client (api_Action) */ #define API_ACTION_DETACH 1 /* request to detach interface */ #define API_ACTION_ATTACH 2 /* request to attach interface */ #define API_ACTION_PAINT 4 /* request to paint the interface */ #define API_ACTION_INPUTEVENT 8 /* request to process an input event (pointer to APIInputEvent in api_Data) */ #define API_ACTION_REFRESH 16 /* request to refresh the interface (see intuition.doc/BeginRefresh() for restrictions) */ /* Supported qualifiers for API_CLASS_WORKSPACE events received by client (api_Action) */ #define API_ACTION_OPEN 1 /* notification: a document has been opened (pointer to host-specific document context in api_Data; see api_Environment) */ #define API_ACTION_CLOSE 2 /* notification: a document has been closed (pointer to host-specific document context in api_Data; see api_Environment) */ #define API_ACTION_NAME 4 /* notification: a document has been renamed (pointer to host-specific document context in api_Data; see api_Environment) */ #define API_ACTION_FREEZE 8 /* notification: a document has been frozen (pointer to host-specific document context in api_Data; see api_Environment) */ #define API_ACTION_UNFREEZE 16 /* notification: a document has been unfrozen (pointer to host-specific document context in api_Data; see api_Environment) */ /* api_Error return codes (to be set by client) */ #define API_ERROR_OK 0 /* message successfully processed */ #define API_ERROR_FAIL 1 /* processing failed */ #define API_ERROR_UNKNOWN 2 /* unsupported api_Class/api_Action packet */ /* api_Refresh values (to be requested by client) */ #define API_REFRESH_DISPLAY (1L<<1) /* redraw entire 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 the selection */ #define API_REFRESH_MARKER (1L<<8) /* refresh the selection */ /* ---------------------------------- APIHost ---------------------------------- Host description (read-only); provided by host. api_Environment is a pointer to a host-specific "document context" (see editor.h for golded). */ 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; /* host-specific document context */ UBYTE *api_Rexx; /* rexx port */ APTR api_Reserved; /* reserved */ /* may be extended in the future */ }; /* -------------------------------- APIInstance -------------------------------- Environment description (read-only); provided by the host instance. Please note that all fields (including api_Window->RPort) are read-only. */ struct APIInstance { struct APIHost *api_Host; /* host application */ UBYTE *api_Name; /* instance name (typically the document name) */ APTR api_Environment; /* configuration (host-specific; see golded:developer/include/golded.h) */ struct Screen *api_Screen; /* screen used by instance or NULL */ struct Window *api_Window; /* window used by instance or NULL */ struct APIContainer *api_Container; /* container area or NULL */ struct TextAttr *api_TextAttr; /* recommended font */ ULONG api_Reserved; /* reserved */ /* may be extended in the future */ }; /* --------------------------------- APIClient --------------------------------- Client description. This is passed to the host application. Please note that the host may or may not be able to fulfill the area request and that the container dimensions provided by the host may not match your requests (the host will automatically use the dimensions preferred by the user if the plug-in has been used before). The actual container dimensions can be found in the next APIMessage. The host will use the api_Image (recommended size: 16x16) instead of the name to represent the iconified client in the toolbar. Note: Clients must have unique names because the name is used when the host decides to restore previously used dimensions. */ struct APIClient { ULONG api_APIVersion; /* interface standard supported by client */ ULONG api_Version; /* release code */ UBYTE *api_Name; /* unique 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 APIArea *api_Area; /* area request */ ULONG api_Signals; /* signals to wait for */ UBYTE *api_Image; /* image representing iconified client (optional) */ ULONG api_Reserved; /* reserved */ /* private client data may follow */ }; /* ------------------------------------ APIOrder ------------------------------- Orders are created by clients and attached to APIMessages after a message has been processed to send "orders" and "commands" back to the host. The contents of the order's data block and the meaning of the flags (which should describe what is in the data block) are host specific. A few standard order types are however supported by all hosts; defines for these order types can be found below. The host will process the order and then call the client's APIFree() function so that the client can free memory and other resources allocated for the order. */ struct APIOrder { struct APIOrder *api_Next; /* next order or NULL */ APTR api_Data; /* host-specific (see developer/include/editor.h for GoldED) */ ULONG api_Flags; /* host-specific (see developer/include/editor.h for GoldED) */ /* private client data may follow */ }; /* standard values for api_Flags supported by all hosts */ #define API_ORDER_ATTACH (2L<<24) /* api_Data contains the gadget list */ #define API_ORDER_DETACH (3L<<24) /* api_Data contains the gadget list */ #define API_ORDER_DTATTACH (4L<<24) /* api_Data contains the datatype list */ #define API_ORDER_DTDETACH (5L<<24) /* api_Data contains the datatype list */ /* ---------------------------------- APIArea ---------------------------------- Area request. The host application will create a new container for each area request (if possible). A container is a reserved rendering space provided by a host instance (typically a host window). You can set the initial width or the initial height. Only one of these values will be used because containers are always aligned with window borders so that either size or height depend on the actual window dimensions. Dimensions requested by the client may or may not be respected by the host application: The host program usually overrides the alignment and dimension values with the values preferred by the user if the plug-in has been used before. The actual dimensions can be read from APIMessage->APIInstance->APIContainer in subsequent APIMessage messages. */ struct APIArea { UWORD api_Width; /* initial size request (width) */ UWORD api_Height; /* initial size request (height) */ UWORD api_UnitsX; /* units used in initial size request (see below) */ UWORD api_UnitsY; /* units used in initial size request (see below) */ UWORD api_Alignment; /* alignment flags (see below) */ UWORD api_Style; /* container style (see below) */ ULONG api_IDCMP; /* IDCMP mask (requested IDCMP events) */ ULONG api_Reserved[16]; /* reserved for future use */ }; /* special size value (api_Width, api_Height) */ #define API_SIZE_UNDEFINED 0 /* size undefined (host will use the host-specific default size) */ /* unit flags (api_UnitsX, apiUnitsY) determine the meaning of the api_Width/api_Height */ #define API_UNITS_PIXEL 0 /* absolute size (pixel) */ #define API_UNITS_FONT 1 /* absolute size (characters) */ #define API_UNITS_PERCENT 2 /* relative size (0-100%) */ /* container alignment flags (api_Alignment) */ #define API_ALIGN_TOP 0 #define API_ALIGN_BOTTOM 1 #define API_ALIGN_LEFT 2 #define API_ALIGN_RIGHT 3 /* container styles (api_Style) */ #define API_STYLE_STANDARD 0 #define API_STYLE_BORDERLESS (1L<<1) #define API_STYLE_NODRAGBAR (1L<<2) #define API_STYLE_NOSIZEBAR (1L<<3) /* ------------------------------- APIContainer -------------------------------- Container description (provided by the host). This structure describes the actual dimensions of the container provided by the host application. All values are read-only. Possible values for api_Alignment and api_Style are similar to those defined for APIAreaRequest (see above). Note that clients should use api_RPort for rendering and may not use the window's rastport (they may specifically not set pens, fonts, patterns or draw modes for the window's RastPort). */ struct APIContainer { struct Rectangle *api_Dimensions; /* dimensions of rendering area or NULL if fully obscured */ struct Rectangle *api_Clipping; /* dimensions of clipping area or NULL if fully obscured */ UWORD api_Alignment; /* alignment flags */ UWORD api_Style; /* container style */ struct RastPort *api_RPort; /* local copy of window's rastport */ struct DrawInfo *api_DrawInfo; /* pens */ UWORD api_Namespace; /* offset for gadget IDs (each client may have 255 gadgets) */ APTR api_VisualInfo; /* visual info of host screen */ struct TextAttr *api_TextAttr; /* recommended font */ ULONG api_IDCMP; /* IDCMP signal request */ APTR api_Reserved; /* reserved */ /* may be extended in the future */ }; /* ------------------------------- APIInputEvent ------------------------------- Input event description (provided by the host, read-only). Clients listening to the API_CLASS_CONTAINER class see all input events of the host instance (e.g. intuiticks and mouse clicks) but should process and consume only input events directly related to the container. */ struct APIInputEvent { struct Window *api_IDCMPWindow; /* idcmp window */ 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) */ /* may be extended in the future */ }; #endif