pygame_gui.core.text package

Submodules

pygame_gui.core.text.horiz_rule_layout_rect module

class pygame_gui.core.text.horiz_rule_layout_rect.HorizRuleLayoutRect(height: int, colour_or_gradient: Color, rule_dimensions: Tuple[int, int] = (-1, 1), has_shade: bool = True, alignment=0)

Bases: TextLayoutRect

Represents a horizontal rule in the HTML style. This is normally a line across the width of the layout block area, but styling options can provide some variation on that theme.

Parameters:

  • height -- the current line height of the layout/font we are using when invoking the rule.

  • colour_or_gradient -- the colour or gradient of the rule.

  • rule_dimensions -- the dimensions of the rule itself, normally it is 1 pixel tall and the width of the text block layout wide.

  • has_shade -- whether the rule has 'shading' which by default is just another alpha'd line beneath it to add some depth. Doesn't work great if the line has more height to it.

  • alignment -- ALIGN_CENTER, ALIGN_LEFT or ALIGN_RIGHT. ALIGN_CENTER is the default.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

pygame_gui.core.text.html_parser module

class pygame_gui.core.text.html_parser.HTMLParser(ui_theme: IUIAppearanceThemeInterface, combined_ids: List[str], link_style: Dict[str, Any], line_spacing: float = 1.0, text_direction: int = 0)

Bases: HTMLParser

Parses a subset of HTML styled text so it is usable as text in pygame GUI. There are lots of text markup languages and this would be the class to swap in and out if you wanted to support them (Though this might need some refactoring to have a generic markup parser base class).

Parameters:

  • ui_theme -- The UI theme we are using - for colour and fonts.

  • combined_ids -- The IDs for the UI element this parser instance belongs to.

  • line_spacing -- The line spacing we use when the text is on multiple lines - defaults to 1.2.

create_styled_text_chunk(text: str)

Create a styled text chunk from the input text string and the current style.

Parameters:

text -- The text to style up into a chunk.

Returns:

A text 'chunk' all in the same style.

empty_layout_queue()

Clear out the layout queue.

error(message)

Feeds any parsing errors up the chain to the warning system.

Parameters:

message -- The message to warn about.

handle_data(data: str)

Handles parsed HTML that is not a tag of any kind, ordinary text basically.

Parameters:

data -- Some string data.

handle_endtag(tag: str)

Handles encountering an HTML end tag. Usually this will involve us popping a style off our stack of styles.

Parameters:

tag -- The end tag to handle.

handle_starttag(tag: str, attrs: List[Tuple[str, str]])

Process an HTML 'start tag' (e.g. 'b' - tags are stripped of their angle brackets) where we have a start and an end tag enclosing a range of text this is the first one of those and controls where we add the 'styling' thing to our styling stack.

Eventually we will want to expand this to handle tags like <img>.

Parameters:

  • tag -- The tag itself

  • attrs -- Attributes of the tag.

pop_style(key: str)

Remove a styling element/dictionary from the stack by it's identifying key name.

Parameters:

key -- The identifier.

push_style(key: str, styles: Dict[str, Any])

Add a new styling element onto the style stack. These are single styles generally (i.e. a font size change, or a bolding of text) rather than a load of different styles all at once. The eventual style of a character/bit of text is built up by evaluating all styling elements currently on the stack when we parse that bit of text.

Styles on top of the stack will be evaluated last, so they can overwrite elements earlier in the stack (i.e. a later 'font_size' of 5 will overwrite an earlier 'font_size' of 3).

Parameters:

  • key -- Name for this styling element so, we can identify when to remove it

  • styles -- The styling dictionary that contains the actual styling.

pygame_gui.core.text.hyperlink_text_chunk module

class pygame_gui.core.text.hyperlink_text_chunk.HyperlinkTextChunk(href: str, text: str, font: IGUIFontInterface, underlined: bool, colour: Color, bg_colour: Color, hover_colour: Color, active_colour: Color, hover_underline: bool, text_shadow_data: Tuple[int, int, int] | None = None, effect_id: str | None = None)

Bases: TextLineChunkFTFont

Represents a hyperlink to the layout system..

on_hovered()

Handles hovering over this text chunk with the mouse. Used for links.

on_unhovered()

Handles hovering over this text chunk with the mouse. Used for links.

set_active()

Handles clicking on this text chunk with the mouse. Used for links.

set_inactive()

Handles clicking on this text chunk with the mouse. Used for links.

pygame_gui.core.text.image_layout_rect module

class pygame_gui.core.text.image_layout_rect.ImageLayoutRect(image_path, float_position, padding: Padding)

Bases: TextLayoutRect

Represents an image that sits in the text.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

pygame_gui.core.text.line_break_layout_rect module

class pygame_gui.core.text.line_break_layout_rect.LineBreakLayoutRect(dimensions: Tuple[int, int], font)

Bases: TextLayoutRect

Represents a line break, or new line, instruction in the text to the text layout system.

Parameters:

dimensions -- The dimensions of the 'line break', the height is the important thing so the new lines are spaced correctly for the last active font.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

pygame_gui.core.text.text_box_layout module

class pygame_gui.core.text.text_box_layout.TextBoxLayout(input_data_queue: Deque[TextLayoutRect], layout_rect: Rect, view_rect: Rect, line_spacing: float, default_font_data: Dict[str, Any], allow_split_dashes: bool = True, text_direction: int = 0, text_x_scroll_enabled: bool = False, editable: bool = False)

Bases: object

Class to layout multiple lines of text to fit in a defined column.

The base of the 'column' rectangle is set once the data supplied has been laid out to fit in the width provided.

add_chunks_to_hover_group(link_hover_chunks: List[TextLayoutRect])

Pass in a list of layout rectangles to add to a hover-able group. Usually used for hyperlinks.

Parameters:

link_hover_chunks --

align_left_all_rows(x_padding)

Align all rows to the left hand side of the layout.

Parameters:

x_padding -- the amount of padding to insert to on the left before the text starts.

align_right_all_rows(x_padding)

Align all rows to the right hand side of the layout.

Parameters:

x_padding -- the amount of padding to insert to on the right before the text starts.

append_layout_rects(new_queue)

Add some LayoutRects on to the end of the current layout. This should be relatively fast as we don't have to rejig everything before the additions, and some of the time don't need to redraw everything either.

This is new so there may still be some bugs to iron out.

Parameters:

new_queue --

backspace_at_cursor()

Deletes a single character behind the edit cursor. Mimics a standard word processor 'backspace' operation.

blit_finalised_text_to_surf(surface: Surface)

Lets us blit a finalised text surface to an arbitrary surface. Useful for doing stuff with text effects.

Parameters:

surface -- the target surface to blit onto.

clear_effects()

Clear text layout level text effect parameters.

clear_final_surface()

Clears the finalised surface.

delete_at_cursor()

Deletes a single character in front of the edit cursor. Mimics a standard word processor 'delete' operation.

delete_selected_text()

Delete the currently selected text.

finalise_to_new()

Finalises our layout to a brand-new surface that this method creates.

finalise_to_surf(surface: Surface)

Take this layout, with everything positioned in the correct place and finalise it to a surface.

May be called again after changes to the layout? Update surf?

Parameters:

surface -- The surface we are going to blit the contents of this layout onto.

find_cursor_position_from_click_pos(click_pos) → int

Find an edit text cursor position in the text from a click.

Here we don't set it, we just find it and return it.

Parameters:

click_pos -- This is the pixel position we want to find the nearest cursor spot to.

Returns:

an integer representing the character index position in the text

get_cursor_colour() → Color

Get the current colour of the editing carat/text cursor.

Returns:

a pygame.Color object containing the current colour.

get_cursor_index()

Get the current character index, in the text layout's text, of the current edit cursor position.

Essentially the reverse of 'set_cursor_position()'.

get_cursor_pos_move_down_one_row(last_cursor_horiz_index)

Returns a cursor character position in the row directly above the current cursor position if possible.

get_cursor_pos_move_up_one_row(last_cursor_horiz_index)

Returns a cursor character position in the row directly above the last horizontal cursor position if possible.

horiz_center_all_rows(method='rect')

Horizontally center all rows of text in the layout. This uses 'rectangular' centering by default, which could also be called mathematical centering. Sometimes this type of centering looks wrong - e.g. for arrows, so we instead have an option to use a 'center of mass' style centering for right facing and left facing triangles.

Parameters:

method -- this is an ID for the method of centering to use, for almost all cases this will be the default 'rect' style basic centering. However, if you are trying to center an arrow you might try 'right_triangle' or 'left_triangle'

insert_layout_rects(layout_rects: Deque[TextLayoutRect], row_index: int, item_index: int, chunk_index: int)

Insert some new layout rectangles from a queue at specific place in the current layout. Hopefully this means we only need to redo the layout after this point... we shall see.

Warning: this is a test function, it may not be up-to-date with current text layout features

Parameters:

  • layout_rects -- the new TextLayoutRects to insert.

  • row_index -- which row we are sticking them on.

  • item_index -- which chunk we are sticking them into.

  • chunk_index -- where in the chunk we are sticking them.

insert_line_break(layout_index: int, parser: HTMLParser | None)

Insert a line break into the text layout at a given point.

Parameters:

  • layout_index -- the character index at which to insert the line break.

  • parser -- An optional HTML parser for text styling data

insert_text(text: str, layout_index: int, parser: HTMLParser | None = None)

Insert some text into the text layout at a given point. Handy when e.g. pasting a chunk of text into an existing layout.

Parameters:

  • text -- the text to insert.

  • layout_index -- the character index at which to insert the text.

  • parser -- An optional HTML parser for text styling data

redraw_other_chunks(not_these_chunks)

Useful for text effects. TODO: no idea how this will play with images? Probably badly.

Parameters:

not_these_chunks -- The chunks not to redraw

Returns:

reprocess_layout_queue(layout_rect)

Re-lays out already parsed text data. Useful to call if the layout requirements have changed but the text data hasn't.

Parameters:

layout_rect -- The new layout rectangle.

set_alpha(alpha: int)

Set the overall alpha level of this text box from 0 to 255. This allows us to fade text in and out of view.

Parameters:

alpha -- integer from 0 to 255.

set_cursor_colour(colour: Color)

Set the colour of the editing carat/text cursor for this text layout.

Parameters:

colour -- The colour to set it to.

set_cursor_from_click_pos(click_pos)

Set the edit cursor position in the text layout from a pixel position. Generally used to set the text editing cursor position from a mouse click.

Parameters:

click_pos -- This is the pixel position we want the cursor to appear near to.

set_cursor_position(cursor_pos)

Set the edit cursor position in the text layout.

Parameters:

cursor_pos -- This is the index of the character the cursor should appear before.

set_cursor_to_end_of_current_row()

Set the edit cursor position in the text layout to the end of the current row and returns the overall position in the text

Returns:

the overall position of the cursor in the text layout, after setting it to the end of the current row

set_cursor_to_start_of_current_row()

Set the edit cursor position in the text layout to the end of the current row and returns the overall position in the text

Returns:

the overall position of the cursor in the text layout, after setting it to the end of the current row

set_default_text_colour(colour)

Set the default text colour, used when no other colour is set for a portion of the text.

Parameters:

colour -- the colour to use as the default text colour.

set_default_text_shadow_colour(colour)

Set the default text shadow colour, used when no other colour is set for the shadow of a portion of the text.

Parameters:

colour -- the colour to use as the default text shadow colour.

set_text_selection(start_index, end_index)

Set a portion of the text layout as 'selected'. This is useful when editing chunks of text all at once (e.g. copying to a memory 'clipboard', deleting a block of text).

Parameters:

  • start_index -- the character index to start the selection area at.

  • end_index -- the character index to end the selection area at.

toggle_cursor()

Toggle the visibility of the edit cursor.

Used routinely by editable text boxes to make the cursor flash to catch user attention.

turn_off_cursor()

Makes the edit test cursor invisible.

turn_on_cursor()

Makes the edit test cursor visible.

update_text_with_new_text_end_pos(new_end_pos: int)

Sets a new end position for the text in this block and redraws it, so we can display a 'typing' type effect. The text will only be displayed up to the index position set here.

Parameters:

new_end_pos -- The new ending index for the text string.

vert_align_bottom_all_rows(y_padding)

Align all rows to the bottom of the layout.

Parameters:

y_padding -- the amount of padding to insert below before the text starts.

vert_align_top_all_rows(y_padding)

Align all rows to the top of the layout.

Parameters:

y_padding -- the amount of padding to insert above before the text starts.

vert_center_all_rows()

Vertically center all rows of text in the layout.

TODO: I expect we should have the arrow centering methods in here too.

pygame_gui.core.text.text_box_layout_row module

class pygame_gui.core.text.text_box_layout_row.TextBoxLayoutRow(row_start_x, row_start_y, row_index, line_spacing, layout)

Bases: Rect

A single line of text-like stuff to be used in a text box type layout.

add_item(item: TextLayoutRect)

Add a new item to the row. Items are added left to right.

If you wanted to build a right to left writing system layout, changing this might be a good place to start.

Parameters:

item -- The new item to add to the text row

align_left_row(start_x: int, floating_rects: List[TextLayoutRect])

Align this row to the left.

Parameters:

  • start_x -- Effectively the padding. Indicates how many pixels from the edge to start this row.

  • floating_rects -- Floating rectangles we need to align around

align_right_row(start_x: int, floating_rects)

Align this row to the right.

Parameters:

  • floating_rects -- Any floating rects in the row

  • start_x -- Effectively the padding. Indicates how many pixels from the right edge of the layout to start this row.

at_start()

Returns true if this row has no items in it.

Returns:

True if we are at the start of the row.

clear()
'Clears' the current row from its target surface by setting the

area taken up by this row to transparent black.

Hopefully the target surface is supposed to be transparent black when empty.

finalise(surface: Surface, current_end_pos: int | None = None, cumulative_letter_count: int | None = None)

Finalise this row, turning it into pixels on a pygame surface. Generally done once we are finished applying styles and laying out the text.

Parameters:

  • surface -- The surface we are finalising this row on to.

  • current_end_pos -- Optional parameter indicating the current end position of the visible text. This lets us do the 'typewriter' effect.

  • cumulative_letter_count -- A count of how many letters we have already finalised. Also helps with the 'typewriter' effect.

find_cursor_pos_from_click_pos(click_pos: Tuple[int, int], num_rows: int)

Find an edit cursor position from a pixel position - usually originating from a mouse click.

Parameters:

  • num_rows --

  • click_pos -- The pixel position to use.

get_cursor_index() → int

Get the current character index of the cursor

Returns:

the character index the edit cursor currently occupies.

horiz_center_row(floating_rects, method='rect')

Horizontally center this row of text.

This uses 'rectangular' centering by default, which could also be called mathematical centering. Sometimes this type of centering looks wrong - e.g. for arrows, so we instead have an option to use a 'center of mass' style centering for right facing and left facing triangles.

Parameters:

  • floating_rects -- Any floating rects in the row.

  • method -- this is an ID for the method of centering to use, for almost all cases this will be the default 'rect' style basic centering. However, if you are trying to center an arrow you might try 'right_triangle' or 'left_triangle'

insert_new_item_at_start(new_item: TextLayoutRect)

Insert a new item to the row at the start

Parameters:

new_item -- The new item to add to the text row

insert_text(text: str, letter_row_index: int, parser: HTMLParser | None = None)

Insert the provided text into this row at the given location.

Parameters:

  • text -- the text to insert.

  • letter_row_index -- the index in the row at which to insert this text.

  • parser -- An optional HTML parser for text styling data

merge_adjacent_compatible_chunks()

Merge chunks of text next to each other in this row that have identical styles.

Should leave the minimum possible chunks in a row given the set styles for text.

rewind_row(layout_rect_queue)

Use this to add items from the row back onto a layout queue, useful if we've added something to the layout that means that this row needs to be re-run through the layout code.

Parameters:

layout_rect_queue -- A layout queue that contains items to be laid out in order.

set_cursor_from_click_pos(click_pos: Tuple[int, int], num_rows: int)

Set the current edit cursor position from a pixel position - usually originating from a mouse click.

Parameters:

  • num_rows --

  • click_pos -- The pixel position to use.

set_cursor_position(cursor_pos)

Set the edit cursor position by a character index.

Parameters:

cursor_pos -- the character index in this row to put the edit cursor after.

set_default_text_colour(colour)

Set the default colour of the text.

Parameters:

colour -- The colour to set.

set_default_text_shadow_colour(colour)

Set the default colour of the text shadow.

Parameters:

colour -- The colour to set.

toggle_cursor()

Toggles the visibility of the edit cursor/carat.

Generally used to make it flash on and off to catch the attention of the user.

turn_off_cursor()

Makes the edit test cursor invisible.

turn_on_cursor()

Makes the edit test cursor visible.

vert_align_items_to_row()

Align items in this row to the row's vertical position.

pygame_gui.core.text.text_layout_rect module

class pygame_gui.core.text.text_layout_rect.Padding(top, right, bottom, left)

Bases: tuple

bottom

Alias for field number 2

left

Alias for field number 3

right

Alias for field number 1

top

Alias for field number 0

class pygame_gui.core.text.text_layout_rect.TextFloatPosition(value)

Bases: Enum

An enumeration covering the three possible 'float' positions of a layout rect in a text layout.

'NONE' is the normal case. This rectangle will be treated as one in a row of rectangles

'LEFT' will allow other rectangles to flow around this one on the right hand side with

potentially multiple rows of shorter rectangles taking up its vertical height.

'RIGHT' the same as left except on the other side.

Generally we use this to embed images into the flow of a text box.

class pygame_gui.core.text.text_layout_rect.TextLayoutRect(dimensions: Tuple[int, int], *, can_split=False, float_pos: TextFloatPosition = TextFloatPosition.NONE, should_span=False)

Bases: Rect

A base class for use in Layouts.

can_split()

Return True if this rectangle can be split into smaller rectangles by a layout.

Returns:

True if splittable, False otherwise.

clear(optional_rect: Rect | None = None)

Clear the space this rect takes up on the finalised surface.

Parameters:

optional_rect -- A rect to clear instead of the default self rect, useful for effects.

abstract finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

float_pos() → TextFloatPosition

Return the 'floating' status of this rectangle. can be TextFloatPosition.left, TextFloatPosition.right or TextFloatPosition.none and the default, used by most rectangles, is TextFloatPosition.none.

Used to make text flow around images.

Returns:

returns the float status of this rectangle.

should_span()

Return True if this rectangle should be expanded/shrunk to fit the available width in a layout.

Returns:

True if should span the width, False otherwise.

split(requested_x: int, line_width: int, row_start_x: int, allow_split_dashes: bool = True) → TextLayoutRect | None

Try to perform a split operation on this rectangle. Often rectangles will be split at the nearest point that is still less than the request (i.e. to the left of the request in the common left-to-right text layout case) .

Parameters:

  • requested_x -- the requested place to split this rectangle along it's width.

  • line_width -- the width of the current line.

  • row_start_x -- the x start position of the row.

  • allow_split_dashes -- whether we allow text to be split with dashes either side. allowing this makes direct text editing more annoying.

vertical_overlap(other_rect: Rect) → bool

Test if two rectangles overlap one another in the y axis.

Parameters:

other_rect --

Returns:

True if they overlap.

pygame_gui.core.text.text_line_chunk module

A bit of renderable text that fits on a single line and all in the same style.

Blocks of text are made up of many text chunks. At the simplest level there would be one per line.

On creation a text chunk calculates how much space it will take up when rendered to a surface and stores this size information in a rectangle. These rectangles can then be used in layout calculations.

Once a layout for the text chunk is finalised the chunk's render function can be called to add the chunk onto it's final destination.

class pygame_gui.core.text.text_line_chunk.TextLineChunkFTFont(text: str, font: IGUIFontInterface, underlined: bool, colour: Color | ColourGradient, using_default_text_colour: bool, bg_colour: Color | ColourGradient, text_shadow_data: Tuple[int, int, int, Color, bool] | None = None, max_dimensions: List[int] | None = None, effect_id: str | None = None)

Bases: TextLayoutRect

A Text line chunk (text on the same horizontal line in the same style)

add_text(input_text: str)

Adds text to the end of this text chunk. Theoretically it should be faster to add text on the end of a text layout than sticking it in the middle.

Parameters:

input_text -- The text to add.

backspace_letter_at_index(index)

Removes the letter before the supplied character index.

Parameters:

index -- the index of the character to 'backspace' from.

can_split()

Return True if this rectangle can be split into smaller rectangles by a layout.

Returns:

True if splittable, False otherwise.

clear(optional_rect: Rect | None = None)

Clear the finalised/rendered text in this chunk to an invisible/empty surface.

clear_effects()

Clear any effect parameters stored on the text chunk back to default values.

delete_letter_at_index(index)

Removes the letter after the supplied character index.

Parameters:

index -- the index of the character to 'delete' from.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

grab_pre_effect_surface()

Grab the 'pre effect' surface, used to get a 'normal' pre-effect surface to apply effects to.

insert_text(input_text: str, index: int)

Insert a new string of text into this chunk and update the chunk's data.

NOTE: We don't redraw the text immediately here as this size of this chunk changing may affect the position of other chunks later in the layout.

Parameters:

  • input_text -- the new text to insert.

  • index -- the index we are sticking the new text at.

redraw()

Redraw a surface that has already been finalised once before.

set_alpha(alpha: int)

Set the overall alpha level of this text chunk from 0 to 255. This allows us to fade text in and out of view.

Parameters:

alpha -- integer from 0 to 255.

set_offset_pos(offset_pos: Tuple[int, int])

Set an offset that lets us move the text around a bit for effects

Parameters:

offset_pos -- integers that offset the x & y position of this text chunk

set_rotation(rotation: int)

Set a rotation that lets us move the text around a bit for effects

Parameters:

rotation -- a rotation in degrees

set_scale(scale: float)

Set a scale that lets us move the text around a bit for effects

Parameters:

scale -- a rotation in degrees

split(requested_x: int, line_width: int, row_start_x: int, allow_split_dashes: bool = True) → TextLayoutRect | None

Try to perform a split operation on this chunk at the requested pixel position.

Often rectangles will be split at the nearest point that is still less than the request (i.e. to the left of the request in the common left-to-right text layout case) .

Parameters:

  • requested_x -- the requested place to split this rectangle along its width.

  • line_width -- the width of the current line.

  • row_start_x -- the x start position of the row.

  • allow_split_dashes -- whether we allow text to be split with dashes either side. allowing this makes direct text editing more annoying.

split_index(index)

Try to perform a split operation on this chunk at the requested character index.

Parameters:

index -- the requested index at which to split this rectangle along it's width.

style_match(other_text_chunk: TextLineChunkFTFont)

Do two layout rectangles have matching styles (generally applies only to actual text).

x_pos_to_letter_index(x_pos: int)

Convert a horizontal, or 'x' pixel position into a letter/character index in this text chunk. Commonly used for converting mouse clicks into letter positions for positioning the text editing cursor/carat.

Module contents

class pygame_gui.core.text.BounceEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

A bounce effect

apply_effect()

Apply the effect to the text

has_text_changed() → bool

Lets us know when the effect has changed enough to warrant us redrawing the text.

Returns:

True if it is is time to redraw our text.

update(time_delta: float)

Updates the effect with amount of time passed since the last call to update.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.ExpandContractEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

Expands to a specified scale and then returns

apply_effect()

Apply the effect to the text

has_text_changed() → bool

Lets us know when the effect has changed enough to warrant us redrawing the text.

Returns:

True if it is is time to redraw our text.

update(time_delta: float)

Updates the effect with amount of time passed since the last call to update.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.FadeInEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

A fade in effect for the text box. Allows us to fade the text, though this class just takes care of fading up an alpha value over time.

apply_effect()

Apply the effect to the text

get_final_alpha() → int

Returns the current alpha value of the fade.

Returns:

The alpha value, between 0 and 255

has_text_changed() → bool

Lets us know when the fade alpha has changed enough (i.e. by a whole int) to warrant us redrawing the text box with the new alpha value.

Returns:

True if it is is time to redraw our text.

update(time_delta: float)

Updates the fade with amount of time passed since the last call to update.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.FadeOutEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

A fade out effect for the text box. Allows us to fade the text, though this class just takes care of fading out an alpha value over time.

apply_effect()

Apply the effect to the text

get_final_alpha() → int

Returns the current alpha value of the fade.

Returns:

The alpha value, between 0 and 255

has_text_changed() → bool

Lets us know when the fade alpha has changed enough (i.e. by a whole int) to warrant us redrawing the text box with the new alpha value.

Returns:

True if it is is time to redraw our text.

update(time_delta: float)

Updates the fade with amount of time passed since the last call to update.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.HTMLParser(ui_theme: IUIAppearanceThemeInterface, combined_ids: List[str], link_style: Dict[str, Any], line_spacing: float = 1.0, text_direction: int = 0)

Bases: HTMLParser

Parses a subset of HTML styled text so it is usable as text in pygame GUI. There are lots of text markup languages and this would be the class to swap in and out if you wanted to support them (Though this might need some refactoring to have a generic markup parser base class).

Parameters:

  • ui_theme -- The UI theme we are using - for colour and fonts.

  • combined_ids -- The IDs for the UI element this parser instance belongs to.

  • line_spacing -- The line spacing we use when the text is on multiple lines - defaults to 1.2.

create_styled_text_chunk(text: str)

Create a styled text chunk from the input text string and the current style.

Parameters:

text -- The text to style up into a chunk.

Returns:

A text 'chunk' all in the same style.

empty_layout_queue()

Clear out the layout queue.

error(message)

Feeds any parsing errors up the chain to the warning system.

Parameters:

message -- The message to warn about.

handle_data(data: str)

Handles parsed HTML that is not a tag of any kind, ordinary text basically.

Parameters:

data -- Some string data.

handle_endtag(tag: str)

Handles encountering an HTML end tag. Usually this will involve us popping a style off our stack of styles.

Parameters:

tag -- The end tag to handle.

handle_starttag(tag: str, attrs: List[Tuple[str, str]])

Process an HTML 'start tag' (e.g. 'b' - tags are stripped of their angle brackets) where we have a start and an end tag enclosing a range of text this is the first one of those and controls where we add the 'styling' thing to our styling stack.

Eventually we will want to expand this to handle tags like <img>.

Parameters:

  • tag -- The tag itself

  • attrs -- Attributes of the tag.

pop_style(key: str)

Remove a styling element/dictionary from the stack by it's identifying key name.

Parameters:

key -- The identifier.

push_style(key: str, styles: Dict[str, Any])

Add a new styling element onto the style stack. These are single styles generally (i.e. a font size change, or a bolding of text) rather than a load of different styles all at once. The eventual style of a character/bit of text is built up by evaluating all styling elements currently on the stack when we parse that bit of text.

Styles on top of the stack will be evaluated last, so they can overwrite elements earlier in the stack (i.e. a later 'font_size' of 5 will overwrite an earlier 'font_size' of 3).

Parameters:

  • key -- Name for this styling element so, we can identify when to remove it

  • styles -- The styling dictionary that contains the actual styling.

class pygame_gui.core.text.HorizRuleLayoutRect(height: int, colour_or_gradient: Color, rule_dimensions: Tuple[int, int] = (-1, 1), has_shade: bool = True, alignment=0)

Bases: TextLayoutRect

Represents a horizontal rule in the HTML style. This is normally a line across the width of the layout block area, but styling options can provide some variation on that theme.

Parameters:

  • height -- the current line height of the layout/font we are using when invoking the rule.

  • colour_or_gradient -- the colour or gradient of the rule.

  • rule_dimensions -- the dimensions of the rule itself, normally it is 1 pixel tall and the width of the text block layout wide.

  • has_shade -- whether the rule has 'shading' which by default is just another alpha'd line beneath it to add some depth. Doesn't work great if the line has more height to it.

  • alignment -- ALIGN_CENTER, ALIGN_LEFT or ALIGN_RIGHT. ALIGN_CENTER is the default.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

class pygame_gui.core.text.HyperlinkTextChunk(href: str, text: str, font: IGUIFontInterface, underlined: bool, colour: Color, bg_colour: Color, hover_colour: Color, active_colour: Color, hover_underline: bool, text_shadow_data: Tuple[int, int, int] | None = None, effect_id: str | None = None)

Bases: TextLineChunkFTFont

Represents a hyperlink to the layout system..

on_hovered()

Handles hovering over this text chunk with the mouse. Used for links.

on_unhovered()

Handles hovering over this text chunk with the mouse. Used for links.

set_active()

Handles clicking on this text chunk with the mouse. Used for links.

set_inactive()

Handles clicking on this text chunk with the mouse. Used for links.

class pygame_gui.core.text.ImageLayoutRect(image_path, float_position, padding: Padding)

Bases: TextLayoutRect

Represents an image that sits in the text.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

class pygame_gui.core.text.LineBreakLayoutRect(dimensions: Tuple[int, int], font)

Bases: TextLayoutRect

Represents a line break, or new line, instruction in the text to the text layout system.

Parameters:

dimensions -- The dimensions of the 'line break', the height is the important thing so the new lines are spaced correctly for the last active font.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

class pygame_gui.core.text.ShakeEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

A shake effect

apply_effect()

Apply the effect to the text

has_text_changed() → bool

Lets us know when the effect has changed enough to warrant us redrawing the text.

Returns:

True if it is is time to redraw our text.

update(time_delta: float)

Updates the effect with amount of time passed since the last call to update.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.SimpleTestLayoutRect(dimensions: Tuple[int, int], *, create_split_points=True, float_pos=TextFloatPosition.NONE)

Bases: TextLayoutRect

Useful class for testing layout generation. Multi coloured boxes make it easy to distinguish different layout Rects from one another and it's possible to set all the layout options in the constructor/initializer to represent different types of layout rect.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

static gen_random_colour()

Creates a random colour using the golden ratio method.

Helps make the test layout rects reasonably distinctive from each other.

split(requested_x: int, line_width: int, row_start_x: int, allow_split_dashes: bool = True)

Try to perform a split operation on this rectangle. Often rectangles will be split at the nearest point that is still less than the request (i.e. to the left of the request in the common left-to-right text layout case) .

Parameters:

  • requested_x -- the requested place to split this rectangle along it's width.

  • line_width -- the width of the current line.

  • row_start_x -- the x start position of the row.

  • allow_split_dashes -- whether we allow text to be split with dashes either side. allowing this makes direct text editing more annoying.

class pygame_gui.core.text.TextBoxLayout(input_data_queue: Deque[TextLayoutRect], layout_rect: Rect, view_rect: Rect, line_spacing: float, default_font_data: Dict[str, Any], allow_split_dashes: bool = True, text_direction: int = 0, text_x_scroll_enabled: bool = False, editable: bool = False)

Bases: object

Class to layout multiple lines of text to fit in a defined column.

The base of the 'column' rectangle is set once the data supplied has been laid out to fit in the width provided.

add_chunks_to_hover_group(link_hover_chunks: List[TextLayoutRect])

Pass in a list of layout rectangles to add to a hover-able group. Usually used for hyperlinks.

Parameters:

link_hover_chunks --

align_left_all_rows(x_padding)

Align all rows to the left hand side of the layout.

Parameters:

x_padding -- the amount of padding to insert to on the left before the text starts.

align_right_all_rows(x_padding)

Align all rows to the right hand side of the layout.

Parameters:

x_padding -- the amount of padding to insert to on the right before the text starts.

append_layout_rects(new_queue)

Add some LayoutRects on to the end of the current layout. This should be relatively fast as we don't have to rejig everything before the additions, and some of the time don't need to redraw everything either.

This is new so there may still be some bugs to iron out.

Parameters:

new_queue --

backspace_at_cursor()

Deletes a single character behind the edit cursor. Mimics a standard word processor 'backspace' operation.

blit_finalised_text_to_surf(surface: Surface)

Lets us blit a finalised text surface to an arbitrary surface. Useful for doing stuff with text effects.

Parameters:

surface -- the target surface to blit onto.

clear_effects()

Clear text layout level text effect parameters.

clear_final_surface()

Clears the finalised surface.

delete_at_cursor()

Deletes a single character in front of the edit cursor. Mimics a standard word processor 'delete' operation.

delete_selected_text()

Delete the currently selected text.

finalise_to_new()

Finalises our layout to a brand-new surface that this method creates.

finalise_to_surf(surface: Surface)

Take this layout, with everything positioned in the correct place and finalise it to a surface.

May be called again after changes to the layout? Update surf?

Parameters:

surface -- The surface we are going to blit the contents of this layout onto.

find_cursor_position_from_click_pos(click_pos) → int

Find an edit text cursor position in the text from a click.

Here we don't set it, we just find it and return it.

Parameters:

click_pos -- This is the pixel position we want to find the nearest cursor spot to.

Returns:

an integer representing the character index position in the text

get_cursor_colour() → Color

Get the current colour of the editing carat/text cursor.

Returns:

a pygame.Color object containing the current colour.

get_cursor_index()

Get the current character index, in the text layout's text, of the current edit cursor position.

Essentially the reverse of 'set_cursor_position()'.

get_cursor_pos_move_down_one_row(last_cursor_horiz_index)

Returns a cursor character position in the row directly above the current cursor position if possible.

get_cursor_pos_move_up_one_row(last_cursor_horiz_index)

Returns a cursor character position in the row directly above the last horizontal cursor position if possible.

horiz_center_all_rows(method='rect')

Horizontally center all rows of text in the layout. This uses 'rectangular' centering by default, which could also be called mathematical centering. Sometimes this type of centering looks wrong - e.g. for arrows, so we instead have an option to use a 'center of mass' style centering for right facing and left facing triangles.

Parameters:

method -- this is an ID for the method of centering to use, for almost all cases this will be the default 'rect' style basic centering. However, if you are trying to center an arrow you might try 'right_triangle' or 'left_triangle'

insert_layout_rects(layout_rects: Deque[TextLayoutRect], row_index: int, item_index: int, chunk_index: int)

Insert some new layout rectangles from a queue at specific place in the current layout. Hopefully this means we only need to redo the layout after this point... we shall see.

Warning: this is a test function, it may not be up-to-date with current text layout features

Parameters:

  • layout_rects -- the new TextLayoutRects to insert.

  • row_index -- which row we are sticking them on.

  • item_index -- which chunk we are sticking them into.

  • chunk_index -- where in the chunk we are sticking them.

insert_line_break(layout_index: int, parser: HTMLParser | None)

Insert a line break into the text layout at a given point.

Parameters:

  • layout_index -- the character index at which to insert the line break.

  • parser -- An optional HTML parser for text styling data

insert_text(text: str, layout_index: int, parser: HTMLParser | None = None)

Insert some text into the text layout at a given point. Handy when e.g. pasting a chunk of text into an existing layout.

Parameters:

  • text -- the text to insert.

  • layout_index -- the character index at which to insert the text.

  • parser -- An optional HTML parser for text styling data

redraw_other_chunks(not_these_chunks)

Useful for text effects. TODO: no idea how this will play with images? Probably badly.

Parameters:

not_these_chunks -- The chunks not to redraw

Returns:

reprocess_layout_queue(layout_rect)

Re-lays out already parsed text data. Useful to call if the layout requirements have changed but the text data hasn't.

Parameters:

layout_rect -- The new layout rectangle.

set_alpha(alpha: int)

Set the overall alpha level of this text box from 0 to 255. This allows us to fade text in and out of view.

Parameters:

alpha -- integer from 0 to 255.

set_cursor_colour(colour: Color)

Set the colour of the editing carat/text cursor for this text layout.

Parameters:

colour -- The colour to set it to.

set_cursor_from_click_pos(click_pos)

Set the edit cursor position in the text layout from a pixel position. Generally used to set the text editing cursor position from a mouse click.

Parameters:

click_pos -- This is the pixel position we want the cursor to appear near to.

set_cursor_position(cursor_pos)

Set the edit cursor position in the text layout.

Parameters:

cursor_pos -- This is the index of the character the cursor should appear before.

set_cursor_to_end_of_current_row()

Set the edit cursor position in the text layout to the end of the current row and returns the overall position in the text

Returns:

the overall position of the cursor in the text layout, after setting it to the end of the current row

set_cursor_to_start_of_current_row()

Set the edit cursor position in the text layout to the end of the current row and returns the overall position in the text

Returns:

the overall position of the cursor in the text layout, after setting it to the end of the current row

set_default_text_colour(colour)

Set the default text colour, used when no other colour is set for a portion of the text.

Parameters:

colour -- the colour to use as the default text colour.

set_default_text_shadow_colour(colour)

Set the default text shadow colour, used when no other colour is set for the shadow of a portion of the text.

Parameters:

colour -- the colour to use as the default text shadow colour.

set_text_selection(start_index, end_index)

Set a portion of the text layout as 'selected'. This is useful when editing chunks of text all at once (e.g. copying to a memory 'clipboard', deleting a block of text).

Parameters:

  • start_index -- the character index to start the selection area at.

  • end_index -- the character index to end the selection area at.

toggle_cursor()

Toggle the visibility of the edit cursor.

Used routinely by editable text boxes to make the cursor flash to catch user attention.

turn_off_cursor()

Makes the edit test cursor invisible.

turn_on_cursor()

Makes the edit test cursor visible.

update_text_with_new_text_end_pos(new_end_pos: int)

Sets a new end position for the text in this block and redraws it, so we can display a 'typing' type effect. The text will only be displayed up to the index position set here.

Parameters:

new_end_pos -- The new ending index for the text string.

vert_align_bottom_all_rows(y_padding)

Align all rows to the bottom of the layout.

Parameters:

y_padding -- the amount of padding to insert below before the text starts.

vert_align_top_all_rows(y_padding)

Align all rows to the top of the layout.

Parameters:

y_padding -- the amount of padding to insert above before the text starts.

vert_center_all_rows()

Vertically center all rows of text in the layout.

TODO: I expect we should have the arrow centering methods in here too.

class pygame_gui.core.text.TextBoxLayoutRow(row_start_x, row_start_y, row_index, line_spacing, layout)

Bases: Rect

A single line of text-like stuff to be used in a text box type layout.

add_item(item: TextLayoutRect)

Add a new item to the row. Items are added left to right.

If you wanted to build a right to left writing system layout, changing this might be a good place to start.

Parameters:

item -- The new item to add to the text row

align_left_row(start_x: int, floating_rects: List[TextLayoutRect])

Align this row to the left.

Parameters:

  • start_x -- Effectively the padding. Indicates how many pixels from the edge to start this row.

  • floating_rects -- Floating rectangles we need to align around

align_right_row(start_x: int, floating_rects)

Align this row to the right.

Parameters:

  • floating_rects -- Any floating rects in the row

  • start_x -- Effectively the padding. Indicates how many pixels from the right edge of the layout to start this row.

at_start()

Returns true if this row has no items in it.

Returns:

True if we are at the start of the row.

clear()
'Clears' the current row from its target surface by setting the

area taken up by this row to transparent black.

Hopefully the target surface is supposed to be transparent black when empty.

finalise(surface: Surface, current_end_pos: int | None = None, cumulative_letter_count: int | None = None)

Finalise this row, turning it into pixels on a pygame surface. Generally done once we are finished applying styles and laying out the text.

Parameters:

  • surface -- The surface we are finalising this row on to.

  • current_end_pos -- Optional parameter indicating the current end position of the visible text. This lets us do the 'typewriter' effect.

  • cumulative_letter_count -- A count of how many letters we have already finalised. Also helps with the 'typewriter' effect.

find_cursor_pos_from_click_pos(click_pos: Tuple[int, int], num_rows: int)

Find an edit cursor position from a pixel position - usually originating from a mouse click.

Parameters:

  • num_rows --

  • click_pos -- The pixel position to use.

get_cursor_index() → int

Get the current character index of the cursor

Returns:

the character index the edit cursor currently occupies.

horiz_center_row(floating_rects, method='rect')

Horizontally center this row of text.

This uses 'rectangular' centering by default, which could also be called mathematical centering. Sometimes this type of centering looks wrong - e.g. for arrows, so we instead have an option to use a 'center of mass' style centering for right facing and left facing triangles.

Parameters:

  • floating_rects -- Any floating rects in the row.

  • method -- this is an ID for the method of centering to use, for almost all cases this will be the default 'rect' style basic centering. However, if you are trying to center an arrow you might try 'right_triangle' or 'left_triangle'

insert_new_item_at_start(new_item: TextLayoutRect)

Insert a new item to the row at the start

Parameters:

new_item -- The new item to add to the text row

insert_text(text: str, letter_row_index: int, parser: HTMLParser | None = None)

Insert the provided text into this row at the given location.

Parameters:

  • text -- the text to insert.

  • letter_row_index -- the index in the row at which to insert this text.

  • parser -- An optional HTML parser for text styling data

merge_adjacent_compatible_chunks()

Merge chunks of text next to each other in this row that have identical styles.

Should leave the minimum possible chunks in a row given the set styles for text.

rewind_row(layout_rect_queue)

Use this to add items from the row back onto a layout queue, useful if we've added something to the layout that means that this row needs to be re-run through the layout code.

Parameters:

layout_rect_queue -- A layout queue that contains items to be laid out in order.

set_cursor_from_click_pos(click_pos: Tuple[int, int], num_rows: int)

Set the current edit cursor position from a pixel position - usually originating from a mouse click.

Parameters:

  • num_rows --

  • click_pos -- The pixel position to use.

set_cursor_position(cursor_pos)

Set the edit cursor position by a character index.

Parameters:

cursor_pos -- the character index in this row to put the edit cursor after.

set_default_text_colour(colour)

Set the default colour of the text.

Parameters:

colour -- The colour to set.

set_default_text_shadow_colour(colour)

Set the default colour of the text shadow.

Parameters:

colour -- The colour to set.

toggle_cursor()

Toggles the visibility of the edit cursor/carat.

Generally used to make it flash on and off to catch the attention of the user.

turn_off_cursor()

Makes the edit test cursor invisible.

turn_on_cursor()

Makes the edit test cursor visible.

vert_align_items_to_row()

Align items in this row to the row's vertical position.

class pygame_gui.core.text.TextEffect

Bases: object

Base class for text effects

apply_effect()

Apply the effect to the text

get_final_alpha() → int

The alpha value to draw the text box with. By default it is 255.

Returns:

The default alpha value for a text box.

has_text_changed() → bool

Stub that returns False

Returns:

False

update(time_delta: float)

Stub for overriding.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.TextFloatPosition(value)

Bases: Enum

An enumeration covering the three possible 'float' positions of a layout rect in a text layout.

'NONE' is the normal case. This rectangle will be treated as one in a row of rectangles

'LEFT' will allow other rectangles to flow around this one on the right hand side with

potentially multiple rows of shorter rectangles taking up its vertical height.

'RIGHT' the same as left except on the other side.

Generally we use this to embed images into the flow of a text box.

class pygame_gui.core.text.TextLayoutRect(dimensions: Tuple[int, int], *, can_split=False, float_pos: TextFloatPosition = TextFloatPosition.NONE, should_span=False)

Bases: Rect

A base class for use in Layouts.

can_split()

Return True if this rectangle can be split into smaller rectangles by a layout.

Returns:

True if splittable, False otherwise.

clear(optional_rect: Rect | None = None)

Clear the space this rect takes up on the finalised surface.

Parameters:

optional_rect -- A rect to clear instead of the default self rect, useful for effects.

abstract finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

float_pos() → TextFloatPosition

Return the 'floating' status of this rectangle. can be TextFloatPosition.left, TextFloatPosition.right or TextFloatPosition.none and the default, used by most rectangles, is TextFloatPosition.none.

Used to make text flow around images.

Returns:

returns the float status of this rectangle.

should_span()

Return True if this rectangle should be expanded/shrunk to fit the available width in a layout.

Returns:

True if should span the width, False otherwise.

split(requested_x: int, line_width: int, row_start_x: int, allow_split_dashes: bool = True) → TextLayoutRect | None

Try to perform a split operation on this rectangle. Often rectangles will be split at the nearest point that is still less than the request (i.e. to the left of the request in the common left-to-right text layout case) .

Parameters:

  • requested_x -- the requested place to split this rectangle along it's width.

  • line_width -- the width of the current line.

  • row_start_x -- the x start position of the row.

  • allow_split_dashes -- whether we allow text to be split with dashes either side. allowing this makes direct text editing more annoying.

vertical_overlap(other_rect: Rect) → bool

Test if two rectangles overlap one another in the y axis.

Parameters:

other_rect --

Returns:

True if they overlap.

class pygame_gui.core.text.TextLineChunkFTFont(text: str, font: IGUIFontInterface, underlined: bool, colour: Color | ColourGradient, using_default_text_colour: bool, bg_colour: Color | ColourGradient, text_shadow_data: Tuple[int, int, int, Color, bool] | None = None, max_dimensions: List[int] | None = None, effect_id: str | None = None)

Bases: TextLayoutRect

A Text line chunk (text on the same horizontal line in the same style)

add_text(input_text: str)

Adds text to the end of this text chunk. Theoretically it should be faster to add text on the end of a text layout than sticking it in the middle.

Parameters:

input_text -- The text to add.

backspace_letter_at_index(index)

Removes the letter before the supplied character index.

Parameters:

index -- the index of the character to 'backspace' from.

can_split()

Return True if this rectangle can be split into smaller rectangles by a layout.

Returns:

True if splittable, False otherwise.

clear(optional_rect: Rect | None = None)

Clear the finalised/rendered text in this chunk to an invisible/empty surface.

clear_effects()

Clear any effect parameters stored on the text chunk back to default values.

delete_letter_at_index(index)

Removes the letter after the supplied character index.

Parameters:

index -- the index of the character to 'delete' from.

finalise(target_surface: Surface, target_area: Rect, row_chunk_origin: int, row_chunk_height: int, row_bg_height: int, row_line_spacing_height: int, x_scroll_offset: int = 0, letter_end: int | None = None)

Bake the contents of this layout rect onto a surface.

Parameters:

  • target_surface --

  • target_area --

  • row_chunk_origin --

  • row_chunk_height --

  • row_bg_height --

  • row_line_spacing_height --

  • x_scroll_offset --

  • letter_end --

grab_pre_effect_surface()

Grab the 'pre effect' surface, used to get a 'normal' pre-effect surface to apply effects to.

insert_text(input_text: str, index: int)

Insert a new string of text into this chunk and update the chunk's data.

NOTE: We don't redraw the text immediately here as this size of this chunk changing may affect the position of other chunks later in the layout.

Parameters:

  • input_text -- the new text to insert.

  • index -- the index we are sticking the new text at.

redraw()

Redraw a surface that has already been finalised once before.

set_alpha(alpha: int)

Set the overall alpha level of this text chunk from 0 to 255. This allows us to fade text in and out of view.

Parameters:

alpha -- integer from 0 to 255.

set_offset_pos(offset_pos: Tuple[int, int])

Set an offset that lets us move the text around a bit for effects

Parameters:

offset_pos -- integers that offset the x & y position of this text chunk

set_rotation(rotation: int)

Set a rotation that lets us move the text around a bit for effects

Parameters:

rotation -- a rotation in degrees

set_scale(scale: float)

Set a scale that lets us move the text around a bit for effects

Parameters:

scale -- a rotation in degrees

split(requested_x: int, line_width: int, row_start_x: int, allow_split_dashes: bool = True) → TextLayoutRect | None

Try to perform a split operation on this chunk at the requested pixel position.

Often rectangles will be split at the nearest point that is still less than the request (i.e. to the left of the request in the common left-to-right text layout case) .

Parameters:

  • requested_x -- the requested place to split this rectangle along its width.

  • line_width -- the width of the current line.

  • row_start_x -- the x start position of the row.

  • allow_split_dashes -- whether we allow text to be split with dashes either side. allowing this makes direct text editing more annoying.

split_index(index)

Try to perform a split operation on this chunk at the requested character index.

Parameters:

index -- the requested index at which to split this rectangle along it's width.

style_match(other_text_chunk: TextLineChunkFTFont)

Do two layout rectangles have matching styles (generally applies only to actual text).

x_pos_to_letter_index(x_pos: int)

Convert a horizontal, or 'x' pixel position into a letter/character index in this text chunk. Commonly used for converting mouse clicks into letter positions for positioning the text editing cursor/carat.

class pygame_gui.core.text.TiltEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

Tilts to an angle and then returns

apply_effect()

Apply the effect to the text

has_text_changed() → bool

Lets us know when the effect has changed enough to warrant us redrawing the text.

Returns:

True if it is is time to redraw our text.

update(time_delta: float)

Updates the effect with amount of time passed since the last call to update.

Parameters:

time_delta -- time in seconds since last frame.

class pygame_gui.core.text.TypingAppearEffect(text_owner: IUITextOwnerInterface, params: Dict[str, Any] | None = None, text_sub_chunk: TextLineChunkFTFont | None = None)

Bases: TextEffect

Does that 'typewriter' effect where the text in a box appears one character at a time as if they were being typed by an invisible hand.

apply_effect()

Apply the effect to the text

has_text_changed() → bool

Test if we should redraw the text.

Returns:

True if we should redraw, False otherwise.

update(time_delta: float)

Updates the effect with amount of time passed since the last call to update. Adds a new letter to the progress every self.time_per_letter seconds.

Parameters:

time_delta -- time in seconds since last frame.