RiscOopLib

RiscOopLib from Arachne Software

The C++ Library for RISC OS

Arachne Software
Go to Arachne Software's Home Page




Find out about HyperStudio, an application written with RiscOopLib



ANT Fresco Friendly

Valid HTML 3.2!

What is RiscOopLib?

Introduction

RiscOopLib (as it is currently known) is a C++ Class Library for RISC OS.

History

RiscOopLib was born when Arachne received Acorn's port of CFront in early 1994. Wishing to learn C++, and finding that RISC_OSLib was neither usable (because of name clashes such as template) nor very suited to modification aimed at making it object-based, we naively set about writing our own class library. Fortunately we started in the right way with a large amount of discussion as to the nature of objects within the RISC OS environment, and came up with a structure which has proved to be very serviceable.

We had written basic support for such things as windows, icon bar icons, menus, etc., when we got the job of converting HyperStudio (a multimedia authoring package) from the Mac to RISC OS. Rather than trying to port the existing C sources (which we didn't receive for quite some time in any case) we decided to recode HyperStudio from scratch in C++, porting only the HyperLogo language interpreter. Thus HyperStudio has had a direct influence on the development of RiscOopLib.

The structure of RiscOopLib

The philosophy of RiscOopLib is that the maximum possible amount of automation should be built into objects without sacrificing any control over the finer details of their operation. Polymorphism provides an ideal way to implement this.

Various parts of the library use hidden channels of communication with each other. This is necessary because the central Wimp_Poll loop of a RISC OS application is not a very object-oriented construct, and is not directly visible from outside the objects in question.

The current state of RiscOopLib

Introduction

In its current form (that used by HyperStudio), RiscOopLib runs on all versions of RISC OS from 3.10 upwards, and includes special support for certain features found in RISC OS 3.5 upwards.

Current classes include: ArtworksFile, BarIcon, CatchEvent, ColourPicker, ColourPickerUser, DataTrans, DBox, DocWindow, DocWindowManager, DrawWindow, DrawItem, DrawFile, DrawWindowManager, DrawFontTable, DrawFont, File, Font, FontList, Gec, Manager, Menu, Messages, Module, OLEObject, OLEClient, PrintWin, Print, Replay, ReplayArea, SaveAs, Sound, Sprite, SpriteArea, SpriteList, SpriteManC, SpriteSelector, SpriteSelectorUser, TempData, Templates, TextArea, TextWindow, TextConsole, ConsoleUser, WAVEPlayer, and Window.

There are various bits of RiscOopLib that are not class-based. Mostly these are fairly insignificant, but two deserve mention: errhandler, and memx.

Object-based library components

Media support
Bitmapped graphics

SpriteArea is, fundamentally, a container class for sprites, although it also provides a number of useful facilities for using them. Sprite builds upon this to provide advanced painting and display facilities, unifying the interface to sprites and the screen. Sprite also provides help with speed optimisation of sprite plotting by cacheing transformed sprites.

Vector graphics support

DrawFile provides encapsulation and display of Drawfiles. Drawfiles may be built by an application using the DrawItem class; a draw item is a 'bit' of a Drawfile which makes sense as a unit and may be manipulated independently of other draw items. For example, a graphing package making use of the DrawItem facilities could use an 'axis' draw item. While this draw item could contain lines and text, it would understand that it was an axis and behave accordingly. Double-clicking on it could allow its parameters to be edited - it would take care of rebuilding itself without requiring the Drawfile to be rebuilt from scratch.

Support is provided in the ArtWorksFile class for displaying ArtWorks files using the AWRender module.

Text

TextArea provides DTP-style, frame-based, editable regions of text. Multiple styles may be used within them, and text may be formatted into irregular shapes. TextWindow allows the easy use of a TextArea in a scrollable window (possibly a pane).

Video

Replay films may be positioned within a frame in a window and played. The introductory sprite may be extracted and displayed in the frame.

Support is provided for live video in a window from cards such as the Eagle M2, via a generic interface module.

Sound

Basic facilities are provided for the manipulation of module sounds. The WAVEPlayer class plays wave files using Arachne's new SampleManager module.

Miscellaneous support
Colour

The ColourPicker class uses Acorn's Colour Picker module (if it is available), or a simple RGB slider window, to allow user selection of colours.

Fonts

The Font class stores a font description and allows fonts to be chosen and previewed in a standard font chooser window.

Printing

PrintWin provides a standard print dialogue passing parameters on to the Print class which performs the actual printing; the contents of a window - or a series of pages displayed in a window - may be printed with no extra redraw code.

GUI components
Window

This class may be split roughly into five functional areas: standard window operations, changing properties of windows, icon operations, intelligent automatic behaviour, and the hierarchical pane system.

Windows may be opened intelligently, centred on the screen, the pointer or a parent window. The redraw loop is automated, facilitating easy printing as mentioned above. As with the rest of RiscOopLib, as much as possible has been automated; for example many dialogue windows can be implemented only supplying code for click events. Comprehensive support for caret positioning operations is provided.

Most of a window's properties may be changed at any time, including the tools such as scroll bars; Window performs the necessary deletion and recreation. Calls for changing a window's extent keep the window intelligently positioned on the screen, adding scroll bars when necessary.

A full set of functions is provided for reading and writing different types of icon. Advanced Icon Types (AITs) provide a number of commonly used gadgets, such as sliders and bump icons, with extreme ease.

There are a number of cunning things which Window will do automatically to assist the programmer. If a window is opened which is larger than the screen, scroll bars are automatically added to the necessary sides of the window. When using Wimp drags, some bounding boxes can be calculated, and the window can be instructed to scroll when the pointer nears the edge, automatically changing the bounding box of the drag if necessary (correcting for a Wimp bug).

A highly sophisticated hierarchical pane system provides for many different behaviours. Panes may be attached to any point of a window, moving around intelligently either with the outline or the work area. Panes may be torn off their parents or may simply be freely movable on the screen but fixed in an ordered stack.

Menu

Standard menus are fully supported with no restriction on editing. Keyboard short cuts are formatted intelligently, and implemented fully automatically - if menu definitions are stored in an application's messages file, a user can change the keyboard short cuts simply by editing this file.

BarIcon

This class supports all permutations of iconbar icons, adjusting bounding boxes as necessary. It can be instructed to automatically open (or inform) a window when clicked on. A default menu, with an automatic info window and quit entry may be provided.

File-related classes
File

This class provides comprehensive support for file reading and writing operations. The chunk file format is supported, allowing each chunk to be used almost as a separate file. Chunks may be added and deleted at any time and automatic relocation ensures that there is no restriction on the growth of any chunk.

SaveAs

This provides a standard 'Save as' window which may either be attached to a menu or used standalone. Polymorphism provides an easy mechanism for the return of save requests.

OLE

An object may inherit the OLEObject class in order to support full OLE very easily. An OLEClient object is created which controls the session before arranging for its own deletion.

DocWindow

This provides support for windows containing documents by producing a Discard/Cancel/Save dialogue if an attempt is made to close them while they contain unsaved data. A Document Window Manager checks all existing Document Windows on pre-quit, and acts accordingly.

Low level
Manager

Every RiscOopLib application has one instance of Manager. This performs a large amount of automatic system initialisation and contains the Wimp_Poll loop. Objects register events which they are interested in with Manager, which then intelligently distributes incoming events. Manager can be requested to supply null events either continuously or not until a particular time has elapsed. It contains functions which allow pathnames for application-embedded files to be built. There is a function which sends a recorded message and waits for its reply before returning without affecting the operation of the rest of the application. Manager also maintains two message files: one for the library (of which a much-reduced version is embedded in the code), and one for the use of the application.

Messages

Any number of message files can be used by an application, each with its own instantiation of the Messages class. The main application message file may be registered with Manager for easy detokenisation of error messages.

CatchEvent

This class is fundamental to the whole philosophy of RiscOopLib. Any class which wishes to receive Wimp events must inherit it; it provides virtual functions for every important event. This allows many default actions to be built into objects, any of which may be overridden or added to. It also allows an inheriting object to request that it be deleted at a time when the stack is in a more suitable state. Event registration with Manager is made easy by a number of CatchEvent functions.

Gec

Short for Graphic event-catcher, this class may be inherited by any object which wishes to know when the palette or mode changes.

DataTrans

Once inherited, this class provides automation of many of the actions required in the Wimp's filing protocols. It also provides virtual functions for the easy receipt of instructions from SaveAs.

Templates

Each Templates object contains a templates file. Any number can be used permitting a memory saving since one or more files can be discarded after creating windows on startup while others are kept to create windows on the fly at a later stage.

Array

To facilitate the handling of arrays, the Array class provides allocation, insertion and deletion operations in memory claimed using 'new'. Spare memory is kept to allow frequent addition of elements without a large overhead in terms of time or memory fragmentation. Array may be inherited to obtain a pointer to any type.

Non-object-based library components

Error handling

Most RiscOopLib functions return a boolean. For these, TRUE implies success. If an error is indicated on return from any function, an error will have been stored in the RiscOopLib error handling system. This alleviates the need to pass around large numbers of error pointers. The three overloaded functions, errhandler(), control the error handling system. They all take a flag which indicates what is to be done with the error: it may be reported immediately as either fatal, non-fatal or giving the user a choice, or it may be stored. The first form takes and returns a pointer to an OS error. The second form takes a string which may contain a message token either for the library messages file or the main messages file; it also takes four parameter strings which are filled in by MessageTrans in the normal way. The last form only takes the flag and is used to display the stored error. Calls also exist for clearing or returning the address of the stored error.

When an object is constructed, a flag is set within it to indicate whether construction was successful or not. This flag is read using the object's !-operator: TRUE means failure, in which case an error will have been stored. The !-operator also tests the 'this' pointer and stores an 'Out of memory' error if it is zero. This has the advantage that 'new' can be used to construct an object and its !-operator will return an error either if 'new' failed or if the constructor itself failed. This results in a significant saving in code size.

Dynamic memory management

In addition to the C++ 'new' system, RiscOopLib provides a dynamic memory manager, similar to but more advanced than flex, called memx. It uses a system of anchors to provide resizable, relocating blocks of memory which may be locked or declared purgeable. A purgeable block may be deleted by memx at any time if the system becomes short of memory.

The future of RiscOopLib

The next stage of development of the library is to make it use Acorn's new Toolbox system. This will entail some quite dramatic internal changes but it is hoped that the external interface will remain mostly unchanged.

It is also intended to add support for:

  • The global clipboard and Drag'n'Drop systems
  • Clares' PCA system
  • A 'Shared RiscOopLib' relocatable module
  • Stack-per-object operation, allowing single functions to implement sequences of operations, rather in the way that RISC_OSLib used to. This would allow 'Wizards', for example, to be easily implemented.

Watch this space for more information on RiscOopLib,
including news of future developments...


Comments? Mail the Webmaster...

This page was last updated on 6/8/98.