gerph Toolbox ImageFileGadget
Use this skill when application code uses the Toolbox ImageFileGadget object to
display image files in a Toolbox Window. ImageFileGadget is a client of
ImageFileRender: the application supplies image file bytes and metadata, and
the gadget performs redraws by calling ImageFileRender_Render.
For direct image rendering or for implementing new filetype renderers, use the
riscos-output skill and read its references/imagefilerender.md reference.
New image file format support is registered with ImageFileRender, not with
ImageFileGadget. Once a renderer is registered for a filetype, ImageFileGadget
can render that filetype through its normal SetValue method.
Application Workflow
- Include the ImageFileGadget Toolbox headers and use a Toolbox resource which contains an ImageFileGadget component.
- Load the image file into memory and determine its RISC OS filetype, normally
from
(load_address >> 8) & &FFF. - Call
ImageFileGadget_SetValuewith the filetype, data pointer, and data length. - Optionally call
ImageFileGadget_SetIndex,SetQuality,SetColourMap,SetTransform, orSetScrollto configure how the image is displayed. - Register a Toolbox handler for
ImageFileGadget_MouseClickif the application needs image-coordinate mouse interaction.
Applications do not need to register the gadget type with the Toolbox Window object. That is internal module setup done by ImageFileGadget itself.
Template and Flags
The ImageFileGadget template extends a normal Toolbox GadgetHeader:
typedef struct {
GadgetHeader hdr;
int event;
unsigned int unused;
unsigned int background;
} ImageFileGadget;
Useful gadget flags:
| Flag | Meaning |
|---|---|
ImageFileGadget_NoBorder |
Disable the gadget border |
ImageFileGadget_ColourMapWhole |
Apply colour mapping to the whole gadget area |
Public Methods
| Method | Purpose |
|---|---|
ImageFileGadget_SetValue(flags, window, component, filetype, data, length) |
Set the image bytes and filetype |
ImageFileGadget_GetValue(flags, window, component, &filetype, &data, &length) |
Read the current filetype, data pointer, and length |
ImageFileGadget_SetColour / GetColour |
Set or read the background colour |
ImageFileGadget_SetState / GetState |
Set or read gadget state bits |
ImageFileGadget_SetIndex / GetIndex |
Select or read the image sequence number |
ImageFileGadget_SetQuality / GetQuality |
Select or read the ImageFileRender quality level |
ImageFileGadget_SetColourMap |
Supply a colour map descriptor |
ImageFileGadget_SetTransform |
Set the ImageFileRender transform type and transform data |
ImageFileGadget_SetScroll / GetScroll |
Set or read the scroll position |
ImageFileGadget_GetBounds |
Read bounds for the current image and transform |
ImageFileGadget_DesktopColours is used with colour methods when the colour is
a desktop colour. ImageFileGadget_ImageCoords is used with scroll methods
when scroll positions are in image coordinates.
Transform and Display
ImageFileGadget_SetTransform uses the same transform types and data blocks as
ImageFileRender:
| Transform type | Data |
|---|---|
TRANSFORMTYPE_SIZE |
16-byte to-fit block: width, height, border, angle |
TRANSFORMTYPE_SCALE |
Standard 16-byte scale block: xmult, ymult, xdiv, ydiv |
TRANSFORMTYPE_TRANSFORM |
Six-word standard transform matrix |
The gadget computes display size with ImageFileRender_BBox, then redraws
inside Wimp redraw rectangles using ImageFileRender_Render. It normally uses
FLAG_IGNORE_DOCUMENT_OFFSET, optional FLAG_COLOURMAP, and
quality << FLAG_QUALITY_SHIFT.
If code needs the actual ImageFileRender register contract or transform block
formats, read the riscos-output ImageFileRender reference.
Mouse Events
Mouse events are raised as ImageFileGadget_MouseClick. The event block is:
typedef struct {
ToolboxEventHeader hdr;
unsigned int flags;
int smousex;
int smousey;
int imousex;
int imousey;
} ImageFileGadgetMouseClickEvent;
smousex and smousey are screen coordinates within the gadget. imousex and
imousey are image coordinates computed by inverting the ImageFileRender
transform.
Mouse event flags:
| Flag | Meaning |
|---|---|
ImageFileGadget_MouseClick_Flags_DoubleClick |
Double-click |
ImageFileGadget_MouseClick_Flags_AdjustClick |
Adjust button was used |
ImageFileGadget_MouseClick_Flags_StartDrag |
Drag start |
ImageFileGadget_MouseClick_Flags_MenuClick |
Menu button was used |
ImageFileGadget_MouseClick_Flags_XInImage |
X coordinate is inside image bounds |
ImageFileGadget_MouseClick_Flags_XLow |
X coordinate is below image bounds |
ImageFileGadget_MouseClick_Flags_XHigh |
X coordinate is above image bounds |
ImageFileGadget_MouseClick_Flags_YInImage |
Y coordinate is inside image bounds |
ImageFileGadget_MouseClick_Flags_YLow |
Y coordinate is below image bounds |
ImageFileGadget_MouseClick_Flags_YHigh |
Y coordinate is above image bounds |
Debugging
Use *ImageFileRenderers to confirm that a renderer is registered for the
filetype being supplied to ImageFileGadget_SetValue.
If the image is blank, check:
- The file data pointer remains valid for as long as the gadget needs it.
- The filetype matches the image data.
- A renderer exists for that filetype.
- The transform data matches the selected transform type.
- The quality value is in the ImageFileRender range 0-15.
- Scroll values are using the expected coordinate system.