|
| void | AddOrUpdateWindowData (string dataKey, WindowFrameData windowData) |
| | Updates or adds window configuration data for persistence.
|
| List< StyleSheet > | BuildSheetList () |
| | Returns the configured collection composition plus the optional global stylesheet.
|
| bool | CancelPendingModal (WindowFrame window) |
| | Removes a detached queued request without presenting it.
|
| void | ClearPreferences (bool forceAll=false) |
| | Clears all framework preferences and window memory, resetting everything to defaults.
|
| void | CloseActiveModal () |
| | Closes the displayed modal and advances queued requests. No input bindings are installed.
|
| void | CloseAllModals () |
| | Discards pending requests, closes the displayed modal and releases its presentation.
|
| void | ConfigurePlayerThemeExtensions (GWG.WindowFramework.Theming.PlayerThemeExtensionRegistry extensions) |
| | Supplies compiled purchaser handlers before automatic player-theme initialization.
|
| WindowFrameData | GetWindowData (string dataKey) |
| | Retrieves window configuration data by its unique identifier.
|
| bool | InitializePlayerThemes (string folder, Func< IEnumerable< VisualElement > > scopes, out string error, GWG.WindowFramework.Theming.PlayerThemeExtensionRegistry extensions=null) |
| | Initializes imported player themes using explicit application-owned UI scopes.
|
| void | OpenSettingsWindow () |
| | Opens the built-in settings window for configuring the window framework.
|
| bool | RemoveModalCard (CardElement card) |
| | Application-authorized removal of a specific visible or queued card, with transition.
|
| void | ReopenWindows (float delay=0.1f) |
| | Restores previously opened windows from saved data after a specified delay.
|
| void | ReopenWindowsInternal () |
| | Performs the actual window restoration from saved data.
|
| void | ResetSettings () |
| | Resets all framework settings to their default values while preserving window memory data.
|
| void | SetActiveWindow (WindowFrame newTarget) |
| | Sets the specified window as the active window and deactivates all others.
|
| void | ShowModal (CardElement card, VisualElement initialFocus=null) |
| | Adds a non-window card to the visible modal queue. Its styles own px/% card sizing.
|
| void | ShowModal (WindowFrame window, VisualElement initialFocus=null, bool dismissOnBackdrop=false) |
| | Presents a detached WindowFrame modally in the controller-linked UIDocument.
|
| bool | WasWindowOpen (string dataKey) |
| | Checks whether a window was open when framework data was last saved using its exact canonical dataKey.
|
| bool | WasWindowOpen (string parentObjectId, string windowId) |
| | Checks whether a window was open when framework data was last saved using its parent object ID and window ID. Provided for backwards compatibility with legacy call sites.
|
| bool | WasWindowOpen (WindowFrame window) |
| | Checks whether the specified WindowFrame was open when framework data was last saved.
|
|
| CardElement | ActiveModalCard [get] |
| | Gets the currently active non-window card, or null.
|
| WindowFrame | ActiveModalWindow [get] |
| | Gets the top modal in this controller's windowing document, or null.
|
| int | ActiveThemeIndex [get] |
| | Gets the index of the currently active theme.
|
| List< WindowFrame > | ActiveWindowFrames [get] |
| | Gets a list of all currently active window frames in the framework.
|
| float | ContextMenuFadeDelay [get, set] |
| | Gets/sets context-menu pre-fade delay in seconds; assignments clamp to zero through five.
|
| float | ContextMenuFadeTime [get, set] |
| | Gets/sets context-menu fade duration in seconds; assignments clamp to zero through three.
|
| StyleSheet | CurrentStylesheet [get] |
| | Gets the primary stylesheet for the current theme.
|
| List< StyleSheet > | CurrentThemeStylesheets [get] |
| | Gets the current list of stylesheets based on active theme settings.
|
| bool | DebugTelemetryEnabled [get, set] |
| | Gets or sets whether high-density machine-readable debug telemetry logging is active.
|
| StyleSheet | DefaultStylesheet [get, set] |
| | Gets or sets the default stylesheet used when themes are not enabled or set.
|
| VisualElement | GhostIcon [get, set] |
| | Gets or assigns the experimental drag-visual reference; getter lazily creates/mounts it.
|
| GlobalsLoadOrder | GlobalsLoadOrder [get, set] |
| | Gets or sets the loading Order for global stylesheet relative to theme stylesheets.
|
| StyleSheet | GlobalStylesheet [get, set] |
| | Gets or sets the global stylesheet applied across all themes.
|
| static WindowFrameController | Instance [get, private set] |
| | Gets the singleton instance of the WindowFrameController.
|
| bool | MemoryEnabled [get, set] |
| | Gets or sets the developer-owned controller policy for using window-state memory.
|
| GWG.WindowFramework.Theming.PlayerThemeRuntime | PlayerThemeRuntime [get] |
| | Gets the opt-in player-theme owner after successful initialization.
|
| string | SavedThemeId [get] |
| | Gets the saved stable theme identity awaiting catalog resolution.
|
| float | TooltipFadeDelay [get, set] |
| | Gets/sets tooltip pre-fade delay in seconds using the configured fallback.
|
| float | TooltipFadeTime [get, set] |
| | Gets/sets tooltip fade duration in seconds, not the modal motion millisecond token.
|
| TooltipFadeType | TooltipFadeType [get, set] |
| | Gets/sets the tooltip fade-mode preference; appearance behavior is handled by the tooltip.
|
| bool | TooltipsActive [get, set] |
| | Gets or sets whether tooltips are active and functional.
|
| float | TooltipShowDelay [get, set] |
| | Gets or sets the delay before showing tooltips when hovering over elements.
|
| static VisualElement | UIRoot [get] |
| | Gets the root VisualElement for the window framework's UI hierarchy.
|
| static WindowFrameTooltip | WindowFrameTooltip [get, set] |
| | Gets or sets the static tooltip system instance.
|
The WindowFrameController is the central management component for the Window Framework system. It serves as a singleton that manages window frames, themes, tooltips, context menus, and persistent data.
This component should be attached to a GameObject with a UIDocument component. It automatically handles initialization, event subscriptions, and cleanup operations.
KeyValue Features:
- Singleton pattern for global access
- Theme management and switching
- Window state persistence
- Tooltip system management
- Context menu configuration
- Input handling for UI interactions
The controller persists across scene loads using DontDestroyOnLoad.
var myWindow = new MyCustomWindow();
The WindowFrameController is the central management component for the Window Framework system....
Definition WindowFrameController.cs:77
static void AddElement(VisualElement newElement)
Adds a visual element to the window framework's root element with special handling for WindowFrame in...
Definition WindowFrameController.cs:2876
static void ApplyTooltips(VisualElement root)
Applies tooltip manipulators to UI elements within the specified root element.
Definition WindowFrameController.cs:1582
static WindowFrameController Instance
Gets the singleton instance of the WindowFrameController.
Definition WindowFrameController.cs:299
| void GWG.WindowFramework.WindowFrameController.AddElement |
( |
VisualElement | newElement | ) |
|
|
inlinestatic |
Adds a visual element to the window framework's root element with special handling for WindowFrame instances.
- Parameters
-
| newElement | The VisualElement to add to the framework |
This method inserts into the configured controller root, not an arbitrary UIDocument. WindowFrame deduplication uses VisualElement.name only when the incoming instance disallows multiples. It does not compare ParentObjectId, WindowId or concrete type. A matching registered frame is activated later; the incoming frame is not mounted and its content is not merged.
Other elements and unmatched frames are added to the existing root and receive tooltip application. Requires an initialized root; a missing controller does not create one. Caller owns the supplied content and any subscriptions/resources on an unused duplicate. No return value identifies the selected existing instance; use the application's retained references rather than assuming every constructed frame was accepted.
Supply the window's developer configuration before this call. Mounting an accepted ordinary runtime frame triggers its attachment-stage theme application, then UI Toolkit's first geometry callback, eligible saved-state restoration or existing placement, and the controller-hosted two-frame reveal continuation. AddElement does not call Show, wait for resolved layout or reassign default dimensions. Panel-scoped themes may already be inherited at mounting. Construction's OnWindowFrameAdded notification is separate from attachment.
var statusBar = new VisualElement();
var chatWindow = new ChatWindow { AllowMultipleInstances = true };
var settingsWindow = new SettingsWindow { AllowMultipleInstances = false };
WindowFrameController.AddElement(settingsWindow);
WindowFrameController.AddElement(new SettingsWindow());
| void GWG.WindowFramework.WindowFrameController.AddGhostIcon |
( |
| ) |
|
|
inlineprivate |
[EXPERIMENTAL] Creates and configures the ghost icon for drag operations.
⚠️ EXPERIMENTAL FEATURE: This method sets up a ghost icon element that can be used for drag-and-drop operations between windows, toolbars, or other UI elements.
The ghost icon is initially hidden and positioned absolutely to follow mouse movement during drag operations. It's semi-transparent to provide visual feedback without obscuring the drop target.
Configuration details:
- Size: 50x50 pixels
- Opacity: 50% (0.5f)
- Position: Absolute positioning at (0,0)
- Visibility: Hidden by default
- Background: Transparent
This is not officially supported and the implementation may change.
void StartDragOperation(VisualElement sourceIcon)
{
controller.GhostIcon.style.backgroundImage = sourceIcon.style.backgroundImage;
controller.GhostIcon.style.visibility = Visibility.Visible;
RegisterCallback<MouseMoveEvent>(evt =>
{
controller.GhostIcon.style.left = evt.mousePosition.x;
controller.GhostIcon.style.top = evt.mousePosition.y;
});
}
| void GWG.WindowFramework.WindowFrameController.AddOrUpdateWindowData |
( |
string | dataKey, |
|
|
WindowFrameData | windowData ) |
|
inline |
Updates or adds window configuration data for persistence.
- Parameters
-
| dataKey | Exact canonical key: concrete window type, parent ID and window ID separated by vertical bars. |
| windowData | WindowFrameData object containing window state information |
This method manages the window data dictionary that persists window states across application sessions. The data is only stored if MemoryEnabled is true.
The dataKey should be unique for each window instance and follow the format: [WindowType]_[ParentObjectId]_[WindowId]
The windowData contains information such as:
- Window position and size
- Open/closed state
- Lock status
- Custom window properties
windowId = "Inventory", parentObjectId = "Player_01",
location = new Vector2(100, 200), size = new Vector2(400, 300),
wasOpen = true, locked = false
};
string key = typeof(InventoryWindow).FullName + "|Player_01|Inventory";
controller.AddOrUpdateWindowData(key, windowData);
Represents the serializable data structure for storing and loading window frame configuration and sta...
Definition WindowFrameData.cs:64
Memory-disabled calls are ignored. Stores the supplied record reference under the supplied key without cloning, validating fields or immediately writing disk. Null keys are invalid for the dictionary. Use a stable concrete-type|owner|window key from normal window persistence; arbitrary keys are not automatically repaired or migrated.
| void GWG.WindowFramework.WindowFrameController.ApplyTooltips |
( |
VisualElement | root | ) |
|
|
inlinestatic |
Applies tooltip manipulators to UI elements within the specified root element.
- Parameters
-
| root | The parent VisualElement containing child elements that may need tooltips. |
This method should be called whenever new UI content is instantiated to ensure tooltip functionality is properly attached. It automatically detects elements with tooltip text and adds the necessary manipulators.
The method prevents duplicate manipulators by checking element userData and only operates when tooltips are enabled in the framework.
var newPage = Resources.Load<VisualTreeAsset>("UI/NewPage");
var pageRoot = newPage.CloneTree();
myContainer.Add(pageRoot);
var button = new Button { text = "Click Me", tooltip = "This button does something" };
myContainer.Add(button);
Requires a nonnull root and initialized controller. Uses element.userData as the literal marker "hasTooltipManipulator" and overwrites existing userData when installing a manipulator. Preserve application metadata elsewhere when using this integration. The marker is not a retained manipulator reference; clearing it may allow duplicate installs.
| void GWG.WindowFramework.WindowFrameController.ClearPreferences |
( |
bool | forceAll = false | ) |
|
|
inline |
Clears all framework preferences and window memory, resetting everything to defaults.
- Parameters
-
| forceAll | If true, forces closure of all windows including locked ones. |
Requests CloseWindow for each currently registered frame, replaces the in-memory window record dictionary and calls ResetSettings. With forceAll=false restricted windows can remain. It does not call PlayerPrefs.DeleteAll, delete player-theme folders, or immediately erase every saved framework file. Application confirmation is required before choosing this reset. Subsequent save/lifecycle paths determine durable disk state; not an atomic reset transaction.
controller.ClearPreferences(forceAll: true);
| void GWG.WindowFramework.WindowFrameController.HandleThemeChanged |
( |
int | newThemeIndex, |
|
|
StyleSheet | newStylesheet ) |
|
inlineprivate |
Handles theme change events and applies new stylesheets based on theme configuration.
- Parameters
-
| newThemeIndex | Index of the new theme being applied |
| newStylesheet | Primary stylesheet of the new theme |
This method responds to theme change events by:
- Building the complete stylesheet list for the new theme
- Applying stylesheets based on the ThemeApplyMethod setting:
- ParentPanel: Applies to the controller's panel only
- AllPanels: Applies to all UIDocument panels in the scene
- WindowFramesOnly: Publishes event for individual window handling
- Triggering the OnThemeChanged event for subscribers
- Updating the active window focus state
The method removes only the previously tracked controller references, not arbitrary application-added sheets. Panel scopes install on panel.visualTree and then publish null as the new window-local composition, with the prior tracked list for local cleanup. WindowsFramesOnly publishes the full new list for subscribed windows to install locally. The new composition is recorded after publication, then the existing activation update runs.
AllPanels is stylesheet scope across the available UIDocument panels, not a request to create windows in each document. Ordinary windows attach only to their existing host and may inherit panel sheets installed before their own attachment. Their initial local requests are consumed at attachment before first-layout restoration and reveal. Later theme changes reuse this method and WindowFrame.ApplyControllerTheme; they do not restart opening or reset DefaultWidth/DefaultHeight. Sheet installation is not synchronous layout calculation.
{
Debug.Log($"Theme changed: {newSheets?.Count} new sheets, {oldSheets?.Count} old sheets");
UpdateCustomElementStyles(newSheets);
};
static Action< List< StyleSheet >, List< StyleSheet > > OnThemeChanged
Event triggered when the application theme changes.
Definition WindowFrameController.cs:487
| void GWG.WindowFramework.WindowFrameController.LoadWindowFrameworkData |
( |
| ) |
|
|
inlineprivate |
Loads window framework configuration data from persistent storage.
This method attempts to load saved data from a JSON file in the persistent data path. The loaded data includes:
- Window positions, sizes, and states
- Tooltip configuration (show delay, fade delay, fade type, etc.)
- Context menu settings (fade delay, fade time)
- Memory/persistence preferences
- Active theme index
If the file doesn't exist or loading fails, default values are applied. The method gracefully handles corruption or missing data by falling back to defaults.
void ReloadSettings()
{
controller.LoadWindowFrameworkData();
controller.ResetSettings();
}
| void GWG.WindowFramework.WindowFrameController.ReopenWindows |
( |
float | delay = 0::1f | ) |
|
|
inline |
Restores previously opened windows from saved data after a specified delay.
- Parameters
-
| delay | Delay in seconds before beginning window restoration. Default: 0.1f |
This method should be called at an appropriate point during application startup when you want saved windows to be restored. The delay allows the UI framework and other systems to fully initialize before creating window instances.
Only windows that were open when the application last closed will be restored, and only if MemoryEnabled is true. Window positions, sizes, and other properties are restored from the saved data.
{
}
void OnSceneLoaded()
{
}
IEnumerator RestoreWindowsWhenReady()
{
yield return new WaitUntil(() => UISystemReady());
WindowFrameController.Instance?.ReopenWindows();
}
void ReopenWindows(float delay=0.1f)
Restores previously opened windows from saved data after a specified delay.
Definition WindowFrameController.cs:2084
| void GWG.WindowFramework.WindowFrameController.SaveWindowFrameworkData |
( |
| ) |
|
|
inlineprivate |
Saves current window framework configuration data to persistent storage.
This method serializes the current framework state to JSON format and saves it to the persistent data path. The saved data includes:
- Window records from WindowFrameSettingsData.
- schemaVersion, stable ActiveThemeId and the legacy ActiveThemeIndex view.
- Global snapping/docking/tab preferences, not controller memory policy.
The current writer does not populate tooltip/context-menu timing fields on its WindowFrameworkData object; those live preferences are handled through PlayerPrefs. Do not infer that every field declared by the DTO is written by this method. Writes directly to persistentDataPath/dataFileName and reports write exceptions. Called during controller destruction and successful theme-selection persistence.
void SaveCurrentSettings()
{
controller.TooltipShowDelay = newValue;
}
| void GWG.WindowFramework.WindowFrameController.Start |
( |
| ) |
|
|
inlineprivate |
Starts the existing configured theme session after controller setup.
Awake establishes the singleton, loads framework persistence and obtains the assigned UIDocument root. OnEnable subscribes to theme-data changes and applies an already available current sheet through HandleThemeChanged. Start then initializes the configured theme session; it does not create another window host or reset window geometry. Configured Addressables loading, when enabled, defers that session until its existing hydration path supplies theme data. Window opening remains attachment/first-layout/restoration/reveal work owned by WindowFrame rather than a synchronous operation of this lifecycle method.
| VisualElement GWG.WindowFramework.WindowFrameController._ghostIcon |
|
private |
[EXPERIMENTAL] The ghost icon element used for drag-and-drop operations.
A VisualElement representing a draggable ghost icon, or null if not active.
⚠️ EXPERIMENTAL FEATURE: This is not a supported feature and is provided only as an example of how to implement icon dragging between windows or toolbars.
The ghost icon provides visual feedback during drag operations, showing a semi-transparent representation of the item being dragged. This can be used with custom drag manipulators to create rich drag-and-drop interactions.
Use at your own risk - this API may change or be removed in future versions.
var dragManipulator = new MyIconDragManipulator();
dragManipulator.OnDragStart += (iconData) =>
{
if (controller.GhostIcon != null)
{
controller.GhostIcon.style.backgroundImage = iconData.image;
controller.GhostIcon.style.visibility = Visibility.Visible;
}
};
| string GWG.WindowFramework.WindowFrameController.dataFileName = "WindowFrameData.json" |
|
private |
The filename for storing window framework data in the persistent data folder.
The name of the JSON file where window and framework settings are stored. Default: "WindowFrameData.json"
This file is created in Application.persistentDataPath and contains:
- Window positions and sizes
- Theme preferences
- Tooltip and context menu settings
- Other framework configuration data
Change this value if you need to use a different filename or want to separate data for different game modes or users.
controller.dataFileName = "MainMenuWindowData.json";
controller.dataFileName = $"WindowData_v{Application.version}.json";
Dictionary storing configuration data for each window frame.
A dictionary where keys are window identifiers and values are WindowFrameData objects containing window settings, position, size, and state information.
This data is used for persistence across application sessions when memory is enabled. The KeyValue format is typically: [WindowType]_[ParentObjectId]_[WindowId]
The dictionary is automatically populated from saved data during initialization and updated during runtime as windows are modified.
string windowKey = "MyWindow_MainUI_001";
var windowData = controller.WindowFrameSettingsData[windowKey];
if (controller.WindowFrameSettingsData.ContainsKey(windowKey))
{
var data = controller.WindowFrameSettingsData[windowKey];
Debug.Log($"Window {data.title} was at position {data.position}");
}
| List<StyleSheet> GWG.WindowFramework.WindowFrameController.CurrentThemeStylesheets |
|
get |
Gets the current list of stylesheets based on active theme settings.
A list of StyleSheet objects representing the current theme's styling. Includes the base theme stylesheet and global stylesheet based on load Order settings.
If no theme data is available, returns a list containing only the default stylesheet. The Order of stylesheets in the list affects CSS cascade and style precedence.
var currentSheets = controller.CurrentThemeStylesheets;
Debug.Log($"Current theme uses {currentSheets.Count} stylesheets");
foreach (var sheet in currentSheets)
{
myPanel.styleSheets.Add(sheet);
}
| bool GWG.WindowFramework.WindowFrameController.DebugTelemetryEnabled |
|
getset |
Gets or sets whether high-density machine-readable debug telemetry logging is active.
When true (and when the WFW_TELEMETRY_ENABLED directive is compiled), emits structured JSON logs for pointer events, window boundary crossings, resize calculations, tooltips, and context menus.
| StyleSheet GWG.WindowFramework.WindowFrameController.GlobalStylesheet |
|
getset |
Gets or sets the global stylesheet applied across all themes.
A StyleSheet that is always applied regardless of the current theme. Can be null if no global styling is needed.
The global stylesheet provides consistent styling elements that should appear the same across all themes. Its load Order relative to theme stylesheets is controlled by the GlobalsLoadOrder property.
This is useful for defining common UI patterns, animations, or framework-specific styles that shouldn't change with themes.
controller.GlobalStylesheet = Resources.Load<StyleSheet>("UI/GlobalFramework");
| bool GWG.WindowFramework.WindowFrameController.MemoryEnabled |
|
getset |
Gets or sets the developer-owned controller policy for using window-state memory.
True permits eligible windows to use memory; false disables its use.
The serialized controller field is the sole authored authority. Only the developer's controller setup or trusted code using this API may change it. Theme defaults, player theme data, saved framework JSON, fresh-start fallback and preference resets must never overwrite it. Per-window flags/identity still apply. Other user preferences and retained geometry records are independent; disabling memory is not a request to delete existing saved files.
controller.MemoryEnabled = true;
controller.MemoryEnabled = false;
if (controller.MemoryEnabled)
{
controller.AddOrUpdateWindowData(windowKey, windowData);
}
| bool GWG.WindowFramework.WindowFrameController.TooltipsActive |
|
getset |
Gets or sets whether tooltips are active and functional.
True if tooltips should be displayed and functional; false to disable tooltip system.
When set to false, existing tooltip manipulators remain but tooltips won't be shown. When set to true, automatically searches for and initializes the tooltip system.
The tooltip system is automatically initialized during framework startup but can be toggled on/off during runtime as needed.
controller.TooltipsActive = false;
controller.TooltipsActive = true;
if (controller.TooltipsActive)
{
Debug.Log("Tooltips are currently enabled");
}
| float GWG.WindowFramework.WindowFrameController.TooltipShowDelay |
|
getset |
Gets or sets the delay before showing tooltips when hovering over elements.
The delay in seconds before a tooltip appears after mouse hover begins. Range: 0 to 5 seconds.
This delay prevents tooltips from appearing immediately on hover, reducing visual noise and only showing tooltips for deliberate hover actions. Shorter delays make tooltips more responsive but potentially more intrusive.
controller.TooltipShowDelay = 0.5f;
controller.TooltipShowDelay = 2.0f;