A pygame library for creating apps (and games).
includes:
- images
- animations
- shapes
- buttons
- highly functional text boxes (keep in mind that these things are difficult to make ok)
- text selecting
- copy/cut/paste support
- customizable highlighting support
- line tracking
- scrolling
- 3D rendering (low quality, but works)
- and more!
(all classes can be imported from ui_library.py)
You will see these referenced a lot.
These constants are hard-coded (may change in the future):
PATH: "./ui_resources"
TAB_SIZE: 4
CURSOR_BLINK_TIME = 50
CURSOR_COLOR: Color(190, 190, 190)
SCROLL_MULTIPLIER: 15
These constants can be modified in editor_settings.json:
FONT: "font" (formatted to replace {PATH} with PATH)
TEXT_SIZE: "text_size"
TEXT_COLOR: "text_color"
TEXT_BG_COLOR: "text_bg_color"
TEXT_BG_COLOR_LIGHTER: "text_bg_color_lighter"
TEXT_HIGHLIGHT: "text_highlight"
BUTTON_HOVER_COLOR: "button_hover_color"
BUTTON_CLICK_COLOR: "button_click_color"
POPUP_FADE_COLOR: "popup_fade_color"
LINE_SEPERATOR_COLOR: "line_seperator_color"
START_RESOLUTION: "start_resolution"
- Inheret from this when you create custom rendering/event classes.
- Subclasses must implement these methods:
_event(self, editor: Editor, X: int, Y: int) -> None_update(self, editor: Editor, X: int, Y: int) -> None
X and Y should be added to all rendering/event positioning calculations,
this is how you keep your object's position relative to its parent.
Used to represent colors.
r: int: red value; clamped between 0 and 255.
g: int: green value; clamped between 0 and 255.
b: int: blue value; clamped between 0 and 255.
a: int | None: alpha value; default None, otherwise clamped between 0 and 255.
r: red value (0-255).
g: green value (0-255).
b: blue value (0-255).
a: alpha value (0-255) or None.
with_alpha() -> Color
returns a Color instance with a set to self.a or 255 if None.
without_alpha() -> Color
returns a Color instance with a set to None.
(classmethod) color(obj:Color|Image|Animation|list|tuple|int|None, allow_none:bool=True, allow_image:bool=True) -> Color|Image|Animation|None
if obj is a Color, it is returned.
if obj is an Image or Animation, it will be returned unless allow_image is False, in which case a ValueError is raised.
if obj is None, it will be returned unless allow_none is False, in which case a ValueError is raised.
if obj is a list or tuple and it's length is 3 or 4, it will be converted into a Color and returned.
if obj is an int, it will be converted to a Color and returned. (ints can be defined as 0xFFFFFF (hex color))
if obj is anything else, a ValueError is raised.
passing an instance of Color to list() or tuple() will return a 3-4 length list/tuple of integers from 0-255.
Used for rendering images to the screen.
file_location: str: path to an image file, you must include the file extension.
x: int: x position.
y: int: y position.
width: int: width of the image. (image stretches to this width)
height: int: height of the image. (image stretches to this height)
surface: the pygame.Surface object the image is rendered on.
_surface: the pygame.Surface object that the original image is rendered on. This surface is kept at the image's true resolution.
copy() -> Image
returns a new Image object.
section(x:int, y:int, w:int, h:int) -> Image
returns a cropped portion of the Image.
resize(width:int, height:int) -> self
resizes to a new size. uses original image for maximum quality.
scale(self, amnt:float) -> self
multiplies width and height by amnt.
functionally equivellent to resize().
Used for animated surfaces.
NOTE: this class has not been very thoroughly tested, if you run into issues with it, please create an issue on the github.
x: int: x position.
y: int: y position.
**options: 3 valid configurations:
OPTION 1: (this will be refered to as the spritesheet configuration)
sprite_sheet: str: path to a sprite sheet image file.
(optional) sprite_width: int: width of each sprite on the sheet. Defaults to the width of the sprite sheet (after offset crop is applied)
(optional) sprite_height: int: height of each sprite on the sheet.
(optional) order: list[int]: what order to play frames. Default is in order from 0 to however many frames are made from the spritesheet - 1.
(optional) loop: bool: whether the animation should loop infinitely, if False, it will only play once.
(optional) fps: float: how many frames to play in a seconds. Defaults to 1.
(optional) resize: tuple[int, int]: size to resize each sprite to.
(optional) offset: tuple[int, int]: offset for finding the first sprite. effectively crops the top and left of the spritesheet before sprites are loaded.
OPTION 2: (this will be refered to as the frame path configuration)
frames: list[str]: list of frame paths.
(optional) order: list[int]: what order to play frames in, default is in order from 0 to however many frames are made from the spritesheet - 1.
(optional) loop: bool: whether the animation should loop infinitely, or only play once.
(optional) fps: float: how many frames to play in a seconds, defaults to 1.
OPTION 3: (this will be refered to as the custom configuration)
custom: list[pygame.Surface]: list of pygame surfaces to use as sprite frames.
(optional) order: list[int]: what order to play frames in, default is in order from 0 to however many frames are made from the spritesheet - 1.
(optional) loop: bool: whether the animation should loop infinitely, or only play once.
(optional) fps: float: how many frames to play in a seconds, defaults to 1.
x: int: set this to change the objects x position.
y: int: set this to change the objects y position.
config_type: str: set to either "spritesheet_config", "frames_config", or "custom_config".
order: list[int]: list of frame indices.
loop: bool: whether the animation will loop infinitely.
fps: float: frames per second of the animation.
hovered: bool: whether the cursor is hovering this object.
current_frame: int: current index of the order list.
spritesheet configuration:
sprite_sheet: str: the path to the sprite sheet.
source: str: the path to the sprite sheet.
sprite_width: int: the width you declared as the sprite width, or the width of the image after the offset cropping is applied.
sprite_height: int: the height you declared as the sprite height, or the height of the image after the offset cropping is applied.
offsetX: int: the x part of offset.
offsetY: int: the y part of offset.
_sheet: pygame.Surface: the full sprite sheet surface.
_frames: list[pygame.Surface]: the generated list of frames.
frames configuration:
frames: list[str]: list of frame sources.
source: list[str]: list of frame sources.
_frames: list[pygame.Surface]: list of frame surfaces.
custom configuration:
_frames: list[pygame.Surface]: the list of frames given during initialization.
sprite_width: int: the width of the first surface in the _frames list.
sprite_height: int: the height of the first surface in the _frames list.
copy() -> Animation
returns a copy of the animation.
section(x:int, y:int, width:int, height:int) -> Animation
returns a copy of the animation with every frame cropped to the given size.
resize(width:int, height:int) -> self
stretches every frame to fit to width and height.
scale(amnt:float) -> self
scales every frame by amnt.
on_hover(editor:Editor) -> None
re-assign this to any function you want. This method is called when the cursor moves over the animation object.
off_hover(editor:Editor) -> None
re-assign this to any function you want. This method is called when the cursor moves off the animation object.
on_end() -> None
re-assign this to any function you want. This method is called when the animation ends. (only possible when loop is False)
Used for rendering text to the screen.
Does not support newlines; see MultilineText.
x: int: x position.
y: int: y position.
min_width: int = 1: minimum width of the pygame surface.
content: str = "": text content to display. newlines are replaced with spaces.
text_color: Color | tuple | int = TEXT_COLOR: font color.
text_bg_color: Color | tuple | int = TEXT_BG_COLOR: font background color.
text_size: int = TEXT_SIZE: font size.
x: int: set this to change the objects x position.
y: int: set this to change the objects y position.
content: str: read this for the current text being displayed.
width: int: read this for the current width of the text surface.
height: int: read this for the height of the text surface. (this value will never change during runtime)
surface: pygame.Surface: the surface that the text is rendered on.
set_text(text: str) -> None
sets the Text object's displayed text.
Does NOT support newlines. (use MultilineTextBox instead)
Used for getting text input from a user.
Multiple lines not supprted; see MultilineTextBox.
x: int: x position.
y: int: y position.
min_width: int = 1: minimum text box width.
content: str = "": initial text box content.
text_color: Color | tuple | int = TEXT_COLOR: text color.
text_bg_color: Color | tuple | int = TEXT_BG_COLOR: text background color.
text_size: int = TEXT_SIZE: text size.
x: int: set this to change the objects x position.
y: int: set this to change the objects y position.
min_width: int: set this to limit the width of the surface. the width will never be less than this.
focused: bool: this is set to True when the user has left-clicked this object.
hovered: bool: this is set to False while the cursor is hovering this object.
get_selection() -> str | None
returns selected text, if any.
set_selection(text:str) -> None
if text is selected, this method replaces it with the text, otherwise it does nothing.
newlines are replaced with spaces.
get_content() -> str
returns the entire content of the text box.
set_content(content:str) -> None
sets the text box's content to content, replacing newlines with spaces.
text selection is reset when this method is called.
on_enter(text: str) -> None
re-assign this to any function you want. This method is called when the user presses the enter/return key while typing in the text box.
Used to control grouping and layering of UIElements.
layers: dict[int, list[UIElement]]: a mapping of layer heights to a list of UIElements.
x: int = 0: an optional x-position, all UIElements are handled relative to this x-position.
y: int = 0: an optional y-position, all UIElements are handled relative to this y-position.
layers: dict[int, list[UIElement]]: the object's layer mapping.
x: int: an x value that offsets all UIElements in this layering.
y: int: a y value that offsets all UIElements in this layering.
Used to make another UIElement be draggable by the user.
x: int: x position of the draggable hitbox.
y: int: y position of the draggable hitbox.
width: int: width of the draggable hitbox.
height: int: height of the draggable hitbox.
lock_horizontal: bool = False: setting to True prevents this object's x position from changing.
lock_vertical: bool = False: setting to True prevents this object's y position from changing.
children: list[UIElement] = ...: list of children that will be moved by the draggable object.
x: int: the draggable hitbox's x position.
y: int: the draggable hitbox's y position.
width: int: the draggable hitbox's width.
height: int: the draggable hitbox's height.
held: bool: this is True while the user is dragging this object.
hovered: bool: this is True when the user is hovering this object. children of the draggable object take priority for hovering.
children: list[UIElement]: list of the draggable's children.
lock_horizontal: bool: whether horizontal movement is allowed.
lock_vertical: bool: whether vertical movement is allowed.
Used to create a user-resizable object.
Currently only resizable from the bottom edge, right edge, and bottom right-corner.
x: int: x position.
y: int: y position.
width: int: object's inital width.
height: int: object's initial height.
color: Color | Image | tuple | int = TEXT_BG_COLOR: fill color of the resizable object.
min_width: int = 1: minimum width of the object.
min_height: int = 1: minimum height of the object.
max_width: int = ...: maximum width of the object. "..." lets it resize infinitely.
max_height: int = ...: maximum height of the object. "..." lets it resize infinitely.
can_drag: bool = True: whether the entire Resizable object can be dragged around.
x: int: the resizable hitbox's x position.
y: int: the resizable hitbox's y position.
width: int: the resizable hitbox's width.
height: int: the resizable hitbox's height.
min_width: int: minimum resize width.
min_height: int: minimum resize height.
max_width: int | Ellipsis: maximum resize width.
max_height: int | Ellipsis: maximum resize height.
color: Color | Image: color/background texture of the resizable object.
can_drag: bool: whether this object can be dragged.
hovered: bool: this value is True when this object is hovered.
right_resize: Draggable: the draggable part for the right edge of the resizable object.
down_resizable: Draggable: the draggable part for the bottom edge of the resizable object.
corner_resize: Draggable: the draggable part for the bottom right edge of the resizable object.
bg: Box: the background surface UIElement.
used to link attributes of any object (i.e. size or position)
parent: Any: parent object.
child: Any: child object.
keyword-only args:
parent_attr: str | None = None: parent attribute. Cannot be mixed with parent_method.
child_attr: str | None = None: child attribute. Cannot be mixed with child_method.
parent_method: str | None = None: parent value getter. Cannot be mixed with parent_attr.
child_method: str | None = None: child value setter. Cannot be mixed with child_attr.
link_handler: Callable | None = None: function to modify the parent value before giving it to the child object.
parent: Any: the parent object.
child: Any: the child object.
parent_attr: str | None: parent attribute name.
child_attr: str | None: child attribute name.
parent_method: str | None: parent value getter name.
child_method: str | None: child value setter name.
link_handler: Callable: function to modify parent's value before giving it to child.
Used to get input from the user.
x: int: button's x position.
y: int: button's y position.
width: int: button's width.
height: int | None = None: button's height. Defaults to text_size + 4.
text: str = "": text to display on button.
bg_color: Color | Image | tuple | int | None = TEXT_BG_COLOR: background color of button.
text_color: Color | tuple | int = TEXT_COLOR: button text color.
text_size: int = TEXT_SIZE: button font size.
hover_color: Color | tuple | list = TEXT_BG_COLOR: button color when hovered.
click_color: Color | tuple | list = TEXT_BG_COLOR: button color when clicked.
x: int: button's x position.
y: int: button's y position.
width: int: button's width.
height: int: button's height.
text: str: button text.
bg_color: Color: button default color.
hover_color: Color: button color when hovered.
click_color: Color: button color when clicked.
text_color: Color: button text color.
lheld: bool: True when user is holding down the left mouse button.
rheld: bool: True when user is holding down the right mouse button.
hovered: bool: True when the button is hovered.
text_size: int: size of button text.
surface: pygame.Surface: button texture surface.
pre_blit(editor: Editor, X: int, Y:int) -> None
re-assign this function to whatever. This function is called immediately before the button renders.
on_left_click(editor: Editor) -> None,
off_left_click(editor: Editor) -> None,
on_right_click(editor: Editor) -> None,
off_right_click(editor: Editor) -> None,
on_hover(editor: Editor) -> None,
off_hover(editor: Editor) -> None
re-assign these methods to hook into their respective events.
Used for creating page tabs similar to a web-browsed or IDE.
x: int: x position.
y: int: y position.
width: int: width of the tab content area.
height: int: height of the tab content area.
tab_style: Tabs.Style: what style tabs are displayed in.
Tabs.Style is an Enum containing TOP, BOTTOM, LEFT, RIGHT, and MENU.
tab_data: dict[str: list[UIElement]]: mapping of tab names, and the content associated with that tab.
**options: