Merge pull request #422 from lawsie/dev

v1.2.0
lawsie · May 4, 2021 · 99fea22 · 99fea22
2 parents 7250e2a + f79e98e
commit 99fea22
Show file tree

Hide file tree

Showing 43 changed files with 615 additions and 236 deletions.
diff --git a/docs-src/docs/about.md b/docs-src/docs/about.md
@@ -32,5 +32,5 @@ The aim of guizero is to make the process of creating simple GUIs quick, accessi
 
 ### Version
 
-guizero is currently [version 1.1.1](changelog.md)
+guizero is currently [version 1.2.0](changelog.md)
 
diff --git a/docs-src/docs/alerts.md b/docs-src/docs/alerts.md
@@ -26,8 +26,9 @@ These functions pop up a box on the screen that displays a message or asks a que
 * `error(title, text)` - popup box with an error icon
 * `yesno(title, text)` - popup box with yes and no options. Pressing `Yes` returns `True` and pressing `No` returns `False`.
 * `question(title, text, initial_value=None)` - popup box with a question box which can accept a text response. Pressing `Ok` returns value entered into the box is returned and pressing `Cancel` returns `None`.
-* `select_file(title="Select file", folder=".", filetypes=[["All files", "*.*"]], save=False)` - popup file dialog box which asks the user to select a file. By default, an *Open* button is displayed, setting `save` to `True` will change the button to *Save as*. The path of the selected file is returned by the function.
+* `select_file(title="Select file", folder=".", filetypes=[["All files", "*.*"]], save=False, filename="")` - popup file dialog box which asks the user to select a file. By default, an *Open* button is displayed, setting `save` to `True` will change the button to *Save as*. The path of the selected file is returned by the function. A `filename` parameter can be supplied which will auto populate the file name field.
 * `select_folder(title="Select folder", folder=".")` - popup box which asks the user to select a folder. The path of the selected folder is returned by the function.
+* `select_color(color=None)` - popup box which prompts the user to select a color. Set `color` to an `#rrggbb` to select a default color when the popup opens. Pressing `Ok` returns the select color as a `#rrggbb` value, pressing `Cancel` returns `None`.
 
 All pop up boxes use the native display, so they will look different depending on your operating system.
 
@@ -141,7 +142,7 @@ hello = Text(app)
 app.display()
 ```
 
-![question popu](images/question_windows.png)
+![question popup](images/question_windows.png)
 
 ** Example: Get a file name**
 

diff --git a/docs-src/docs/app.md b/docs-src/docs/app.md
diff --git a/docs-src/docs/changelog.md b/docs-src/docs/changelog.md
@@ -1,5 +1,16 @@
 # guizero
 
+## 1.2.0 - 2021-05-04
+- Added `filename` to `select_file` dialog
+- Added `when_resized` and `when_double_clicked` events
+- Removed previously deprecated `App.on_closed` method
+- A window icon can be set using the `.icon` property
+- Add `select_color` popup
+- Documentation updates and fixes
+- Added new examples and recipes
+- Tests updated to cope with a greater range of operating systems. Tests work on Windows, macOS and Raspberry Pi OS.
+- contributors [martinohanlon](https://github.com/martinohanlon), [lawsie](https://github.com/lawsie), [mirelsol](https://github.com/mirelsol), [maroph](https://github.com/maroph)
+
 ## 1.1.1 - 2020-11-27
 - PushButton image bug fix for macOS
 - Documentation updates regarding how to use tk, particularly for ListBox widget
@@ -10,9 +21,9 @@
 - contributors [martinohanlon](https://github.com/martinohanlon), [aajshaw](https://github.com/aajshaw)
 
 ## 1.1.0 - 2019-10-25
-- Added ability to be able to change the grid of a widget at room time
+- Added ability to be able to change the grid of a widget at run time
 - Added `hide_text` to `TextBox` for use with passwords
-- Added open file and folder popups `select_file` and `select_folder`
+- Added open file and folder pop-ups `select_file` and `select_folder`
 - Changes to `Text` to better support cascading of text color, font and size
 - Various documentation updates 
 - contributors [martinohanlon](https://github.com/martinohanlon), [lawsie](https://github.com/lawsie)

diff --git a/docs-src/docs/commands.md b/docs-src/docs/commands.md
@@ -19,3 +19,17 @@ text = Text(app)
 button = PushButton(app, command=say_hello)
 app.display()
 ```
+
+Arguments can be passed to the command function using the `args` parameter.
+
+```python
+from guizero import App, Text, PushButton
+
+def say_goodbye(first_name, last_name):
+    text.value = first_name + " " + last_name
+
+app = App()
+text = Text(app)
+button = PushButton(app, command=say_goodbye, args=['John', 'Doe'])
+app.display()
+```
diff --git a/docs-src/docs/events.md b/docs-src/docs/events.md
@@ -3,6 +3,7 @@
 Custom events can be added to guizero widgets to call functions when the user takes the following actions:
 
 - when clicked - `when_clicked`
+- when double clicked - `when_double_clicked`
 - when the left mouse button is pressed - `when_left_button_pressed`
 - when the left mouse button is released - `when_left_button_released`
 - when the right mouse button is pressed - `when_right_button_pressed`
@@ -12,6 +13,7 @@ Custom events can be added to guizero widgets to call functions when the user ta
 - when the mouse enters a widget - `when_mouse_enters`
 - when the mouse leaves a widget - `when_mouse_leaves`
 - when the mouse is dragged across a widget - `when_mouse_dragged`
+- when the widget is resized - `when_resized`
 
 Events are set by assigning them to a function:
 
@@ -24,17 +26,21 @@ widget.when_clicked = do_this
 
 ### Event Data
 
-The function which is called can also accept a parameter and will be passed data about the event which occured.
+The function which is called can also accept a parameter and will be passed data about the event which occurred.
 
 The event data returned has:
 
 - `widget` - the guizero widget which raised the event
 - `tk_event` - the [tkinter event object](http://effbot.org/tkinterbook/tkinter-events-and-bindings.htm)
 - `key` - the key which raised the event
-- `x` - the mouse's x position relative to the widget when the event occured
-- `y` - the mouse's y position relative to the widget when the event occured
-- `display_x` - the mouse's x position on the display when the event occured
-- `display_y` - the mouse's y position on the display when the event occured
+- `x` - the mouse's x position relative to the widget when the event occurred
+- `y` - the mouse's y position relative to the widget when the event occurred
+- `display_x` - the mouse's x position on the display when the event occurred
+- `display_y` - the mouse's y position on the display when the event occurred
+- `width` - the width of the widget. 
+- `height` - the height of the widget.
+
+**Note:** only data relevant to the event will be returned. e.g. `key` is only returned for `when_key_#` events and `width` and `height` are only returned for `when_resized` events.
 
 ```python
 def clicked(event_data):
@@ -66,4 +72,4 @@ text_box.when_mouse_enters = highlight
 text_box.when_mouse_leaves = lowlight
 
 app.display()
-```
+```
diff --git a/docs-src/docs/index.md b/docs-src/docs/index.md
@@ -142,7 +142,7 @@ If you installed guizero using the easy install method, to upgrade you should fo
 
 If you are using Windows you can install guizero by downloading and running a Windows MSI installer application.
 
-1. Download either the [64-bit guizero installer](https://github.com/lawsie/guizero/releases/latest/download/guizero-1.1.1.amd64.msi) or the [32-bit guizero installer](https://github.com/lawsie/guizero/releases/latest/download/guizero-1.1.1.win32.msi) depending on which version of Python you are using.
+1. Download either the [64-bit guizero installer](https://github.com/lawsie/guizero/releases/latest/download/guizero-1.2.0.amd64.msi) or the [32-bit guizero installer](https://github.com/lawsie/guizero/releases/latest/download/guizero-1.2.0.win32.msi) depending on which version of Python you are using.
 
     **Note:** If you are not sure what version of python you are running, run the following program in Python, which will output either `32` or `64`:
 

diff --git a/docs-src/docs/pushbutton.md b/docs-src/docs/pushbutton.md
@@ -86,7 +86,6 @@ You can call the following methods on a `PushButton` object.
 | enable()                            | -                                                                                    | -       | Enables the widget                                                                                                                                             |
 | focus()                             | -                                                                                    | -       | Gives focus to the widget                                                                                                                                      |
 | hide()                              | -                                                                                    | -       | Hides the widget from view. This method will unpack the widget from the layout manager.                                                                        |
-| image(image_source)                 | image_source (string)                                                                | -       | The file path, tkinter.PhotoImage or PIL.Image you wish to display.                                                                                            |
 | padding(padx, pady)                 | padx (int), pady(int)                                                                | -       | Sets the amount of x (horizontal) and y (vertical) padding between the text/icon and the edge of the button                                                    |
 | repeat(time, command, args=None)    | time (int), command (function name), args (list of arguments)                        | -       | Repeats `command` every `time` milliseconds. This is useful for scheduling a function to be regularly called, for example updating a value read from a sensor. |
 | resize(width, height)               | width (int), height (int)                                                            | -       | Sets the width and height of the widget                                                                                                                        |
@@ -99,22 +98,23 @@ You can call the following methods on a `PushButton` object.
 
 You can set and get the following properties:
 
-| Method     | Data type          | Description                                                                                           |
-|------------|--------------------|-------------------------------------------------------------------------------------------------------|
-| align      | string             | The alignment of this widget within its container                                                     |
-| bg         | [color](colors.md) | The background colour of the widget                                                                   |
-| enabled    | boolean            | `True` if the widget is enabled                                                                       |
-| font       | string             | The font of the text on the button                                                                    |
-| grid       | List               | `[x,y]` coordinates of this widget. This parameter is only required if the `master` object has a grid |
-| height     | [size](size.md)    | Set the height of the widget in characters or pixels if its an image button or to `"fill"`            |
-| master     | App or Box         | The container to which this widget belongs                                                            |
-| text       | string             | The text on the button                                                                                |
-| text_color | [color](colors.md) | The colour of the text on the button                                                                  |
-| text_size  | int                | The size of the text on the button                                                                    |
-| tk         | tkinter.Button     | The internal tkinter object, see [Using tkinter](usingtk.md)                                          |
-| value      | int                | Returns 1 when the button is pressed, 0 if the button is released                                     |
-| visible    | boolean            | If this widget is visible                                                                             |
-| width      | [size](size.md)    | Set the width of the widget in characters or pixels if its an image button or to `"fill"`             |
+| Method     | Data type             | Description                                                                                           |
+|------------|-----------------------|-------------------------------------------------------------------------------------------------------|
+| align      | string                | The alignment of this widget within its container                                                     |
+| bg         | [color](colors.md)    | The background colour of the widget                                                                   |
+| enabled    | boolean               | `True` if the widget is enabled                                                                       |
+| font       | string                | The font of the text on the button                                                                    |
+| grid       | List                  | `[x,y]` coordinates of this widget. This parameter is only required if the `master` object has a grid |
+| height     | [size](size.md)       | Set the height of the widget in characters or pixels if its an image button or to `"fill"`            |
+| image      | image_source (string) | The file path, tkinter.PhotoImage or PIL.Image you wish to display.                                   |
+| master     | App or Box            | The container to which this widget belongs                                                            |
+| text       | string                | The text on the button                                                                                |
+| text_color | [color](colors.md)    | The colour of the text on the button                                                                  |
+| text_size  | int                   | The size of the text on the button                                                                    |
+| tk         | tkinter.Button        | The internal tkinter object, see [Using tkinter](usingtk.md)                                          |
+| value      | int                   | Returns 1 when the button is pressed, 0 if the button is released                                     |
+| visible    | boolean               | If this widget is visible                                                                             |
+| width      | [size](size.md)       | Set the width of the widget in characters or pixels if its an image button or to `"fill"`             |
 
 Refer to a property as `<name of widget>.property`. For example, if your `PushButton` object is called `button` you would write `button.value`.
 

diff --git a/docs-src/docs/recipes.md b/docs-src/docs/recipes.md
@@ -129,3 +129,21 @@ height.value = picture.height
 
 app.display()
 ```
+
+## Double click a widget
+
+To be able to react when a user double click's you will need to use [events](events.md).
+
+```python
+from guizero import App, Text
+
+def double_click():
+    double_click_me.value = "Thanks"
+
+app = App()
+
+double_click_me = Text(app, text="Double click me")
+double_click_me.when_double_clicked = double_click
+
+app.display()
+```
Original file line number	Diff line number	Diff line change
Expand Up		@@ -32,5 +32,5 @@ The aim of guizero is to make the process of creating simple GUIs quick, accessi

		### Version

		guizero is currently [version 1.1.1](changelog.md)
		guizero is currently [version 1.2.0](changelog.md)