appJar v1.0

Some features we are working towards in the 1.0 release, are a simplified way of adding, setting & getting widgets.
Each widget will have a single function that supports all three actions.

We're also simplifying GUI settings, exposing most settings as properties, as well as letting them be passed in the constructor.
This is available for BETA testing in the current release, but still needs a bit of work.

If you combine this with the context manager feature, building GUIs is getting even easier:

from appJar import gui 

def press(btnName):
    app.popUp("INFO", "You pressed " + btnName)

def update(value):
    if value == "list": app.slider("slider", app.listbox(value)[0])
    elif value == "slider": app.listbox("list", app.slider(value))
    app.label("display", app.listbox("list")[0])

with gui("Version 1.0", bg="teal") as app:
    app.label("Version 1.0 Demo", colspan=2, bg="red")
    with app.labelFrame("Big Buttons", colspan=2, sticky="news", expand="both"):
        app.button("BUTTON A", press)
        app.button("BUTTON B", press)
        app.button("BUTTON C", press)
    app.listbox("list", [1, 2, 3, 4, 5], rows=5, selected=0, submit=update)
    app.label("display", "1", row=2, column=1, bg="yellow", sticky="news")
    app.slider("slider", colspan=2, range=(1,5), change=update, interval=1)

SimpleAppJar

Operation

As demonstrated above, each widget now has a single function - the name of the widget.
Call this function passing one or both of the key parameters, to determine what will happen:

app.label("title", "text")      # ADD a label if the title is new
app.label("title", "text_2")    # SET a label if the title exists
print(app.label("title"))       # GET a label if no widget is being created or set

The two key parameters are:

Parameter Data type Description
title string A unique identifier for that widget type.
value string Any relevant information for the widget.

The logic is as follows:

Positioning

When adding a widget, it's also possible to set its position.
When no position is specified, each widget goes in the first column of a new row. 

app.label("title", "text", row=2, column=4, rowspan=3)      # ADD a label

The following positional parameters are available when adding widgets:

Parameter Data type Default Description
row integer <next row> The grid row to place the widget in.
column integer 0 The grid column to place the widget in.
rowspan integer 1 The number of grid rows to stretch the widget across.
colspan integer 1 The number of grid columns to stretch the widget across.

Alternatively, they can be specified as a tuple: 

app.label("title0", "text", pos=(1, 0))      # ADD a label in row 1, column 0
app.label("title2", "text", pos=(1, 1))      # ADD a label in row 1, column 1
app.label("title3", "text", pos=(2, 0, 2))   # ADD a label in row 2, column 0, spanning 2 columns
Parameter Data type Default Description
pos list/tuple () Position parameters for the widget, in the order: row, column, colspan, rowspan

GUI Properties

There are two GUI properties which affect how widgets are displayed sticky and stretch.
These can be modified when adding a widget, just bear in mind they are GUI settings, and will affect all future widgets in the current container. 

app.label("title0", "text", sticky="", stretch="none")
app.label("title2", "text", sticky="ns", stretch="row")
Parameter Data type Default Description
sticky string <Container specific> Describes which sides the widget will stick to, one or more of: n, e, w, s in a single string.
stretch string <Container specific> Describes how the widget will stretch to fill the row/column: none, row, column or all.

Events

Most of the widgets also have some support for events (see the events page for more information).
submit & change will pass the name of the widget to the function, drop will pass the data to the function:
NB. the parameter is only the name of the function, don't include any brackets.

Parameter Data type Default Description
change function None A function to call when the widget is changed.
submit function None A function to call when the widget is submitted.
over function (list) None A function to call when the mouse enters the widget, with an optional second function to call when the mouse leaves.
drop boolean/function None Update the widget with dropped data if True, otherwise call the function.
drag function (list) None A function to call call when the widget is dragged, with an optional second function to call when the widget is dropped. 
def update(name):
    if name == "size":
        updateSize()
    elif name == "toppings":
        updateToppings()

app.listbox("size", ["small", "medium", "large"], change=update)
app.listbox("toppings", ["corn", "cheese", "peppers"], change=update)
app.image("img1", "placeholder.gif", drop=True)

Label

A widget for displaying text in the GUI.

Parameter Data type Default Description
kind string standard Set to selectable or flash to create different labels.

Message

A widget for displaying multi-line text in the GUI.

Entry

An interactive widget, for capturing user input in the GUI.

Parameter Data type Default Description
label boolean False Adds a Label before the widget.
kind string standard One of: standard, file, directory, numeric, auto or validation.
secret boolean False Configures the entry box to show stars instead of characters.
default string None Sets default text to display in an empty entry.
focus boolean False Should the entry box be given focus?
rows integer 10 If the kind is auto this will set the number of rows to show.

There are also some validation settings that can be applied:

Parameter Data type Default Description
limit integer None Sets a maximum limit on the number of characters that can be entered.
case string None Set to upper to force uppercase or lower to force lowercase.

Text

An interactive widget, for capturing multi-line user input in the GUI.

Parameter Data type Default Description
scroll boolean False Will configure this as a scrollable text area.

Button

A clickable button for triggering events.

Parameter Data type Default Description
image string None A path to an image to show in the button.
icon string None The name of an icon to show in the button.

A clickable hyperlink to trigger events or launch webpages.

Check

A checkbox style widget, that can be checked/unchecked.

Radio

Radio buttons are used in groups, only one of them can be checked.
By default, the first radio button added to a group will be selected.

Parameter Data type Default Description
selected boolean False Should this radio be selected?

Option

When clicked, displays a drop-down of items, one of which can be selected.

Parameter Data type Default Description
kind string standard Set this to ticks if you want tickable options.

Spin

Shows a single value, with arrows to scroll up or down, allowing the user to change the value.

Parameter Data type Default Description
endValue integer None If specified, value & endValue should be integers, and will be used to generate a range.
pos integer 0 The position of an item to select.
item string None The name of an item to select.

Listbox

Displays a list of items, one (or more than one) of which can be selected.

Parameter Data type Default Description
rows integer None Specifies how many rows to display in the listbox.
multi boolean False Set the listbox to be multi-selectable.
group boolean False Set the listbox to be part of a group.

Slider

A draggable widget, where the user can select a number from a range.

Parameter Data type Default Description
direction string horizontal Set the direction of the slider: vertical or horizontal.
show boolean False Show the slider's value above the slider.
increment integer 10 Configures how much the slider jumps, when the trough is clicked.
interval integer None Configures the slider to show interval values, along its length. In steps of the value specified.

Meter

Various styles of progress meter.

Parameter Data type Default Description
text string None Set text to show on the meter.
kind string standard Choose the kind of meter: standard, split or dual.
fill boolean None Set the fill colour(s) for the slider (a list of two colours for split & dual).

Grip

Displays a draggable icon, which allows the GUI to be moved.

Separator

Displays a line, giving visual separation in the GUI.

Parameter Data type Default Description
direction string horizontal Set the orientation of the separator: horizontal or vertical.

Image

Displays a picture.

Parameter Data type Default Description
kind string standard The kind of image, one of: icon, data or standard.
fmt string None If the kind is data this will be used to determine the file type.
compound string None Can be set to a position to show the title as well (top, bottom, left, right or center).
speed integer None If this is an animated image, the FPS to animate the image at.
over string None The path to an alternative image to show, when the mouse goes over the image.
map dictionary None A dictionary of name:coordinates to use as an image map. submit must also be set.

Properties

Displays a list of checkboxes, stored in a dictionary.

Date

Displays a simple date picker widget.

Canvas

Displays a the canvas widget.

Displays a popUp.

GUI Properties

Most of the setters & getters for GUI/widget configuration will now be available as properties.
This allows them to be set in a slightly simpler way:

app.title = "Property Demo"
app.bg = "red"
app.fg = "yellow"
Property Data type Description
title string Pass a string for the title of the GUI
icon string Pass the path to an icon file
transparency integer Pass a percentage (between 0 & 100) to set the transparency
visible boolean Pass either True or False
padding integer (list) Pass a tuple containing the x & y padding or a single integer for both x & y
inPadding integer (list) Pass a tuple containing the x & y padding or a single integer for both x & y
guiPadding integer (list) Pass a tuple containing the x & y padding or a single integer for both x & y
size integer (list) Pass a tuple containing the width & height (or the string fullscreen)
location integer (list) Pass a tuple containing the x & y coordinates (or the string CENTER)
fullscreen boolean Pass either True or False
resizable boolean Pass either True or False
sticky string Pass a string describing which sides to stick to (news).
stretch string Pass a string describing if rows/columns should stretch.
fg string Pass a colour to use for the text colour of all label style widgets.
bg string Pass a colour to use for the background of all label style widgets.
font integer Pass a value to set the size of the font.
buttonFont integer Pass the font size to use for all button style widgets.
labelFont integer Pass the font size to use for all label style widgets.
ttkTheme string Only available in ttk mode - pass the name of the ttk theme you want to use.
row integer Gets or sets the next row number to be used.