Object References

Object References

Typed widget pointers for behavior code. A reference gives a widget — or a whole window — a stable Python name that handlers can reach without scraping the widget tree.

Two scopes

Scope	What it points at	Where it lives
Local	An inner widget (Button, Entry, Frame…)	The owning form
Global	A whole Window or Dialog	The project

The two share one UUID pool so renames are safe — bindings reference the UUID, the user-facing name is just a label.

Scope is enforced by target type. A Window/Dialog can only be a global reference; an inner widget can only be a local reference. The Properties panel toggle picks the right scope for you.

Open the Object References tab

F11 opens the Data window. Click the Object References tab (third column).

The tab shows every reference in the project — local refs grouped under their owning form, plus globals (Window/Dialog targets).

Declare a reference

Per-widget (local)

Select an inner widget. In the Properties Panel, flip the Object Reference toggle on. CTkMaker auto-suggests a name from the widget's user-facing name (or <type>_ref if the name isn't a valid identifier); collisions get a _2 / _3 suffix.

Window/Dialog (global)

Right-click the empty canvas → Window/Dialog Properties. In the Properties panel, flip the Window-Global Reference toggle on. The whole form becomes reachable from any other form's Event Handlers.

Use a reference in code

The exporter wires every reference into the behavior class right after _build_ui() returns and before setup() is called. Inside the behavior class, just use self.<ref_name>:

class LoginPage:
    def setup(self, window):
        # self.submit_button is already wired — safe to use here
        self.submit_button.configure(state="disabled")

    def on_submit(self):
        self.submit_button.configure(state="normal")

Globals resolve to the target class, not an instance — opening the window means calling the class:

class LoginPage:
    def setup(self, window):
        self.window = window

    def on_open_settings(self):
        self.settings_dialog(self.window)   # instantiate the Toplevel

Rename / delete

The Object References tab supports rename and delete. Rename the user-facing name freely — the UUID is the identity, so existing bindings keep working. Generated code regenerates against the new name on export.

Unbound slots

A reference declared by hand (added in the Object References tab without picking a target) has an empty target_id. The exporter silently skips it, so the generated .py stays runnable while you finish wiring it up.

Legacy migration

Pre-1.11 projects with the older "behavior fields" data are migrated automatically on open — no manual step required.

---

See also — Variables · Event Handlers · Properties Panel · Window Properties