GridView changed 0.2.8-dev

Grid(grid_size=None, pos=None, size=None, texture=None, **kwargs)

A grid-based UI element for tile-based rendering and entity management. Creates and owns grid data (cells, entities, layers) with an integrated rendering view (camera, zoom, perspective).

Can also be constructed as a view of existing grid data: Grid(grid=existing_grid, pos=…, size=…)

Args: grid_size (tuple): Grid dimensions as (grid_w, grid_h). Default: (2, 2) pos (tuple): Position as (x, y). Default: (0, 0) size (tuple): Size as (w, h). Default: the whole map at 1:1 (grid_size x cell_size), following the cell size if it changes. texture (Texture): Tile texture atlas; its sprite size is the cell size. Default: None – assigned mcrfpy.default_texture (with a TextureWarning) when the grid is first drawn.

Keyword Args: grid (Grid): Existing Grid to view (creates view of shared data). fill_color (Color): Background fill color. on_click (callable): Click event handler. center_x, center_y (float): Camera center coordinates. zoom (float): Zoom level. Default: 1.0 visible (bool): Visibility. Default: True opacity (float): Opacity (0.0-1.0). Default: 1.0 z_index (int): Rendering order. Default: 0 name (str): Element name. layers (list): List of ColorLayer/TileLayer objects.

Properties

Property Description
align Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None to disable alignment and use manual positioning.
bounds Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
camera_rotation Rotation of grid contents around camera center in degrees (float).
center Camera center point in pixel coordinates (Vector).
center_x Camera center X-coordinate in pixel space (float).
center_y Camera center Y-coordinate in pixel space (float).
children added 0.2.8-dev  
UICollection of UIDrawable children such as speech bubbles, effects, and range indicators anchored to grid content (UICollection, read-only).  
fill_color Background fill color (Color). Drawn behind all tiles and entities.
global_bounds Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
global_position Global screen position (read-only). Calculates absolute position by walking up the parent chain.
grid_data The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
h Visible widget height (float).
horiz_margin Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
hovered Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
hovered_cell added 0.2.8-dev  
Currently hovered cell as (x, y) tuple, or None if not hovering (tuple | None, read-only).  
margin General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueError).
name Name for finding elements (str).
on_cell_click added 0.2.8-dev  
Callback when a grid cell is clicked (Callable | None). Called with (cell_pos: Vector, button: MouseButton, action: InputState).  
on_cell_enter added 0.2.8-dev  
Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector).  
on_cell_exit added 0.2.8-dev  
Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector).  
on_click Callable executed when object is clicked (Callable | None).
on_enter Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element’s bounds.
on_exit Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element’s bounds.
on_move Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
opacity Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
origin Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
parent Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
perspective added 0.2.8-dev  
Entity whose perspective_map drives fog-of-war rendering in this view (Entity | None). Setting an entity enables perspective mode; setting None disables it. Cells the entity has never seen are drawn black, discovered-but-not-visible cells dimmed.  
perspective_enabled added 0.2.8-dev  
Whether this view renders the perspective/FOV overlay (bool). Set automatically when assigning perspective; set False to show the whole map without clearing the entity.  
pos Position of the grid as Vector (Vector).
rotate_with_camera changed 0.2.8-dev  
Whether to rotate visually with parent Grid’s camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of a Grid; ignored for other parents.  
rotation Rotation angle in degrees (clockwise around origin). Animatable property.
shader Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
size added 0.2.8-dev  
Size of the grid widget in pixels as (w, h) (Vector). This is the viewport, not the map: the map’s dimensions are grid_size.  
texture changed 0.2.8-dev  
The GridData’s tile atlas (Texture | None); setting it sets the data’s. Layers and entities with no texture of their own draw with it.  
uniforms Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms[‘name’] = value. Supports float, vec2/3/4 tuples, PropertyBinding, and CallableBinding.
vert_margin Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
visible Whether the object is visible (bool). Invisible objects are not rendered or clickable.
w Visible widget width (float).
x Top-left corner X-coordinate (float).
y Top-left corner Y-coordinate (float).
z_index Z-order for rendering (int). Lower values are rendered first.
zoom Zoom level for rendering (float). Values greater than 1.0 magnify; less than 1.0 shrink.

Methods

animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation changed 0.3.4-dev

animate(property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode=’replace’) -> Animation

Create and start an animation on this drawable’s property.

Args: property: Name of the attribute to animate (e.g., ‘x’, ‘pos’, ‘fill_color’, ‘opacity’), or one channel of a Color attribute (‘fill_color.r’) target: Target value, of the attribute’s type: a number, a Vector or (x, y), a Color, (r, g, b[, a]) or a color string, an int (or list of ints to step through), or a str duration: Animation duration in seconds easing: Easing function: Easing enum value, string name, or None for linear delta: If True, target is relative to current value; if False, target is absolute loop: If True, animation repeats from start when it reaches the end (default False) callback: Optional callable invoked when animation completes (not called for looping animations) conflict_mode: ‘replace’ (default), ‘queue’, or ‘error’ if property already animating

Returns: Animation object for monitoring progress

Raises: ValueError: If the name is not an animatable attribute of this drawable

Raises: TypeError: If the target is not of the attribute’s type

Note: This is a convenience method that creates an Animation, starts it, and adds it to the AnimationManager.

center_camera(pos: tuple = None) -> None added 0.2.8-dev

center_camera(pos: tuple = None) -> None

Point this view’s camera at a tile, or at the middle of the map when called with no argument.

Args: pos: (tile_x, tile_y) to center on. Offset by 0.5 to aim at a tile’s middle rather than its top-left corner.

Note: The camera belongs to the VIEW, not the map: two views of one GridData pan independently.

move(dx, dy) or (delta) -> None

move(dx, dy) or (delta) -> None

Move the element by a relative offset.

Args: dx: Horizontal offset in pixels (or use delta) dy: Vertical offset in pixels (or use delta) delta: Offset as tuple, list, or Vector: (dx, dy)

Note: Accepts move(dx, dy), move((dx, dy)), move(Vector), or move(pos=(dx, dy)).

realign() -> None

realign() -> None

Reapply alignment relative to parent, useful for responsive layouts.

Note: Call this to recalculate position after parent changes size. For elements with align=None, this has no effect.

resize(width, height) or (size) -> None

resize(width, height) or (size) -> None

Resize the element to new dimensions.

Args: width: New width in pixels (or use size) height: New height in pixels (or use size) size: Size as tuple, list, or Vector: (width, height)

Note: Accepts resize(w, h), resize((w, h)), resize(Vector), or resize(pos=(w, h)).