Window Framework for UI Toolkit v2.0.x
GWG.WindowFramework.WindowModal Class Reference

Fullscreen blocking surface presenting an ordered queue of content-sized cards. More...

Inheritance diagram for GWG.WindowFramework.WindowModal:
Collaboration diagram for GWG.WindowFramework.WindowModal:

Data Structures

class  CardEntry

Public Member Functions

 WindowModal ()
 Constructs a detached locked-fullscreen queue surface with an initial empty card.
void AddCard (CardElement card, VisualElement initialFocus=null)
 Appends a detached card while preserving the queue order.
void ClearCards ()
 Immediately detaches all queued cards and force-closes the modal surface.
void CloseActiveCard ()
 Begins application-authorized removal of ActiveCard, if one exists.
bool RemoveCard (CardElement card)
 Starts application-authorized removal of one exact queued card.
Public Member Functions inherited from GWG.WindowFramework.WindowFrame
 WindowFrame ()
 Represents a custom UI element serving as a container for window-based content, including a header, content, and footer, providing event handling and theme adaptability for Unity's UI Toolkit.
void CloseWindow (bool forceAll=false)
 Closes the window if allowed.
void DockTab (WindowFrame incoming)
 Docks an incoming standalone WindowFrame into this window as a nested tab.
void DockTo (WindowDockState targetState)
 Applies the specified programmatic dock geometry, preserving initial floating bounds.
void ExitFullscreenToCursor (Vector2 cursorPos)
 Exits fullscreen mode and pre-positions the restored floating window centered horizontally under the cursor.
void Hide ()
 Hides the window while keeping it in memory.
void SetOpeningPosition ()
 Sets the opening position of the window based on the selected position. Options include: TopLeft, Top, TopRight, Left, Center, Right, BottomLeft, Bottom, BottomRight.
void Show ()
 Shows the window by setting its display style to flex and opacity to 1.0f.
void SwitchToTab (int index)
 Switches the active view to display the specified nested tab's content.
void Undock (Vector2? cursorPos=null)
 Undocks the window frame, restoring its pre-dock floating size and positioning.
WindowFrame UndockTab (int index, Vector2? mousePos=null)
 Undocks a nested tab back into an independent standalone WindowFrame.

Properties

CardElement ActiveCard [get]
 Gets the first queued card that has not begun closing, or null.
bool AllowClickOutsideToClose [get, set]
 Gets or sets outside-dismissal permission on the compatibility card only.
int CardCount [get]
 Gets queued entries including those still fading out.
VisualElement ModalBody [get]
 Gets the compatibility card's application content container.
Button ModalCloseButton [get]
 Gets the compatibility card's user-dismissal button.
VisualElement ModalDialog [get]
 Gets the constructor-created compatibility card, not the active queue card.
VisualElement ModalFooter [get]
 Gets the compatibility card's fixed action area.
VisualElement ModalHeader [get]
 Gets the compatibility card's fixed header.
ScrollView ModalScrollView [get]
 Gets the compatibility card's scrolling body viewport.
string ModalTitle [get, set]
 Gets or sets the compatibility card title; does not select or rename queued cards.
Label ModalTitleLabel [get]
 Gets the compatibility card's plain-text title label.
bool ShowModalCloseButton [get, set]
 Gets or sets close-button visibility; this alone does not prohibit dismissal.
bool ShowModalFooter [get, set]
 Gets or sets compatibility-footer visibility without destroying its children.
bool ShowModalHeader [get, set]
 Gets or sets compatibility-header visibility without destroying its children.
Properties inherited from GWG.WindowFramework.WindowFrame
bool Active [get, set]
 Gets or sets whether the window is active.
int ActiveTabIndex [get]
 Gets the current tab-selection index; interpret against the current live tab list.
bool AllowClose = true [get, set]
 Gets or sets whether the window can be closed.
bool AllowFullscreen = true [get, set]
 Determines whether the window frame can toggle to fullscreen mode.
bool AllowLock [get, set]
 Gets or sets whether the window can be locked.
bool AllowMove = true [get, set]
 Gets or sets whether the window can be moved.
bool AllowMultipleInstances = true [get, set]
 Gets or sets whether multiple instances of this window are allowed.
bool AllowResize [get, set]
 Gets or sets whether the window can be resized.
bool AllowTabDocking = true [get, set]
 Gets or sets whether this window can participate in tabbed window nesting and docking.
VisualElement Content [get, set]
 Gets or sets the content area of the window.
override VisualElement contentContainer [get]
 Overrides the contentContainer to return the window's content area instead of the root.
ContextMenuConfig ContextMenuConfig [get, set]
 Gets or sets the context menu configuration for this window.
float DefaultHeight [get, set]
float DefaultWidth [get, set]
WindowDockState DockState [get, set]
 Gets/sets docking metadata; assignment alone does not reposition or resize this window.
WindowFrameDragger Dragger [get]
 Gets the installed header dragger, which can be null before scheduled setup.
VisualElement FooterToolbar [get, set]
 Gets or sets the toolbar in the footer area of the window.
bool Fullscreen [get, set]
 Gets or sets whether the window is in fullscreen mode.
bool Locked [get, set]
 Gets or sets whether the window is locked.
bool LockedFullscreen [get, set]
 Determines whether the fullscreen mode of the window is locked, preventing the user from toggling fullscreen on or off.
bool LockedToStartPosition [get, set]
 Gets or sets whether the window is locked to its start position.
float MinHeight [get, set]
 Gets or sets the minimum height of the window.
float MinWidth [get, set]
 Gets or sets the minimum width of the window.
IReadOnlyList< WindowTabEntry > NestedTabs [get]
 Gets the live nested-tab list through a read-only interface, not an independent snapshot.
string OptionsMenuTooltip [get, set]
 Gets or sets the tooltip for the options menu button.
string ParentObjectId [get, set]
 Gets or sets the ID of the parent object associated with the window.
Rect PreDockRect [get, set]
 Gets/sets floating restore bounds in parent layout coordinates.
string ResizeAreaTooltip [get, set]
 Gets or sets the tooltip for the resize area.
bool ShowFooter [get, set]
 Gets or sets whether the footer is visible.
bool ShowHeader [get, set]
 Gets or sets whether the header is visible.
WindowFramePosition StartPosition [get, set]
 Gets or sets the position of the window frame.
List< StyleSheet > StyleSheet [get, set]
 Gets or sets the stylesheet applied to the window.
string Title [get, set]
 Gets or sets the title of the window.
string WindowId [get, set]
 Gets or sets the unique ID of the window.
bool WindowMemoryEnabled = false [get, set]
 Gets or sets whether the window memory is enabled.

Private Member Functions

void FinishRemoval (CardEntry entry)
void LayoutCards ()
void OnBackdrop (PointerDownEvent evt)
void OnCardGeometry (GeometryChangedEvent evt)
void OnDismissRequested (CardElement card)
void RemoveImmediately (CardEntry entry)
void UpdateBottomFade ()

Private Attributes

readonly List< CardEntry > _cards = new List<CardEntry>()
bool _clearing
readonly CardElement _defaultCard
IVisualElementScheduledItem _fadeUpdate
float _fadeZone = 120
float _motionMs = 560
float _spacing = 16
readonly VisualElement _viewport

Static Private Attributes

static readonly CustomStyleProperty< float > FadeZone = new CustomStyleProperty<float>("--wfw-modal-bottom-fade")
static readonly CustomStyleProperty< float > Motion = new CustomStyleProperty<float>("--wfw-modal-motion-ms")
static readonly CustomStyleProperty< float > Spacing = new CustomStyleProperty<float>("--wfw-modal-card-gap")

Additional Inherited Members

Events inherited from GWG.WindowFramework.WindowFrame
static Action< WindowFrame > OnWindowFrameAdded
 Event triggered when a new WindowFrame is added to the panel.
static Action< WindowFrame > OnWindowFrameRemoved
 Event triggered when a WindowFrame is removed from the panel.

Detailed Description

Fullscreen blocking surface presenting an ordered queue of content-sized cards.

The controller-owned modal host supplies blocking, backdrop lifetime and focus routing. This WindowFrame is deliberately locked fullscreen with ordinary drag, resize, tabs and memory off; its children are CardElements, not separately registered windows. Populate a detached card and call controller.ShowModal(card), or AddCard on an application-owned WindowModal. Only the first non-closing card is active. Closing fades the exact card in place, retains its queue space until removal, then animates remaining cards upward. There is no collapse animation. Default motion is 560 ms. Dismissal is presentation only: the application must perform validation, submission/reward logic and decide when an application-authorized RemoveCard is appropriate. No Escape/input binding is installed. Theme roles control appearance, not dismissal permissions. The ModalBody/Header/Footer aliases target the initial compatibility card, not whichever card is currently active; queued-card content must be accessed through the actual CardElement.

Constructor & Destructor Documentation

◆ WindowModal()

GWG.WindowFramework.WindowModal.WindowModal ( )
inline

Constructs a detached locked-fullscreen queue surface with an initial empty card.

Drag, resize, tabs, layout memory and ordinary fullscreen controls are disabled. AddCard replaces an unused initial card on the first explicit addition. Populate and present through the existing controller; construction alone does not mount the modal or arbitrate gameplay input.

Here is the call graph for this function:
Here is the caller graph for this function:

Member Function Documentation

◆ AddCard()

void GWG.WindowFramework.WindowModal.AddCard ( CardElement card,
VisualElement initialFocus = null )
inline

Appends a detached card while preserving the queue order.

Parameters
cardApplication-created card. Its width/max-width remain developer USS choices.
initialFocusOptional focus target inside this card; focus is applied when eligible.

The modal creates and owns a positioning slot, subscribes to geometry/dismissal, and removes those subscriptions when the card leaves. An unused empty initial card is replaced by the first explicit card so consumers do not receive an unintended blank prompt.

Exceptions
ArgumentNullExceptionThe card is null.
InvalidOperationExceptionThe card already belongs to a hierarchy.
ArgumentExceptionThe focus target does not belong to the card.
Here is the call graph for this function:
Here is the caller graph for this function:

◆ ClearCards()

void GWG.WindowFramework.WindowModal.ClearCards ( )
inline

Immediately detaches all queued cards and force-closes the modal surface.

This teardown path does not run per-card fade transitions or business callbacks. It removes geometry/dismissal subscriptions, then calls CloseWindow(true). Application-owned content resources and callbacks remain the application's cleanup responsibility.

Here is the call graph for this function:

◆ CloseActiveCard()

void GWG.WindowFramework.WindowModal.CloseActiveCard ( )
inline

Begins application-authorized removal of ActiveCard, if one exists.

Uses RemoveCard and therefore bypasses user AllowDismiss. A closing card remains in its slot until timed cleanup. Use CardElement.RequestDismiss for a user cancellation action.

Here is the call graph for this function:

◆ FinishRemoval()

void GWG.WindowFramework.WindowModal.FinishRemoval ( CardEntry entry)
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ LayoutCards()

void GWG.WindowFramework.WindowModal.LayoutCards ( )
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ OnBackdrop()

void GWG.WindowFramework.WindowModal.OnBackdrop ( PointerDownEvent evt)
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ OnCardGeometry()

void GWG.WindowFramework.WindowModal.OnCardGeometry ( GeometryChangedEvent evt)
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ OnDismissRequested()

void GWG.WindowFramework.WindowModal.OnDismissRequested ( CardElement card)
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ RemoveCard()

bool GWG.WindowFramework.WindowModal.RemoveCard ( CardElement card)
inline

Starts application-authorized removal of one exact queued card.

Parameters
cardThe card to remove; unrelated cards retain their content and order.
Returns
True if removal began; false if the card is absent or already closing.

This deliberately bypasses AllowDismiss: the application may complete a required form after validating an answer. User-facing closure must use CardElement.RequestDismiss instead. The card becomes non-interactive and fades at its existing position, without shrinking. Its slot remains in layout until the transition finishes (or the bounded cleanup fallback), so lower cards do not overlap a still-visible card. Removal then reflows the remaining queue. True means removal started, not synchronous detachment. The last removal closes this surface.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ RemoveImmediately()

void GWG.WindowFramework.WindowModal.RemoveImmediately ( CardEntry entry)
inlineprivate
Here is the call graph for this function:
Here is the caller graph for this function:

◆ UpdateBottomFade()

void GWG.WindowFramework.WindowModal.UpdateBottomFade ( )
inlineprivate
Here is the caller graph for this function:

Field Documentation

◆ _cards

readonly List<CardEntry> GWG.WindowFramework.WindowModal._cards = new List<CardEntry>()
private

◆ _clearing

bool GWG.WindowFramework.WindowModal._clearing
private

◆ _defaultCard

readonly CardElement GWG.WindowFramework.WindowModal._defaultCard
private

◆ _fadeUpdate

IVisualElementScheduledItem GWG.WindowFramework.WindowModal._fadeUpdate
private

◆ _fadeZone

float GWG.WindowFramework.WindowModal._fadeZone = 120
private

◆ _motionMs

float GWG.WindowFramework.WindowModal._motionMs = 560
private

◆ _spacing

float GWG.WindowFramework.WindowModal._spacing = 16
private

◆ _viewport

readonly VisualElement GWG.WindowFramework.WindowModal._viewport
private

◆ FadeZone

readonly CustomStyleProperty<float> GWG.WindowFramework.WindowModal.FadeZone = new CustomStyleProperty<float>("--wfw-modal-bottom-fade")
staticprivate

◆ Motion

readonly CustomStyleProperty<float> GWG.WindowFramework.WindowModal.Motion = new CustomStyleProperty<float>("--wfw-modal-motion-ms")
staticprivate

◆ Spacing

readonly CustomStyleProperty<float> GWG.WindowFramework.WindowModal.Spacing = new CustomStyleProperty<float>("--wfw-modal-card-gap")
staticprivate

Property Documentation

◆ ActiveCard

CardElement GWG.WindowFramework.WindowModal.ActiveCard
get

Gets the first queued card that has not begun closing, or null.

Closing entries remain counted until their fade/removal completes. The active card is not necessarily interactive until layout settles; do not infer input readiness from this property.

◆ AllowClickOutsideToClose

bool GWG.WindowFramework.WindowModal.AllowClickOutsideToClose
getset

Gets or sets outside-dismissal permission on the compatibility card only.

Actual backdrop requests target ActiveCard and also obey that card's AllowDismiss. For explicitly queued cards configure their own AllowOutsideDismiss instead.

◆ CardCount

int GWG.WindowFramework.WindowModal.CardCount
get

Gets queued entries including those still fading out.

◆ ModalBody

VisualElement GWG.WindowFramework.WindowModal.ModalBody
get

Gets the compatibility card's application content container.

◆ ModalCloseButton

Button GWG.WindowFramework.WindowModal.ModalCloseButton
get

Gets the compatibility card's user-dismissal button.

◆ ModalDialog

VisualElement GWG.WindowFramework.WindowModal.ModalDialog
get

Gets the constructor-created compatibility card, not the active queue card.

◆ ModalFooter

VisualElement GWG.WindowFramework.WindowModal.ModalFooter
get

Gets the compatibility card's fixed action area.

◆ ModalHeader

VisualElement GWG.WindowFramework.WindowModal.ModalHeader
get

Gets the compatibility card's fixed header.

◆ ModalScrollView

ScrollView GWG.WindowFramework.WindowModal.ModalScrollView
get

Gets the compatibility card's scrolling body viewport.

◆ ModalTitle

string GWG.WindowFramework.WindowModal.ModalTitle
getset

Gets or sets the compatibility card title; does not select or rename queued cards.

◆ ModalTitleLabel

Label GWG.WindowFramework.WindowModal.ModalTitleLabel
get

Gets the compatibility card's plain-text title label.

◆ ShowModalCloseButton

bool GWG.WindowFramework.WindowModal.ShowModalCloseButton
getset

Gets or sets close-button visibility; this alone does not prohibit dismissal.

◆ ShowModalFooter

bool GWG.WindowFramework.WindowModal.ShowModalFooter
getset

Gets or sets compatibility-footer visibility without destroying its children.

◆ ShowModalHeader

bool GWG.WindowFramework.WindowModal.ShowModalHeader
getset

Gets or sets compatibility-header visibility without destroying its children.