1/****************************************************************************************
2
3 Copyright (C) 2015 Autodesk, Inc.
4 All rights reserved.
5
6 Use of this software is subject to the terms of the Autodesk license agreement
7 provided at the time of installation or download, or which otherwise accompanies
8 this software in either electronic or hard copy form.
9
10****************************************************************************************/
11
12//! \file fbxexternaldocreflistener.h
13#ifndef _FBXSDK_FILEIO_EXTERNAL_DOCREF_LISTENER_H_
14#define _FBXSDK_FILEIO_EXTERNAL_DOCREF_LISTENER_H_
15
16#include <fbxsdk/fbxsdk_def.h>
17
18#include <fbxsdk/core/fbxlistener.h>
19
20#include <fbxsdk/fbxsdk_nsbegin.h>
21
22/** Contains data about an external document.
23 * The document is a FbxDocument object.
24 */
25struct FBXSDK_DLL FbxExternalDocumentInfo
26{
27 FbxString mDocumentName; //!< Bare name of external document in document hierarchy.
28 FbxString mClassName; //!< Class name of the document (FbxDocument, FbxLibrary...).
29 FbxString mParentFullName; //!< Full name of the parent document in document hierarchy.
30 FbxString mFilePathUrl; //!< File path of the external document.
31};
32
33/** Event that is emitted on loading document when a referenced document
34 * is encountered while loading external references.
35 */
36class FBXSDK_DLL FbxEventReferencedDocument : public FbxEvent<FbxEventReferencedDocument>, public FbxExternalDocumentInfo
37{
38 FBXSDK_EVENT_DECLARE(FbxEventReferencedDocument);
39public:
40 FbxEventReferencedDocument() {}
41};
42
43
44class FbxExternalDocRefListenerData;
45
46/** Typical handler for the referenced document events.
47*
48* Register it like so:
49* FbxExternalDocRefListener lRefDocListener( sdkManager, fileName );
50* FbxEventHandler * lHandler = lRefDocListener.Bind(scene,
51* &FbxExternalDocRefListener::HandleEvent);
52*
53* And later unregister it like so:
54* lRefDocListener.Unbind(lHandler);
55*/
56class FBXSDK_DLL FbxExternalDocRefListener : public FbxListener
57{
58public:
59 /** Constructor.
60 * \param pManager
61 * \param pDocFilePath
62 * \remarks Keep a reference to the SDK and the path of the document
63 * to be able to resolve relative paths.
64 */
65 FbxExternalDocRefListener( FbxManager & pManager, const FbxString & pDocFilePath );
66 virtual ~FbxExternalDocRefListener();
67
68 /** Set the document file path used to resolve documents.
69 * \param pDocFilePath
70 * \remarks Allows re-using the same instance for multiple document loadings.
71 */
72 virtual void SetDocumentFilePath( const FbxString & pDocFilePath );
73
74 /** Verify that all documents that were previously loaded in a previous
75 * load session are still valid.
76 * \return \c true if all documents are still valid, \c false otherwise.
77 */
78 virtual bool AreAllExternalDocumentsStillValid() const;
79
80 //
81 /** Verify that all documents that were referred to didn't change.
82 * \return \c true if all documents didn't change, \c false otherwise.
83 * \remarks This function should be called if at posteriori check is desired.
84 */
85 virtual bool WereAllExternalDocumentsValid() const;
86
87 /** Unload all documents that were loaded through this event handler.
88 */
89 virtual void UnloadExternalDocuments();
90
91 // External document reference event handler.
92 //
93 // Operation: calls FindDocument() to find the specified external document
94 // and if not found calls LoadDocument() either directly,
95 // if it has not parent, or via ConnectToParentLibrary().
96 // If its parent cannot be found, it's added to the dangling
97 // document list (and it is not loaded until it's parent is found).
98 // After, it tries to resolve dangling documents by calling
99 // TryConnectingDanglingLibraries().
100 /** External document reference event handler.
101 * \param pEvent
102 * \remarks Operation: calls FindDocument() to find the specified external document
103 * and if not found calls LoadDocument() either directly,
104 * if it has not parent, or via ConnectToParentLibrary().
105 * If its parent cannot be found, it's added to the dangling
106 * document list (and it is not loaded until it's parent is found).
107 * After, it tries to resolve dangling documents by calling
108 * TryConnectingDanglingLibraries().
109 */
110 virtual void HandleEvent(const FbxEventReferencedDocument * pEvent);
111
112protected:
113 /**
114 * Turn a relative path to an absolute path using the file path of the original document being loaded.
115 * If the path is already is absolute, it is returned as is.
116 */
117 virtual FbxString MakeFilenameAbsolute(const FbxString & pFilename) const;
118 //! Locate a document by its document path.
119 virtual FbxDocument * FindDocument( const FbxString & pPathToDoc );
120 //! Load a library, potentially under another library.
121 virtual FbxDocument * LoadDocument(FbxObject * pParent, const FbxString & pClassName, const FbxString & pFilename);
122 //! Try to connect a library to its parent given its document path.
123 virtual bool ConnectToParentLibrary(const FbxExternalDocumentInfo &);
124 //! Try to reconnect dangling libraries that didn't find their parent.
125 virtual void TryConnectingDanglingLibraries();
126
127private:
128 FbxExternalDocRefListenerData * mData;
129};
130
131#include <fbxsdk/fbxsdk_nsend.h>
132
133#endif /* _FBXSDK_FILEIO_EXTERNAL_DOCREF_LISTENER_H_ */
134