Thorpy

set_bck_color(self, color, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the background color of the element (depending on how its style handles it).
Mandatory arguments
color : either a RGB or RGBA color, or an gradient color (see tagged example).
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

set_opacity_bck_color(self, value, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the opacity (alpha value) of the element's background color.
Mandatory arguments
value : (int) between 0 and 255
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

get_bck_color(self)
Returns self's background color if there is a style attached to this element.

get_main_bck_color(self)
Returns self's main background color if there is a style attached to this element. The difference with get_bck_color is that the latter can return gradient color, whereas get_main_bck_color necessarily returns either a single RGB tuple, a single RGBA tuple or None.

set_font_color(self, color, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the font color of the element (depending on how its style handles it).
Mandatory arguments
color : a RGB color.
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

set_font_size(self, size, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the font size of the element (depending on how its style handles it).
Mandatory arguments
size : (integer) new font size.
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

set_font_name(self, name, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the font family of the element (depending on how its style handles it).
Mandatory arguments
name : (string) new font name.
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

set_max_text_width(self, width, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the maximum text width of the element before line breaks are automatically inserted.
Mandatory arguments
width : (float or integer) the new max width. If a value smaller than 1 is given, then text is not automatically processed as a multiline text. Otherwise, line breaks are automatically inserted to fit the maximum width specified.
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

set_font_rich_text_tag(self, tag, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set the tag for creating rich text. See the tagged examples for rich text usage.
Mandatory arguments
tag : (string) the new tag for rich texts.
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

set_style_attr(self, attr, value, states="all", copy_style=True, refresh=True, apply_to_children=False)
Set any style attribute of the element.
Mandatory arguments
attr : (str) the name of the style attribute.
value : the value of the style attribute.
Optionnal arguments
states : either 'all' or any state name (e.g. 'hover') or a sequence of state names (excluding 'all').
copy_style : (bool) make a copy of the current style, so that it does not affect element sharing the same style object.
refresh : (bool) refresh element surfaces.
apply_to_children : (bool) apply the same change to children elements.

get_current_style(self)
Returns the current style object of the element, using its current state.

get_style(self, state)
Returns the style object of the element corresponding to a given state.
state : name of the state ("normal", "pressed", "hover" or "locked").

move(self, dx, dy)
Moves the element (update from the current position).
Mandatory arguments
dx : the number of pixels along x axis.
dy : the number of pixels along y axis.

clamp(self, rect)
Moves self inside rect argument, using Pygame's clamp function.
rect : the pygame Rect object in which the element should be clamped.

set_topleft(self, x, y)
Set the absolute topleft position of the element.
Mandatory arguments
x : x-coordinate (in pixels) of the topleft corner of the element. None can be passed to leave this coordinate unchanged.
y : y-coordinate (in pixels) of the topleft corner of the element. None can be passed to leave this coordinate unchanged.

set_bottomright(self, x, y)
Set the absolute bottomright position of the element.
Mandatory arguments
x : x-coordinate (in pixels) of the bottomright corner of the element. None can be passed to leave this coordinate unchanged.
y : y-coordinate (in pixels) of the bottomright corner of the element. None can be passed to leave this coordinate unchanged.

set_bottomleft(self, x, y)
Set the absolute bottomleft position of the element.
Mandatory arguments
x : x-coordinate (in pixels) of the bottomleft corner of the element. None can be passed to leave this coordinate unchanged.
y : y-coordinate (in pixels) of the bottomleft corner of the element. None can be passed to leave this coordinate unchanged.

set_topright(self, x, y)
Set the absolute topright position of the element.
Mandatory arguments
x : x-coordinate (in pixels) of the topright corner of the element. None can be passed to leave this coordinate unchanged.
y : y-coordinate (in pixels) of the topright corner of the element. None can be passed to leave this coordinate unchanged.

set_center(self, x, y)
Set the absolute position of the element's center.
Mandatory arguments
x : x-coordinate (in pixels) of the center of the element. None can be passed to leave this coordinate unchanged.
y : y-coordinate (in pixels) of the center of the element. None can be passed to leave this coordinate unchanged.

center_on(self, what)
Centers the element on another, or on a pygame Surface or Rect.
what : either a pygame Rect, a 2-tuple, a pygame Surface or a thorpy element. It is also possible to specify what = 'screen' as a shortcut for screen's rect.

stick_to(self, other, self_side, other_side, delta=(0,0), move_x=True, move_y=True)
Sticks the element to another.
Mandatory arguments
other : another element or pygame surface.
self_side : side of the element beeing sticked. Can be 'left', 'right', 'top' or 'bottom'.
other_side : side of the other element. Can be 'left', 'right', 'top' or 'bottom'.
Optionnal arguments
delta : 2-tuple delta (pixels) to apply after the element has been moved.
move_x : (bool) set to False if x-axis movement should be ignored.
move_y : (bool) set to False if y-axis movement should be ignored.

englobe_children(self, margins=(5,5), adapt_parent=True, size_limit=(float("inf"), float("inf")))
Resizes the element so that its size englobes that of its children.
Optionnal arguments
margins : space between self's border and its children.
adapt_parent : (bool) if False, parent of self won't be adapted accordingly.
size_limit : (2-tuple) specifying the maximum width and height of the new size.

set_size(self, size, adapt_parent=True, adapt_text=False)
Rebuild element's surfaces with imposed size.
Mandatory arguments
size : 2-tuple on the form (w, h), where w and/or h can be None (in this case, it remains unchanged).
adapt_parent : (bool) if True, then parent's size is adapted to fit the new self's size.
adapt_text : (bool) if True, then self's text is automatically cut in several lines if needed, for instance if the new size if smaller than the old one and the textual content is now overflowing.

rotate(self, angle, also_children=True, states="all", reactivate_surface_copy=True)
Rotate the images of the element. Experimental, be cautious ! In most cases, only angles that are multiple of 90 degrees will yield fancy results. Important note: as for now, element's shadows are not rotated.
Mandatory arguments
angle : the angle of rotation in degrees.
Optionnal arguments
also_children : if True, recursively rotates the children elements (for grouping rotation).
states : the states affected (either a list of strings or a specific state name or 'all')
reactivate_surface_copy : if needed, reactivate surface copy (for memory savings) if True.

get_current_width(self)
Returns the width of the element using its current state.

get_current_height(self)
Returns the height of the element using its current state.

get_text_size(self, state=None)
Return the size of the text within the element.
Optionnal arguments
state : specify which state has to be taken into account (if None, then current state is used).

sort_children(self, mode="v", align="center", gap=5, margins=(5,5), offset=0, nx="auto", ny="auto", grid_gaps=(5,5), horizontal_first=False, englobe_children=True, limit_size_if_englobe=(float("inf"),float("inf")))
Sort/organize children elements. See the tagged examples as they illustrate a lot of common situations.
Optionnal arguments
mode : either 'v' (vertical), 'h' (horizontal) or 'grid'.
align : either 'center', 'left' or 'right.
gap : (integer) space between elements.
margins : 2-tuple of integers specifying the margins.
offset : (integer) offset of the whole rearrangment.
nx : number of columns (in grid mode).
ny : number of lines (in grid mode).
grid_gaps : gap to use if grid mode used.
horizontal_first : (bool) whether columns are filled first in grid mode (otherwise, lines are filled first).
englobe_children : update self's size after sorting so that it englobes its children.
limit_size_if_englobe : (2-tuple) specifying the maximum width and height of the new size, if englobe_children is True.

resort(self)
Try to sort using the last parameters as for last call to sort.

other_is_dragged(self)
Returns True if another element is beeing dragged by the user.

get_value(self)
Returns the value stored in the element. For non-specialized elements, simply returns their text content.

set_value(self, text)
Set the value stored in the element. For non-specialized elements, simply change their text content.

launch_alone(self, func_before=None, click_outside_cancel=True, reaction=None, func_after=None)
Creates a time loop to interact with this element alone. The element thus 'pops' to the screen for the user.
Optionnal arguments
func_before : either None or a function to call before each update and draw of the element.
func_after : either None or a function to call after each update and draw of the element.
click_outside_cancel : (bool) if True, the user can discard the popped element.
reaction : either None or a function to call each frame and that takes as only argument the pygame event.

launch_and_lock_others(self, other, func_before=None, click_outside_cancel=True, reaction=None, func_after=None)
Creates a time loop to interact with this element. The element thus 'pops' to the screen for the user. The other elements enters in lock mode ; they are drawn to the screen, but not updated according to events.
Mandatory arguments
other : parent element of the other elements to block.
Optionnal arguments
func_before : either None or a function to call before each update and draw of the element.
func_after : either None or a function to call after each update and draw of the element.
click_outside_cancel : (bool) if True, the user can discard the popped element.
reaction : either None or a function to call each frame and that takes as only argument the pygame event.

launch_nonblocking(self, loop=None, click_outside_cancel=True)
Inserts the element in the current loop, so that other elements are still reacting. Works only when using thorpy.Updater's loop.
Optionnal arguments
loop : specify a given loop as reference. If None, then use the current loop.
click_outside_cancel : (bool) if True, the user can discard the popped element.

get_updater(self, fps=-1, esc_quit=False)
Returns a thorpy Updater object so that you can use thorpy elements in your own loop without thinking about how to update and draw thorpy elements. See the tagged examples for standard usage.
Optionnal arguments
fps : (float) the framerate of the update. If fps is negative (which is the case by default), framerate control is unactivated (typically, you want it if your application already limitates FPS).
esc_quit : (bool) set to True if you want that the updater exits when user press escape.

draw(self)
Draws the element according to its current state. Note that in most cases, you won't use this method, as the updater of the element will handle it (see tagged example).

generate_surfaces(self)
Build the element surfaces for each style and refresh the element's rect accordingly.

get_current_frame(self)
Returns the image of the element being displayed.

copy_normal_state(self, only_normal)
Avoid building multiple times surfaces that are actually the same.
Mandatory arguments
only_normal : (bool) if False, surfaces are build for each state separately.

generate_shadow(self, fast="auto", shadowgen=None, states="all", uniform=False)
Generates a shadow and binds it to the element. This function is not meant to be called within the app loop, but only at initialization.
Optionnal arguments
fast : (bool) if True, will generate a rectangular shadow whatever the element's shape is. Otherwise, this may be slow. You can also pass 'auto' : in this case, you let Thorpy choose whether the computing time is acceptable and automatically set fast to False if needed.
shadowgen : you can indicate a shadow generator (see tagged examples) or None to let Thorpy choose.
states : a string or a sequence of strings indicating for which states the shadow should be generated.
uniform : (bool) if True and fast is also True, then the shadow wont have per-pixel alpha values.

set_special_frames(self, frames)
Bypasses the element's style to display special frames instead, until the animation is finished.
frames : a sequence of pygame surfaces.

stop_special_frames(self)
Stops the special frames display (see set_special_frames)

add_child(self, element, i=-1)
Add a child to the element.
Mandatory arguments
element : the child element to add.
Optionnal arguments
i : (integer) where in the list of children the new one should be added. By default -1 : it goes to the end.

add_children(self, elements)
Add children to the element.
Mandatory arguments
elements : (list) the children elements to add.

remove_child(self, element)
Remove a child to the element.
element : the children element to add.

replace_child(self, old_one, new_one, refresh=True)
Replaces a child of the element.
Mandatory arguments
old_one : the children element to remove.
new_one : the children element to add (new_one replaces old_one).
Optionnal arguments
refresh : (bool) if False, self's surface and arrangment won't be refreshed.

get_children(self)
Returns the children of the element, but not the children of the children and so on.

root(self)
Returns the 'oldest' parent of the element, i.e. the parent of its parent of its parent and so on. Returns the element itself if it has no parent.

get_all_descendants(self)
Returns all the descendants of the elements, including self, i.e. its children, the children of its children and so on.

has_descendant_in_state(self, state)
Returns True if any of the descendants is in the specified state. By 'descendants', we mean either self or self's children, or self's children's children and so on.
state : (string) either 'normal', 'pressed', 'hover' or 'locked'.

at_unclick(self, **params)
Function called each time the element is unclicked by the mouse. IMPORTANT: in most cases, this is what you want to redefine as the common user 'click', e.g. my_button.at_unclick = my_function_to_launch.
The parameters passed can be sat as my_button.at_unclick_params = {...}.

at_hover(self, **params)
Function called each time the element starts to be hovered by the mouse. The parameters passed can be sat as my_button.at_hover_params = {...}.

at_unhover(self, **params)
Function called each time the element stops to be hovered by the mouse. The parameters passed can be sat as my_button.at_unhover_params = {...}.

at_drag(self, dx, dy, **params)
Function called each time the element is dragged by the mouse. The parameters passed can be sat as my_button.at_drag_params = {...}.
dx : the mouse_rel along x-axis (it is mandatory that your function accepts it as first argument).
dy : the mouse_rel along x-axis (it is mandatory that your function accepts it as first argument).

at_cancel(self, **params)
Function called each time the element is cancelled (deactivated for many elements).

_at_click(self, **params)
Function called each time the element is clicked by the mouse. IMPORTANT: in most cases, this is NOT what you want to redefine as the common user 'click'. We strongly advise you not to redefine this function, as usual behaviour of buttons is to react to unclick rather than click events, which can result in incompatible events handling between elements. The parameters passed can be sat as my_button._at_click_params = {...}.

get_current_state(self)
Return the current state (string) of the element.

set_invisible(self, value, recursive=False)
Set the element as invisible.
value : if False, the element is visible, otherwise it is invisible.
recursive : if True, recursively call this on the children elements.

set_locked(self, value)
Set the current state from 'locked' to 'normal' or from 'normal' to 'locked'.
value : (bool) if True, the new state will be 'locked', wheras if False, the new state will be 'normal'. Also adapt the children states.

set_draggable(self, x_axis=True, y_axis=True, cannot_drag_outside=True, cannot_draw_outside=True, adapt_cursor_style=True)
Set whether the element can be dragged by the user. If you set your element as draggable, keep in mind that whenever you change the size of the parent element it resets the original position of the draggable element. If you want to always keep the position of the element, make sure you set to False the adapt_parent argument of methods that modify the appearance of the parent and any of its children, e.g : some_sister_element.set_text("This is a new text", adapt_parent=False).
Optionnal arguments
x_axis : (bool) determines whether the element can be dragger on x-axis.
y_axis : (bool) determines whether the element can be dragger on y-axis.
cannot_drag_outside : (bool) if True, the element cannot be dragged outside of its parent.
cannot_draw_outside : (bool) if True, the element cannot be drawn outside of its parent.
adapt_cursor_style : (bool) if True, mouse cursor will appear as a hand when hovering the element.