RISC OS Widget Set

Rather crappy documentation

Abstraction layer

This file documents in brief the ROWS GUI abstraction layer. At the time of writing, this isn't complete (ROWS_window is still in need of a bit of a fix), however, the observant of you will have noticed that now only the ROWS_X* source files reference X library functions, and ROWS_drawable, etc run a little bit slower than before.

The abstraction layer is currently described in ROWSint_drawable.h. To start writing a graphics driver for ROWS, you first need to derive a new drawable widget from the base widget (you could probably derive a new drawable from one of the non-abstract drawables, but you will need to be cautious about trampling over some of the data structures). As I write this, there's still quite a lot of crap lying around in the source code from my first attempt at the same thing...

Anyway, back to your new drawable. In your setup function, you need to call ROWS_drawable_get_abstraction_layer() (defined in ROWSint_drawable.h) to get a pointer to the structure that holds the functions. Note that you can only change this in your setup function - if you try altering the functions from anywhere else, you risk thread-safeness problems. The function returns a pointer to a ROWS_drawable_brush_calls structure, which currently contains one item - 'functions', which is an array of all the functions (which have some default values). Each of these functions is of type void foo(ROWS_drawable_fparam *param). The ROWS_drawable_fparam structure is defined in ROWSint_drawable.h, and is used to pass the parameters to the various functions. These parameters are passed as follows:

Generally you will want to store additional data with each brush that is created for your drawable. ROWSint_brush.h contains the ROWS_brush widget data structure. is of particular interest, as you can use it to store any data you like (at least if your drawable is directly derived from ROWS_drawable). Use ROWS_alloc to allocate the data (as it produces an error on failure) in your function for ROWS_DRAWABLE_BRUSH_CREATE. The other items in the ROWS_brush structure can be pretty much used how you like, although it's probably best to keep to their default definitions:

You may be intrigued to know the meaning of the last_serial. Well, the ROWS_drawable data structure is also open to perusal by your driver (although I recommend that you only read from it [I could provide a function layer to go through to read from it, but that would be slow...]). You can check if the _p_ROWS_drawable_data.clip_serial is equal to your brush's last_serial number (_p_ROWS_drawable_data.clip_serial is automatically updated by the ROWS_drawable_* functions when required, and you don't have to worry about doing this yourself in your abstraction layer).

Anyway, I think that's about it... Note that, with the exception of ROWS_DRAWABLE_BRUSH_CREATE & DESTROY, the functions default to an error message, and that generally the drawable is not locked on entrance to the colour and brush functions and you might need to lock it yourself with ROWS_widget_lock.

Not finished