browsergui.elements package

Module contents

Defines many types of GUI elements.

Element Index

Basic

Simple, static, atomic GUI elements.

Text(text[, tag_name])	A piece of text with no structure inside it.
Paragraph(text, **kwargs)	A block of plain text.
CodeSnippet(text, **kwargs)	Inline text representing computer code.
CodeBlock(text, **kwargs)	A block of computer code.
EmphasizedText(text, **kwargs)	Text that should have emphasis on it.
Link(text, url, **kwargs)	A hyperlink.
Image(filename[, format])

Input

Elements that gather input from the user.

Button([text, callback])	A simple button that does something when clicked.
TextField([value])	A single-line text input field.
BigTextField([value, placeholder, ...])	A multi-line text field.
Dropdown(options[, change_callback])	A dropdown-selector for a set of options (strings).
NumberField([value])
ColorField([value, placeholder])
DateField([placeholder])
FloatSlider(min, max[, value])	A type of Slider that accepts real-valued values/bounds (e.g.
IntegerSlider(min, max[, value])	A type of Slider that accepts only integer values/bounds.

Layout

Elements that arrange their children in certain ways.

Container(*children, **kwargs)	Contains other elements without any fancy layout stuff.
Viewport(target, width, height, **kwargs)	A scrollable window into some other (probably big) element.
List([items, numbered])	A list of elements.
Grid([cells, n_rows, n_columns])	A two-dimensional grid of elements.

Element Class

The most important thing defined here, from which all other things inherit, is Element.

class browsergui.elements.Element(css={}, callbacks={}, **kwargs)

A conceptual GUI element, like a button or a table.

ancestors

Lists the object’s parent, parent’s parent, etc.

callbacks = None

a dict-like object mapping Event subclasses to functions that should be called when the corresponding event occurs.

>>> my_element.callbacks[Click] = (lambda event: print('Click:', event))

children

A list of the element’s immediate children, in depth-first order.

css = None

a dict-like object mapping strings (CSS properties) to strings (CSS values).

>>> my_text.css['color'] = 'red'

gui

The GUI the element belongs to, or None if there is none.

id

A unique identifying string.

mark_dirty()

Marks the element as needing redrawing.

orphaned

Whether the element has no parent.

parent

The element whose tag contains this element’s tag (or None)

root

The uppermost ancestor of the element (i.e. the one with no parent).

walk()

Iterates over the element and all the elements below it in the tree.

Full Subclass Documentation

class browsergui.elements.Text(text, tag_name='span', **kwargs)

A piece of text with no structure inside it.

The currently displayed string may be accessed or changed via the text attribute.

If you want to be fancy, a Text instance can represent any HTML tag that contains only plain text. For instance, Button subclasses Text, even though it’s not just a plain piece of text.

Parameters:text (str) – the text to display

text

The string to be displayed.

class browsergui.elements.Paragraph(text, **kwargs)

A block of plain text.

class browsergui.elements.CodeSnippet(text, **kwargs)

Inline text representing computer code.

class browsergui.elements.CodeBlock(text, **kwargs)

A block of computer code.

class browsergui.elements.EmphasizedText(text, **kwargs)

Text that should have emphasis on it.

class browsergui.elements.Link(text, url, **kwargs)

A hyperlink.

url

The URL to which the link points.

class browsergui.elements.Image(filename, format=None, **kwargs)

data

The raw image data, as bytes.

reload_data()

Reads image contents from disk, in case they’ve changed.

class browsergui.elements.InputField(tag_name='input', value=None, placeholder=None, change_callback=None, **kwargs)

An abstract class for elements that conceptually contain a value (string, number, color...)

Many kinds of input (e.g. TextField, Slider, DateField) inherit from this, or at least pretend to.

Parameters:change_callback (function of zero arguments) – function to be called whenever the input’s value changes

def_change_callback(f)

Decorator to set the InputField’s change_callback.

>>> text_field = TextField()
>>> @text_field.def_change_callback
... def _():
...   print("Current value: " + text_field.value)

placeholder

The placeholder text that should be shown when the field is empty.

Applicable to many, but not all, kinds of InputField.

value

The value currently entered into the field.

Setting the value fires the field’s change_callback.

class browsergui.elements.Button(text='Click!', callback=None, **kwargs)

A simple button that does something when clicked.

The text and callback fields may be safely set at any time.

Parameters:

• text (str) – the label of the button
• callback (function of zero arguments, or None) – the function to be called

def_callback(f)

Decorator to set the Button’s callback.

>>> button = Button()
>>> @button.def_callback
... def _():
...   print("Button was clicked!")

class browsergui.elements.TextField(value='', **kwargs)

A single-line text input field.

For multi-line text input, see BigTextField, which has a very similar interface.

class browsergui.elements.BigTextField(value='', placeholder='', change_callback=None, **kwargs)

A multi-line text field.

Like InputField elements, has a value, a placeholder, and a change_callback.

class browsergui.elements.Dropdown(options, change_callback=None, **kwargs)

A dropdown-selector for a set of options (strings).

Like InputField elements, a Dropdown has a value, a placeholder, and a change_callback. Also, a Dropdown is a mutable sequence, meaning most things you can do to lists (append, get/set/delitem), you can do to Dropdowns too.

def_change_callback(f)

Decorator to set the Dropdown’s change_callback

class browsergui.elements.NumberField(value=None, **kwargs)

class browsergui.elements.ColorField(value=(0, 0, 0), placeholder='#xxxxxx', **kwargs)

class browsergui.elements.DateField(placeholder='yyyy-mm-dd', **kwargs)

class browsergui.elements.Slider(min, max, value=None, **kwargs)

A draggable slider.

Any attempted assignment to min, max, or value that would violate min <= value <= max will fail and instead raise a ValueError.

Don’t instantiate; you probably want FloatSlider or IntegerSlider. You can also define your own subclasses for other data types: see this tutorial.

Parameters:

• min – the smallest value the slider can accept. Writable.
• max – the largest value the slider can accept. Writable.

class browsergui.elements.FloatSlider(min, max, value=None, **kwargs)

A type of Slider that accepts real-valued values/bounds (e.g. float, int, fractions.Fraction).

When the user drags the slider, the value is set to a float.

class browsergui.elements.IntegerSlider(min, max, value=None, **kwargs)

A type of Slider that accepts only integer values/bounds.

class browsergui.elements.Container(*children, **kwargs)

Contains other elements without any fancy layout stuff.

Useful when you want to put several elements in a place that can only hold one element (e.g. if you want a List item consisting of multiple elements, or if you want to put multiple elements in a Grid cell).

Subclasses MutableSequence, which means that most operations you’d do to a list (e.g. insert, remove, get/set/delitem), you can do to a Container as well.

Parameters:children – Elements the Container should contain

class browsergui.elements.Viewport(target, width, height, **kwargs)

A scrollable window into some other (probably big) element.

height

The Viewport’s height, in pixels.

target

The Element being viewed through the Viewport.

width

The Viewport’s width, in pixels.

class browsergui.elements.List(items=(), numbered=False, **kwargs)

A list of elements.

May be numbered or bulleted, according to the numbered property (a boolean).

Supports pretty much all the operations that a normal list does, e.g.

my_list = List(items=[first, second]) my_list.append(third) my_list.insert(0, new_first) assert my_list[0] is new_first my_list[1] = new_second del my_list[2]

class browsergui.elements.Grid(cells=(), n_rows=None, n_columns=None, **kwargs)

A two-dimensional grid of elements.

A grid’s number of rows and columns are given by n_rows and n_columns. Those properties may also be set, to change the number of rows and columns.

Grids are indexable by pairs of non-negative integers, e.g.

>>> my_grid[0, 0]
>>> my_grid[3, 2] = Text('hi')
>>> my_grid[1, 2] = None
>>> del my_grid[3, 3]

class browsergui.elements.Element(css={}, callbacks={}, **kwargs)

Bases: browsergui.elements._xmltagshield.XMLTagShield

A conceptual GUI element, like a button or a table.

callbacks = None

a dict-like object mapping Event subclasses to functions that should be called when the corresponding event occurs.

>>> my_element.callbacks[Click] = (lambda event: print('Click:', event))

css = None

a dict-like object mapping strings (CSS properties) to strings (CSS values).

>>> my_text.css['color'] = 'red'

gui

The GUI the element belongs to, or None if there is none.

handle_event(event)

mark_dirty()

Marks the element as needing redrawing.

class browsergui.elements.NotUniversallySupportedElement(**kwargs)

Bases: browsergui.elements.Element

Mixin for elements that aren’t supported in all major browsers.

Prints a warning upon instantiation, i.e. if MyElement subclasses NotUniversallySupportedElement, then MyElement() will log a warning.

To avoid the warning, either set MyElement.warn_about_potential_browser_incompatibility = False or pass the keyword argument warn_about_potential_browser_incompatibility=False into the constructor. (Yes, it’s intentionally verbose. This package is meant to be super-portable and work the same way for everyone.)

warn_about_potential_browser_incompatibility = True