4.3.1.6 Client Side

Now let's explain how to use all this mess from client side. First, we should be able to create objects that implement the interfaces we want. For this, you should use the scfCreateInstance() macro. It receives two arguments: the name of external class, and the name of the interface it implements. So, if we know class ‘MyGraphics3D’ implements the ‘iGraphics3D’ interface, we can write:

csRef<iGraphics3D> G3D = scfCreateInstance<iGraphics3D> ("MyGraphics3D");
if (!G3D)
{
  fprintf(stderr,
    "Failed to create an instance of iGraphics3D!\n");
  abort();
}

Now you can use the object any way you like, just like standard C++:

G3D->BeginDraw();
G3D->DrawLine(...);
G3D->DrawPolygon(...);
G3D->EndDraw();

When you are done using the ‘G3D’ pointer (say, when program exits), the reference you own for the object should be released. This happens automatically when the csRef<> goes out of scope. If you are not using csRef<>, but are instead using a plain pointer, ‘iGraphics3D*’, then you must manually release the reference when you are done with it by calling G3D->DecRef(). After this you can not use ‘G3D’ anymore; you should create another instance of ‘iGraphics3D’ if needed.

To query an object to see if it implements an interface, you should use the scfQueryInterface macro. It also receives two arguments, first being the object you are querying for the embedded interface, and second being the name of the interface you desire. Example:

csRef<iHalo> halo = scfQueryInterface<iHalo> (G3D);
if (!halo)
{
  fprintf(stderr,
    "3D graphic driver doesn't support halos!\n");
  return;
}

This document was generated using texi2html 1.76.