A custom form container element that extends Unity's VisualElement with USO UI framework functionality and specialized form management capabilities. Provides enhanced styling, field validation, data binding capabilities, form lifecycle events, and integration with the USO UI system for comprehensive form-based user interfaces. More...

Inheritance diagram for GWG.UsoUIElements.UsoFormElement:

Public Member Functions
	UsoFormElement ()
	Initializes a new instance of the UsoFormElement class with default settings. Creates a form container with USO framework integration, theme loading, and form lifecycle event management.
	UsoFormElement (string fieldName)
	Initializes a new instance of the UsoFormElement class with the specified field name. Creates a form container with custom identification for binding and reference purposes.
	UsoFormElement (string fieldName, Object fieldDatasource)
	Initializes a new instance of the UsoFormElement class with field name and initial data source. Creates a form container with custom identification and establishes initial data binding relationships.
	UsoFormElement (string fieldName, Object fieldDatasource, out UsoFormElement newField)
	Initializes a new instance of the UsoFormElement class with field name, initial data source, and returns a reference. Creates a form container with custom identification, establishes initial data binding, and provides an out parameter for immediate access.
	UsoFormElement (string fieldName, out UsoFormElement newField)
	Initializes a new instance of the UsoFormElement class with field name and returns a reference. Creates a form container with custom identification and provides an out parameter for immediate access.
void	ApplyBinding (string fieldBindingProp, string fieldBindingPath, BindingMode fieldBindingMode)
	Applies data binding to the specified property of this control using Unity's data binding system. Configures the binding with the provided path and mode for automatic data synchronization.
void	CancelForm ()
	Initiates a form cancellation operation by invoking the OnFormCancel event. This method provides a centralized way to trigger cancel logic and cleanup across all form components.
UsoLineItem	GetParentLineItem ()
	Retrieves the first ancestor UsoLineItem control in the visual tree hierarchy. This is useful for accessing parent container functionality and maintaining proper UI structure.
void	InitElement (string fieldName=null)
	Initializes the USO UI element with the specified field name and applies necessary styling classes and theme configuration. This method sets up the basic USO framework integration for the control including theme loading and flexible layout configuration.
void	ResetForm ()
	Initiates a form reset operation by invoking the OnFormReset event. This method provides a centralized way to trigger reset logic across all form components.
void	SetFieldStatus (FieldStatusTypes fieldStatus)
	Updates the field's status type, which affects its visual appearance and validation state. The status change is automatically reflected in the UI through the FieldStatus property.
void	ShowFieldStatus (bool status)
	Controls the visibility and functionality of the field status/validation system. When disabled, removes validation-related styling from the control.
void	SubmitForm ()
	Initiates a form submission operation by invoking the OnFormSubmit event. This method provides a centralized way to trigger submit logic and validation across all form components.
void	UpdateDatasource (Object fieldDatasource=null)
	Updates the form's data source, establishing or clearing data binding relationships and triggering appropriate lifecycle events. Manages the connection and disconnection of data sources with proper event notifications for form state management.
Public Member Functions inherited from GWG.UsoUIElements.IUsoUiElement
void	AddToClassList (string className)
	Adds the specified CSS class name to this element's class list. This method is inherited from Unity's VisualElement and enables dynamic styling modifications.
void	ClearBindings ()
	Removes all data binding configurations from this element. This method is inherited from Unity's VisualElement and provides cleanup functionality for data bindings.
void	RemoveFromClassList (string className)
	Removes the specified CSS class name from this element's class list. This method is inherited from Unity's VisualElement and provides dynamic styling capabilities.

Properties
FieldStatusTypes	FieldStatus `[get, private set]`
	Gets the current field status type, which determines the visual state and validation feedback. This property is automatically reflected in the UI through CSS class modifications.
bool	FieldStatusEnabled `[get, private set]`
	Gets or sets whether field status/validation functionality is enabled for this control. When enabled, adds validation CSS class for styling. When disabled, removes validation styling.

Events
Action	OnFormCancel
	Internal event triggered when the form cancel operation is requested. Subscribe to this event to implement custom cancel logic for form abandonment and cleanup.
Action< Object >	OnFormDataConnection
	Internal event triggered when a new data source is connected to the form. Subscribe to this event to initialize form fields and establish data binding relationships.
Action< Object >	OnFormDataDisconnection
	Internal event triggered when the form's data source is disconnected or cleared. Subscribe to this event to handle cleanup operations when data binding relationships are removed.
Action	OnFormReset
	Internal event triggered when the form reset operation is requested. Subscribe to this event to implement custom reset logic for form fields and data.
Action	OnFormSubmit
	Internal event triggered when the form submit operation is requested. Subscribe to this event to implement custom submit logic for form validation and data processing.

Private Attributes
FieldStatusTypes	_fieldStatus
bool	_fieldStatusEnabled = false

Static Private Attributes
const string	DefaultBindProp = ""
	Default binding property used when applying data bindings to this field. Currently set to empty string as form elements typically manage multiple child bindings rather than a single value.
const string	ElementClass = "uso-display-section"
	CSS class name applied to all UsoFormElement instances for styling purposes. Uses "uso-display-section" to maintain consistency with the stylesheet.
const string	ElementStylesheet = "uso-display-section"
	CSS stylesheet name applied to all UsoFormElement instances for styling purposes. Uses "uso-display-section" for consistent section-based styling.
const string	ElementValidationClass = "uso-field-validation"
	CSS class name applied when field validation/status functionality is enabled.

Detailed Description

A custom form container element that extends Unity's VisualElement with USO UI framework functionality and specialized form management capabilities. Provides enhanced styling, field validation, data binding capabilities, form lifecycle events, and integration with the USO UI system for comprehensive form-based user interfaces.

This control implements the IUsoUiElement interface to provide consistent behavior across the USO UI framework. It supports field status indicators, automatic data binding capabilities, and custom styling through CSS classes. The control serves as a specialized container for form-based interfaces, providing form lifecycle management through events for reset, submit, cancel, and data source connection/disconnection operations. It automatically loads and applies the USO theme stylesheet and configures itself with flexible layout properties suitable for form layouts. The control includes comprehensive data source management capabilities, allowing dynamic connection and disconnection of data objects with appropriate event notifications for form state management and data synchronization scenarios.

Constructor & Destructor Documentation

◆ UsoFormElement() [1/5]

GWG.UsoUIElements.UsoFormElement.UsoFormElement ( )

Initializes a new instance of the UsoFormElement class with default settings. Creates a form container with USO framework integration, theme loading, and form lifecycle event management.

◆ UsoFormElement() [2/5]

GWG.UsoUIElements.UsoFormElement.UsoFormElement ( string fieldName )

Initializes a new instance of the UsoFormElement class with the specified field name. Creates a form container with custom identification for binding and reference purposes.

Parameters

fieldName The name to assign to this form element.

◆ UsoFormElement() [3/5]

GWG.UsoUIElements.UsoFormElement.UsoFormElement	(	string	fieldName,
		out UsoFormElement	newField )

Initializes a new instance of the UsoFormElement class with field name and returns a reference. Creates a form container with custom identification and provides an out parameter for immediate access.

Parameters

fieldName	The name to assign to this form element.
newField	Output parameter that receives a reference to the newly created form element.

◆ UsoFormElement() [4/5]

GWG.UsoUIElements.UsoFormElement.UsoFormElement	(	string	fieldName,
		Object	fieldDatasource )

Initializes a new instance of the UsoFormElement class with field name and initial data source. Creates a form container with custom identification and establishes initial data binding relationships.

Parameters

fieldName	The name to assign to this form element.
fieldDatasource	The Unity Object to use as the initial data source for form binding operations.

◆ UsoFormElement() [5/5]

GWG.UsoUIElements.UsoFormElement.UsoFormElement	(	string	fieldName,
		Object	fieldDatasource,
		out UsoFormElement	newField )

Initializes a new instance of the UsoFormElement class with field name, initial data source, and returns a reference. Creates a form container with custom identification, establishes initial data binding, and provides an out parameter for immediate access.

Parameters

fieldName	The name to assign to this form element.
fieldDatasource	The Unity Object to use as the initial data source for form binding operations.
newField	Output parameter that receives a reference to the newly created form element.

Member Function Documentation

◆ ApplyBinding()

void GWG.UsoUIElements.UsoFormElement.ApplyBinding	(	string	fieldBindingProp,
		string	fieldBindingPath,
		BindingMode	fieldBindingMode )

Applies data binding to the specified property of this control using Unity's data binding system. Configures the binding with the provided path and mode for automatic data synchronization.

Parameters

fieldBindingProp	The property name on this control to bind to.
fieldBindingPath	The path to the data source property to bind from.
fieldBindingMode	The binding mode that determines how data flows between source and target.

Exceptions

Exception Thrown when binding setup fails. Original exception is preserved and re-thrown.

While form elements typically manage child element bindings rather than direct value bindings, this method enables binding to form-level properties such as visibility, enabled state, or other container characteristics.

Implements GWG.UsoUIElements.IUsoUiElement.

◆ CancelForm()

void GWG.UsoUIElements.UsoFormElement.CancelForm ( )

Initiates a form cancellation operation by invoking the OnFormCancel event. This method provides a centralized way to trigger cancel logic and cleanup across all form components.

Calling this method will notify all subscribers to the OnFormCancel event, allowing them to perform cleanup operations, discard pending changes, and handle form abandonment scenarios.

◆ GetParentLineItem()

UsoLineItem GWG.UsoUIElements.UsoFormElement.GetParentLineItem ( )

Retrieves the first ancestor UsoLineItem control in the visual tree hierarchy. This is useful for accessing parent container functionality and maintaining proper UI structure.

Returns: The parent UsoLineItem if found; otherwise, null.

◆ InitElement()

void GWG.UsoUIElements.UsoFormElement.InitElement ( string fieldName = null )

Initializes the USO UI element with the specified field name and applies necessary styling classes and theme configuration. This method sets up the basic USO framework integration for the control including theme loading and flexible layout configuration.

Parameters

fieldName Optional name to assign to the element. If null, no name is set.

The initialization process includes setting flexible layout properties, loading the USO theme stylesheet from resources, and applying appropriate CSS classes for consistent form styling throughout the application.

Implements GWG.UsoUIElements.IUsoUiElement.

◆ ResetForm()

void GWG.UsoUIElements.UsoFormElement.ResetForm ( )

Initiates a form reset operation by invoking the OnFormReset event. This method provides a centralized way to trigger reset logic across all form components.

Calling this method will notify all subscribers to the OnFormReset event, allowing them to implement their specific reset logic such as clearing fields, resetting validation states, and restoring default values.

◆ SetFieldStatus()

void GWG.UsoUIElements.UsoFormElement.SetFieldStatus ( FieldStatusTypes fieldStatus )

Updates the field's status type, which affects its visual appearance and validation state. The status change is automatically reflected in the UI through the FieldStatus property.

Parameters

fieldStatus The new field status type to apply.

Implements GWG.UsoUIElements.IUsoUiElement.

◆ ShowFieldStatus()

void GWG.UsoUIElements.UsoFormElement.ShowFieldStatus ( bool status )

Controls the visibility and functionality of the field status/validation system. When disabled, removes validation-related styling from the control.

Parameters

status True to enable field status functionality; false to disable it.

Implements GWG.UsoUIElements.IUsoUiElement.

◆ SubmitForm()

void GWG.UsoUIElements.UsoFormElement.SubmitForm ( )

Initiates a form submission operation by invoking the OnFormSubmit event. This method provides a centralized way to trigger submit logic and validation across all form components.

Calling this method will notify all subscribers to the OnFormSubmit event, enabling them to perform validation, data processing, and submission logic as appropriate for the form's purpose.

◆ UpdateDatasource()

void GWG.UsoUIElements.UsoFormElement.UpdateDatasource ( Object fieldDatasource = null )

Updates the form's data source, establishing or clearing data binding relationships and triggering appropriate lifecycle events. Manages the connection and disconnection of data sources with proper event notifications for form state management.

Parameters

fieldDatasource The Unity Object to use as the new data source. Pass null to disconnect the current data source.

When a non-null data source is provided, the method establishes the binding relationship and invokes the OnFormDataConnection event. When null is provided, it clears all existing bindings, sets the data source to null, and invokes the OnFormDataDisconnection event. This method enables dynamic data source management for scenarios where form data context needs to change during runtime.

Member Data Documentation

◆ _fieldStatus

FieldStatusTypes GWG.UsoUIElements.UsoFormElement._fieldStatus

private

◆ _fieldStatusEnabled

bool GWG.UsoUIElements.UsoFormElement._fieldStatusEnabled = false

private

◆ DefaultBindProp

const string GWG.UsoUIElements.UsoFormElement.DefaultBindProp = ""

staticprivate

Default binding property used when applying data bindings to this field. Currently set to empty string as form elements typically manage multiple child bindings rather than a single value.

◆ ElementClass

const string GWG.UsoUIElements.UsoFormElement.ElementClass = "uso-display-section"

staticprivate

CSS class name applied to all UsoFormElement instances for styling purposes. Uses "uso-display-section" to maintain consistency with the stylesheet.

◆ ElementStylesheet

const string GWG.UsoUIElements.UsoFormElement.ElementStylesheet = "uso-display-section"

staticprivate

CSS stylesheet name applied to all UsoFormElement instances for styling purposes. Uses "uso-display-section" for consistent section-based styling.

◆ ElementValidationClass

const string GWG.UsoUIElements.UsoFormElement.ElementValidationClass = "uso-field-validation"

staticprivate

CSS class name applied when field validation/status functionality is enabled.

Property Documentation

◆ FieldStatus

FieldStatusTypes GWG.UsoUIElements.UsoFormElement.FieldStatus

getprivate set

Gets the current field status type, which determines the visual state and validation feedback. This property is automatically reflected in the UI through CSS class modifications.

The current FieldStatusTypes value indicating the field's validation state.

Implements GWG.UsoUIElements.IUsoUiElement.

◆ FieldStatusEnabled

bool GWG.UsoUIElements.UsoFormElement.FieldStatusEnabled

getprivate set

Gets or sets whether field status/validation functionality is enabled for this control. When enabled, adds validation CSS class for styling. When disabled, removes validation styling.

True if field status functionality is enabled; otherwise, false. Default is false for form elements.

Form elements have field status functionality disabled by default since they primarily serve as containers for other form controls that handle their own validation states.

Implements GWG.UsoUIElements.IUsoUiElement.

Event Documentation

◆ OnFormCancel

Action GWG.UsoUIElements.UsoFormElement.OnFormCancel

package

Internal event triggered when the form cancel operation is requested. Subscribe to this event to implement custom cancel logic for form abandonment and cleanup.

This event provides a mechanism for handling form cancellation scenarios, allowing implementers to perform cleanup operations, discard changes, and return to previous states.

◆ OnFormDataConnection

Action<Object> GWG.UsoUIElements.UsoFormElement.OnFormDataConnection

package

Internal event triggered when a new data source is connected to the form. Subscribe to this event to initialize form fields and establish data binding relationships.

This event enables subscribers to respond to new data source connections by initializing form fields, establishing bindings, and configuring the UI to reflect the new data context.

◆ OnFormDataDisconnection

Action<Object> GWG.UsoUIElements.UsoFormElement.OnFormDataDisconnection

package

Internal event triggered when the form's data source is disconnected or cleared. Subscribe to this event to handle cleanup operations when data binding relationships are removed.

This event notifies subscribers when the data source is being disconnected, allowing for proper cleanup of binding relationships, UI state management, and resource disposal.

◆ OnFormReset

Action GWG.UsoUIElements.UsoFormElement.OnFormReset

package

Internal event triggered when the form reset operation is requested. Subscribe to this event to implement custom reset logic for form fields and data.

This event provides a centralized mechanism for handling form reset operations across all contained form elements. Implementers can use this to clear form data, reset validation states, and restore default values.

◆ OnFormSubmit

Action GWG.UsoUIElements.UsoFormElement.OnFormSubmit

package

Internal event triggered when the form submit operation is requested. Subscribe to this event to implement custom submit logic for form validation and data processing.

This event enables centralized form submission handling, allowing implementers to perform validation, data processing, and submission logic when the form is ready to be processed.

Public Member Functions

Properties

Events

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ UsoFormElement() [1/5]

◆ UsoFormElement() [2/5]

◆ UsoFormElement() [3/5]

◆ UsoFormElement() [4/5]

◆ UsoFormElement() [5/5]

Member Function Documentation

◆ ApplyBinding()

◆ CancelForm()

◆ GetParentLineItem()

◆ InitElement()

◆ ResetForm()

◆ SetFieldStatus()

◆ ShowFieldStatus()

◆ SubmitForm()

◆ UpdateDatasource()

Member Data Documentation

◆ _fieldStatus

◆ _fieldStatusEnabled

◆ DefaultBindProp

◆ ElementClass

◆ ElementStylesheet

◆ ElementValidationClass

Property Documentation

◆ FieldStatus

◆ FieldStatusEnabled

Event Documentation

◆ OnFormCancel

◆ OnFormDataConnection

◆ OnFormDataDisconnection

◆ OnFormReset

◆ OnFormSubmit