Open 3D Engine AzFramework API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | List of all members
AZ::DocumentPropertyEditor::DocumentAdapter Class Referenceabstract

#include <DocumentAdapter.h>

Inherited by AZ::DocumentPropertyEditor::BasicAdapter, AZ::DocumentPropertyEditor::CvarAdapter, AZ::DocumentPropertyEditor::MetaAdapter, AZ::DocumentPropertyEditor::RoutingAdapter, AZ::DocumentPropertyEditor::RowAggregateAdapter, and AZ::DocumentPropertyEditor::SettingsRegistryAdapter.

Public Types

using ResetEvent = Event<>
 
using ChangedEvent = Event< const Dom::Patch & >
 
using MessageEvent = Event< const AdapterMessage &, Dom::Value & >
 

Public Member Functions

 AZ_RTTI (DocumentAdapter, "{8CEFE485-45C2-4ECC-B9D1-BBE75C7B02AB}")
 
Dom::Value GetContents () const
 
void ConnectResetHandler (ResetEvent::Handler &handler)
 
void ConnectChangedHandler (ChangedEvent::Handler &handler)
 
void ConnectMessageHandler (MessageEvent::Handler &handler)
 
virtual void SetRouter (RoutingAdapter *router, const Dom::Path &route)
 
Dom::Value SendAdapterMessage (const AdapterMessage &message)
 
bool IsEmpty ()
 
virtual ExpanderSettings * CreateExpanderSettings (DocumentAdapter *referenceAdapter, const AZStd::string &settingsRegistryKey=AZStd::string(), const AZStd::string &propertyEditorName=AZStd::string())
 

Static Public Member Functions

static bool IsDebugModeEnabled ()
 
static void SetDebugModeEnabled (bool enableDebugMode)
 
static bool IsRow (const Dom::Value &domValue)
 convenience method to determine whether a particular Dom Value is a row
 

Protected Types

enum class  DocumentResetType { SoftReset , HardReset }
 Specifies the type of reset operation triggered in NotifyResetDocument. More...
 

Protected Member Functions

virtual Dom::Value GenerateContents ()=0
 
virtual Dom::Value HandleMessage (const AdapterMessage &message)
 
void NotifyResetDocument (DocumentResetType resetType=DocumentResetType::SoftReset)
 
void NotifyContentsChanged (const Dom::Patch &patch)
 

Detailed Description

A DocumentAdapter provides an interface for transforming data from an arbitrary source into a DOM hierarchy that can be viewed and edited by a DocumentPropertyView.

A DocumentAdapter shall provide hierarchical contents in the form of a DOM structure in a node-based hierarchy comprised of:

  • A root Adapter element that contains any number of child rows. A mininmal correct adapter may be represented as an empty Adapter element.
  • Row elements, that may contain any number of property editors or rows within. Nested rows will be displayed as children within the hierarchy, while all other nodes will be turned into widget representations and laid out horizontally within the row.
  • Label elements displayed as textual labels within a Row. Labels may have attributes, but no children.
  • PropertyEditor elements that display a property editor of an arbitrary type, specified by the mandatory "type" attribute. The Document Property View will scan for a registered property editor of this type, and provide this node to the property editor for rendering. The contents of a PropertyEditor are dictated by its type.

Member Enumeration Documentation

◆ DocumentResetType

enum class AZ::DocumentPropertyEditor::DocumentAdapter::DocumentResetType
strongprotected

Specifies the type of reset operation triggered in NotifyResetDocument.

Enumerator
SoftReset 

(Default) On soft reset, the adapter will compare any existing cached contents to the new result of GetContents and produce patches based on the difference, assuming cached contents are available.

HardReset 

On hard reset, the adapter will clear any cached contents and simply emit a reset event, ensuring any views fully reset their contents. In cases where the new adapter contents are fully disparate, this can be more efficient than the comparison from a soft reset.

Member Function Documentation

◆ ConnectChangedHandler()

void AZ::DocumentPropertyEditor::DocumentAdapter::ConnectChangedHandler ( ChangedEvent::Handler &  handler)

Connects a listener for the changed event, fired when the contents of the adapter have changed. The provided patch contains all the changes provided (i.e. it shall apply cleanly on top of the last GetContents() result).

◆ ConnectMessageHandler()

void AZ::DocumentPropertyEditor::DocumentAdapter::ConnectMessageHandler ( MessageEvent::Handler &  handler)

Connects a listener for the message event, fired when SendAdapterMessage is called. is invoked. This can be used to prompt the view for a response, e.g. when asking for a confirmation dialog.

◆ ConnectResetHandler()

void AZ::DocumentPropertyEditor::DocumentAdapter::ConnectResetHandler ( ResetEvent::Handler &  handler)

Connects a listener for the reset event, fired when the contents of this adapter have completely changed. Any views listening to this adapter will need to call GetContents to retrieve the new contents of the adapter.

◆ GenerateContents()

virtual Dom::Value AZ::DocumentPropertyEditor::DocumentAdapter::GenerateContents ( )
protectedpure virtual

Generates the contents of this adapter. This must be an Adapter DOM node. These contents will be cached - to notify clients of changes to the structure, NotifyResetDocument or NotifyContentsChanged must be used.

See also
AdapterBuilder for building out this DOM structure.

Implemented in AZ::DocumentPropertyEditor::RowAggregateAdapter, AZ::DocumentPropertyEditor::CvarAdapter, AZ::DocumentPropertyEditor::RowFilterAdapter, AZ::DocumentPropertyEditor::ReflectionAdapter, AZ::DocumentPropertyEditor::SettingsRegistryAdapter, and AZ::DocumentPropertyEditor::RowSortAdapter.

◆ GetContents()

Dom::Value AZ::DocumentPropertyEditor::DocumentAdapter::GetContents ( ) const

Retrieves the contents of this adapter. These contents will be lazily initialized and kept cached, allowing cheap access. Adapters may send notifications via reset and change notifications to indicate when the internal state has changed.

◆ HandleMessage()

virtual Dom::Value AZ::DocumentPropertyEditor::DocumentAdapter::HandleMessage ( const AdapterMessage &  message)
protectedvirtual

Called by SendAdapterMessage before the view is notified. This may be overridden to handle BoundAdapterMessages on fields.

Reimplemented in AZ::DocumentPropertyEditor::RowAggregateAdapter, AZ::DocumentPropertyEditor::ReflectionAdapter, and AZ::DocumentPropertyEditor::SettingsRegistryAdapter.

◆ IsDebugModeEnabled()

static bool AZ::DocumentPropertyEditor::DocumentAdapter::IsDebugModeEnabled ( )
static

If true, debug mode is enabled for all DocumentAdapters.

See also
SetDebugModeEnabled

◆ NotifyContentsChanged()

void AZ::DocumentPropertyEditor::DocumentAdapter::NotifyContentsChanged ( const Dom::Patch &  patch)
protected

Subclasses may call this to trigger a ChangedEvent to notify the view that this adapter's contents have changed. This patch should apply cleanly on the last result GetContents would have returned after any preceding changed or reset events.

◆ NotifyResetDocument()

void AZ::DocumentPropertyEditor::DocumentAdapter::NotifyResetDocument ( DocumentResetType  resetType = DocumentResetType::SoftReset)
protected

Subclasses may call this to trigger a ResetEvent and let the view know that GetContents should be requeried. Where possible, prefer to use NotifyContentsChanged instead.

◆ SendAdapterMessage()

Dom::Value AZ::DocumentPropertyEditor::DocumentAdapter::SendAdapterMessage ( const AdapterMessage &  message)

Sends a message to this adapter. The adapter, or its view, may choose to inspect and examine the message. AdapterMessage provides a Match method to facilitate checking the message against registered CallbackAttributes.

◆ SetDebugModeEnabled()

static void AZ::DocumentPropertyEditor::DocumentAdapter::SetDebugModeEnabled ( bool  enableDebugMode)
static

Enables or disables debug mode globally for all DocumentAdapters. Debug mode adds expensive extra steps to notification operations to ensure the adapter is behaving correctly and will report warnings if an issue is detected. This can also be set at runtime with the ed_debugDocumentPropertyEditorUpdates CVar.

◆ SetRouter()

virtual void AZ::DocumentPropertyEditor::DocumentAdapter::SetRouter ( RoutingAdapter *  router,
const Dom::Path &  route 
)
virtual

Sets a router responsible for chaining nested adapters, if supported.

See also
RoutingAdapter

Reimplemented in AZ::DocumentPropertyEditor::RoutingAdapter.

The documentation for this class was generated from the following file: