iGac — macOS Port of GacUI

macOS implementation of GacUI using Cocoa and CoreGraphics/Quartz2D.

License

Read the LICENSE first.

Project Structure

iGac/
├── Mac/                        macOS platform implementation
│   ├── NativeWindow/OSX/       Cocoa windowing (controller, window, view, input)
│   │   ├── ServicesImpl/       Service implementations (screen, clipboard, dialog, ...)
│   │   └── CoreGraphics/       CoreGraphics app entry point
│   └── GraphicsElement/
│       └── CoreGraphics/       CoreGraphics rendering engine (renderers, layout, resource manager)
│
├── MacShared/                  Shared static libraries and test utilities
│   ├── CMakeLists.txt          Builds GacUI, GacOSX, GacOSXShared static libraries
│   ├── gac_include.h           Convenience header: includes GacUI, registers DarkSkin theme
│   ├── osx_shared.h/mm         OS X helpers (string conversion, file utils, resource folder)
│   └── UnixFileSystemInfo.*    Cross-platform file system utilities
│
├── MacTest/                    Simple test app (Hello World)
│   ├── CMakeLists.txt
│   └── HelloWorlds/Cpp/Main.cpp
│
├── MacFullControlTest/         Full-featured test app using BlackSkin control template
│   ├── CMakeLists.txt
│   ├── Main.mm
│   └── UI/FullControlTest/     Generated UI source files (copied by testFC_Update.sh)
│
├── Release/                    Git submodule: GacUI release imports, tools, tutorials
│   ├── Import/                 Amalgamated GacUI source files (Vlpp, GacUI, Workflow, ...)
│   ├── Tutorial/               Tutorial projects and resources
│   └── Tools/                  Build tools and scripts
│
├── doc/                        Documentation
│   ├── OSProvider.md           macOS OS provider: controller, services, entry point
│   ├── OSProvider_Window.md    macOS OS provider: INativeWindow, CocoaWindow, popups
│   ├── OSProvider_Graphics.md  macOS OS provider: CoreGraphics rendering, elements, fonts
│   ├── OSProvider_HostedMode.md macOS hosted mode: virtual windows, render lifecycle
│   └── lldb.md                 LLDB MCP server setup, debugging workflow
│
├── CMakeLists.txt              Root CMake config (project GacOSX, C++23)
├── build.sh                    Build script (incremental by default, --rebuild for clean)
├── test.sh                     Run MacTest Hello World app (--unblock for background)
├── testFC.sh                   Run MacFullControlTest app (--unblock for background)
└── testFC_Update.sh            Copy BlackSkin UI sources from Release/Tutorial to MacFullControlTest

Building

./build.sh              # Incremental build
./build.sh --rebuild    # Clean build (git clean -xdf + full rebuild)

Build output goes to build/. The build system uses CMake with C++23.

Static Libraries (built by MacShared/CMakeLists.txt)

• GacUI — Core GacUI amalgamated sources (Vlpp, VlppOS, VlppRegex, VlppReflection, VlppGlrParser, VlppWorkflowLibrary, GacUI, DarkSkin)
• GacOSX — All macOS platform code (Cocoa windowing, CoreGraphics rendering, services)
• GacOSXShared — Shared test helpers (osx_shared, UnixFileSystemInfo)

Code is compiled with VCZH_DEBUG_NO_REFLECTION. If reflection is needed, remove this define from MacShared/CMakeLists.txt and add all reflection .cpp files.

Running

./test.sh               # Run Hello World test
./test.sh --unblock     # Run in background, prints PID

./testFC.sh             # Run Full Control Test (BlackSkin)
./testFC.sh --hosted    # Run Full Control Test in hosted mode (single window)
./testFC.sh --unblock   # Run in background, prints PID

Updating MacFullControlTest Sources

./testFC_Update.sh

Copies generated UI source files from Release/Tutorial/GacUI_ControlTemplate/BlackSkin/ to MacFullControlTest/UI/, excluding reflection files. Also copies BlackSkin.bin resource.

Documentation

• doc/OSProvider.md — Controller, services, entry point, and overall architecture of the macOS platform layer.
• doc/OSProvider_Window.md — INativeWindow implementation (CocoaWindow): window lifecycle, Show/Hide, popups, child windows, custom frame, key differences from Windows.
• doc/OSProvider_Graphics.md — CoreGraphics rendering backend: render targets, element renderers, text layout, font management.
• doc/OSProvider_HostedMode.md — Hosted mode: single-window rendering, hosted controller, virtual windows, render target lifecycle.
• doc/lldb.md — LLDB MCP server setup, debugging workflow, graceful app termination.

TODO

• IGuiGraphicsParagraph
  • Need to test inserting image.
  • Test CocoaClipboardService when image is tested.

Known Issues

• VKEY mapping is quite big, should be shorter
• Not Implemented:
  • AsyncService::Semaphore::WaitForTime
  • CoreGraphicsResourceManager::CreateRawElement
  • CocoaInputService::(R|Unr)egisterGlobalShortcutKey
  • CocoaWindow::GetIcon and SetIcon

Upstream Issues

• FakeDialogService
  • File dialog shows empty local disk. The issue is in VlppOS, fix it and test here again.

Planning

• Replace CGLayer with Metal for rendering