/*
 * wimp.h
 *
 * Interface to WIMP SWIs
 *
 * © 1994-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __wimp_h
#define __wimp_h

#ifndef __wimpstruct_h
  #include "wimpstruct.h"
#endif

/*----- Notes -------------------------------------------------------------*
 *
 * This file defines functions callable from C programs to allow access to
 * the WIMP at the SWI level.
 *
 * Each function maps directly to a single WIMP SWI, and performs little
 * or no additional processing.  For full information about each one,
 * you should consult the RISC OS 3 Programmer's Reference Manual.
 * Little or no documentation is provided for each function.
 *
 * Two SWIs are not supported currently:
 *
 * Wimp_ClaimFreeMemory -- since the memory is only usable in SVC mode,
 *   it doesn't seem to be very useful to be able to claim it from C.
 *
 * Wimp_SetColourMapping -- this call is only useful for specialised 
 *   applications, and a veneer defined here isn't really appropriate.
 */

/*----- Polling the WIMP --------------------------------------------------*
 *
 * The two functions wimp_poll and wimp_pollidle map to SWIs Wimp_Poll and
 * Wimp_PollIdle respectively.  The other two functions control the saving
 * or not of the floating point status -- the default is to save this
 * status (although this is not performed if the FPEmulator is not present).
 *
 * Correct handling of the DLL Application Handle is also performed.
 */

os_error *wimp_poll(wimp_emask mask,wimp_eventstr *e);
os_error *wimp_pollidle(wimp_emask mask,wimp_eventstr *e,int time);

void wimp_corrupt_fp_state_on_poll(void);
void wimp_save_fp_state_on_poll(void);

/*----- Initialising the WIMP ---------------------------------------------*
 *
 * wimp_initialise should only be used if you don't want a multitasking
 * application -- not very useful, really.  wimp_taskinit will perform all
 * the initialisation a full multitasking application requires.  If you
 * initialise with a version number of 300 or higher, the optional messages
 * argument should be filled in with a pointer to an array of message
 * numbers.
 */

os_error *wimp_initialise(int *version);
os_error *wimp_taskinit(char *name,
                        int *version,
                        wimp_t *taskhandle,...
                     /* int *messages */);

/*----- Closing down the WIMP ---------------------------------------------*/

os_error *wimp_closedown(void);
os_error *wimp_taskclose(wimp_t taskhandle);

/*----- Creating and deleting windows and icons ---------------------------*/

os_error *wimp_create_wind(wimp_wind *w,wimp_w *handle);
os_error *wimp_delete_wind(wimp_w w);
os_error *wimp_create_icon(wimp_icreate *i,wimp_i *handle);
os_error *wimp_delete_icon(wimp_w w,wimp_i i);

/*----- Getting and changing window and icon states -----------------------*/

os_error *wimp_open_wind(wimp_openstr *o);
os_error *wimp_close_wind(wimp_w w);
os_error *wimp_set_extent(wimp_redrawstr *r);
os_error *wimp_get_wind_state(wimp_w w,wimp_wstate *s);
os_error *wimp_get_wind_info(wimp_winfo *w);
os_error *wimp_get_icon_info(wimp_w w,wimp_i i,wimp_icon *icn);
os_error *wimp_set_icon_state(wimp_w w,wimp_i i,int eorMask,int bicMask);
os_error *wimp_which_icon(wimp_which_block *w,wimp_i *icons);
os_error *wimp_getwindowoutline(wimp_redrawstr *r);

/*----- Redrawing windows -------------------------------------------------*/

os_error *wimp_redraw_wind(wimp_redrawstr *r,BOOL *more);
os_error *wimp_update_wind(wimp_redrawstr *r,BOOL *more);
os_error *wimp_get_rectangle(wimp_redrawstr *r,BOOL *more);
os_error *wimp_force_redraw(wimp_redrawstr *r);
os_error *wimp_ploticon(wimp_icon *i);
os_error *wimp_blockcopy(wimp_w w,wimp_box *box,int x,int y);

/*----- Menu handling -----------------------------------------------------*/

os_error *wimp_create_menu(wimp_menustr *m,int x,int y);
os_error *wimp_create_submenu(wimp_menustr *m,int x,int y);
os_error *wimp_decode_menu(wimp_menustr *m,void *hits,void *stringbuffer);
os_error *wimp_getmenustate(int action,
                            int *hits,...
                         /* wimp_w w, */
                         /* wimp_i i */);

/*----- Colour handling ---------------------------------------------------*/

os_error *wimp_setcolour(int colour);
os_error *wimp_textcolour(int colour);
os_error *wimp_setfontcolours(int background,int foreground);
os_error *wimp_setpalette(wimp_palettestr *pal);
os_error *wimp_readpalette(wimp_palettestr *pal);

/*----- Sprite handling ---------------------------------------------------*/

os_error *wimp_spriteop(int action,char *sprite);
os_error *wimp_spriteop_full(os_regset r);
void *wimp_baseofsprites(void);
os_error *wimp_readpixtrans(sprite_area *sa,
                            sprite_id *sid,
                            sprite_factors *zoomage,
                            sprite_pixtrans *pixtrans);

/*----- Message handling --------------------------------------------------*/

os_error *wimp_sendmessage(wimp_etype event,wimp_msgstr *m,wimp_t dest);
os_error *wimp_sendwmessage(wimp_etype event,
                            wimp_msgstr *m,
                            wimp_w w,
                            wimp_i i);
os_error *wimp_addmessages(wimp_msgaction *messages);
os_error *wimp_removemessages(wimp_msgaction *messages);

/*----- Pointer handling --------------------------------------------------*/

os_error *wimp_get_point_info(wimp_mousestr *m);
os_error *wimp_set_point_shape(wimp_pshapestr *shapeinfo);

/*----- Caret and key handling --------------------------------------------*
 *
 * Warning: Don't pass STEEL extended keyset keys on with wimp_processkey!
 *          Only use standard WIMP key mapping codes.
 */

os_error *wimp_set_caret_pos(wimp_caretstr *c);
os_error *wimp_get_caret_pos(wimp_caretstr *c);
os_error *wimp_processkey(int key);

/*----- Handing template files --------------------------------------------*/

os_error *wimp_open_template(char *filename);
os_error *wimp_close_template(void);
os_error *wimp_load_template(wimp_template *loadinfo);

/*----- Miscellaneous calls -----------------------------------------------*
 *
 * Warning: Use _dll_starttask instead of wimp_starttask if you are using
 *          a dynamically linked STEEL.
 */

os_error *wimp_drag_box(wimp_dragstr *d);
os_error *wimp_starttask(char *command);
os_error *wimp_reporterror(os_error *error,wimp_errflags how,char *appname);
os_error *wimp_setmode(int newmode);
os_error *wimp_slotsize(int *current,int *next,int *free);
os_error *wimp_commandwindow(wimp_commandwind *dowhat);
os_error *wimp_transferblock(wimp_t sourceTask,
                             char *sourceBuffer,
                             wimp_t destinationTask,
                             char *destinationBuffer,
                             int size);
os_error *wimp_readsysinfo(wimp_sysinfo info,
                           int *r0_out,...
                        /* int *r1_out */);

/*----- The end -----------------------------------------------------------*/

#endif