Windows GUI Library (wui)

A pure Go library to create native Windows GUIs. This project is a modified and enhanced version of the original gonutz/wui library.

See the online documentation for API details.

Credits

This project is based on the excellent work by gonutz who created the original wui library. We've extended it with additional features and improvements while maintaining compatibility with the original API.

Original library: github.com/gonutz/wui

Self-contained

The former third-party packages are now part of this module, so there are no external dependencies and no network access is needed to build:

• github.com/2dprototype/wui/w32 (Win32 bindings, from gonutz/w32 v2, extended)
• github.com/2dprototype/wui/check (test helper, from gonutz/check)

New Controls

• GroupBox - captioned frame for visually grouping controls
• TabControl - tab headers with SetOnChange; show/hide Panels per tab (use ContentBounds() to place them)
• StatusBar - bottom status bar, optional multiple parts via SetParts / SetPartText
• Window.AddTimer(ms, f) - periodic Timer running on the GUI thread (Start, Stop, SetInterval)
• DatePicker - date / long date / time chooser with Value, SetValue, SetOnChange
• ColorDialog - system color chooser (SetColor, Execute(parent), Color)
• ClipboardText() / SetClipboardText(text) - read and write unicode text on the clipboard

Centering Windows

• window.SetCenterOnShow(true) - centers on the screen when shown with Show, and over the parent window when shown with ShowModal
• window.Center(), window.CenterOnScreen(), window.CenterOnParent() - center at any time

Examples

The examples folder has one small program for each new feature: group_box, tab_control, status_bar, timer, center_window, clipboard, color_dialog, date_picker, canvas_drawing, canvas_mouse, tree_view, context_menu, tooltip and toolbar. Run one with go run ./examples/timer.

Canvas Drawing (PaintBox)

New Canvas functions, all work inside PaintBox.SetOnPaint:

• Strokes: SetStroke(wui.Stroke{Width, Style, Cap, Join}), SetLineWidth, SetLineStyle - width, dash styles (LineDash, LineDot, ...), round/square/flat caps, round/bevel/miter joins. They apply to every outline function (Line, DrawRect, DrawEllipse, Polyline, Arc, DrawPie, ...)
• Shapes: DrawRoundRect, FillRoundRect, FillRoundRectOutline, FillRectOutline, FillEllipseOutline, DrawPolygon, FillPolygonOutline, Bezier, Curve (smooth curve through points), SetPixel, Pixel, DrawFocusRect
• Helpers: RegularPolygonPoints (triangle, hexagon, ...), StarPoints, Clear
• Fills: FillGradientH, FillGradientV, FillRectAlpha (transparent fill)
• Images: DrawImageScaled (stretch), DrawImageAlpha (transparency)
• Clipping: PushDrawEllipse, PushDrawRoundRect, PushDrawPolygon (undo with PopDrawRegion)
• State: Save() / Restore() for stroke, font and clip region
• Text: TextRectEllipsis (cuts long text with "...")
• Mouse: PaintBox.SetOnMouseDown, SetOnMouseUp, SetOnDoubleClick (with MouseButton); dragging keeps reporting SetOnMouseMove outside the box

More Controls and Features

• TreeView / TreeNode - hierarchical list (Add, Selected, SetOnSelect, SetOnDoubleClick, Expand, Collapse, ExpandAll, Remove, Tag)
• PopupMenu - context menus; Window.SetContextMenu(menu) and control.SetContextMenu(menu) open on right click, or call menu.Show(window, x, y)
• SetToolTip(text) - hover hint, available on every control
• ToolBar - NewToolBar(parent, x, y, height) with AddButton and AddSeparator

New examples: canvas_drawing, canvas_mouse, tree_view, context_menu, tooltip, toolbar.

Window Effects, Tray, Colors and Drag and Drop

• Drag and drop files: window.SetOnDropFiles(func(files []string, x, y int) {...}), and the same SetOnDropFiles on any control (the innermost control under the mouse gets the files)
• Colored text: SetTextColor(color) / SetBackgroundColor(color) (and ResetTextColor, ResetBackgroundColor) on Label, CheckBox, RadioButton, GroupBox, EditLine, TextEdit, ComboBox and the fill of a Panel. Check boxes, radio buttons and group boxes drop visual styles when a text color is set because themed controls ignore it
• System tray: NewTrayIcon() with SetToolTip, SetIcon, SetMenu(*PopupMenu), SetOnClick, SetOnDoubleClick, ShowBalloon(title, text, kind); attach it with window.SetTrayIcon(tray). window.SetMinimizeToTray(true), window.SetCloseToTray(true), HideToTray, RestoreFromTray, Quit. The icon comes back by itself when Explorer restarts
• Transparent window: SetAlpha(0..255) for opacity, SetTransparentColor(color) / SetTransparent(true) for a color key (pixels in that color are see-through and click-through)
• Headless window: SetHeadless(true) (no title bar and border) with SetDragByBackground(true) to move it, SetCornerRadius(px) for rounded corners
• More window options: SetTopMost, SetShowInTaskbar, SetMinSize, SetMaxSize

New examples: drag_drop, tray, colored_text, overlay_window.

Minimal Example

This is all the code you need to create a window (which does not do much):

package main

import "github.com/2dprototype/wui"

func main() {
	wui.NewWindow().Show()
}

The Designer

A graphical designer tool is included for visually creating GUIs. It is located at github.com/2dprototype/wui/cmd/designer.

Features

• Visual Layout: Drag and drop controls onto a window
• Property Editor: Modify control properties in real-time
• Live Preview: See your GUI as you build it
• Code Generation: Export designs as Go source code
• Project Management: Save and load designs as JSON project files
• Font Customization: Configure fonts for individual controls
• Event Handling: Define event handlers (OnPaint, etc.)
• Multiple Controls: Button, Label, CheckBox, RadioButton, Slider, ProgressBar, EditLine, TextEdit, ComboBox, Panel, PaintBox, IntUpDown, FloatUpDown, GroupBox, TabControl, DatePicker, StatusBar
• Full support for the new features: color pickers for text/background/key color, window options (transparency, headless via Has Border, corner radius, top most, taskbar, drag move, tray, drop files), OnClick and OnDropFiles event editors, copy / cut / paste / duplicate
• Responsive: works on small screens. The toolbox and the property panel hide automatically when the window is narrow (F2 / F3 toggle them, F4 goes back to automatic), both scroll with the mouse wheel, the preview pans with the wheel (Shift for sideways) and project files can be dropped onto the designer to open them

Keyboard Shortcuts

Shortcut	Action
Ctrl+N	New Project
Ctrl+O	Open Project (JSON)
Ctrl+S	Save Project (JSON)
Ctrl+Shift+S	Save Project As (JSON)
Ctrl+E	Export as Go Code
Ctrl+J	Export as JSON
F5	Run Preview
Del	Delete Selected Control
Ctrl+D	Duplicate selected control
Ctrl+C / Ctrl+X / Ctrl+V	Copy / cut / paste control
F2 / F3 / F4	Toggle toolbox / toggle properties / automatic layout
F1	About
Ctrl+F1	Keyboard Shortcuts Reference

Project File Format

Projects are saved as JSON files with the following structure:

{
  "windows": [
    {
      "name": "window",
      "type": "Window",
      "props": [
        {"name": "Title", "value": "My Window"},
        {"name": "InnerWidth", "value": 400},
        {"name": "InnerHeight", "value": 300}
      ],
      "font": {
        "name": "Tahoma",
        "height": -11,
        "bold": false,
        "italic": false,
        "underlined": false,
        "striked_out": false
      },
      "children": [
        {
          "name": "button1",
          "type": "Button",
          "props": [
            {"name": "Text", "value": "Click Me"},
            {"name": "X", "value": 10},
            {"name": "Y", "value": 10},
            {"name": "Width", "value": 100},
            {"name": "Height", "value": 25}
          ]
        }
      ]
    }
  ],
  "events": [
    {
      "control_name": "paintBox1",
      "event_name": "OnPaint",
      "code": "func(canvas *wui.Canvas) {\n\tcanvas.FillRect(0, 0, 100, 100, wui.RGB(255, 0, 0))\n}"
    }
  ]
}

WML: XML Layouts (package wml)

github.com/2dprototype/wui/wml loads window layouts from XML files at run time, similar to QML or XAML. The layout contains data only; events refer to Go functions by name.

<wml version="1">
  <Window Name="main" Title="Login" InnerSize="400,300">
    <EditLine Name="user" Bounds="80,10,300,22"/>
    <Button Text="Login" Bounds="300,260,90,26" OnClick="doLogin"/>
  </Window>
</wml>

type form struct {
	Window *wui.Window   `wml:"main"`
	User   *wui.EditLine `wml:"user"`
}

doc, err := wml.ParseFile("login.xml") // validated, with line and column in errors
var f form
_, err = doc.Build(&f, wml.Handlers{"doLogin": func() { println(f.User.Text()) }})
f.Window.Show()

See wml/README.md for the format reference. go run ./cmd/wmlcheck file.xml validates a layout without opening a window, and examples/wml_login is a complete program.

Installation

go get github.com/2dprototype/wui

Requirements

• Go 1.16 or later
• Windows operating system (uses native Windows API)

Changes from Original

This version includes several enhancements over the original gonutz/wui:

• JSON Project Files: Save and load complete GUI designs

License

This project maintains the same license as the original work. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

Acknowledgments

Special thanks to gonutz for creating the original wui library that made this project possible.

New in this version

Many controls and features were added (ListView, RichEdit, NativeToolBar, layouts, DPI awareness, Window.Invoke, ...). See docs/NEW_FEATURES.md and examples/showcase. That code has not been compiled yet, read the note there.