john commented

Owner

BASE TYPES:
---
• FONT        - sf::Font
• TEXTURE     - sf::Texture
• COLOR       - sf::Color
• VECTOR      - sf::Vector2i, sf::Vector2f
• CALLABLE    - <function>
• SOUND       - ??? handled oddly, text filenames only
• SCENE       - not sf:: (not representative of SFML object/concept)
• WINDOW      - nearly sf::
 (APIs suck for Scene and Window)


DERIVED TYPES:
---
• Timer
  └─ CALLABLE (tick callback)

• Animation
  └─ CALLABLE (done callback) *not implemented yet, but very important

• UIDrawable
  ├─ CALLABLE (click)
  └─ VECTOR (position)

• Frame
  ├─ VECTOR (size)
  └─ COLOR (outline, fill)

• Caption
  ├─ FONT
  └─ COLOR (outline, fill)

• Sprite
  ├─ TEXTURE
  └─ VECTOR (scale)

• Grid
  ├─ TEXTURE
  ├─ VECTOR (size, grid_size())
  └─ COLOR (fill) *other colors overlooked: discovered but not in FOV overlay

• Entity
  ├─ VECTOR (grid_pos())
  └─ ...sprite stuff

Extension of #20 - use mcrfpy classes:

in __init__ (see #110)
without inconvenience compared to the tuple-version of any given object (see #109)

This is the "leader issue" for a broader class of pain-in-the-ass deficiencies with the way C++ items are exposed and the way Python has to present them.

Acceptable shorthand for Python

We have these vectors across all classes:

position -> pos
- 'x' and 'y' are shorthand for pos.x and pos.y
size -> size
- 'w' and 'h' are shorthand for size.x and size.y
grid_pos and grid_size
- 'grid_x', 'grid_y', 'grid_w', and 'grid_h' match the pattern above

Similarly, we have fill and outline colors

There are a lot of other ints and floats these objects expose - they should be enumerated and made into optional __init__ keyword-only args

Mandatory args, positional args, and rules for `mcrfpy` Python objects during `init`

no args are mandatory - Caption(), Sprite(), Grid() and Frame() must result in valid, safe objects
Each object has a field or two they always need:

Sprite - Texture, index
Grid - grid_size
Entity - same as Sprite
Frame - size
Caption - font, text

The correct order for position args is [pos, size, grid_pos, grid_size vectors], [texture/font objects], [text]

Other optional args

keyword-only.

parent - see #122
name - see #39, #40, #41
children - see #38

Wiki References:

Blocked by: Need to document current patterns before automating generation

``` BASE TYPES: --- • FONT - sf::Font • TEXTURE - sf::Texture • COLOR - sf::Color • VECTOR - sf::Vector2i, sf::Vector2f • CALLABLE - <function> • SOUND - ??? handled oddly, text filenames only • SCENE - not sf:: (not representative of SFML object/concept) • WINDOW - nearly sf:: (APIs suck for Scene and Window) DERIVED TYPES: --- • Timer └─ CALLABLE (tick callback) • Animation └─ CALLABLE (done callback) *not implemented yet, but very important • UIDrawable ├─ CALLABLE (click) └─ VECTOR (position) • Frame ├─ VECTOR (size) └─ COLOR (outline, fill) • Caption ├─ FONT └─ COLOR (outline, fill) • Sprite ├─ TEXTURE └─ VECTOR (scale) • Grid ├─ TEXTURE ├─ VECTOR (size, grid_size()) └─ COLOR (fill) *other colors overlooked: discovered but not in FOV overlay • Entity ├─ VECTOR (grid_pos()) └─ ...sprite stuff ``` Extension of #20 - use mcrfpy classes: * in `__init__` (see #110) * without inconvenience compared to the tuple-version of any given object (see #109) This is the "leader issue" for a broader class of pain-in-the-ass deficiencies with the way C++ items are exposed and the way Python has to present them. # Acceptable shorthand for Python We have these vectors across all classes: * `position` -> `pos` - 'x' and 'y' are shorthand for `pos.x` and `pos.y` * `size` -> `size` - 'w' and 'h' are shorthand for `size.x` and `size.y` * `grid_pos` and `grid_size` - 'grid_x', 'grid_y', 'grid_w', and 'grid_h' match the pattern above Similarly, we have `fill` and `outline` colors There are a lot of other ints and floats these objects expose - they should be enumerated and made into optional `__init__` keyword-only args # Mandatory args, positional args, and rules for `mcrfpy` Python objects during `__init__` * no args are mandatory - `Caption()`, `Sprite()`, `Grid()` and `Frame()` must result in valid, safe objects * Each object has a field or two they always need: - Sprite - Texture, index - Grid - grid_size - Entity - same as Sprite - Frame - size - Caption - font, text * The correct order for position args is `[pos, size, grid_pos, grid_size vectors], [texture/font objects], [text]` # Other optional args keyword-only. * parent - see #122 * name - see #39, #40, #41 * children - see #38 **Wiki References:** - [Python Binding System](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Python-Binding-System) - [Adding Python Bindings](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Adding-Python-Bindings) - [UI Component Hierarchy](https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/UI-Component-Hierarchy) **Blocked by:** Need to document current patterns before automating generation

john added the

Major Feature

label

2025-07-12 19:58:59 +00:00

john referenced this issue from a commit

2025-07-16 01:42:02 +00:00

Squashed commit of the following: [alpha_presentable]

john added the

Refactoring & Cleanup

system:input

workflow:blocked

priority:tier1-active

system:python-binding

workflow:needs-documentation

labels

2025-10-26 00:44:40 +00:00

john added this to the Cursor, Grid, and Callback project

2025-11-27 13:25:48 +00:00

john referenced this issue

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

Callback Naming Standardization #139

john commented

2025-12-28 19:31:41 +00:00

Author

Owner

Issue #126 Completed

This issue has been addressed through cumulative work over time:

Original Goals - All Met ✅

Goal	Status
No mandatory constructor args	✅ All types constructable with `ClassName()`
Shorthand properties (`x`, `y`, `w`, `h`, `pos`, `size`)	✅ Implemented
`name` field on UIDrawables (#39)	✅ Closed
`children` arg on Frame (#38)	✅ Closed
Parent-Child system (#122)	✅ Closed
Callback properties use `on_*` pattern (#139)	✅ All use `on_click`, `on_enter`, `on_exit`, `on_move`
Grid cell events	✅ `on_cell_click`, `on_cell_enter`, `on_cell_exit`

Final Change: Constructor kwarg consistency

Commit c9c7375 renamed the constructor keyword argument from click to on_click for all UIDrawable types:

Frame, Caption, Sprite, Grid (core types)
Line, Circle, Arc (newer drawing primitives)

This is a breaking change:

# Before
frame = Frame(pos=(0,0), size=(100,100), click=handler)

# After  
frame = Frame(pos=(0,0), size=(100,100), on_click=handler)

The property was already named on_click - this makes the constructor kwarg match.

Note on Type Stubs

The stubs/mcrfpy.pyi file is manually maintained and currently missing the newer types (Line, Circle, Arc). This is a separate maintenance task for the stub generator script.

## Issue #126 Completed This issue has been addressed through cumulative work over time: ### Original Goals - All Met ✅ | Goal | Status | |------|--------| | No mandatory constructor args | ✅ All types constructable with `ClassName()` | | Shorthand properties (`x`, `y`, `w`, `h`, `pos`, `size`) | ✅ Implemented | | `name` field on UIDrawables (#39) | ✅ Closed | | `children` arg on Frame (#38) | ✅ Closed | | Parent-Child system (#122) | ✅ Closed | | Callback properties use `on_*` pattern (#139) | ✅ All use `on_click`, `on_enter`, `on_exit`, `on_move` | | Grid cell events | ✅ `on_cell_click`, `on_cell_enter`, `on_cell_exit` | ### Final Change: Constructor kwarg consistency Commit `c9c7375` renamed the constructor keyword argument from `click` to `on_click` for all UIDrawable types: - Frame, Caption, Sprite, Grid (core types) - Line, Circle, Arc (newer drawing primitives) **This is a breaking change:** ```python # Before frame = Frame(pos=(0,0), size=(100,100), click=handler) # After frame = Frame(pos=(0,0), size=(100,100), on_click=handler) ``` The property was already named `on_click` - this makes the constructor kwarg match. ### Note on Type Stubs The `stubs/mcrfpy.pyi` file is manually maintained and currently missing the newer types (Line, Circle, Arc). This is a separate maintenance task for the stub generator script.

john closed this issue

2025-12-28 19:31:42 +00:00

john referenced this issue from a commit

2025-12-28 19:38:04 +00:00

refactor: Rename click kwarg to on_click for API consistency (closes #126)

john referenced this issue from a commit

2025-12-28 19:38:04 +00:00

docs: Add Line/Circle/Arc to stubs and fix click→on_click

john referenced this issue

2026-01-03 22:58:06 +00:00

Timer objects: remove setTimer, delTimer #172

john referenced this issue