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 switches into your home directory,
if you want a different start up dir, use Tools -> Set Builder environment
under Tools menu, edit start up dir field and click on Start Up Dir button.
Closing environment dialog choose to save changes.

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

3. CREATING A NEW PROJECT

A modal files saving dialog entitled "New project" will be showed.
The left panel lists all home dirs.  
  Now another modal window will show you the project name that you choosed:

you should read:
/your-home/vdkb-examples/step1.prj

Tip: project types allowed:
-    VDK normal vdk gui application
-    console: a non gui application that runs on a xterminal or in text mode.
-    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 are the first files builder has made for you.

Tip: even step1.frm if is a plain-text files and is editable i do not suggest to patch it unless you
become familiar with Builder, the parser heavily uses this file 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 into screen.


 

You have done first step: creating a trivial and unuseless 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 Form Edit window will appear together with WI (Widget Inspector)
Widget Inspector is an important feature, it permits you to edit widget properties
and construct gui as well. It shows a widget tree, now the tree is almost empty
since it  contains just the form itself.


 

WI title changes to show which widget is, in this case it shows:
Inspector: Step1::step1, this means that Step1 main form is under inspecting. You will see that the main form title is changed now. now a modal dialog is presented warning you that your-home/vdkb-examples/step1.frm
is changed and need to be saved. Again builder maker makes his job and a new main form is running into screen with
a different title and a different size. 6. BROWSING SOURCE FILES now builder editor will pop up showing step1.cc file Now step1.cc is  syntax-coloured
(you have same result 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 for you.
Each form has two source files associated: one is step1.cc the other is step1_gui.cc.
The former is at your hand, builder will never touch it (unless few exceptions).
the latter is reserved for builder, is unuseful write on it since will be rewritten by
builder each time you make/run the app.
At this stage you can't see them all since is the first time you make step1.prj
  Watching on collapsed PM files tree 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 under builder responsibility. Editor will pop-up showing /your_home/vdkb-examples/step1_gui.cc
At this stage void Step1Form::GUISetup(void) is filled only with form size and title
but soon you will see that function grow sas you add widgets to 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 on builder maker these errors:
/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 complains about that offending line of code.

you will see that the editor bottom panel list is filled with those messages 9. FILLING WITH WIDGETS
Now you will add some widgets to the form.
First of all we have to put a container as first widget into form. A vertical box named Vbox1 will be added to the main form and WI will show you
that box under step1 node.
Tip: is necessary put a container as first widget since other widgets can be added only
to a container. and WI will show the 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 two widget share
equally the available space.
Agreed looks ugly, probably main form size is too big to accomodate just those two widgets. 10. EDITING WIDGET PROPERTIES
Note: during this step answers Ok if builder request to save changed files. You will see that Label0 caption is changed You will see Label0 caption center justified. You will see the LabelButton0 caption changed. Now we can see the effect of our changes into source code. You notice that 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.

Ok, we have quite written an "hello" app without writing a single line of code.

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

Available signals are displayed as a table of buttons and entry.
Each button caption is the signal you want connect and the entry the signal response method.
Response method names are by default constructed joining On+widget name+signal but if you
want you can change it. the below response table 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, 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 label button labeled "Quit" will terminate
step1 application.
  More detailed examples will come with TUTORIAL.step2
(I apologyze for my bad english, but that's the life, nobody is perfect !)