Widgets

In a GUI, the fillings are known as widgets.
There are lots of different widgets to choose from, each suited to a specific task.

Nearly every widget needs a TITLE.
This is a unique name for the widget, so that later you can get information from that widget, or change it.

Nearly all widgets in appJar provide the same three functions:

On top of these, there is a common set of functions for changing widgets.
As well as some specialist functions, unique to each widget (see below).

Label

Labels are used for displaying text in the GUI. 

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

FlashLabel 

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

Get Labels

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:

See the relevant section for a description of what the widget does.

Entry

Entries are used to capture input from the user. They take a single parameter - a title.

There are five special-case Entries:

Entries

from appJar import gui

app=gui()

app.addEntry("e1")
app.addEntry("e2")
app.addEntry("e3")
app.addLabelEntry("Name")
app.addValidationEntry("v1")
app.addFileEntry("f1")

app.setEntryDefault("e2", "Age here")
app.setEntryValid("v1")

app.go()

Add Entries

Set Entries

Get Entries

Advertisement why?

Button

A clickable button, that will call a function.
These are the key to starting an interactive application.
The GUI is looping, waiting for something to happen.
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

    from appJar import gui

    # the title of the button will be received as a parameter
    def press(btn):
        print(btn)

    app=gui()
    # 3 buttons, each calling the same function
    app.addButton("One", press)
    app.addButton("Two", press)
    app.addButton("Three", press)
    app.go()

Add Buttons

Set Buttons

RadioButton

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 

from appJar import gui

app=gui()
app.addRadioButton("song", "Killer Queen")
app.addRadioButton("song", "Paradise City")
app.addRadioButton("song", "Parklife")
app.go()

Add RadioButtons

Set RadioButtons

Get RadioButtons

    from appJar import gui

    def press(rb):
        print(app.getRadioButton("song"))

    app=gui()
    app.addRadioButton("song", "Killer Queen")
    app.addRadioButton("song", "Paradise City")

    # call this function, when the RadioButton changes
    app.setRadioButtonChangeFunction("song", press)

    app.addButton("PLAY", press)
    app.go()

CheckBox

A simple tick-box, with a label, that can be either ON or OFF.

CheckBoxes 

from appJar import gui

app=gui()
app.setFont(20)

app.addCheckBox("Apples")
app.addCheckBox("Pears")
app.addCheckBox("Oranges")
app.addCheckBox("Kiwis")

app.setCheckBox("Oranges")

app.go()

Add CheckBoxes

Set CheckBoxes

Get CheckBoxes

OptionBox

Creates a simple drop-down box.
It is only possible to select one option from this drop-down.
Pass in a list of values to show in the drop-down box.
They will be added in the same order, with the first item shown.
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 OptionBox 

from appJar import gui

app=gui()
app.setFont(20)
app.addLabelOptionBox("Options", ["- Fruits -", "Apple", "Orange",
                        "Pear", "kiwi", "- Pets -", "Dogs", "Cats",
                        "Fish", "Hamsters"])
app.go()

Add OptionBoxes

from appJar import gui

def get(btn):
    print(app.getOptionBox("Favourite Pets"))

app=gui()
app.setFont(20)
app.addTickOptionBox("Favourite Pets", ["Dogs", "Cats", "Hamsters", "Fish"])
app.addButton("GET", get)
app.go()

Set OptionBoxes

Get OptionBoxes

SpinBox

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 

from appJar import gui

app=gui()
app.setFont(20)
app.addLabelSpinBox("options", ["Apple", "Orange", "Pear", "kiwi"])
app.go()

Add SpinBoxes

    from appJar import gui

    app=gui()
    app.setFont(20)
    app.addSpinBoxRange("Numbers", 1, 12)
    app.go()

Set SpinBoxes

Get SpinBoxes

Advertisement why?

ListBox

A box containing a list of items, single or multi-select

ListBox 

from appJar import gui

app=gui()
app.setFont(20)
app.addListBox("list", ["apple", "orange", "pear", "kiwi"])
app.go()

Add ListBoxes

Set ListBoxes

from appJar import gui
def press(btn):
    items = app.getListItems("list")
    if len(items)> 0:
        app.removeListItem("list", items[0])

app=gui()
app.setFont(20)
app.addListBox("list", ["apple", "orange", "pear", "kiwi"])
app.addButton("press",  press)
app.go()

LB Colours

Get ListBoxes

Scale

A slider, that has a minimum & maximum value.

Scale 

from appJar import gui

app=gui()
app.setFont(20)
app.addLabelScale("scale")
app.go()

Add Scales

Set Scales

Get Scales

Message

Similar to a Label, except it will wrap the text over multiple lines.

Message 

from appJar import gui

app=gui()
app.setFont(12)
app.addMessage("mess", """You can put a lot of text in this widget.
The text will be wrapped over multiple lines.
It's not possible to apply different styles to different words.""")
app.go()

Add Messages

Set Messages

TextArea

Similar to an Entry, but allows you to type text over multiple lines.

TextArea 

from appJar import gui

app=gui()
app.addTextArea("t1")
app.go()

Add TextAreas

ScrolledTextArea

Set TextAreas

Get TextAreas

Advertisement why?

Meter

Various styles of progress meter: 

from appJar import gui

app=gui()
app.addMeter("progress")
app.setMeterFill("progress", "blue")
app.go()

Add Meters

Set Meters

Get Meters

Background Processing

Meters are designed to show progress over time.
One common solution is to register a function that is constantly updating a meter.
This should then be monitoring/updating a global variable: 

def updateMeter():
    app.setMeter("progress", percentComplete)

# schedule function to be called regularly
app.registerEvent(updateMeter)

Properties

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 Properties

from appJar import gui

toppings={"Cheese":False, "Tomato":False, "Bacon":False,
            "Corn":False, "Mushroom":False}

app=gui()
app.setBg("lightBlue")
app.setFont(20)
app.addProperties("Toppings", toppings)
app.setProperty("Toppings", "Pepper")
app.go()

Add Properties

Set Properties

Get Properties

Examples

It's possible to put Properties into ToggleFrames, and also set a Function to listen for any changes.

Properties Properties Properties

from appJar import gui

def changed(props):
    print("Changed", props)

toppings={"Cheese":False, "Tomato":False, "Bacon":False,
            "Corn":False, "Mushroom":False}

app=gui()
app.setBg("lightBlue")
app.setFont(20)

app.startToggleFrame("Toppings")
app.addProperties("Toppings", toppings)
app.setPropertiesChangeFunction("Toppings", changed)
app.stopToggleFrame()

app.go()

Separator

Useful for indicating separation between widgets.
Will draw a horizontal/vertical line spanning the cell.
Separator 

from appJar import gui

app=gui()
app.setBg("lightBlue")
app.addHorizontalSeparator(0,0,4, colour="red")
app.addVerticalSeparator(1,0, colour="red")
app.addVerticalSeparator(1,1, colour="red")
app.addVerticalSeparator(1,2, colour="red")
app.addVerticalSeparator(1,3, colour="red")
app.addHorizontalSeparator(2,0,4, colour="red")
app.go()

Add Seperators

Clickable text to call a function or launch a URL

Link 

from appJar import gui
def press(link):
    app.infoBox("Info", "You clicked the link!")

app=gui()
app.setFont(20)
app.addLink("Click me", press)
app.addWebLink("appJar.info", "http://appJar.info")
app.go()

Grip

Clickable icon to drag the window around.

Grip 

from appJar import gui

app=gui()
app.setFont(20)
app.setBg("lightBlue")

app.addLabel("l1", "Move me around...", 0, 0)
app.addGrip(0,1)
app.addSeparator(1,0,2, colour="red")
app.go()

Add Grips

DatePicker

A widget to capture a date - will handle presenting accurate drop-downs, and return a date.
DatePicker 

from appJar import gui

def showDate(btn):
    print(app.getDatePicker("dp"))

app=gui()
app.addDatePicker("dp")
app.addButton("GET", showDate)
app.setDatePickerRange("dp", 1900, 2100)
app.setDatePicker("dp")
app.go()

Add DatePickers

Set DatePickers

Get DatePickers