-------------------------------
HOW TO MAKE VDK COMPONENTS THAT
CAN BE PLUGGED INTO VDKBUILDER
------------------------------

INTRODUCTION
------------
VDKBuilder comes with plugins capability.
Plugins are shared libraries that handle vdk components,
such components can be handled by vdkbuilder without recompile
it.

PLUGIN DATABASE
---------------
VDKbuilder mantain a database of plugin components into the file
<user home>/.vdkb/res/plugins.db.
Each file line contains a pair <lib_path,lib_name>. VDKBuilder at start
reads this file, load all shared libraries and checks them.
After that prepare the plugin database. User can browse and update
this database using "Components" on main menu.
In order to let VDKBuilder use plugins is necessary that shared libraries
are into a path known by the loader (i.e the path is pointed into
/etc/ld.so.conf) or that the environment variable LD_LIBRARY_PATH points
to the plugins path.
Usually plugins shared libraries should stay where vdk lib are even if
isn't strictly necessary.

MAKING COMPONENTS AND PLUGINS
-----------------------------
- To construct a component that can be used both with vdk and vdkbuilder
5 steps are necessary:

1. Write the code of the component on the vdk side
2. Make a component library, static or shared (preferred)
3. Write the code of the plugin on vdkbuilder side
4. Make a plugin shared library
5. Install component into vdkbuilder

STEPS NOTES
-----------
* Step 1 can be done wrapping some gtk widget or writing a
  component using vdk itself.

* Into vdkbuilder/plugins dir there are examples for all
  above steps:

  vdk component made wrapping a gtk+ widget
  -----------------------------------------
  vdkcalendar.cc and vdkcalendar.h show how to wrap gtk_calendar widget
  for the vdk library (step 1)

  vdk component made using vdk itself
  -----------------------------------
  vdkdclock.cc and vdkdclock.h show how to make a component using
  vdk only.
  VDKDigitalClock is a simple digital clock that displays time, date
  and have an alarm set/unset by the user.
  An "alarm_signal" is generated as well.

  vdkbuilder plugins
  ------------------
  - vdkb_calendar.cc and .h show how to write a vdk calendar plugin
  for vdkbuilder  (step 3)

  - databox.cc and databox.h are another example how to make a
    plugin using an already existing vdk component: VDKDataBox (step 3)

  - vdkb_dclock.cc and vdkb_dclock.h show how to write a VDKDigitalClock
    plugin for vdkbuilder  (step 3)

  autoconf/automake
  ----------------
  Autoconf/automake users can find an example of step5 into
  ./plugins/Makefile.am

* All sources are higly parameterized and heavily commented,
    user should be able to copy and paste those files and use
    them as footsteps.

* To explain above steps we will use calendar component and plugin.

STEP 1 : WRITING A  COMPONENT WRAPPING A GTK+ WIDGET
----------------------------------------------------
In order to have a plugin we must before have a valid vdk
component. We choose to wrap gtk_calendar since it does not
exist in vdk kernel neither in vdkcompo.
To correctly wrap a gtk widget we must write code mainly for
two sections:
- properties
- signal handling
This means that we choose wich properties and which signal will
be available for vdk users.
At this end we should read gtk+ source code and examples since gtk+
documentation still lacks or is not enough for our purposes.
In our case there is a good example how to use gtk_calendar into
gtk+-<version>/examples/calendar/gcalendar.c, also reading
gtk+-<version>/gtk/gtkcalendar.c and gtkcalendar.h are a necessary
step.
Carefully reading ./plugins/vdkcalendar.cc and ./plugins/vdkcalendar.h
should give a good idea how to wrap a gtk+ widget.

STEP 2: MAKING A COMPONENT SHARED LIBRARY
-----------------------------------------
Automake user should take advantage of ./plugins/Makefile.am.
Other users:
$ cd <where you wrote this>
$ g++ `vdk-config --cflags` -fPIC -c  vdkcalendar.cc
$ g++ -shared -Wl,-soname,libvdkcalendar.so \
   -o libvdkcalendar.so `vdk-config --libs` vdkcalendar.o
Once you have vdkcalendar.so install it into /usr/local/lib, or
wherever you keep your libraries, keep the loader
informed where shared lib is, either editing /etc/ld.so.conf
or setting LD_LIBRARY_PATH.

STEP 3: MAKING A PLUGIN FOR VDKBUILDER
--------------------------------------
Once we made a component, next step is to make a plugin
in order to let vdkbuilder manage the component.
Again vdkb_calendar.h and vdkb_calendar.cc are a good
footstep that users can paste and easily adapt to their
own components.
Plugin exports just a function:
- GetExportClass()
  This will be invoked by builder to have a valid interface
  with the plugin itself.

Other few functions are necessary to complete the plugin:
- WriteOnFrm()
  This writes widget definition into .frm file

- MakeWidget()
  This one make a new widget to be added to a container into
  vdkbuilder edit form

- CreateSource()
  This one actually write the source code

- CreateWidget()
  This one is similar to MakeWidget() but is called when
  vdkbuilder is reading a .frm file in order to construct a widget.

All this function are templatized with macro and should be easy
adapt them for others widget.

Other code should be written if the widget must have properties
handled by WI, refer to the above source code for further
informations.

STEP 4: MAKING A PLUGIN SHARED LIBRARY
-------------------------------------
Automake user should take advantage of ./plugins/Makefile.am.
Other users:
$ cd <where you wrote this>
$ g++ `vdk-config --cflags` -fPIC -c  vdkb_calendar.cc
$ g++ -shared -Wl,-soname,libvdkbcalendar.so \
   -o libvdkbcalendar.so `vdk-config --libs`\
   -L <where you wrote this> -lvdkcalendar\
   vdkbcalendar.o

Note that you must explicitely link plugin shared with
component shared otherwise vdkbuilder won't able to resolve symbols
contained into libvdkcalendar.so
Once you have vdkbcalendar.so install it into /usr/local/lib,
or wherever you keep your libraries, and make the loader
informed where shared libs are, either editing /etc/ld.so.conf
or setting LD_LIBRARY_PATH.

STEP 5: INSTALL COMPONENT INTO VDKBUILDER
-----------------------------------------
This step can be done from vdkbuilder, choosing
"Components" menu item and Component database browser.
Recall to make a /sbin/ldconfig after have installed
a new plugin. Restart vdkbuilder after that and new
plugin icon will appear on plugins palette.
An alternate way is to edit <user home>/.vdkb/res/plugins.db
adding a line with lib_path,lib_name pair.


FINAL NOTES
-----------
- Even if should be more simple make a single shared:
  component+plugin this is not possible since the stand-alone
  executable made by vdkbuilder would need builder libraries
  to work properly. So we can't avoid to have two separated shared
  libraries: one for component and one for plugin (dynamically
  linked with component lib).
- Into vdkbuilder-<version>/example/plugs there is an example how to use
plugins with vdkbuilder.
