A collection of reusable widgets for Guigui, the Go GUI framework built on Ebitengine. The widgets are extracted from Zbolt and are meant to be dropped into any Guigui application.
Status: pre-1.0. Guigui itself is alpha, so expect the API of this module to change between releases. Pin a version in your
go.mod.Not supported yet: disabling a widget. See Known limitations.
go get github.com/Zbolt-org/widgetsimport "github.com/Zbolt-org/widgets"The module builds on github.com/guigui-gui/guigui and github.com/hajimehoshi/ebiten/v2. Both are pulled in through go.mod. See go.mod for the minimum Go version.
The gallery directory is a small application that shows every widget in one window. It is the quickest way to see what each widget looks like and how it is wired up, and its source is the reference for the examples in this README.
git clone https://github.com/Zbolt-org/widgets.git
cd widgets
go run ./galleryRun it from the repository root. The gallery loads its icons and sample image by relative path, so starting it from another directory will fail to find them.
The gallery contains:
- a toggle that switches between light and dark mode
- an icon, an info hint and an infinite loading bar
- an image wrapped in a skeleton loader, with a toggle that flips its loading state
- a text input with a context menu
- a button that adds tabs to a tab container, and a link
| Widget | Use it for |
|---|---|
LabeledToggle |
An on/off switch with a text label |
Button |
A button with an optional icon and tooltip |
TextInput |
A text field with a customizable context menu |
Link |
Clickable text that opens a URL |
Icon |
Showing an icon, optionally clickable |
InfoHint |
A small hint that explains something nearby |
Text |
A wrapper around basicwidget.Text |
SkeletonLoader |
A placeholder shown while content is loading |
InfiniteLoadingBar |
A loading bar for work of unknown duration |
TabContainer |
Closable, movable tabs, each with its own content |
LazyWidget |
A helper that creates a child widget on first use |
Icons and images are read from an fs.FS. The gallery passes nil and loads from disk relative to the working directory. In your own application, pass an fs.FS such as an embed.FS so the files travel with the binary.
A basicwidget.Toggle with a text label next to it.
Use it when you need a labeled boolean setting, for example "Follow redirects" or "Color mode".
SetLabel(label string)sets the text.Toggle()returns the underlying*basicwidget.Toggle. Use it to read or set the value and to subscribe to changes.
darkMode widgets.LabeledToggle
// in Build
r.darkMode.SetLabel("Color mode")
r.darkMode.Toggle().OnValueChanged(func(context *guigui.Context, value bool) {
// react to the new value
})A basicwidget.Button that can show an icon and a tooltip. Because it embeds basicwidget.Button, everything the basic button offers (SetText, OnDown, OnUp, and so on) is available too.
Use it when a button needs a picture or a hover explanation, for example an "add" button with a plus icon.
SetIcon(name string, fs fs.FS) errorsets the icon.SetTooltip(text string)sets the text shown when hovering the button.
addButton widgets.Button
// in Build
if err := r.addButton.SetIcon("icons/add.png", nil); err != nil {
return err
}
r.addButton.SetText("Add a new tab")
r.addButton.SetTooltip("Add a new tab to the tab container widget")
r.addButton.OnDown(func(context *guigui.Context) {
// handle the click
})A basicwidget.TextInput with a context menu (right click). The default entries are copy, paste, cut, select all, undo and redo. You can disable any of them and add your own. Because it embeds basicwidget.TextInput, the usual text input methods are available too.
Use it when you want a text field with a context menu you control, for example a request body editor that adds extra actions next to copy and paste.
SetIcon(name string, fs fs.FS) errorshows an icon in the input.SetDisable(item, disable)andDisable(item)turn a default menu entry off or report whether it is off. The items areContextMenuItemCopy,ContextMenuItemPaste,ContextMenuItemCut,ContextMenuItemSelectAll,ContextMenuItemUndoandContextMenuItemRedo.SetAditionalItems([]basicwidget.PopupMenuItem[int])adds your own entries to the menu, andOnAdditionalItemSelected(fn)is called with the index of the chosen one.SetTextContent(widgets.TextContent)andTextContent()set and read the kind of content the input holds:TextContentPlainText(the default) orTextContentHTML.
bodyInput widgets.TextInput
// in Build
if err := r.bodyInput.SetIcon("icons/input.png", nil); err != nil {
return err
}
r.bodyInput.SetDisable(widgets.ContextMenuItemCut, true)
r.bodyInput.SetAditionalItems([]basicwidget.PopupMenuItem[int]{
{Text: "Clear"},
})
r.bodyInput.OnAdditionalItemSelected(func(context *guigui.Context, index int) {
// index of the selected additional item
})Text that opens a URL when clicked. It embeds basicwidget.Text, so SetValue sets the visible text. When the visible text differs from the URL, a tooltip shows the URL on hover.
Use it when you want an inline link, such as a documentation or "learn more" link.
SetURL_Str(u string)sets the target from a string, andSetURL(u *url.URL) errorsets it from a parsed URL.SetBaseStyle(style *basicwidget.TextStyle)changes how the text is drawn.
docsLink widgets.Link
// in Build
r.docsLink.SetValue("Click here to open the link")
r.docsLink.SetURL_Str("https://example.com/docs")Warning: a
Linkcan also open file paths. Only pass URLs you trust, and be careful with values that come from user input or from remote content.
Draws an icon, and optionally reacts to clicks.
Use it when you need a standalone icon, for example a close icon in a toolbar, an icon in a form row, or a clickable icon button.
Load(icon string, fs fs.FS, size image.Point) errorloads the icon. The gallery passesnilandimage.Point{}for the last two arguments.SetClickable(bool)andClickable()control whether it reacts to the pointer, andOnClick(fn)registers the handler. A clickable icon also shows the pointer cursor.HasIcon()reports whether an icon is loaded, andSize(context)returns its size.
closeIcon widgets.Icon
// in Build
if err := r.closeIcon.Load("icons/close.png", nil, image.Point{}); err != nil {
return err
}
r.closeIcon.SetClickable(true)
r.closeIcon.OnClick(func(context *guigui.Context, icon *widgets.Icon) {
// handle the click
})A small information indicator that shows a hint text.
Use it when a setting or field needs a short explanation without taking up space on the screen, typically next to a label in a form.
SetText(text string)sets the hint text.
hint widgets.InfoHint
// in Build
r.hint.SetText("This is an information hint.")A widget that wraps a basicwidget.Text and exposes it through Text().
Use it when you want to place a text widget where a widgets widget is expected, and still configure the inner basicwidget.Text directly.
title widgets.Text
// in Build
r.title.Text().SetValue("Request headers")A generic wrapper, SkeletonLoader[T], that shows a loading placeholder in place of any Guigui widget T while it is loading.
Use it when content arrives asynchronously, such as an image, a response body or a list, and you want the layout to keep its shape while waiting.
SetLoading(bool)andLoading()control and report the loading state.Widget()returns the wrapped widgetT, which you configure as usual.
The loader has no intrinsic size, so give it one. The gallery wraps it in guigui.WidgetWithSize and sets a fixed width:
type Root struct {
guigui.DefaultWidget
picture guigui.WidgetWithSize[*widgets.SkeletonLoader[*basicwidget.Image]]
}
// in Build
r.picture.SetFixedWidth(basicwidget.UnitSize(context) * 8)
r.picture.Widget().Widget().SetImage(img) // configure the wrapped basicwidget.Image
r.picture.Widget().SetLoading(isLoading) // show or hide the placeholderr.picture.Widget() is the *SkeletonLoader, and r.picture.Widget().Widget() is the wrapped *basicwidget.Image.
A loading bar that animates continuously, with no progress value.
Use it when something is in progress and you cannot tell how long it will take, such as sending a request or waiting for a connection. It needs no configuration.
loadingBar widgets.InfiniteLoadingBar
// in Build: add it only while work is in progress
if r.busy {
adder.AddWidget(&r.loadingBar)
}A tab bar together with the content of the selected tab. Tabs can be closable and movable (drag to reorder), and each tab carries its own widget.
TabContainer[T] is generic over the type of the value attached to each tab, which must be comparable. Use struct{} when you do not need one, or something like a string or integer ID to identify tabs.
Use it when the user can open several documents or views at once, such as multiple requests in an API client.
A tab is described by a TabItem[T]:
| Field | Meaning |
|---|---|
Text |
The tab title |
Icon |
A TabIcon{Icon: "path", Fs: fsys} shown in the tab |
Closable |
Whether the tab has a close button |
Movable |
Whether the tab can be reordered |
Widget |
The content shown when the tab is selected |
Value |
A value of type T that you attach to the tab |
TabContainer does not own the list of tabs. You keep the slice, pass it with SetTabItems, and update it yourself in the callbacks:
OnTabClose(fn)is called when a tab is closed. Remove the tab from your slice.OnTabSwitch(fn)is called when two tabs swap places. Swap them in your slice.OnTabSelect(fn)is called when a tab is selected.SelectTabItem(index)selects a tab, andSelectedTabItem()returns the selected index and whether there is one.SetUnselectedWidget(widget)sets the widget shown when no tab is selected.
Give every tab its own widget instance. A widget can only live in one place in the tree.
type Root struct {
guigui.DefaultWidget
addButton widgets.Button
tabs widgets.TabContainer[struct{}]
tabItems []widgets.TabItem[struct{}]
tabCount int
}
// in Build
r.addButton.SetText("Add a new tab")
r.addButton.OnDown(func(context *guigui.Context) {
r.tabCount++
content := &basicwidget.Text{}
content.SetValue(fmt.Sprintf("Tab %d", r.tabCount))
r.tabItems = append(r.tabItems, widgets.TabItem[struct{}]{
Text: fmt.Sprintf("Tab %d", r.tabCount),
Icon: widgets.TabIcon{Icon: "icons/info-tip.png"},
Closable: true,
Movable: true,
Widget: content,
})
})
r.tabs.SetTabItems(r.tabItems)
r.tabs.OnTabClose(func(context *guigui.Context, index int, item widgets.TabItem[struct{}]) {
r.tabItems = slices.Delete(r.tabItems, index, index+1)
})
r.tabs.OnTabSwitch(func(context *guigui.Context, index1 int, item1 widgets.TabItem[struct{}], index2 int, item2 widgets.TabItem[struct{}]) {
r.tabItems[index1], r.tabItems[index2] = r.tabItems[index2], r.tabItems[index1]
})
adder.AddWidget(&r.tabs)The container usually takes the remaining space, so lay it out with a flexible size:
// in Layout
(guigui.LinearLayout{
Direction: guigui.LayoutDirectionVertical,
Items: []guigui.LinearLayoutItem{
{Widget: &r.addButton},
{Widget: &r.tabs, Size: guigui.FlexibleSize(1)},
},
}).LayoutWidgets(context, widgetBounds.Bounds(), layouter)LazyWidget[T] is a small generic helper that holds a child widget of type T and creates it the first time Widget() is called. It is useful when building your own wrapper widgets that need a child but should still work from their zero value.
type Wrapper struct {
guigui.DefaultWidget
inner widgets.LazyWidget[*basicwidget.Text]
}
// anywhere in Build or Layout
r.inner.Widget().SetValue("created on first use")The package also exports a few helpers for loading images from an fs.FS:
OpenImage(file_path string, fs fs.FS) (*ImageDetails, error)opens an image and returns an*ImageDetails.ImageDetailsholds the decoded*ebiten.Image(Img), extra data (Details) and aCacheflag.ChangeImageDetails(file_path string, fs fs.FS, details any) (ok bool)updates the details of an image.
See the package documentation for the full API.
Guigui lets you disable a widget with context.SetEnabled(&widget, false). The widgets in this module do not support this yet. A widget you disable this way may not look or behave as a disabled widget should, so do not rely on it to block input or to signal that a control is unavailable.
The behavior of disabling a widget may change in a future release, including how each widget looks and responds when disabled. If your application depends on it, check the release notes when you update and test the affected screens.
Until it is supported, you can keep a widget out of the user's way by not adding it in Build (a widget that is not added is not drawn or sent input), or by ignoring its events in your own callbacks.
TextInput.SetDisable and TextInput.Disable are a separate feature. They turn individual context menu entries on or off, not the whole widget.
Released under the BSD 3-Clause License.
lazy-widget.go is derived from code by The Guigui Authors and keeps its original Apache-2.0 notice.