VDKBuilder Tutorial
STEP 1
Return to Index

1. PREPARING AN EXAMPLE DIR
Prepare a dir vdkb-examples into you $HOME dir:
$ mkdir vdkb-examples

2. RUNNING BUILDER

Tip : Builder will automatically switch into your home directory,
if you want a different start up dir, use Tools -> Set Builder environment
under the Tools menu, edit the start up dir field and click on Start Up Dir button.
Closing the environment dialog will save the changes.

Tip: vdkb international language support isn't yet completed, however
you can have some of it by using one of the following:
$ vdkb -it& (italian version)
$ vdkb -de& (german version)

3. CREATING A NEW PROJECT

A project wizard will appear:
  Tip: project types allowed:
-    VDK normal vdk gui application
-    console: a non gui application that runs on an xterminal or in the console.
-    shared: a shared library (not yet implemented)
-    static: a static library (not yet implemented)

Now the project manager will show the project files tree:

These files have been automatically produced by Builder.

Tip: step1.frm is a plain-text files and is editable but I do not suggest you patch it unless you
are very familiar with Builder, the parser uses this file heavily and is not  error resistant.

4. FIRST RUN

VDKBuilder Maker will appear and begins compilation:


 
 

again VDKBuilder Maker will appear and runs the program.
An empty, useless form entitled "step1 Main form"  will appear on screen.


 

You have finished the first step: creating a trivial and useless gui application
without writing a single  line of code.

5. ENTITLING AND RESIZING MAIN FORM

Now we will put a title on main form.

Now the Form Edit window will appear together with WI (Widget Inspector).
Widget Inspector is an important feature that lets you edit widget properties
and construct the gui as well. It shows a widget tree. At the momentthe tree is
almost empty since it only contains the form itself.


 

The WI title changes to show which widget is being edited, in this case it shows:
Inspector: Step1::step1, this means that Step1 main form is the current widget. You will see that the main form title is now changed. now a modal dialog is presented warning you that your-home/vdkb-examples/step1.frm
is changed and needs to be saved. Again builder maker builds the project and a new main form is running on screen with
a different title and a different size. 6. BROWSING SOURCE FILES now the Builder editor will pop up showing the step1.cc file Now step1.cc is now syntax-colored
(you get same results right clicking and selecting  Syntax Higlight on pop-menu.)
You can see what Builder wrote for you, a skeleton application.
Notice :
void Step1Form::Setup(void) method.
This in turn calls GUISetup() that is the function that Builder takes care of for you.
Each form has two source files associated: one is step1.cc the other is step1_gui.cc.
The former is left in your hands, Builder will never touch it (with a few exceptions).
the latter is reserved for Builder,  which shouldn't be edited by hand since it will be
rewritten by the Builder each time you make/run the app.
At this stage you can't see them all since this is the first time you made step1.prj
  Keep an eye on the collapsed PM files tree and you will see that under
/your_home/vdkb-examples/step1.frm
node there are two other nodes:
/your_home/vdkb-examples/step1_gui.cc
/your_home/vdkb-examples/step1_gui.h
those are gui related files that are updated by Builder. The Editor will pop-up showing /your_home/vdkb-examples/step1_gui.cc
At this stage void Step1Form::GUISetup(void) contains only the form size and title
but soon you will see that function grow sas you add widgets to your form.

So we learned that Step1Form::Setup(void) calls Step1Form::GUISetup(void).
If you want change something in interface setup do not patch GUISetup(), write
in Setup() after GUISetup() as remark suggests.

7. SHOWING UNDO AND JUMP TO ERROR CAPABILITY
Now we simulate a code error in order to see how compiler outputs are integrated into
builder.

Tip: notice that even if you do not intentionally hilight the source this will be
coloured as soon as you begin to write something.
  Now you'll see the following errors from Builder:
/your_home/vdkb-examples/step1.cc: In method `void Step1Form::Setup()':
/your_home/vdkb-examples/step1.cc:42: `error' undeclared (first use this function)
/your_home/vdkb-examples/step1.cc:42: (Each undeclared identifier is reported only once
/your_home/vdkb-examples/step1.cc:42: for each function it appears in.)
/your_home/vdkb-examples/step1.cc:42: parse error before `}'
make: *** [/your_home/vdkb-examples/step1.o] Error 1

obviously your compiler is complaining about that offending line of code.
You will see that the panel at the bottom of the editor lists those messages

9. FILLING WITH WIDGETS
Now you will add some widgets to the form.
First of all we have to put a container onto the form to hold the other widgets. A vertical box named Vbox1 will be added to the main form and WI will show you
that box under the step1 node.
Tip: It is necessary to put a container as your first widget since it will "contain" the other
widgets you need/want. and WI will reflect this situation:
Step1 form contains Vbox1 that contains Label0. You notice that Label0
will expand to occupy all available space, that's normal. you will see that a button named LabelButton0 is added to Vbox1 and WI
will show the change. Now VBox1 contains LabelButton0 as well.
And you will notice that the powerful gtk layout capability makes the two widget share
the available space equally.
Of course this looks ugly, because the main form is too large. 10. EDITING WIDGET PROPERTIES
Note: during this step answer Ok if builder asks if you want to save the changed files. You will see that the Label0 caption is changed You will see the Label0 caption center justified. You will see the LabelButton0 caption changed. Now we can see the effect of our changes in the source code. You notice that the editor will pop-up showing /your_home/vdkb-examples/step1_gui.cc
source code. Notice that GUISetup() is now changed, both Label0 and LabelButton0 have
been added with their properties.

So now we have written a "hello" app without writing a single line of code.

11. CONNECTING SIGNALS
In this step we connect the "click" signal on LabelButton0 with a response method
(or callback in gtk+ language).
 

Available signals are displayed as a table of buttons and entry fields.
Each button caption is the signal you want connect and the entry is the signal response method.
Response method names are constructed by joining On+widget name+signal but if you
want you can change it. the response table below that is filled with the signal connection arguments You will see that editor will pop up showing the response function definiton into step1.cc:
Tip: this is the only case that builder will touch your step1.cc, adding a response function.
Builder will never cancel this function, it is your job to do this if necessary.
// signal response method
bool
Step1Form::OnLabelButton0Click(VDKObject* sender)
{
return true;
} // signal response method
bool
Step1Form::OnLabelButton0Click(VDKObject* sender)
{
Close();
return true;
} You will notice that clicking on the button labeled "Quit" will terminate the
step1 application.
  More detailed examples will come with TUTORIAL.step2
(Grammar editing by Darel Finkbeiner, mythus@mailandnews.com)