Editor Overview
This page is the complete reference for the Lopaka editor UI. Each major section has a dedicated guide linked from the headings below. Use this page to get your bearings and find your way into the details.
Layout
The editor combines a project layer tree, a workspace, and a code panel:
┌──────────┬──────────────────────────┬─────────────┐
│ │ Top bar │ │
│ Layers ├──────────────────────────┤ Inspector │
│ panel │ Screens + tools │ panel │
│ ├──────────────────────────┴─────────────┤
│ │ Code panel │ Code settings │
└──────────┴──────────────────────┴─────────────────┘| Region | Purpose |
|---|---|
| Layers panel | Expandable screens, layers, and groups, resizable |
| Top bar | Project details and actions |
| Canvas | The project’s screens and artwork |
| Inspector panel | Properties for the selected layer |
| Code panel | Screen code tabs, resizable |
| Code settings | Code output toggles and downloads |
Resize the panels
The Layers panel and the code panel are resizable. Drag the resize handle on a panel edge to change the size of that panel.
Top bar
The top bar contains Project details and Actions. Drawing tools sit above the workspace, with zoom controls on its right.
Project details
Shows information about the current project and screen.
- Breadcrumb —
Project name › Screen name. Both labels are truncated if long. - Platform badge — shows the active platform (e.g.
tft-espi). Read-only display; the platform is chosen when the project is created and cannot be changed later. - Display size badge — shows the configured display resolution (e.g.
128×64). - Settings (cog icon) — opens the Project Settings modal.
- Public project — a green label shown when the project is visible to all users in the Gallery.
The project details zone is only shown when you are logged in or viewing in read-only mode.
Toolbar
The toolbar above the workspace contains the Select button and drawing tools for the active platform.
Select (no tool active)
Click the cursor icon or press Escape to return to select mode. In select mode the cursor is the default pointer; clicking a layer on the canvas selects it. Clicking empty space deselects all layers.
Drawing tools
Tools that are not supported by the active platform are hidden. The following tools exist in the codebase:
| Tool | How to use |
|---|---|
| Image | Opens the image wizard: upload an image, GIF, or video; pick from built-in icon packs; paste a raw byte array; or add an animation on supported platforms |
| Paint | Freehand pixel-level drawing on a bitmap layer; right-click erases; hold Shift to draw straight lines |
| Text | Click activates the tool; a text layer is placed at the center of the screen automatically, selected, and the inspector text field focused |
| Rectangle | Click-drag to define opposite corners |
| Circle | Click-drag from center; radius follows the drag |
| Ellipse | Click-drag to define the bounding box |
| Line | Click-drag from start to end point |
| Triangle | Three-click multi-point: click each vertex, double-click or Escape to finish |
| Polygon | Multi-click: place any number of vertices, double-click or Escape to finish; double-click an existing polygon to edit vertices |
| Arc | TFT_eSPI only; adds a centered arc with editable radius, angles, width, colors, and edge smoothing |
LVGL only
| Tool | How to use |
|---|---|
| Text Area | Same as Text but produces a multiline text layer |
| Panel | Draws a panel container widget |
| Button | Draws a button widget |
| Checkbox | Draws a checkbox widget |
| Switch | Draws a switch widget |
| Slider | Draws a slider widget |
| Arc LVGL | Adds an LVGL arc widget with value and track |
Arc tools
TFT_eSPI and LVGL use separate arc tools because their drawing models are different. Arc on TFT_eSPI is a drawing primitive controlled by radius, start and end angles, width, foreground color, background color, and a Smooth toggle. Equal start and end angles produce a full circle.
Arc LVGL creates a widget with width, height, rotation, start and end angles, value, indicator color, and track color. The value is limited to 0–100. Each arc tool is shown only on its supported platform.
Image import wizard
See the full Importing Images guide for all import modes, editor controls, and step-by-step workflows.
Tip: You can also drag a PNG or BMP file directly onto the canvas to skip the wizard entirely — the image is imported with default settings.
Paint brush controls
When the Paint tool is active, extra controls appear in the toolbar:
- Pattern dropdown — choose Full, Checkerboard, Horizontal lines, Vertical lines, or Circle. The preview updates before you draw, and patterns align to the screen grid across separate strokes.
- Eraser mode toggle — makes normal painting erase pixels. Right-click also erases, and both eraser paths use the selected brush pattern.
- Color mode toggle — switch between Monochrome (1-bit) and RGB brush modes.
- Brush color picker — visible in RGB mode; sets the current paint color.
- Crop — appears for Paint layers large enough to crop. Crop mode shows orange handles and dims the area outside the crop; drag the region or handles, then apply or cancel.
Escapeexits crop mode before leaving the Paint tool, and applied crops can be undone.
Scale
A scale control on the right of the workspace adjusts canvas zoom. The same zoom can be changed with Ctrl + / Ctrl - or by scrolling the mouse wheel while holding Ctrl/Cmd.
Actions
Project-level actions, visible when logged in or viewing in read-only mode.
- Star — bookmark the project. The button shows the current star count.
- Fork — creates a copy of the project under your own account and opens it immediately. Requires login.
- Share — dropdown menu with the following options:
- Copy public link — copies a direct gallery URL to the clipboard. Disabled if the project or current screen is private.
- Presentation — opens a full-screen slideshow of all screens in the project.
- Save As — Text file exports the open code tab, including custom code. PNG image and BMP image export the selected screen, or the code tab’s screen if no screen is selected.
Canvas
The workspace shows the project’s screens together at the selected scale. Each screen previews the artwork for the target display.
Grid
Click Grid on the right of the workspace to cycle between a 1-pixel grid, a 10-pixel grid, and no grid. The default 1-pixel grid appears at 300% zoom or higher; the 10-pixel grid appears at 30% or higher. The grid is visual only and has no snap behavior.
Mouse interactions
| Interaction | Effect |
|---|---|
| Click empty area | Deselect all layers |
| Click layer | Select that layer |
Shift + click | Add or remove layer from selection |
| Click-drag empty area | Draw a rubber-band selection rectangle |
| Click-drag selected layer | Move the layer |
| Click-drag resize handle | Resize the selected layer |
Hold Shift while resizing | Constrain to original aspect ratio |
Hold Alt while resizing | Resize from center |
| Click a grouped layer | Selects all layers in the group |
| Double-click a grouped layer | Selects that individual layer only |
Shift + click a grouped layer | Adds all group members to selection |
| Double-click Polygon / Triangle | Enter vertex edit mode |
| Double-click empty space in a selected screen | Deselect the screen, so you can draw a selection rectangle inside it |
| Right-click (Paint tool) | Erase pixels |
Ctrl/Cmd + scroll wheel | Zoom in / out, centered on the cursor |
| Scroll wheel (no modifier) | Pan the canvas |
| Middle-button drag | Pan the canvas |
Touch and stylus
A tap works like a click. A quick double tap with a finger or a stylus works like a double-click: it renames a screen from its title, enters vertex edit mode, or deselects a selected screen when you double tap empty space inside it. Drag with two fingers to pan and pinch to zoom.
Interrupted gestures
A drag can end without you lifting the pointer: you switch to another window or tab, or the device cancels your touch or stylus contact (for example, palm rejection). Then:
- Layers or screens you were moving, a layer you were resizing, and a crop frame you were adjusting return to where they started. Nothing is added to Undo.
- A shape you were drawing is discarded.
- A paint stroke keeps what you painted so far. One Undo removes it.
Undo does nothing while you are still dragging; release first. If you close the editor in the middle of a drag, the drag is kept.
Dropping images
You can drag a PNG or BMP file directly onto the canvas. The image is imported immediately using default settings and placed as a bitmap (Paint) layer.
Screens list
Screens appear as expandable entries in the Layers tree on the left, with their layers and groups nested underneath.
Adding screens
Click Add Screen in the Layers header to add a new screen. The name is auto-generated as Screen N with the next available number.
Navigating screens
Click a screen row in the Layers tree to select and focus that screen. Use its expand arrow to show or hide its layers.
Reordering screens
Drag a screen row to a new position. The order is saved immediately.
Renaming a screen
Double-click the title above a screen in the workspace to edit it inline.
Context menu (right-click)
Right-click the title above a screen to open its context menu:
| Action | Description |
|---|---|
| Duplicate | Creates a copy of the screen and appends it to the list. |
| Publish | Makes a private screen visible in the Gallery. |
| Make Private | Hides the screen from the Gallery. |
| Delete | Removes the screen. Requires a second click to confirm. |
Layers list
The Layers tree lists the project’s screens, layers, and groups. Expand a screen to see its layers in render order (top of the list = top of the stack = drawn last).
Layer list actions
| Action | How |
|---|---|
| Select a layer | Click its row |
| Select range | Click one layer, then Shift + click another layer |
| Toggle selection | Ctrl/Cmd + click a layer |
| Select all | Ctrl A |
| Reorder | Drag-and-drop a row to a new position |
| Reorder with keyboard | Select a layer, then Ctrl ↑ / Ctrl ↓ |
| Show / hide | Click the eye icon on hover |
| Lock / unlock | Click the lock icon on hover |
| Delete | Select, then Delete or the Delete button in the Inspector |
Groups
Layers can be grouped. A group appears as a collapsible entry in the layer list. Click the group header to select all member layers at once. Ctrl/Cmd + click a group header toggles all members of that group in the current selection. Click the expand arrow to show or hide member layers inside the group row; range selection still includes layers inside collapsed groups.
| Action | Shortcut |
|---|---|
| Group selected layers | Ctrl G |
| Ungroup | Ctrl Shift G |
| Rename group | Double-click group name in Inspector |
You can drag individual layers into and out of groups by dropping them inside or outside the group container in the list.
Inspector
The inspector panel is on the right side. Its content changes depending on the selection state. Use Hide inspector or Show inspector on the right of the workspace to toggle it; the choice is remembered in this browser.
Shortcuts cheatsheet
When nothing is selected the inspector shows a keyboard shortcut reference. This is a quick reminder; the full list is in the Keyboard Shortcuts reference.
Single layer selected
The inspector shows:
- Layer icon + name — hover to reveal the edit icon, then click it to rename inline.
- Alignment buttons — six buttons that position the layer relative to the display edges and center:
| Button | Single layer | Multiple layers |
|---|---|---|
| Align left | Move to left edge of display | Align all left edges to the leftmost layer |
| Align horizontal centers | Center horizontally on display | Align all horizontal centers to the shared center |
| Align right | Move to right edge of display | Align all right edges to the rightmost layer |
| Align top | Move to top edge of display | Align all top edges to the topmost layer |
| Align vertical centers | Center vertically on display | Align all vertical centers to the shared center |
| Align bottom | Move to bottom edge of display | Align all bottom edges to the bottommost layer |
With multiple layers selected, alignment is relative to the bounding box of all selected layers, not the display. Each layer moves to match the corresponding edge or center of that combined bounds.
- Property fields — all editable properties for the selected layer type. Common fields:
| Field | Type | Layers |
|---|---|---|
| X, Y | Number | All positionable layers |
| W, H | Number | All sized layers |
| X1, Y1, X2, Y2 | Number | Line |
| Radius / RX / RY | Number | Circle, Ellipse |
| Radius / Start / End / Width | Number | Arc |
| Rotation / Start / End / Value | Number | Arc LVGL |
| Fill | Boolean | Rectangle, Circle, Ellipse, Triangle |
| Inverted (XOR) | Boolean | Most shape layers |
| Color / Fill / Back / Border | Color | Platform-dependent; text background is hidden or ignored on platforms that do not support it |
| Font | Font picker | Text, Text Area, Button, Checkbox |
| Text | String | Text, Text Area, Button, Checkbox |
| Checked | Boolean | Checkbox |
| Overlay | Boolean | Dims layer and skips it from code generation |
| Transparency | Boolean | RGB images with transparent pixels; keeps them see-through instead of the screen background |
For text layers on U8g2, Flipper, CircuitPython, and LVGL, the inspector also shows rotation buttons for 0°, 90°, 180°, and 270°. Rotation is clockwise, keeps the center of the layer bounds fixed, and is preserved in saved projects and generated code. The buttons are hidden on platforms without native text rotation support.
- Variable toggle (small switch next to numeric and color fields) — marks a property as a variable instead of a literal in the generated code.
- Actions — image operation buttons available on bitmap (Paint) layers:
- Flip horizontally — mirror the bitmap along the vertical axis.
- Flip vertically — mirror the bitmap along the horizontal axis.
- Rotate clockwise — rotate the bitmap 90° to the right.
- Invert colors — invert every pixel in the bitmap.
- Merge to Bitmap — renders all selected layers into a single bitmap (Paint) layer. The source layers are removed and replaced by one flat image the size of the full display. XOR/inverted layers are composited correctly during the merge.
- Delete — removes the selected layer(s).
Multiple layers selected
The inspector shows the count of selected layers, alignment buttons (for distributing relative to each other), the Merge to Bitmap button, and the Delete button.
If all selected layers belong to the same group, the group name is shown and can be renamed inline.
Code
The code panel sits at the bottom of the editor. For projects with multiple screens, select a screen’s tab to see its generated source code in real time.
The panel uses syntax highlighting for the active platform language (C, C++, YAML, etc.).
- Copy button — copies the full generated code to the clipboard, including any custom prefix and suffix you have written (see below).
- Import button — imports a source file into the open code tab’s screen on supported platforms. Works best with code that Lopaka itself generated.
Editable code template
The code panel is split into three zones separated by marker comments:
// [BEGIN lopaka generated]
… generated draw calls …
// [END lopaka generated]The prefix zone (above the BEGIN marker) and the suffix zone (below the END marker) are fully editable. Type any code you need there — #include directives, variable declarations, a setup() function, or anything else your sketch requires. The generated section in the middle is read-only and updates automatically as you edit layers.
Your prefix and suffix are saved locally in your browser per screen and restored on page reload. Switching code tabs loads the template that belongs to each screen.
Code settings
The code settings panel is to the right of the code panel. It controls how source code is generated.
Output toggles
Available toggles depend on the platform. The common ones are:
| Setting | Effect |
|---|---|
| Wrapper function | Wraps all draw calls in a named function |
| Comments | Emits a // layer name comment before each draw call |
| Include fonts | Outputs #include or font declarations |
| Declare images | Outputs bitmap array declarations |
| Declare variables | Extracts mutable layer properties into typed C variables |
| Clear/Fill display | Prepends a screen-clear call at the top of the function |
| Declare as PROGMEM | U8g2 only — places bitmap arrays in flash memory |
Syntax selector
On platforms with more than one code template, a Syntax dropdown appears above the toggles:
| Platform | Options |
|---|---|
| U8g2 | Arduino (Cpp), ESP-IDF (C) |
| AdafruitGFX Color, AdafruitGFX Mono, ArduinoGFX, TFT_eSPI | Arduino (C++), ESP-IDF (C++) |
The Arduino option is the default. The ESP-IDF options emit code you can drop into an ESP-IDF component: arrays are declared without PROGMEM, and no setup() / loop() (or app_main()) is generated, so you call the generated draw functions from your own task. Other platforms have a single template and show no dropdown.
Font and image downloads
When fonts or bitmap images are referenced by layers, download links appear at the bottom of the code settings panel. Click a font link to download the .h or .bdf file. Click an image link to download the bitmap as a .bmp or .h file depending on the platform.
Autosave
The editor saves your work automatically as you draw. Changes are persisted to the cloud every second after the last edit. There is no manual save button; closing the tab or navigating away is safe after the canvas is no longer changing.
If a save fails because the connection drops or the server is briefly busy, the editor retries it automatically for about a minute. If your changes still are not saved, a warning asks you to keep the tab open.
Panning and zooming are saved too, but they never make the browser ask you to confirm leaving the page.
Reopening a project while it saves
If you reopen a project while your previous changes are still being saved, the editor shows Saving your previous changes… and stays read-only. Once they are saved, the project shows them and you can edit.
- If saving them takes longer than 10 seconds, the editor opens the latest saved version and a warning says so. You can keep editing.
- If your previous changes finish saving after you have made new edits, a warning tells you. Reload the page to see them, or keep editing: saving a screen keeps your version of that screen.
- If the saved version cannot be loaded, the banner says the editor is retrying. After about a minute it stops and asks you to check your connection and click Try again. You can click Try again at any time.
Read-only / gallery mode
A public project opened from the Gallery is a read-only preview. You can browse its screens, zoom the preview, and copy each screen's code, but you cannot edit it. To edit the project, click Fork to save your own copy in My Projects; forking needs a free Lopaka account.