Skip to content

Latest commit

 

History

History
220 lines (157 loc) · 6.52 KB

README.md

File metadata and controls

220 lines (157 loc) · 6.52 KB
Raw

QArgparse

image

Build settings-style graphical user interfaces with Python's argparse syntax.

import sys
from Qt import QtWidgets
from qargparse import QArgumentParser

app = QtWidgets.QApplication(sys.argv)

parser = QArgumentParser(description="My first graphical parser")
parser.add_argument("name", type=str, help="Your name")
parser.add_argument("age", type=int, help="Your age")
parser.add_argument("height", type=float, help="Your height")
parser.add_argument("alive", type=bool, help="Your state")
parser.show()

app.exec_()

Features

  • Automatic user interface for settings-style GUIs
  • Automatic tooltips from argument help=
  • Persistence to disk
  • Rich selection of types
  • Infer type from default value
  • Imperative and declarative mode
  • Tab-support for transitioning between arguments
  • Automatic label from name
  • Dual PEP8 and Qt syntax
  • Theme support
  • HDPI support
  • Min/max values for sliders
  • Wrap any instance of argparse.ArgumentParser with a GUI
  • Argument Icons, for extra flare
  • Argument Groups, e.g. tree view or side-panel

An example of use from within Maya.


Types

In addition to being able to subclass and create your own widgets, these are the ones included out-of-the-box.

Type Description Example
Boolean Checkbox for on/off state
Tristate Checkbox with 3 states
Integer Whole number
Float Fraction
Range Two numbers, a start and an end
String A single line of text
Text A multi-line segment of text
Info Read-only single line of text
Color An RGB or HSV color
Button A clickable button
Toggle A checkable button
Enum Multiple choice
Separator A visual separation between subsequent arguments
List Multiple string-values
Path A formatted string, with OS-specific file-browser
EnvironmentVariable A key/value string with limited character support
EnvironmentPath An os.pathsep-separated string
Color A color with visual swatch and hex, HSV and RGB support
Image A Path with thumbnail and restrictions on file extension

Install

Download or copy/paste qargparse.py into your project, there are no dependencies other than PyQt5 or PySide2.

# Test it from a command-line like this
$ python -m qargparse --demo

Usage

Use qargparse.QArgumentParser as you would argparse.ArgumentParser.

import sys
from Qt import QtWidgets
from qargparse import QArgumentParser

app = QtWidgets.QApplication(sys.argv)

parser = QArgumentParser(description="My first graphical parser")
parser.add_argument("name", type=str, help="Your name")
parser.add_argument("age", type=int, help="Your age")
parser.add_argument("height", type=float, help="Your height")
parser.add_argument("alive", type=bool, help="Your state")
parser.show()

app.exec_()

Or declaratively, using explicit types.

import qargparse
parser = qargparse.QArgumentParser([
    qargparse.String("name", help="Your name"),
    qargparse.Integer("age", help="Your age"),
    qargparse.Float("height", help="Your height"),
    qargparse.Boolean("alive", help="Your state"),
])

Types can also be inferred by their default value.

import qargparse
parser = qargparse.QArgumentParser()
parser.add_argument("name", default="My Name")  # `str` inferred
parser.add_argument("age", default=54)  # `int` inferred

Default and Initial Values

There are two seemingly similar values per argument.

Boolean("alive", default=True, initial=False)

What does this mean?

  1. False is the initial value displayed in the UI
  2. True is the value returned to when the value is reset

This way, you can store the current state of values elsewhere, such as on disk, and launch the UI with those values set, whilst still allowing the user to spot which values differs from their default values.

"Initial" is the value you would typically store on disk, keeping defaults as immutable somewhere in your application code.


Types

In addition to standard types, QArgparse also supports user interface types.

import qargparse
qargparse.Button("press me", help="See what happens!")

Camel and Snake

Consistency is important. Sometimes you work with a camel_case codebase, sometimes not. This library supports both, use the one which best suits your current codebase.

import qargparse
qargparse.addArgument()
qargparse.add_argument()

Style

Customise the user experience, with qargparse.DefaultStyle.

style = qargparse.DefaultStyle.copy()
style["comboboxFillWidth"] = True
parser = qargparse.QArgumentParser(style=style)
parser.show()


Signals

Respond to any change via the .changed signal.

import qargparse

def on_changed(argument):
    print("%s was changed!" % argument["name"])

args = [
    qargparse.Integer("age")
]

parser = qargparse.QArgumentParser(args)
parser.changed.connect(on_changed)

Or respond to individual changes.

import qargparse

def on_pressed():
    print("%s was changed!" % button["name"])

button = qargparse.Button("press me")
button.changed.connect(on_pressed)

parser = qargparse.QArgumentParser([button])