pyggui.gui package

Submodules

pyggui.gui.animation module

Module for animation classes that hold image lists and handle different types of animations.

class pyggui.gui.animation.Animator(images: List[pygame.surface.Surface], animation_velocity: Union[int, float] = 1, loop: bool = False)

Bases: object

Class for handling animations in lists of images, can either loop indefinitely or loop once and stay at the last image. The get method should be called for fetching current image. That method also updates the state of the animator object, so it should be called even if the image wont be used.

property at_end

get() → pygame.surface.Surface

Method returns current image to display, also updates images index so this method should be called in a loop.

Returns

pygame.surface.Surface – Current image in animation loop.

property index

reset_index() → None

Resets the current image index back to 0 (at beginning).

set_animation(animation_type: str) → None

Method sets the current animation type of the object. Options:

normal: Only loops once over the images and stays at the last image. loop: Loops indefinitely.

Parameters

animation_type (str) – Animation type between the currently implemented: normal, loop

pyggui.gui.bar module

Module for Bar classes.

class pyggui.gui.bar.DefaultProgressBar(position: List[int] = [0, 0], size: Tuple[int, int] = (1, 1), visible: bool = True, selected: bool = False, color: Tuple[int, int, int] = (255, 255, 255), line_width: int = 3)

Bases: pyggui.gui.item.StaticItem

Default progress bar is a horizontal rectangle that gets filled up based on progress. The default color is white but can be changed by modifying the color attribute. update_progress(float) method should be used to update the fill of bar.

draw()

Method draws self to screen.

property progress

update() → None

Method updates current filling bar.

update_progress(progress: float) → None

Parameters

progress (float) – Float representation of current progress in range [0, 1]. Progress bar is filled based on this value; 0 = empty, 0.5 = half full, 1 = full.

class pyggui.gui.bar.ProgressBar(*args, **kwargs)

Bases: pyggui.gui.item.StaticItem

Progress bar is used for displaying progress. Passing a directory path in the argument directory_path will let you create a custom imaged progress bar, an DefaultProgressBar gets returned otherwise, for wich size should be passed.

pyggui.gui.button module

Module containing different buttons.

class pyggui.gui.button.Button(*args, **kwargs)

Bases: pyggui.gui.item.Item

Class for creating a button. Button has on_click method which gets triggered once the item is clicked. A directory path parameter should be passed for creating button with images, otherwise a DefaultButton is created. Directory path for button images should be structured:

/some/path/button/-

normal.png # Image or directory of images

on_click/ on_hover/

The on_click and on_hover must be directories even if holding just one file.

Animation velocity can be changed for each of the above types (normal, on_click or on hover) by accessing buttons animated dictionary. The dictionary holds Animator objects with passed images, so for ex.: Changing animation velocity to on_click animation:

animated[‘on_click’].animation_velocity = 0.7

Changing animation type is also possible but should be done using Animators set_animation method, ex.:

animated[‘on_click’].set_animation(‘loop’)

draw()

Overwrite parent method. Used for drawing itself and every item attached to it.

image_setup()

Method loads all images in the passed directory_path into the local animated dictionary attribute which is used internally for animating the button.

update()

Overwrite parent method for updating this classes custom attributes. Used for updating all items attached to it(sizes, positions, etc.).

class pyggui.gui.button.DefaultButton(controller: Controller, position: typing.List[int] = [0, 0], size: typing.Tuple[int, int] = (100, 40), on_click: typing.Callable = <function DefaultButton.<lambda>>, text: typing.Union[str, pyggui.gui.text.Text] = 'Button', fill_color: typing.Tuple[int, int, int] = (0, 0, 0), border_color: typing.Tuple[int, int, int] = (255, 255, 255), movable: bool = False, visible: bool = True)

Bases: pyggui.gui.item.Item

Default button is used when the user hasn’t specified an image for the button itself.

draw() → None

Method draws button along with its text on screen.

get_text_position() → List[int]

Method calculates the position of text inside button to that it is centered.

Returns

list[int, int] – Position of centered text.

update() → None

Method updates self and re-sets text position.

pyggui.gui.container module

Module containing container classes used for storing and moving grouped items.

class pyggui.gui.container.Container(*args, **kwargs)

Bases: object

Container objects can store items in positions relative to self. If items get added to a container object, those items can all be moved together by moving the container object.

Passing the argument resizable as True will create a Resizable container, otherwise a StaticContainer where it and its items can’t be resized.

class pyggui.gui.container.ResizableContainer(position: List[int] = [0, 0], size: Tuple[int, int] = (100, 100), visible: bool = False, selected: bool = False, resizable: bool = False)

Bases: pyggui.gui.item.ResizableItem

Container object can be resized along with every item contained in it. Because of this only re-sizable items can be added.

add_item(item: any, relative_position: Tuple[int, int]) → int

Method adds item in a position relative to self upper left corner. Item will be moved along with the container object.

Parameters

• item (any) – Item to add.

• relative_position (Tuple[int, int]) – Position of added item in container based on upper left corner.

Returns

int – Position (index) in items list of added item.

change_item_at_index(index: int, item: any) → None

Method changes item at index inside the items list. Position of item inside container stays the same.

Parameters

• index (int) – Index in items list to change item.

• item (any) – Item to add.

draw() → None

Used for drawing itself and every item attached to it.

reset_size() → None

Method resets size of self and every item to the initially set size.

resize(factor: float) → None

Method re-sizes self and every item inside by a factor passed as an argument.

Parameters

factor (float) – Representing scale to resize in the interval (0, inf]

update() → None

Updates all items and its positions relative to self.

class pyggui.gui.container.StaticContainer(position: List[int] = [0, 0], size: Tuple[int, int] = (100, 100), visible: bool = False, selected: bool = False, resizable: bool = False)

Bases: pyggui.gui.item.StaticItem

Container object for holding items inside, items are moved with the container. Static container can not be resized but can still be moved.

add_item(item: any, relative_position: Tuple[int, int]) → int

Method adds item in a position relative to self upper left corner. Item will be moved along with the container object.

Parameters

• item (any) – Item to add.

• relative_position (Tuple[int, int]) – Position of added item in container based on upper left corner.

Returns

int – Position (index) in items list of added item.

change_item_at_index(index: int, item: any) → None

Method changes item at index inside the items list. Position of item inside container stays the same.

Parameters

• index (int) – Index in items list to change item.

• item (any) – Item to add.

draw() → None

Used for drawing itself and every item attached to it.

update() → None

Updates all items and its positions relative to self.

pyggui.gui.event_handler module

Module containing event handler classes.

class pyggui.gui.event_handler.EventHandler(types: Union[int, List[int]], handlers: Union[Callable, List[Callable]])

Bases: object

Class stores event types and handlers for those events. Once one of the event types appears in the input event loop all of its handlers get called. Event types are Pygame specific event types.

property handlers

property types

update(event: Event) → None

Method calls all handlers set to self. Is called once on of the set event types appeared in input.

Parameters

event (Event) – Pygame Event object

pyggui.gui.grid module

Module containing grid definition and every addition needed for it.

class pyggui.gui.grid.Cell(grid: pyggui.gui.grid.Grid, position_in_grid: Tuple, position: List[int] = [0, 0], size: Tuple[int, int] = (1, 1))

Bases: pyggui.gui.item.StaticItem

Class for representing a single rectangle in the grid that is placed in the i, j position and has i-th rows height, j-th columns height. Items can be added to it, aligned and padded.

add_item(item: any, align: Optional[str] = None, padding: Optional[str] = None) → None

Method adds item to cell, aligns and pads it base on passed values.

Parameters

• item (any) – Item to add.

• align (str) – String defining alignment type. Multiple alignments are separated by a space character. Example: alignment = “centre top” # Centre should always be first.

• padding (str) – String defining padding of item. Multiple alignments are separated by a comma. Value is passed next to the alignment position as an integer value. Example: padding = “top 5, left 3” # 5px from top 3px from bottom

draw(visible: bool = False)

Used for drawing itself and every item attached to it.

property padding

update()

Used for updating all items attached to it(sizes, positions, etc.).

class pyggui.gui.grid.Grid(position: List[int] = [0, 0], rows: int = 1, columns: int = 1, row_sizes: Optional[Union[List[int], List[float]]] = None, column_sizes: Optional[Union[List[int], List[float]]] = None, size: Optional[Tuple[int, int]] = None, visible: bool = False, selected: bool = False)

Bases: pyggui.gui.item.StaticItem

add_item(item: any, row: Optional[int] = None, column: Optional[int] = None, align: Optional[str] = None, padding: Optional[str] = None) → None

Method adds item to the grid in the specified cell at position row, column. Optional alignments, and paddings can be defined relative to the cell where the item is being added.

Parameters

• item (any) – Item to add.

• row (int) – Row in grid to add the item in. Starting at 0.

• column (int) – Column in grid to add the item in. Starting at 0.

• align (str) – Representing one or more alignment types. These include: centre, top, bottom, left, right. Centre should be defined first. Separate alignments using a space ” “.

• padding (str) – Representing one or more paddings of each side of the cell. Multiple can be passed by separating them with commas “,”, each padding should be passed as “side px”. Where sides include: top, bottom, left, right. Px represents an integer number of pixels to pad. Ex.: padding = “top 5, left 10”

property columns

draw()

Method draws every item added to a cell in the grid.

property rows

update()

Method updates every item added to a cell in the grid.

class pyggui.gui.grid.Row(grid: pyggui.gui.grid.Grid, data: Optional[List] = None)

Bases: object

Single row in Grid, is only used for grabbing items using indexing with []. Row contains cells that are in that row in the grid.

append(val)

Append value at end of list

insert(i, val)

Insert value at index

pyggui.gui.grid.make_grid_line(line: List[Union[float, int]], total_size: int, number_of_items: int) → List[int]

Used internally by Grid for constructing cell sizes for each column, row. Function creates a list representing sizes of cells (in px) in that line (either row or column). Line can be passed as a list of decimals (representing percentage of total size) or integers (representing sizes). Line can also include less elements than there are rows/columns, elements then get added/removed accordingly.

Parameters

• line (List[Union[float, int]]) – List of either integers or floats representing different size format (px or %).

• total_size (int) – Total size (height of all rows or width of all columns), can be either 1 (if %) or an integer representing size in px.

• number_of_items (int) – Expected number of items in line.

pyggui.gui.image module

Module for classes handling images.

class pyggui.gui.image.Image(*args, **kwargs)

Bases: object

Class for creating image objects and place them on screen or page. Argument ‘transparent’ decides how the passed image (if passed as a path) will be loaded (as a transparent surface

or not).

Class can return either a ResizableImage object or a StaticImage object based on the passed argument ‘resizable’,

which defaults to false.

class pyggui.gui.image.ResizableImage(image: Union[str, pygame.Surface], transparent: bool = False, position: List[int] = [0, 0], visible: bool = True, selected: bool = False, resizable: bool = True)

Bases: pyggui.gui.item.ResizableItem

Class for handling a single static image that can be moved and re-sized. Inherits from ResizableItem.

draw() → None

Method will draw itself and every item attached to it.

reset_size() → None

Method will reset images size to the initially set one.

resize(factor: float) → None

Method will re-size image and its position based on a factor passed as argument.

Parameters

factor (float) – Factor to scale item in range [0, inf]

class pyggui.gui.image.StaticImage(image: Union[str, pygame.Surface], transparent: bool = False, position: List[int] = [0, 0], visible: bool = True, selected: bool = False, resizable: bool = False)

Bases: pyggui.gui.item.StaticItem

Class for handling a single static image. This image can be moved but not resized, refer to ResizableImage for resizable images or pass ‘resizable=True’ to Image class constructor. inherits from StaticItem.

draw() → None

Used for drawing itself and every item attached to it.

draw_at(position: List[int]) → None

Method draws Image at given position without drawing all items attached to self.

Parameters

position (List[int]) – Position on screen to draw image at.

get() → pygame.Surface

Method returns current image.

Returns

pygame.Surface – Current surface where the image is loaded in.

pyggui.gui.image.fetch_image(image: Union[str, pygame.Surface], transparent: bool = False) → pygame.Surface

Function loads one image and returns it as a pygame.Surface object.

Parameters

• image (Union[str, pygame.Surface]) – Either a path to the image (preferably relative path), or an already loaded image as a pygame.Surface object.

• transparent (bool) – If image should be loaded as transparent. If image is passed as a Surface object it is set as the default False.

Returns

pygame.Surface – Image loaded into a surface,

pyggui.gui.item module

Module containing Item base classes.

class pyggui.gui.item.BaseItem(position: List[int], size: Tuple[int, int], visible: bool = True, selected: bool = False)

Bases: object

Base class for all items.

add_item(item: any, relative_position: Optional[Union[Tuple[int, int], List[int]]] = None) → None

Method adds item to self. If relative position is not specified, item will be added based on its position relative to this items position. If relative position is specified however, item will be added into that position relative to this items position.

Parameters

• item (any) – Item to add to self.

• relative_position (Union[Tuple[int, int], List[int]]) – Optional; [x, y] value of added items position relative to this items upper left corner.

draw()

property height: int

move(change: Union[Tuple[int, int], List[int]]) → None

Method moves item by specified change along with every attached item.

Parameters

change (Union[Tuple[int, int], List[int]]) – dx, dy to move item in each direction.

move_to(point: Union[List[int], Tuple[int, int]]) → None

Method moves item to specified position along with every attached item.

Parameters

point (Union[List[int], Tuple[int, int]]) – x, y point to move item to on screen or page.

property position: List[int]

reset_position() → None

Method resets items position to its initial one.

property size: Tuple[int, int]

update()

update_items_positions() → None

Method updates every attached items position relative to self.

property width: int

property x: int

property y: int

class pyggui.gui.item.Item(controller: Controller, position: List[int] = [0, 0], size: Tuple[int, int] = (1, 1), on_click: Callable = None, movable: bool = False, visible: bool = True)

Bases: pyggui.gui.item.BaseItem

Class for items that are interactive but dependant on controller object. Items have hovered property which is set to true once the item is hovered by mouse. Have on_click method to trigger an action once the item is clicked.

add_on_click(on_click: Union[Callable, List[Callable], Tuple[Callable]]) → None

Method adds callable function or list of functions to self. These functions get executed once the item is clicked.

Parameters

• on_click (Union[Callable, List[Callable], Tuple[Callable]]) – Either a callable function or a list / tuple

• of callable functions.

debounce_time() → bool

Method checks if enough(debounce_interval) time passed from the time of the last click. Used for eliminating double clicks.

Returns

bool – If debounce_interval time has passed or not

draw()

Used for drawing itself and every item attached to it.

property mouse_clicked

on_click()

Method gets executed once the item has been clicked on. Executes all on_click functions.

update()

Used for updating all items attached to it(sizes, positions, etc.).

class pyggui.gui.item.ResizableItem(position: List[int] = [0, 0], size: Tuple[int, int] = (1, 1), visible: bool = True, selected: bool = False)

Bases: pyggui.gui.item.BaseItem

Base class for defining static items that have actions performed on them and are able to re-size. The main difference between the Item class is that it can be resized, the lack of on_hover / on_click methods and that this class does not need the controller to be passed. Items can not be attached to this class.

reset_size() → None

Method will reset its size to the initial.

resize(factor: float) → None

Method will re-size item based on a factor passed as argument. If class gets inherited method should first get called with super function.

Parameters

factor (float) – Resize factor, 1 is the same size, 0.5 is half size and 2 is double size

property scaled_height: int

Property returns objects scaled height. If not resized it is the same as its normal height.

property scaled_position: List[int]

Property returns scaled position when item is re-sized, keeping original position intact.

property scaled_width: int

Property returns objects scaled width. If not resized it is the same as its normal width.

property scaled_x: int

Property returns scaled x position when item is re-sized, keeping original position intact.

property scaled_y: int

Property returns scaled y position when item is re-sized, keeping original position intact.

class pyggui.gui.item.StaticItem(position: List[int] = [0, 0], size: Tuple[int, int] = (1, 1), visible: bool = True, selected: bool = False)

Bases: pyggui.gui.item.BaseItem

Class for static items that are not intractable (can’t be clicked and do not have hovered property).

draw() → None

Used for drawing itself and every item attached to it.

update() → None

Used for updating all items attached to it(sizes, positions, etc.).

pyggui.gui.page module

Module containing base classes for pages.

class pyggui.gui.page.Page(controller: Controller)

Bases: object

Main class other pages should inherit from. Page object functions similarly to an Item, it can be moved and resized.

add_event_handler(event_handler: pyggui.gui.event_handler.EventHandler) → None

Method adds a page-wide EventHandler object. This event handler is not triggered after the page has been redirected from i.e. with the redirect_to or go_back methods of Controller.

Parameters

event_handler (EventHandler) – EventHandler object to add.

add_event_type_handler(event_type: int, handler: Callable)

Method adds a single page-wide event type handler. The handler callable function gets triggered once the event_type appears in the main input loop. This event type handler is not triggered after the page has been redirected from i.e. with the redirect_to or go_back methods of Controller.

Parameters

• event_type (int) – Pygame event type.

• handler (Callable) – Callable function to get called once the event type appears in the main input loop.

add_item(item: any) → None

Method adds item to page. Items position should be set beforehand.

Parameters

item (any) – Item to add to page. Item must have the update and draw methods.

property display_size

draw() → None

Method draws every item added to page.

property height: int

on_appearance() → None

Method gets called once the page been has brought up again. Safe for overriding.

on_exit() → None

Method gets called once the page has been redirected from. Safe for overriding.

property position: List[int]

property size: Tuple[int, int]

update() → None

Method updates every item added to page. Once the item is added, page no longer controlls its position but it has its original position stored.

property width: int

property x: int

property y: int

pyggui.gui.text module

Module for text based items.

class pyggui.gui.text.Text(position: List[int] = [0, 0], value: str = 'Text', font: Optional[str] = None, font_size: int = 21, color: Tuple[int, int, int] = (255, 255, 255))

Bases: pyggui.gui.item.StaticItem

Class for displaying text on screen. You can pass own font file or use one of the System specific ones by passing a font name without any . / characters. Text can not be resized after initialization, for that use the ResizableText class TODO(Add).

Note: If you change the value of the text the render method should be called to re-render the changed text.

draw() → None

Method will draw text and all attached items on screen.

render() → None

TODO: Add value property and setter to auto-update text Method re-renders the text surface, method should be called once the text value has changed.

update() → None

Method will update all items attached to self.

property value

Module contents

This imports all classes defined in the gui package. We exclude classes starting with _ as those are considered private.