diff --git a/README.md b/README.md index 861cec0..4b8d4b9 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,8 @@ Gooey (Beta) Turn (almost) any Python Console Program into a GUI application with one line

- -

+ +

Table of Contents @@ -22,10 +22,12 @@ Table of Contents - [How does it work](#how-does-it-work) - [Internationalization](#internationalization) - [Configuration](#configuration) +- [Run Modes](#run-modes) - [Full/Advanced](#advanced) - [Basic](#basic) - [No Config](#no-config) -- [Final Screen](#final-screen) +- [Examples](#examples) +- [Screenshots](#screenshots) - [Change Log](#change-log) - [TODO](#todo) - [Contributing](#wanna-help) @@ -146,14 +148,14 @@ Gooey does its best to choose sensible defaults based on the options it finds. C | Parser Action | Widget | Example | |:----------------------|-----------|------| -| store | TextCtrl | | -| store_const | CheckBox | | -| store_true| CheckBox | | -| store_False | CheckBox| | -| append | TextCtrl | | -| count| DropDown                  | | -| Mutually Exclusive Group | RadioGroup | -|choice                                             | DropDown | | +| store | TextCtrl | | +| store_const | CheckBox | | +| store_true| CheckBox | | +| store_False | CheckBox| | +| append | TextCtrl | | +| count| DropDown                  | | +| Mutually Exclusive Group | RadioGroup | +|choice                                             | DropDown | | ###GooeyParser @@ -170,7 +172,7 @@ If the above defaults aren't cutting it, you can control the exact widget type b Given then above, Gooey would select a normal `TextField` as the widget type like this:

- +

However, by dropping in `GooeyParser` and supplying a `widget` name, you can display a much more user friendly `FileChooser` @@ -183,20 +185,20 @@ However, by dropping in `GooeyParser` and supplying a `widget` name, you can dis parser = GooeyParser(description="My Cool Gooey App!") parser.add_argument('filename', help="name of the file to process", widget='FileChooser') -

+

**Custom Widgets:** | Widget | Example | |----------------|------------------------------| -| Directory/FileChooser |

| -| DateChooser                                             |

| +| Directory/FileChooser |

| +| DateChooser                                             |

| Internationalization -------------------- - + Gooey is international ready and easily ported to your host language. Languages are controlled via an argument to the `Gooey` decorator. @@ -218,45 +220,57 @@ Want to add another one? Submit a [pull request!](https://github.com/chriskiehl/ +------------------------------------------- +Configuration +------------- - +Just about everything in Gooey can be customized by passing arguments to the decorator. -------------------------------------------- +| Parameter | Summary | +|-----------|---------| +| advanced | Toggles whether to show the 'full' configuration screen, or a simplified version | +| show_config | Skips the configuration all together and runs the program immediately | +| language | Tells Gooey which language set to load from the `gooey/languages` directory.| +|program_name | The name displayed in the title bar of the GUI window. If not supplied, the title defaults to the script name pulled from `sys.argv[0]`. | +| program_description | Sets the text displayed in the top panel of the `Settings` screen. Defaults to the description pulled from `ArgumentParser`. | +| default_size | Initial size of the window | +| required_cols | Controls how many columns are in the Required Arguments section | +| optional_cols | Controls how many columns are in the Optional Arguments section | +| dump_build_config | Saves a `json` copy of its build configuration on disk for reuse/editing | +Run Modes +--------- +Gooey has a handful of presentation modes so you can tailor its layout to your content type and user's level or experience. -Configuration ------------- -Gooey comes in three main flavors. -- Full/Advanced -- Basic -- No config -Each has the following options: +###Advanced -| Parameter | Summary | -|-----------|---------| -| language | Gooey is (kind of) international ready (sans Unicode issues (TODO)). All program text is stored in an external `json` file. Translating to your host language only requires filling in the key/value pairs.| -|program_name | The name displayed in the title bar of the GUI window. If the value is `None`, the title is pulled from `sys.argv[0]`. | -| program_description | Sets the text displayed in the top panel of the `Settings` screen. If `None` the description is pulled from the `ArgumentParser`. | +The default view is the "full" or "advanced" configuration screen. It has two different layouts depending on the type of command line interface it's wrapping. For most applications, the flat layout will be the one to go with, as its layout matches best to the familiar CLI schema of a primary command followed by many options (e.g. Curl, FFMPEG). +On the other side is the Column Layout. This one is best suited for CLIs that have multiple paths or are made up of multiple little tools each with their own arguments and options (think: git). It displays the primary paths along the left column, and their corresponding arguments in the right. This is a great way to package a lot of varied functionality into a single app. +

+ +

-###Advanced +Both views present each action in the `Argument Parser` as a unique GUI component. It makes it ideal for presenting the program to users which are unfamiliar with command line options and/or Console Programs in general. Help messages are displayed along side each component to make it as clear as possible which each widget does. +**Setting the layout style:** -The default view is the "full" or "advanced" configuration screen. It can be toggled via the `advanced` parameter in the `Gooey` decorator. +Currently, the layouts can't be explicitely specified via a parameter (on the TODO!). The layouts are built depending on whether or not there are `subparsers` used in your code base. So, if you want to trigger the `Column Layout`, you'll need to add a `subparser` to your `argparse` code. +It can be toggled via the `advanced` parameter in the `Gooey` decorator. @gooey(advanced=True) @@ -264,11 +278,6 @@ The default view is the "full" or "advanced" configuration screen. It can be tog # rest of code - -This view presents each action in the `Argument Parser` as a unique GUI component. This view is ideal for presenting the program to users which are unfamiliar with command line options and/or Console Programs in general. Help messages are displayed along side each component to make it as clear as possible which each widget does. -

- -

-------------------------------------------- @@ -283,7 +292,7 @@ The basic view is best for times when the user is familiar with Console Applicat # rest of code

- +

@@ -294,16 +303,36 @@ The basic view is best for times when the user is familiar with Console Applicat No Config pretty much does what you'd expect: it doesn't show a configuration screen. It hops right to the `display` section and begins execution of the host program. This is the one for improving the appearance of little one-off scripts.

- +

--------------------------------------- -Final Screen + +Examples +-------- + +Gooey comes with a bunch of example programs. Examples are located in the `examples` directory inside of the root `gooey` package. However, the easiest way to play with them is to import them into a python project and execute their `main` function. + + from gooey.examples import widget_demo + widget_demo.main() + +or + + from gooey.examples import subparser_demo + subparser_demo.main() + +>Note: The examples *must* be run from a Python file! Due to Gooey's file requirements, it won't work from the comman line. + + +Screenshots ------------ -

- -

+ +| Flat Layout | Column Layout |Success Screen | Error Screen | Warning Dialog | +|-------------|---------------|---------------|--------------|----------------| +| | | | | | + + ---------------------------------------------- @@ -311,24 +340,17 @@ Final Screen ###Change Log ---------- +- Subparser Support! - Moved all internal messaging to pubsub - expanded i18n converage - allowed returning to the main configuration screen - Fixed success checkmark showing on failure - Refactoring to beauty - - Removed parsing code, replaced it with @SylvainDe patch - Fixed issue #87 - Fixed issue #85 - Argparse no longer required to me in `main` (issue 84) - Drag and Drop support (`Issue #28`) - -

- -

- -Tada! - - Added drag and drop support - Added new widget packs: DateChooser, FileChooser, DirChooser - fixed several parsing related issues.