/* Copyright 1997 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the toolbox library for writing desktop applications in C. It may be     *
 * used freely in the creation of programs for RISC OS.                     *
 *                                                                          *
 * Copyright  Acorn Computers Ltd, 1994                                    *
 *                                                                          *
 ***************************************************************************/

/*
 * Name        : ToolBox.h
 * Description : SWI veneers to the SWI's provided by the toolbox core module
 */


#ifndef __toolbox_h
#define __toolbox_h

#ifndef __kernel_h
#include "kernel.h"
#endif

#ifndef __wimp_h
#include "wimp.h"
#endif



/****************************************************************************
 * Fundamental types                                                        *
 ****************************************************************************/


typedef int ObjectId;            /* abstract Object Id (as used by client apps)         */
typedef int ComponentId;         /* component Id within an Object (eg gadget in Window) */
typedef int ObjectClass;         /* the abstract class of an Object                     */

#define NULL_ObjectId    (ObjectId)0
#define NULL_ComponentId (ComponentId)-1

#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif

#ifndef NULL
#define NULL 0
#endif



/*-- block filled in by Toolbox on Wimp Poll --*/

typedef struct
{
  ObjectId      ancestor_id;           /* object's "ancestor" */
  ComponentId   ancestor_component;
  ObjectId      parent_id;             /* object's "parent" */
  ComponentId   parent_component;
  ObjectId      self_id;               /* object on which an event occurred */
  ComponentId   self_component;
} IdBlock;


/*-- a MessageTrans file descriptor --*/


typedef struct
{
  int           data [4];
} MessagesFD;


/****************************************************************************
 * Object Templates                                                         *
 ****************************************************************************/


#define MAX_OBJECT_NAME 12

/*-- flags --*/

#define Object_CreateOnLoad      0x00000001
#define Object_ShowOnCreate      0x00000002
#define Object_Shared            0x00000004
#define Object_Ancestor          0x00000008


/*-- template definition ---*/

typedef struct                               /* an object template header (after relocation) */
{
  ObjectClass         object_class;          /* class of the object                          */
  int                 flags;                 /* generic flags (see above)                    */
  int                 version;               /* object class module version                  */
  char                name[MAX_OBJECT_NAME]; /* name given to template for use in
                                                        Toolbox_ObjectCreate                 */
  int                 total_size;            /* size of whole object (inc header)            */
  void                *body;                 /* object body (defined by object class module) */
  int                 body_size;             /* sizeof *body                                 */
} ObjectTemplateHeader;



/****************************************************************************
 * Resource file format                                                      *
 ****************************************************************************/

typedef int StringReference;           /* offset into Object's string table */
typedef int MessageReference;          /* offset into Object's messages table */

/*-- relocations --*/

/*-- directives --*/

#define Relocate_StringReference     1
#define Relocate_MsgReference        2
#define Relocate_SpriteAreaReference 3
#define Relocate_ObjectOffset        4

typedef struct
{
  int             word_to_relocate;
  int             directive;
} Relocation;

typedef struct
{
  int             num_relocations;
  Relocation      relocations[1];
} RelocationTable;


/*-- Resource file header --*/

typedef struct
{
  int             file_id;         /* should be 'RESF' */
  int             version_number;  /* resource file version number * 100, eg 1.32 is 132 */
  int             object_offset;   /* byte offset of first template from start of file */
} ResourceFileHeader;


/*-- Resource file Object template --*/

typedef struct
{
  int                  string_table_offset;
  int                  message_table_offset;
  int                  relocation_table_offset;
  ObjectTemplateHeader hdr;
} ResourceFileObjectTemplateHeader;



/****************************************************************************
 * Toolbox SWIs                                                              *
 ****************************************************************************/


#define Toolbox_SWIChunkBase    0x44ec0

/*-- SWI Numbers --*/

#define Toolbox_CreateObject           (Toolbox_SWIChunkBase + 0)
#define Toolbox_DeleteObject           (Toolbox_SWIChunkBase + 1)
#define Toolbox_ShowObject             (Toolbox_SWIChunkBase + 3)
#define Toolbox_HideObject             (Toolbox_SWIChunkBase + 4)
#define Toolbox_GetObjectState         (Toolbox_SWIChunkBase + 5)
#define Toolbox_ObjectMiscOp           (Toolbox_SWIChunkBase + 6)
#define Toolbox_SetClientHandle        (Toolbox_SWIChunkBase + 7)
#define Toolbox_GetClientHandle        (Toolbox_SWIChunkBase + 8)
#define Toolbox_GetObjectClass         (Toolbox_SWIChunkBase + 9)
#define Toolbox_GetParent              (Toolbox_SWIChunkBase + 10)
#define Toolbox_GetAncestor            (Toolbox_SWIChunkBase + 11)
#define Toolbox_GetTemplateName        (Toolbox_SWIChunkBase + 12)
#define Toolbox_RaiseToolboxEvent      (Toolbox_SWIChunkBase + 13)
#define Toolbox_GetSysInfo             (Toolbox_SWIChunkBase + 14)
#define Toolbox_Initialise             (Toolbox_SWIChunkBase + 15)
#define Toolbox_LoadResources          (Toolbox_SWIChunkBase + 16)

#define Toolbox_DeRegisterObjectModule (Toolbox_SWIChunkBase + 58)
#define Toolbox_TemplateLookUp         (Toolbox_SWIChunkBase + 59)
#define Toolbox_GetInternalHandle      (Toolbox_SWIChunkBase + 60)
#define Toolbox_RegisterObjectModule   (Toolbox_SWIChunkBase + 61)
#define Toolbox_RegisterPreFilter      (Toolbox_SWIChunkBase + 62)
#define Toolbox_RegisterPostFilter     (Toolbox_SWIChunkBase + 63)


/*-- flags for Toolbox_GetSysInfo --*/

#define Toolbox_GetSysInfo_TaskName                      0
#define Toolbox_GetSysInfo_MessagesFD                    1
#define Toolbox_GetSysInfo_DirName                       2
#define Toolbox_GetSysInfo_TaskHandle                    3
#define Toolbox_GetSysInfo_SpriteArea                    4


/*-- flags for Toolbox_CreateObject --*/

#define Toolbox_CreateObject_InCore             0x00000001


/*-- flags for Toolbox_DeleteObject --*/

#define Toolbox_DeleteObject_DontRecurse        0x00000001


/*-- flags for Toolbox_CopyObject --*/

#define Toolbox_CopyObject_DontRecurse          0x00000001


/*-- return values for Toolbox_GetObjectState --*/

#define Toolbox_GetObjectState_Showing         0x00000001


/*-- flags for Toolbox_RegisterPreFilter --*/

#define Toolbox_RegisterPreFilter_Remove        0x00000001


/*-- flags and types for Toolbox_RegisterPostFilter --*/

#define Toolbox_RegisterPostFilter_Remove       0x00000001
#define Toolbox_RegisterPostFilter_WimpEvent             1
#define Toolbox_RegisterPostFilter_WimpMessage           2
#define Toolbox_RegisterPostFilter_ToolboxEvent          3

#define Toolbox_RegisterPostFilter_AnyClass            (-1)
#define Toolbox_RegisterPostFilter_WimpObject            0

typedef struct
{
  int             code;                       /* pair of event code and object class */
  ObjectClass     object_class;               /* used in Toolbox_RegisterPostFilter  */
} EventInterest;



/*-- flags and types for Toolbox_ShowObject --*/

#define Toolbox_ShowObject_AsMenu               0x00000001
#define Toolbox_ShowObject_AsSubMenu            0x00000002
#define Toolbox_ShowObject_AsSubWindow		0x00000004

#define Toolbox_ShowObject_Default                       0
#define Toolbox_ShowObject_FullSpec                      1
#define Toolbox_ShowObject_TopLeft                       2
#define Toolbox_ShowObject_Centre                        3
#define Toolbox_ShowObject_AtPointer                     4

typedef struct
{
  int           x;
  int           y;
} TopLeft;



/****************************************************************************
 * Toolbox Events                                                            *
 ****************************************************************************/

/*-- event codes --*/

#define Toolbox_Error             (Toolbox_SWIChunkBase + 0)
#define Toolbox_ObjectAutoCreated (Toolbox_SWIChunkBase + 1)
#define Toolbox_ObjectDeleted     (Toolbox_SWIChunkBase + 2)


typedef struct
{
  unsigned int     size;
  int              reference_number;
  unsigned int     event_code;
  unsigned int     flags;
} ToolboxEventHeader;


typedef struct
{
  ToolboxEventHeader hdr;
  union
  {
    char          bytes [212];
    int           words [53];
  } data;
} ToolboxEvent;    /* generic structure of a Toolbox Event block */


typedef struct
{
  ObjectId        self;
  ComponentId     component;
  ToolboxEvent    event;
} ToolboxMsgEvent;


/*-- a Toolbox error event --*/

typedef struct
{
  ToolboxEventHeader hdr;
  int                errnum;
  char               errmess [256-20-sizeof(ToolboxEventHeader)-sizeof(ObjectId)-sizeof(ComponentId)-sizeof(int)];
} ToolboxErrorEvent;


/*-- object has been auto-created event --*/

typedef struct
{
  ToolboxEventHeader hdr;
  char               template_name [256-20-sizeof(ToolboxEventHeader)-sizeof(ObjectId)-sizeof(ComponentId)];
} ToolboxObjectAutoCreatedEvent;


/*-- object has been deleted --*/

/*-- flags and types for ToolboxObjectDelected event --*/

#define ToolboxObjectDeleted_ExtendedInformation 0x00000001

typedef struct
{
  ToolboxEventHeader hdr;
  ObjectClass        class_id;
  void               *client_handle;
} ToolboxObjectDeletedEvent;




/****************************************************************************
 * The following functions provide veneers to the SWIs that are             *
 * associated with this particular module.  Please read the User Interface  *
 * toolbox manual for more detailed information on their functionality.     *
 ****************************************************************************/


#ifdef __cplusplus
   extern "C" {
#endif

/*
 *   Name        : toolbox_get_sys_info
 *   Description : returns information about a task
 *   In          : unsigned int reason_code
 *   In/Out      : _kernel_swi_regs *regs;
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_get_sys_info ( unsigned int reason_code,
                                               _kernel_swi_regs *regs
                                              );


/*
 *  Name        : toolbox_get_template_name
 *  Description : gets the name of the specified object
 *  In          : unsigned int    flags
 *                ObjectId        id
 *                char           *buffer     - pointer to buffer to hold name
 *                int             buff_size  - size of buffer
 *  Out         : int            *nbytes     - true size of buffer
 *  Returns     : pointer to error block
 *  Other Info  : If buffer = NULL then nbytes will contain the required size
 *                for the buffer, else nbytes will be updated with the number bytes
 *                written to the buffer
 */

extern _kernel_oserror *toolbox_get_template_name ( unsigned int flags,
                                                    ObjectId id,
                                                    char *buffer,
                                                    int  buff_size,
                                                    int *nbytes
                                                  );


/*
 *   Name        : toolbox_create_object
 *   Description : creates a named object
 *   In          : unsigned int flags
 *                 const void  *name_or_template - pointer to template name or
 *                                                 description block
 *   Out         : ObjectId    *id               - destination for object id upon creation
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_create_object ( unsigned int flags,
                                                const void *name_or_template,
                                                ObjectId *id
                                              );


/*
 *   Name        : toolbox_delete_object
 *   Description : deletes a specified object
 *   In          : unsigned int flags
 *                 ObjectId     id        - id of object to delete
 *   Out         : None
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_delete_object ( unsigned int flags,
                                                ObjectId id
                                              );


/*
 *   Name        : toolbox_template_lookup
 *   Description : looks up an ObjectTemplateHeader from a template name suitable for
 *                 use with Window_ExtractGadgetInfo or Toolbox_CreateObject
 *   In          : unsigned int flags
 *                 const char *name           - the name of the template
 *   Out         : const ObjectTemplateHeader **hdr - a pointer to an object template header
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_template_lookup (unsigned int flags,
                                                 const char *name,
                                                 const ObjectTemplateHeader **hdr
                                                );


/*
 *   Name        : toolbox_show_object
 *   Description : shows the specified object
 *   In          : unsigned int     flags
 *                 ObjectId         id
 *                 int              show_type        - show type reason code
 *                 const void      *type             - contents dependent on reason code
 *                                                     (can be null)
 *                 ObjectId         parent           - parent object
 *                 ComponentId      parent_component - parent component
 *   Out         : None
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_show_object ( unsigned int flags,
                                              ObjectId id,
                                              int show_type,
                                              const void *type,
                                              ObjectId parent,
                                              ComponentId parent_component
                                            );




/*
 *   Name        : toolbox_hide_object
 *   Description : hides a specified object
 *   In          : unsigned int flags
 *                 ObjectId     id      - id of object to hide
 *   Out         : None
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_hide_object ( unsigned int flags,
                                              ObjectId id
                                            );


/*
 *   Name        : toolbox_get_object_state
 *   Description : gets information for a specified object
 *   In          : unsigned int  flags
 *                 ObjectId      id
 *   Out         : unsigned int *state
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_get_object_state ( unsigned int flags,
                                                   ObjectId id,
                                                   unsigned int *state
                                                 );



/*
 *   Name        : toolbox_set_client_handle
 *   Description : sets a client handle for the specified object
 *   In          : unsigned int  flags
 *                 ObjectId      id
 *                 void         *client_handle - handle to give object
 *   Out         : None
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_set_client_handle ( unsigned int flags,
                                                    ObjectId id,
                                                    void *client_handle
                                                  );


/*
 *   Name        : toolbox_get_client_handle
 *   Description : gets a client handle from the specified object
 *   In          : unsigned int  flags
 *                 ObjectId      id
 *   Out         : void          **client_handle - destination for client handle
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_get_client_handle ( unsigned int flags,
                                                    ObjectId id,
                                                    void **client_handle
                                                  );

/*
 *   Name        : toolbox_get_object_class
 *   Description : gets the class for the specified object
 *   In          : unsigned int flags
 *                 ObjectId     id
 *   Out         : ObjectClass *object_class - destination for the objects class
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_get_object_class ( unsigned int flags,
                                                   ObjectId id,
                                                   ObjectClass *object_class
                                                 );


/*
 *   Name        : toolbox_get_parent
 *   Description : gets the parent object and component id for the object
 *   In          : unsigned int  flags
 *                 ObjectId      id
 *   Out         : ObjectId     *parent           - destination for parent object id
 *                 ComponentId  *parent_component - destination for parent component id
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_get_parent ( unsigned int flags,
                                             ObjectId id,
                                             ObjectId *parent,
                                             ComponentId *parent_component
                                           );



/*
 *   Name        : toolbox_get_ancestor
 *   Description : gets the ancestor object and component id for the object
 *   In          : unsigned int flags
 *                 ObjectId     id
 *   Out         : ObjectId    *ancestor           - destination for ancestor object id
 *                 ComponentId *ancestor_component - destination for ancestor component id
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_get_ancestor ( unsigned int flags,
                                               ObjectId id,
                                               ObjectId *ancestor,
                                               ComponentId *ancestor_component
                                             );


/*
 *   Name        : toolbox_raise_toolbox_event
 *   Description : raises a specific event for a specific object/component
 *   In          : unsigned int        flags
 *                 ObjectId            id
 *                 ComponentId         component - optional
 *                 const ToolboxEvent *event     - toolbox event data
 *   Out         : None
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_raise_toolbox_event ( unsigned int flags,
                                                      ObjectId id,
                                                      ComponentId component,
                                                      const ToolboxEvent *event
                                                    );



/*
 *   Name        : toolbox_initialise
 *   Description : called by client when initialising the application
 *   In          : unsigned int flags
 *                 int          wimp_version            - wimp version * 100 (must be >= 310)
 *                 const int   *wimp_messages           - list of wimp messages that client wishes
 *                                                        to receive
 *                 const int   *toolbox_events          - list of toolbox events that the task
 *                                                        wishes to receive
 *                 const char     *directory            - name of dir holding resources
 *                 MessagesFD     *mfd                  - destination for messages file descriptor
 *                 IdBlock        *idb                  - pointer to id block
 *  Out          : int            *current_wimp_version - destination pointer for current wimp
 *                                                        version
 *                 int            *task                 - destination pointer for task handle of
 *                                                        this task
 *                 void           **sprite_area         - destination pointer for sprite area
 *   Returns     : pointer to error block
 *   Other Info  : if wimp_messages  = NULL then all wimp messages will be delivered
 *                 if toolbox_events = NULL then all toolbox events will be delivered
 */

extern _kernel_oserror *toolbox_initialise ( unsigned int flags,
                                             int wimp_version,
                                             const int *wimp_messages,
                                             const int *toolbox_events,
                                             const char *directory,
                                             MessagesFD *mfd,
                                             IdBlock *idb,
                                             int *current_wimp_version,
                                             int *task,
                                             void **sprite_area
                                           );




/*
 *   Name        : toolbox_load_resources
 *   Description : loads the resources file
 *   In          : unsigned int  flags
 *                 const char   *resources   - name of resources file
 *   Out         : None
 *   Returns     : pointer to error block
 */

extern _kernel_oserror *toolbox_load_resources ( unsigned int flags,
                                                 const char *resources
                                               );



#ifdef __cplusplus
   }
#endif

#endif

