DeskLib

C Wimp Library for RISC OS

Introduction

DeskLib is a fully-sourced, general-purpose freeware C library for writing desktop applications for RISC OS. It provides comprehensive support for window and icon manipulation, menu creation, graphics routines, message handling, filing operations, font handling, string manipulation and much more. High level event management functions are provided in order to build coherent and powerful code.

Download

Latest Release

The current version of DeskLib is 2.80, released in July 2007. It is available for installation using RiscPkg or can be downloaded from here:

• Core contains everything needed to use the library, including documentation.
• Examples has practical examples on how to use the different parts of DeskLib.
• Source contains the C and assembler source which makes up the library functions. (Note: this part is not included in the RiscPkg package.)

Changes

Changes since version 2.70 include:

• Several important bugfixes, optimisations and a couple of API changes in Sprite.
• Provided 'sprite by pointer' in addition to 'sprite by name' routines (named as Sprite_*P()).
• Added Sprite_SetPointerShape()/Sprite_SetPointerShapeP().
• Some extra examples
• Tinct support
• Rationalised documentation including an updated StrongHelp manual
• Minor additions to the Icon and Window modules

For older changes, see the changes page.

Documentation

Manuals

Descriptions of the functions, structures, types etc are included with the Core download in StrongHelp format, or you can browse an unofficial online HTML version. The download also includes various notes and updates which can be accessed from the Help option on the filer menu for the applications.

Tutorials & Examples

• Tutorial by Frauke Nonnenmacher (quite old, but still good)
• Examples by Shaun Lindsley

Development

Source

The sources for DeskLib are held in a subversion repository on riscos.info. Read access is available to all, either by checking out the project with svn or by viewing via the WebSVN web interface.

To make contributions, post to the DeskLib mailing list with patches or a request for svn write access.

Properties

Subversion allows 'properties' to be set for files in the repository and a number of conventions should be followed when creating or modifying files:

• svn:executable should be unset for all files
• svn:mime-type should be set equal to some non-text value (for instance application/octet-stream) for binary files
• svn:eol-style should be set to native for all text-based files, and should not be set for binary files

Building

DeskLib is built, as standard, using GCC, though it should still build using other compilers. It can be built using the GCC cross-compiler; natively using GCC; or using the GCCSDK autobuilder.

Cross-compiling using GCCSDK

To build from the sources using GCCSDK, make sure the current work directory is !DLSources and use:

$ make -f Makefile.unix

(Remember to escape the !s - e.g. cd \!DLSources.) Note that for the cross-compile build to be successful, the environment variable GCCSDK_INSTALL_CROSSBIN needs to be present. If you don't have this set already and you've followed the standard installation instructions for GCCSDK then adding the line:

GCCSDK_INSTALL_CROSSBIN ?= /home/riscos/cross/bin

to the start of the makefile will set the variable for you (if it's unset).

Compiling under RISC OS

To compile under RISC OS using GCC, set the current directory to !DLSources and either run the MakeDeskLib file or open a taskwindow and type:

* make  

Roadmap

The next major release of DeskLib will be version 3.0 and will be ELF-based, requiring GCC 4.x. The following is a list of potential work which could be done on DeskLib. Items with "low" priority may not be implimented. Items with "high" priority need to be completed for version 3.0. If you'd like to help out, please get in touch.

High Priority

• ELF: Move to ELF format with GCC 4.x
  Status: In progress (see trunk in svn repository)

• Namespace: Prefix all DeskLib objects with dl_. Create a "compatibility" header file with a set of macros to map old names to new scheme along with an automated tool to permanently change source code to use the new scheme.
  Status: -

• Documentation: Cleaning up and rationalisation. For instance, 10-year old notes need bringing up to date or removing.
  Status: Provisional changes checked in to AOF branch

• OSLib Integration: Use OSLib SWI calls in DeskLib.
  Status: -

Medium Priority

• Multi-tasking message windows: Provide standard message windows, perhaps with a set of handlers to deal with simple yes/no input from end user.
  Status: -

• New error handling routines: Re-think how DeskLib handles run-time errors. See old notes in current documentation and the changes made to Desk. Possibly just add a Error_Initialise function which takes an error handler, then call that from the Error routines.
  Status: -

• Wimp_ReportError Updates: Update the Error functions to use the extensions included in RISC OS 3.6 - for instance including the program icon in the error window.
  Status: -

• Initialisation Routines: Rationalise some of the "init" functions, for instance in the Template and Resource modules.
  Status: Changes checked in to AOF branch

• Parameter Checking: Values passed to DeskLib functions should be checked that they are not invalid and dealt with accordingly, to improve stability.
  Status: -

• Build to C99 Standard: Build library to C99 and make use of new functions such as snprintf (rather than sprintf) throughout to improve stability.
  Status: Changes checked in to AOF branch

• SysLog: Add SysLog functionality.)
  Status: Changes checked in to AOF branch (in Environment module)

• Makefiles QA: The various makefiles have been amended and adapted over time and need checking/re-writing.
  Status: -

• Code Audit: Examine existing code to determine its status - for instance, the Tinct module is written, but has no documentation; the clipboard module is half-written; some code can be retired as it's only needed for RISC OS 2; etc.
  Status: CSV database checked in to AOF branch (AR)

• Debug Library Changes: Move the debug functions into the main library binary and alter Debug_Initialise to accept some parameter to determine which set of debug functionality is used. (As this will alter the API, need to ensure the namespace-change task, above, copes with it.)
  Status: Provisional changes checked in to AOF branch.

• Module Rationalisation: Some modules are only present for compatibility reasons, others could be merged (e.g. ColourMenu module only has one function which ought to fit neatly in the Menu module and the several of the KernelSWIs functions would fit better elsewhere). Tidy up these issues.
  Status: Changes checked in to AOF branch

Low Priority

• Internationalisation: Provide structure to allow internationalisation of DeskLib error messages.
  Status: -

• License Change: Change license to MIT for clarity and simplicity
  Status: -

• Back-ports: Port back changes made to Desk and to Richard Murray's branch of DeskLib. Probably only need to make list of potential changes and port when required.
  Status:-

• Scrap: Routines to set up/use the scrap directory (in Resource module)
  Status: -

• Internal Debugging: Create internal debugging messages - for instance, see Menu2 module.
  Status: -

• Environment Module: Create new module to include functions such as manipulating system variables, listing running tasks, modules etc
  Status: First draft checked in to AOF branch

• Reporter Debug Library: Create debug library which makes use of the Reporter module.
  Status: Checked in to AOF branch.

• ZapRedraw Support: New module to interface to ZapRedraw
  Status: -

• Tabs: Tabbed window support.
  Status: -

• Writable Icons: Provide means to intelligently check input to writable icons. This could be done by using A in the validation string then claiming all keypresses, allowing things like only allowing any number between x and y, including decimal parts; converting all characters to lower/upper case; any other validation function you choose.
  Status:-

• Window Opening: Expand the number of window_OPENPOSs to include things like opening: not over the caret, in spare screen space, centred over another window. Could also deal intelligently with multiple monitor setups.
  Status:-

Support

If you have questions either about the use of DeskLib or about building it, please either ask on the comp.sys.acorn.programmer usenet group or the DeskLib mailing list. (The mailing list can be joined by sending an email to desklib-subscribe@googlegroups.com.)