Please download and install the RichClient-Toolset first,
as usual from: http://www.thecommon.net/3.html

Even if you already have a working RichClient3-install
(a registered dhRichClient3.dll and dhCairo.dll) - 
these Demos here want to work against a dhCairo.dll with
a release-date >= 19.05.2010 - the release-version of this
ActiveX-dll is yet constant - at 1.0 - and will be left there
as long as Binary-compatibility is not yet switched on).

So, dhCairo.dll is (yet) work in progress - its COM-interfaces,
(mainly those who cover the Widget-Engine-part of dhCairo) are not
yet entirely settled - and therefore new releases of dhCairo.dll
will require always a re-registering of the "newest version"
which comes in the RichClient-toolset-package.

I hope to be able to change that behaviour soon (switching on
Binary-Compatibility on the COM-Interface of dhCairo) - but 
please wait for my "signaling" in this regard.

The Cairo-Drawing-Methods though, are already pretty mature and stable
and will not change in the future (meaning, the Drawing-Methods-Signatures
and their Parameters will remain constant, so that you from now on can 
rely on, that at least your *Drawing-Call-Code* will not break - in case 
you want to use the functionality of cCairo already in your own projects. 

Plain Cairo-Drawing (no Widgets anywhere) is done in the Demo-
Folders #1-#19 of this tutorial - so there's a lot of useful stuff,
which you already can start to "ripp-off" and integrate into your
own Applications. Please make your way through the Tutorial-steps
in increasing order - I've tried to cover most of the cairo-
functionality in "a chain", which seemed "right to me" with regards
to a "step-by-step-understanding" - but inform me, when you feel,
that I've lost you somewhere - I'm happy to include a new step
"#8 B" on request, if you find there's somewhere a too large "gap".
Please mail me directly under os@datenhaus.de, if you have such 
an request, maybe paired with some ideas already - but also feel
free, to post your own examples in case these could be useful
for other users when "officially included" here in the "main-tutorial"). 

So, a little bit more carefulness is required with regards to your
own Widget-Implementations in "real world projects" (and currently 
only Tutorial #20 is covering this part with examples). Here some more 
additions are yet to come - most important one - a new cTheme managerclass, 
which will ease your burden and the Code-Volume within your own Widgets 
by reusing the new "Default-Drawing-Routines" it will offer ... (as e.g. 
DrawButtonFace - or DrawDownArrow ... stuff like that).
Such a Theme-manager is also important, to be able to cover different
"Standard-Control-Visualizations" on the different Operating-Systems - 
rendered in a unified manner then, to give a consistent look and feel
at least within a new "widget-driven VB-App".

Nonetheless I want to encourage you, to play around with this stuff,
also with the Widgets - please try to implement simple ones, in case
you want to "be prepared" and help later on, to make this project a 
success in the VB-community - let's try to achieve something like a 
"revival" of the (already some years ago) - CCRP (Common-Conntrols-
Replacement-Project).

This time we should have good chances, to implement a well-working and
Unicode-capable set of "important Controls", completely independent
of the CommonControls-Runtime, having the same Vector-capabilities 
and "goodies" as .NETs WPF (which many .NETers will need to learn
in any case now too, since this is relative new stuff, pretty different
from their existing experience with the older .NET-WinForms-engine).

So, VB-Classic is on its way to "bleeding edge" again <g> (at least
with regards to modern drawing) - and the cairo-lib, whilst known, 
not to be  the "very fastest" among modern 2D-engines, has some
huge potential especially due to its flexibility and easy userinterface.
Just look into Demo #17 - how you can work with the very same Drawing-
Calls which you perform first against "Pixel-Surfaces" - but with a simple 
"Surface-Switch" you can also render a similar looking PDF-Document directly.

IMO that's the strength of cairo - the "multi-surface-support" - 
and with regards to performance you can expect much in the next months
from cairo too - on Linux a (reworked now) OpenGL-backend is already
doing pretty well - and for the Windows-Platform the FireFox-Developers
(which use cairo for their renderings too) have already a working binding
of the brand-new MS-Direct2D- and DirectWrite-backends up and running.
This will be officially released together with the new FireFox 4
(planned release date for that is the end of 2010) - 
and I will recompile the cairo2_engine.dll as soon as these new
backend-bindings for Windows are available. The nice thing is, that
you will not have to change anything in your Drawing-Calls - all 
the interfaces (those in the LGPL-licensed cairo2_engine.dll - and 
those in the COM-Wrapper (dhCairo.dll, which I'll open up under LGPL
soon) will remain the same - you will only notice a better performance 
(and conformance to the Win-OS) on the newer MS-OSes with Direct2D and 
DirectWrite-support (Vista over some Servicepack - and Win7 already 
by default).

So, have fun with the tutorial - (and I'm sure you will... <g>)
and let's find some "community-spirit" again over the next weeks
and months - there must be something like that, damn it...;-)


Olaf Schmidt,

in May, 2010