more work on pages #356

jarvisteach · Jan 28, 2018 · 8173bf8 · 8173bf8
1 parent 5de2b1b
commit 8173bf8
Show file tree

Hide file tree

Showing 26 changed files with 154 additions and 44 deletions.
diff --git a/docs/mkdocs/docs/widgets/button.md b/docs/mkdocs/docs/widgets/button.md
@@ -9,7 +9,7 @@ A button click is the classic way to start interacting with a GUI.
 Whenever any function is called by the GUI, the title of the widget that called it is passed as a parameter.  
 That way, multiple widgets can use the same function, but different actions can be performed, depending on the name passed as a parameter.
 
-![Buttons](img/1_buttons.gif)
+![Buttons](../img/1_buttons.gif)
 
 ```python
     from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/canvas.md b/docs/mkdocs/docs/widgets/canvas.md
@@ -2,7 +2,7 @@
 ---
 This lets you embed a canvas in appJar
 
-![Canvas](img/1_canvas.png)  
+![Canvas](../img/1_canvas.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/chart.md b/docs/mkdocs/docs/widgets/chart.md
@@ -3,7 +3,7 @@
 Widget to depict a Pie Chart.  
 It will automatically calculate percentages, and draw a pie chart, given a dictionary of items and their amount.  
 The PieChart is purely for display purposes, and is not interactive, other than a simple mouse-over effect with a tooltip.  
-![PieChart](img/dev/pie.png)  
+![PieChart](../img/dev/pie.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/check.md b/docs/mkdocs/docs/widgets/check.md
@@ -2,7 +2,7 @@
 ____
 A simple tick-box, with a label, that can be either ON or OFF.  
 
-![CheckBoxes](img/1_checks.png)  
+![CheckBoxes](../img/1_checks.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/date.md b/docs/mkdocs/docs/widgets/date.md
@@ -1,7 +1,7 @@
 ##DatePicker
 ---
 A widget to capture a date - will handle presenting accurate drop-downs, and return a date.  
-![DatePicker](img/dev/1_cal.png)  
+![DatePicker](../img/dev/1_cal.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/entry.md b/docs/mkdocs/docs/widgets/entry.md
@@ -10,7 +10,7 @@ There are five special-case Entries:
 * ValidationEntry - can be set to valid/invalid/waiting - will colour the border green/red/black and show a ✔/✖/★  
 * FileEntry/DirectoryEntry - provides a button to select a file/directory and auto-populates the Entry  
 
-![Entries](img/1_entries.png)
+![Entries](../img/1_entries.png)
 
 ```python
 from appJar import gui
@@ -62,15 +62,15 @@ app.go()
 * `.setEntryValid(title)` & `.setEntryInvalid(title)` & `.setEntryWaitingValidation(title)`  
     These will set the relevant status of a validation Entry.  
     (Have a look [here](/specialCharacters) for help displaying special characters)  
-    ![EntryValidation](img/entValidation.png)
+    ![EntryValidation](../img/entValidation.png)
 
 * `.setValidationEntry(title, state="valid")`  
     Same as above, set flag to one of `valid`, `invalid` or `wait`.  
 
 * `.setAutoEntryNumRows(title, rows)`  
     This will set the number of rows to display in an AutoEntry.  
     NB. this is limited to the depth of the GUI - if there is no space, then no rows will be displayed. 
-    ![AutoEntry](img/1_autoEntry.png)  
+    ![AutoEntry](../img/1_autoEntry.png)  
 
 * `.appendAutoEntry(title, value)`  
     This will add the value/list of values to the specified AutoEntry.  

diff --git a/docs/mkdocs/docs/widgets/grid.md b/docs/mkdocs/docs/widgets/grid.md
@@ -4,7 +4,7 @@ Used to create a spreadsheet like interface.
 The grid has mouse interactivity, with mouse-over highlighting, and mouse-click highlighting.  
 It is possible to include buttons at the end of each row, and an additional row of entry boxes, with their own button.  
 
-![Grid](img/dev/grid.png)  
+![Grid](../img/dev/grid.png)  
 
 ```python
 from appJar import gui
@@ -27,24 +27,24 @@ app.go()
 
     If `action` is set, a button will be created, at the end of each row, calling the specified function. It will pass the row number (starting at 0).  
 
-    ![Grid](img/dev/grid_2.png)   
+    ![Grid](../img/dev/grid_2.png)   
 
     If `addRow` is set, then an additional row will appear at the end of the grid, with entry boxes and a button to call the specified function.  
     The button will pass the string `newRow` to the specified function.  
 
-    ![Grid](img/dev/grid_3.png)   
+    ![Grid](../img/dev/grid_3.png)   
 
     If both parameters are set to a function, then both buttons at the end of each row and a row of Entry boxes will be shown:  
 
-    ![Grid](img/dev/grid_4.png)   
+    ![Grid](../img/dev/grid_4.png)   
 
     It's also possible to set the following parameters:  
         * `actionHeading` - set the title of the right column  
         * `actionButton` - set the button text for each row  
         * `addButton` - set the button text for the Entry row  
         * `showMenu` - boolean to show a right-click menu  
 
-    ![Grid](img/dev/1_gridMenu.png)   
+    ![Grid](../img/dev/1_gridMenu.png)   
 
 #### Connecting to Databases
 

diff --git a/docs/mkdocs/docs/widgets/grip.md b/docs/mkdocs/docs/widgets/grip.md
@@ -2,7 +2,7 @@
 ____
 Clickable icon to drag the window around.  
 
-![Grip](img/1_grip.png)  
+![Grip](../img/1_grip.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/label.md b/docs/mkdocs/docs/widgets/label.md
@@ -0,0 +1,85 @@
+##Label
+---
+*Labels* are used for displaying text in the GUI.  
+
+* They are great for titles, at the top of the GUI, usually spanning multiple columns.  
+* They are really useful before *Entries* and *Drop-downs* to explain their purpose.  
+* And, they're very helpful at the bottom of the GUI, to show the results of an action.  
+![Label](../img/1_labels.gif)  
+```python
+from appJar import gui
+
+app = gui()
+
+app.addLabel("l1", "Label 1")
+app.addLabel("l2", "Label 2")
+app.addLabel("l3", "Label 3")
+app.addLabel("l4", "Label 4")
+# common set functions
+app.setLabelBg("l1", "red")
+app.setLabelBg("l2", "yellow")
+app.setLabelBg("l3", "purple")
+app.setLabelBg("l4", "orange")
+
+app.go()
+```
+
+####Add Labels
+* `.addLabel(title, text=None)`  
+    This will create a label widget to display text in the GUI.  
+    The `title` is used to uniquely identify the label, in case you want to change it later, and the `text` is what gets displayed.  
+    If `text` is set to None, or no `text` is provided, the `title` will be displayed in the label.  
+
+* `.addEmptyLabel(title)`  
+    Does the same as add a *label*, except there's no parameter to set any text.
+
+* `.addSelectableLabel(title, text=None)`  
+    This adds a label whose text can be selected with the mouse.  
+    This is really just a *read-only* Entry, disguised to look like a label.  
+    But it seems to do the trick...  
+
+* `.addFlashLabel(title, text=None)`  
+    This adds a flashing *label*, that will alternate between the foreground and background colours.
+
+![FlashLabel](../img/1_flash.gif)  
+```python
+from appJar import gui
+
+app = gui()
+
+app.addFlashLabel("f1", "This is flashing")
+app.addLabel("f2", "This is not flashing")
+app.addFlashLabel("f3", "This is also flashing")
+
+app.go()
+```
+
+####Set Labels
+* `.setLabel(title, text)`  
+    Change the contents of the *label*.
+
+* `.clearLabel(title)`  
+    Clear the contents of the *label*.
+
+####Get Labels
+* `.getLabel(title)`  
+    Get the contents of the *label*.
+
+##Auto-Labelled Widgets
+___
+
+It's possible to automatically include a *label* alongside a lot of the  widgets.  
+Both the label and widget will be placed in the same grid space.  
+Simply add the word `Label` to the command when adding the widget:  
+
+* `.addLabelEntry(title)`
+* `.addLabelNumericEntry(title)`
+* `.addLabelSecretEntry(title)`
+* `.addLabelAutoEntry(title, words)`
+* `.addLabelScale(title)`
+* `.addLabelOptionBox(title, values)`
+* `.addLabelTickOptionBox(title, values)`
+* `.addLabelSpinBox(title, values)`
+* `.addLabelSpinBoxRange(title, from, to)`  
+
+See the relevant section for a description of what the widget does.
diff --git a/docs/mkdocs/docs/widgets/link.md b/docs/mkdocs/docs/widgets/link.md
@@ -2,7 +2,7 @@
 ____
 Clickable text to call a function or launch a URL
 
-![Link](img/1_link.png)  
+![Link](../img/1_link.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/listbox.md b/docs/mkdocs/docs/widgets/listbox.md
@@ -3,7 +3,7 @@
 
 A box containing a list of items, single or multi-select
 
-![ListBox](img/1_listBox.png)  
+![ListBox](../img/1_listBox.png)  
 
 ```python
 from appJar import gui
@@ -82,7 +82,7 @@ app.go()
     Sets the background or foreground colours the specified ListBox item.  
     Can either specify a named item (will update all with that name) or the position of an item.  
 
-![LB Colours](img/lbCols.png)  
+![LB Colours](../img/lbCols.png)  
 
 ####Get ListBoxes
 

diff --git a/docs/mkdocs/docs/widgets/maps.md b/docs/mkdocs/docs/widgets/maps.md
@@ -4,7 +4,7 @@ A self-contained GoogleMaps widget.
 It provides useful functionality for finding somewhere on Earth.  
 All requests for map data are performed in the background, so the UI shouldn't become unresponsive.  
 
-![GoogleMaps](img/gmap_2.png)
+![GoogleMaps](../img/gmap_2.png)
 
 ```python
 from appjar import gui

diff --git a/docs/mkdocs/docs/widgets/message.md b/docs/mkdocs/docs/widgets/message.md
@@ -2,7 +2,7 @@
 ____
 Similar to a Label, except it will wrap the text over multiple lines.  
 
-![Message](img/1_mess.png)  
+![Message](../img/1_mess.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/meter.md b/docs/mkdocs/docs/widgets/meter.md
@@ -5,17 +5,17 @@ Various styles of progress meter:
 
 * #### Meter  
 
-    ![Meter](img/1_meter.png)  
+    ![Meter](../img/1_meter.png)  
     A simple meter for showing progress from 0% to 100%.  
 
 * #### SplitMeter  
 
-    ![Meter](img/2_meter.png)  
+    ![Meter](../img/2_meter.png)  
     A possession style meter, showing percentages on either side.  
 
 * #### DualMeter  
 
-    ![Meter](img/3_meter.png)  
+    ![Meter](../img/3_meter.png)  
     Two separate meters, expanding out from the middle.  
 
 ```python

diff --git a/docs/mkdocs/docs/widgets/microbit.md b/docs/mkdocs/docs/widgets/microbit.md
@@ -2,7 +2,7 @@
 ---  
 Widget to emulate a [MicroBit](http://microbit.org)
 
-![MicroBit Emulator](img/mb.png)
+![MicroBit Emulator](../img/mb.png)
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/option.md b/docs/mkdocs/docs/widgets/option.md
@@ -8,7 +8,7 @@ If the first item is empty, a simple title `- options -` will be created.
 Any other empty items will be removed.  
 If an item starts with a dash (-), it will be treated as a separator, and can't be selected.  
 
-![OptionBox](img/1_optBox.png) ![OptionBox](img/2_optBox.png)  
+![OptionBox](../img/1_optBox.png) ![OptionBox](../img/2_optBox.png)  
 
 ```python
 from appJar import gui
@@ -29,7 +29,7 @@ app.go()
     This will create an OptionBox made up of check boxes.  
     The `title` will always be displayed as the *selected* entry in the OptionBox, event though it can't be selected/ticked.  
     Instead of selecting a single item, you tick the ones you want.  
-    ![TickOptionBox](img/3_optBox.png)  
+    ![TickOptionBox](../img/3_optBox.png)  
 
     Calling `.getOptionBox(title)` will return a dictionary of the options along with a True/False value.  
 

diff --git a/docs/mkdocs/docs/widgets/plot.md b/docs/mkdocs/docs/widgets/plot.md
@@ -3,7 +3,7 @@
 
 Support for embedding very basic [MatPlotLib](http://matplotlib.org) plots.  
 
-![Plot](img/1_plot.png)  
+![Plot](../img/1_plot.png)  
 ```python
 from numpy import sin, pi, arange
 from appJar import gui 

diff --git a/docs/mkdocs/docs/widgets/properties.md b/docs/mkdocs/docs/widgets/properties.md
@@ -3,8 +3,8 @@ ____
 A compound widget that shows multiple CheckButtons linked to a dictionary.  
 Note, dictionaries have no order, so when added as a dictionary, the items will be automatically sorted.  
 
-![Properties](img/1_props.png)
-![Properties](img/2_props.png)
+![Properties](../img/1_props.png)
+![Properties](../img/2_props.png)
 
 ```python
 from appJar import gui
@@ -74,9 +74,9 @@ app.go()
 ####Examples
 It's possible to put Properties into ToggleFrames, and also set a Function to listen for any changes.  
 
-![Properties](img/3_props.png)
-![Properties](img/4_props.png)
-![Properties](img/5_props.png)
+![Properties](../img/3_props.png)
+![Properties](../img/4_props.png)
+![Properties](../img/5_props.png)
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/radio.md b/docs/mkdocs/docs/widgets/radio.md
@@ -3,7 +3,7 @@ ____
 A group of round boxes, only one of which can be selected.  
 These are great for getting a single value, for a multiple choice question.  
 
-![Radios](img/t_radios.png)  
+![Radios](../img/t_radios.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/scale.md b/docs/mkdocs/docs/widgets/scale.md
@@ -2,7 +2,7 @@
 ____
 A slider, that has a minimum & maximum value.  
 
-![Scale](img/1_scale.png)  
+![Scale](../img/1_scale.png)  
 
 ```python
 from appJar import gui
@@ -33,16 +33,16 @@ app.go()
 * `.showScaleIntervals(title, intervals)`  
     Configures the Scale to show interval labels along its length.  
     `intervals` should be how often to show a value, eg. `25` would show 0, 25, 50, and so on...  
-    ![Scale](img/4_scale.png)  
+    ![Scale](../img/4_scale.png)  
 
 * `.showScaleValue(title, show=True)`  
     Configures the Scale to show the currently selected value.  
-    ![Scale](img/2_scale.png)  
+    ![Scale](../img/2_scale.png)  
 
 * `.setScaleHorizontal(title)` & `.setScaleVertical(title)`  
     Changes the Scale's orientation to the specified value.  
 
-    ![Scale](img/3_scale.png)  
+    ![Scale](../img/3_scale.png)  
 
 * `.setScaleWidth(title, width)` & `.setScaleLength(title, length)`  
     Sets a width/length for the scale's slider.  

diff --git a/docs/mkdocs/docs/widgets/separator.md b/docs/mkdocs/docs/widgets/separator.md
@@ -2,7 +2,7 @@
 ____
 Useful for indicating separation between widgets.  
 Will draw a horizontal/vertical line spanning the cell.  
-![Separator](img/1_sep.png)  
+![Separator](../img/1_sep.png)  
 
 ```python
 from appJar import gui

diff --git a/docs/mkdocs/docs/widgets/spin.md b/docs/mkdocs/docs/widgets/spin.md
@@ -3,7 +3,7 @@ ____
 A scrollable list of options. Up and down buttons are provided to scroll from one item to the next.  
 Unlike the OptionBox, you do not get a drop-down of choices, instead it spins to the next/previous option.  
 
-![SpinBox](img/1_spinBox.png)  
+![SpinBox](../img/1_spinBox.png)  
 
 ```python
 from appJar import gui
@@ -21,7 +21,7 @@ app.go()
 * `.addSpinBoxRange(title, from, to)`  
     This will create a SpinBox, with a numeric range of items.  
 
-    ![SpinBox](img/3_spinBox.png)  
+    ![SpinBox](../img/3_spinBox.png)  
 
 ```python
     from appJar import gui