Summary of CWimp release to ISVs, version 0.1
========================================

The information here is lifted from the header ('h.') files. It lists the
functions in each module; some additional notes have been added where
this may be useful.

BBC: BBC-style graphics and mouse/keyboard control
----------------------------------------------
* Symbolic codes for VDU commands and plot commands
* Symbolic codes for VDU and mode variables

bbc_vdu
  Single character VDU call.
bbc_vduw
  Double character VDU call.
bbc_vduq
  Multiple character VDU call.
bbc_stringprint
  Print a null-terminated string indicated on the screen.
bbc_cls
  Clear text window.
bbc_colour
  Set text colour.
bbc_pos
  Return the X coordinate of the text cursor.
bbc_vpos
  Return Y coordinate of text cursor.
bbc_tab
  Positon text cursor.
bbc_plot
  Perform an operating system plot operation.
bbc_mode
  Set screen mode.
bbc_move
  Move graphics cursor to an absolute position.
bbc_moveby
  Move the graphics cursor to a position relative to its current
  position.
bbc_draw
  Draw a line to absolute coordinates.
bbc_drawby
  Draw a line to coordinates specified relative to current graphic
  cursor.
bbc_rectangle
  Plot a rectangle.
bbc_rectanglefill
  Plot a solid rectangle.
bbc_circle
  Draw a circle.
bbc_circlefill
  Draw a solid circle.
bbc_origin
  Move the graphics origin to absolute coordinates.
bbc_gwindow
  Set up graphics window.
bbc_clg
  Clear graphic window.
bbc_fill
  Flood-fill an area.
bbc_gcol
  Set graphics colour.
bbc_tint
  Set grey level of a colour.
bbc_palette
  Physical to logical colour definition.
bbc_point
  Find the logical colour of a pixel at indicated coordinates.
bbc_vduvar
  Read a single VDU or mode variable value, for the current screen
  mode.
bbc_vduvars
  Read several VDU or mode variable values.
bbc_modevar
  Read a single mode variable, for the a screen mode.
bbc_get
  Return a character code from the input stream.
bbc_cursor
  Alter cursor appearance.
bbc_adval
  Read data from analogue ports or gives buffer data.
bbc_getbeat
  Return current beat value.
bbc_getbeats
  Read beat counter cycle length.
bbc_gettempo
  Read rate at which beat counter counts.
bbc_inkey
  Return a character code from an input stream or the keyboard.
bbc_rnd
  Return a random number.
bbc_beats
  Set beat counter cycle length.
bbc_settempo
  Set rate at which beat counter counts.
bbc_sound
  Make or schedule a sound.
bbc_soundoff
  Deactivate sound system.
bbc_soundon
  Activate sound system.
bbc_stereo
  Set stereo position for specified channel.
bbc_voices
  Set number of sound channels.

FLEX: Flexible storage allocator
---------------------------

flex_alloc
  Allocates store.
flex_free
  Frees store.
flex_size
  Find exact number of bytes in store area.
flex_extend
  Increase/decrease size of an area of store.
flex_midextend
  Insert/delete space in the middle of an area of store.
flex_storefree
  Give approximate number of bytes free.
flex_init
  Initialisation.

FONT: Interface to RISC OS font manager
-----------------------------------

font_cacheaddr
  Read font cache metrics.
font_find
  Find a font.
font_lose
  Lose reference to a font.
font_readdef
  Read definition of a font.
font_readinfo
  Read size of a box that would surround any character in the font.
font_strwidth
  Find width of a string.
font_paint
  Paint characters.
font_caret
  Set the colour, size and position of the caret.
font_converttoos
  Converts coords in 1/72000th inch to OS units.
font_converttopoints
  Converts coords in OS units to 1/72000th inch.
font_setfont
  Set the font in which to paint characters.
font_current
  Returns the current state of the font painter's internal variables.
font_future
  Used to find out what the effect of a Font_Paint would have on the
  current font handle and colours.
font_findcaret
  Work out the best place for the caret to go.
font_charbbox
  Find the bounding box of a character.
font_readscalefactor
  Returns the x, y scale factors.
font_setscalefactor
  Sets up the x, y scale factors.
font_list
  List known fonts.
font_setcolour
  Set colour for character painting.
font_setpalette
  Set palette for character painting.
font_readthresholds
  Reads the current threshold values.
font_setthresholds
  Sets up threshold values for a given number of output colours.
font_findcaret
  Returns nearest point where caret can go.
font_stringbbox
  Used to find out how much of the page a string would take up.

OS: General access to low-level RISC OS routines
------------------------------------------

os_swi
  Perform a SWI instruction, with the given registers loaded.
os_swix
  Perform SWI and return errors.
os_swi0
os_swi1
os_swi2
os_swi3
os_swi4
os_swi6
os_swi1r
os_swi2r
os_swi3r
os_swi4r
os_swi6r
  SWIs with various numbers of arguments. R versions return the
  given registers.
os_byte
os_word
os_gbpb
os_file
os_args
os_find
os_cli
  Calls to various general OS routines.
os_read_var_val
  Read value of a system variable

POLL: Wimp polling routines
-----------------------

wimp_poll
  Poll wimp. Used at the heart of many wimp programs.
wimp_save_fp_state_on_poll
  Activates saving of floating point state on calls to wimp_poll and
  wimp_pollidle.
wimp_corrupt_fp_state_on_poll
  Disables saving of floating point state on calls to wimp_poll and
  wimp_pollidle.
wimp_pollidle
  Like wimp_poll, but do not return before a given earliest return time.

SPRITE: Access to RISC OS sprite facilities
------------------------------------

sprite_screensave
  Save the current graphics window as a sprite file, with optional
  palette.
sprite_screenload
  Load a sprite file onto the screen.
sprite_area_initialise
  Initialise an area of memory as a sprite area
sprite_area_readinfo
  Read information from a sprite area control block
sprite_area_reinit
  Reinitialise a sprite area.
sprite_area_load
  Load a sprite file into a sprite area.
sprite_area_merge
  Merge a sprite file with a sprite area.
sprite_area_save
  Save a sprite area as a sprite file.
sprite_getname
  Return the name and length of the n'th sprite in a sprite area.
sprite_get
sprite_get_rp
  Copy a rectangle of screen into a sprite.
sprite_get_given
sprite_get_given_rp
  Copy a rectangle of screen into a sprite, optionally with a palette.
sprite_create
sprite_create_rp
  Create a named sprite.
sprite_select
sprite_select_rp
  Select a sprite for plotting using plot (0xed,x,y).
sprite_delete
  Delete a sprite.
sprite_rename
  Rename a sprite.
sprite_copy
  Copy a sprite as another sprite in the same sprite area.
sprite_put
  Plot a sprite.
sprite_put_given
  Plot a sprite at a given location.
sprite_put_scaled
  Plot a sprite with scaling.
sprite_put_greyscaled
  Plot a sprite using grey scales for colours.
sprite_put_mask
  Plot a sprite mask in the background colour.
sprite_put_mask_given
  Plot a sprite mask at a given location.
sprite_put_mask_scaled
  Plot a sprite mask with scaling.
sprite_put_char_scaled
  Paint a character in the system font, with scaling.
sprite_create_mask
  Create a mask definition for a sprite.
sprite_remove_mask
  Remove the mask definition from a sprite.
sprite_insert_row
  Insert a row into a sprite.
sprite_delete_row
  Delete a row from a sprite.
sprite_insert_column
  Insert a column into a sprite.
sprite_delete_column
  Delete a column from a sprite.
sprite_flip_x
  Flip a sprite about the x axis.
sprite_flip_y
  Flip a sprite about the y axis.
sprite_readsize
  Read the size information for a sprite.
sprite_readpixel
  Read the colour of a pixel in a sprite.
sprite_writepixel
  Write the colour of a pixel in a sprite.
sprite_readmask
  Read the state of a pixel in a sprite mask.
sprite_writemask
  Write the state of a pixel in a sprite mask.

SWI: Access to RISC OS SWIs from C
-------------------------------

* Symbolic codes for SWIs

TRACE: Trace/debug output
-----------------------

tracef
  General trace call.
tracef0
tracef1
tracef2
tracef3
tracef4
  Trace calls with given number of integer arguments.
trace_is_on
  Test if tracing is on.
trace_on
  Turn tracing on.
trace_off
  Turn tracing off.

WERR: Error reporting in wimp programs
-----------------------------------

werr
  Report an error amd wait for response. Can be used to abort
  program.
werr_handler
  Install the handler procedure that werr uses.

WIMP: C interface to RISC OS Wimp routines
-------------------------------------

* Symbolic codes for window and icon flags, event codes, button types,
  etc.
* Also see POLL, WIMPT.

wimp_initialise
  (Re-)Initialise wimp, return wimp version number.
wimp_taskinit
  Initialise a wimp task.
wimp_create_wind
  Define (but not display) window.
wimp_create_icon
  Add icon definition to that of window.
wimp_delete_wind
  Delete a window.
wimp_delete_icon
  Delete an icon.
wimp_open_wind
  Make window appear on screen.
wimp_close_wind
  Remove window from screen.
wimp_redraw_wind
  Draw window outline and icons.
wimp_update_wind
  Return visible portion of window.
wimp_get_rectangle
  Return next rectangle in redraw list.
wimp_get_wind_state
  Read current window state.
wimp_get_wind_info
  Get information about a window.
wimp_set_icon_state
  Set the state of an icon.
wimp_get_icon_info
  Get information about an icon.
wimp_get_point_info
  Get information about the pointer.
wimp_drag_box
  Start the wimp dragging a box.
wimp_force_redraw
  Mark an area of the screen as invalid.
wimp_set_caret_pos
  Set position/size of text caret.
wimp_get_caret_pos
  Get position/size of text caret.
wimp_create_menu
  'Pop up' menu structure.
wimp_decode_menu
  Decode values returned from a menu.
wimp_which_icon
  Determine which of a group of icons was selected.
wimp_set_extent
  Sets the work area extent of a window.
wimp_set_point_shape
  Set pointer shape on screen.
wimp_open_template
  Open a template file.
wimp_close_template
  Close a template file.
wimp_load_template
  Load a window template from open file.
wimp_processkey
  Hand back to the wimp a key that you do not understand.
wimp_closedown
wimp_taskclose
  Close down the wimp/a task in the wimp.
wimp_taskclose
  Calls closedown in the multi-tasking form.
wimp_starttask
  Start a new wimp task, with a given CLI command.
wimp_getwindowoutline
  Find the outline of a window.
wimp_ploticon
  Plot an icon.
wimp_setmode
  Set the screen mode.
wimp_readpalette
  Read the current palette.
wimp_setpalette
  Set the palette.
wimp_setcolour
  Set to a colour defined by the wimp.
wimp_spriteop
  Do a sprite operation.
wimp_spriteop_full
  Do a sprite operation, allowing full information to be passed.
wimp_baseofsprites
  Find base of sprite area.
wimp_blockcopy
  Copy the source box to the given destination.
wimp_reporterror
  Produces an error window.
wimp_sendmessage
  Send a message to other tasks.
wimp_sendwmessage
  Send a message to the owner of a specific window/icon.
wimp_create_submenu
  Create submenu.
wimp_slotsize
  Read/set the memory allocated to the task.
wimp_transferblock
  Transfer memory between domains.
wimp_setfontcolours
  Set font manager colours.

WIMPT: Low-level wimp functionality
-------------------------------

wimpt_poll
  Poll the wimp; identical to wimp_poll, but with the extra facilities.
  Use wimp_poll unless there is a genuine need for this.
wimpt_fake_event
  Fake an event.
wimpt_last_event
  Find last event yielded by wimpt_poll.
wimpt_noerr
  Check for existing errors and report new ones.
wimpt_complain
  Report an error and return.
wimpt_setmode
  Set screen mode. Not recommended in the multi-tasking world.
wimpt_checkmode
  Test if the mode has changed; also sets variables for wimpt_mode,
  wimpt_dx, wimpt_dy and wimpt_bpp.
wimpt_mode
  Read screen mode.
wimpt_dx
  Read OS x units per screen pixel.
wimpt_dy
  Read OS y units per screen pixel.
wimpt_bpp
  Read bits per screen pixel.
wimpt_init
  Sets up the screen and initialises a task. Program closedown code
  is set up to tidy things up on exit.
wimpt_programname
  Find the name of a program.
wimpt_reporterror
  Report an error, using the program name to identify it.
wimpt_task
  Gives handle for the task.
wimpt_forceredraw
  Invalidate the whole screen.
(Also: int wimpt_last_event_was_a_key. Replaced by wimpt_last_event.)
