RedcrabX – ImageBox Guide
Embedding, scaling and managing images on the worksheet | Version 1.0
← Back to Quick Start Guide
Table of Contents
1. Overview
The ImageBox embeds a raster image (PNG, JPEG, BMP, GIF, TIFF) directly
into the worksheet. The image is stored inside the worksheet file as base‑64
data, so the worksheet remains self-contained even if the original file is moved or deleted.
| Property | Default | Description |
|---|
| Min size | 64 × 64 px | The box cannot be made smaller than this |
| Initial size | 200 × 200 px | Size of a freshly inserted ImageBox |
| Scaling mode | Uniform | The image keeps its aspect ratio while filling the box |
| Render quality | HighQuality | Bitmap scaling uses high-quality interpolation |
2. Inserting an Image
- Click the Image button in the ribbon (workspace area).
- Choose a file in the Open File dialog.
- The image is loaded, encoded as base‑64, and placed on the canvas.
Note: The full image bytes are embedded in the worksheet, not just a
reference to the file path. Even if the original file is renamed or deleted, the worksheet
still displays the image correctly when re-opened.
3. Paste from Clipboard
You can paste any image currently on the Windows clipboard directly onto the canvas:
- Copy an image to the clipboard from any application (browser, screenshot tool, image editor, …).
-
Switch back to RedcrabX and press Ctrl+V
or click the Paste button.
- A new ImageBox is created and the bitmap is encoded as PNG inside the worksheet.
Tip: This is the fastest way to add screenshots, plots from external tools,
or copied figures to a worksheet without needing a separate file on disk.
4. Resizing and Aspect Ratio
The image is rendered with Stretch.Uniform: it always fits inside the box without
being distorted. You can therefore freely change the box size; the image scales but never stretches.
Manual Resizing
Drag the resize handle in the bottom-right corner of the ImageBox to scale it. The image
re-fits to the new content area automatically.
Reset to Original Size
Click the Reset to original size button in the status toolbar to set the
box dimensions to the image’s native pixel size (plus the small inner margin).
Reset to Original Aspect Ratio
Click the Reset to original aspect ratio button to keep the current
height (or width) but adjust the other dimension so the box matches the image’s
width-to-height ratio. This removes the gray margins that appear when the box is too
wide or too tall for the image.
When an ImageBox is selected, two buttons appear in the status toolbar at the bottom of the window:
| Icon | Tooltip | Action |
|---|
| Resize icon | Reset to original size | Set box dimensions to the image’s native pixel size |
| Axis icon | Reset to original aspect ratio | Adjust width or height so the box matches the image ratio |
6. Moving and Selecting
- Click the ImageBox to select it (a frame appears).
- Drag the box anywhere on the canvas to reposition it.
- Drag the bottom-right corner thumb to resize.
- Press Del to remove the selected box.
7. Saving with the Worksheet
When the worksheet is saved (Ctrl+S),
every ImageBox stores two pieces of information:
| Field | Description |
|---|
imageBase64 | The full image bytes encoded as a base‑64 string – this is the master copy used when re-opening the worksheet. |
imagePath | The original file path (for reference only). The image is not reloaded from this path on open. |
Self-contained worksheets: Because the image is embedded as base‑64,
you can share the worksheet file with others without needing to send the original images
separately. The trade-off is that worksheets containing many high-resolution images
become larger.
The Open File dialog accepts the following raster image formats:
- PNG – recommended for screenshots, diagrams, and graphics with sharp edges.
- JPEG / JPG – recommended for photographs (smaller file size).
- BMP – uncompressed Windows bitmap.
- GIF – only the first frame is shown for animated GIFs.
- TIFF – multi-page TIFFs show the first page.
Vector formats (SVG, PDF) are not supported. Convert them to PNG
beforehand if you need to embed them.
9. Tips and Best Practices
-
Resolution: Use images at roughly the resolution you want to display.
Embedding a 4000×3000 px photo to display it at 200×200 inflates the worksheet file unnecessarily.
-
Reset buttons: If an image looks distorted or framed by gray margins,
use the Reset to original aspect ratio button.
-
Print preview: Images print at the size shown on the canvas; use
Ctrl+P to preview before printing.
-
Grouping: Combine an ImageBox with a TextBox or LabelBox to create
annotated figures and diagrams.
-
Copy/paste workflow: Screenshot tools (e.g. Win+Shift+S)
pair perfectly with Ctrl+V for fast figure capture.