On this page

Introduction

The B9X Basic Screen Designer is a visual editor for laying out screens for the B9X display system. Instead of calculating every coordinate and writing every displayAdd... call by hand, you place elements visually, edit their properties, save the design, and copy the generated B9X Basic function to the Windows clipboard.

The supplied project supports both 320 × 480 portrait and 480 × 320 landscape layouts. Coordinates and sizes are stored in real display pixels; preview scaling is only a Windows editing convenience.

Beginner Quick Start

Screen Designer Interface

The top toolbar adds common elements and provides Duplicate, Delete, Copy B9X BASIC, Load, Save, Screen color, About, and the Portrait/Landscape control. A second toolbar row contains the newer sizeable controls. The third row provides Background BMP and Sample Color.

The left panel lists elements. The center is the hardware-screen preview. The right panel is the property inspector. Selecting an element makes its editable properties available.

Portrait & Landscape

Portrait is 320 × 480. Landscape is 480 × 320. Changing orientation also causes existing elements to be clamped inside the new screen boundaries. The generated function begins by calling displaySetOrientation(0) for portrait or displaySetOrientation(1) for landscape.

Complete Element Reference

Properties Reference

Moving, Resizing & Editing

Drag an element to move it. Drag the blue lower-right handle to resize sizeable elements. Icons and BMP images do not use the resize handle because their image dimensions are fixed by the asset itself. Arrow keys move the selected element by one display pixel; Shift + Arrow resizes by one display pixel.

For exact values, click the desired property row and type the value. The designer keeps elements inside the current screen dimensions.

Duplicate creates another element based on the selected item. Delete removes the selected item.

RGB565 Colors

Screen, text and background colors are stored as decimal RGB565 values from 0 through 65535. You can type a value directly or use the visual color picker. The Sample Color tool samples the rendered screen preview and displays the corresponding RGB565 decimal value so it can be copied.

BMP Images & Backgrounds

When adding an SD BMP or Background BMP, first choose the BMP file on Windows. The designer uses that file for preview. You then choose where the same filename will exist on the target: S for /sdcard/filename.bmp or P for /spiffs/filename.bmp.

Generated code uses displayAddBmpFromFile(number, x, y, path$, touchable). Normal BMP elements are generated touchable. A screen background is generated as reserved element 0 and is not touchable.

result = displayAddBmpFromFile(0, 0, 0, "/spiffs/background.bmp", 0);
result = displayAddBmpFromFile(PHOTO1, 20, 50, "/sdcard/photo.bmp", 1);

The selected BMP retains its real pixel dimensions. The local Windows path is stored in the project so the preview can be restored when the project is reopened.

Text, Passwords & Keyboard

A TextBox stores normal editable text. A Password TextBox uses the same basic idea but masks a filled caption in the designer preview. It generates displayAddPasswordTextBox(...).

Only one Keyboard is allowed on a screen. The designer always generates the keyboard after every other displayAdd call, regardless of its position in the element list. This keeps the keyboard above the other elements. Set Keyboard target to the element number of the text field it should edit.

result = displayAddTextBox(USERNAME1, 20, 60, 280, 42, "", 32, 2);
result = displayAddPasswordTextBox(PASSWORD1, 20, 120, 280, 42, "", 32, 2);
result = displayAddKeyboard(KEYBOARD1, PASSWORD1);

Element Numbers, Names & Start Number

Each element has both a designer number and a generated symbolic name. For example, a button may be named BUTTON1. The generated function declares that name before creating the screen.

The Start number is especially useful when an application contains several screens. The generated code declares START_NUM and then adds the designer number to it.

let START_NUM = 100;
let BUTTON1 = START_NUM + 1;
let LABEL1 = START_NUM + 2;

This lets screen designs remain simple while keeping their runtime element numbers unique.

Saving & Loading Designs

Save writes a .b9xscreen project. Load reopens it for editing. The project stores screen color, orientation, start number, element order, types, names, numbers, coordinates, sizes, captions, fonts, colors, values, ranges, checkbox state, icon number, keyboard target, BMP information and other applicable element properties.

Older projects without a Start number load with Start number 0. Unsupported element types are ignored, coordinates are clamped to the active screen, and the design is limited to 48 elements. If an older or manually edited project contains multiple keyboards, only the first is loaded.

Generated B9X Basic

Click Copy B9X BASIC to generate the screen function and copy it to the Windows clipboard. The generator sets orientation, removes existing elements, clears the screen, optionally draws a background BMP, creates each element, applies colors, creates the keyboard last, refreshes the display and returns 1.

// Typical generated structure
function mainScreen()
    let START_NUM = 100;
    let BUTTON1 = START_NUM + 1;
    let LABEL1 = START_NUM + 2;

    let result = displaySetOrientation(0);
    result = displayRemoveAllElements();
    result = displayClear(2089);
    result = displayAddButton(BUTTON1, 20, 184, 289, 49, "START", 3);
    result = displaySetColors(BUTTON1, 65535, 2089);
    result = displayAddLabel(LABEL1, 40, 5, 244, 29, "B9X Basic", 3, 65535);
    result = displaySetColors(LABEL1, 65535, 2089);
    result = displayRefresh();
    return 1;
end function

Complete Beginner Tutorial

Project: a simple control screen

This tutorial creates a screen with a title, status lamp, slider, rounded START button, editable name field and keyboard.

Controlling the Screen from B9X Basic

The designer creates the initial screen. Your running B9X Basic program can then change supported elements using the normal display API. The supplied project reference specifically shows these patterns for the newer controls:

// Move an analog meter needle or vertical bar
result = displaySetValue(METER1, 75);
result = displaySetValue(BAR1, 80);

// Select a list row (zero based)
result = displaySetValue(LISTBOX1, 2);

// Replace list choices
result = displaySetText(LISTBOX1, "Heat|Cool|Fan|Off");

// Turn a lamp or program-controlled switch on
result = displaySetChecked(LAMP1, 1);
result = displaySetChecked(SWITCH1, 1);

// Read a user-toggleable switch
state = displayGetChecked(TOGGLE1);

The project notes that a toggle switch queues checked/unchecked activity and a list box queues value-changed activity. Other touchable new elements can generate normal pressed, released and clicked messages.

Rules & Limits

Troubleshooting

Quick Reference

B9X Basic Screen Designer — Complete User Guide. Prepared from the supplied B9X_Basic_Screen_Designer_v2_25 project. Public user-facing behavior only.