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.
-
Run builder from an Xterm:
$ vdkb&
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
-
Choose from File -> New... -> Project menu item
(or use
icon on toolbar)
A project wizard will appear:
-
Select vdkb-examples in your home dir using
the "dotted" button
-
Enter step1 into "Project name" field
-
Click on Ok button
-
answer Yes to the dialog that asks you if you want to create the step1
dir.
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.
-
your-home/vdkb-examples/step1/step1.cc, contains main program skeleton
-
your-home/vdkb-examples/step1/step1.h contains main program classes declaration
-
your-home/vdkb-examples/step1/step1.frm contains gui interface instructions
for 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
-
Choose Project ->Make menu item
VDKBuilder Maker will appear and begins compilation:
-
Click on Run icon on the main toolbar
again VDKBuilder Maker will appear and runs the program.
An empty, useless form entitled "step1 Main form" will appear
on screen.
-
Just click on the form's system menu and choose "close" or hit the
"X" button and application form will disappear.
-
close VDKBuilder Maker clicking on "Kill or Close" icon
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.
-
Select step1.frm from the PM (project manager)
-
Click on Edit icon on the PM toolbar (or double click selected step1.frm)
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.
-
first, select WI tree node labeled step1
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.
-
select the form title entry and type "VDKBuilder Tutorial step 1"
-
click on the button labeled Set form title
You will see that the main form title is now changed.
-
resize the main form to make it narrower.
-
click again on the Run icon on the builder toolbar
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.
-
click on Kill or Close icon on builder maker, this will shut down
the application
-
click again on Kill or Close icon on builder maker.
6. BROWSING SOURCE FILES
-
Select the PM node labeled: step1.cc and click the Edit icon on
PM toolbar
(or double click on the selected tree node)
now the Builder editor will pop up showing the step1.cc file
-
select editor page and press F6
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
-
now select from toolbar the Save project icon:

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.
-
double click on /your_home/vdkb-examples/step1_gui.cc
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.
-
Select step1.cc into editor and modify Setup() to read:
/*
main form setup
*/
void
Step1Form::Setup(void)
{
GUISetup(); // vdkb gui setup
// put your code below here
error here
}
Tip: notice that even if you do not intentionally
hilight the source this will be
coloured as soon as you begin to write something.
-
click on Run icon and answer Ok to saving step1.cc.
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
-
select the second error line named:
/root/vdkb-examples/step1.cc:42: `error' undeclared (first use this
function)
-
double-click on it and you will see that the editor jumps to and selects
the error line (or
better the line after).
-
correct the error cutting the offending line
Tip: you can correct the error by pressing
F4 (undo).
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.
-
Select edit form window
-
Select a vert. box from the Builder tool palette (under Containers page)
-
Point and click on the main form area
Tip: notice that cursor becames a cross-hair,
this means that you are into
dropping mode. We call the action of selecting
a widget from the tool palette
and placing that widget into a form or container
a "drop". At any time you can cancel
drop mode using the Reset icon on the tool
bar. Drop mode will automatically be
cancelled after the drop operation is completed.
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.
-
Select a label from the Builder tool palette (under "Text" page)
-
click over Vbox1, a label named "Label0" is added to Vbox1
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.
-
now select a LabelButton from the Builder tool palette (under Buttons labeled
page)
-
click on top of Label0 on the main form.
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.
-
Try to resize (shrinking) the main form to its miminum size, notice that
you can do
this until the two widgets reach their minimum size.
-
Click on run to see the effect
-
Close the step1 application and builder maker
10. EDITING WIDGET PROPERTIES
Note: during this step answer Ok if builder asks if you want to
save the changed files.
-
Select on form editing window Label0 widget
-
notice that WI has changed to reflect the selected widget
-
edit the Label0 Caption property to read: Hello world !
-
hit return key.
You will see that the Label0 caption is changed
-
select c_justify on the combo box and click on "Set justify"
You will see the Label0 caption center justified.
-
select LabelButton0 and edit the caption to read: Quit
-
click on "Set Caption" button
You will see the LabelButton0 caption changed.
-
again click on "Run" to see the effect
-
close the step1 application and builder maker
Now we can see the effect of our changes in the source code.
-
In the PM select the /your_home/vdkb-examples/step1_gui.cc node
and double click on it
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).
-
select LabelButton0 node on WI and switch to the "Signals" tab.
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.
-
click on clicked_signal button
the response table below that is filled with the signal connection arguments
-
select the table line "ON_SIGNAL(LabelButton0,clicked_signal,OnLabelButton0Click)
-
click on list column header labeled "Write or jump to response method"
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;
}
-
again click on Run to see the effect
You will notice that clicking on the button labeled "Quit" will terminate
the
step1 application.
-
close VDKbuilder and go get a sandwich.
More detailed examples will come with TUTORIAL.step2
(Grammar editing by Darel Finkbeiner, mythus@mailandnews.com)