Output 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 - we've grouped them into output widgets & input widgets.

Output widgets are used for displaying information to a user.

They usually provide three functions:

As well as options to change the way they look/act.

For each of the above to work, we need to know which widget you are referring to - so every widget gets a unique title.

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.

Message

Very similar to a Label, except it will wrap the text over multiple lines.
By default the text is laid out 50% wider than it is high.
This can be changed by setting a specific width or by changing the aspect ratio.

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

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)

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

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

Canvas

This lets you embed a canvas in appJar.
Canvases are very powerful, appJar will never provide wrappers for all their functions.
So, if you're looking to truly harness a canvas, add it and save the widget as a variable: canvas = app.addCanvas("c1"). Then, you can call all the canvas functions as you would a tKinter canvas.

Canvas 

from appJar import gui
app=gui()
app.addCanvas("c1")
app.addCanvasOval("c1", 10, 10, 100, 100, fill="red", outline="blue", width=3)
app.addCanvasLine("c1", 0, 0, 255, 255, width=5)
app.addCanvasLine("c1", 0, 255, 255, 0, dash=123)
app.go()

Or, as mentioned above, you can work directly with the canvas object: 

from appJar import gui
app=gui()
canvas = app.addCanvas("c1")
canvas.create_oval(10, 10, 100, 100, fill="red", outline="blue", width=3)
canvas.create_line(0, 0, 255, 255, width=5)
canvas.create_line(0, 255, 255, 0, dash=123)
app.go()

Setting a Canvas

Drawing on a Canvas

NB. each of these functions returns the object being created, so you can later change it:

canvas = app.addCanvas("c1")
rect = app.addCanvasRectangle("c1", x=40, y=80, w=100, h=100, fill='green')
canvas.itemconfig(rect, fill='pink')

Turtle

This lets you embed a turtle widget in appJar.

Turtle 

from appJar import gui 

def press(b):
    s = app.getTurtleScreen("t1")
    t = app.getTurtle("t1")
    s.bgcolor("blue")
    t.pencolor("white")
    for i in range(20):
        t.forward(i * 10) 
        t.right(144)

app=gui()
app.addTurtle("t1")
app.addButton("DRAW", press)
app.go()

MicroBit Emulator

Widget to emulate a MicroBit

MicroBit Emulator

from appJar import gui

app = gui()
app.addMicroBit("mb1")
app.setMicroBitImage("mb1", "09090:90909:90009:09090:00900")
app.go()

Add MicroBits

Set MicroBits

GoogleMaps

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

from appjar import gui

app = gui()
app.addGoogleMap("m1")
app.setGoogleMapSize("m1", "300x500")
app.go()

Add GoogleMaps

Set GoogleMaps

Get GoogleMaps

Save GoogleMaps

PieChart

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 

from appJar import gui

app = gui()
app.addPieChart("p1", {"apples":50, "oranges":200, "grapes":75,
                        "beef":300, "turkey":150})
app.go()

Add PieCharts

Set PieCharts

MatPlotLib

Support for embedding very basic MatPlotLib plots.

Plot 

from numpy import sin, pi, arange
from appJar import gui 
import random

def getXY():
    x = arange(0.0, 3.0, 0.01)
    y = sin(random.randint(1,10) * pi * x)
    return x,y 

def generate(btn):
    # *getXY() will unpack the two return values
    # and pass them as separate parameters
    app.updatePlot("p1", *getXY())
    showLabels()

def showLabels():
    axes.legend(['The curve'])
    axes.set_xlabel("X Axes")
    axes.set_ylabel("Y Axes")
    app.refreshPlot("p1")

app = gui()
axes = app.addPlot("p1", *getXY())
showLabels()
app.addButton("Generate", generate)
app.go()

from appJar import gui 
from mpl_toolkits.mplot3d import Axes3D

with gui() as app:
    fig = app.addPlotFig("p1")
    ax = fig.add_subplot(111, projection='3d')
    ax.scatter([1,2],[1,2],[1,2])