Quartz

A Windows Forms-inspired, cross-platform GUI toolkit for Crystal

---

✨ Overview

Quartz is a native, cross-platform GUI toolkit for the Crystal programming language. Its API is inspired by Windows Forms, making it instantly familiar to developers who have worked with desktop GUI frameworks before.

Quartz does not bundle a rendering engine or ship a UI library. Instead, it wraps each platform's native toolkit through a thin C bridge, giving you truly native look-and-feel on every OS — for free.

🧪 Tested On

Quartz has been verified to work on the following environments:

---

🚀 Quick Start

require "quartz"

Quartz::Application.run do |app|
  window = Quartz::Window.new("Hello, Quartz!", 400, 250)

  label = Quartz::Label.new("Welcome! 👋", x: 20, y: 20, width: 360, height: 30)
  window.add_control(label)

  button = Quartz::Button.new("Click Me", x: 20, y: 60, width: 120, height: 32)
  button.on_click { label.text = "Button clicked! 🎉" }
  window.add_control(button)

  window.show
end

---

📦 Installation

1. Add the dependency to your shard.yml:

   dependencies:
     quartz:
       github: umutuluer/quartz
   

2. Install with Shards:

   shards install
   

---

🔨 Building from Source

Quartz links against a compiled ext/quartz_helper.o object file. Use the provided Makefile to build it:

make          # auto-detects your platform (macOS / Linux / Windows)
make mac      # force macOS AppKit backend
make gtk      # force Linux GTK 3 backend
make qt       # force Linux Qt 5/6 backend (QT_VERSION=6 for Qt6)
make win      # force Windows Win32 backend
make clean    # remove build artifacts

Then compile your Crystal application as usual:

shards build

---

📖 API Reference

Application Lifecycle

Window

Button

Label

TextBox

ListBox

ComboBox

FileDialog

Abstract base for file dialogs. Concrete classes: OpenFileDialog, SaveFileDialog.

OpenFileDialog additionally has multiselect : Bool. SaveFileDialog additionally has overwrite_prompt : Bool (default true).

Multiselect MVP: only the first selected file is returned. Full Array(String)? API coming later.

StackLayout

Linear layout: vertical ya da horizontal stack. Saf Crystal sınıfıdır (Control'den türemez); çocukları add(control, width, height) ile ölçüleriyle birlikte ekler, relayout ile yeniden konumlandırır.

Vertical: çocuklar dikey; her biri parent_width - 2*padding kadar genişlikte. Horizontal: çocuklar yatay; her biri belirtilen width kadar, parent_height - 2*padding yüksekliğinde.

Not: Resize'da otomatik reflay henüz yok. Pencere yeniden boyutlandırılırsa layout.relayout manuel çağrılmalı. Hook altyapısı (Window#on_resize) bir sonraki sürümde eklenecek.

CheckBox

RadioButton

Radio buttons in the same window are mutually exclusive — selecting one automatically deselects others. Radio buttons in different windows are independent.

MenuBar / MenuItem / MenuSeparator / ContextMenu

MVP limitations:

• Submenu (nested menus) not supported — flat menubar only
• Shortcuts, checked items — out of MVP scope
• macOS menubar is app-global (last assigned wins); per-window future work
• Qt menubar requires QMainWindow promotion (separate backend task)

⚠️ Submenu support is OUT of the MVP — flat menubar only. A menubar currently holds a single level of items; nested/submenus require an extra C API (quartz_menu_item_set_submenu or similar) that is deferred to a later wave. MenuBar instances are designed to be reused as submenu containers once that lands.

macOS limitation: the menubar is app-global ([NSApp setMainMenu:]). With multiple windows the last window.menu_bar= wins. This matches the documented Wave-1b risk in MENU_PLAN.md.

Qt limitation: Qt menubar ataması, QMainWindow terfisi ayrı bir dalgada eklenecek. Context menu (sağ tık) Qt'de çalışır.

All controls inherit from Control, which provides the low-level handle and parent properties.

---

🧪 Examples

Run the included hello-world example:

make examples
./bin/hello_world

Example source: examples/hello_world.cr

Run the TextBox demo:

crystal build examples/textbox_example.cr -o bin/textbox_example
./bin/textbox_example

Example source: examples/textbox_example.cr

Run the ListBox demo:

crystal build examples/listbox_example.cr -o bin/listbox_example
./bin/listbox_example

Example source: examples/listbox_example.cr

Run the OpenFileDialog demo:

crystal build examples/openfiledialog_example.cr -o bin/openfiledialog_example
./bin/openfiledialog_example

Example source: examples/openfiledialog_example.cr

Run the SaveFileDialog demo:

crystal build examples/savefiledialog_example.cr -o bin/savefiledialog_example
./bin/savefiledialog_example

Example source: examples/savefiledialog_example.cr

Run the Layout demo:

crystal build examples/layout_example.cr -o bin/layout_example
./bin/layout_example

Example source: examples/layout_example.cr

Run the ComboBox demo:

crystal build examples/combobox_example.cr -o bin/combobox_example
./bin/combobox_example

Example source: examples/combobox_example.cr

Run the CheckBox demo:

crystal build examples/checkbox_example.cr -o bin/checkbox_example
./bin/checkbox_example

Example source: examples/checkbox_example.cr

Run the RadioButton demo:

crystal build examples/radiobutton_example.cr -o bin/radiobutton_example
./bin/radiobutton_example

Example source: examples/radiobutton_example.cr

Run the Menu demo:

crystal build examples/menu_example.cr -o bin/menu_example
./bin/menu_example

Example source: examples/menu_example.cr

---

🏗️ Architecture

┌──────────────────────────────────────────┐
│            Crystal (src/)                 │
│  Application · Window · Button · Label    │
│       TextBox · ListBox · ComboBox          │
│  CheckBox · FileDialog · RadioButton ·     │
│  MenuBar · MenuItem · MenuSeparator ·      │
│            ContextMenu                       │
│            StackLayout                       │
│                  │                        │
│            lib_quartz.cr                  │
│          (C bindings via @[Link])         │
└──────────────────┬───────────────────────┘
                   │  quartz_helper.h
┌──────────────────┴───────────────────────┐
│          C bridge (ext/)                  │
│  quartz_helper_mac.m  ──  AppKit         │
│  quartz_helper_gtk.c  ──  GTK 3          │
│  quartz_helper_qt.cpp ──  Qt 5/6         │
│  quartz_helper_win.c  ──  Win32 API      │
└──────────────────────────────────────────┘

---

🗺️ Roadmap

• macOS AppKit backend
• Linux GTK 3 backend
• Linux Qt 5/6 backend
• Windows Win32 backend
• TextBox / input controls
• ListBox
• CheckBox, RadioButton
• ComboBox / DropDown
• File dialogs
• Layout managers — Stack MVP
• Layout managers (Flow, Grid)
• Menu bar & context menus (C layer: AppKit/GTK/Win32/Qt items + context menus; Qt menubar attach deferred — QMainWindow promotion. Submenus out of MVP.)
• Comprehensive test suite

---

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Open a Pull Request

Please make sure your code follows the existing style and includes appropriate specs.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

👤 Author

Umut ULUER — @umutuluer

---

_{Built with ❤️ and Crystal}

Testing

Quartz ships with 259 deterministic spec examples that run in under 500ms across 4 native backends.

make spec          # run the full suite (default backend: mac/AppKit)
make lint          # ameba static analysis
make format        # crystal tool format --check
make examples      # build the 10 example programs

The test suite covers:

• Crystal-level coverage — every public method on every widget
• Native callback routing — C-level trampoline helpers fire real callbacks through the 4 backends' callback tables
• Lifecycle — show/close, multi-window ID uniqueness, re-parenting, queryability after operations
• Edge cases — Unicode (emoji 🚀, RTL عربية, ZWJ 👨‍👩‍👧), 10k-char strings, zero/negative dimensions, empty strings
• Geometry — StackLayout pixel-position asserts via quartz_widget_get_bounds
• Modal dialogs — OpenFileDialog/SaveFileDialog mocked through a C-level seam (quartz_test_dialog_set_mode + QUARTZ_TEST_DIALOG_PATH)

CI matrix runs the full suite on all 4 backends: macOS/AppKit, Linux/GTK3 (under xvfb), Linux/Qt5 (offscreen QPA), Windows/Win32.

Spec files live under spec/ (unit specs in spec/unit/, helpers in spec/support/). The C-level test helpers (quartz_test_fire_*, quartz_widget_get_bounds, quartz_test_dialog_set_mode) are declared in ext/quartz_helper.h and implemented in all 4 backends.