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

1. Include the ImageFileGadget Toolbox headers and use a Toolbox resource which contains an ImageFileGadget component.
2. Load the image file into memory and determine its RISC OS filetype, normally from (load_address >> 8) & &FFF.
3. Call ImageFileGadget_SetValue with the filetype, data pointer, and data length.
4. Optionally call ImageFileGadget_SetIndex, SetQuality, SetColourMap, SetTransform, or SetScroll to configure how the image is displayed.
5. Register a Toolbox handler for ImageFileGadget_MouseClick if 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:

Public Methods

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:

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:

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.