Default image support in appJar assumes no extra libraries, so it only has native support for .GIF and .PPM images.
However, extra code is included to allow the use of .PNG and .JPG files. appJar will convert these to .GIF files, before showing them.
Converting image files is SLOW, so it's best to stick to .GIF files!
Also, converting PNGs is temperamental in Python 2.7 - another reason to avoid.

Getting the path for images right can be TRICKY
It's therefore best to put images in the same folder as your Python code.
Or, create an image folder and set it using the .setImageLocation(location) function.

Built-in icons

appJar has a host of built-in icons you can use.
They are all located in a folder called: gui.icon_path
If you want to use one, you could just use .addIcon() or .addIconButton()
Otherwise, concatenate gui.icon_path with the icon's name and .png

Add Images

app.startLabelFrame("Simple", 0, 0)
app.addImage("simple", "balloons.gif")
from appJar import gui 
from PIL import Image, ImageTk

app = gui()
photo = ImageTk.PhotoImage("images.jpg"))
app.addImageData("pic", photo, fmt="PhotoImage")

Change Images

def changePic(btn):
    if btn == "Reload":
        app.reloadImage("reload", "balloons.gif")

app.startLabelFrame("Reload", 1, 1)
app.addImage("reload", "balloons.gif")
app.addButton("Reload", changePic)
clicked = False
def changePic(btn):
    if btn == "clickme":
        global clicked
        if clicked: app.setImage("clickme", "balloons.gif")
        else: app.setImage("clickme", "balloons2.png")
        clicked = not clicked

app.startLabelFrame("Click Me", 0, 2)
app.addImage("clickme", "balloons.gif")
app.setImageSubmitFunction("clickme", changePic)
app.startLabelFrame("Mouse Over", 0, 1)
app.addImage("mo_1", "balloons.gif")
app.setImageMouseOver("mo_1", "balloons2.png")
def changePic(btn):
    if btn == "Zoom":
        app.zoomImage("Zoom", int(app.getSpinBox("Zoom")))

Image Maps

It is possible to set up a simple ImageMap - a clickable image, with names linked to different areas.
When one of those areas is clicked, a function will be called, passing the name of the area as a parameter.

from appJar import gui

# each list of numbers contains the top left x/y and bottom right x/y
coords = {
    "America":[32, 17, 242, 167],
    "South America":[126, 170, 226, 292],

def click(area):
    app.setLabel("l1", area)

app.addImage("i1", "map.gif")
app.setImageMap("i1", click, coords)
app.addLabel("l1", "<click the map>")

Change Image Animation

If an image is animated, it's possible to control it.

def changePic(btn):
    if btn == "Stop":
        global animated
        if animated:
            app.setButton("Stop", "Start")
            app.setButton("Stop", "Stop")
        animated = not animated

app.startLabelFrame("Animated", 1, 2)
app.addImage("animated", "animated_balloons.gif")
app.addButton("Stop", changePic)

Set Background Images

It's also possible to add a background image to your GUI.
If you have lots of grouped widgets, this can look quite UGLY, as all of the widgets are drawn on top.

Image Caching

appJar employs an image caching mechanism, to speed up image processing.
Every time an image is loaded, it's added to the cache.
The next time an image of the same filename is referenced, it will be loaded from the cache.
This speeds up processes such as mouse-overs, or setting images back-and-forth.

Animated images also have their own internal cache, storing each version of the image.

appJar attempts to preload mouse over images and animated images, to improve smoothness.

If there's ever a need to clear the image cache (maybe reduce memory footprint), call: .clearImageCache()