Mousetrap.jl: a GUI library for Julia and C++ that wraps GTK4

Mousetrap is a GUI library for Julia. It, and its stand-alone C++-component of the same name, fully wrap GTK4 (which is written in C), vastly simplifying its interface to improve ease-of-use without sacrificing flexibility.

It aims to give developers of all skill levels the tools to start creating complex GUI applications with little time and effort.

Note: Mousetrap is under active development. While backwards-compatibility for all future releases can already be guaranteed, stability, portability, and quality of the documentation may be affected.


Consider participating in the development by opening an issue when you encounter an error or bug (which – as of now – will most likely happen).

Table of Contents

0. Introduction
   
   
1. Features
   
   
2. Planned Features
   
   
3. Showcase
   
   
   3.1 Hello World
   
   
   3.2 Swapping between Light- and Dark Themes
   
   
   3.3 Opening a File Explorer Dialog
   
   
   3.4 Rendering a Rectangle using OpenGL
   
   
   3.5 Reacting to Mouse / Touchscreen Events
   
   
4. Supported Platforms
   
   
5. Installation
   
   
6. Documentation
   
   
7. Credits & Donations
   
   
8. Contributing
   
   
9. License
   
   

Features

• Create complex GUI application for Linux, Windows, and MacOS
• Choose from over 40 different kinds of pre-made widgets, or create your own!
• Supports mice, keyboards, touchscreens, touchpads, and stylus devices
• Image processing facilities, well-suited for image manipulation programs
• Fully abstracted OpenGL interface, allows for high-performance, hardware-accelerated rendering of custom shapes / shaders
• Hand-written manual and extensive documentation: every exported symbol is documented

Planned Features

Inn order of priority, highest first:

• Simplify installation process to ] add mousetrap
• Add support for global and per-widget custom themes by exposing the CSS interface
• Implement installation of .desktop files on end-user computers
• Implement drag-and-drop for files, images, and widgets
• Allow retrieving a widget from its container, for this to be possible the widgets type has to be stored C-side
• Allow filtering and searching of selectable widget containers such as ListView and ColumnView
• Allow adding custom signals that use the GLib marshalling system
• Allow bundling of mousetrap apps, their resources, and all their dependencies into a portable C-executable
• Fully polish interactive use from within the REPL
• Make all functions that modify the global state thread-safe
• Add an event controller to capture video game controller / joystick events
• Expose the full GtkTextView and GtkSourceView interface, making TextView a fully feature text editor
• Allow binding textures to fragment shader uniforms at texture unit 1 or higher, currently, only texture unit 0 is supported
• Add 3D shapes and geometry shaders

Showcase

Hello World

using mousetrap
main() do app::Application
    window = Window(app)
    set_child!(window, Label("Hello World!"))
    present!(window)
end

Swapping between Light- and Dark Themes

set_current_theme!(app, THEME_DEFAULT_LIGHT) 

Opening a File Explorer Dialog

file_chooser = FileChooser()
on_accept!(file_chooser) do self::FileChooser, files
    println("selected files: $files")
end
present!(file_chooser)

Rendering a Rectangle with OpenGL

render_area = RenderArea()
rectangle = Rectangle(Vector2f(-0.5, 0.5), Vector2f(1, 1))
add_render_task!(render_area, RenderTask(rectangle))

Reacting to Mouse / Touchscreen Presses

function on_click(::ClickEventController, x, y)
    println("Click registered at ($x, $y)") # in pixels
end

click_controller = ClickEventController()
connect_signal_clicked!(on_click, click_controller)
add_controller!(window, click_controller)

Click registered at (367.5, 289.0)

Supported Platforms

• MacOS support remains untested and may be unstable

Installation

In the Julia REPL, execute:

import Pkg
Pkg.add(url="https://github.com/Clemapfel/mousetrap_windows_jll")
Pkg.add(url="https://github.com/Clemapfel/mousetrap_linux_jll")
Pkg.add(url="https://github.com/Clemapfel/mousetrap_apple_jll")
Pkg.add(url="https://github.com/Clemapfel/mousetrap.jl")

Where all four packages need to be installed, regardless of the operating system.

Installation may take a long time. Once mousetrap is installed and precompilation is done, it can be loaded in only a few seconds during regular usage.

We can confirm everything works by pressing ] while in the REPL to enter Pkg mode, then:

At the end it should say mousetrap tests passed.

Note: On Windows, some GLib log messages regarding dbus connections and may appear during testing. These do not indicate a problem, as long as at the end of the testing suite it says mousetrap tests passed.

Documentation

Documentation is available here. This includes a tutorial on how to get started using mousetrap, a manual introducing users to mousetrap and GUI programming in general, as well as an index of all classes, enums, and functions.

Credits & Donations

The Julia and C++ component of mousetrap were designed and implemented by C.Cords.

Consider donating to support the continued development of this library:

• GitHub Sponsors
• PayPal

The goal is for mousetrap to be 100% stable and flawless when Julia static compilation finishes development. Static compilation and the lack of fully featured, easy-to-use GUI libraries are currently the largest factors as to why Julia is ill-suited for front-end development. Mousetrap aims to address this.

Contributing

Consider contributing by taking on one of these bounty projects:

• App Bundler
• Native Rendering on MacOS
• Cross-Platform Continuous Integration

I am unable to offer any monetary reward, but I’d be happy to credit you as a co-author of mousetrap on GitHub and as a Julia package author if your work contributes significantly to the implementation of one of these three bounty projects.

Other than this, consider participating in development by opening an issue if you encounter a bug, crash, or missing feature.

Thank you for your consideration.


C.

License

The current and all past version of mousetrap, including any text or assets used in mousetraps documentation, are licensed under GNU Lesser General Public License (Version 3.0). This means it can be used in both free, open-source, as well as commercial, closed-source software.