You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

590 lines
29 KiB

10 years ago
7 years ago
11 years ago
10 years ago
9 years ago
7 years ago
10 years ago
10 years ago
10 years ago
9 years ago
10 years ago
9 years ago
6 years ago
6 years ago
9 years ago
10 years ago
6 years ago
6 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
7 years ago
10 years ago
7 years ago
10 years ago
9 years ago
10 years ago
9 years ago
10 years ago
10 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
9 years ago
10 years ago
9 years ago
10 years ago
9 years ago
10 years ago
9 years ago
10 years ago
10 years ago
10 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
9 years ago
10 years ago
10 years ago
10 years ago
9 years ago
10 years ago
10 years ago
9 years ago
10 years ago
10 years ago
10 years ago
9 years ago
10 years ago
7 years ago
7 years ago
10 years ago
10 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
6 years ago
9 years ago
6 years ago
9 years ago
6 years ago
9 years ago
9 years ago
6 years ago
9 years ago
6 years ago
9 years ago
6 years ago
6 years ago
6 years ago
6 years ago
10 years ago
9 years ago
9 years ago
10 years ago
10 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
10 years ago
10 years ago
10 years ago
9 years ago
10 years ago
10 years ago
10 years ago
9 years ago
10 years ago
6 years ago
6 years ago
6 years ago
6 years ago
10 years ago
9 years ago
9 years ago
9 years ago
9 years ago
9 years ago
10 years ago
9 years ago
6 years ago
9 years ago
10 years ago
6 years ago
10 years ago
10 years ago
9 years ago
  1. Gooey (Beta)
  2. =====
  3. Turn (almost) any Python 2 or 3 Console Program into a GUI application with one line
  4. <p align="center">
  5. <img src="https://cloud.githubusercontent.com/assets/1408720/7904381/f54f97f6-07c5-11e5-9bcb-c3c102920769.png" />
  6. </p>
  7. # Gooey now supports Python 3!!
  8. Table of Contents
  9. -----------------
  10. - [Gooey](#gooey)
  11. - [Table of contents](#table-of-contents)
  12. - [Latest Update](#latest-update)
  13. - [Quick Start](#quick-start)
  14. - [Installation Instructions](#installation-instructions)
  15. - [Usage](#usage)
  16. - [Examples](#examples)
  17. - [What It Is](#what-is-it)
  18. - [Why Is It](#why)
  19. - [Who is this for](#who-is-this-for)
  20. - [How does it work](#how-does-it-work)
  21. - [Internationalization](#internationalization)
  22. - [Global Configuration](#global-configuration)
  23. - [Layout Customization](#layout-customization)
  24. - [Run Modes](#run-modes)
  25. - [Full/Advanced](#advanced)
  26. - [Basic](#basic)
  27. - [No Config](#no-config)
  28. - [Input Validation](#input-validation)
  29. - [Using Dynamic Values](#using-dynamic-values)
  30. - [Customizing Icons](#customizing-icons)
  31. - [Packaging](#packaging)
  32. - [Screenshots](#screenshots)
  33. - [Contributing](#wanna-help)
  34. - [Image Credits](#image-credits)
  35. ----------------
  36. ## Quick Start
  37. ### Installation instructions
  38. The easiest way to install Gooey is via `pip`
  39. pip install Gooey
  40. Alternatively, you can install Gooey by cloning the project to your local directory
  41. git clone https://github.com/chriskiehl/Gooey.git
  42. run `setup.py`
  43. python setup.py install
  44. **NOTE:** Python 2 users must manually install WxPython! Unfortunately, this cannot be done as part of the pip installation and should be manually downloaded from the [wxPython website](http://www.wxpython.org/download.php).
  45. ### Usage
  46. Gooey is attached to your code via a simple decorator on whichever method has your `argparse` declarations (usually `main`).
  47. from gooey import Gooey
  48. @Gooey <--- all it takes! :)
  49. def main():
  50. parser = ArgumentParser(...)
  51. # rest of code
  52. Different styling and functionality can be configured by passing arguments into the decorator.
  53. # options
  54. @Gooey(advanced=Boolean, # toggle whether to show advanced config or not
  55. language=language_string, # Translations configurable via json
  56. show_config=True, # skip config screens all together
  57. target=executable_cmd, # Explicitly set the subprocess executable arguments
  58. program_name='name', # Defaults to script name
  59. program_description, # Defaults to ArgParse Description
  60. default_size=(610, 530), # starting size of the GUI
  61. required_cols=1, # number of columns in the "Required" section
  62. optional_cols=2, # number of columbs in the "Optional" section
  63. dump_build_config=False, # Dump the JSON Gooey uses to configure itself
  64. load_build_config=None, # Loads a JSON Gooey-generated configuration
  65. monospace_display=False) # Uses a mono-spaced font in the output screen
  66. )
  67. def main():
  68. parser = ArgumentParser(...)
  69. # rest of code
  70. See: [How does it Work](#how-does-it-work) section for details on each option.
  71. Gooey will do its best to choose sensible widget defaults to display in the GUI. However, if more fine tuning is desired, you can use the drop-in replacement `GooeyParser` in place of `ArgumentParser`. This lets you control which widget displays in the GUI. See: [GooeyParser](#gooeyparser)
  72. from gooey import Gooey, GooeyParser
  73. @Gooey
  74. def main():
  75. parser = GooeyParser(description="My Cool GUI Program!")
  76. parser.add_argument('Filename', widget="FileChooser")
  77. parser.add_argument('Date', widget="DateChooser")
  78. ...
  79. ### Examples
  80. Gooey downloaded and installed? Great! Wanna see it in action? Head over the the [Examples Repository](https://github.com/chriskiehl/GooeyExamples) to download a few ready-to-go example scripts. They'll give you a quick tour of all Gooey's various layouts, widgets, and features.
  81. [Direct Download](https://github.com/chriskiehl/GooeyExamples/archive/master.zip)
  82. What is it?
  83. -----------
  84. Gooey converts your Console Applications into end-user-friendly GUI applications. It lets you focus on building robust, configurable programs in a familiar way, all without having to worry about how it will be presented to and interacted with by your average user.
  85. Why?
  86. ---
  87. Because as much as we love the command prompt, the rest of the world looks at it like an ugly relic from the early '80s. On top of that, more often than not programs need to do more than just one thing, and that means giving options, which previously meant either building a GUI, or trying to explain how to supply arguments to a Console Application. Gooey was made to (hopefully) solve those problems. It makes programs easy to use, and pretty to look at!
  88. Who is this for?
  89. ----------------
  90. If you're building utilities for yourself, other programmers, or something which produces a result that you want to capture and pipe over to another console application (e.g. *nix philosophy utils), Gooey probably isn't the tool for you. However, if you're building 'run and done,' around-the-office-style scripts, things that shovel bits from point A to point B, or simply something that's targeted at a non-programmer, Gooey is the perfect tool for the job. It lets you build as complex of an application as your heart desires all while getting the GUI side for free.
  91. How does it work?
  92. -----------------
  93. Gooey is attached to your code via a simple decorator on whichever method has your `argparse` declarations.
  94. @Gooey
  95. def my_run_func():
  96. parser = ArgumentParser(...)
  97. # rest of code
  98. At run-time, it parses your Python script for all references to `ArgumentParser`. (The older `optparse` is currently not supported.) These references are then extracted, assigned a `component type` based on the `'action'` they provide, and finally used to assemble the GUI.
  99. #### Mappings:
  100. Gooey does its best to choose sensible defaults based on the options it finds. Currently, `ArgumentParser._actions` are mapped to the following `WX` components.
  101. | Parser Action | Widget | Example |
  102. |:----------------------|-----------|------|
  103. | store | TextCtrl | <img src="https://cloud.githubusercontent.com/assets/1408720/7904380/f54e9f5e-07c5-11e5-86e5-82f011c538cf.png"/>|
  104. | store_const | CheckBox | <img src="https://cloud.githubusercontent.com/assets/1408720/7904367/f538c850-07c5-11e5-8cbe-864badfa54a9.png"/>|
  105. | store_true| CheckBox | <img src="https://cloud.githubusercontent.com/assets/1408720/7904367/f538c850-07c5-11e5-8cbe-864badfa54a9.png"/>|
  106. | store_False | CheckBox| <img src="https://cloud.githubusercontent.com/assets/1408720/7904367/f538c850-07c5-11e5-8cbe-864badfa54a9.png"/> |
  107. | append | TextCtrl | <img src="https://cloud.githubusercontent.com/assets/1408720/7904380/f54e9f5e-07c5-11e5-86e5-82f011c538cf.png"/> |
  108. | count| DropDown &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | <img src="https://cloud.githubusercontent.com/assets/1408720/7904371/f53ccbe4-07c5-11e5-80e5-510e2aa22922.png"/> |
  109. | Mutually Exclusive Group | RadioGroup | <img src="https://cloud.githubusercontent.com/assets/1408720/7904383/f553feb8-07c5-11e5-9d5b-eaa4772075a9.png"/>
  110. |choice &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;| DropDown | <img src="https://cloud.githubusercontent.com/assets/1408720/7904379/f54e4da6-07c5-11e5-9e66-d8e6d7f18ac6.png"/> |
  111. ### GooeyParser
  112. If the above defaults aren't cutting it, you can control the exact widget type by using the drop-in `ArgumentParser` replacement `GooeyParser`. This gives you the additional keyword argument `widget`, to which you can supply the name of the component you want to display. Best part? You don't have to change any of your `argparse` code to use it. Drop it in, and you're good to go.
  113. **Example:**
  114. from argparse import ArgumentParser
  115. ....
  116. def main():
  117. parser = ArgumentParser(description="My Cool Gooey App!")
  118. parser.add_argument('filename', help="name of the file to process")
  119. Given then above, Gooey would select a normal `TextField` as the widget type like this:
  120. <p align="center">
  121. <img src="https://cloud.githubusercontent.com/assets/1408720/7904368/f5393e20-07c5-11e5-88e9-c153fc3ecfaa.PNG">
  122. </p>
  123. However, by dropping in `GooeyParser` and supplying a `widget` name, you can display a much more user friendly `FileChooser`
  124. from gooey import GooeyParser
  125. ....
  126. def main():
  127. parser = GooeyParser(description="My Cool Gooey App!")
  128. parser.add_argument('filename', help="name of the file to process", widget='FileChooser')
  129. <p align="center"><img src="https://cloud.githubusercontent.com/assets/1408720/7904370/f53ae23e-07c5-11e5-8757-c8aa6f3013b5.PNG"></p>
  130. **Custom Widgets:**
  131. | Widget | Example |
  132. |----------------|------------------------------|
  133. | DirChooser/FileChooser/MultiFileChooser | <p align="center"><img src="https://cloud.githubusercontent.com/assets/1408720/7904377/f5483b28-07c5-11e5-9d01-1935635fc22d.gif" width="400"></p> |
  134. | DateChooser &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;| <p align="center"><img src="https://cloud.githubusercontent.com/assets/1408720/7904376/f544756a-07c5-11e5-86d6-862ac146ad35.gif" width="400"></p> |
  135. | PasswordField | <p align="center"><img src="https://user-images.githubusercontent.com/1408720/28953722-eae72cca-788e-11e7-8fa1-9a1ef332a053.png" width="400"></p> |
  136. | Listbox | ![image](https://user-images.githubusercontent.com/1408720/31590191-fadd06f2-b1c0-11e7-9a49-7cbf0c6d33d1.png) |
  137. Internationalization
  138. --------------------
  139. <img src="https://cloud.githubusercontent.com/assets/1408720/7904365/f52e9f1a-07c5-11e5-8f31-36a8fc14ac02.jpg" align="right" />
  140. Gooey is international ready and easily ported to your host language. Languages are controlled via an argument to the `Gooey` decorator.
  141. @Gooey(language='russian')
  142. def main():
  143. ...
  144. All program text is stored externally in `json` files. So adding new langauge support is as easy as pasting a few key/value pairs in the `gooey/languages/` directory.
  145. Thanks to some awesome [contributers](https://github.com/chriskiehl/Gooey/graphs/contributors), Gooey currently comes pre-stocked with the following language sets:
  146. - English
  147. - Dutch
  148. - French
  149. - Portuguese
  150. Want to add another one? Submit a [pull request!](https://github.com/chriskiehl/Gooey/compare)
  151. -------------------------------------------
  152. Global Configuration
  153. --------------------
  154. Just about everything in Gooey's overall look and feel can be customized by passing arguments to the decorator.
  155. | Parameter | Summary |
  156. |-----------|---------|
  157. | encoding | Text encoding to use when displaying characters (default: 'utf-8') |
  158. | use_legacy_titles | Rewrites the default argparse group name from "Positional" to "Required". This is primarily for retaining backward compatibilty with previous versions of Gooey (which had poor support/awareness of groups and did its own naive bucketing of arguments). |
  159. | advanced | Toggles whether to show the 'full' configuration screen, or a simplified version |
  160. | auto_start | Skips the configuration all together and runs the program immediately |
  161. | language | Tells Gooey which language set to load from the `gooey/languages` directory.|
  162. | target | Tells Gooey how to re-invoke itself. By default Gooey will find python, but this allows you to specify the program (and arguments if supplied).|
  163. |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]`. |
  164. | program_description | Sets the text displayed in the top panel of the `Settings` screen. Defaults to the description pulled from `ArgumentParser`. |
  165. | default_size | Initial size of the window |
  166. | required_cols | Controls how many columns are in the Required Arguments section <br> :warning: **Deprecation notice:** See [Group Parameters](#group-configuration) for modern layout controls|
  167. | optional_cols | Controls how many columns are in the Optional Arguments section <br> :warning: **Deprecation notice:** See [Group Parameters](#group-configuration) for modern layout controls|
  168. | dump_build_config | Saves a `json` copy of its build configuration on disk for reuse/editing |
  169. | load_build_config | Loads a `json` copy of its build configuration from disk |
  170. | monospace_display | Uses a mono-spaced font in the output screen <br> :warning: **Deprecation notice:** See [Group Parameters](#group-configuration) for modern font configuration|
  171. | image_dir | Path to the directory in which Gooey should look for custom images/icons |
  172. | language_dir | Path to the directory in which Gooey should look for custom languages files |
  173. | disable_stop_button | Disable the `Stop` button when running |
  174. | show_stop_warning | Displays a warning modal before allowing the user to force termination of your program |
  175. | force_stop_is_error | Toggles whether an early termination by the shows the success or error screen |
  176. | show_success_modal | Toggles whether or not to show a summary modal after a successful run |
  177. | run_validators | Controls whether or not to have Gooey perform validation before calling your program |
  178. | poll_external_updates | (Experimental!) When True, Gooey will call your code with a `gooey-seed-ui` CLI argument and use the response to fill out dynamic values in the UI (See: [Using Dynamic Values](#using-dynamic-values))|
  179. | return_to_config | When True, Gooey will return to the configuration settings window upon successful run |
  180. | progress_regex | A text regex used to pattern match runtime progress information. See: [Showing Progress](#showing-progress) for a detailed how-to |
  181. | progress_expr | A python expression applied to any matches found via the `progress_regex`. See: [Showing Progress](#showing-progress) for a detailed how-to |
  182. | disable_progress_bar_animation | Disable the progress bar |
  183. | navigation | Sets the "navigation" style of Gooey's top level window. <br>Options: <table> <thead> <tr><th>TABBED</th><th>SIDEBAR</th></tr></thead> <tbody> <tr> <td><img src="https://user-images.githubusercontent.com/1408720/34464826-2a946ba2-ee47-11e7-92a4-4afeb49dc9ca.png" width="200" height="auto"></td><td><img src="https://user-images.githubusercontent.com/1408720/34464847-9918fbb0-ee47-11e7-8d5f-0d42631c2bc0.png" width="200" height="auto"></td></tr></tbody></table>|
  184. | navigation_title | <img src="https://user-images.githubusercontent.com/1408720/34472159-1bfedbd0-ef10-11e7-8bc3-b6d69febb8c3.png" width="250" height="auto" align="right"> Controls the heading title above the SideBar's navigation pane. Defaults to: "Actions" |
  185. | show_sidebar | Show/Hide the sidebar in when navigation mode == `SIDEBAR` |
  186. | body_bg_color | HEX value of the main Gooey window |
  187. | header_bg_color | HEX value of the header background |
  188. | header_height | height in pixels of the header |
  189. | header_show_title | Show/Hide the header title |
  190. | header_show_subtitle | Show/Hide the header subtitle |
  191. | footer_bg_color | HEX value of the Footer background |
  192. | sidebar_bg_color | HEX value of the Sidebar's background |
  193. | terminal_panel_color | HEX value of the terminal's panel |
  194. | terminal_font_color | HEX value of the font displayed in Gooey's terminal |
  195. | terminal_font_family | Name of the Font Family to use in the terminal |
  196. | terminal_font_weight | Weight of the font (NORMAL|BOLD) |
  197. | terminal_font_size | Point size of the font displayed in the terminal |
  198. | error_color | HEX value of the text displayed when a validation error occurs |
  199. Layout Customization
  200. --------------------
  201. You can achieve fairly flexible layouts with Gooey by using a few simple customizations.
  202. At the highest level, you have several overall layout options controllable via various arguments to the Gooey decorator.
  203. | `show_sidebar=True` | `show_sidebar=False` | `navigation='TABBED'` | `tabbed_groups=True` |
  204. |---------------------|----------------------|----------------------|------------------------|
  205. |<img src="https://user-images.githubusercontent.com/1408720/34464847-9918fbb0-ee47-11e7-8d5f-0d42631c2bc0.png" width="400"> |<img src="https://user-images.githubusercontent.com/1408720/35487799-762aa308-0434-11e8-8eb3-1e9fab2d13ae.png" width="400"> |<img src="https://user-images.githubusercontent.com/1408720/34464835-5ba9b0e4-ee47-11e7-9561-55e3647c2165.png" width="400"> |<img src="https://user-images.githubusercontent.com/1408720/34464826-2a946ba2-ee47-11e7-92a4-4afeb49dc9ca.png" width="400"> |
  206. **Grouping Inputs**
  207. By default, if you're using Argparse with Gooey, your inputs will be split into two buckets: `positional` and `optional`. However, these aren't always the most descriptive groups to present to your user. You can arbitrarily bucket inputs into logic groups and customize the layout of each.
  208. With `argparse` this is done via `add_argument_group()`
  209. <img src="https://user-images.githubusercontent.com/1408720/35487956-a4c9915e-0436-11e8-8a11-fd21528aedf0.png" align="right" width="410">
  210. ```
  211. parser = ArgumentParser()
  212. search_group = parser.add_argument_group(
  213. "Search Options",
  214. "Customize the search options"
  215. )
  216. ```
  217. You can add arguments to the group as normal
  218. ```
  219. search_group.add_argument(
  220. '--query',
  221. help='Base search string'
  222. )
  223. ```
  224. Which will display them as part of the group within the UI.
  225. **Customizing Group Layout**
  226. > Note: Make sure you're using GooeyParser if you want to take advantage of the layout customizations!
  227. With a group created, we can now start tweaking how it looks! `GooeyParser` extends the API of `add_argument_group` to accept an additional keyword argument: `gooey_options`. It accepts two keys: `show_border` and `columns`
  228. ```
  229. gooey_options={
  230. 'show_border': Bool,
  231. 'columns': 1-100
  232. }
  233. ```
  234. <img src="https://user-images.githubusercontent.com/1408720/35488154-e201ab90-0438-11e8-9479-3a27fd1c523e.png" align="right" width="400">
  235. `show_border` is nice for visually tying together closely related items within a parent group. Setting it to `true` will draw a small border around all of the inputs and nest the title at the top.
  236. `columns` controls how many many items get places on each row within the
  237. Run Modes
  238. ---------
  239. Gooey has a handful of presentation modes so you can tailor its layout to your content type and user's level or experience.
  240. ### Advanced
  241. 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).
  242. 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.
  243. <p align="center">
  244. <img src="https://cloud.githubusercontent.com/assets/1408720/7927433/f06a36cc-08ad-11e5-843e-9322df96d4d6.png">
  245. </p>
  246. 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.
  247. **Setting the layout style:**
  248. 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.
  249. It can be toggled via the `advanced` parameter in the `Gooey` decorator.
  250. @gooey(advanced=True)
  251. def main():
  252. # rest of code
  253. --------------------------------------------
  254. ### Basic
  255. The basic view is best for times when the user is familiar with Console Applications, but you still want to present something a little more polished than a simple terminal. The basic display is accessed by setting the `advanced` parameter in the `gooey` decorator to `False`.
  256. @gooey(advanced=False)
  257. def main():
  258. # rest of code
  259. <p align="center">
  260. <img src="https://cloud.githubusercontent.com/assets/1408720/7904369/f53a4306-07c5-11e5-8e63-b510d6db9953.png">
  261. </p>
  262. ----------------------------------------------
  263. ### No Config
  264. 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.
  265. <p align="center">
  266. <img src="https://cloud.githubusercontent.com/assets/1408720/7904382/f54fe6f2-07c5-11e5-92e4-f72a2ae12862.png">
  267. </p>
  268. ---------------------------------------
  269. ### Input Validation
  270. <img src="https://user-images.githubusercontent.com/1408720/34464861-0e82c214-ee48-11e7-8f4a-a8e00721efef.png" width="400" height="auto" align="right" />
  271. >:warning:
  272. >Note! This functionality is experimental. Its API may be changed or removed alltogether. Feedback/thoughts on this feature is welcome and encouraged!
  273. Gooey can optionally do some basic pre-flight validation on user input. Internally, it uses these validator functions to check for the presence of required arguments. However, by using [GooeyParser](#gooeyparser), you can extend these functions with your own validation rules. This allows Gooey to show much, much more user friendly feedback before it hands control off to your program.
  274. **Writing a validator:**
  275. Validators are specified as part of the `gooey_options` map available to `GooeyParser`. It's a simple map structure made up of a root key named `validator` and two internal pairs:
  276. * `test` The inner body of the validation test you wish to perform
  277. * `message` the error message that should display given a validation failure
  278. e.g.
  279. ```
  280. gooey_options={
  281. 'validator':{
  282. 'test': 'len(user_input) > 3',
  283. 'message': 'some helpful message'
  284. }
  285. }
  286. ```
  287. **The `test` function**
  288. Your test function can be made up of any valid Python expression. It receives the variable `user_input` as an argument against which to perform its validation. Note that all values coming from Gooey are in the form of a string, so you'll have to cast as needed in order to perform your validation.
  289. **Full Code Example**
  290. ```
  291. from gooey.python_bindings.gooey_decorator import Gooey
  292. from gooey.python_bindings.gooey_parser import GooeyParser
  293. @Gooey
  294. def main():
  295. parser = GooeyParser(description='Example validator')
  296. parser.add_argument(
  297. 'secret',
  298. metavar='Super Secret Number',
  299. help='A number specifically between 2 and 14',
  300. gooey_options={
  301. 'validator': {
  302. 'test': '2 <= int(user_input) <= 14',
  303. 'message': 'Must be between 2 and 14'
  304. }
  305. })
  306. args = parser.parse_args()
  307. print("Cool! Your secret number is: ", args.secret)
  308. ```
  309. <img src="https://user-images.githubusercontent.com/1408720/34465024-f011ac3e-ee4f-11e7-80ae-330adb4c47d6.png" width="400" height="auto" align="left" />
  310. With the validator in place, Gooey can present the error messages next to the relevant input field if any validators fail.
  311. ---------------------------------------
  312. ## Using Dynamic Values
  313. >:warning:
  314. >Note! This functionality is experimental. Its API may be changed or removed alltogether. Feedback on this feature is welcome and encouraged!
  315. Gooey's Choice style fields (Dropdown, Listbox) can be fed a dynamic set of values at runtime by enabling the `poll_external_updates` option. This will cause Gooey to request updated values from your program everytime the user visits the Configuration page. This can be used to, for instance, show the result of a previous execution on the config screen without requiring that the user restart the program.
  316. **How does it work?**
  317. <img src="https://user-images.githubusercontent.com/1408720/35487459-bd7fe938-0430-11e8-9f6d-fa8f703b9da5.gif" align="right" width="420"/>
  318. At runtime, whenever the user hits the Configuration screen, Gooey will call your program with a single CLI argument: `gooey-seed-ui`. This is a request to your program for updated values for the UI. In response to this, on `stdout`, your program should return a JSON string mapping cli-inputs to a list of options.
  319. For example, assuming a setup where you have a dropdown that lists user files:
  320. ```
  321. ...
  322. parser.add_argument(
  323. '--load',
  324. metavar='Load Previous Save',
  325. help='Load a Previous save file',
  326. dest='filename',
  327. widget='Dropdown',
  328. choices=list_savefiles(),
  329. )
  330. ```
  331. Here the input we want to populate is `--load`. So, in response to the `gooey-seed-ui` request, you would return a JSON string with `--load` as the key, and a list of strings that you'd like to display to the user as the value. e.g.
  332. ```
  333. {"--load": ["Filename_1.txt", "filename_2.txt", ..., "filename_n.txt]}
  334. ```
  335. Checkout the full example code in the [Examples Repository](https://github.com/chriskiehl/GooeyExamples/blob/master/examples/dynamic_updates.py). Or checkout a larger example in the silly little tool that spawned this feature: [SavingOverIt](https://github.com/chriskiehl/SavingOverIt).
  336. --------------------------------------
  337. ## Customizing Icons
  338. Gooey comes with a set of six default icons. These can be overridden with your own custom images/icons by telling Gooey to search additional directories when initializing. This is done via the `image_dir` argument to the `Goeey` decorator.
  339. @Gooey(program_name='Custom icon demo', image_dir='/path/to/my/image/directory')
  340. def main():
  341. # rest of program
  342. Images are discovered by Gooey based on their _filenames_. So, for example, in order to supply a custom configuration icon, simply place an image with the filename `config_icon.png` in your images directory. These are the filenames which can be overridden:
  343. * program_icon.ico
  344. * success_icon.png
  345. * running_icon.png
  346. * loading_icon.gif
  347. * config_icon.png
  348. * error_icon.png
  349. ## Packaging
  350. Thanks to some [awesome contributers](https://github.com/chriskiehl/Gooey/issues/58), packaging Gooey as an executable is super easy.
  351. The tl;dr [pyinstaller](https://github.com/pyinstaller/pyinstaller) version is to drop this [build.spec](https://github.com/chriskiehl/Gooey/files/29568/build.spec.txt) into the root directory of your application. Edit its contents so that the `application` and `name` are relevant to your project, then execute `pyinstaller build.spec` to bundle your app into a ready-to-go executable.
  352. Detailed step by step instructions can be found [here](http://chriskiehl.com/article/packaging-gooey-with-pyinstaller/).
  353. Screenshots
  354. ------------
  355. | Flat Layout | Column Layout |Success Screen | Error Screen | Warning Dialog |
  356. |-------------|---------------|---------------|--------------|----------------|
  357. | <img src="https://cloud.githubusercontent.com/assets/1408720/7950190/4414e54e-0965-11e5-964b-f717a7adaac6.jpg"> | <img src="https://cloud.githubusercontent.com/assets/1408720/7950189/4411b824-0965-11e5-905a-3a2b5df0efb3.jpg"> | <img src="https://cloud.githubusercontent.com/assets/1408720/7950192/44165442-0965-11e5-8edf-b8305353285f.jpg"> | <img src="https://cloud.githubusercontent.com/assets/1408720/7950188/4410dcce-0965-11e5-8243-c1d832c05887.jpg"> | <img src="https://cloud.githubusercontent.com/assets/1408720/7950191/4415432c-0965-11e5-9190-17f55460faf3.jpg"> |
  358. | Custom Groups | Tabbed Groups | Tabbed Navigation | Sidebar Navigation | Input Validation |
  359. |-------------|---------------|---------------|--------------|----------------|
  360. | <img src="https://user-images.githubusercontent.com/1408720/34464824-c044d57a-ee46-11e7-9c35-6e701a7c579a.png"> | <img src="https://user-images.githubusercontent.com/1408720/34464826-2a946ba2-ee47-11e7-92a4-4afeb49dc9ca.png"> | <img src="https://user-images.githubusercontent.com/1408720/34464835-5ba9b0e4-ee47-11e7-9561-55e3647c2165.png"> | <img src="https://user-images.githubusercontent.com/1408720/34464847-9918fbb0-ee47-11e7-8d5f-0d42631c2bc0.png"> | <img src="https://user-images.githubusercontent.com/1408720/34464861-0e82c214-ee48-11e7-8f4a-a8e00721efef.png"> |
  361. ----------------------------------------------
  362. Wanna help?
  363. -----------
  364. Code, translation, graphics? Pull requests are welcome.
  365. [1]: http://i.imgur.com/7fKUvw9.png