pygvisuals.widgets package

Package for interactive GUI-objects with pygame.

class pygvisuals.widgets.Widget(x, y, width, height)

Bases: pygame.sprite.DirtySprite

Underlying class for interactive GUI-objects with pygame; intended for use together with pygame.sprite.LayeredDirty.

Note: If you change any widget’s visual characteristics (e.g. its background-color) via its methods or properties (e.g. setBackground()), its appearance will not change until it is redrawn. You can force this by calling widget.update() after you modified its characteristics.

Initialisation of a basic Widget. The units for the following lengths are pixel.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

getActualBounds()

Return the widget’s actual bounds (position and size).

Returns

A pygame.Rect with the bounds of the widget.

getBackground()

Return the widget’s background-color.

Returns

A color-like object that represents the widget’s background color.

getBackgroundImage()

Return the widget’s background-image. A falsy value (e.g. None) indicates that there is no background-image to be drawn.

Returns

A surface-like object that is rendered in the background of the widget or a falsy value indicating that there is no such surface.

getBorder()

Return the widget’s border.

Returns

A PyGVisuals-border belonging to the widget.

getBounds()

Return the widget’s base bounds (position and size).

Returns

A pygame.Rect with the bounds of the widget.

getDisabeledOverlay()

Return the widget’s color which is overlayed when it is disabled.

Returns

A color-like object that represents the widget’s disabeled color.

getForeground()

Return the widget’s foreground-color (not used by basic implementation).

Returns

A color-like object that represents the widget’s foreground color.

getScalingFunction()

Return the scaling-function used for scaling the background-image (to the widgets bounds).

Returns

A function that scales a given surface-like object to a given size (like pygame.transform.scale) or a falsy value (e.g. None) if the background-image is not rescaled when drawn.

hasSmoothScaling()

Return whether the background-image is known to be scaled smoothly or not.

Returns

A boolean indicating whether the scaling-function is pygame.transform.smoothscale and the background-image is therefore scaled smoothly.

isActive()

Return whether the widget is active. An inactive widget should not be interactable and will have an overlay painted on.

Returns

A boolean indicating whether the widget is active.

isDirty()

Return if the widget is dirty and will be redrawn in the next draw-cycle.

isDirtyForever()

Return if the widget is constantly dirty and will be redrawn periodically with every draw-cycle.

isFocused()

Return whether the widget is focused. A widget will be focused automatically if it is clicked on.

Returns

A boolean indicating whether the widget is declared focused.

isVisible()

Return whether the widget is visible. Invisible widgets will not be drawn and are inactive.

Returns

A boolean indicating whether the widget is declared visible.

markClean()

Mark the widget as clean and therefore not to be redrawn in the next draw-cycle.

markDirty(overwriteDirtyForever=False)

Mark the widget as dirty and therefore to be redrawn in the next draw-cycle.

Parameters

overwriteDirtyForever – A boolean indicating whether this should overwrite the dirty-forever state. The default is False meaning that a widget which is marked as dirty-forever will not be clean after the next cycle when this method was called on it.

markDirtyForever()

Mark the widget as constantly dirty and therefore to be redrawn periodically with every draw-cycle.

setActive(active)

Set the widget as active and therefore as interactive. An inactive widget should not be interactable and will have an overlay painted on.

Parameters

active – A boolean indicating whether the widget should be active

Returns

Itsself (the widget) for convenience.

setBackground(color)

Set the widget’s background-color.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setBackgroundImage(image, smooth=None, scale_immediately=False)

Set the widget’s background-image.

Parameters

• image – A surface-like object (e.g. pygame.Surface) that should be rendered as the background. If this is a falsy value (e.g. None), there will be no background-image.

• smooth – A boolean indicating whether the image should be scaled smoothly or not. If this is None, the previous value will not be overwritten. The default value is None, so the previous configuration will be kept.

• scale_immediately – A boolean indicating whether the image should be scaled during this assignment. Usually the image is rescaled every time the widget is drawn. This is especially useful when the scaling-function is set to None since the image will only be resized once during this assignment therefore increasing performance. The default value is False, so the image will not be rescaled in this assignment which preserves image quality.

Returns

Itsself (the widget) for convenience.

setBorder(border)

Set the widget’s border.

Parameters

border – A PyGVisuals-border to be set. If this is a falsy value a empty border will be used.

Returns

Itsself (the widget) for convenience.

setBounds(rect)

Set the widget’s base bounds according to a pygame.Rect. This can be used to change the position of the widget or its size.

Parameters

rect – A pygame.Rect with the according position and size.

Returns

Itsself (the widget) for convenience.

setDisabeledOverlay(color)

Set the widget’s color to overlay when it is disabled.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setFocused(focused)

Set whether the widget is focused.

A widget will be focused automatically if it is clicked on. Although the default implementation does not process this information, subclasses may use this information to determine if the user-interaction was meant to be processed by them or not.

Parameters

visible – A boolean indicating whether the widget should be focused.

Returns

Itsself (the widget) for convenience.

setForeground(color)

Set the widget’s foreground-color (not used by basic implementation).

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setScalingFunction(scaling_function)

Set the scaling-function used for scaling the background-image (to the widgets bounds).

Parameters

scaling_function – A function that scales a given surface-like object to a given size. See for example pygame.transform.scale. If this is a falsy value (e.g. None), the image will not be rescaled when drawn.

Returns

Itsself (the widget) for convenience.

setSmoothScaling(smooth)

Set whether the widget’s background-image will be scaled smoothly (with pygame.transform.smoothscale) or not. For more control see the widget’s ‘scaling_function’ property.

Parameters

smooth – A boolean indicating whether the image should be scaled smoothly or not.

Returns

Itsself (the widget) for convenience.

setVisible(visible)

Set the widget’s visibility. Invisible widgets will not be drawn and are inactive.

Parameters

visible – A boolean indicating whether the widget should be visible.

Returns

Itsself (the widget) for convenience.

update(*args)

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property active

The widget’s active status as a boolean. An inactive widget will should not respond to user-input and will have a grey overlay.

property background

The widget’s background color.

property background_image

The widget’s background-image. If this is a falsy value (e.g. None), no image will be drawn.

property border

The widget’s border (a PyGVisuals’ border).

property bounds

The widget’s base position and size as a pygame.Rect.

property disabeled_overlay

The widget’s color to overlay when it is disabled.

property focused

The widget’s focus status as a boolean. A widget will be focused automatically if it is clicked on.

property foreground

The widget’s foreground color.

property rect

The widget’s actual position and size as a pygame.Rect.

property scaling_function

The widget’s function used for scaling the background-image (to the widgets bounds). If this is a falsy value (e.g. None), the image will not be rescaled when drawn.

property smooth_scaling

The widget’ status as a boolean regarding whether the background-image will be scaled smoothly (with pygame.transform.smoothscale). Exact control of the scaling-function is given via the ‘scaling_function’ property.

class pygvisuals.widgets.Label(x, y, width, height, text='', font=<pygame.font.Font object>)

Bases: pygvisuals.widgets.text_widget.TextWidget

A label for displaying simple text.

Initialisation of a Label.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

class pygvisuals.widgets.Entry(x, y, width, height, text='', font=<pygame.font.Font object>, editable=True, validation_function=<function Entry.<lambda>>, selection_overlay=(45, 110, 235, 120))

Bases: pygvisuals.widgets.selection_text_widget.SelectionTextWidget

Entry-fields that accept keyboard-input.

Initialisation of an Entry.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• editable – A boolean indicating whether the widget’s content is editable by the user. The default value is True, meaning it can be edited by user-input.

• validation_function – A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText(). The default value is a function that accepts every change.

• selection_overlay – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values); this is used as an overlay for content that has been selected. The default value is the global default for the selection-color.

update(*args)

Additionally handles keyboard-input.

Additionally handles the selection and deletion of content.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

class pygvisuals.widgets.Listbox(x, y, width, height, font=<pygame.font.Font object>, editable=False, validation_function=<function Listbox.<lambda>>, selection_overlay=(45, 110, 235, 120))

Bases: pygvisuals.widgets.selection_text_widget.SelectionTextWidget

Listbox for displaying lists of multiple objects as strings.

Initialisation of an Listbox.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• editable – A boolean indicating whether the widget’s content is editable by the user. The default value is False, meaning it can not be edited by user-input.

• validation_function – A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText(). The default value is a function that accepts every change.

• selection_overlay – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values); this is used as an overlay for content that has been selected. The default value is the global default for the selection-color.

delete(start, end)

Deletes the widget’s content between the two given indices.

Parameters

• start – An integer representing the index from which the content should be deleted.

• end – An integer representing the index until which the content should be deleted.

Returns

A boolean indicating whether the change was successful.

getActualIndex(index, constrain=True)

Return the actual index corresponding to the given representation. This converts known constants (e.g. END, CURSOR) to the corresponding integers.

Parameters

• index – An integer (or known constant) to be converted.

• constrain – A boolean indicating whether the given index should be constrained to valid indices for the content or not. The default value is True, meaning that the returned index is constrained.

Returns

An integer representing the actual index the given value corresponds to.

getList()

Return the widget’ list-representation of its content.

Returns

A list representing the content of the widget.

getText()

Return the widget’ string-representation of its content.

Returns

A string representing the content of the widget.

getViewpoint()

Return the widget’s viewpoint-position.

Returns

An integer representing the index the viewpoint is at.

insert(index, text)

Note: The argument ‘text’ can be of any type, not only a string.

Insert a given text at the given index.

Parameters

• index – An integer (or known constant) representing the position the text should be insterted at.

• text – A string specifing the content to add to the content of the widget.

Returns

A boolean indicating whether the change was successful.

moveViewpoint(index)

Move the widget’s viewpoint-position by the given amount.

Parameters

amount – An integer representing the amount the viewpoint should be moved by.

Returns

Itsself (the widget) for convenience.

setCursor(index)

Set the widget’s cursor-position.

Parameters

index – An integer (or known constant) representing the index the cursor should be set to.

Returns

Itsself (the widget) for convenience.

setList(list)

Set the widget’ list-representation of its content.

Parameters

list – A list with the content to set.

Returns

Itsself (the widget) for convenience.

setText(text)

Note: Any given text will be ignored; use insert or delete instead.

Additionally validate the change of content.

Set the widget’ string-representation of its content.

Parameters

text – A string with the content to set.

Returns

Itsself (the widget) for convenience.

setViewpoint(index)

Set the widget’s viewpoint-position.

Parameters

index – An integer (or known constant) representing the index the viewpoint should be set to.

Returns

Itsself (the widget) for convenience.

update(*args)

Additionally handles keyboard-input.

Additionally handles the selection and deletion of content.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property list

The widget’ list-representation of its content.

property viewpoint

The widget’s position of the viewpoint as a index. This is the first currently visible index.

class pygvisuals.widgets.Button(x, y, width, height, text='', font=<pygame.font.Font object>, callback=None)

Bases: pygvisuals.widgets.label.Label

Clickable buttons with a simple text display.

Initialisation of a Button.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• callback – A callable object to be called when the button is pressed. There are no arguments passed and the return value will be ignored. If this is a falsy value, no function will be called when the button is pressed; The default value is None, meaning that the button will not have any special behaivour when pressed.

getCallback()

Return the button’s function to be called when it is pressed.

Returns

A callable object that is called when the button is pressed.

getHoveredOverlay()

Return the button’s color to overlay when hovered over.

Returns

A color-like object that represents the button’s color overlay when hovered over.

getPressedOverlay()

Return the button’s color to overlay when pressed.

Returns

A color-like object that represents the button’s color overlay when pressed.

isHovered()

Return whether the button is hovered over.

Returns

A boolean indicating whether the button is hovered over.

isPressed()

Return whether the button is pressed.

Returns

A boolean indicating whether the button is pressed.

setCallback(callback)

Set the button’s function to be called when it is pressed.

Parameters

callback – A callable object to be called when the button is pressed. If this is a falsy value, no function will be called when the button is pressed; The default value is None, meaning that the button will not have any special behaivour when pressed.

Returns

Itsself (the widget) for convenience.

setHoveredOverlay(color)

Set the button’s color to overlay when hovered over.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setPressedOverlay(color)

Set the button’s color to overlay when pressed.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

update(*args)

Additionally handles the clicking of the button and calls the callback-function.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property callback

The widget’s function to be called when it is pressed.

property hovered

The widget’ status as a boolean regarding whether it is hovered over.

property hovered_overlay

The widget’s color to overlay when it is hovered over.

property pressed

The widget’ status as a boolean regarding whether it is pressed.

property pressed_overlay

The widget’s color to overlay when it is pressed.

Submodules

pygvisuals.widgets.button module

class pygvisuals.widgets.button.Button(x, y, width, height, text='', font=<pygame.font.Font object>, callback=None)

Bases: pygvisuals.widgets.label.Label

Clickable buttons with a simple text display.

Initialisation of a Button.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• callback – A callable object to be called when the button is pressed. There are no arguments passed and the return value will be ignored. If this is a falsy value, no function will be called when the button is pressed; The default value is None, meaning that the button will not have any special behaivour when pressed.

getCallback()

Return the button’s function to be called when it is pressed.

Returns

A callable object that is called when the button is pressed.

getHoveredOverlay()

Return the button’s color to overlay when hovered over.

Returns

A color-like object that represents the button’s color overlay when hovered over.

getPressedOverlay()

Return the button’s color to overlay when pressed.

Returns

A color-like object that represents the button’s color overlay when pressed.

isHovered()

Return whether the button is hovered over.

Returns

A boolean indicating whether the button is hovered over.

isPressed()

Return whether the button is pressed.

Returns

A boolean indicating whether the button is pressed.

setCallback(callback)

Set the button’s function to be called when it is pressed.

Parameters

callback – A callable object to be called when the button is pressed. If this is a falsy value, no function will be called when the button is pressed; The default value is None, meaning that the button will not have any special behaivour when pressed.

Returns

Itsself (the widget) for convenience.

setHoveredOverlay(color)

Set the button’s color to overlay when hovered over.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setPressedOverlay(color)

Set the button’s color to overlay when pressed.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

update(*args)

Additionally handles the clicking of the button and calls the callback-function.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property callback

The widget’s function to be called when it is pressed.

property hovered

The widget’ status as a boolean regarding whether it is hovered over.

property hovered_overlay

The widget’s color to overlay when it is hovered over.

property pressed

The widget’ status as a boolean regarding whether it is pressed.

property pressed_overlay

The widget’s color to overlay when it is pressed.

pygvisuals.widgets.entry module

class pygvisuals.widgets.entry.Entry(x, y, width, height, text='', font=<pygame.font.Font object>, editable=True, validation_function=<function Entry.<lambda>>, selection_overlay=(45, 110, 235, 120))

Bases: pygvisuals.widgets.selection_text_widget.SelectionTextWidget

Entry-fields that accept keyboard-input.

Initialisation of an Entry.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• editable – A boolean indicating whether the widget’s content is editable by the user. The default value is True, meaning it can be edited by user-input.

• validation_function – A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText(). The default value is a function that accepts every change.

• selection_overlay – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values); this is used as an overlay for content that has been selected. The default value is the global default for the selection-color.

update(*args)

Additionally handles keyboard-input.

Additionally handles the selection and deletion of content.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

pygvisuals.widgets.label module

class pygvisuals.widgets.label.Label(x, y, width, height, text='', font=<pygame.font.Font object>)

Bases: pygvisuals.widgets.text_widget.TextWidget

A label for displaying simple text.

Initialisation of a Label.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

pygvisuals.widgets.listbox module

class pygvisuals.widgets.listbox.Listbox(x, y, width, height, font=<pygame.font.Font object>, editable=False, validation_function=<function Listbox.<lambda>>, selection_overlay=(45, 110, 235, 120))

Bases: pygvisuals.widgets.selection_text_widget.SelectionTextWidget

Listbox for displaying lists of multiple objects as strings.

Initialisation of an Listbox.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• editable – A boolean indicating whether the widget’s content is editable by the user. The default value is False, meaning it can not be edited by user-input.

• validation_function – A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText(). The default value is a function that accepts every change.

• selection_overlay – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values); this is used as an overlay for content that has been selected. The default value is the global default for the selection-color.

delete(start, end)

Deletes the widget’s content between the two given indices.

Parameters

• start – An integer representing the index from which the content should be deleted.

• end – An integer representing the index until which the content should be deleted.

Returns

A boolean indicating whether the change was successful.

getActualIndex(index, constrain=True)

Return the actual index corresponding to the given representation. This converts known constants (e.g. END, CURSOR) to the corresponding integers.

Parameters

• index – An integer (or known constant) to be converted.

• constrain – A boolean indicating whether the given index should be constrained to valid indices for the content or not. The default value is True, meaning that the returned index is constrained.

Returns

An integer representing the actual index the given value corresponds to.

getList()

Return the widget’ list-representation of its content.

Returns

A list representing the content of the widget.

getText()

Return the widget’ string-representation of its content.

Returns

A string representing the content of the widget.

getViewpoint()

Return the widget’s viewpoint-position.

Returns

An integer representing the index the viewpoint is at.

insert(index, text)

Note: The argument ‘text’ can be of any type, not only a string.

Insert a given text at the given index.

Parameters

• index – An integer (or known constant) representing the position the text should be insterted at.

• text – A string specifing the content to add to the content of the widget.

Returns

A boolean indicating whether the change was successful.

moveViewpoint(index)

Move the widget’s viewpoint-position by the given amount.

Parameters

amount – An integer representing the amount the viewpoint should be moved by.

Returns

Itsself (the widget) for convenience.

setCursor(index)

Set the widget’s cursor-position.

Parameters

index – An integer (or known constant) representing the index the cursor should be set to.

Returns

Itsself (the widget) for convenience.

setList(list)

Set the widget’ list-representation of its content.

Parameters

list – A list with the content to set.

Returns

Itsself (the widget) for convenience.

setText(text)

Note: Any given text will be ignored; use insert or delete instead.

Additionally validate the change of content.

Set the widget’ string-representation of its content.

Parameters

text – A string with the content to set.

Returns

Itsself (the widget) for convenience.

setViewpoint(index)

Set the widget’s viewpoint-position.

Parameters

index – An integer (or known constant) representing the index the viewpoint should be set to.

Returns

Itsself (the widget) for convenience.

update(*args)

Additionally handles keyboard-input.

Additionally handles the selection and deletion of content.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property list

The widget’ list-representation of its content.

property viewpoint

The widget’s position of the viewpoint as a index. This is the first currently visible index.

pygvisuals.widgets.selection_text_widget module

class pygvisuals.widgets.selection_text_widget.SelectionTextWidget(x, y, width, height, text='', font=<pygame.font.Font object>, editable=False, validation_function=<function SelectionTextWidget.<lambda>>, selection_overlay=(45, 110, 235, 120))

Bases: pygvisuals.widgets.text_widget.TextWidget

Underlying class for widgets using selectable content.

Initialisation of a SelectionTextWidget.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

• editable – A boolean indicating whether the widget’s content is editable by the user. The default value is False, meaning it can not be edited by user-input.

• validation_function – A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText(). The default value is a function that accepts every change.

• selection_overlay – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values); this is used as an overlay for content that has been selected. The default value is the global default for the selection-color.

delete(start, end)

Deletes the widget’s content between the two given indices.

Parameters

• start – An integer representing the index from which the content should be deleted.

• end – An integer representing the index until which the content should be deleted.

Returns

A boolean indicating whether the change was successful.

getActualIndex(index, constrain=True)

Return the actual index corresponding to the given representation. This converts known constants (e.g. END, CURSOR) to the corresponding integers.

Parameters

• index – An integer (or known constant) to be converted.

• constrain – A boolean indicating whether the given index should be constrained to valid indices for the content or not. The default value is True, meaning that the returned index is constrained.

Returns

An integer representing the actual index the given value corresponds to.

getCursor()

Return the widget’s cursor-position.

Returns

An integer representing the index the cursor is at.

getSelection()

Return the widget’ selection-range.

Returns

A tuple (start, end) with the start- and end-index of the selection. This is not the selected content, only the indices of the range!

getSelectionIndex()

Return the widget’ selection-index.

Returns

An integer representing the index the selection-index is at.

getSelectionOverlay()

Return the widget’s color to overlay for content that has been selected.

Returns

A color-like object that represents the widget’s color to overlay for content that has been selected.

getValidation()

Return the widget’s validation-function.

Returns

A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText().

insert(index, text)

Insert a given text at the given index.

Parameters

• index – An integer (or known constant) representing the position the text should be insterted at.

• text – A string specifing the content to add to the content of the widget.

Returns

A boolean indicating whether the change was successful.

isEditable()

Return whether the widget’s content is editable by the user (via user-input).

Returns

A boolean indicating whether the widget’s content is editable by the user.

moveCursor(amount)

Move the widget’s cursor-position by the given amount.

Parameters

amount – An integer representing the amount the cursor should be moved by.

Returns

Itsself (the widget) for convenience.

moveSelectionIndex(amount)

Move the widget’s cursor-position by the given amount.

Parameters

amount – An integer representing the amount the cursor should be moved by.

Returns

Itsself (the widget) for convenience.

setCursor(index)

Set the widget’s cursor-position.

Parameters

index – An integer (or known constant) representing the index the cursor should be set to.

Returns

Itsself (the widget) for convenience.

setEditable(editable)

Set whether the widget’s content is editable by the user (via user-input).

Parameters

editable – A boolean indicating whether the widget’s content is editable by the user.

Returns

Itsself (the widget) for convenience.

setSelection(selection_index, cursor)

Set the widget’ selection between the given bounds.

Parameters

• selection_index – An integer (or known constant) representing the index the selection should start. This will be the position of the selection-index.

• cursor – An integer (or known constant) representing the index the selection should end. This will be the position of the cursor. The indices can actually be reversed (meaning the start-index is larger than the end-index) so that the cursor is at the start of the selection.

Returns

Itsself (the widget) for convenience.

setSelectionIndex(index)

Set the widget’ selection-index.

Parameters

index – An integer (or known constant) representing the index the selection-index should be set to.

Returns

Itsself (the widget) for convenience.

setSelectionOverlay(color)

Set the widget’s color to overlay for content that has been selected.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setText(text, return_success_boolean=False)

Additionally validate the change of content.

Set the widget’ string-representation of its content.

Parameters

text – A string with the content to set.

Returns

Itsself (the widget) for convenience.

setValidation(validation_function)

Set the widget’s validation-function.

Parameters

validation_function – A function that validates changed content. It will receive three arguments (the new content, the old content and the widget-object) and should return a boolean indicating whether the change is valid (True when valid). The old content can be None if it was not set before; the new content can be anything that is being passed to setText().

Returns

Itsself (the widget) for convenience.

update(*args)

Additionally handles the selection and deletion of content.

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property cursor

The widget’s position of the cursor as a index. This is another endpoint for the range of selected content.

property editable

The widget’ status as a boolean whether its content is editable by the user.

property selection

The widget’s indices spanning the range of selected content.

property selection_index

The widget’s index representing an endpoint for the range of selected content.

property selection_overlay

The widget’s color to overlay for content that has been selected.

property validation_function

The widget’s function used for validating change of its content.

pygvisuals.widgets.selection_text_widget.CURRENT = 'c'

A index-constant alias for CURSOR.

pygvisuals.widgets.selection_text_widget.CURSOR = 'c'

A index-constant for the cursor of a widget.

pygvisuals.widgets.selection_text_widget.END = 'e'

A index-constant for the last index of a widget’s content.

pygvisuals.widgets.selection_text_widget.INSERT = 'c'

A index-constant alias for CURSOR.

pygvisuals.widgets.selection_text_widget.SELECTION = 's'

A index-constant for the selection-index of a widget.

pygvisuals.widgets.selection_text_widget.START = 0

A index-constant for the first index of a widget’s content.

pygvisuals.widgets.text_widget module

class pygvisuals.widgets.text_widget.TextWidget(x, y, width, height, text='', font=<pygame.font.Font object>)

Bases: pygvisuals.widgets.widget.Widget

Underlying class for widgets using text/strings.

Initialisation of a TextWidget.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

• text – A string specifing the content of the widget. The default value is an empty string.

• font – A font-like object that can be interpreted by pygame.font as a Font; this is used as the font for rendering text. The default value is the global default for fonts.

getFont()

Return the widget’s font used when rendering text.

Returns

A font-like object that can be interpreted by pygame.font as a Font.

getText()

Return the widget’ string-representation of its content.

Returns

A string representing the content of the widget.

isAntialiasing()

Return whether the widget’s text will be antialiased when rendered or not.

Returns

A boolean indicating whether the text is rendered with antialiasing.

setAntialiasing(antialiased)

Set whether the widget’s text will be antialiased when rendered or not.

Parameters

antialiased – A boolean indicating whether the text should be rendered with antialiasing.

Returns

Itsself (the widget) for convenience.

setFont(font)

Set the widget’s font used when rendering text.

Parameters

font – A font-like object that can be interpreted by pygame.font as a Font.

Returns

Itsself (the widget) for convenience.

setText(text)

Set the widget’ string-representation of its content.

Parameters

text – A string with the content to set.

Returns

Itsself (the widget) for convenience.

property antialiased

The widget’ status as a boolean regarding whether antialiasing is used when rendering text.

property font

The widget’s font used when rendering text.

property text

The widget’ string-representation of its content.

pygvisuals.widgets.widget module

class pygvisuals.widgets.widget.Widget(x, y, width, height)

Bases: pygame.sprite.DirtySprite

Underlying class for interactive GUI-objects with pygame; intended for use together with pygame.sprite.LayeredDirty.

Note: If you change any widget’s visual characteristics (e.g. its background-color) via its methods or properties (e.g. setBackground()), its appearance will not change until it is redrawn. You can force this by calling widget.update() after you modified its characteristics.

Initialisation of a basic Widget. The units for the following lengths are pixel.

Parameters

• x – An integer specifing the x-coordinate of the widget. This is the horizontal distance from the left reference point.

• y – An integer specifing the y-coordinate of the widget. This is the vertical distance from the top reference point.

• width – An integer specifing the width of the widget.

• height – An integer specifing the height of the widget.

getActualBounds()

Return the widget’s actual bounds (position and size).

Returns

A pygame.Rect with the bounds of the widget.

getBackground()

Return the widget’s background-color.

Returns

A color-like object that represents the widget’s background color.

getBackgroundImage()

Return the widget’s background-image. A falsy value (e.g. None) indicates that there is no background-image to be drawn.

Returns

A surface-like object that is rendered in the background of the widget or a falsy value indicating that there is no such surface.

getBorder()

Return the widget’s border.

Returns

A PyGVisuals-border belonging to the widget.

getBounds()

Return the widget’s base bounds (position and size).

Returns

A pygame.Rect with the bounds of the widget.

getDisabeledOverlay()

Return the widget’s color which is overlayed when it is disabled.

Returns

A color-like object that represents the widget’s disabeled color.

getForeground()

Return the widget’s foreground-color (not used by basic implementation).

Returns

A color-like object that represents the widget’s foreground color.

getScalingFunction()

Return the scaling-function used for scaling the background-image (to the widgets bounds).

Returns

A function that scales a given surface-like object to a given size (like pygame.transform.scale) or a falsy value (e.g. None) if the background-image is not rescaled when drawn.

hasSmoothScaling()

Return whether the background-image is known to be scaled smoothly or not.

Returns

A boolean indicating whether the scaling-function is pygame.transform.smoothscale and the background-image is therefore scaled smoothly.

isActive()

Return whether the widget is active. An inactive widget should not be interactable and will have an overlay painted on.

Returns

A boolean indicating whether the widget is active.

isDirty()

Return if the widget is dirty and will be redrawn in the next draw-cycle.

isDirtyForever()

Return if the widget is constantly dirty and will be redrawn periodically with every draw-cycle.

isFocused()

Return whether the widget is focused. A widget will be focused automatically if it is clicked on.

Returns

A boolean indicating whether the widget is declared focused.

isVisible()

Return whether the widget is visible. Invisible widgets will not be drawn and are inactive.

Returns

A boolean indicating whether the widget is declared visible.

markClean()

Mark the widget as clean and therefore not to be redrawn in the next draw-cycle.

markDirty(overwriteDirtyForever=False)

Mark the widget as dirty and therefore to be redrawn in the next draw-cycle.

Parameters

overwriteDirtyForever – A boolean indicating whether this should overwrite the dirty-forever state. The default is False meaning that a widget which is marked as dirty-forever will not be clean after the next cycle when this method was called on it.

markDirtyForever()

Mark the widget as constantly dirty and therefore to be redrawn periodically with every draw-cycle.

setActive(active)

Set the widget as active and therefore as interactive. An inactive widget should not be interactable and will have an overlay painted on.

Parameters

active – A boolean indicating whether the widget should be active

Returns

Itsself (the widget) for convenience.

setBackground(color)

Set the widget’s background-color.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setBackgroundImage(image, smooth=None, scale_immediately=False)

Set the widget’s background-image.

Parameters

• image – A surface-like object (e.g. pygame.Surface) that should be rendered as the background. If this is a falsy value (e.g. None), there will be no background-image.

• smooth – A boolean indicating whether the image should be scaled smoothly or not. If this is None, the previous value will not be overwritten. The default value is None, so the previous configuration will be kept.

• scale_immediately – A boolean indicating whether the image should be scaled during this assignment. Usually the image is rescaled every time the widget is drawn. This is especially useful when the scaling-function is set to None since the image will only be resized once during this assignment therefore increasing performance. The default value is False, so the image will not be rescaled in this assignment which preserves image quality.

Returns

Itsself (the widget) for convenience.

setBorder(border)

Set the widget’s border.

Parameters

border – A PyGVisuals-border to be set. If this is a falsy value a empty border will be used.

Returns

Itsself (the widget) for convenience.

setBounds(rect)

Set the widget’s base bounds according to a pygame.Rect. This can be used to change the position of the widget or its size.

Parameters

rect – A pygame.Rect with the according position and size.

Returns

Itsself (the widget) for convenience.

setDisabeledOverlay(color)

Set the widget’s color to overlay when it is disabled.

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setFocused(focused)

Set whether the widget is focused.

A widget will be focused automatically if it is clicked on. Although the default implementation does not process this information, subclasses may use this information to determine if the user-interaction was meant to be processed by them or not.

Parameters

visible – A boolean indicating whether the widget should be focused.

Returns

Itsself (the widget) for convenience.

setForeground(color)

Set the widget’s foreground-color (not used by basic implementation).

Parameters

color – A color-like object that can be interpreted as a color by pygame (such as a tuple with RGB values).

Returns

Itsself (the widget) for convenience.

setScalingFunction(scaling_function)

Set the scaling-function used for scaling the background-image (to the widgets bounds).

Parameters

scaling_function – A function that scales a given surface-like object to a given size. See for example pygame.transform.scale. If this is a falsy value (e.g. None), the image will not be rescaled when drawn.

Returns

Itsself (the widget) for convenience.

setSmoothScaling(smooth)

Set whether the widget’s background-image will be scaled smoothly (with pygame.transform.smoothscale) or not. For more control see the widget’s ‘scaling_function’ property.

Parameters

smooth – A boolean indicating whether the image should be scaled smoothly or not.

Returns

Itsself (the widget) for convenience.

setVisible(visible)

Set the widget’s visibility. Invisible widgets will not be drawn and are inactive.

Parameters

visible – A boolean indicating whether the widget should be visible.

Returns

Itsself (the widget) for convenience.

update(*args)

Perform any updates on the widget if needed.

This is a basic implementation of focus, active-state and border-rendering; used for interaction in more advanced widget-classes.

Parameters

*args – Any arguments provided for the update. This can include an optional pygame.event.Event to process.

property active

The widget’s active status as a boolean. An inactive widget will should not respond to user-input and will have a grey overlay.

property background

The widget’s background color.

property background_image

The widget’s background-image. If this is a falsy value (e.g. None), no image will be drawn.

property border

The widget’s border (a PyGVisuals’ border).

property bounds

The widget’s base position and size as a pygame.Rect.

property disabeled_overlay

The widget’s color to overlay when it is disabled.

property focused

The widget’s focus status as a boolean. A widget will be focused automatically if it is clicked on.

property foreground

The widget’s foreground color.

property rect

The widget’s actual position and size as a pygame.Rect.

property scaling_function

The widget’s function used for scaling the background-image (to the widgets bounds). If this is a falsy value (e.g. None), the image will not be rescaled when drawn.

property smooth_scaling

The widget’ status as a boolean regarding whether the background-image will be scaled smoothly (with pygame.transform.smoothscale). Exact control of the scaling-function is given via the ‘scaling_function’ property.