Callback Naming Standardization #139

New issue

Closed

opened 2025-11-27 18:34:42 +00:00 by john · 0 comments

john commented

2025-11-27 18:34:42 +00:00

Owner

Rename callback properties to consistent on_* pattern across all event types.

Context

Current API uses inconsistent naming:

drawable.click - callback property
mcrfpy.keypressScene() - function to set scene keyboard handler

As we add more event types (enter, exit, move, cell events), we need consistent naming. This is a breaking change - do it now before the API stabilizes further.

Definition of Done

Rename click property to on_click on all UIDrawables
Add on_key property to UIDrawables (optional per-widget keyboard handler)
Scene-level keyboard: scene.on_key or keep keypressScene() but document deprecation path
Update all tests to use new names
Update all demo scripts
Update documentation

New Callback Pattern

# Mouse events
drawable.on_click = lambda x, y: ...
drawable.on_enter = lambda: ...      # No args needed
drawable.on_exit = lambda: ...       # No args needed
drawable.on_move = lambda x, y: ...  # Screen coords

# Keyboard events  
drawable.on_key = lambda key, state: ...

# Grid-specific
grid.on_cell_click = lambda cell_x, cell_y: ...
grid.on_cell_enter = lambda cell_x, cell_y: ...
grid.on_cell_exit = lambda cell_x, cell_y: ...

# Animation
animation.on_complete = lambda: ...  # See #126

Callback Validation

When a callback is assigned, McRogueFace should inspect the callable's signature:

Use inspect.signature() or callable.__code__.co_argcount
If arg count doesn't match expected, emit warnings.warn()
Accept *args, **kwargs signatures as compatible with anything
Warning appears at assignment time, helping developers find the issue near the code that set it

frame.on_click = lambda: print("clicked")  
# Warning: on_click callback expects (x, y) arguments, got 0. 
# Callback may fail when invoked.

Migration

This is a breaking change. Options:

Hard break - just rename, fix what breaks
Soft deprecation - support both names temporarily, warn on old name

Recommend option 1 given current project maturity level.

Dependencies

None (can be done early)

Part of: #126 (Consistent Python API)
Affects: All drawable types

Rename callback properties to consistent `on_*` pattern across all event types. ## Context Current API uses inconsistent naming: - `drawable.click` - callback property - `mcrfpy.keypressScene()` - function to set scene keyboard handler As we add more event types (enter, exit, move, cell events), we need consistent naming. This is a breaking change - do it now before the API stabilizes further. ## Definition of Done - [ ] Rename `click` property to `on_click` on all UIDrawables - [ ] Add `on_key` property to UIDrawables (optional per-widget keyboard handler) - [ ] Scene-level keyboard: `scene.on_key` or keep `keypressScene()` but document deprecation path - [ ] Update all tests to use new names - [ ] Update all demo scripts - [ ] Update documentation ## New Callback Pattern ```python # Mouse events drawable.on_click = lambda x, y: ... drawable.on_enter = lambda: ... # No args needed drawable.on_exit = lambda: ... # No args needed drawable.on_move = lambda x, y: ... # Screen coords # Keyboard events drawable.on_key = lambda key, state: ... # Grid-specific grid.on_cell_click = lambda cell_x, cell_y: ... grid.on_cell_enter = lambda cell_x, cell_y: ... grid.on_cell_exit = lambda cell_x, cell_y: ... # Animation animation.on_complete = lambda: ... # See #126 ``` ## Callback Validation When a callback is assigned, McRogueFace should inspect the callable's signature: - Use `inspect.signature()` or `callable.__code__.co_argcount` - If arg count doesn't match expected, emit `warnings.warn()` - Accept `*args, **kwargs` signatures as compatible with anything - Warning appears at assignment time, helping developers find the issue near the code that set it ```python frame.on_click = lambda: print("clicked") # Warning: on_click callback expects (x, y) arguments, got 0. # Callback may fail when invoked. ``` ## Migration This is a breaking change. Options: 1. Hard break - just rename, fix what breaks 2. Soft deprecation - support both names temporarily, warn on old name Recommend option 1 given current project maturity level. ## Dependencies - None (can be done early) ## Related Issues - Part of: #126 (Consistent Python API) - Affects: All drawable types