Documentation from main.h

ROV

Introduction

[top]

ROV - Easy applications from C

Copyright - © Jason Tribbeck / 7th ARM 1994-2001

Contributing authors - Jason Tribbeck

File - main.h

Type - core

Description

The main core system, as its name suggests, is the main system. It handles standard memory allocation, WIMP polling, event routing, memory transfers and other key functions.

The memory allocation is done via a similar system to the malloc-style calls, renamed rmalloc, rfree and rcalloc (note there is no rrealloc). All ROV functions use these instead of the standard malloc-style calls, as the memory pool can be extended from the WIMP, and also freed back to the WIMP if possible.

Other core systems and subsystems interface with the main core's event routing, so this really has to be used with ROV functions.

BOOL (definition)

[top]

Definition of a BOOL.

#define BOOL int

TRUE (definition)

[top]

Definition of TRUE.

#define TRUE (1)

FALSE (definition)

[top]

Definition of FALSE.

#define FALSE (0)

canvas (type definition)

[top]

Definition of a canvas.

Note - It is cast as an integer pointer, because certain functions need to have access to the information contained within. Applications should not do this (this may be enforced at a later date).

typedef int *canvas;

icon (type definition)

[top]

Definition of an icon.

typedef void *icon;

menu (type definition)

[top]

Definition of a menu.

typedef void *menu;

date_str (type definition)

[top]

Structure of a date string.

typedef struct {
  char d[5];
} date_str;

message_block (type definition)

[top]

Structure of a WIMP message block.

Fields:

 - int size - the size of the WIMP message.
 - int sender - the task handle of the sender.
 - int my_ref - the application's reference.
 - int your_ref - the sender's reference.
 - int action - the message action.
 - char[232] data.chars - the information expressed as a character array.
 - int[58] data.words - the information expressed as an integer array.
 - int data.xfer.w - the WIMP window handle for a transfer.
 - int data.xfer.i - the WIMP icon handle for a transfer.
 - int data.xfer.x - the (screen) x coordinate for a transfer.
 - int data.xfer.y - the (screen) y coordinate for a transfer.
 - int data.xfer.size - the file size for a transfer.
 - int data.xfer.type - the file type for a transfer.
 - char[212] data.xfer.name - the file name for a transfer.

Note - This is a bit more limited that RISC_OSLib's WIMP message block, but it does for now. If extensions are required, then do not change the overall structure of this - extend to the data union.

typedef struct {
  int size;
  int sender;
  int my_ref;
  int your_ref;
  int action;
  union {
    char chars[232];
    int	words[58];
    struct {
      int w;
      int i;
      int x;
      int y;
      int size;
      int type;
      char name[212];
    } xfer;
  } data;
} message_block;

main_mousestr (type definition)

[top]

Structure of a raw mouse information block.

Fields:

 - int x - the (screen) x coordinate.
 - int y - the (screen) y coordinate.
 - int b - the mouse buttons.
 - int w - the WIMP window handle.
 - int i - the WIMP icon handle.

typedef struct {
  int x;
  int y;
  int b;
  int w;
  int i;
} main_mousestr;

main_init

[top]

Initialise the ROV core system, and start as an application.

Parameters:

 - char *task_name - the name of the application.

Returns:

 -  the WIMP task handle for this application.

int main_init(char *task_name);

See also: main_initnormalloc(), main_taskhandle

main_initnormalloc

[top]

Initialise the ROV core system, but do not initialise the memory allocation system. It is used when flex is being used without dynamic areas.

Parameters:

 - char *task_name - the name of the application.

Returns:

 -  the WIMP task handle for this application.

int main_initnormalloc(char *task_name);

See also: flex.h, main_init(), main_taskhandle

main_exit

[top]

Quit

Note - This is not absolutely necessary, as ROVLib adds this as an atexit() handler.

void main_exit(void);

main_nocrash

[top]

Enable a special 'nocrash' operation, but storing stack information, and registering handlers for aborts of various types. If an abort occurs, then a message box appears, prompting the user to either try to continue, or to actually abort the program. If the user elects to continue, then execution continues at the point after this function.

Note - Although it works fine, this isn't the most ideal system.

Note - This could be extended to perform some find of once-off execption system.

void main_nocrash(void);

main_addhandler

[top]

Add a handler to an event handler.

Parameters:

 - int event_code - the event handler code.
 - ... - the pointer to the event handler function.

Returns:

 -  the pointer to the old handler function.

Note - You should not use this, unless you intend to override ROV's functions, or if you wish to handle an event that ROV does not handle by default.

Note - You must not claim the HANDLER_RESERVED1 event.

Note - You should not claim the HANDLER_MESSAGE, HANDLER_MESSAGEACK note the HANDLER_ACKNOWLEDGE - you should use the functions in handextend.h instead.

void * main_addhandler(int event_code,
		       ...);

See also: Handler event codes, handextend.h

main_acknowledge

[top]

Acknowledge a message

Parameters:

 - message_block *block - the (modified) message block to acknowledge.
 - int reason - the WIMP message reason to reply with (17, 18 or 19).
 - int action - the action code to use.

Note - my_ref and your_ref are swapped for you.

void main_acknowledge(message_block *block,
		      int reason,
		      int action);

See also: main_send(), message_block

main_send

[top]

Send a message

Parameters:

 - message_block *block - the message block to send.
 - int reason - the WIMP message reason to send.
 - int to - either the task handle, or the WIMP window handle of the destination.
 - int ic - the WIMP icon handle, if to is a WIMP window handle.

Returns:

 -  the destination task handle.

int main_send(message_block *block,
	      int reason,
	      int to,
	      int ic);

main_transferblock

[top]

Transfer a block of memory

Parameters:

 - int src_task - the source task handle.
 - void *src_ptr - the source memory pointer.
 - int dst_task - the destination task handle.
 - void *dst_ptr - the destination memory pointer.
 - int len - the transfer length.

void main_transferblock(int src_task,
			void *src_ptr,
			int dst_task,
			void *dst_ptr,
			int len);

main_poll

[top]

Never-ending poll loop.

Note - Unlike RISC_OSLib where you call their poll within a loop, this one never terminates.

void main_poll(void);

main_setpollword

[top]

Set the polling pollword pointer

Parameters:

 - void *ptr - the pointer.

void main_setpollword(void *ptr);

poll_once

[top]

Polls repeatedly until the first null event.

void poll_once(void);

main_nextnull

[top]

Makes the next poll explicitly null pollable.

void main_nextnull(int);

main_time

[top]

Gets the OS monotonic timer.

Returns:

 -  the OS_ReadMonotonicTime value.

int main_time(void);

poll_block (external variable)

[top]

The message block used for polling

extern message_block poll_block;

poll_lastevent (external variable)

[top]

The last poll reason code.

extern int poll_lastevent;

rmalloc_newinit

[top]

Initialise a different memory allocation system if flex without dynamic areas is being used.

void rmalloc_newinit(void);

See also: flex.h, main_initnormalloc()

rmalloc

[top]

Allocate memory.

Parameters:

 - size_t len - the amount to allocate.

Returns:

 -  the pointer to the memory, or NULL if unable to allocate.

Note - Equivalent to malloc().

void *rmalloc(size_t len);

rcalloc

[top]

Allocate memory.

Parameters:

 - size_t len - the size of the object.
 - int count - the number of objects.

Returns:

 -  the pointer to the memory, or NULL if unable to allocate.

Note - Equivalent to calloc(), except memory is not zero'd

void *rcalloc(size_t len,
	      int count);

rfree

[top]

Free memory.

Parameters:

 - void *ptr - the pointer to free.

Note - Equivalent to free().

void rfree(void *ptr);

simple_warning

[top]

Produce a simple warning

Parameters:

 - char *str - the string to display.
 - int flags - OK and cancel flags.

Returns:

 -  0 for nothing clicked, 1 for OK clicked or 2 for Cancel clicked.

Note - This simply calls Wimp_ReportError.

int simple_warning(char *str,
		   int flags);

See also: Simple warning flags, Simple warning responses

get_3dstatus

[top]

Get the state of the 3D enabled flag in CMOS.

Returns:

 -  non-zero if 3D is enabled.

int get_3dstatus(void);

get_dragstatus

[top]

Get the state of the DragASprite enabled in CMOS.

Returns:

 -  non-zero if DragASprite is enabled.

int get_dragstatus(void);

new_errorbox

[top]

Produce a new-style error box on any version of RISC OS.

Parameters:

 - void *error - pointer to RISC OS error.
 - char *title - the title of the error box.
 - char *sprite - the name of the sprite on left hand side.
 - int nboxes - the number of boxes.
 - ... - list of pointers to strings for each box name.

Returns:

 -  index of the box clicked on.

Note - This does not use RISC OS 3.5+ error boxes, and performs its own display of an error-style box that works on any version of RISC OS.

int new_errorbox(void *error,
		 char *title,
		 char *sprite,
		 int nboxes,
		 ...);

See also: QUIT, new_errorbox(), ro35error.h

new_errorboxtxt

[top]

Produce a new-style error box on any version of RISC OS.

Parameters:

 - char *text - pointer to the text that appears as the error.
 - char *title - the title of the error box.
 - char *sprite - the name of the sprite on left hand side.
 - int nboxes - the number of boxes.
 - ... - list of pointers to strings for each box name.

Returns:

 -  index of the box clicked on.

Note - This differs from new_errorbox() in that it can be passed a pure text string to display.

int new_errorboxtxt(char *text,
		    char *title,
		    char *sprite,
		    int nboxes,
		    ...);

See also: QUIT, new_errorbox(), ro35error.h

errorbox_3d

[top]

Makes the new errorbox functions 3D instead of 2D.

Note - This is deprecated - it is called internally.

void errorbox_3d(void);

main_getosversion

[top]

Get the OS version (from OS_Byte 129, 0, 255)

Returns:

 -  the OS version number.

int main_getosversion(void);

main_getrawmouse

[top]

Get the raw mouse coordinates and button state

Parameters:

 - int *xp - the pointer to hold the (screen) x coordinate.
 - int *yp - the pointer to hold the (screen) y coordinate.
 - int *bp - the pointer to hold the button state.

void main_getrawmouse(int *xp,
		      int *yp,
		      int *bp);

main_machinetype

[top]

Get the machine type.

Returns:

 -  the machine type.

int main_machinetype(void);

See also: Machine types

main_processkey

[top]

'Send' a key to the WIMP (to deliver an unprocessed key)

Parameters:

 - int chcode - the character code to send.

Note - This calls Wimp_ProcessKey.

void main_processkey(int chcode);

main_starttask

[top]

Start a new task.

Parameters:

 - char *exec - the task's execution name.

Returns:

 -  the created task's task handle.

Note - this calls Wimp_StartTask.

int main_starttask(char *exec);

main_getmemorysize

[top]

Get the total memory size.

Returns:

 -  the total memory size in bytes.

int main_getmemorysize(void);

main_strlen

[top]

Get length of ctrl terminated string.

Parameters:

 - char *str - the string to get the length of.

Note - This is similar to strlen(), except that the string can be ctrl terminated.

int main_strlen(char *str);

main_strcpy

[top]

Copy a ctrl terminated string.

Parameters:

 - char *dst - the destination.
 - char *src - the source.

Note - This is similar to strcpy(), except that the source string can be ctrl terminated.

Note - The destination string will be zero terminated.

void main_strcpy(char *dst,
		 char *src);

main_strcmp

[top]

Compare two ctrl terminated strings.

Parameters:

 - char *str1 - the first string.
 - char *str2 - the second string.

Returns:

 -  negative if str1 < str2, zero if str1 = str2, and positive if str1 > str2.

Note - This is similar to strcmp(), except that the strings can be ctrl terminated.

int main_strcmp(char *str1,
		char *str2);

main_strwidth

[top]

Get the pixel width of a string.

Parameters:

 - char *str - the string to get the width of.

Returns:

 -  the string width in OS units.

Note - If the WIMP is using a font, then this is the width of the string in that font. If the WIMP is not using a font (or is incapable of doing so), then it is the width in OS characters.

int main_strwidth(char *str);

main_vsync

[top]

Wait for a vertical sync.

Note - This calls OS_Byte 19.

void main_vsync(void);

main_getdate

[top]

Get the current date from the real-time clock.

Parameters:

 - date_str *date - the block to store the date in.

Note - This is identical to file_getcurrentdate() in file.h.

void main_getdate(date_str *date);

See also: file.h

QUIT (external variable)

[top]

The text on the "Quit" icon for error boxes.

extern char QUIT[];

CANCEL (external variable)

[top]

The text on the "Cancel" icon for error boxes.

extern char CANCEL[];

CONTINUE (external variable)

[top]

The text on the "Continue" icon for error boxes.

extern char CONTINUE[];

OK (external variable)

[top]

The text on the "OK" icon for error boxes.

extern char OK[];

ERRORSPRITE (external variable)

[top]

The sprite name for error boxes.

extern char ERRORSPRITE[];

TASKNAME (external variable)

[top]

The task name for error boxes.

extern char TASKNAME[];

APPLY (external variable)

[top]

The text on the "Apply" icon for error boxes.

extern char APPLY[];

SAVE (external variable)

[top]

The text on the "Save" icon for error boxes.

extern char SAVE[];

main_wimpversion (external variable)

[top]

The WIMP version when called from Wimp_Initialise.

extern int main_wimpversion;

main_taskhandle (external variable)

[top]

The task handle assigned to this application.

extern int main_taskhandle;

Handler event codes

[top]
#define HANDLER_NULL		(0)
#define HANDLER_REDRAW		(1)
#define HANDLER_OPEN		(2)
#define HANDLER_CLOSE		(3)
#define HANDLER_ENTERWINDOW	(4)
#define HANDLER_LEAVEWINDOW	(5)
#define HANDLER_MOUSE		(6)
#define HANDLER_DRAG		(7)
#define HANDLER_KEY		(8)
#define HANDLER_MENU		(9)
#define HANDLER_SCROLL		(10)
#define HANDLER_LOSECARET	(11)
#define HANDLER_GAINCARET	(12)
#define HANDLER_MESSAGE		(13)
#define HANDLER_MESSAGEACK	(14)
#define HANDLER_ACKNOWLEDGE	(15)
#define HANDLER_SAVE		(16)
#define HANDLER_SAVEACK		(17)
#define HANDLER_LOAD		(18)
#define HANDLER_LOADACK		(19)
#define HANDLER_RUN		(20)
#define HANDLER_HELP		(21)
#define HANDLER_MODE		(22)
#define HANDLER_PALETTE		(23)
#define HANDLER_PREQUIT		(24)
#define HANDLER_MENUWARNING	(25)
#define HANDLER_RESERVED1       (26)
#define HANDLER_RMALLOC         (27)
#define HANDLER_RCALLOC         (28)
#define HANDLER_RFREE           (29)
#define HANDLER_CLIPCLAIM	(30)
#define HANDLER_CLIPREQUEST	(31)
#define HANDLER_DRAGGING	(32)
#define HANDLER_DRAGCLAIM	(33)
#define HANDLER_RAMFETCH	(34)
#define HANDLER_RAMTRANSMIT	(35)
#define HANDLER_CLAIMDEVICE	(36)
#define HANDLER_DEVICEUNCLAIMED	(37)
#define HANDLER_DEVICECLAIMED	(38)
#define HANDLER_TASKEXIT	(39)

Simple warning flags

[top]
#define WARN_OK			(0)
#define WARN_CANCEL		(1)
#define WARN_OKCANCEL		(2)

Simple warning responses

[top]
#define WARN_NOCLICK		(0)
#define WARN_OKSELECTED		(1)
#define WARN_CANCELSELECTED	(2)

WIMP messages

[top]
#define MESSAGE_QUIT		(0)
#define MESSAGE_DATASAVE	(1)
#define MESSAGE_DATASAVEACK	(2)
#define MESSAGE_DATALOAD	(3)
#define MESSAGE_DATALOADACK	(4)
#define MESSAGE_DATAOPEN	(5)
#define MESSAGE_DATARAMFETCH	(6)
#define MESSAGE_DATARAMTRANSMIT	(7)
#define MESSAGE_PREQUIT		(8)
#define MESSAGE_PALETTECHANGED	(9)
#define MESSAGE_CLAIMENTITY	(15)
#define MESSAGE_DATAREQUEST	(16)
#define MESSAGE_DRAGGING	(17)
#define MESSAGE_DRAGCLAIM	(18)

Button types

[top]
#define BUTTON_RIGHT            (1)
#define BUTTON_MENU             (2)
#define BUTTON_LEFT             (4)
#define DRAG_RIGHT              (16)
#define DRAG_LEFT               (64)
#define CLICK_RIGHT             (256)
#define CLICK_LEFT              (1024)

Machine types

[top]
#define MACHINE_PRE5000         (0)
#define MACHINE_PRERISCPC	(1)
#define MACHINE_RISCPCSTYLE	(2)
#define MACHINE_DOESNOTEXIST	(128)
#define MACHINE_A4		(129)
#define MACHINE_RISCPCLITE	(130)

Generated Thu Feb 7 23:22:52 2002