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 some 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.
focus boolean False Give keyboard focus to the widget.
tip string None Sets text to show in a mouse-over tooltip.

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
kind string standard One of: standard, open, save, 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.
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.
text string None Special parameter to change the text of the file entry button.

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.
tags list [] A list of tags, where each tag contains a name and dictionary of values.
end boolean True Whether to add the new text to the end (True) or beginning (False)
replace boolean False Will replace any existing text in the text area when updating.

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
kind string standard Set this to square to change the style of the radio buttons.
Not supported in ttk or on Mac.
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.
disabled string - Sets the character used to indicate disabled menu options.
checked boolean True When setting the widget, this determines what to do to the specified value. None will delete the value.
mode string select One of: select, change, rename. clear or delete - see below.

Different modes can be used when setting the widget:
select - the default, the specified value will be selected.
 clear - deselects all items in the option box.
change - the contents of the list will be replaced with a new listi, with an optional index.
 rename - this will change the text of an item in the option box, to the newName.
* delete - this will delete the specified option from the option box.

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.
selected 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.
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.
mode string select One of: select, change, rename. clear or delete - see below.

Different modes can be used when setting the widget:
select - default, select the specified item(s) or all
 deselect - deselect the specified item(s), or all
toggle - toggle the specified item(s), or all
 clear - clear any selected items rename - rename the specified item
 replace - replace all items
add - add the specified item(s) delete - delete the specified item, or all

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.
range list/tuple () Sets a start value and end value for the slider.

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.
colour string None Set a colour for the separator.

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/list False Determines if appJar should try to find icons for each menu item (True) or a list of icon names.
status list [] The enabled status of each button (False to disable).
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.

Displays a menubar

Parameter Data type Default Description
kind string button The type of item to add: button, sub, menu, sep, check, radio
group string None Only used for radio buttons, the group to add the button to.
It's not necessary to set kind if this is set.
shortcut string None A keyboard shortcut, to associate with the menu item.
underline int -1 Which letter in the item name to underline (not all platforms).
tear boolean False Only used for toplevel menus, configures them to be tearable (not all platforms).
state string "enabled" Whether the menu item should be enabled or disabled
image string None The path to an image to put alongside the menu item.
icon string None The name of an icon to put alongside the menu item.
align string "left" If an image/icon is added, how to align it alongside the text.

Tree

Displays the tree widget.

Parameter Data type Default Description
click function None A function to call when a node is clicked.
dbl function None A function to call when a node is double-clicked.
edit function None A function to call when a node is edited.
editable boolean None Determines if nodes are editable or not.
attributes boolean None Determines if attributes should be shown in the tree.
fg string None The foreground colour of the widget.
bg string None The background colour of the widget.
fgH string None The foreground colour of a selected node.
bgH string None The background colour of a selected node.

Plot

Displays matplotlib widgets.

Parameter Data type Default Description
t list None The x values if required.
s list None The y values if required.
width int None A width for the plot.
height int None A height for the plot.
nav boolean false Whether to show a navigation bar or not.