These are basic, “general purpose” interfaces that are defined and used throughout the DynObj library.
A compound object may implement several of these interfaces (can be implemented in C++ with multiple base classes).
h2. Interfaces
A DynObj interface is described with a C++ class in a header file. But, really the significant part of it is the virtual functions, their names and their signatures. Other parts of the class (enums, inline functions) are formally not part of the interface, but are convenient to have there none the less. (It is only the names and number of virtual functions, their ordering and signature that is fixed when an interface is tagged as public and stable.)
In the DynObj library, an interface type is suffixed with a capital letter I:
DynI, NotifierI, PathFileIIf the interface type really is not intended to derive from (more than one step), we can omit the I:
DynStr
h2. DynI derived interfaces
The member function names below are prefixed with do to reduce the chance of function name collision, when used in multi base class scenarios.
h4. DynI
The base class of the DynObj class hierarchy. A DynI object knows its own type, it can respond to queries for other types, it can store and report its error status.
| Base class | None | |
| File | dynobj/DynObj.h | |
| Methods | DynObjType* doGetType( const DynI ** pself=NULL ) | Returns its own DynObjType structure. |
| const char* doGetError( int* perr_code=NULL ) | Return current error message | |
| void doClearError( ) | Clear object error message |
h4. DynObj
A DynObj class adds the ability to be created and destroyed compared to DynI. A DynObj derived class should not be destroyed with a C++ delete statemennt, one should use the member function doDestroy() instead (in a system with mutiple memory allocators, doDestroy() will use the right one).
| Base class | DynI | |
| File | dynobj/DynObj.h | |
| Methods | void doDestroy( ) | Destroys the object. |
| void doDtor( ) | Run the destructor on the object, without freing memory. (Currently not used). |
h4. DynSharedI
The object is the base class for objects with shared ownership (ref counted).
| Base class | DynObj | |
| File | dynobj/DynObj.h | |
| Methods | int doAddRef( ) | Increment owership count. |
| int doRelease( ) | Decrement ownership count and destroy object if reaching 0. |
h4. DynStr
This is the interface to a feature rich, Unicode string class that can be used over plugin boundaries.
DynStr has many inline helper functions:
Internally, it store the strings in UTF8 encoding, but it can also be used to hold arbitrary 8 bit strings, if we avoid stepping through such data with UTF8 iterators.
| Base class | DynObj | |
| File | dynobj/DynStr.h | |
| Methods | DynStr& AssignA( const char* s, int len=-1 ) | Assigns an 8 bit string. |
| DynStr& AssignW( const wchar_t* s, int len=-1 ) | Assigns an wide string (doing necessary conversion). | |
| int Strcmp( const char* s ) | Compare with input string. | |
| int Stricmp( const char* s ) | Compare with input string, case insensitive, according to Unicode properties. | |
| … | and many more methods, see DynStr.h |
h4. DynArr<T>
This is an array interface, providing growable arrays that can be used over plugin boundaries. From the C++ perspective, it’s a template class. From a binary perspective, there are distinct specializations for these types:
| Base class | DynObj | |
| File | dynobj/DynArr.hpp | |
| Methods | ArrBase<T,int>& GetArrBase( ) | Returns read-only array object. |
| T& ElemRef( int ix ) | Returns reference to an element. | |
| DynArr<T>& Push( T t ) | Pushes (appends) an element. | |
| T Pop( ) | Pops an element off the end. | |
| T& Top( ) | Returns an element to the tail element. | |
| … | and many more methods, see DynArr.hpp. |
h4. NamedRefI
This is an associative array class where named objects of type DynI are stored:
@ const char* => DynI* @In addition, each object added to the collection must be safely trackable. That means:
So, the objects references held by an instance of NamedRefI are always safe.
NamedRefI can many times be used where a global namespace would be used when linking statically.
Also, an object may implement NamedRefI and allow itself to be extended with references to other objects at run-time.
| Base class | DynObj | |
| File | dynobj/NamedRefI.h | |
| Methods | DynI* GetByName( const char* name, int type_id=0 ) | Lookup an instance by name. |
| DynI* GetByIndex( int index, DynStr &ds, int type_id=0 ) | Lookup an instance by index (allows enumerating objects). | |
| bool docall Set( const char* name, DynI* pdi ) | Add/set a named object. | |
| bool docall Remove( DynI* pdi ) | Remove an instance. |
The ready-to-use C++ class NamedRef implements thisinterface and can be quickly added as an additional base class for a type. Then it has its very own dynamic namespace.
h2. Free (raw) interfaces
h4. NotifierI
This interface is implemented by objects that can hold a list of subscribers to its messages. NotifierI represent objects that emit notifications.
Objects that implement NotifierI are trackable, they must emit a NOT_EVT_DESTRUCTOR notfication when they are destroyed. That enables holding safe object references to them.
Notifier is a C++ class that implements NotifierI and can be added to the base class list, providing a trackable object.
| Base class | no base | |
| File | utils/NotfiableI.hpp | |
| Methods | bool AddNotifiable( NotifiableI* pnot, int evt) | Add a subscriber to event evt. |
| bool RemoveNotifiable(NotifiableI* pnot, int evt) | Remove a sbscriber to event evt. | |
| bool RemoveNotifiable(NotifiableI* pnot, int evt) | Remove a sbscriber to event evt. | |
| int Notify(int evt, NotDataI* pnd) | Send a notification event evt with data pnd to all subscribers. |
h4. NotifiableI
This interface is is the receiver of notifications sent by NotifierI. So, a compound object wanting to receive notifications must implement this interface.
A C++ smart pointer for plugin objects (such as DynObjHolder) can use this interface to track objects.
| Base class | no base | |
| File | utils/NotfiableI.hpp | |
| Methods | bool OnNotify( NotifierI* src, int evt, NotDataI* pnd=NULL ) | Receive a notification of type evt with optional data pnd. |
h4. StateI
This is an interface to ojects which have a state they can store and load from an char string (UTF8 encoding expected).
| Base class | no base | |
| Methods | bool GetState( DynStr &ds ) | Get/retrieve the object state. |
| bool SetState( const char* state ) | Set the object state. |
h4. PathI
This interface can be implemented by any object that has the concept of a current path.
A directory browser or a command shell are obvious candidates, but also an editor may respond by returning the directory where the current document is located.
| Base class | no base | |
| Methods | bool piGetPath( DynStr& ds ) | Get/retrieve the current path. |
| bool piSetPath( const char* path ) | Set the current path. |
h4. PathFileI
This interface extends the one above by adding the concept of a current file. A directory browser can return the focused file and an editor the name of the current document.
Setting the filename, an editor can switch to, or open a new document with this name.
| Base class | PathFileI | |
| Methods | bool piGetFileName( DynStr& ds ) | Get/retrieve the current file. |
| bool piSetFileName( const char* path ) | Set the current file. |