ezEngine Release 25.08
Loading...
Searching...
No Matches
Classes | Public Member Functions | Public Attributes | Static Public Attributes | Protected Member Functions | Protected Attributes | Friends | List of all members
ezDocument Class Referenceabstract

Base class for all editable documents in the editor. Handles state, object management, undo/redo, and more. More...

#include <Document.h>

Inheritance diagram for ezDocument:
Inheritance graph
[legend]

Classes

struct  PasteInfo
 Information about a pasted object, including its parent and index. More...
 

Public Member Functions

 ezDocument (ezStringView sPath, ezDocumentObjectManager *pDocumentObjectManagerImpl)
 
Document State Functions
bool IsModified () const
 
bool IsReadOnly () const
 
const ezUuid GetGuid () const
 
const ezDocumentObjectManager * GetObjectManager () const
 
ezDocumentObjectManager * GetObjectManager ()
 
ezSelectionManager * GetSelectionManager () const
 
ezCommandHistory * GetCommandHistory () const
 
virtual ezObjectAccessorBase * GetObjectAccessor () const
 
Clipboard Functions
virtual void GetSupportedMimeTypesForPasting (ezHybridArray< ezString, 4 > &out_mimeTypes) const
 Whether this document supports pasting the given mime format into it.
 
virtual bool CopySelectedObjects (ezAbstractObjectGraph &out_objectGraph, ezStringBuilder &out_sMimeType) const
 Creates the abstract graph of data to be copied and returns the mime type for the clipboard to identify the data.
 
virtual bool Paste (const ezArrayPtr< PasteInfo > &info, const ezAbstractObjectGraph &objectGraph, bool bAllowPickedPosition, ezStringView sMimeType)
 Pastes objects from the given object graph into the document.
 
Inter Document Communication
void BroadcastInterDocumentMessage (ezReflectedClass *pMessage, ezDocument *pSender)
 This will deliver the message to all open documents. The documents may respond, e.g. by modifying the content of the message.
 
virtual void OnInterDocumentMessage (ezReflectedClass *pMessage, ezDocument *pSender)
 Called on all documents when BroadcastInterDocumentMessage() is called.
 
Editing Functionality
virtual ezEditorInputContext * GetEditorInputContextOverride ()
 Allows to return a single input context that currently overrides all others (in priority).
 
Misc Functions
virtual void DeleteSelectedObjects () const
 Deletes all currently selected objects in the document.
 
const ezSet< ezString > & GetUnknownObjectTypes () const
 Returns the set of unknown object types encountered during loading.
 
ezUInt32 GetUnknownObjectTypeInstances () const
 Returns the number of unknown object type instances encountered during loading.
 
void SetAddToResetFilesList (bool b)
 If disabled, this document will not be put into the recent files list.
 
bool GetAddToRecentFilesList () const
 Whether this document shall be put into the recent files list.
 
void ShowDocumentStatus (const ezFormatString &msg) const
 Broadcasts a status message event. The window that displays the document may show this in some form, e.g. in the status bar.
 
virtual ezResult ComputeObjectTransformation (const ezDocumentObject *pObject, ezTransform &out_result) const
 Tries to compute the position and rotation for an object in the document. Returns EZ_SUCCESS if it was possible.
 
virtual ezManipulatorSearchStrategy GetManipulatorSearchStrategy () const
 Needed by ezManipulatorManager to know where to look for the manipulator attributes.
 
- Public Member Functions inherited from ezReflectedClass
virtual const ezRTTI * GetDynamicRTTI () const
 
bool IsInstanceOf (const ezRTTI *pType) const
 Returns whether the type of this instance is of the given type or derived from it.
 
template<typename T >
EZ_ALWAYS_INLINE bool IsInstanceOf () const
 Returns whether the type of this instance is of the given type or derived from it.
 

Public Attributes

ezUniquePtr< ezObjectMetaData< ezUuid, ezDocumentObjectMetaData > > m_DocumentObjectMetaData
 Meta data for all document objects.
 
ezEvent< const ezDocumentEvent & > m_EventsOne
 Event for document-specific notifications.
 
ezEvent< const ezObjectAccessorChangeEvent & > m_ObjectAccessorChangeEvents
 Event for object accessor change notifications.
 

Static Public Attributes

static ezEvent< const ezDocumentEvent & > s_EventsAny
 Static event for notifications across all documents.
 

Protected Member Functions

void SetModified (bool b)
 
void SetReadOnly (bool b)
 
virtual ezTaskGroupID InternalSaveDocument (AfterSaveCallback callback)
 Internal save implementation. Returns a task group ID for async save.
 
virtual ezStatus InternalLoadDocument ()
 Internal load implementation. Loads the document from disk.
 
virtual ezDocumentInfo * CreateDocumentInfo ()=0
 Creates the document info structure. Must be implemented by derived classes.
 
virtual void InternalAfterSaveDocument ()
 Hook to execute additional code after successfully saving a document. E.g. manual asset transform can be done here.
 
virtual void AttachMetaDataBeforeSaving (ezAbstractObjectGraph &graph) const
 
virtual void RestoreMetaDataAfterLoading (const ezAbstractObjectGraph &graph, bool bUndoable)
 
virtual void InitializeAfterLoading (bool bFirstTimeCreation)
 
virtual void InitializeAfterLoadingAndSaving ()
 
virtual void BeforeClosing ()
 
void SetUnknownObjectTypes (const ezSet< ezString > &Types, ezUInt32 uiInstances)
 

Protected Attributes

ezUniquePtr< ezDocumentObjectManager > m_pObjectManager
 
ezUniquePtr< ezCommandHistory > m_pCommandHistory
 
ezUniquePtr< ezSelectionManager > m_pSelectionManager
 
ezUniquePtr< ezObjectCommandAccessor > m_pObjectAccessor
 Default object accessor used by every doc.
 
ezDocumentInfo * m_pDocumentInfo = nullptr
 
const ezDocumentTypeDescriptor * m_pTypeDescriptor = nullptr
 

Friends

class ezDocumentManager
 
class ezCommandHistory
 
class ezSaveDocumentTask
 
class ezAfterSaveDocumentTask
 

Document Management Functions

using AfterSaveCallback = ezDelegate< void(ezDocument *, ezStatus)>
 Callback type for asynchronous save operations.
 
ezStringView GetDocumentPath () const
 Returns the absolute path to the document.
 
ezStatus SaveDocument (bool bForce=false)
 Saves the document, if it is modified. If bForce is true, the document will be written, even if it is not considered modified.
 
ezTaskGroupID SaveDocumentAsync (AfterSaveCallback callback, bool bForce=false)
 Saves the document asynchronously. Calls the callback when done.
 
void DocumentRenamed (ezStringView sNewDocumentPath)
 Updates the document path after a rename operation.
 
ezStatus LoadDocument ()
 Loads the document from disk.
 
void EnsureVisible ()
 Brings the corresponding window to the front.
 
ezDocumentManager * GetDocumentManager () const
 Returns the document manager that owns this document.
 
bool HasWindowBeenRequested () const
 
const ezDocumentTypeDescriptor * GetDocumentTypeDescriptor () const
 
ezStringView GetDocumentTypeName () const
 Returns the document's type name. Same as GetDocumentTypeDescriptor()->m_sDocumentTypeName.
 
const ezDocumentInfo * GetDocumentInfo () const
 
virtual bool CanEngineProcessBeRestarted () const
 Asks the document whether a restart of the engine process is allowed at this time.
 
static ezStatus ReadDocument (ezStringView sDocumentPath, ezUniquePtr< ezAbstractObjectGraph > &ref_pHeader, ezUniquePtr< ezAbstractObjectGraph > &ref_pObjects, ezUniquePtr< ezAbstractObjectGraph > &ref_pTypes)
 Reads a document from disk and parses its header, objects, and types.
 
static ezStatus ReadAndRegisterTypes (const ezAbstractObjectGraph &types)
 Reads and registers types from the given object graph.
 

Main / Sub-Document Functions

ezDocument * m_pHostDocument = nullptr
 Pointer to the main document if this is a sub-document, otherwise self.
 
ezDocument * m_pActiveSubDocument = nullptr
 Pointer to the currently active sub-document.
 
bool IsMainDocument () const
 Returns whether this document is a main document, i.e. self contained.
 
bool IsSubDocument () const
 Returns whether this document is a sub-document, i.e. is part of another document.
 
const ezDocument * GetMainDocument () const
 In case this is a sub-document, returns the main document this belongs to. Otherwise 'this' is returned.
 
const ezDocument * GetActiveSubDocument () const
 At any given time, only the active sub-document can be edited. This returns the active sub-document which can also be this document itself. Changes to the active sub-document are generally triggered by ezDocumentObjectStructureEvent::Type::AfterReset.
 
ezDocument * GetMainDocument ()
 
ezDocument * GetActiveSubDocument ()
 

Prefab Functions

virtual bool ArePrefabsAllowed () const
 Whether the document allows to create prefabs in it. This may not be allowed for prefab documents themselves, to prevent nested prefabs.
 
virtual void UpdatePrefabs ()
 Updates ALL prefabs in the document with the latest changes. Merges the current prefab templates with the instances in the document.
 
void RevertPrefabs (ezArrayPtr< const ezDocumentObject * > selection)
 Resets the given objects to their template prefab state, if they have local modifications.
 
virtual void UnlinkPrefabs (ezArrayPtr< const ezDocumentObject * > selection)
 Removes the link between a prefab instance and its template, turning the instance into a regular object.
 
virtual ezStatus CreatePrefabDocumentFromSelection (ezStringView sFile, const ezRTTI *pRootType, ezDelegate< void(ezAbstractObjectNode *)> adjustGraphNodeCB={}, ezDelegate< void(ezDocumentObject *)> adjustNewNodesCB={}, ezDelegate< void(ezAbstractObjectGraph &graph, ezDynamicArray< ezAbstractObjectNode * > &graphRootNodes)> finalizeGraphCB={})
 Creates a prefab document from the current selection.
 
virtual ezStatus CreatePrefabDocument (ezStringView sFile, ezArrayPtr< const ezDocumentObject * > rootObjects, const ezUuid &invPrefabSeed, ezUuid &out_newDocumentGuid, ezDelegate< void(ezAbstractObjectNode *)> adjustGraphNodeCB={}, bool bKeepOpen=false, ezDelegate< void(ezAbstractObjectGraph &graph, ezDynamicArray< ezAbstractObjectNode * > &graphRootNodes)> finalizeGraphCB={})
 Creates a prefab document from the given root objects.
 
virtual ezUuid ReplaceByPrefab (const ezDocumentObject *pRootObject, ezStringView sPrefabFile, const ezUuid &prefabAsset, const ezUuid &prefabSeed, bool bEnginePrefab)
 Replaces the given object by a prefab instance. Returns new guid of replaced object.
 
virtual ezUuid RevertPrefab (const ezDocumentObject *pObject)
 Reverts the given object to its prefab state. Returns new guid of reverted object.
 
virtual void UpdatePrefabsRecursive (ezDocumentObject *pObject)
 Recursively updates all prefab instances starting from the given object.
 
virtual void UpdatePrefabObject (ezDocumentObject *pObject, const ezUuid &PrefabAsset, const ezUuid &PrefabSeed, ezStringView sBasePrefab)
 

Additional Inherited Members

- Static Public Member Functions inherited from ezNoBase
static const ezRTTI * GetStaticRTTI ()
 

Detailed Description

Base class for all editable documents in the editor. Handles state, object management, undo/redo, and more.

Member Function Documentation

◆ ArePrefabsAllowed()

virtual bool ezDocument::ArePrefabsAllowed ( ) const
inlinevirtual

Whether the document allows to create prefabs in it. This may not be allowed for prefab documents themselves, to prevent nested prefabs.

Reimplemented in ezSceneDocument.

◆ CanEngineProcessBeRestarted()

virtual bool ezDocument::CanEngineProcessBeRestarted ( ) const
inlinevirtual

Asks the document whether a restart of the engine process is allowed at this time.

Documents that are currently interacting with the engine process (active play-the-game mode) should return false. All others should return true. As long as any document returns false, automatic engine process reload is suppressed.

Reimplemented in ezSceneDocument.

◆ ComputeObjectTransformation()

ezResult ezDocument::ComputeObjectTransformation ( const ezDocumentObject *  pObject,
ezTransform &  out_result 
) const
virtual

Tries to compute the position and rotation for an object in the document. Returns EZ_SUCCESS if it was possible.

Reimplemented in ezGameObjectDocument, and ezParticleEffectAssetDocument.

◆ CopySelectedObjects()

virtual bool ezDocument::CopySelectedObjects ( ezAbstractObjectGraph &  out_objectGraph,
ezStringBuilder &  out_sMimeType 
) const
inlinevirtual

Creates the abstract graph of data to be copied and returns the mime type for the clipboard to identify the data.

Reimplemented in ezAnimationGraphAssetDocument, ezRenderPipelineAssetDocument, ezStateMachineAssetDocument, ezProcGenGraphAssetDocument, ezVisualScriptClassAssetDocument, ezMaterialAssetDocument, and ezSceneDocument.

◆ CreateDocumentInfo()

virtual ezDocumentInfo * ezDocument::CreateDocumentInfo ( )
protectedpure virtual

Creates the document info structure. Must be implemented by derived classes.

Implemented in ezAssetDocument, ezSimpleAssetDocument< PropertyType, BaseClass >, ezSimpleAssetDocument< ezAngelScriptAssetProperties >, ezSimpleAssetDocument< ezAnimatedMeshAssetProperties >, ezSimpleAssetDocument< ezAnimationClipAssetProperties >, ezSimpleAssetDocument< ezAnimationGraphAssetProperties >, ezSimpleAssetDocument< ezBlackboardTemplateAssetObject >, ezSimpleAssetDocument< ezCollectionAssetData >, ezSimpleAssetDocument< ezColorGradientAssetData >, ezSimpleAssetDocument< ezCurveGroupData >, ezSimpleAssetDocument< ezCustomDataAssetProperties >, ezSimpleAssetDocument< ezDecalAssetProperties >, ezSimpleAssetDocument< ezEditableSkeleton >, ezSimpleAssetDocument< ezImageDataAssetProperties >, ezSimpleAssetDocument< ezJoltCollisionMeshAssetProperties >, ezSimpleAssetDocument< ezKrautTreeAssetProperties >, ezSimpleAssetDocument< ezLUTAssetProperties >, ezSimpleAssetDocument< ezMaterialAssetProperties >, ezSimpleAssetDocument< ezMeshAssetProperties >, ezSimpleAssetDocument< ezMiniAudioSoundAssetProperties >, ezSimpleAssetDocument< ezParticleEffectDescriptor >, ezSimpleAssetDocument< ezPropertyAnimationTrackGroup, ezGameObjectContextDocument >, ezSimpleAssetDocument< ezRmlUiAssetProperties >, ezSimpleAssetDocument< ezSoundBankAssetProperties >, ezSimpleAssetDocument< ezSoundEventAssetProperties >, ezSimpleAssetDocument< ezSubstancePackageAssetProperties >, ezSimpleAssetDocument< ezSurfaceResourceDescriptor >, ezSimpleAssetDocument< ezTextureAssetProperties >, ezSimpleAssetDocument< ezTextureCubeAssetProperties >, and ezSimpleAssetDocument< ezVisualScriptClassAssetProperties >.

◆ CreatePrefabDocumentFromSelection()

ezStatus ezDocument::CreatePrefabDocumentFromSelection ( ezStringView  sFile,
const ezRTTI *  pRootType,
ezDelegate< void(ezAbstractObjectNode *)>  adjustGraphNodeCB = {},
ezDelegate< void(ezDocumentObject *)>  adjustNewNodesCB = {},
ezDelegate< void(ezAbstractObjectGraph &graph, ezDynamicArray< ezAbstractObjectNode * > &graphRootNodes)>  finalizeGraphCB = {} 
)
virtual

Creates a prefab document from the current selection.

Reimplemented in ezSceneDocument.

◆ GetEditorInputContextOverride()

virtual ezEditorInputContext * ezDocument::GetEditorInputContextOverride ( )
inlinevirtual

Allows to return a single input context that currently overrides all others (in priority).

Used to implement custom tools that need to have priority over selection and camera movement.

Reimplemented in ezGameObjectDocument.

◆ GetManipulatorSearchStrategy()

virtual ezManipulatorSearchStrategy ezDocument::GetManipulatorSearchStrategy ( ) const
inlinevirtual

Needed by ezManipulatorManager to know where to look for the manipulator attributes.

Override this function for document types that use manipulators. The ezManipulatorManager will assert that the document type doesn't return 'None' once it is in use.

Reimplemented in ezPropertyAnimAssetDocument, ezSkeletonAssetDocument, and ezSceneDocument.

◆ GetSupportedMimeTypesForPasting()

virtual void ezDocument::GetSupportedMimeTypesForPasting ( ezHybridArray< ezString, 4 > &  out_mimeTypes) const
inlinevirtual

Whether this document supports pasting the given mime format into it.

Reimplemented in ezAnimationGraphAssetDocument, ezMaterialAssetDocument, ezRenderPipelineAssetDocument, ezStateMachineAssetDocument, ezProcGenGraphAssetDocument, ezSceneDocument, and ezVisualScriptClassAssetDocument.

◆ InternalAfterSaveDocument()

virtual void ezDocument::InternalAfterSaveDocument ( )
inlineprotectedvirtual

Hook to execute additional code after successfully saving a document. E.g. manual asset transform can be done here.

Reimplemented in ezAssetDocument.

◆ InternalLoadDocument()

ezStatus ezDocument::InternalLoadDocument ( )
protectedvirtual

Internal load implementation. Loads the document from disk.

Reimplemented in ezSimpleAssetDocument< PropertyType, BaseClass >, ezSimpleAssetDocument< ezAngelScriptAssetProperties >, ezSimpleAssetDocument< ezAnimatedMeshAssetProperties >, ezSimpleAssetDocument< ezAnimationClipAssetProperties >, ezSimpleAssetDocument< ezAnimationGraphAssetProperties >, ezSimpleAssetDocument< ezBlackboardTemplateAssetObject >, ezSimpleAssetDocument< ezCollectionAssetData >, ezSimpleAssetDocument< ezColorGradientAssetData >, ezSimpleAssetDocument< ezCurveGroupData >, ezSimpleAssetDocument< ezCustomDataAssetProperties >, ezSimpleAssetDocument< ezDecalAssetProperties >, ezSimpleAssetDocument< ezEditableSkeleton >, ezSimpleAssetDocument< ezImageDataAssetProperties >, ezSimpleAssetDocument< ezJoltCollisionMeshAssetProperties >, ezSimpleAssetDocument< ezKrautTreeAssetProperties >, ezSimpleAssetDocument< ezLUTAssetProperties >, ezSimpleAssetDocument< ezMaterialAssetProperties >, ezSimpleAssetDocument< ezMeshAssetProperties >, ezSimpleAssetDocument< ezMiniAudioSoundAssetProperties >, ezSimpleAssetDocument< ezParticleEffectDescriptor >, ezSimpleAssetDocument< ezPropertyAnimationTrackGroup, ezGameObjectContextDocument >, ezSimpleAssetDocument< ezRmlUiAssetProperties >, ezSimpleAssetDocument< ezSoundBankAssetProperties >, ezSimpleAssetDocument< ezSoundEventAssetProperties >, ezSimpleAssetDocument< ezSubstancePackageAssetProperties >, ezSimpleAssetDocument< ezSurfaceResourceDescriptor >, ezSimpleAssetDocument< ezTextureAssetProperties >, ezSimpleAssetDocument< ezTextureCubeAssetProperties >, and ezSimpleAssetDocument< ezVisualScriptClassAssetProperties >.

◆ InternalSaveDocument()

ezTaskGroupID ezDocument::InternalSaveDocument ( AfterSaveCallback  callback)
protectedvirtual

Internal save implementation. Returns a task group ID for async save.

Reimplemented in ezAssetDocument, and ezScene2Document.

◆ OnInterDocumentMessage()

virtual void ezDocument::OnInterDocumentMessage ( ezReflectedClass *  pMessage,
ezDocument *  pSender 
)
inlinevirtual

Called on all documents when BroadcastInterDocumentMessage() is called.

Use the RTTI information to identify whether the message is of interest.

Reimplemented in ezSceneDocument.

◆ Paste()

virtual bool ezDocument::Paste ( const ezArrayPtr< PasteInfo > &  info,
const ezAbstractObjectGraph &  objectGraph,
bool  bAllowPickedPosition,
ezStringView  sMimeType 
)
inlinevirtual

Pastes objects from the given object graph into the document.

Reimplemented in ezAnimationGraphAssetDocument, ezMaterialAssetDocument, ezRenderPipelineAssetDocument, ezStateMachineAssetDocument, ezProcGenGraphAssetDocument, ezSceneDocument, and ezVisualScriptClassAssetDocument.

◆ ReplaceByPrefab()

ezUuid ezDocument::ReplaceByPrefab ( const ezDocumentObject *  pRootObject,
ezStringView  sPrefabFile,
const ezUuid &  prefabAsset,
const ezUuid &  prefabSeed,
bool  bEnginePrefab 
)
virtual

Replaces the given object by a prefab instance. Returns new guid of replaced object.

Reimplemented in ezSceneDocument.

◆ RevertPrefab()

ezUuid ezDocument::RevertPrefab ( const ezDocumentObject *  pObject)
virtual

Reverts the given object to its prefab state. Returns new guid of reverted object.

Reimplemented in ezSceneDocument.

◆ UnlinkPrefabs()

void ezDocument::UnlinkPrefabs ( ezArrayPtr< const ezDocumentObject * >  selection)
virtual

Removes the link between a prefab instance and its template, turning the instance into a regular object.

Reimplemented in ezSceneDocument.

◆ UpdatePrefabs()

void ezDocument::UpdatePrefabs ( )
virtual

Updates ALL prefabs in the document with the latest changes. Merges the current prefab templates with the instances in the document.

Reimplemented in ezSceneDocument.

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