Developer documentation

_locals

A collection of things for widgets to use. These can be imported with a from _locals import * line.

Constants:

GUI: Widgets should use this for the event type of any events emitted.

get_screen(): Returns the screen object.

get_screen()

class Font

Class containing fonts available for use.

Index class to get fonts, such as Font["widget"] for the widget font.

The default fonts are:

widget: The default font for widgets.

title: A larger title font.

mono: A monospaced font.

Attributes:

col: (r,g,b) tuple, containing the default font colour.

col = (255, 255, 255)

classmethod set_fonts(fonts={})

Set fonts to a specific font. If a font exists, it will be replaced, otherwise it will be newly created.

Args:

fonts: Dictionary containing fonts to use.

Key should be name of font. Value should be string

naming either custom FreeType or a system font.

Base widget

Base widget, all widgets inherit from this.

class sgc.widgets.base_widget.Simple

Attributes to customise widget:

Simple._can_focus = False

True if the widget can receive focus. The widget will not be able to receive events if it is not focused.

Simple._default_size = None

(w,h) A tuple containing the default size of the widget in pixels.

Simple._modal = False

True if the widget should be modal (blocks other widgets from receiving focus). This will normally be used in combination with _layered.

Simple._layered = False

True if the widget should be layered. This means the widget will float above other widgets, such as a dialog window.

Simple._surf_flags = 0

Flags to be passed to pygame.surface.Surface when creating the images. This will typically just be SRCALPHA when the widget wants transparency.

Simple._available_images = ()

This is a tuple containing the names of the different image states for the widget. See the tutorial.

Simple._extra_images = {}

This is a dictionary containing the names and sizes of the extra images for the widget. See the tutorial.

Simple._image_state = 'image'

Change this attribute to change the default image state the widget should display. This should not be changed directly after initialisation.

Simple._settings_default = {}

This is a dictionary containing the default settings for the widget. It will be copied to self._settings when the widget is instantiated.

Simple._parent = None

This should be assigned the parent widget, if this widget is attached to another. This is mainly used in container widgets.

Override these methods to customise widget behaviour:

Simple.update(time)

Overload to update the widget per frame.

Args:

time: Milliseconds passed since last frame.

Simple._event(event)

Overload to process events received by the widget one at a time.

Simple._change_focus(forward=True)

Called when focus should be changed. Used primarily by the Container widget.

Args:

forward: True if toggling focus forwards, False if backwards.

Returns:

True if widget should change focus from this widget.

Simple._config(**kwargs)

Override to provide configuration options. Receives the keyword arguments user passed to self.config(). Will also receive “init” when the widget is instantiated, which can be used to initialise some things (preferred from overriding __init__).

Simple._draw_base()

Widgets should overload to draw default images found in self._images. This method will not be called when the user gives a custom image.

Simple._draw_final()

Widgets should overload to draw final things that should be drawn regardless of whether a custom image was used or not.

Simple._focus_enter(focus=0)

Called when the widget gains focus. Overload to customise behaviour.

Args:

focus: 1 if focused by keyboard, 2 if by mouse.

Simple._focus_exit()

Called when the widget loses focus. Overload to customise behaviour.

Useful functions that can be used by the widget:

Simple._create_base_images(surf, parent=None)

Creates the base surfaces to draw on, or uses existing images.

If self._default_size is None, widget is expected to call this function manually when no size is given.

Simple._dotted_rect(col=(255, 255, 255))

Draw a dotted rectangle to show keyboard focus.

Simple._create_event(gui_type, **kwargs)

Returns a GUI pygame.event.Event object. The first argument must be the value for gui_type and should roughly describe the event. Optional keyword arguments can also be passed with additional attributes for the event.

Simple._switch(image=None)

Switch image state to the given image name.

Given no arguments will simply refresh the current image.

class _Label(text, parent)

Simple label that can be displayed next to widgets.

This differs from the normal label widget in that it is attached to a widget and should not be used standalone. This is automatically attached by the base widget when the user passes the label argument to config(). Args:

text: Text label should display.

parent: Widget label should be attached to.

col

Colour of label text. Defaults to Font.col. Changed in the base widget when “label_col” is passed to self.config().

font

Font used for label text. Defaults to Font[“widget”]. Changed in the base widget when “label_font” is passed to self.config().

text = ''

The text that should be displayed. Changed in the base widget when “label” is passed to self.config().

side

Return which side widget should be attached to. Returns parent._label_side or defaults to “right”.

rect

Returns the rect aligned to the appropriate side of it’s parent.

_draw()

Redraw label.