federico-terzi / modulo

Basic Cross-platform GUI Toolkit for Any Language

modulo

A (very) basic Cross-platform GUI Toolkit for Any Language

Modulo is a simple, distributable binary that can be used to generate a variety of native GUI dialogs with ease:

macOS	Linux	Windows

Table of Contents

• Installation
  • Windows
  • macOS
  • Linux
• Getting Started
• Technology

Installation

modulo is still in its early days, so some of the details are work in progress.

Windows

espanso users

If you use modulo as part of espanso, it's shipped by default with it since version 0.7.0.

Prebuilt release

For Windows x64 systems, you can find the prebuilt modulo-win.exe in the Releases page.

While you can simply download it in your favourite location, if you use modulo as part of espanso you should:

• Rename the executable from modulo-win.exe to modulo.exe
• Move it to a persistent location, such as C:\modulo\modulo.exe
• Add that location (C:\modulo) to the PATH environment variable.

modulo also requires Visual C++ Redistributable 2019 to run.

Compile from source

To compile modulo on Windows, you need a recend Rust compiler, the MSVC C++ compiler and the LLVM compiler.

TODO

macOS

espanso users

If you use modulo as part of espanso and used Homebrew to install it, modulo is automatically included since version 0.7.0.

Prebuilt release

For x64 macOS systems, you can find the prebuilt modulo-mac in the Releases page.

While you can simply download it in your favourite location, if you use modulo as part of espanso you should:

• Rename the executable from modulo-mac to modulo
• Place it in /usr/local/bin

Compile from source

Compiling from source on macOS requires a few steps:

1. Download the wxWidgets source archive
2. Extract the content of the archive in a known directory, such as $USER/wxWidgets.
3. Open a terminal, cd into the wxWidgets directory and type the follwing commands:

mkdir build-cocoa
cd build-cocoa
../configure --disable-shared --enable-macosx_arch=x86_64
make -j6

4. Install LLVM using Homebrew with: brew install llvm

5. Now open the modulo project directory in the Terminal and compile with: WXMAC=$USER/wxWidgets cargo build --release

6. You will find the compiled binary in the target/release directory.

Linux

AppImage

On Linux the easiest way to use modulo is the offical AppImage, that you can find in the Releases page.

Compile from source

Compiling modulo is not too difficult, but requires many tools so it's highly suggested to use the AppImage instead. If you still want to compile it:

1. Install the wxWidgets development packages for you platform, the Clang compiler and the Rust compiler. On Ubuntu/Debian, they can be installed with: sudo apt install clang libwxgtk3.0-0v5 libwxgtk3.0-dev build-essential.

2. In the project directory run: cargo build --release.

3. You will find the compiled binary in the target/release directory.

Getting started

Creating a Form

There are a variety of built-in dialogs that can be customized by feeding modulo with YAML (or JSON) descriptors:

1. Create a form.yml file with the following content:

layout: |
  Hey {{name}},
  This form is built with modulo!

2. Invoke modulo with the command:

modulo form -i form.yml

3. The dialog will appear:

4. After clicking on Submit (or pressing CTRL+Enter), modulo will return to the STDOUT the values as JSON:

{"name":"John"}

This was a very simple example to get you started, but its only the tip of the iceberg!

Technology

Modulo is written in Rust and uses the wxWidgets GUI toolkit under the hoods. This allows modulo to use platform-specific controls that feel, look and behave much better than other solutions based on emulation (such as web-based technologies as Electron), with the additional benefit of a very small final size.

More info coming soon...

modulo's Issues

Add calendar view for date selection in forms

It would be awesome to implement the wxCalendarCtrl as a form option. I've been building some pretty complex forms for date selection that are good enough, but a calendar would be far superior.

For example:

matches:
  - trigger: ":select date"
    replace: "{{formatteddate}}"
    vars:
      - name: dates
        type: form
        params:
          layout: |
            {{days}}
          fields:
            days:
              type: list
              values:
                - Today
                - One week from Today
                - Monday
                - Tuesday
                - Wednesday
                - Thursday
                - Friday
                - Next Monday
                - Next Tuesday
                - Next Wednesday
                - Next Thursday
                - Next Friday
              default: "Today"
      - name: dateforward
        type: shell
        params:
          cmd: "echo `case $ESPANSO_DATES_DAYS in 'Monday') echo '-v +Mon' ;; 'Tuesday') echo '-v +Tue' ;; 'Wednesday') echo '-v +Wed' ;; 'Thursday') echo '-v +Thu' ;; 'Friday') echo '-v +Fri' ;; 'Next Monday') echo '-v +1w -v +Mon' ;; 'Next Tuesday') echo '-v +1w -v +Tue' ;; 'Next Wednesday') echo '-v +1w -v +Wed' ;; 'Next Thursday') echo '-v +1w -v +Thu' ;; 'Next Friday') echo '-v +1w -v +Fri' ;; 'Today') echo '' ;; 'One week from Today') echo '-v +7d'  ;; esac`"
      - name: newdate
        type: shell
        params:
          cmd: "echo `date $ESPANSO_DATEFORWARD +\"%A, %B %-d\"`"
      # Grabbing the ordinal date
      - name: day
        type: shell
        params:
          cmd: "echo `date $ESPANSO_DATEFORWARD +\"%-d\"`"
      - name: ordinal
        type: shell
        params:
          cmd: "case $ESPANSO_DAY in *1[0-9] | *[04-9]) echo th ;; *1) echo st ;; *2) echo nd ;; *3) echo rd ;; esac"
      - name: formatteddate
        type: shell
        params:
          cmd: "echo $ESPANSO_NEWDATE$ESPANSO_ORDINAL"

could be simplified to just:

matches:
  - trigger: ":selectdate"
    form: |
      {{selectdate}}
    form_fields:
      selectdate:
        type: calendar
          output_format: "%A, %B %-d"

Note I just realized my above example includes some tricky stuff for grabbing the ordinal date. I don't think that would necessarily be needed.

Installation problem on Linux Mint 21 / Ubuntu 22.04

Hello,

I installed modulo from https://github.com/federico-terzi/modulo/releases/tag/v0.1.1 on my Linux Mint 21 (Ubuntu 22.04 LTS).

I came from https://espanso.org/docs/legacy/install/linux/#installing-modulo and followed the guide there.

For installation, I did choose to install it only for my user and copied, linked the file into my $HOME/bin/ folder, which is in my path.

After installation I, I got this error:

➜  ~ modulo
modulo: symbol lookup error: /lib/x86_64-linux-gnu/libgio-2.0.so.0: undefined symbol: g_module_open_full

What do I need to install?
Cheers

Fix macOS wrong border color on darkmode

Add explanatory label to modulo forms

Modulo forms can be submitted by pressing CTRL+Enter, but this is not immediately clear (espanso/espanso#578)

Add a label in the bottom with "Or press CTRL+Enter to submit"

Open Forms and Search bar in the active desktop

Otherwise it gets confusing

Allow set another field's name as default value

Request for 1 enhancement feature as described in the title, below is the example use case:

layout: |
  Field1: {{field1}}, /n Field2: {{field2}}
fields:
  field2:
    default: {{field1}}

Not sure can it be done, hope I can help out, but I don't know Rust at the moment.

Million thanks to the plugin created, appreciate lots!!

Modulo/Forms should accept dynamic list/choice values.

Currently, Modulo only supports static lists in the config file.

What if we could have a new type or a subcategory of list/choice which gets lines from the output of a shell command or even source the list of values from the lines in a file?

Output something or show a GUI when invoking modulo without arguments

Mac: On user press esc, it still return layout's text

On user press esc, currently it still return the layout text.

I think it shouldn't output any text if user quit the form. The issue I met actually from espenso, form setup.

PKGBUILD for Arch/Manjaro

_pkgname=modulo
pkgname=${_pkgname}
pkgver=0.1.1
pkgrel=1
pkgdesc="A (very) basic Cross-platform GUI Toolkit for Any Language"
arch=(x86_64)
url="https://espanso.org/"
license=("GPL3")
depends=("wxgtk2")
makedepends=("rust" "git" "cmake" "wxgtk2" "wxgtk-common" "clang")
source=(""${_pkgname}::git+https://github.com/federico-terzi/${_pkgname}.git#tag=v${pkgver}"")
sha512sums=('SKIP')

check() {
    cd "$_pkgname"

    cargo test --release --locked
}

build() {
    cd "$_pkgname"

    cargo build --release
}

package() {
    cd "$_pkgname"

    install -Dm755 "target/release/${_pkgname}" "${pkgdir}/usr/bin/${_pkgname}"
}

`

Cannot handle CJK characters?

File encoding is UTF-8:

layout: |
  Hello 中文測試 {{name}},
  This form is built with modulo!

Chinese characters cause problem, even Hello cannot display on the form.

Create ROFI-like search feature

Does not expand symbols?

I added :em to expand to [email protected] but it expands to myemail2mycompany.com. Also :expanso expands to Hi there1

Ubuntu 18 with XMonad.

Also it does not work with xterm, only with gnome-terminal.
I did not install modulo

Does not run on Xubuntu 18.04

Thi @federico-terzi, thanks for making an AppImage. We'd like to add it to https://appimage.github.io/. However, it does not run on Xubuntu 18.04:

AppRun: /lib/x86_64-linux-gnu/libz.so.1: version `ZLIB_1.2.9' not found (required by /run/firejail/appimage/.appimage-9261/usr/bin/../lib/libpng16.so.16)

This is most likely because the binaries inside the AppImage were compiled on a "too new" system. Can you please build on the oldest still-supported distribution release, which currently is Ubuntu xenial? Thanks.

Reference:
AppImage/appimage.github.io#2287

How to set the window size?

Following your example, I successfully created a form, but it looks so small that I want to make it larger.
Is there any way to set the height and width for the window?

It doesn't work on xterm

It does work on gnome-terminal, pangoterm, and others, but not in xterm