Introduction and Overview
NanoColour is a module which renders syntax-coloured text from a caller-supplied memory buffer. It is intended for applications which need to size and draw source text or similarly structured files without embedding their own nanorc parser, colouriser or font management.
The module combines three pieces of work into a single service: syntax selection, colour decoding, and graphical rendering. A caller opens a rendering session for a text buffer, optionally supplies a syntax name, configures the rendering style, requests the overall rendered size, and then renders the text at a chosen position.
If no syntax name is supplied, the module searches the nanorc definitions in NanoRCs$Dir and selects the most suitable syntax automatically.
Technical details
Each open session is represented by an opaque handle returned by SWI NanoColour_Open. The handle owns the decoded text, the selected syntax, the cached colour information, the chosen font details and any cached layout information needed for efficient measurement and redraw.
Rendering model
The module creates a single GContext during initialisation and uses it for all rendering operations. Callers do not supply a GContext handle. Instead, the session records the presentation choices which the module should apply when measuring and drawing.
The module owns the font selection for each session. The caller supplies a font name and font size through SWI NanoColour_SetStyle, and the module creates or replaces the underlying font instance as required. Changing the font, default colours or text content invalidates any cached layout metrics.
Syntax selection
If the syntax pointer passed to SWI NanoColour_Open or SWI NanoColour_Recolour is non-zero, it names the syntax to be used explicitly. If the pointer is zero, the module searches the nanorc files in NanoRCs$Dir and auto-detects a syntax from the supplied text.
Auto-detection is intended to follow the same syntax-matching rules as the NanoColour library: filename-style rules where available, followed by header matching against the start of the buffer. If no suitable syntax can be identified, the module reports an error rather than silently applying an arbitrary syntax.
Measurement and rendering
The session caches enough layout information that SWI NanoColour_GetSize can be called before any drawing takes place. This allows applications to size work areas, scroll extents or transient display regions before invoking SWI NanoColour_Render.
Rendering is performed relative to the caller-supplied origin. The draw operation uses the session's configured colours and font. An optional clip rectangle may be supplied to permit callers to redraw only the region which intersects the visible area.
Flags and handles
All SWIs use R0 for flags. Reserved flag bits must be zero. Session handles returned by the module are opaque values and must not be interpreted by the caller.
Provisional allocation
This design uses the provisional SWI chunk base &C3AC0 and the provisional error base &9FBA00. Both values are unallocated and are recorded as placeholders pending formal registration.
System variables
This variable identifies the directory searched when syntax selection is requested without an explicit syntax name. The directory should contain nanorc files in the format understood by the NanoColour library.
SWI calls
| R0 | = | flags:
| ||||||
| R1 | = | Pointer to the text buffer to be rendered | ||||||
| R2 | = | Length of the text buffer in bytes | ||||||
| R3 | = | Pointer to a NUL-terminated syntax name, or 0 to auto-detect from NanoRCs$Dir | ||||||
| R0 | = | Session handle |
This SWI creates a new rendering session from the caller-supplied buffer. The buffer is treated as the text source for the session, and the session retains whatever internal state is required to recolour, size and render that content.
If R3 is zero, the module performs syntax auto-detection using the definitions found in NanoRCs$Dir. If R3 is non-zero, the named syntax is used directly.
| R0 | = | flags:
| ||||||
| R1 | = | Session handle | ||||||
| R0 - R9 | preserved | |
This SWI destroys a session created by SWI NanoColour_Open and releases all associated state, including cached colour information, layout caches and module-owned font objects for the session.
| R0 | = | flags:
| |||||||||||||||
| R1 | = | Session handle | |||||||||||||||
| R2 | = | Pointer to a NUL-terminated font name; ignored unless bit 2 is set | |||||||||||||||
| R3 | = | Font width in sixteenths of a point; ignored unless bit 2 is set | |||||||||||||||
| R4 | = | Font height in sixteenths of a point; ignored unless bit 2 is set | |||||||||||||||
| R5 | = | Default foreground colour value; ignored unless bit 0 is set | |||||||||||||||
| R6 | = | Default background colour value; ignored unless bit 1 is set | |||||||||||||||
| R0 - R9 | preserved | |
This SWI updates the presentation for an existing session. The module owns the font instance created from the supplied name and size, and replaces any existing session font when the font-select flag is set.
Any change made by this SWI invalidates the cached layout metrics for the session, so that the next call to SWI NanoColour_GetSize or SWI NanoColour_Render recalculates the layout.
| R0 | = | flags:
| ||||||
| R1 | = | Session handle | ||||||
| R0 | = | Rendered width |
| R1 | = | Rendered height |
This SWI returns the total bounds of the rendered text for the session's current style. Applications should call it before drawing if they need to establish the size of a work area or the extent of a display region.
| R0 | = | flags:
| |||||||||
| R1 | = | Session handle | |||||||||
| R2 | = | X coordinate of the render origin | |||||||||
| R3 | = | Y coordinate of the render origin | |||||||||
| R4 | = | Pointer to a clip rectangle, or 0 if bit 0 is clear | |||||||||
| R0 - R9 | preserved | |
This SWI renders the current contents of the session using the module-owned GContext and the session's configured style. The origin identifies the top left position of the rendered text.
If a clip rectangle is supplied, the module may reject rendering which falls wholly outside the rectangle and may use the rectangle to restrict redraw work.
| R0 | = | flags:
| ||||||
| R1 | = | Session handle | ||||||
| R2 | = | Pointer to the replacement text buffer | ||||||
| R3 | = | Length of the replacement text buffer in bytes | ||||||
| R4 | = | Pointer to a NUL-terminated syntax name, or 0 to auto-detect from NanoRCs$Dir | ||||||
| R0 - R9 | preserved | |
This SWI updates an existing session with new text and re-runs the colouring stage. It is intended for viewers and editors which need to keep a stable handle while their text changes over time.
Changing the text or syntax also invalidates the cached layout metrics for the session.
Error messages
The error numbers in this section use the provisional unallocated base &9FBA00 and are intended to be replaced only if a different registered base is assigned during implementation.
This error is reported when a SWI is called with one or more reserved bits set in R0.
This error is reported when a SWI which operates on an existing session is passed an unknown or expired handle.
This error is reported when the caller supplies an invalid text pointer, an invalid length, or an invalid style parameter block for the requested operation.
This error is reported when the caller asks for auto-detection and the module cannot identify a suitable syntax from NanoRCs$Dir, or when the explicitly named syntax does not exist.
This error is reported when the module cannot create or select the requested font for a session.
This error is reported when the module cannot allocate the working storage needed for syntax processing, colour decoding, font state or rendering caches.
Examples
handle = SWI "NanoColour_Open", flags 0, text_ptr, text_len, 0
SWI "NanoColour_SetStyle", set font and colours, handle,
"Corpus.Medium", 192, 192, foreground, background
width, height = SWI "NanoColour_GetSize", 0, handle
SWI "NanoColour_Render", 0, handle, x, y, 0
SWI "NanoColour_Close", 0, handle