Mousetrap

Mousetrap is a GUI library designed for Julia. It fully wraps 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, while taking full advantage of Julias idiosyncrasies.

Note: Mousetrap is under active development. Consider participating in the development by opening an issue when you encounter an error, bug, question, or missing feature.

Note: February 8th, 2024: I've been having some health issues at the moment, it may take me some time to get to open issues. Mousetrap is still usable and (mostly) stable, the repo will be maintained in the immediate future to the best of my abilities. Thank you for your understanding, C.

---

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 Displaying a GLMakie Plot in a Mousetrap Window
   
4. Supported Platforms
   
5. Documentation
   
6. Installation
   
7. Credits & Donations
   
8. 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
• Built using OpenGL, allowing for high-performance, hardware-accelerated rendering, and integration of other OpenGL-based libraries such as GLMakie
• Hand-written manual and extensive documentation: every exported symbol is documented

---

Planned Features

In order of priority, highest first:

• Allow bundling of Mousetrap apps using PackageCompiler.jl
• Implement installation of .desktop files on end-user computers
• Implement drag-and-drop for files, images, and widgets
• Allow filtering and searching of selectable widget containers such as ListView and ColumnView
• Allow adding custom signals that use the GLib marshalling system
• Make all functions that modify the global state thread-safe

---

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))

---

Displaying a GLMakie Plot in a Mousetrap Window

using GLMakie, MousetrapMakie
canvas = GLMakieArea()
window = Mousetrap.Window()
set_child!(window, canvas) # can be used like any other widget

screen = create_glmakie_screen(canvas)
display(screen, scatter(rand(123)))

(Note: This feature is still experimental. See here for more information)

---

Supported Platforms

Since v0.3.0, Mousetrap is fully portable. All features are available for all 64-bit versions of Linux, FreeBSD, macOS, and Windows.

Note: Linux systems running Wayland may require additional configuration before the RenderArea widget becomes available. See here for more information.

Note: Ubuntu systems using proprietary NVIDIA drivers may encounter a crash on initialization, a fix is available here.

---

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.

---

Installation

In the Julia REPL, execute:

import Pkg;
begin
    Pkg.add(url="https://github.com/clemapfel/mousetrap.jl")
    Pkg.test("Mousetrap")
end

At the end, it should say Mousetrap tests passed.

Note: On Windows, some GLib log messages regarding dbus connections may appear during testing. These do not indicate a problem.

Note: On Linux Wayland, a warning regarding EGL displays may appear during installation. See the here for how to fix this issue.

---

If you have had Mousetrap version 0.3.0 or earlier installed on your device before, run the following before installing the current version of Mousetrap:

import Pkg
begin
    try Pkg.rm("mousetrap") catch end
    try Pkg.rm("mousetrap_windows_jll") catch end
    try Pkg.rm("mousetrap_linux_jll") catch end
    try Pkg.rm("mousetrap_apple_jll") catch end
    try Pkg.rm("libmousetrap_jll") catch end
    Pkg.gc()
end

This will remove any trace of older versions that may cause conflicts.

---

Credits & Donations

Mousetrap was designed and implemented by C.Cords.

It was created with no expectation of compensation and made available for free. Consider donating to reward past work and 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.

---

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.