Merge pull request #287 from lawsie/dev

0.6.3
lawsie · Apr 18, 2019 · 84c7f0b · 84c7f0b
2 parents 079da95 + e4d2421
commit 84c7f0b
Show file tree

Hide file tree

Showing 49 changed files with 425 additions and 224 deletions.
diff --git a/README.md b/README.md
@@ -1,85 +1,52 @@
-# guizero
-
-[Version 0.6.2](http://lawsie.github.io/guizero/changelog) (5th Apr 2019)
-
-guizero is designed to allow children to quickly and easily create GUIs for their programs.
-
-If you can download and unzip a file, you can [install guizero](#easy-installation) - **no special permissions or administrator rights are required**.
-
-If you have administrator rights and are connected to the internet, you can use [pip to quickly install guizero](#install-using-pip).
-
-guizero only requires `tkinter` to be installed, which is included with a standard Python installation on all platforms except Linux.
-
-## Easy installation
-
-Use this installation method if you do not have access to a terminal or command prompt on your computer.
-
-1. Click the green "Clone or download" button and then "Download ZIP"
-
-    ![Download the zip](docs-src/docs/images/download-zip.png)
-
-2. Unzip the file
+![version number](https://badge.fury.io/py/guizero.svg)
 
-3. Open the `guizero-master` folder, then copy the `guizero` folder and paste it into your home directory
-
-    ![Copy the guizero folder](docs-src/docs/images/copy-guizero.png)
-
-4. That's it! When you write your guizero code, make sure you save it into your home directory.
-
-## Install using pip
-
-If you have administrator rights to your computer and are connected to the internet, you can use pip to quickly install guizero.
-
-### Windows
+# guizero
 
-1. Make sure you have pip installed - follow [this guide](https://projects.raspberrypi.org/en/projects/using-pip-on-windows) if you are not sure.
-2. Open a command prompt
-3. Type `pip3 install guizero` and press Enter
+[guizero](https://lawsie.github.io/guizero) is a Python 3 library for creating simple GUIs. 
 
-### Raspberry Pi
+It is designed to allow new learners to quickly and easily create GUIs for their programs.
 
-1. Open a terminal window
-2. Type `sudo pip3 install guizero` and press Enter
+![Have a go with guizero and see what you can create](docs-src/docs/images/have-a-go.png)
 
-### Mac OS
-1. Open a terminal (you can search for it in the Launch Pad)
+```python
+from guizero import App, Text, PushButton
 
-    ![Mac terminal](docs-src/docs/images/mac-terminal.png)
+app = App(title="guizero")
 
-2. Type `sudo pip3 install guizero`
+intro = Text(app, text="Have a go with guizero and see what you can create.")
+ok = PushButton(app, text="Ok")
 
-    ![Mac install screenshot](docs-src/docs/images/mac-install.png)
+app.display()
+```
 
-### Linux
+## Install
 
-1. Open a terminal
-2. Install `tkinter` using your distribution's package manager, e.g. `sudo apt install python3-tk`
-3. Install guizero using pip by typing `pip3 install guizero` or `sudo pip3 install guizero` if you dont have superuser rights
+If you can download and unzip a file, you can [install guizero](https://lawsie.github.io/guizero/#easy-install) - **no special permissions or administrator rights are required**.
 
-## Upgrading
+If you have administrator rights and are connected to the internet, you can use [pip to install guizero](https://lawsie.github.io/guizero/#install-using-pip).
 
-- Raspberry Pi/Linux/Mac - `sudo pip3 install guizero --upgrade`
-- Windows - `pip3 install guizero --upgrade`
+## Documentation
 
-## Mission statement
-The aim of guizero is to make the process of creating simple GUIs quick, accessible and understandable for children.
+Comprehensive documentation can be found at [lawsie.github.io/guizero](https://lawsie.github.io/guizero) including:
++ [installation instructions](https://lawsie.github.io/guizero)
++ [a getting started guide](https://lawsie.github.io/guizero/start)
++ [recipes](https://lawsie.github.io/guizero/recipes)
++ [an API reference](https://lawsie.github.io/guizero/app/)
 
 ## Aims
-* Works with standard Python GUI library (and no need to install other libraries)
-* Abstracts away details children find hard (such as Tkinter StringVar() objects)
-* Accessible widget naming system to help children to build up a mental model
-* Flexible enough to be used for projects up to A-Level standard, yet accessible to primary school children
-* Comprehensive and accessible [documentation with examples](https://lawsie.github.io/guizero)
-* Helpful error messages
+The aim of guizero is to make the process of creating simple GUIs quick, accessible and understandable for new learners.
 
-## Documentation
-
-[lawsie.github.io/guizero](https://lawsie.github.io/guizero)
+* Works with standard Python Tkinter GUI library (and no need to install other libraries)
+* Abstracts away details new learners find difficult to understand (such as Tkinter StringVar() objects)
+* Accessible widget naming system to help new learners to build up a mental model
+* Flexible enough to be used for projects up to A-Level standard, yet accessible to primary school children
+* Comprehensive and accessible documentation with examples
+* Generates helpful additional error messages
 
 ## Contributing
 
 Contributions are very welcome - please see [lawsie.github.io/guizero/contributing](https://lawsie.github.io/guizero/contributing) for notes, build and deployment instructions.
 
 ## Issues
 
-All issues should be raise on [github.com/lawsie/guizero/issues](https://github.com/lawsie/guizero/issues)
+All issues should be raised on [github.com/lawsie/guizero/issues](https://github.com/lawsie/guizero/issues)
diff --git a/docs-src/docs/about.md b/docs-src/docs/about.md
@@ -2,8 +2,22 @@
 
 ### What is guizero?
 
-* It is a Python 3 library for creating simple GUIs
-* It is a wrapper for the standard Tkinter library (included by default when Python is installed)
+guizero is a Python 3 library for creating simple GUIs. 
+
+It is designed to allow new learners to quickly and easily create GUIs for their programs.
+
+![So have a go with guizero and see what you can create](images/have-a-go.png)
+
+```python
+from guizero import App, Text, PushButton
+
+app = App(title="guizero")
+
+intro = Text(app, text="Have a go with guizero and see what you can create.")
+ok = PushButton(app, text="Ok")
+
+app.display()
+```
 
 ### Aims
 
@@ -18,6 +32,6 @@ The aim of guizero is to make the process of creating simple GUIs quick, accessi
 
 ### Version
 
-guizero is currently [version 0.6.2](changelog.md)
+guizero is currently [version 0.6.3](changelog.md)
 
 There may be bugs and features may change and be updated.
diff --git a/docs-src/docs/changelog.md b/docs-src/docs/changelog.md
@@ -1,5 +1,12 @@
 # guizero
 
+## 0.6.3 - 2019-04-18
+- ListBox scrollbar bug fix (again)
+- Removed pillow requires dependency
+- Added pillow as an extra dependency `pip3 install guizero[images]`
+- Installation instructions update
+- contributors [martinohanlon](https://github.com/martinohanlon), [lawsie](https://github.com/lawsie) 
+
 ## 0.6.2 - 2019-04-05
 - Ability to [add tk widgets](./usingtk/) into a guizero app with `.add_tk_widget()`
 - ListBox scrollbar bug fix

diff --git a/docs-src/docs/deployment.md b/docs-src/docs/deployment.md
@@ -5,8 +5,6 @@ Notes on how to deploy guizero (on Windows).
 ## Prepare
 
 - Update version number in `guizero\__init__.py`
-- Update version number in `README.md`
-- Update release date in `README.md`
 - Update version number in `docs-src\docs\about.md`
 - Update `changelog.md` in docs
 

diff --git a/docs-src/docs/gettinghelp.md b/docs-src/docs/gettinghelp.md
@@ -12,12 +12,14 @@ If you have a question about your guizero program it is a good idea to join a co
 
 If you would like to read guides and resources for guizero there are many freely available:
 
+- [Getting started with GUIs](https://projects.raspberrypi.org/en/projects/getting-started-with-guis) - a beginners guide to guizero by the Raspberry Pi Foundation
+
+- [Python guizero video](https://youtu.be/3dab9xX6Uyg) - a series of videos by [Devon Schafer](https://www.youtube.com/channel/UCTHAn3Viqm9lZO2YSALXNWw) on using guizero.
+
 - [Example programs](https://github.com/lawsie/guizero/tree/master/examples) - some example programs to get you going.
 
 - [Using guizero with hardware](https://github.com/bennuttall/guizero-examples) - Ben Nuttall's projects using guizero combined with hardware
 
-- [Getting started with GUIs](https://projects.raspberrypi.org/en/projects/getting-started-with-guis) - a beginners guide to guizero by the Raspberry Pi Foundation
-
 - [Cat name generator](http://www.cotswoldjam.org/downloads/2017-03/cat-name-generator/) - materials for a kids workshop, first run at the [Cotswold Jam](http://www.cotswoldjam.org)
 
 - [Name your pet](https://helloworld.raspberrypi.org/issues/2) - article on page 42 of [Hello World](https://helloworld.raspberrypi.org/) magazine issue 2.

diff --git a/docs-src/docs/images.md b/docs-src/docs/images.md
@@ -17,7 +17,7 @@ All systems support the `GIF` file type.
 
 Windows and Linux also support `PNG` files.
 
-If you [installed guizero](index.md) using `pip` it will also have installed `PIL` (Python Imaging Library) and you will be able use the majority of commonly used image types.
+If you [installed the addition image features](index.md#additional-features-install) using `pip` it will also have installed `PIL` (Python Imaging Library) and you will be able use the majority of commonly used image types.
 
 guizero will tell you what file types are supported on your computer using the following code:
 

diff --git a/docs-src/docs/images/copy-guizero-annotated.png b/docs-src/docs/images/copy-guizero-annotated.png
diff --git a/docs-src/docs/images/copy-guizero-macos-annotated.png b/docs-src/docs/images/copy-guizero-macos-annotated.png
diff --git a/docs-src/docs/images/copy-guizero-macos.png b/docs-src/docs/images/copy-guizero-macos.png
diff --git a/docs-src/docs/images/copy-guizero.png b/docs-src/docs/images/copy-guizero.png
diff --git a/docs-src/docs/images/have-a-go.png b/docs-src/docs/images/have-a-go.png
diff --git a/docs-src/docs/images/linux_pip_install.gif b/docs-src/docs/images/linux_pip_install.gif
diff --git a/docs-src/docs/images/mac_pip_install.gif b/docs-src/docs/images/mac_pip_install.gif
diff --git a/docs-src/docs/images/pi-terminal.png b/docs-src/docs/images/pi-terminal.png
diff --git a/docs-src/docs/images/pi_pip_install.gif b/docs-src/docs/images/pi_pip_install.gif
diff --git a/docs-src/docs/images/windows_command_prompt_app.png b/docs-src/docs/images/windows_command_prompt_app.png
diff --git a/docs-src/docs/images/windows_pip_install.gif b/docs-src/docs/images/windows_pip_install.gif
diff --git a/docs-src/docs/index.md b/docs-src/docs/index.md
@@ -2,52 +2,129 @@
 
 guizero is designed to allow new learners to quickly and easily create GUIs for their programs.
 
-If you can download and unzip a file, you can [install guizero](#easy-installation) - **no special permissions or administrator rights are required**.
+If you can download and unzip a file, you can [install guizero](#easy-install) - **no special permissions or administrator rights are required**.
 
-If you have administrator rights and are connected to the internet, you can use [pip to quickly install guizero](#install-using-pip).
+If you have administrator rights and are connected to the internet, you can use [pip to install guizero](#install-using-pip).
 
-guizero only requires `tkinter` to be installed, which is included with a standard Python installation on all platforms except Linux.
+## Easy install
 
-## Easy installation
-
-1. Go to the [Github repo](https://github.com/lawsie/guizero) for guizero
+1. Go to the [guizero repository](https://github.com/lawsie/guizero) on GitHub.
 
 2. Click the green "Clone or download" button and then "Download ZIP"
 
     ![Download the zip](images/download-zip.png)
 
-3. Unzip the file
+3. Open the zip file
 
 4. Open the `guizero-master` folder, then copy the `guizero` folder and paste it into your home directory
 
-    ![Copy the guizero folder](images/copy-guizero.png)
+    + Windows
+
+        ![Copy the guizero folder in windows](images/copy-guizero-annotated.png)
+
+    + macOS
+
+        ![Copy the guizero folder in macos](images/copy-guizero-macos-annotated.png)
 
 5. That's it! When you write your guizero code, make sure you save it into your home directory.
 
 ## Install using pip
 
+You can use the command prompt and `pip` to install guizero for:
+
++ [Windows](#windows)
++ [macOS](#macos)
++ [Raspberry Pi](#raspberry-pi)
++ [Linux](#linux)
+
+`pip` can also be used to [install additional features](#additional-features-install) and [upgrade guizero](#upgrading).
+
 ### Windows
 
-1. Make sure you have [pip](https://projects.raspberrypi.org/en/projects/using-pip-on-windows) installed.
-2. Open a command prompt
-3. Type `pip install guizero` and press Enter
+1. Open a command prompt by clicking **Start** > **Windows System** > **Command Prompt**, or by typing 'command' into the start menu's search bar.
+
+    ![windows command prompt](images/windows_command_prompt_app.png)
+
+2. Type this command and press enter:
 
-## Raspberry Pi
+    ```
+    pip3 install guizero
+    ```
 
-1. Open a terminal window
-2. Type `sudo pip3 install guizero` and press Enter
+![windows pip install](images/windows_pip_install.gif)
 
-## Mac OS
-1. Open a terminal (you can search for it in the Launch Pad)
+If you experience problems, have a look at this guide to [_Using pip on Windows_](https://projects.raspberrypi.org/en/projects/using-pip-on-windows).
+
+### macOS
+
+1. Open a terminal window by clicking **Applications** > **Utilities** > **Terminal**, or by typing 'terminal' into the desktop's search bar.
 
     ![Mac terminal](images/mac-terminal.png)
 
-2. Type `sudo pip3 install guizero`
+2. Type this command and press enter:
+
+    ```
+    pip3 install guizero
+    ```
+
+    ![mac pip install](images/mac_pip_install.gif)
+
+### Raspberry Pi
+
+1. Open a terminal window by clicking **Menu** > **Accessories** > **Terminal**.
+
+    ![pi terminal](images/pi-terminal.png)
+
+2. Type this command and press enter:
 
-    ![Mac install screenshot](images/mac-install.png)
+    ```
+    sudo pip3 install guizero
+    ```
 
-## Linux
+    ![run pip install guizero](images/pi_pip_install.gif)
+
+### Linux
 
 1. Open a terminal
 2. Install `tkinter` using your distribution's package manager, e.g. `sudo apt install python3-tk`
 3. Install guizero using pip by typing `pip3 install guizero` or `sudo pip3 install guizero` if you dont have superuser rights
+
+    ![linux pip install](images/linux_pip_install.gif)
+
+### Additional features install
+
+To use the additional [image features](images.md) of guizero such as:
+
+- JPG image support
+- scaling images
+- animated gifs 
+
+... you will need to install guizero with the pip command:
+
+- Windows / macOS
+
+    ```
+    pip3 install guizero[images]
+    ```
+
+- Linux / Raspberry Pi
+
+    ```
+    sudo pip3 install guizero[images]
+    ```
+
+### Upgrading
+
+Upgrade guizero using the pip command 
+
+- Windows / macOS
+
+    ```
+    pip3 install guizero --upgrade
+    ```
+
+- Linux / Raspberry Pi
+
+    ```
+    sudo pip3 install guizero --upgrade
+    ```
diff --git a/docs-src/docs/listbox.md b/docs-src/docs/listbox.md
@@ -38,8 +38,8 @@ If you want the `ListBox` to allow multiple items to be selected you must set th
 | enabled     | boolean            | None    | No         | If the widget should be enabled. If `None` (the default) the enabled property will be inherited from the master                                                                                             |
 | multiselect | boolean            | False   | No         | If the widget should allow multiple items to be selected.                                                                                                                                                   |
 | scrollbar   | boolean            | False   | No         | If the widget should have a verticle scrollbar.                                                                                                                                                             |
-| width       | [size](size.md)    | None    | No         | Set the width of the widget in characters or to `"fill"`                                                                                                                                                    |
-| height      | [size](size.md)    | None    | No         | Set the height of the widget in characters or to `"fill"`                                                                                                                                                   |
+| width       | [size](size.md)    | None    | No         | Set the width of the widget in pixels or to `"fill"`                                                                                                                                                    |
+| height      | [size](size.md)    | None    | No         | Set the height of the widget in pixels or to `"fill"`                                                                                                                                                   |
 
 
 ### Methods
@@ -76,12 +76,12 @@ You can set and get the following properties:
 | enabled    | boolean            | `True` if the widget is enabled                                                                                                                                                                                                       |
 | font       | string             | The font of the text                                                                                                                                                                                                                  |
 | 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 to `"fill"`                                                                                                                                                                             |
+| height     | [size](size.md)    | Set the height of the widget in pixels or to `"fill"`                                                                                                                                                                             |
 | items      | List               | Returns a list of items in the ListBox                                                                                                                                                                                                |
 | master     | App or Box         | The container to which this widget belongs                                                                                                                                                                                            |
 | value      | string             | Sets or returns the items selected in a ListBox. Returns `None` if 0 items are selected. If the ListBox is a not `multiselect`, `value` is the item selected, if the ListBox is a `multiselect`, `value` is a list of items selected. |
 | visible    | boolean            | If this widget is visible                                                                                                                                                                                                             |
-| width      | [size](size.md)    | Set the width of the widget in characters or to `"fill"`                                                                                                                                                                              |
+| width      | [size](size.md)    | Set the width of the widget in pixels or to `"fill"`                                                                                                                                                                              |
 | text_size  | int                | The size of the text                                                                                                                                                                                                                  |
 | text_color | [color](colors.md) | The colour of the text                                                                                                                                                                                                                |