Essentials

Overview of essential interfaces, classes, concepts, etc.

Fundamentals

Interface / Class	Notes
IUnknown	Basic interface to manage object lifetime and to obtain other interface pointers
Unknown	Reference-counted base class for implementing interfaces. Initial reference count is 1
Object	Object base class with RTTI, messages, storage
UID, UIDRef	16-Byte Globally Unique Identifier. Interface ID used with queryInterface Class ID used with ccl_new
AutoPtr	Smart pointer. Takes ownership on assignement of raw IUnknown/Object pointer
SharedPtr	Smart pointer. Similar to AutoPtr, calls addRef and release balanced
UnknownPtr	Smart pointer + queryInterface
Variant	Data type used to store different types of data. A Variant can contain various types of data, such as: Integers Floating-point numbers Strings Object references Boolean values (True/False)

Using IUnknown

Function / Interface	Notes / Examples
ccl_new	Create instance via Plug-in Manager AutoPtr<IProgressNotify> dialog; dialog = ccl_new<IProgressNotify> (CCL::ClassID::ProgressDialog);
ccl_release	Instances of ‘real’ plug-ins (dynamically loaded modules) must be released with ccl_release. This can be a little bit tricky, because ccl_release is not not supported by smart pointers.
isEqualUnknown	Test if interface pointers have the same implementation class instance bool isSame (ISubject* subject, IUnknown* unknown) { return isEqualUnknown (subject, unknown); } Pointers must not be compared directly !
Cast interfaces: UnknownPtr	Example for casting one interface to another void addObserver (IUnknown* unknown, IObserver* observer) { UnknownPtr<ISubject> subject (unknown); if(subject) subject->addObserver (observer); }

Define interface based on IUnknown

Only “public” data types are allowed as parameters and return types. The idea is that the code has the same binary output with any compiler on a platform.

Per value: fundamental data types:

• int, int64

• float, double

• tbool, tresult

• but no compiler dependent types like ‘bool’

• enum types are allowed if they specify an explicit underlying type, like enum Mode: int

Per reference or pointer:

• String, Variant

• struct (interface specific with no or inline methods)

• IUnknown and other interfaces but no implementation classes.

Macro	Notes	Example
DECLARE_IID, DEFINE_IID	Declare and define identifier of interface	interface INewInterface: IUnknown { // ... DECLARE_IID (INewInterface) }; DEFINE_IID (INewInterface, 0xc5d8ffd1, 0xd7cd, ...)
CCL_API	Calling convention needed for every interface method	virtual tresult CCL_API interfaceMethod () = 0;

Object Details

Macro / Function	Notes	Example
DECLARE_CLASS, DECLARE_CLASS_ABSTRACT	Header: Declare RTTI for Object (CCL::MetaClass)	class MyClass: public CCL::Object { public: DECLARE_CLASS (MyClass, Object) // ... };
DEFINE_CLASS, DEFINE_CLASS_HIDDEN, …	CPP: Define Meta Class	DEFINE_CLASS_HIDDEN (MyClass, Object) Hidden: Class is not added to the class registry.
CLASS_INTERFACE, CLASS_INTERFACE2 CLASS_INTERFACES	Define Interfaces in an implementation class	class MyClass: public CCL::Object, public CCL::IMyInterface { public: // ... CLASS_INTERFACE (IMyInterface, Object) // ... };
ccl_typeid	Template function to get the meta class of a class derived from Object	ccl_typeid<MyClass> ().getPersistentName ();

Casting

Case	Function	Example
Object to Object	ccl_cast + ccl_strict_cast	Url* asUrl (Object* obj) { return ccl_cast<Url> (obj); }
Interface to Object	unknown_cast	Object* getUrlObject (IUrl* url) { return unknown_cast<Object> (url); } Only works if the implementation of interface is in the same module
Object to interface	ccl_as_unknown	bool activateObject (Object* object, bool state) { if(IActivatable* act = ccl_as_unknown<IActivatable> (object)) { if(state) act->activate (); else act->deactivate (); } }

Container

Familiy	Class	Notes
Template Container	LinkedList	Double-linked list container class
	Vector	One-dimensional array that grows dynamically
Object Container	Container, Iterator	Abstract container base class and iterator
	ObjectList	Double-linked object list
	ObjectArray	Container class for array of objects
Interface Container	UnknownList, IUnknownList	List of IUnknown instances

Template Container

• + type-safe

• + can contain any data

• + reference counting can be added via smart pointers Vector <AutoPtr <Unknown> > UnknownVector;

• - storage not supported

• - no scripting access

Object Container

• + common abstract interfaces (Container, Iterator)

• + provide reference counting (but not in ‘remove’)

• + provide storage support

• - content type always unspecific (ccl_cast is needed)

• preferred for types derived from Object

• combine with iterate_as<> in range-for loop

• use when script access is needed

Interface Container

• use with interface at ABI boundaries (IUnknownList)

Strings

Classs	Related	Notes
String	StringChars StringWriter StringBuilder	Unicode string and utility classes.
MutableCString	CString	C-String, 8-Bit. CString is read only

Messages + Observer

Interface / Class	Related	Notes
Message	IMessage MessageRef	Has Identifier + Parameter. Most messages are specific to a class, but there a some common messages: kChanged kPropertyChanged kDestroyed (see remark below)
ISubject	Implemented in Object	A subject notifies observers about changes. Observers register with a subject
IObserver	Implemented in Object	Message receiver. Will be notified if one of its subjects sends a message.
ISignalHandler	System::GetSignalHandler	Central registry of ISubject/IObserver relations. Also implements deferred messages.
SignalSink	SignalSource	Process-wide signals. Categories and Message are defined in namespace Signals

• Message instances can be created direcly (no ccl_new needed)

• Object implements both ISubject (full) and IObserver (empty)

• kDestroyed is usually called inside of a destructor. isEqualUnknown or other methods that modify the reference count of an object must not used when this message is received

• Message can be delivered deferred. In this case the receiver must call cancelSignals in its destructor

  Example:

  DEFINE_STRINGID_MEMBER_ (MyClass, kOpenWindow, "openWindow")
  
  //////////////////////////////////////////////////////////////////////////////////
  
  MyClass::~MyClass
  {
    cancelSignals ();
  }
  
  //////////////////////////////////////////////////////////////////////////////////
  
  void MyClass::openWindow (bool deferred)
  {
    if(deferred)
      (NEW Message (kOpenWindow))->post (this, -1);
    else
    {
      // ...
    }
  }
  
  //////////////////////////////////////////////////////////////////////////////////
  
  void CCL_API MyClass::notify (ISubject* subject, MessageRef msg)
  {
    if(msg == kOpenWindow)
    {
      openWindow (false);
      return;
    }
  
    SuperClass::notify (subject, msg);
  }
  

File System

Interface / Class	Notes
FileType	Extension, MIME type, Description
Url, IUrl	Uniform Resource Locator
IFileSystem, INativeFileSystem	Singleton System::GetFileSystem
IStream	Access to open file. See also Streamer
File	Helper class

Object Persistence

Class / Method	Notes
Object::save Object::load	Overwrite in derived class to store values of members in Attributes. See also DEFINE_CLASS_PERSISTENT
Attributes	Nested map of string id and value
Archive	An archive reads/writes Attributes from/to streams. Archive is a base class. Most often used archive type is XML XmlArchive
Storage	Storage combines Archive and Attributes.
ArchiveHandler	Helper class to load/save objects from/to a structured storage (Zip-File). An Archive in this case reads/writes a sub-stream (file) of the structured file.

Miscellaneous

Interface / Class	Notes
Singleton	Singleton mix-in, destroyed automatically on exit class MyClass: public CCL::Object, public CCL::Singleton<MyClass> { void myMethod (); }; // ... MyClass::instance ().myMethod (); // ... Variants: ExternalSingleton SharedSingleton UnmanagedSingleton ComponentSingleton
NumericLimits	Namespace containing constants like kMaxInt
Primitives	Various utility functions, examples: ccl_min ccl_max ccl_abs ccl_bound
CCL_KERNEL_INIT, CCL_KERNEL_TERM	Initializers are called on application/module startup. The main purpose is to register something somewhere. Example: CCL_KERNEL_INIT (AudioEffect) { // register native .fxpreset handler (NEW AudioFXPresetHandler)->registerSelf (); return true; }
IProgressNotify	Used to report the progress of an operation

Parameter + Controller

Class / Method	Notes
IParameter	GUI data object representing a simple value that is displayed and modified by standard controls. Usually a IParameter is owned by a controller that handles changes.
IController	Implements the back-end logic for user interaction. It provides parameters and other objects used by GUI widgets. It can also be in the role of a model, or it can represent another data model
Component	Standard implementation of a Controller. Ready to use or base class for user defined components. Components are nested and can also create specific views.
ParamContainer	Manages parameters. Has methods to create and add standard and user defined parameter objects. Is a member ‘paramList’ of Component. But can also be used by itself.

Frequently Used

Most Frequently used system singletons

Interface	Function	Notes
INativeFileSystem	System::GetFileSystem	Get file system singleton
ISystemInformation	System::GetSystem	Get system information singleton
ISignalHandler	System::GetSignalHandler	Get signal handler singleton
IUserInterface	System::GetGUI	Get GUI Management singleton
IDesktop	System::GetDesktop	Get Desktop singleton
IWindowManager	System::GetWindowManager	Get Window Manager singleton
IPlugInManager	System::GetPlugInManager	Get plug-in manager singleton. Manages classes from all process modules (“Plug-ins”).

Most Frequently used components created with ccl_new

Class ID	Interfaces	Notes
CCL::ClassID::ProgressDialog	IProgressNotify, IProgressDialog, IProgressDetails	Creates a progress dialog
CCL::ClassID::FileSelector	IFileSelector	Creates a platform specific file selector dialog. Can be used to select files for open or save in the platform file system.
CCL::ClassID::FolderSelector	IFolderSelector	Creates a platform specific folder selector dialog. Can be used to let the user select a folder in the platform file system.
CCL::ClassID::PopupSelector	IPopupSelector	Create a popup window that allows to select one out of multiple items.