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.

251 lines
8.2 KiB

4 years ago
4 years ago
  1. # Gooey Options
  2. Using `GooeyParser` we can extend the API of `argparse` to support lots of cool additional functionality.
  3. The main addition to the top-level `argparse` API is that we pick up extra keywords: `widget` and `gooey_options`. `widget` is used to specified which UI element to provide for the argument, i.e., a listbox or a file browser. `gooey_options` accepts a dictionary of configuration parameters that lets you specify things like custom validators, style overrides, and a bunch of behavioral extensions for the various widget classes.
  4. `GooeyParser` is a drop-in replacement for `argparse`. You can import it from the root Gooey namespace like this:
  5. ```python
  6. from gooey import GooeyParser
  7. ```
  8. and replace `ArgumentParser` with `GooeyParser`
  9. ```python
  10. # parser = ArgumentParser() # old busted
  11. parser = GooeyParser() # new hotness
  12. ```
  13. and with that, you're ready to rock.
  14. ## Overview
  15. * Global Style/Layout Options
  16. * Global Config Options
  17. * Custom Widget Options
  18. * Textarea
  19. * BlockCheckbox
  20. * Listbox
  21. * RadioGroups
  22. * Argument Group Options
  23. ## Global Style / Layout Options
  24. All widgets in Gooey (with the exception of RadioGroups) are made up of three basic components.
  25. 1. Label
  26. 2. Help Text
  27. 3. Input Control
  28. ![image](https://user-images.githubusercontent.com/1408720/56450719-cfca9c80-62dc-11e9-93ec-6ad56810e79a.png)
  29. The following options apply to all Widget types in Gooey.
  30. ```python
  31. parser.add_argument('-my-arg', gooey_options={
  32. 'label_color': '#ffffff',
  33. 'label_bg_color': '#ffffff',
  34. 'help_color': '#ffffff',
  35. 'help_bg_color': '#ffffff',
  36. 'error_color': '#ffffff',
  37. 'error_bg_color': '#ffffff',
  38. 'show_label': bool,
  39. 'show_help': bool,
  40. 'visible': bool,
  41. 'full_width': bool
  42. })
  43. ```
  44. | Keyword | Type | Description |
  45. |---------|------|-------------|
  46. | label_color | hex string | The foreground color of the label text (e.g. `#ff0000`) |
  47. | label_bg_color | hex string | The background color of the label text. |
  48. | help_color | hex string | The foreground color of the help text. |
  49. | help_bg_color | hex string | The background color of the help text. |
  50. | error_color | hex string | The foreground color of the error text (when visible). |
  51. | error_bg_color | hex string | The background color of the error text (when visible). |
  52. | show_label | bool | Toggles whether or not to display the label text |
  53. | show_help | bool | Toggles whether or not to display the help text |
  54. | visible | bool | Hides the entire widget when `False`. Note: the widget is still present in the UI and will still send along any default values that have been provided in code. This option is here for when you want to hide certain advanced / dangerous inputs from your GUI users. |
  55. | full_width | bool | This is a layout hint for this widget. When `True` the widget will fill the entire available space within a given row. Otherwise, it will be sized based on the column rules provided elsewhere. |
  56. ## Global Config Options
  57. > new in 1.0.8
  58. All widgets in Gooey accept an `initial_value` option to seed the UI.
  59. ```python
  60. parser.add_argument('-my-arg', widget='Textarea', gooey_options={
  61. 'initial_value': 'Hello world!'
  62. })
  63. ```
  64. ## Individual Widget Options
  65. A few widgets have additional options for controlling their layout and behavior.
  66. ### Textarea
  67. ```python
  68. parser.add_argument('-my-arg', widget='Textarea', gooey_options={
  69. # height of the text area in pixels
  70. 'height': int,
  71. # prevents the user from editing when true
  72. 'readonly': bool
  73. })
  74. ```
  75. ### IntegerField
  76. ```python
  77. parser.add_argument('-my-arg', widget='IntegerField', gooey_options={
  78. min: int,
  79. max: int,
  80. increment: int
  81. })
  82. ```
  83. ### DecimalField
  84. ```python
  85. parser.add_argument('-my-arg', widget='DecimalField', gooey_options={
  86. min: float,
  87. max: float,
  88. increment: float,
  89. precision: int # 0 - 20
  90. })
  91. ```
  92. ### Slider
  93. The Slider is just a reskinned IntegerField, so it has the same options
  94. ```python
  95. parser.add_argument('-my-arg', widget='Slider', gooey_options={
  96. min: int,
  97. max: int,
  98. increment: int
  99. })
  100. ```
  101. ### BlockCheckbox
  102. ```python
  103. parser.add_argument('-my-arg', widget='BlockCheckbox', gooey_options={
  104. # allows customizing the checkbox's label
  105. 'checkbox_label': str
  106. })
  107. ```
  108. ### Listbox
  109. ```python
  110. parser.add_argument('-my-arg', widget='Listbox', gooey_options={
  111. # height of the listbox in pixels
  112. 'height': int
  113. })
  114. ```
  115. ### Radio Group
  116. ```python
  117. parser.add_mutually_exclusive_group(gooey_options={
  118. # Pre-select a specific option within a mutually exclusive group.
  119. # default behavior is to have all options unselected by default.
  120. 'initial_selection': int,
  121. # customizes the text which appears over the Radio Group
  122. # default: "Choose one"
  123. 'title': str
  124. })
  125. ```
  126. ## Argument Groups
  127. Argument Groups take a number of `gooey_options` to help control layout.
  128. ```python
  129. parser.add_argument_group('MyGroup', description='my cool group', gooey_options={
  130. 'show_border': bool,
  131. 'show_underline': bool,
  132. 'label_color': '#FF9900',
  133. 'columns': int,
  134. 'margin_top': int
  135. })
  136. ```
  137. | Keyword | Type | Description |
  138. |---------|------|-------------|
  139. | show_border | bool | When `True` a labeled border will surround all widgets added to this group. |
  140. | show_underline | bool | Controls whether or not to display the underline when using the default border style |
  141. | label_color | hex string | The foreground color for the group name |
  142. | columns | int | Controls the number of widgets on each row |
  143. | margin_top | int | specifies the top margin in pixels for this group |
  144. ![image](https://user-images.githubusercontent.com/1408720/57576112-9c77bb00-740d-11e9-9dac-4e798699a35c.png)
  145. ## File and Folder choosers
  146. File and Folder Choosers Groups take a number of `gooey_options` to help control default values.
  147. ```python
  148. parser.add_argument("FileChooser", widget="FileChooser",
  149. gooey_options={
  150. 'wildcard':
  151. "Comma separated file (*.csv)|*.csv|"
  152. "All files (*.*)|*.*",
  153. 'default_dir': "c:/batch",
  154. 'default_file': "def_file.csv",
  155. 'message': "pick me"
  156. }
  157. )
  158. parser.add_argument("DirectoryChooser", widget="DirChooser",
  159. gooey_options={
  160. 'wildcard':
  161. "Comma separated file (*.csv)|*.csv|"
  162. "All files (*.*)|*.*",
  163. 'message': "pick folder",
  164. 'default_path': "c:/batch/stuff"
  165. }
  166. )
  167. parser.add_argument("FileSaver", widget="FileSaver",
  168. gooey_options={
  169. 'wildcard':
  170. "JPG (*.jpg)|*.jpg|"
  171. "All files (*.*)|*.*",
  172. 'message': "pick folder",
  173. 'default_dir': "c:/projects",
  174. 'default_file': "def_file.csv"
  175. }
  176. )
  177. parser.add_argument("MultiFileSaver", widget="MultiFileChooser",
  178. gooey_options={
  179. 'wildcard':
  180. "Comma separated file (*.csv)|*.csv|"
  181. "All files (*.*)|*.*",
  182. 'message': "pick folder",
  183. 'default_dir': "c:/temp",
  184. 'default_file': "def_file.csv"
  185. }
  186. )
  187. ```
  188. | Keyword | Type | Description |
  189. |---------|------|-------------|
  190. | wildcard | string | Sets the wildcard, which can contain multiple file types, for example: "BMP files (.bmp)|.bmp|GIF files (.gif)|.gif" |
  191. | message | string | Sets the message that will be displayed on the dialog. |
  192. | default_dir | string | The default directory |
  193. | default_file | string | The default filename |
  194. | default_path | string | The default path |