Window Framework for UI Toolkit v2.0.x
Visual Scripting Integration

Drive supported window operations from graphs, query existing window state, and respond to framework notifications without replacing your application's windowing setup.

WindowFramework supplies window, theme, tooltip and context-menu units, plus an optional Window Scripting Bridge for GameObject-targeted Custom Events. The graph layer works with your existing controller and UI Toolkit content; it does not create a second UI system.

Preview feature:** this integration is experimental/preview. Node signatures and APIs may evolve. The guide describes the current supplied implementation, not a promise that every framework API already has a custom node.

Required Setup

  • Use the supported Unity environment in Asset Requirements and Unity Visual Scripting 1.8.0 or later.
  • Complete Installation and Setup so the controller, UI root, theme data and intended windows exist.
  • Use a listening ScriptMachine/graph for graph events. A bridge alone does not create or assign a graph.
  • Run window operations after the controller/root is ready and after your application's window-creation path has supplied the target.

The optional assembly detects the installed package through its existing version configuration. Do not manually add compatibility symbols or edit package source to force missing nodes to compile.

In the node picker, look under Window Framework/Windows, Window Framework/Theme, Window Framework/Tooltips, and Window Framework/Context Menu. Native event units are under Events/Window Framework.

If newly imported units are absent, check compilation and the installed package first, then use Edit > Project Settings > Visual Scripting > Node Library > Regenerate Nodes as appropriate for the project's node library. Graph state and runtime configuration are separate from node discovery.

1. Inspect the Existing Demo Material

The supplied files are:

  • Assets/GarageWareGames/WIndowFramework/Demo/VisualScripting/WindowFramework_SampleGraph.asset.
  • Assets/GarageWareGames/WIndowFramework/Demo/VisualScripting/VisualScriptingDemoRunner.cs.
  • The existing Visual Scripting Demo page/content within the Demo.

    The supplied sample graph is an unwired starter palette, not an automatically runnable sequence.** It currently contains Start, Update, Show Window, Toggle Window, Set Theme by Name, Show Context Menu, and Get Active Theme Info nodes. Its name inputs are blank and it has no serialized control connections.

Use it to inspect the existing units, then wire the intended event/control flow and provide real targets/names in your own application graph. Do not assume that assigning this asset alone creates windows or that every Update should toggle a window.

VisualScriptingDemoRunner exposes bridge calls for the existing Demo controls and can obtain/add its bridge at runtime. It does not load or wire the sample graph. Its custom-event helper targets the runner's own GameObject, which can differ from a bridge's separately configured Target Graph Object.

2. Use the Right Window Identity

Most window commands accept an existing Target Window reference. When supplied, that reference takes priority over the optional Window Name fallback.

Window Name lookup is an exact, case-sensitive match against the registered window's Title or VisualElement.name. It is not a GameObject name, WindowId, ParentObjectId, saved record key, or player-theme ID. Duplicate titles/names can resolve the first matching window; retain explicit references when your application needs to distinguish instances.

Show and Hide operate on a retained instance. They do not reconstruct a window that was never created or was closed/unparented. Focus Window is a separate activation request; Show does not automatically mean focused.

Explanatory wiring with the existing On Window Opened and Focus Window units. No new graph or scene example is created by this diagram.

An opened-window event provides a usable instance reference for subsequent commands, but its notification does not certify first-layout completion. See 2. Create Your First Window and 8. Show, Hide, Activate, and Close for creation/opening and lifecycle behavior.

3. Control Flow Is Not Completion

Command nodes normally use Enter and Exit. Exit means the synchronous request returned; it is not a guarantee that layout, a fade, a selection save, an asynchronous import, or an application operation completed.

Read command-cached outputs after executing the node. Value-only query outputs evaluate current state when read. A missing target/controller often results in a no-op and normal Exit rather than a success signal.

Do not use a cached Window or Success value from an earlier invocation as proof that the current request succeeded. Check the target/state that matters to your application, and wait for actual layout when using resolved geometry.

4. Window Units

All units in this section are under Window Framework/Windows.

Show Window

  • Flow: Enter → Exit.
  • Inputs: Target Window (WindowFrame, default null); Window Name (string, default empty).
  • Output: Window (cached last resolved WindowFrame, or null after an unresolved request).

Calls Show on the existing target. It does not create a frame or automatically activate it through the controller.

Hide Window

  • Flow: Enter → Exit.
  • Inputs: Target Window, Window Name, using the same reference/name priority.
  • Output: Window, cached after execution.

Calls Hide while retaining the instance. It does not dispose application subscriptions or save document content.

Toggle Window

  • Flow: Enter → Exit.
  • Inputs: Target Window, Window Name.
  • Output: Is Visible, the cached result of the latest toggle request; false when unresolved.

The decision checks the target's visible flag and inline DisplayStyle.Flex. This output is not an independent live visibility query or proof that the element is on-screen/unclipped.

Close Window

  • Flow: Enter → Exit.
  • Inputs: Target Window, Window Name, Force All (bool, default false).
  • No success output.

Requests CloseWindow on that resolved instance. Normal closure respects its AllowClose/Locked policy. Force All bypasses ordinary closure restrictions for the one target, not every window in the application. It does not authorize a business action or discard unsaved document data for you.

Focus Window

  • Flow: Enter → Exit.
  • Input: Target Window (WindowFrame, default null).
  • No Window Name fallback or success output.

Requests controller activation when both the reference and controller exist. It is not a general search for an arbitrary focused UI control.

Find Window

  • Input: Window Name (string, default empty).
  • Outputs: Window, Found.
  • Value-only unit; no Enter/Exit.

Returns the first registered window matching Title or VisualElement.name. Hidden retained windows can still be registered; closed/unparented windows are not recreated. Found means an instance resolved, not that it is visible or fully initialized.

Get Window State

  • Inputs: Target Window, Window Name.
  • Outputs: Is Visible, Position, Size, Title, Found.
  • Value-only unit.

Position reads resolved left/top and Size reads resolved width/height. An unresolved target yields zero vectors, false flags and empty title. An existing target still needs real layout for meaningful geometry; attaching an element does not synchronously calculate every bound.

Is Visible reads the visible flag, not a complete display/clipping/hit-test result. See 4. Choose Size and Starting Position when controlling initial placement or size.

Get Active Window

  • Outputs: Active Window, Has Active Window.
  • Value-only unit.

Queries the controller's registered windows for the first frame marked Active. It does not identify arbitrary focused elements outside the framework.

Open Settings Window

  • Flow: Enter → Exit.
  • No value inputs/outputs.

Requests the supplied settings window through the existing controller. Without a controller it is a no-op; Exit is not a window-open success certificate. Theme setup is described in Theme Studio and Manager and Player Themes.

5. Theme Units

These units are under Window Framework/Theme and operate on the configured built-in ThemeData.Themes list. They do not search imported player themes by stable ID.

Set Theme by Name

  • Flow: Enter → Exit.
  • Input: Theme Name (string, default empty).
  • Output: Success, cached after the command.

Matches a built-in display name case-insensitively and requests its list index. The first matching name wins. Success indicates a match/assignment request, not proof of downstream appearance, persistence or portable-theme application.

Set Theme by Index

  • Flow: Enter → Exit.
  • Input: Theme Index (int, default 0).
  • Output: Success, cached true for an in-range assignment request.

Use a zero-based built-in collection index. It is not an imported player-theme ID, and an index can change when the collection changes. Validate your configuration rather than assuming index 0 is the application's default.

Set Default Theme

  • Flow: Enter → Exit.
  • No value inputs/outputs.

Uses the existing configured-default selection path. It does not fabricate a default, delete player folders, reset window geometry, or change the controller's memory policy.

Get Active Theme Info

  • Outputs: Theme Name, Theme Index, Is Default, Total Themes.
  • Value-only unit.

Reports the active built-in/baseline entry and built-in collection count, excluding imported player entries. Missing configuration produces empty name, index zero, false default and zero count as applicable; zero is not itself proof of a valid theme.

For player selection and identity restoration, use the existing runtime owner described in 10. Integrate With Your Existing UI Owner rather than treating a player ID as Theme Name or Theme Index.

6. Tooltip and Context Menu Units

Hide Tooltip

Category: Window Framework/Tooltips.

  • Flow: Enter → Exit.
  • Input: Immediate (bool, default false).

False requests Close with the normal tooltip behavior; true uses CloseNow. A missing tooltip is a no-op. Exit is not fade completion.

Get Tooltip State

Category: Window Framework/Tooltips.

  • Outputs: Is Open, Target Element.
  • Value-only unit.

Reads the tooltip's current IsOpen flag and borrowed target. The target can exist while a tooltip is pending; a target reference alone does not prove that help is currently displayed.

Show Context Menu

Category: Window Framework/Context Menu.

  • Flow: Enter → Exit for the construction request.
  • Inputs: Screen Position (Vector2, default zero); Title (string, default empty); Items (IList of strings, default null).
  • Later flow output: On Selected.
  • Cached outputs: Selected Label (initially empty), Selected Index (initially -1).

Builds simple label actions using the existing context-menu API. Selecting a row updates its label/index and invokes On Selected later. Read those outputs from the selection branch, not immediately after Enter/Exit; a previous selection can remain cached between requests.

The current renderer uses target-based placement with the controller root as target. Screen Position is passed to that API but is not a guarantee of arbitrary cursor-positioned layout. This simple node does not expose every checked/disabled/separator option of ContextMenuConfig.

Keep the graph owner valid for later menu callbacks and test scene/machine changes during an open menu. Application action validation belongs in your graph/code; a chosen label is not authorization.

Dismiss Context Menu

Category: Window Framework/Context Menu.

  • Flow: Enter → Exit.
  • No value inputs/outputs.

Queries beneath the controller RootElement for the first WindowFrameContextMenu and requests RemoveNow. It is not a global registry of every menu on every panel; a menu mounted outside that subtree is not guaranteed to be found. See 2. Put Item Actions in a Context Menu for the underlying menu workflow and placement/ownership behavior.

7. Native Framework Event Units

These three units are under Events/Window Framework. They use global framework EventBus hooks, not a GameObject-targeted Custom Event. They do not require WindowScriptingBridge.

Native event units and bridge Custom Events have different targets and payloads. Choose the route expected by your graph.

On Window Opened

  • Outputs: event flow, Window (WindowFrame), Title (string).
  • Underlying hook: OnWindowFrameAdded.

Triggered by the window-added/attachment notification. It is not a first-layout, fade or business-operation completion event. Filter the supplied instance/title when only a particular window matters.

On Window Closed

  • Outputs: event flow, Window (WindowFrame), Title (string).
  • Underlying hook: OnWindowFrameRemoved.

Triggered by removal notifications. It is not an automatic save/discard decision for application data. Do not assume hiding, detaching, closing and reconstructing all produce the same lifecycle sequence.

On Theme Changed

  • Outputs: event flow, Theme Index, Theme Name.
  • Underlying hook: OnWindowFrameworkThemeChanged.

Describes the controller's built-in/baseline state during its stylesheet/theme notification. It is not a player-theme stable ID or a signal that every later override/import/save step completed.

The current preview units connect/disconnect shared static relays as graphs start/stop listening. They are not reference-counted independent per-graph relays: stopping one listener can affect another that shares the relay. Coordinate multiple graph lifetimes and test the actual ownership setup instead of assuming unrestricted multi-listener isolation.

8. Use Window Scripting Bridge for Custom Events

If your graph uses ordinary GameObject-targeted Custom Events, configure Window Framework > Visual Scripting > Window Scripting Bridge on its intended owner. This is an optional route, not a replacement controller or an automatically assigned ScriptMachine.

Set Target Graph Object when the receiving ScriptMachine is on another GameObject. Otherwise the bridge sends to its own GameObject. Match event names exactly and configure one argument on the receiving Custom Event:

  • OnWindowOpened: argument 0 is the window title string.
  • OnWindowClosed: argument 0 is the window title string.
  • OnThemeChanged: argument 0 is the built-in/baseline theme name string.

These are default configurable bridge names. An empty configured name suppresses that relay. The title string is not a WindowFrame reference; use Find Window when a name lookup is appropriate, or use the native event unit when you need the actual instance payload.

Public bridge actions are ShowWindow(string), HideWindow(string), ToggleWindow(string), CloseWindow(string), SetActiveTheme(string), and SetDefaultTheme(). Window-name actions use exact Title/element-name lookup. Theme-name actions use case-insensitive built-in name lookup. CloseWindow is normal closure, without the unit's Force All option.

The bridge subscribes while enabled and removes its subscriptions when disabled. Configure its target and graph listening before expecting events; it does not replay missed notifications or scan for every graph in the scene.

Check the Integration in Your Application

  • Confirm package/assembly compilation and node-library availability.
  • Confirm the existing controller/root, graph owner and target windows are ready.
  • Test an explicit Window reference, then the exact name fallback if your design uses it.
  • Read cached outputs after commands and geometry only after real layout.
  • Match native-event versus bridge-event payloads; do not connect a title string as an instance.
  • Wire the supplied starter graph deliberately; blank inputs/unconnected nodes do not implement a sequence.
  • Test later context-menu callbacks and graph/window lifetime changes.
  • Test multiple event listeners and theme/player-baseline behavior within the preview limitations.

Continue to Windows and Layout for window creation and lifecycle, Tooltips, Context Menus, and Modals for the interaction systems, or Troubleshooting for setup/availability problems. The integration exposes supported operations through graphs; it does not require rebuilding the asset's existing Demo or add a custom node for every API.