Skip to main content

Create simple GUIs using the Wofi application

Project description

A Python module to make simple GUIs using Wofi. (forked from the original python-rofi module)

What is Wofi?

Wofi is a launcher/menu program for wlroots based wayland compositors such as sway. Its basic operation is to display a list of options and let the user pick one. The following screenshot is shamelessly hotlinked from the wofi website (which you should probably visit if you want actual details about wofi!).

A screenshot of Wofi.

What is this module?

It simplifies making simple GUIs using Wofi. It provides a class with a number of methods for various GUI actions (show messages, pick one of these options, enter some text / a number). These are translated to the appropriate Wofi command line options, and then the standard subprocess module is used to run Wofi. Any output is then processed and returned to you to do whatever you like with.

Examples

Data entry

The simplest example is to create a Wofi instance and prompt the user to enter a piece of text:

from wofi import Wofi
r = Wofi()
name = r.text_entry('What is your name? ')

There are also entry methods for integers, floating-point numbers, and decimal numbers:

age = r.integer_entry('How old are you? ')
height = r.float_entry('How tall are you? ')
price = r.decimal_entry('How much are you willing to spend? ')

All of these return the corresponding Python type. Dates and times can also be requested:

dob = r.date_entry('What is your date of birth? ')
start = r.time_entry('When do you start work? ')
reminder = r.datetime_entry('When do you want to be alerted? ')

Again, these return the corresponding Python type. By default, they expect the user to enter something in the appropriate format for the current locale. You can override this by providing a list of format specifiers to any of these functions. The available specifiers are detailed in the Python documentation for the datetime module. For example:

start = r.time_entry('When do you start work? ', formats=['%H:%M'])

All of these entry methods are specialisations of the generic_entry() method. You can use this to create your own entry types. All you need to do is create a validator function which takes the text entered by the user, and returns either the Python object or an error message. For example, to enforce a minimum length on an entered piece of text:

validator = lambda s: (s, None) if len(s) > 6 else (None, "Too short!")
r.generic_entry('Enter a 7-character or longer string: ', validator)

Note that all of these methods return None if the dialog is cancelled.

Errors

To show an error message to the user:

r.error('I cannot let you do that.')
r.exit_with_error('I cannot let you do that.')

The latter shows the error message and then exits.

Selections

To give the user a list of things to select from, and return the index of the option they chose:

options = ['Red', 'Green', 'Blue', 'White', 'Silver', 'Black', 'Other']
index, key = r.select('What colour car do you drive?', options)

The returned key value tells you what key the user pressed. For Enter, the value is 0, while -1 indicates they cancelled the dialog. You can also specify custom key bindings:

index, key = r.select('What colour car do you drive?', options, key5=('Alt+n', "I don't drive"))

In this case, the returned key will be 5 if they press Alt+n.

Status

To display a status message to the user:

r.status("I'm working on that...")

This is the only non-blocking method (all the others wait for the user to finish before returning control to your script). To close the status message:

r.close()

Calling a display or entry method will also close any status message currently displayed.

Messages

Any of the entry methods and the select method have an optional argument message. This is a string which is displayed below the prompt. The string can contain Pango markup:

r.text_entry('What are your goals for this year? ', message='Be <b>bold</b>!')

If you need to escape a string to avoid it being mistaken for markup, use the Wofi.escape() class method:

msg = Wofi.escape('Format: <firstname> <lastname>')
r.text_entry('Enter your name: ', message=msg)

Customisation

There are a number of options available to customise the display. These can be set in the initialiser to apply to every dialog displayed, or you can pass them to any of the display methods to change just that dialog. See the Wofi documentation for full details of these parameters.

  • lines: The maximum number of lines to show before scrolling.

  • fixed_lines: Keep a fixed number of lines visible.

  • width: If positive but not more than 100, this is the percentage of the screen’s width the window takes up. If greater than 100, it is the width in pixels. If negative, it estimates the width required for the corresponding number of characters, i.e., -30 would set the width so approximately 30 characters per row would show.

  • fullscreen: If True, use the full height and width of the screen.

  • location: The position of the window on the screen.

  • You can also pass in arbitrary arguments to wofi through the wofi_args parameter. These have to be passed in as a list of strings, with every argument in a seperate string. For example, to make a selection case insensitive:

    r = Wofi()
    r.select('Choose one', ['option 1', 'option 2', 'option 3'],
        wofi_args=['-i'])

    or, to choose a different style for an instance of Wofi:

    r = Wofi(wofi_args=['-theme', 'path/to/theme.rasi'])
    r.status('Stuff is happening, please wait...')

Requirements

You need to have the wofi executable available on the system path (i.e., install Wofi!). Everything else that python-wofi needs is provided by the Python standard libraries.

What Python versions are supported?

It should work with any version of Python from 2.7 onwards. It may work with older versions, though no specific support for them will be added. It is developed on Python 2.7 and Python 3.6 – the latest versions of the Python 2 and 3 branches respectively.

What license does it use?

The MIT license, the same as python-wofi.

Bug reports

The project is developed on GitHub. Please file any bug reports or feature requests on the Issues page there.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python_wofi-0.3.1.tar.gz (13.5 kB view details)

Uploaded Source

Built Distribution

python_wofi-0.3.1-py3-none-any.whl (12.5 kB view details)

Uploaded Python 3

File details

Details for the file python_wofi-0.3.1.tar.gz.

File metadata

  • Download URL: python_wofi-0.3.1.tar.gz
  • Upload date:
  • Size: 13.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for python_wofi-0.3.1.tar.gz
Algorithm Hash digest
SHA256 dd1ae33d5009105be4eceee1900810eaa20d0b73af5b1e7133e9ee56a019890d
MD5 b8d0b7f67f21bb21c322a7dafaf77daf
BLAKE2b-256 63d0831e6b5c4ef6a0d72711a6571f9af430be36709f25f94f8e86cf063f440b

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_wofi-0.3.1.tar.gz:

Publisher: python-publish.yml on cristobaltapia/python-wofi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file python_wofi-0.3.1-py3-none-any.whl.

File metadata

  • Download URL: python_wofi-0.3.1-py3-none-any.whl
  • Upload date:
  • Size: 12.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for python_wofi-0.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ba5aac85ff97ca61c2bf9a4715d22c544a9a5a4c200b292043a583e85c0fbfc9
MD5 ae9fb1ca667975d543c57c9f3700fccc
BLAKE2b-256 7827bcbb4ebf412c296d54017c973015f1aa8ff9afc4df4d2f1974fd321aed31

See more details on using hashes here.

Provenance

The following attestation bundles were made for python_wofi-0.3.1-py3-none-any.whl:

Publisher: python-publish.yml on cristobaltapia/python-wofi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page