UI

This article goes through how to use the Freecode canvas and the UI library.

How to use the canvas

Depending on what skeleton you are using, the way you add your graphics to the canvas differs. The templates for either skeleton will include an example of using the canvas.

If you use BasicChallenge (or no skeleton) you will want to manually add the elements to the canvas, like so:

    def setup_canvas(self):
        self.my_rectangle = Rectangle(x=10, y=10, color="green", parent=self.canvas)

If you use StageChallenge or GameChallenge you will want to return the element in the setup_view method:

    def setup_view(self):
        self.my_rectangle = Rectangle(color="green")
        return self.my_rectangle

Note that you neither specify parent nor position in setup_view, this is done for you

Overview

The UI library is object oriented, meaning that the graphical elements are represented by Python objects. You create a new element by creating a new object and you can modify the elements by modifying the objects. An element will not show up on the canvas unless the object has the canvas as a parent (or grand parent).

A child element will inherit some of the attributes from it's parent. They will be positioned relative to the parent, scaled according to the parent, and opacity of the parent is applied. A child with opacity of 0.5 and with a parent with opacity of 0.5 will in effect have an opacity of 0.25.

When creating an element object, you can (and sometimes must) include a number of attributes. You can use any of the names listed here, e.g. width or w or size_x. The same names can be used to get or modify the attributes later on. Here is an example of this:

my_rect = Rectangle(w=8, h=6, x=10, y=12, parent=self.canvas)
my_rect.width = 4
my_rect.color = "blue"

All elements can have a parent, and some can have children. If an element switches parent it will be removed from the previous parent's list of children. You can either use the parent attribute or the .add_child(child)/.remove_child(child) methods to update the heirarchy. But remember that for an element to show up in the canvas it needs to have it as an ancestor.

The following section and subsections will detail the different elements available in the UI library, grouped by similarities. Many elements have common attributes, which are detailed in their own section to make things cleaner.

Elements

All these elements can be imported from the lib.ui package, along with any of the enums and constants listed here.

As an example:

from lib.ui import Rectangle, Text

my_rect = Rectangle(children=[Text("Hello")])

Remember to add the element to the import list, or you will get an error.

Shapes

These elements are used to make geometric shapes, either filled or outlines. Use Polygon to make additional shapes such as triangles and hexagons. For more complex shapes, consider using images instead.

Rectangle

Use to make squares, rectangles and rounded rectangles.

General attributes: common, container, shape, action, click, drag

corner_radius - float | None S

Add rounded corners to the rectangle

Rectangle(w=10, h=5, x=10, y=10, color="green", corner_radius=1)

Circle

Use to make circles.

General attributes: common, container, shape, action, click, drag

radius/r - float S

The radius of the circle, use instead of width/height

min_radius/min_r - float

The minimum radius for this element, does not affect the current radius

max_radius/max_r - float

The maximum radius for this element, does not affect the current radius

fixed_radius - bool

Prevents automatic resizing of the circle

Circle(r=20, color="blue", stroke=2)

Polygon

Use to make any other straight edge shapes. Consider using images if you need rounded shapes or a large number of points.

General attributes: common, container, shape, action, click, drag

points - list[tuple[float, float]] R

A list of points to use to draw the polygon, required and positional

bounds - tuple[tuple[float, float], tuple[float, float]] S

The bounds of the polygon used to determine size and pivot, calculated if omitted

Polygon([(0, -5), (5, 5), (-5, 5)], color="red")

Text

These elements can be used to display text.

Text

Simple text element. The size is based on the text string and font size.

General attributes: common, action, click, drag

text - str

The text to display, required and positional

color - str

The text color

font_size - float

The text font size

align_x - "left" | "right" | "center"

The horizontal text align

Text("Hello World!", font_size=10, color="yellow")

DynamicText

Alternative to Text where the text is adjusted to fit within the size rather than the other way around. You can use .fit_to_content() to calculate the size based on the text and font size (useful together with min and max size).

General attributes: common, action, click, drag

text - str

The text to display, required and positional

color - str

The text color

font_size - float

The text font size

align_x - "left" | "right" | "center"

The horizontal text align

align_y - "top" | "bottom" | "center"

The vertical text align

DynamicText("Hello World!", font_size=10, color="yellow", w=40, h=10)

HtmlArea

Use to add a block of text that can be formatted using HTML code. If the content is wider or taller than the element size, a scrollbar will appear. It is possible to include images and CSS, using normal HTML syntax.

General attributes: common, scroll

html - str

The HTML text to display, required and positional

font_size - float

The text font size

align_x - "left" | "right" | "center"

The horizontal text align

HtmlArea("Hello <b>World</b>!", font_size=5, w=50, h=20)

Graphics

These elements can be used to display images and animations.

Image

Displays a static image.

General attributes: common, action, click, drag

image - str S

The name of the image to show

color - str

A color to use for tinting the image

Image("TODO", w=30, h=30, opacity=0.75)

Sprite

Displays an animated image.

General attributes: common, action, click, drag

image - str S

The name of the image to show

color - str

A color to use for tinting the image

animation/anim - str S

The name of the animation to play, use "default" for the default animation

start_frame/start - int | None S

An animation frame to start on

end_frame/end - int | None S

An animation frame to end on

Sprite("TODO", w=30, h=30)

Containers

These elements can be used to fit more content in the canvas.

ScrollArea

Use when you want some content to be scrollable (vertical and/or horizontal).

General attributes: common, scroll

scroll = ScrollArea(w=40, h=20)
Text("Hello World!", font_size=20, parent=scroll)

TabArea

Use when you want to split up some content into tabs. Consider putting tab content into ScrollAreas for even more space.

General attributes: common, style

tabs - dict[str, BaseElement]

The tab names and content to include, required and positional, constructor only

font_size - float

The font size to use for the tab headers

red = Rectangle(color="red", children=[Text("R", font_size=20)])
green = Rectangle(color="green", children=[Text("G", font_size=20)])
blue = Rectangle(color="blue", children=[Text("B", font_size=20)])
TabArea({"Red": red, "Green": green, "Blue": blue}, w=30, h=50)

Layouts

These elements can be used to simplify positioning of elements. They handle adddion, removal and resizing of elements as well.

Horizontal

Use to position elements horizontally.

General attributes: common, Layout

All positional arguments are added as children

Horizontal(Rectangle(color="yellow"), Rectangle(color="magenta"), Rectangle(color="cyan"))

Vertical

Use to position elements vertically.

General attributes: common, Layout

All positional arguments are added as children

Vertical(*[Text(str(i)) for i in range(5)], spacing=5)

Grid

Use to position elements in a grid.

General attributes: common, Layout

All positional arguments are added as children

columns - int

Number of columns in the grid, required

Grid(*[Text(str(i)) for i in range(20)], columns=5, w=30, h=30, spacing=5)

Attributes

This section lists the attributes common among several elements, check each element above for which attributes apply.

Container

children - list[BaseElement] R

Elements to add as children

on_add_child - (ChildEventData) -> None E

Called when a (public) child is added to the container

on_remove_child - (ChildEventData) -> None E

Called when a (public) child is removed from the container

Shape

color - str

The fill or stroke color of the shape

stroke - float | None S

Draw the edge of the shape rather than the area

Action

action_effect - Effect | None

Effect to apply when hovering the element and it is interactable

hover_effect - Effect | None

Effect to apply when hovering the element

hover_targets - list[BaseElement]

Elements that will be toggled while this element is hovered

Click

on_click - (ClickEventData) -> None E

Called when this element is clicked in interact mode

click_targets - list[BaseElement]

Elements that will be toggled when this element is clicked

interact_click_targets - list[BaseElement]

Same as click_targets but only works in interact mode

Drag

draggable - bool | None S

Whether the element should be draggable, set to None for default behaviour

on_drop - (DragEventData) -> None E

Called when this element is dropped after being dragged

drag_targets - list[BaseElement]

Elements that will be toggled while this element is dragged

drag_effect - Effect | None

Effect to apply when the element is being dragged

Scroll

widget_color - str

The color of the scroll bars

widget_size - float S

The size of the scroll bars

follow_bottom - bool

If set to True then the area will continue scrolling automatically if at the bottom

Layout

spacing - float

Distance between elements

align_x - "left" | "right" | "center"

The horizontal element align

align_y - "top" | "bottom" | "center"

The vertical element align

Style

style - Style

The style to apply to this element, see Styling