------------------------------- 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 /.vdkb/res/plugins.db. Each file line contains a pair . 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+-/examples/calendar/gcalendar.c, also reading gtk+-/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 $ 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 $ g++ `vdk-config --cflags` -fPIC -c vdkb_calendar.cc $ g++ -shared -Wl,-soname,libvdkbcalendar.so \ -o libvdkbcalendar.so `vdk-config --libs`\ -L -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 /.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-/example/plugs there is an example how to use plugins with vdkbuilder.