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

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

---

🏗️ Architecture

┌──────────────────────────────────────────┐
│            Crystal (src/)                 │
│  Application · Window · Button · Label    │
│                  │                        │
│            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
• CheckBox, RadioButton
• Layout managers (Flow, Grid, Stack)
• ComboBox / DropDown
• File dialogs
• Menu bar & context menus
• 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}