v1.0 Naming

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

If you combine this with the context manager feature, this becomes possible:

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 should happen:

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

Key Parameters

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:

Positional Parameters

When adding a widget, it is positioned in the first column of a new row.
If you want to change this, you can specify where it should go, either by naming the paramters:

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

Or by passing them as a tuple:

app.label("Main Title", pos=(1, 0))     # ADD a label in row 1, column 0
app.label("Sub Title", pos=(2, 0, 2))   # ADD a label in row 2, column 0, spanning 2 columns
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.
pos list/tuple () Position parameters for the widget, in the order: row, column, colspan, rowspan

GUI Parameters

There are two GUI parameters 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("Title", sticky="", stretch="none")
app.label("SubTitle", sticky="ns", stretch="row")
Parameter Data type Default Description
sticky string <varies> Describes which sides the widget will stick to, one or more of: n, e, w, s in a single string.
stretch string <varies> Describes how the widget will stretch to fill the row/column: none, row, column or all.

Event Parameters

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 should only be the name of the function, don't include any brackets.

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)
Parameter Data type Default Description
change function None A function to call when the widget is changed.
callFunction boolean True Set this to False, when setting the widget to stop the change function form being called.
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.

Other Parameters

There are a couple of other parameter that can be set on widgets.

Parameter Data type Default Description
label boolean/string False Adds a Label before the widget (only some input widgets), either the label's title or the the text of this parameter.
right string None Specify a premade right-click menu to link to the widget.
font integer/dict None Pass either a font size, or a dictionary of font properties to use for this widget's font.

Label


A widget for displaying text in the GUI.

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

Message

A widget for displaying multi-line text in the GUI.
Will automatically wrap the text, based on either the aspect or width settings, defaulting to 50% wider than tall.

Parameter Data type Default Description
aspect integer 150 Set the ratio between the width & height.
width integer None Set the number of characters per line. If None, then the aspect is used to calculate the width.

Entry


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

Parameter Data type Default Description
label boolean/string False Adds a Label before the widget, either the label's title or the the text of this parameter.
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.
labBg string None Special parameter to change the BG of the validation label in a validaiton entry.

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.
label string None Alternative text to display on 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.
Setting this widget won't change the values, but change which one is selected.

Parameter Data type Default Description
kind string standard Set this to ticks if you want tickable options.
selected string/integer None Start with the specified item/position selected.
checked boolean True When setting the widget, this determines what to do to the specified value. None will delete the value.
label boolean/string False Adds a Label before the widget, either the label's title or the the text of this parameter.
disabled string - Sets the character used to indicate disabled menu options.

Spin


Shows a single value, with arrows to scroll up or down, allowing the user to change the value.
Setting this widget won't change the values, but change which one is selected.

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.
label boolean/string False Adds a Label before the widget, either the label's title or the the text of this parameter.

Listbox


Displays a list of items, one (or more than one) of which can be selected.
Setting this widget won't change the values, but change which one is 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.
selected int None The position to select when the listbox is added.

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 values, along its length, in steps of the value specified.
label boolean/string False Adds a Label before the widget, either the label's title or the the text of this parameter.

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 canvas widget.

Parameter Data type Default Description
map dictionary None A dictionary of name:coordinates to use as a canvas map. submit must also be set.

Displays a popUp.

Statusbar


Toolbar


Displays the toolbar.

Parameter Data type Default Description
icons boolean False Determines if appJar should try to find icons for each menu item.
pinned boolean None If set, the toolbar will be pinnable. Setting to True wil start pinned, False not pinned.
disabled boolean False Determines if the toolbar should start disabed or not.
hidden boolean False Determines if the toolbar should start hidden or not. When hidden it is completley removed from the GUI.