BambooBasic Logo


BGI Designer - Visual GUI Builder

The BGI Designer is a visual GUI builder built into the BambooBasic IDE. You lay out a dialog's gizmos (buttons, lists, menus and so on), set their properties and name their event handlers. The IDE then writes the handler functions and the code that calls them into your source file.



Starting a BGI Application

The designer works on a .bam file that has a design file next to it with the same name plus .bgi (for MyApp.bam that is MyApp.bam.bgi). The easiest way to get both is File > New > BGI Application: choose where to save, and the IDE creates the .bam with a ready-to-run main loop, creates an empty dialog in the .bam.bgi, and opens the designer.

A plain .bam without a .bam.bgi next to it has no designer view.



Switching Between Designer and Source

Each open file remembers which view it was in, so switching tabs puts a file back in the view you left it in.

The designer has three parts:



The Dialog

Every design is one dialog window. Click an empty part of the canvas to select it and set its Name, Title, Width, Height and onClose handler. A new BGI Application starts with a dialog named MyDialog whose onClose handler is OnMyDialog_Close.



Adding Gizmos
  1. Double-click a gizmo type in the Toolbox. It is added to the dialog with a default name.
  2. Drag it into place, or type exact values into the Properties panel.
  3. To remove a gizmo, select it and press Delete, or right-click it and choose Delete Control.

Gizmo types in the Toolbox:

Menus, tab controls, list view columns and toolbar buttons each have their own editor in the Properties panel. Menu items can have submenus.



Properties

All gizmos have:

Some types have more, for example Min/Max/Value for a Spinner, an image path for a PictureBox or BitmapButton, and font and colours for a RichTextBox.



Event Handlers

The Properties panel offers the handlers that make sense for the selected gizmo. Type a function name (for example OnSaveButton_Click) into one.

HandlerOffered forCalled when
onClickButton, BitmapButton, CheckBox, RadioButton, Link, Toolbar, PictureBox, menu itemsthe gizmo (or menu item) is clicked
onChangeTextBox, CheckBox, RadioButton, ListBox, ComboBox, Trackbar, Spinner, VScrollbar, HScrollbar, DatePicker, TimePicker, RichTextBox, ScrollPanelthe gizmo's value changes
onSelectListBox, ComboBox, TabControl, TreeView, ListViewan item is chosen (for a ListBox: double-clicked)
onClosethe dialogthe dialog's close button is pressed

When you switch back to Source View (or build), the IDE:

  1. adds a Function stub to your .bam for every handler that doesn't have one yet, and
  2. rewrites the dispatcher in the main loop so each handler name calls its function.

A function that already exists is left alone, so your code in it is never overwritten. If you delete a gizmo, its handler function is commented out under a ; UNUSED: Control was deleted from designer line rather than deleted.



The Generated Code

A BGI Application's main loop looks like this once the IDE has filled in the dispatcher:

Import "BBRuntime64.decls"

Global running:Int = True
Global gizmos:Int
Global window:Int

Function Main()
    ; Initialize BGI (Bamboo Gizmo Interface)
    bgiInitBGI("Arial", 16)

    ; Load gizmos from .bgi file
    gizmos = bgiLoadGizmos("MyApp.bam.bgi")

    ; Get handles to gizmo elements
    window = bgiGetGizmoHandle("MyDialog", gizmos)

    ; Main event loop
    While running
        sysUpdateEvents()

        ; Process gizmo events and dispatch to handlers (auto-generated)
        Local handler:String = bgiProcessGizmoEvents(gizmos)
        If handler <> ""
            If handler = "OnMyDialog_Close"
                OnMyDialog_Close()
            ElseIf handler = "OnSaveButton_Click"
                OnSaveButton_Click()
            ElseIf handler = "OnFiles_Select"
                OnFiles_Select()
            EndIf
        EndIf

        bgiFlushEvent()
        ; Small delay to prevent CPU spinning
        sysDelay(10)
    Wend

    ; Cleanup
    b2dEnd()

    Return False
EndFunction

bgiProcessGizmoEvents looks at the current event and returns the name of the handler set for it in the designer, or "" if there is none. bgiFlushEvent clears the event so it is handled only once.

The stubs it generates look like this:

; Event handler: OnMyDialog_Close
Function OnMyDialog_Close()
	running = False
EndFunction

; Event handler: OnSaveButton_Click
Function OnSaveButton_Click()
	Print "saveButton clicked"
	; TODO: Add button click logic here
EndFunction

; Event handler: OnFiles_Select
Function OnFiles_Select()
	Local handle:Int = bgiGetGizmoHandle("files", gizmos)
	Local selected:Int = bgiGetSelectedGizmoItem(handle)
	Print "files selection: {%selected}"
	; TODO: Add selection handler logic here
EndFunction


Saving

There is no separate save step for the design. The IDE writes it to the .bam.bgi file when you save the .bam, when you build, when you switch back to Source View and when you switch to another tab.

The .bam.bgi file is XML and has to be next to your program when it runs, because bgiLoadGizmos reads it at run time. Ship it with your .exe.



Handling Events Yourself

You don't have to use bgiProcessGizmoEvents. You can read the event directly, as non-designer BGI programs do:

Local saveButton:Int = bgiGetGizmoHandle("saveButton", gizmos)

While running
    sysUpdateEvents()

    Local msg:Int = bgiGetEventMessage()
    Local source:Int = bgiGetEventSource()

    If msg = 2 And source = saveButton    ; 2 = BGI_EVENT_COMMAND_CLICK
        Print "Save clicked"
    EndIf

    bgiFlushEvent()
    sysDelay(10)
Wend

The event constants (BGI_EVENT_COMMAND_CLICK and the rest) are defined in examples/BambooRuntime/BBR_INCLUDE.bam. For a menu item the event source is the window and bgiGetEventData() is the item's ID.



Tips

See Also

Back to Documentation Index