simple_gg - Cross-Platform SimpleGUI for V

simple_gg is a lightweight, beginner-friendly UI framework for building native, hardware-accelerated desktop applications in V. Built on top of V's native gg graphics module (powered by Sokol), simple_gg delivers smooth performance and uniform UI rendering across macOS, Linux, and Windowswithout relying on external C/Obj-C dependencies.

---

Visual Showcase & Snapshots of All Examples

Click to view remaining example screenshots (19 more)

---

Key Features

• Cross-Platform: Runs natively on macOS, Linux, and Windows with native OS drag-and-drop support.
• 87 Built-in Production Themes: The complete 76-theme Bun RAD Studio catalog plus SimpleGUI exclusives, with theme-specific surfaces, borders, secondary accents, and accessible button contrast.
• RAD Development Controls Suite: Multi-select Tag Input, Dual-Thumb Range Slider, Monospace Code Editor, File Drop Zone, Property Grid Inspector, Sparkline Micro-Charts, Pagination Bar, Resizable Split View, Toast Notification Overlay Stack, Command Palette (Ctrl+K), and Context Menus.
• Complete Widget Set: ListBox (interactive single/multi select), ComboBox, Transfer List, Console Output Viewer, Color Palette Swatch Grid, Status Bar, Step Slider, text/password inputs, steppers, range sliders, toggle switches, checkboxes, dropdowns, segmented controls, rating stars, date pickers, metric cards, charts, tree views, data tables, breadcrumbs, avatars, status badges, accordions, and alert banners.
• Layout Engine: Automatic vertical stacking, horizontal rows (begin_row), multi-column grids (begin_grid), flexboxes (begin_flex_box), tab containers, and group cards.
• Reactive State Management & Universal Persistence (state.v): Key-value reactive store (set_state, get_state), typed accessors, reactive state listeners (on_state_change), atomic crash-proof disk persistence (save_app_state, load_app_state), automated per-application form state restoration on launch, global theme auto-save, and window session restoration (save_window_session, restore_window_session).
• OS & System Extensions (sys.v): Standardized user directory lookups for macOS (~/Library), Windows (%APPDATA%), and Linux ($XDG_*), path expansion with tilde (~) and environment variable resolution, native notifications, hardware metrics, process execution, clipboard, and file operations.
• Headless Console & RAD Toolkit (simplecli): Full-featured zero-window CLI framework with flag parsing, ANSI colors, tables, interactive prompts, multi-level logging, process control, hardware probing, and cryptography.
• V Standard Library Integrations (stdlib.v): Built-in fluent helpers for HTTP requests, RegEx matching, Cryptography (SHA256, MD5, AES, Bcrypt), Gzip/Zlib/Zstd compression, TOML parsing, SemVer checks, and WebSockets.
• 30 Bundled Production Utility Modules (vlang_utils): Zero-boilerplate ergonomic toolkit ready to import anywhere (fileutils, sqliteutils, strutils, sliceutils, envutils, cryptoutils, timeutils, httputils, cliutils, sysutils, netutils, validutils, structutils, statutils, stateutils, cacheutils, semverutils, flowutils, templateutils, colorutils, archiveutils, asyncutils, regexutils, mockutils, logutils, tomlutils, htmlutils, bitutils, compressutils, tarutils). Full manual in UTILS_API.md.
• Beginner Friendly: Fluent chainable builder API with zero boilerplate.

---

📦 Installation & Module Setup

1. Install from GitHub (recommended for this repo)

This repository is currently published under the GitHub repo name simple_gg, but the V module you import is simplegui.

If you cloned the project manually, put it in your V module path so imports resolve correctly:

git clone https://github.com/codecaine-zz/simple_gg.git
mkdir -p ~/.vmodules
ln -s "$PWD/simple_gg/simplegui" ~/.vmodules/simplegui

Then run examples from the project directory or from any project that imports simplegui.

If the package is later published to VPM under a matching name, the standard v install ... flow will work as usual. For this repo today, linking the repository's simplegui/ directory at ~/.vmodules/simplegui is the reliable Linux/macOS workflow.

2. Install Homebrew dependencies (macOS)

For a default install on macOS, run the project’s bundled Homebrew installer:

./install_homebrew_dependencies.sh

This installs the required runtime tools used by the project and apps, such as FFmpeg, ImageMagick, jq, rg, pandoc, sqlite, nmap, and related toolchain utilities.

If you also want optional cross-compilation toolchains for Windows builds, install them explicitly:

./install_homebrew_dependencies.sh --optional

This adds zig and mingw-w64, which are only needed for Windows-targeted builds and are not required for the normal app runtime.

You can also install only the base bundle directly:

brew bundle --file ./Brewfile

3. Linux System Dependencies

On Linux (Debian / Ubuntu / Pop!_OS / Mint), ensure standard X11/GL development headers are present:

# The project dependency checker is cross-platform and will show Linux guidance:
v run install_dependencies.vsh --check

# Or install manually via apt:
sudo apt update
sudo apt install -y libx11-dev libxcursor-dev libxi-dev libgl1-mesa-dev libasound2-dev xclip

4. Naming & Import Convention

5. V Compiler Version & v up Maintenance

simple_gg is developed and validated against V 0.5.2 (commit 9e9f7f05 / V3 compiler backend). All 43 test suites, 30 GUI demos, 29 examples, 47 desktop workstations, and 49 CLI tools are tested and verified on this build.

⚠️ Caution with v up

Running v up directly pulls rolling changes from the V master branch, which can occasionally introduce compiler bootstrap issues or codegen regressions:

• cheaders.v / EmbedFileData Panic: If v up pulls a commit where embedded C headers are restructured before the bootstrap pre-built vc sources are synchronized, running v will fail with:

  V panic: EmbedFileData error: files ... cheaders.v do not exist
  

• Interface Dispatch Mismatches (json2, io.Reader): Upstream master changes can affect generic interface method dispatch parameter resolution (e.g., when streaming io.Reader in json2 encounters types with zero-parameter read methods).

🔄 How to Safely Rebuild / Recover V

If running v up leaves your V installation broken or unable to compile, restore it cleanly from bootstrap C code (vc):

cd /path/to/v

# 1. Fetch latest changes or pin to verified commit
git fetch origin
git checkout 9e9f7f05   # Verified working commit (or master)

# 2. Bootstrap from the official vc repository
git clone --depth 1 https://github.com/vlang/vc /tmp/vc
cc -std=gnu99 -w -o v /tmp/vc/v.c -lm -lpthread

# 3. Recompile V self-hosted
./v self

# 4. Clean out any obsolete fallback caches
rm -rf ~/.cache/v/v1-fallback

💡 Environment Flag (VFLAGS) Best Practice

On macOS with Homebrew, if you set library search paths via VFLAGS in ~/.zshrc or ~/.bashrc, specify -ldflags separately for each path to avoid argument-splitting failures during recursive sub-invocations (e.g. v test or v crun):

# ✅ Recommended (avoids nested quoting errors in subshells):
export VFLAGS="-ldflags -L/opt/homebrew/lib -ldflags -L/usr/local/lib"

# ❌ Avoid (inner quotes break argument tokenization in V child processes):
# export VFLAGS="-ldflags '-L/opt/homebrew/lib -L/usr/local/lib'"

---

Quick Start

module main

import simplegui

fn main() {
	mut win := simplegui.new_simple_window('My App', 520, 380)
	win.set_theme('Apple Dark')
	win.add_heading('SimpleGUI Starter')
	win.add_form_field('Name:', 'username', 'Ada Lovelace')
	win.add_checkbox('agree', 'I agree to the Terms', true)

	win.add_button('btn_save', 'Save')
	win.on_click('btn_save', fn (mut win simplegui.SimpleWindow) {
		println("User: ${win.get_text('username')}")
	})

	win.run()
}

---

Beginner-Friendly Examples & Snapshots

The repository includes beginner-friendly example programs in the examples/ directory:

---

simplecli - Headless Console & RAD Toolkit (Zero GUI Dependencies)

Need all the power of OS system calls, process management, hardware monitoring, desktop alerts, speech synthesis, standard paths, and stdlib crypto/HTTP without spinning up a graphical window? Use import simplecli!

module main

import simplecli

fn main() {
	mut app := simplecli.new_app('DeployCLI', '1.0.0')
	app.banner('DeployCLI Workspace', 'v1.0.0')

	// System metrics & paths
	cpu := app.get_cpu_info()
	ram := app.get_memory_info()
	app.print_kv({ 'CPU': cpu, 'RAM': ram })

	// Interactive RAD prompts & tables
	env := app.select('Target environment', ['dev', 'staging', 'prod'])
	app.success('Selected ${env}')

	// Desktop notification
	app.notify('Ready', 'DeployCLI initialized.')
}

See CLI_API.md for the complete SimpleCLI documentation and API reference.

---

💻 Production Console Applications Suite (cli_apps/ - 49 Utilities)

simple_gg includes 49 zero-window command-line applications and client versions of the GUI workstations in the cli_apps/ directory:

See the cli_apps/README.md for the complete catalog of all 49 command-line applications.

---

Production Workstations & Studio Applications (47 Workstations)

simple_gg includes 47 desktop applications in the applications/ directory, covering devtools, media studios, network utilities, data converters, and security workstations:

---

Security & Safe Execution Engine

simple_gg features a hardened system execution framework (simplegui/security.v) designed to prevent shell injection, command poisoning, and path traversal attacks across all platforms:

• POSIX Single-Quote Escaping (simplegui.quote_arg, simplegui.quote_path): Wraps and escapes user input safely, neutralizing quotes, semicolons, backticks, dollar signs, and redirection operators.
• Safe Subshell Execution (simplegui.exec_safe(tool, args)): Automatically quotes all arguments and executes binaries without vulnerability to command injection.
• Safe Stdin Pipe Execution (simplegui.exec_safe_stdin(tool, args, input_data)): Safely pipes arbitrary data over standard input without shell exposure.
• Filename Sanitization (simplegui.sanitize_filename(name)): Strips path separators (/, \), null bytes, and traversal tokens (..).

---

Documentation

• Full API Guide (GUI): See API.md for complete details on window configuration, controls, layout engine, themes, event callbacks, reactive state management (state.v), system calls (sys.v), and standard library extensions (stdlib.v).
• SimpleCLI Reference (Headless & Console): See CLI_API.md for complete details on the zero-window console utility framework, flag parsing, ANSI UI, interactive prompts, process management, hardware metrics, and stdlib utilities.
• 30 Utility Modules Reference (vlang_utils): See UTILS_API.md for complete documentation, function signatures, and beginner-friendly examples for all 30 utility modules.
• Workstations Catalog: See applications/README.md for the complete list & visual showcase of 47 desktop applications.
• Examples Guide: See examples/README.md for detailed descriptions of all example scripts.

---

Related GUI & RAD Desktop Projects

Explore sister projects and complementary GUI frameworks, templates, and RAD visual design suites:

Notable Open-Source Webview Frameworks

• pywebview - Lightweight, cross-platform native GUI window wrapper around OS webviews for Python applications by Roman Sirokov (r0x0r) and community.
• Neutralinojs - Portable, lightweight cross-platform desktop application development framework using web technologies and native webview by the Neutralinojs organization.