RedcrabX – ImageBox Guide
Embedding, scaling and managing images on the worksheet | Version 1.0
Table of Contents
- 1. Overview
- 2. Inserting an Image
- 3. Paste from Clipboard
- 4. Resizing and Aspect Ratio
- 5. Status Toolbar Buttons
- 6. Moving and Selecting
- 7. Saving with the Worksheet
- 8. Supported File Formats
- 9. Tips and Best Practices
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.
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.
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.
5. Status Toolbar Buttons
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. |
8. Supported File Formats
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.
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.