Object Types

There are 3 types of ClanLib objects:

  • Handle Objects
  • Value Objects
  • GUI Components

Handle Objects

These classes contain a single std::shared_ptr that contains the object implementation. Copying such an object variable therefore doesn't create a copy of the actual object. Avoid using use the "new" keyword to create them.

Here are some examples on how to manipulate handle objects:

Sprite sprite; // API says this constructs a null instance of Sprite (no resources allocated) if ( sprite.is_null() ) { ... } // The is_null() function shows that it is a null instance Sprite sprite2(gc, "image.png"); // Construct the Sprite object sprite = sprite2; // Copy the handle. sprite and sprite2 refer to the same object sprite2 = Sprite(); // Assign sprite2 to a new object, in this case, a null instance. sprite.draw(gc, 100, 100); // Draw the sprite.

Some classes allow to clone the object state. Here sprite and sprite2 have different settings: (Note internally, the two Sprite objects still share the same image)

sprite = sprite2.clone(); sprite.set_scale(2.0f, 2.0f); sprite2.set_scale(4.0f, 4.0f);

Handle objects generally have a default constructor that creates a null instance (the std::shared_ptr points at null). There are a few exceptions to this rule, however.

Value Objects

These classes do not have a private implementation. They are copied by value as normal C++ objects:

Colorf color1(1.0f, 1.0f, 1.0f, 1.0f); // Set RGBA = 1.0f (white) Colorf color2 = color1; // Copy the object including the data color1.b = 0.0f; // Clear blue component

Color1 becomes yellow and color2 remains white.

GUI Components

The clanGUI GUIComponent class has a std::shared_ptr implemention, but cannot be copied. The copy constructor has been intentially disabled. Use the "new" keyword to create new GUI components.

They will be destroyed automatically by clanGUI when a parent component is destroyed, or when the clanGUI display window is destroyed.

They can be destroyed manually by using the "delete" keyword.

Object destruction order

ClanLib has been designed so that the destruction order of objects does not matter. This is internally implemented by using DisposableObject. For example:

Texture texture; DisplayWindow window("Hello World"); GraphicContext gc = window.get_gc(); texture = Texture(gc, "image.png");

The "window" object is destroyed before the "texture" object. Internally, the DisplayWindow destructor calls dispose on the texture object, to deallocate it's resources. When the Texture destructor is called the resource has already been disposed and does nothing.

Note: ClanLib 3.0 does this more cleanly than ClanLib 2.3. It should work in ClanLib 2.3, but avoid creating display objects in different threads.