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: In progress (AR)

• 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.
  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. Possibly create a new framework to create a skeleton app with just one set-up function.
  Status: In progress (AR)

• 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: In progress (AR)

• SysLog: Add SysLog functionality (& possibly include in a Debug library). (Wait for conclusion to priority scheme as noted on GCCDSK mailing list.)
  Status: In progress (AR)

• 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: -

• 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.

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: In progress (AR)

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

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

• Tabs: Tabbed window support.
  Status: -

• KernelSWIs Module: This module currently provides a slightly random set of functions based on OS* SWIs. The functionality would be better placed in other modules, based on function rather than SWI name. A KernelSWIs header file containing #includes for the new locations could be created for backwards compatibility.
  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.)