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.

- Click on Ok.

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;
}

- change the code to read:

// 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 builder maker

- close VDKbuilder and go get a sandwich.

More detailed examples will come with TUTORIAL.step2
(Grammar editing by Darel Finkbeiner, mythus@mailandnews.com)