Frame

Rectangular container UI element with background and border.

Overview

A Frame is a rectangular UI element that can contain other drawable elements. Use frames for panels, buttons, dialog boxes, HUDs, and other UI containers. Frames support clipping children to their bounds and caching their subtree for performance optimization.

Quick Reference

import mcrfpy

scene = mcrfpy.Scene("demo")
mcrfpy.current_scene = scene

# Create a styled panel
panel = mcrfpy.Frame(pos=(100, 100), size=(200, 150))
panel.fill_color = mcrfpy.Color(40, 40, 40, 200)
panel.outline_color = mcrfpy.Color(100, 100, 100)
panel.outline = 2

# Add to scene
scene.children.append(panel)

# Frames can contain children
label = mcrfpy.Caption(text="Panel Title", pos=(10, 10))
panel.children.append(label)

# Enable clipping for scrollable content
panel.clip_children = True

# Animate properties
panel.animate("opacity", 0.5, 1.0, "easeInOut")

Constructor

mcrfpy.Frame(pos=None, size=None, **kwargs)

Arguments:

pos (tuple, optional): Position as (x, y). Default: (0, 0)
size (tuple, optional): Size as (width, height). Default: (0, 0)

Keyword Arguments:

fill_color (Color): Background fill color. Default: (0, 0, 0, 128)
outline_color (Color): Border outline color. Default: (255, 255, 255, 255)
outline (float): Border thickness. Default: 0
on_click (callable): Click event handler
children (list): Initial child elements; each is moved here from any parent it had
visible (bool): Visibility state. Default: True
opacity (float): Opacity (0.0-1.0). Default: 1.0
z_index (int): Rendering order. Default: 0
name (str): Element name for finding
clip_children (bool): Clip children to frame bounds. Default: False
cache_subtree (bool): Cache rendering to texture. Default: False

Properties

Property	Type	Description
`x`, `y`	float	Position coordinates
`w`, `h`	float	Size dimensions
`pos`	Vector	Position as a Vector
`fill_color`	Color	Background color
`outline_color`	Color	Border color
`outline`	float	Border thickness
`children`	UICollection	Child elements
`clip_children`	bool	Whether to clip children to bounds
`cache_subtree`	bool	Cache rendering to texture
`visible`	bool	Visibility toggle
`opacity`	float	Transparency (0.0-1.0)
`z_index`	int	Rendering order (lower = first)
`name`	str	Element name for finding
`parent`	Drawable	Parent element or None
`hovered`	bool	Mouse hover state (read-only)
`on_click`	callable	Click event handler
`on_enter`	callable	Mouse enter handler
`on_exit`	callable	Mouse exit handler
`on_move`	callable	Mouse move handler

Methods

Method	Description
`animate(property, target, duration, ...)`	Animate a property over time
`move(dx, dy)`	Move by relative offset
`resize(width, height)`	Resize to new dimensions
`realign()`	Reapply alignment relative to parent

The read-only bounds property returns a (pos, size) pair of Vectors.

Children

frame.children is a list-like UICollection: append, extend, insert, remove, pop, clear, index, count, find, indexing and slices. A drawable has exactly one parent and appears once, so adding it always moves it: out of its old parent, or to its new slot if it is already in this collection.

panel = mcrfpy.Frame(pos=(0, 0), size=(200, 100))
other = mcrfpy.Frame(pos=(220, 0), size=(200, 100))
label = mcrfpy.Caption(text="HP", pos=(5, 5))

panel.children.append(label)
other.children.append(label)        # moves: label leaves panel
assert label.parent is other and len(panel.children) == 0

panel.children.clear()              # remove every child at once

try:
    label_box = mcrfpy.Frame()
    other.children.append(label_box)
    label_box.children.append(other)    # other would contain itself
except ValueError:
    pass                                # refused; nothing changed

Making a drawable its own ancestor raises ValueError, as does a value list that names one drawable twice (extend([x, x]), children[0:1] = [x, x]). extend() checks every item before adding any.

Caching

With cache_subtree=True a frame renders itself and all its children to a texture and re-blits it while nothing changes. Changes to children (text, colors, position, nested content) invalidate the cache, so cached frames stay current, including a Grid’s layer edits and entities added or removed inside it. Before 0.3.0 (#368, #427, #446), such changes could be frozen out of a cached frame.