# Using Libriscoslib

> Use the RISC_OSLib library from C-based RISC OS projects, including choosing the correct header include path and linking the exported library object in `Makefile,fe1`. Use when a task adds or reviews `#include "RISC_OSLib/..."` headers, `wimp_*`/other RISC_OSLib APIs, or `LIBS` entries for desktop applications and other RISC_OSLib-based code.

- Skill: `gerph/using-libriscoslib` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add gerph/using-libriscoslib`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gerph/using-libriscoslib/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- License: MIT
- Author: gerph (https://skillmd.com/u/gerph)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gerph/using-libriscoslib

---

# Using the library RISC_OSLib

Use this skill when a C project depends on the `RISC_OSLib` library.

## Default workflow

1. Confirm that the project is a C-based RISC OS component using `RISC_OSLib` APIs such as `wimp_*`.
2. Read the relevant resource notes for the headers you are about to touch:
   * `resources/overview.md` for the header map and major caveats
   * `resources/wimp-ui.md` for Wimp, template, menu, dialogue, help, and transfer helpers
   * `resources/text-editing.md` for `txt*` and `txtedit*`
   * `resources/system-graphics.md` for OS, resources, fonts, sprites, Draw, printing, memory helpers, and utility wrappers
3. Include headers with the exported include form `#include "RISC_OSLib/<header>.h"`.
4. Ensure the makefile can resolve those headers through `INCLUDES`, which is normally `-IC:` by default in the standard project templates.
5. Link the exported library object explicitly in `Makefile,fe1` through `LIBS`.
6. For simple Wimp tasks, prefer the `wimpt_*` helper layer from `RISC_OSLib` rather than dropping straight to the lower-level `wimp_taskinit` path.
7. Rebuild after any header or link change to catch unresolved symbols immediately.

## Include guidance

Use the exported include path form:

* `#include "RISC_OSLib/wimp.h"`
* `#include "RISC_OSLib/wimpt.h"`
* `#include "RISC_OSLib/os.h"`

Do not include headers by their host filesystem paths.

When using `RISC_OSLib/template.h`, include `RISC_OSLib/wimp.h` first, because
the template header relies on `wimp_wind` already being defined.

## Makefile linkage

When a project uses `RISC_OSLib`, add the library to `LIBS` in
`Makefile,fe1` using the exported object name:

    LIBS       = C:RISC_OSLib.o.risc_oslib

For 32-bit application builds this resolves to the correct `-32` variant
through the build system. If other libraries are already present, append
`C:RISC_OSLib.o.risc_oslib` to the existing `LIBS` list rather than replacing
them.

## Wimp task startup through `RISC_OSLib`

For small desktop applications using `RISC_OSLib`, the practical startup path
is usually:

1. call `wimpt_wimpversion(<minimum_version>)`
2. register the required message list with `wimpt_messages(...)`
3. call `wimpt_init(<task_name>)`
4. read back the task handle with `wimpt_task()`
5. enter the event loop with `wimpt_poll(...)`

This keeps startup and polling aligned with the `RISC_OSLib` helper layer.

When using `wimpt_messages`, terminate the `wimp_msgaction` array with
`wimp_MCLOSEDOWN`, as documented by the `RISC_OSLib` header.
Do not assume that an unterminated list is acceptable just because the first
few entries appear to work.

`wimpt_init` returns the actual Wimp version. Check it against the minimum
version you requested before continuing into application setup.

## Template loading

`RISC_OSLib` exposes both:

* the higher-level `template.h` helper layer
* the lower-level `wimp_open_template`, `wimp_load_template`, and
  `wimp_close_template` calls from `wimp.h`

Be careful with the higher-level helper layer. The `template.h` comments
document an assumption that the template file is called `Templates` in the
application directory. If the real packaged path or lookup context matters,
prefer the explicit `wimp_open_template("<App$Dir>.Templates")` path instead
of assuming the helper's default lookup will resolve correctly.

For explicit template loading through `wimp.h`, a practical pattern is:

1. call `wimp_open_template(...)` with the full application-relative path
2. call `wimp_load_template(...)` once with `buf <= 0` to obtain the required
   template-buffer and indirected-workspace sizes
3. allocate persistent storage for both the template buffer and the indirected
   workspace
4. call `wimp_load_template(...)` again with the allocated pointers
5. call `wimp_close_template()` even on failure paths

Keep the template buffer and indirected workspace alive for as long as the
created window exists. Do not free or overwrite them immediately after
`wimp_create_wind()`.

If the template name is being matched by name, use a writable aligned name
buffer rather than a string literal.

## Structure-field usage

`RISC_OSLib` gives you C structures for Wimp objects, but many UI details are
still configured through explicit packed fields rather than high-level helper
functions.

In particular:

* menu title and work-area colours are set through the menu header fields such
  as `tit_fcol`, `tit_bcol`, `work_fcol`, and `work_bcol`
* menu item foreground and background colours come from the item's
  `iconflags`, not the menu header colours
* icon button types are encoded into the icon flags, for example with
  `(wimp_BCLICKDEBOUNCE << 12)`
* submenu dialogue windows are attached through the menu item's `submenu`
  field even though the field type is expressed as `wimp_menuptr`

Do not assume that a `RISC_OSLib` menu API will derive those values for you.
When a menu or icon renders or behaves incorrectly, inspect the populated
structure fields and packed flag values directly.

For Wimp colour numbers used through `RISC_OSLib` structures, remember that
the logical Wimp palette maps `0` to white and `7` to black.

## Open-window protocol

Even when a window came from a template or is only used as a menu submenu,
normal Wimp open-window handling still applies.

If the task receives `wimp_EOPEN`, pass the returned `wimp_openstr` back to
`wimp_open_wind()` promptly. If you omit that handler, otherwise moveable
windows will not behave correctly when the user drags or reopens them.

## Practical checks

When reviewing or repairing a `RISC_OSLib` project, check these first:

* headers included as host paths instead of `RISC_OSLib/...`
* calls to `wimp_*` or other `RISC_OSLib` APIs with no matching `LIBS` entry
* abstract or guessed library names such as `libRISC_OSLib` instead of the
  exported object `C:RISC_OSLib.o.risc_oslib`
* application skeletons that compile but fail to link because the library was
  never added
* `wimpt_messages` lists that are not terminated with `wimp_MCLOSEDOWN`
* applications using `wimpt_init` but never checking the returned Wimp version
* code including `template.h` before `wimp.h`
* template-loading code that relies on the `template.h` default `Templates`
  lookup when an explicit application-relative path is safer
* template buffers or indirected workspaces that are stack-allocated or freed
  too early
* menu or icon code that changes the wrong colour fields because it confuses
  menu-header colours with item `iconflags`
* moveable windows or menu subwindows that never handle `wimp_EOPEN`

## Related skills

Use `writing-c` for general C style and structure.
Use `riscos-wimp` or `riscos-wimp-app` when the `RISC_OSLib` usage is
specifically for desktop Wimp applications.

## Resource notes

The `resources/` directory in this skill contains source-backed notes on the
public `RISC_OSLib` headers and the behaviour that is easy to miss from the
header comments alone. Use those notes instead of relying on the local
implementation sources being available to the next agent.