Where does a click on a template instance actually land?
Follow the click. The client hit-tests the pointer against every component stacked at that screen point, from the top down. The event goes to the topmost, deepest component that registers for mouse events, not to the object you attached the script to. A template instance is a container. Its mouseClicked handler runs only when nothing stacked above it on the window, and nothing nested inside it, claims the event first.
A menu button built as a template (a label plus lines and rectangles) is a stack of several components. If one of them sits above the label, or carries its own mouse behaviour, it receives the click. The instance-level script never sees it. You get no error because nothing failed. The event was delivered to a component with no script attached.
The same mechanism explains why rebuilding a template with identical elements can suddenly work. The new copy was drawn in a different order, or without a stray handler on an inner element. The table lists every hop the click passes through and what can stop it there.
| Hop | What to inspect | How it fails |
|---|---|---|
| Runtime mode | Designer design mode vs. preview mode or launched client | Event scripts do not execute while editing |
| Window stack | Components on the main window drawn above the instance | An overlay absorbs the click before the instance |
| Template stack | Shapes and lines drawn above the label inside the template | An inner graphic becomes the event target |
| Inner listeners | Event scripts, tooltips, or built-in mouse behaviour on child components | The child consumes the event and the parent handler never runs |
| Instance handler | Scripting dialog: Navigation builder vs. Script Editor | The action is empty, or a different action type than expected is selected |
Check 1: Does the handler run at all?
Isolate the script from the navigation action before you debug the navigation. Right-click the instance, open Scripting, select mouseClicked, and replace the action with a single print in the Script Editor:
print("menu instance clicked")Run it in preview mode or in a launched client, then watch the output console while you click the centre of the label.
| Console reading | Meaning | Next check |
|---|---|---|
| Line prints once per click | Event path is clear and the handler runs | The fault is in the navigation action or the target window name |
| Nothing prints, and you were in design mode | Scripts do not fire while editing | Switch to preview mode and repeat |
| Nothing prints in preview or client | Something upstream consumes the event | Check 2 |
Configure the action in one place only. The Navigation builder and the Script Editor are alternative ways to define the same event action. If you configure one and test the other, you are testing an action that is not active.
Check 2: Is something on the window covering the instance?
Layer one first, and on a window that means the stacking order. In the window's component tree, anything listed as drawn after the instance and overlapping its bounds sits above it. Common culprits are decorative rectangles behind the menu that were later moved forward, a transparent container, or a copied instance left stacked on top of another.
- Select the instance on the window and choose Bring to Front.
- Repeat the preview click test from Check 1.
- If the line now prints, the overlay was the blocker. Keep the instance in front, or send the decorative element to back.
- If nothing prints yet, the blocker is inside the template. Go to Check 3.
Check 3: Which inner element takes the click?
Probe each element directly. With the print still in place, click in preview on these points and note which clicks print:
| Click point | Prints | Diagnosis |
|---|---|---|
| Bare margin of the instance, no graphics | Yes | The container receives events; an inner component intercepts elsewhere |
| Bare margin | No | Go back to Check 2; the window stack or the mode is still wrong |
| On the label text | No | The label, or a shape drawn over it, owns the event |
| On a line or rectangle | No | That graphic sits above the label, or carries mouse behaviour |
Open the template and inspect the elements that failed:
- Z-order: shapes drawn after the label cover it. Reorder them so decorative graphics sit behind the label, or use Bring to Front on the label.
- Event scripts on children: an inner component that has any mouse event script registers a listener. It then keeps the click even when the script body is empty or left over from an earlier edit.
- Tooltips: a tooltip on a child component also registers mouse handling on that child.
- Interactive component types: buttons, input fields, and similar controls consume clicks by design. Do not use them as decoration inside a template that should handle clicks at the instance level.
Use the rebuild test to settle ambiguous cases. A fresh template with the same graphics, no child scripts, no tooltips, and the label drawn last will pass the instance click test. If a rebuilt copy works and the original does not, diff the two in the component tree for order and per-child scripting.
Which fix pattern should you keep?
| Pattern | Where the script lives | Trade-off |
|---|---|---|
| Instance-level script |
mouseClicked on each instance |
Flexible per instance. The template interior must stay free of listeners, and every future edit can reintroduce the fault. |
| Parameterised template |
mouseClicked on the inner label, target window passed as a string template parameter |
Immune to interior layering, and one script to maintain. You must set the parameter on each instance. |
For a menu where every button performs the same kind of action, the parameterised template is the more durable build. Keep instance-level scripts for cases where instances genuinely do different things.
Procedure for the instance-level approach:
- Open the template and delete all event scripts and tooltips from inner components.
- Order the inner components so decorative shapes sit behind the label, and do not use interactive components as graphics.
- Save the template. Then, on the main window, select each instance and choose Bring to Front if anything overlaps it.
- On each instance, open Scripting >
mouseClicked. Configure the window swap in either the Navigation builder or the Script Editor, not both.
How do you verify the fix holds?
- Keep the print statement, enter preview mode, and click the centre, each edge, the label text, and every line and rectangle of one instance. The console must print exactly once per click at every point.
- Duplicate the instance on the window and give the copy a different print string. Clicking each copy must print only its own string, which proves each instance runs its own handler.
- Replace the print with the navigation action and confirm the target window swaps in from every click point tested in step 1.
- Save, launch a runtime client, and repeat the full click sweep there. Only a clean sweep in the launched client closes the fault, not a sweep in designer preview.
FAQ
Why does my template instance mouseClicked script not fire with no error?
The click was delivered to another component: a shape drawn above the label, a child with its own event script or tooltip, or an overlay on the window. Put a print in mouseClicked, test in preview mode, and click the bare edge of the instance versus the label to find the interceptor.
Why does a rebuilt template work when the original with the same elements does not?
The rebuild changed the stacking order or dropped a stray script or tooltip on an inner component. Compare the component tree order and the per-child scripting of both templates to find the difference.
Why does Bring to Front fix a template button that ignores clicks?
Hit-testing delivers the event to the topmost component under the pointer. Bringing the instance, or the label inside the template, to the front puts it above the decorative shapes that were catching the click.
How do I pass the target window to a template menu button?
Add a string template parameter holding the window name and put the mouseClicked script on the inner label, reading that parameter. Each instance then sets only its parameter value, and interior layering can no longer block the instance.