1.2.0

docs/Filterable-Dropdown-Guide.md

@@ -0,0 +1,49 @@
+# Customizing FilterableDropdown's search behavior
+
+
+Out of the box, FilterableDropdown does a very simple 'startswith' style lookup to find candidates which match the user's input. However, this behavior can be customized using GooeyOptions to support all kinds of filtering strategies. 
+
+For each example, we'll be starting with the following sample program. This uses just 4 choices to keep the different options easy to follow. However, `FilterableDropdown` is fully virtualized and can be used with 10s of thousands of choices. 
+
+
+```python
+from gooey import Gooey, GooeyParser, PrefixTokenizers
+
+choices = [
+    'Afghanistan Kabul',
+    'Albania Tirana',
+    'Japan Kyoto',
+    'Japan Tokyo'
+]
+
+@Gooey(program_name='FilterableDropdown Demo', poll_external_updates=True)
+def main():
+    parser = GooeyParser(description="Example of the Filterable Dropdown")
+    parser.add_argument(
+        "-a",
+        "--myargument",
+        metavar='Country',
+        help='Search for a country',
+        choices=choices,
+        widget='FilterableDropdown',
+        gooey_options={
+            'label_color': (255, 100, 100),
+            'placeholder': 'Start typing to view suggestions'
+        })
+    args = parser.parse_args()
+    print(args)
+```
+
+
+
+
+
+
+## Combining results 
+
+## Suffix Trees
+
+
+
+
+

docs/Gracefully-Stopping.md

@@ -0,0 +1,76 @@
+# Gracefully Stopping a Running Process
+
+>New in v1.0.9!
+
+<p align="center">
+  <img src="https://github.com/chriskiehl/GooeyImages/raw/images/docs/graceful-stopping/screenshot.PNG"/>
+</p>
+
+**Contents:**
+
+* [How to tell Gooey which shutdown signal to use](#how-to-tell-gooey-which-signal-to-use)
+* [How to catch KeyboardInterrupts](#How-to-catch-KeyboardInterrupts)
+* [How to catch general interrupt signals](#How-to-catch-general-interrupt-signals)
+
+By default, Gooey will kill the child process without any chance for cleanup. This guide will explain how to adjust that behavior so that you can detect when Gooey is attempting to close your process and use that signal to shutdown gracefully.   
+
+### Basics: How to tell Gooey which shutdown signal to use: 
+
+You can control the signal Gooey sends while stopping your process via `shutdown_signal` decorator argument. Signal values come from the builtin `signal` python module. On linux, any of the available constants may be used as a value. However, on Windows, only `CTRL_BREAK_EVENT`, `CTRL_C_EVENT` and `SIGTERM` are supported by the OS.   
+
+
+```python
+import signal 
+@Gooey(shutdown_signal=signal.CTRL_C_EVENT)
+def main():
+    ...
+```
+
+
+### How to catch KeyboardInterrupts:
+
+Keyboard interrupts are triggered in response to the `CTRL_C_EVENT` signal.
+
+```python
+import signal 
+@Gooey(shutdown_signal=signal.CTRL_C_EVENT)
+def main():
+    ...
+``` 
+
+Catching them in your code is really easy! They conveniently show up as top-level Exceptions. Just wrap your main logic in a try/except and you'll be able to catch when Gooey tries to shut down your process.   
+
+```python
+try
+   # your code here
+except KeyboardInterrupt: 
+   # cleanup and shutdown or ignore 
+``` 
+
+### How to catch general interrupt signals
+
+Handling other signals is only slightly more involved than the `CTRL_C_EVENT` one. You need to install a handler via the `signal` module and tie it to the specific signal you want to handle. Let's use the `CTRL_BREAK_EVENT` signal as example. 
+
+```python
+import signal
+
+# (1)
+def handler(*args): 
+    print("I am called in response to an external signal!")
+    raise Exception("Kaboom!")
+
+# (2) 
+signal.signal(signal.SIGBREAK, handler)
+
+# (3)
+@Gooey(shutdown_signal=signal.CTRL_BREAK_EVENT)
+def main():
+    # your code here 
+    # ... 
+```    
+
+Here we setup a handler called `handler` (1). This function can do anything you want in response to the signal including ignoring it entirely. Next we tie the signal we're interested in to the handler (2). Finally, we tell Gooey to send the `BREAK` signal(3) when the stop button is clicked. 
+
+> Note: pay close attention to the different constants used while specifying a handler (e.g. `SIGBREAK`) versus specifying which signal will be sent (e.g. `CTRL_BREAK_SIGNAL`).   
+
+

docs/packaging/Packaging-Gooey.md

@@ -75,7 +75,7 @@ The `Analysis` section is where you'll tell PyInstaller about your program. Usin
 
 Next is `EXE`. In this section you'll replace the `name` argument with what you'd like the final `.exe` to be named.
 
->Note: if you're providing your own icon file, EXE is where you'll provide it.   
+>Note: if you're providing your own icon file, EXE is where you'll provide it. If you're on Windows, you must provide an .ico file (not PNG).
 
 If you're on OSX, you'll have an additional `BUNDLE` section. You'll need to make one final edit here as well to control the name of the `.app` bundle that PyInstaller produces. Additionally, if you're customizing the bundle's icon, this is where you would supply the override (versus Windows, which places it in the EXE section). 
 

docs/releases/1.0.6-release-notes.md

@@ -3,7 +3,7 @@
 
 This is a minor release beefing up the new FilterableDropdown's search capabilities and performance. In the previous release, the dropdown was backed by WX's `ListBox` widget. 1.0.6 replaces this for a fully virtualized version which allows Gooey to operate on massive datasets without taking a hit to UI performance. Additionally, how Gooey internally filters for matches has also been updated. Choice are now backed by a trie for super fast lookup even against large data sets. Tokenization and match strategies can be customized to support just about any lookup style.      
 
-Head over to the [Examples Repo](https://github.com/chriskiehl/GooeyExamples) to see the updated demo which now uses a datset consisting of about 25k unique items.  
+Head over to the [Examples Repo](https://github.com/chriskiehl/GooeyExamples) to see the updated demo which now uses a dataset consisting of about 25k unique items.  
 
 
 **New Gooey Options:**

docs/releases/1.2.0-ALPHA-release-notes.md

@@ -0,0 +1,26 @@
+# Gooey 1.2.0-ALPHA Released! 
+
+### Warning: 
+
+>**Upgrade with caution!** 1.2.0 removes the experimental Dynamic Updates feature and replaces it with a _new_ experimental Dynamic Updates feature! The two APIs are incompatible.    
+
+This release brings a whole host of new features to Gooey. Chief among them are the new Dynamic Updates and Validation functionality. This was effectively a rebuild of a substantial portion of Gooey's internal to enable a more client/server style functionality. This means that you have more control over the gooey's lifecycle, and can subscribe to high level events. Currently, FormSubmit, OnComplete, and OnError are supported, but more are on their way! Soon you'll be able to have fine grained control over the UI and its presentation, and still without having to write a single line of traditional GUI code! 
+
+
+### Breaking Changes (1.0.8 -> 1.2.0) 
+
+ * **Validation** - the validation mechanism available via gooey_options has been removed entirely in favor of the new API.   
+ * **Dynamic Updates** - there was previously minimal support for loading new data at run time. This has been revomed in favor of a new system which gives advanced control over the state of the UI. 
+
+### New Features
+
+* **Dynamic Updates and Validation** - Checkout the [README](https://github.com/chriskiehl/Gooey/blob/master/README.md) for details on how to get started. This feature is really hairy behind the scenes and involves all kinds of crazy monkey patching in order to work. Odds of encountering a bug or scenario that doesn't work for your use case is high in this initial release. Please fill out an issue if any problems pop up! 
+* **Graceful Shutdown control** - Gooey previously would `SIGTERM` your application when you tried to halt it while running. However, with 1.2.0, you have control over which signal Gooey sends when you request a shutdown. This gives you a chance to catch that signal and clean up and resources currently un use before shutting down.
+* **Better sys.argv handling** - Gooey no longer mutates the global sys.argv variable. This caused people all kinds of problems -- most frequent being Gooey spawning multiple windows. This is now removed, and hopefully all the pain stemming from it as well. 
+
+
+TODO: rewx: document toubleshoot for when custom controlled component has its children disappear (i.e. add "self_managed=True)
+
+
+
+

docs/releases/release-checklist.md

@@ -14,6 +14,7 @@
  - [ ] all debug prints removed  
  - [ ] setup.py version is updated 
  - [ ] __init__.py version is updated
+ - [ ] types check (for the most part) `./venv/Scripts/python.exe -m mypy /path/to/python_bindings/types.py`
  - [ ] pip install of release branch works.   
      - [ ] All Gooey Examples run and work as expected
  - [ ] pypi is updated 

gooey/__init__.py

@@ -3,6 +3,9 @@
 from gooey.python_bindings.gooey_parser import GooeyParser
 from gooey.gui.util.freeze import localResourcePath as local_resource_path
 from gooey.python_bindings import constants
+from gooey.python_bindings.constants import Events
 from gooey.gui.components.filtering.prefix_filter import PrefixTokenizers
 from gooey.gui.components.options import options
-__version__ = '1.0.8.1'
+from gooey.python_bindings import types
+types = types
+__version__ = '1.2.0-ALPHA'