Professional Documents
Culture Documents
Gambas 3
Building GUI
Applications
version 0.0.1 Pre-release 1
Main Author:
Willy Raets (The Netherlands)
<willy@development.earthshipbelgium.be>
Version:
0.0.1 Pre-release 1 (2013-09-29)
Contributing author:
-
Illustrations:
Sholzy (United Stated), Illustrations 173
Willy Raets (The Netherlands), Illustrations 1-172, 174-178
Proofreaders:
Alain J. Baudrez (Belgium)
Ammar Ali Kurd (Yemen)
Jim Cook (United States)
Netizen1993 (United States)
Instruction and example testing
Alain J. Baudrez (Belgium)
Ammar Ali Kurd (Yemen)
Jim Cook (United States)
Netizen1993 (United States)
Advisors:
Alain J. Baudrez (Belgium)
Ian Roper (Australia)
How to Gambas 3 – Building GUI Applications (this work) is licensed by Willy J.L. Raets under the Creative
Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License
In short meaning that everyone can share and read this work for free, as is. Commercial use is not al-
lowed, neither is changing the work. You need to attribute in the manner required by the licensor (see
below). Check the full license text for a detailed explanation. For conditions of use prohibited by this
license, contact the licensor.
THIS WORK IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL"
OR "LICENSE"). THIS WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE
OF THIS WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIB-
ITED.
UNLESS OTHERWISE MUTUALLY AGREED BY THE PARTIES IN WRITING, LICENSOR OFFERS THIS WORK
AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THIS WORK, EX-
PRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE,
MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF
LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR
NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES,
SO SUCH EXCLUSION MAY NOT APPLY TO YOU.
For full license text visit: http://creativecommons.org/licenses/by-nc-nd/3.0/legalcode
Attribution is required as follows:
'How to Gambas 3 – Building GUI Applications' by Willy Raets (http://howtogambas.org)
Table of Contents
4 INTRODUCTION..........................................................................................................5
4.1 WHAT IS GAMBAS?................................................................................................................5
Willy Raets,
Main author,
May 2012
A special thanks to all the contributors on the White Island Software and GambasForum, for their
help in improving this guide and of course all developers of Gambas for their effort spent on creat-
ing the powerful Basic language, named Gambas.
This guide is dedicated to an old friend, Jos (a.k.a. Yellowmoor), to help him get started with Gam-
bas programming.
I would like to dedicated the 'How To Gambas 3'-series to my three sons Nicky, Luca and Nino.
1
Meanwhile Gambas has been introduced at my job and is being used there as well. The environ-
ment has gone from Windows only to a mixed Windows/Linux one.(added September 23th, 2013)
1
2. Foreword
2 Foreword
This guide is the second in the series 'How To Gambas 3'. The guide is aimed at people new
to Gambas and programming and discusses the building of simple standalone GUI applica-
tions.
This pre-release 1 is a first public release of a still unfinished guide. Fact that it isn't finished
yet, doesn't mean it can't prove useful to people new to programming in Gambas.
The guide will learn you the basics of making new GUI projects in the Gambas IDE. Drawing
controls on forms, learn to code their events and run the program.
It will explain terminology common to programming and Gambas in specific. You will learn
about user interaction, input and output of data, handling text-based and numeric data, local-
isation, the basics of loading and saving data to files and of handling images in your applica-
tion. Besides that Gambas syntax and useful string, arithmetical and other functions are ex-
plained and demonstrated.
All is learned in a step by step approach explaining each and every new detail, accompanied
by code, screenshots2 and hands on practice in using the Gambas IDE, typing code, compil-
ing and running code and see things work (or fail).
Often examples are approached in a manner that let's you stumble upon problems that
gradually get solved. This will slowly get you acquainted with detecting problems , different
manners of solving the same problem and a broader insight in the Gambas language in gen-
eral.
At the end of pre-release 1 you should be capable of building very basic GUI applications,
handling text and numbers, save and load files and images, working with menus and toolbars
and have a basic understanding of concepts like Public, Private, methods, functions, objects,
controls and such.
In the chapters still in development, things like printing data, drawing on a DrawArea, more
complex saving and loading of data, form classes, modules, the Gambas IDE and it's possibil-
ities, folder structures of projects, Gambas components and their function and maybe even
more will be explained.
For now enjoy pre-release 1,
Willy Raets,
September 28th, 2013
Practical note: When you copy/paste code from the code boxes into the Gambas IDE you
might get errors running the code. To prevent this from happening simply copy/paste the code
into a plain text editor first and next copy/paste from the text editor into the Gambas IDE and
you won't have this trouble.
Better practice is to simply type the code directly into the Gambas IDE as this will get you fa-
miliar with typing code in the editor and working with the auto-help feature, during typing.
2
All screenshots are made on Linux Mint 13 – Mate 1.4 with English language installed using
Gambas 3.4.2, except otherwise mentioned. Screenshots might look different on your distribu-
tion and with your localisation settings.
2
3. Before you get started
'Sample code
'
Public Sub Form_Open()
Me.Center
Me.Caption = “Sample application”
End
The Gambas code that you need to write in the examples will be placed in a white box.
Good practice will make for more effective maintenance of your system or applications.
3.4 Terminal
If you would ever need to run a command in a terminal window it will be placed in a black box.
This means you will need to open a terminal interface like Gnome terminal, LX terminal or
whatever application lets you go to the command line interface on your distribution.
3
Code will most likely work as well in Gambas 3.1.x or higher, although this was not tested.
Just give it a try if that is your situation, since nothing I know of has changed in the
syntax and use of the core Gambas components discussed and used in this guide.
3
3. Before you get started
uname -a
3.5 Warning
If it would ever be needed to get your attention to matters that are of great importance they
will be placed in a red box.
4
4. Introduction
4 Introduction
Gambas provides you with the tools for RAD (Rapid Application Development) through use of
the IDE. This makes GUI application design, debugging and packaging for distribution easy
and by Gambas supporting OOP (see below in yellow), a concept that makes reuse of parts
already built possible, saving time, energy, and reducing errors. No need to do things over
and over again.
4
http://gambas.sourceforge.net
5
5. Some good practices
6
5. Some good practices
1. Application documentation
This folder is used to place documentation files made to accompany applications I distribute.
2. Gambas3-ArchivedApps
Archived applications can be any application I haven't looked at for a long time. I never trow
them away, but relocate them to this folder. They can sometimes still be useful just to remem-
ber how you done something in those days, or as a base for an entire new application.
3. Gambas3-GameZone
The folder I store my Gambas game projects
4. Gambas3-Projects
The folder I use for all my distributed application projects. Each project will get his own folder
named after the project. This will be done when creating a new project in the Gambas IDE.
5. Gambas3-SourceOthers
In this folder I unpack project source code from other developers they shared. I can then
open them as normal projects in the Gambas IDE. It could be for purpose of checking out
code, testing the application or help solving an error. When not useful they get deleted instead
of archived.
6. Gambas3-TestZone
This folder is for making a quick project for testing something, or for trying out things or for
replicating a question asked on a forum to see if I can come up with a solution. They are no
serious projects, but exactly what the folder says, test zone applications. They often get de-
leted instead or archived.
7. Gambas3-Tools
The folder I use for applications (libraries) I develop for use in my distributed projects, or for
tools I use myself.
You can make more or less folders to categorise and organise your projects on your system.
You can add new folders later and replace projects. For the projects you will be making in this
guide you could make a 'Gambas3-LearningZone' folder to put them in. All that is up to you.
1. Archived folder
The 'Archived' folder contains distribution packages of applications no longer maintained.
2. Website folder
7
5. Some good practices
8
5. Some good practices
9
5. Some good practices
The other thing is that, if you built your applications open source, it makes the code more
readable to those looking at it.
10
5. Some good practices
11
5. Some good practices
Names of variables that suggest what their content will be, are easier to comprehend and re-
member when reading or writing many lines of code.
In one of my applications I try to extract the window manger used on the system. An easy
name for that could be WinMan.
The name tells us that the information on window manger retrieved on the system will be
stored in the variable named WinMan.
2. Begin the name with a lower case letter identifying the type of content it represents
Going back to the previous example of the window manager being stored in a variable named
WinMan it is best make some minor adjustment to the name to identify the type of content.
The content that will be extracted from the system will contain text, so in Gambas it's type is
String. Now to indicate that the variable WinMan will contain data of the type String I named it
sWinMan.
By putting a lower case 's' in front of 'WinMan' I identify the variable as being a string contain-
ing window manager information.
In the course of this guide and all the examples you will get more examples on how you could
use this to your benefit.
12
5. Some good practices
In the examples provided in this guide you will get to see more examples of indenting as I use
it in all my coding.
13
6. A first GUI application: TextPlay
5
See 'How To Gambas 3 – Installing Gambas'
14
6. A first GUI application: TextPlay
Now click on New Project... to make a new project. In the 'New project' screen you select the
type of application you wish to build.
Select Graphical application as that is what you are going to build, a GUI application.
No further options need to be selected.
15
6. A first GUI application: TextPlay
16
6. A first GUI application: TextPlay
In the 'New project' screen step 3 you can name both the folder where the project will be loc-
ated and the name the actual application will have. They can be different if you like.
17
6. A first GUI application: TextPlay
After clicking OK the Gambas 3 IDE opens with a new empty project named TextPlay.
You have just created a new project in Gambas for building a first GUI application.
Each project opened in IDE has 4 major zones:
➢ Zone 1: Menu and toolbar zone
➢ Zone 2: Project browser
➢ Zone 3: Working area
➢ Zone 4: Debug area
They will gradually make more sense when working with the examples that will be built in this
guide.
9
Note the small black arrow in the project browser in front of the FMain icon. That arrow in-
dicates that this form is the first one to run, after starting the application
18
6. A first GUI application: TextPlay
Just double click Fmain and the empty form will be in the Working area (zone 3)
In the 'Working area' (zone 3) you see an empty form and at the right of it a box with 'Proper-
ties/Hierarchy'.
Underneath the 'Properties/Hierarchy' you will find a ToolBox to build the controls.
The ' Properties/Hierarchy' is only visible when forms are in the 'Working Area'. If code is
viewed in the 'Working Area' there will be no ' Properties/Hierarchy' box nor Toolbox.
19
6. A first GUI application: TextPlay
Click on the Label icon and next drag a rectangle on the form.
20
6. A first GUI application: TextPlay
Click on the TextBox icon and next drag a rectangle on the form.
Click on the Button icon and drag two rectangles on the form.
21
6. A first GUI application: TextPlay
You are about to change some of them and see what they do.
Note that when you selected Label1 in the 'Properties/Hierarchy' Box it says 'Label1 Label'
(Label1 is the name of the control and Label is the type of control).
In the box below you can find Help on Label (gb.gui).
First click on the 'Alignment' property on Normal and a selection box will appear. Select
Right.
22
6. A first GUI application: TextPlay
Next go to the 'Text' property and click on Label1 and type Enter your name:
You will see the typed text appear in your label on your form. Your label is now ready for use
in the application.
Label controls are usually used in combination with an input control. The Label is used to make
clear what the input control is for and should contain.
For example a Label could show 'Name', followed by an input control like a TextBox where the
user can type his/her name.
This doesn't mean you can use Labels otherwise.
Next lets focus on the other controls by means of exercise. Here is what needs to be done:
➢ Select TextBox1 and empty the Text property.
➢ Select Button1 and change the Text property to 'Show'.
➢ Select Button2 and change the Text property to 'Clear'.
23
6. A first GUI application: TextPlay
1. User input:
- Type name
- Click on Button Show
- Click on Button Clear
2. Application output:
- Message with name
- Clear a TextBox
In the user input you can see some events (or things that can happen to an object). Text be-
ing entered by the user in a TextBox and clicking on buttons. So these are events where you
need to write your code.
In the application output you see what needs to happen, so what you need to code.
Now for the text being entered nothing realy needs to be coded as things happen when click-
ing the buttons. Clicking the Show button needs to show you a message box with the entered
text. Clicking the Clear button needs to clear the entered text.
10
A "creatable" object is an object that can be instantiated by itself.
24
6. A first GUI application: TextPlay
This will open the FMain.Class in a new tab in the 'Working Area'.
25
6. A first GUI application: TextPlay
Message(TextBox1.Text)
End
The object named TextBox1 holds the text entered by the user in the property Text. To get
there you write TextBox1.Text11.
The method Message() displays a String value in a message box.
Next double click FMain in the project browser (or click tab FMain.form) to go back to the
form. Right click button Clear and select Event → Click.
Write this code for Public Sub Button2_Click():
TextBox1.Text = “”
End
The = “” (2 times double quote) sets an empty string value (or Null value) to the
TextBox1.Text property. Strings are anything in between double quotes. Note that copying the
code with quotes into IDE will generate errors. You need to type the quotes in IDE.
11
You will notice when tying code in Gambas IDE you will get some help along the way. Like
when typing the name of a control followed with a dot you will see all methods, functions,
constants and properties of that control.
26
6. A first GUI application: TextPlay
Now lets see if the application does what you want it to do.
Enter your name in the TextBox and click Show. A message with the entered name will ap-
pear. Click OK to close the message.
Me.Center
End
Me refers to Fmain. Center is the method that will center FMain.
12
Another option is to simply double click the form to go to Form_Open()
27
6. A first GUI application: TextPlay
You will also need to add a test to the Click event for button Show to act one way or the other
depending on the result of the test. What needs testing is if text has been entered into Text-
Box1.
So you need to check the property Text if it is empty or not.
Change the code for Public Sub Button1_Click() to:
End
IsNull(TextBox1.Text) will test if TextBox1.Text is empty13 and return True if it is. If true a mes-
sage will tell you to first fill in a name. If false the name will be shown, but a bit more nicer this
time. Note: If IsNull(TextBox1) Then is the same as: If IsNull(TextBox1.Text) = True Then.
IsNull() is a datatype function of type Boolean, meaning it will be true or false. Depending on
the expression tested.
IsNull(expression)
Returns True if expression is NULL.
NULL means:
- The NULL constant
- A null object reference
- A zero length string
- A null date
- An uninitialized variant
More on IsNull() see http://gambasdoc.org/help/lang/isnull?ja&v3
If expression Then..Else..Endif
Behind If you need a test (expression) that returns a Boolean (True/False)
The code for Then is run when test returns true.
The code for Else is run when test returns false.
Endif ends the code block.
You can use logic operators (like And and Or) in the expression to test for more than one
condition.
More on If see http://gambasdoc.org/help/lang/if?v3
Message() needs to contain string values. Text between quotes is considered string as is the
content of a Text property. To connect them together to one string you use &.
Next it is time to test. Press F5 and next click the button Show.
13
A TextBox with a space entered by the user might look empty but actually isn't as it is not
equal to Null (it contains a space and thus as string looks like “ “ and has a length of 1
instead of looking like this “” with a length of 0).
28
6. A first GUI application: TextPlay
As you can see the application is now centred on the screen. Clicking Show results in a mes-
sage to first fill in a name.
Now click OK enter a name and click Show again.
You see this results in a nicer result than in the first round of testing. Congratulations, you
have just build a first GUI application in Gambas 3.
Now close the project in menu File → Quit. This will also close Gambas and set you at the
point to start for the next chapter.
29
7. Extending application TextPlay
The project TextPlay should be in the list somewhere on top if recently opened14. Click on
TextPlay to open in IDE.
14
Or it could be the only application in there if TextPlay is your first Gambas 3 application.
30
7. Extending application TextPlay
Your pointer will change appearance and you will be able to drag the form wider. So drag the
form a bit wider.
Next click the Label, hold down ctrl key and click the TextBox.
31
7. Extending application TextPlay
This will select both of them and you will be able to drag them a bit to the left, as there is still
some room left over.
Next select button Show, hold ctrl key and select button Clear. Drag them to the bottom of
the form.
32
7. Extending application TextPlay
Now drag the newly pasted controls below the ones already there.
Next select one of the buttons, copy/paste it and drag it to the bottom-left of the form.
33
7. Extending application TextPlay
When copy/pasting controls their name will always be a copy of the name of the original control
with an added number. The number will be one higher than the previous one.
Example:
If you copy/paste Label1, the copy will be named Label2. If you next copy/paste either Label1
or Label2 the next copy will be named Label3
Select the Text property for Label1 and type Enter your first name:
Next select TextBox1. Change the Name property to tbxFirstName. Next select TextBox2
and change the name property to tbxName.
34
7. Extending application TextPlay
In case I do not use the name of a control on a form in code I will keep the original name given
to the control when first drawn on the form (or copied onto the form).
In case I am going to use the name of the control in code, I like to have a name that makes
some sense. Two things are important to me:
1. I would like to know the type of control
2. I would like to get an idea what the control is for
For this I have developed my own system, based on the naming of variables according to type
(see 5.3.2 Clear choices for names). I use three lower case letter to identify the type of control,
next a Capital letter followed by lower case identifying the purpose of the control.
Some examples:
TextBox1 → tbxFirstName
Button1 → btnShow
Label3 → lblResult
TextArea1 → txaResult
CheckBox1 → cbxShow1
RadioButton1 → rbnYes
You will get to see more of this as the guide continues.
If all changes are met have a look at the FMain.class. Click the tab Fmain or in the project
browser right click FMain and select Edit code
35
7. Extending application TextPlay
Now two more things are left to do and they make for a great exercise as well:
- Add a Label (below tbxName) to the form, name it lblResult
- Add a TextBox (below lblResult) to the form, name it tbxResult and set ReadOnly to True
- Add a TextArea (below tbxResult) to the form, name it txaResult and set ReadOnly to True
- Empty the Text property of lblResult and txaResult
36
7. Extending application TextPlay
End
Dim (short for Dimension) is to declare local variables and their types. In Gambas you always
need to declare your variables before you can use them in your code.
The & is used to add different strings together to one string. In this case the string in tbxFirst-
Name.Text followed by a space (“ “) and the string in tbxName.Text. The space is to separate
the first name from the name.
Now run the project type in your first name and name and click Add to see what happens.
Now click Clear and see what happens. As it seems only the first name gets cleared. It would
be nice if not only first name gets cleared but name and the results as well.
37
7. Extending application TextPlay
Next click in the first name box and press Tab key a few times. The order of how Tab jumps
from one control to the other can be determined by you.
So here is two points for change.
Note the difference in how the result is shown in lblResult, txbResult and txaResult.
Also note that the lblResult, tbxResult and txaResult are not editable, meaning you can't
change the content. For tbxResult and txaResult you needed to set property ReadOnly to
True. Labels don't have a ReadOnly property as they are default read only.
You can select a control in the Hierarchy Box and move it up or down, changing the order it
will be selected.
The only fields that need to be 'Tabbed' are FirstName, Name and the three buttons. So move
them up in the hierarchy. Label1 and Label2 are of no importance so move them down.
38
7. Extending application TextPlay
Next click on the Properties Tab and select Label1, Label2, lblResult, tbxResult and txaResult.
In the properties scroll to the property NoTabFocus and set this to True
'tbxFirstName.Text = “”
tbxFirstName.Text = Null
tbxName.Text = Null
lblResult.Text = Null
tbxResult.Text = Null
txaResult.Clear
End
The ' before tbxFirstName.Text = “” makes the line a comment. So it will not be executed.
Here you just try another manner of clearing the content using Null.
When replacing a piece of code with new code a good practice is to comment the old code
rather than deleting it. Next write the new code below the commented code.
If the new code turns out to be problematic or buggy, you can delete the new code and remove
the comments from the old one, rather than having to code it all over again.
If the new code turns out a success you could consider removing the old (commented) code.
The txaResult could be cleared using txaResult.Text = Null but I wanted to show you another
way of clearing content. Just play around with the different options and see what works and
what doesn't if you want to learn some more.
One more feature would be nice to add. When clicking Add if one of the name boxes is empty
you should be told that it is empty and set the focus on that box.
For this you will need to adapt the code for the btnAdd.
Change the code for Public Sub btnAdd_Click() to:
39
7. Extending application TextPlay
End
First you test if tbxFirstName is empty. If so a message will be displayed and focus will be set
to First Name box (tbxFirstName.SetFocus → SetFocus is a method that gives focus to the
control).
If tbxFirstname is not empty you test if tbxName is empty. If so a message is displayed and
focus is set to the Name box.
If tbxName is not empty the result will be shown.
As you can see you can use an If..Then..Else in another If..Then..Else.. Indenting will make
clear where each block of the If..Then..Else.. is resided.
Now it is time to run the application.
First click on Add without entering names. See what happens.
Next enter a name for First Name and click Add and see what happens.
40
7. Extending application TextPlay
Next enter a name for Name and click Add and see what happens.
Next click the Clear button and see what happens.
If all is well the code should be working as supposed to.
Next run the application and click on the three CheckBoxes, then click on the three RadioBut-
tons and note the difference.
Where all three CheckBoxes can be selected only one RadioButton can at any given time.
Keep that in mind.
Now back to form design.
41
7. Extending application TextPlay
What you require is when 1 Line is selected clicking the button Add shows the information in 1
Line. When 2 Lines is selected clicking the button Add shows the information in two lines.
But that is not all. First name will only be added if cbxFirstName is selected, Name will only
be added if cbxName is selected.
Next you need to code Add button to incooperate the new requirements.
When a CheckBox is selected its value is set to -1, if it is deselected its value is set to 0.
When a RadioButton is selected its value is set to True, if not selected it is set to False.
So this is what you need to to be able to test what needs to be done.
Lets take it step by step. First you code for the RadioButtons to work.
Change the code for Public Sub btnAdd_Click() to:
End
As you can see only rbtLine1 gets tested. As there are only two RadioButtons one of them will
always be selected. So if rbtLine1 is not selected rbtLine2 is.
Run and see if this first part of code does the job. Just see what happens and pay special at-
tention to the different result outputs when 2 Lines is selected.
42
7. Extending application TextPlay
As you can see in the illustration above a TextBox can not hold two lines off text. Both Label
and TextArea can. The strange character in the TextBox is the line feed shown (“\n”).
Next lets add the code for the CheckBoxes and remove the TextBox as it is of no use any
longer.
Back to Form design:
- Remove tbxResult
- Check Fmain.class code if tbxResult is used and remove if needed.
Again a nice exercise. And if you might forget to remove tbxResult from code some where,
don't worry, IDE will tell you once you try running the application. Just so you know.
Next change the code for Public Sub btnAdd_Click() to:
43
7. Extending application TextPlay
End
iSwitch is set to -1 every time one of the name boxes needs to be filled in and gets the focus.
In such a case nothing further needs to be tested or shown.
44
7. Extending application TextPlay
Now back to running the project. If you get errors you probably forgot to remove tbxResult
somewhere in the code. Fix it.
Type a first name and a name and select only first name to add. Next click Add and see what
happens.
Now select name to add and deselect first name. Click Add and see what happens.
Now select both and click Add to see what happens.
45
7. Extending application TextPlay
First let's focus on code to make tarResult show proper text when clicking btnAdd.
For this you will need to add some code to the btnAdd_Click routine.
46
7. Extending application TextPlay
'
'Test if first name needs to be added before checking if field is empty
If cbxFirstName.Value = -1 Then
If IsNull(tbxFirstName.Text) Then
Message(“Fill in first name”)
tbxFirstName.SetFocus
iSwitch = -1
Else
iSwitch = 1
Endif
Endif
'
'Test if Name needs to be added before checking if field is empty
If iSwitch <> - 1 Then
If cbxName.Value = -1 Then
If IsNull(tbxName.Text) Then
Message(“Fill in name”)
tbxName.SetFocus
iSwitch = -1
Else
If iSwitch = 1 Then
iSwitch = 12
Else
iSwitch = 2
Endif
Endif
Endif
Endif
'--------- ADDED CODE ------
'Test if Country needs to be added before checking if field is empty
If iSwitch <> - 1 Then
If cbxCountry.Value = -1 Then
If IsNull(tbxCountry.Text) Then
Message(“Fill in a country”)
tbxCountry.SetFocus
iSwitch = -1
Else
If iSwitch = 1 Then
iSwitch = 13
Else
If iSwitch = 2 Then
iSwitch = 23
Else
If iSwitch = 12 Then
iSwitch = 123
Else
iSwitch = 3
Endif
Endif
Endif
Endif
Endif
Endif
'---------- END ADDED CODE ------
47
7. Extending application TextPlay
'
'Check iSwitch what needs to be done
If iSwitch <> -1 Then
Select iSwitch
Case 1 'Show first name
sResult = tbxFirstName.Text
Case 2 'Show name
sResult = tbxName.Text
Case 12 'Show first name and name
rbtLine1.Value Then 'Check for 1 line
sResult = tbxFirstName.Text & “ “ & tbxName.Text
Else
sResult = tbxFirstName.Text & “\n“ & tbxName.Text '\n generates a new line
Endif
'----------- ADDED CODE ------------------
Case 3 'Show country
sResult = tbxCountry.Text
Case 13 'Show first name and country
If rbtLine1.Value Then 'Check for 1 line
sResult = tbxFirstName.Text & “ “ & tbxCountry.Text
Else
sResult = tbxFirstName.Text & “\n“ & tbxCountry.Text
Endif
Case 23 'Show name and country
If rbtLine1.Value Then 'Check for 1 line
sResult = tbxName.Text & “ “ & tbxCountry.Text
Else
sResult = tbxName.Text & “\n“ & tbxCountry.Text
Endif
Case 123 'Show first name, name and country
If rbtLine1.Value Then 'Check for 1 line
sResult = tbxFirstName.Text & “ “ & tbxName.Text & “ “ & tbxCountry.Text
Else
If rbtLine2.Value Then 'Check for 2 lines
sResult = tbxFirstName.Text & “ “ & tbxName.Text & “\n “ & tbxCountry.Text
Else
sResult = txbFirstName.Text & “\n“ & txbName.Text & “\n “ & txbCountry.Text
Endif
Endif
'----------- END ADDED CODE ------------------
End Select
lblResult.Text = sResult
txaResult.Text = sResult
Endif
End
48
7. Extending application TextPlay
'tbxFirstName.Text = “”
tbxFirstName.Text = Null
tbxName.Text = Null
'– ADDED CODE --
tbxCountry.Text = Null
'-- To clear the checkboxes
cbxFirstName.Value = 0
cbxName.Value = 0
cbxCountry.Value = 0
'– END ADDED CODE --
lblResult.Text = Null
tbxResult.Text = Null
txaResult.Clear
End
Time to test the application. Hit F5 to run the application. Fill in some values and check if
everything works as expected.
Also try using the button Clear to see if everything clears up well.
Everything should work just fine, if not check your code to see if you haven't made a mistake
somewhere.
Now let's focus on the last requirement: you want to be able to determine what to Show when
clicking button Show. Outcome could be either first name, name or country.
With current controls on the form there is no way to determine what to show when clicking
button Show. You will need some extra RadioButtons to get that job done.
Add three RadioButtons behind the three CheckBoxes. Next run the application and select
one of them. What happens and why? Try answering this for yourself before reading further.
49
7. Extending application TextPlay
You will probably have noticed that when clicking on one of the newly added RadioButtons
the RadioButton selected at lines group gets deselected.
Remember page 41: “Where all three CheckBoxes can be selected only one RadioButton can
at any given time. Keep that in mind.”
All RadioButtons act like this when being in the same container. And for a RadioButton that
makes sense as you only want one to be selected.
In this case your form is the container of the placed RadioButtons and since all the RadioBut-
tons are in the same container only one can be selected.
So what you need is a separate container to hold your newly added RadioButtons.
First rename the RadioButtons to rbtShow1, rbtShow2 and rbtShow3. Next select them and
do ctrl+x (or right click and select cut in menu).
50
7. Extending application TextPlay
Now with the frame selected do ctrl+v (or right click and select paste in menu)
Now run the application again and see what happens. You should be able to click the Show
RadioButtons independently from the one for lines.
Containers
Containers make it easy to manage controls that belong together. If you drag the frame over
the form all controls within the frame will be dragged along as they are in the container.
When for example you need certain controls visible under certain conditions, place them in one
container. Next you can make them visible or invisible just by setting the Visible property of the
container, instead of setting the Visible property of each individual control.
A Frame is a container with edges borders and a label.
More on Frame see http://gambasdoc.org/help/comp/gb.qt4/frame?v3
Back to design place the Line RadioButtons in their own frame as well. Name the Frame
fraLines with Text Lines
51
7. Extending application TextPlay
Consider it good practice to always place RadioButtons in their own container. In time you will
find out this has his advantages
When completed your result should look something like the illustration below.
Now let's recode the btnShow event click to meet our requirements (code see next page).
Now run and test the result. If all is well it should work.
52
7. Extending application TextPlay
If rbtShow1.Value Then
If IsNull(tbxFirstName.Text) Then
Message(“First fill in a first name”)
Else
Message(“The name entered is “ & tbxFirstName.Text)
Endif
Else
If rbtShow2.Value Then
If IsNull( tbxName.Text) Then
Message(“First fill in a name”)
Else
Message(“The name entered is “ & tbxName.Text)
Endif
Else
If IsNull( tbxCountry.Text) Then
Message(“First fill in a country”)
Else
Message(“The name entered is “ & tbxCountry.Text)
Endif
Endif
Endif
End
7.5 A last review of the application
In this last part of this chapter you are going to review your application and see if it can be
simplified and made more friendly in use.
53
7. Extending application TextPlay
54
7. Extending application TextPlay
If IsNull(tbxFirstName.Text) Then
Message(“First fill in a first name”)
Else
Message(“The first name entered is “ & tbxFirstName.Text)
Endif
End
End
55
7. Extending application TextPlay
End
Code, run and test is all that is left.
Me.Center
btnAdd.Enabled = False
End
Code to enable disable button Add when clicking cbxFirstName, cbxName or cbxCountry:
As you will notice in code below, you can run code from one routine (being
cbxFirstName_Click) from another routine (being cbxName_Click and cbxCountry_Click).
56
7. Extending application TextPlay
End
'– Since code for other checkboxes is same use cbxFirstName_Click routine to do the job --
cbxFirstName_Click
End
cbxFirstName_Click
End
You will get to see more of this further in the guide. For now just knowing that it is possible will
do.
Me.Center
btnAdd.Enabled = False
btnClear.Enabled = False
End
57
7. Extending application TextPlay
….
…..
Endif
'– Add this line at the end of the routine
btnClear.Enabled = True
End
….
…..
tarResult.Clear
'– Add this at the end of the routine
'– You need to set the focus to another control before disabling btnClear as it has the focus
btnAdd.SetFocus
btnClear.Enabled = False
End
Since btnClear has the focus when being clicked and you can't disable a control that has the
focus you need to set the focus to another control before disabling btnClear.
You will notice that upon clicking clear, the Adds are deselected by code resulting in the Add
button being disabled as well. In this example that is just perfect.
You probably didn't expect that to happen, but you did code for it. But it is a good demonstra-
tion of event driven programming. One event can trigger a next event, that can trigger a next
event. So keep your mind to it not to end up with unwanted side effects coming from parts of
could you would never look for.
Now close the project in menu File → Quit. This will also close Gambas and set you at the
point to start for the next chapter.
58
8. Your second application: TextPlayT(w)o
59
8. Your second application: TextPlayT(w)o
60
8. Your second application: TextPlayT(w)o
Me.Center
End
Step 1: Focus on splitting the text
What you need to accomplish is split entered text in the TextArea (txaContent) into the Text-
Boxes (tbxLine1 to tbxLine4). For that you need to know on what character to split.
Example:
txaContent.Text → “split this text on space”
tbxSplit.Text → “ “ (a space)
Pressing Split should result in:
tbxLine1.Text → “split”
tbxLine2.Text → “this”
tbxLine3.Text → “text”
tbxLine4.Text → “on”
So input is the text entered in txaContent and the character entered in tbxSplit. The splitting
needs to take place when btnSplit is clicked.
For splitting strings you can use the function Split().
61
8. Your second application: TextPlayT(w)o
Case 3
tbxLine3.Text = sText
Case 4
tbxLine4.Text = sText
End Select
iX = iX + 1
Next
End
It runs as expected, but try again with some other text in txaContent en Split on “\n” (line
feed).
Run the application and:
1. in txaContent type:
This is Line 1
Next line aka as line 2
62
8. Your second application: TextPlayT(w)o
Now this makes sense as “ Separators are the characters used to split the text” So Split will
check for both “\” and “n” to split and that is exactly what happened.
Step 2: Improve splitting the text
What you want is it to split on a line feed (“\n”) instead. So you need to code the btnSplit
event to recognize the “\n” and act accordingly. For this you need to add an extra “\”15.
So back to IDE for some recoding:
15
The extra “\” makes sure the following “\” is preserved.
63
8. Your second application: TextPlayT(w)o
Case 4
tbxLine4.Text = sText
End Select
iX = iX + 1
Next
End
64
8. Your second application: TextPlayT(w)o
End
Now check if it works by running the application
65
8. Your second application: TextPlayT(w)o
You will notice that when showing 4 lines and next trying 2 lines that lines 3 and 4 are still
filled. The reason behind this is that the tbxLine variables aren't cleared before a new split.
Step 2: Recode to make tbxLine variables clear
To do this you need to code the btnSplit event again:
End
tbxLine1.Clear
tbxLine2.Clear
tbxLine3.Clear
tbxLine4.Cear
End
As you can see in the code above the code for clearing the lines is taken into a separate
routine (Public Sub ClearLines()). This separate routine is a subroutine (indicated by the Sub).
It is a Private routine (indicated by Private).
The fact that the routine is a subroutine and Private means that it can be called anywhere
within the same class it resides to be executed.
The class subroutine ClearLines() resides in the form class of FrmMain (the tab in IDE named
FrmMain.Class). So anywhere in the code of FrmMain you can use subrourine ClearLines().
66
8. Your second application: TextPlayT(w)o
You call the routine simply by its name to be executed (in our code you simply write
ClearLines).
Upon execution the interpreter after executing the line 'iNumSplits = vbxSplit.Value' will run
the subroutine ClearLines and execute it line by line before continuing with the execution of
'Select tbxSplit.Text'
Private
Keyword that declares accessibility of a method (sub/procedure or function), variable or
property
A Private declared method, variable or property can NOT be used outside its own class.
More on Private see http://gambasdoc.org/help/lang/private?v3
Public
Keyword that declares accessibility of a method (sub/procedure or function), variable or
property
A Public declared method, variable or property can be used outside its own class.
More on Private see http://gambasdoc.org/help/lang/public?v3
Now run the application again and first let it split showing 4 lines
Next split again for 1 line and see if lines 2 to 4 are cleared (see illustration on next page).
67
8. Your second application: TextPlayT(w)o
Illustration 69: Next a split for 1 line (other lines are now cleared)
68
8. Your second application: TextPlayT(w)o
69
8. Your second application: TextPlayT(w)o
Now add some initial code to the form open event (right click the form and select menu Event
→ Open)
Me.Caption = “Search”
End
This will give the FrmSearchReplace the caption “Search”. As you notice FrmSearchReplace
is not centered, FrmMain is. Idea is that FrmSearchReplace gets opened when clicking the
btnSearch in FrmMain. To make sure that FrmSearchReplace is not in front of txaContent,
you leave all default, meaning in top left of your screen
FrmSearchReplace.Show
End
What you do here is call the method Show of FrmSearchReplace. So you tell the FrmSear-
chReplace to show itself.
Forms inherit the Window class which means properties, methods and events are inherited
from the window class every time a form is made.
Forms
The Form class inherits the Window class. This means that properties, methods (routines) and
events of the Windows class (parent class to the form class) are inherited from the window
class every time a form is made.
This also means that you can use these in your forms.
Sub Show()
Shows the window
More on Forms see http://gambasdoc.org/help/comp/gb.qt4/form?v3
More on Show see http://gambasdoc.org/help/comp/gb.qt4/window/show?v3
Now run the application and click the btnSearch.
You should see something like the illustration on the next page. Notice the window caption of
FrmSearchReplace stating Search.
70
8. Your second application: TextPlayT(w)o
Seems you now have an application consisting of two forms. And from within one form you
can open the other.
Now the real challenge is to enter a search string in the FrmSearchReplace and search for
the string in txaContent on FrmMain.
This will require some interaction between the two forms and brings us to a next level.
71
8. Your second application: TextPlayT(w)o
btnSplit_Click()
btnSearch_Click
Private in FrmMain are:
Methods
ClearLines()
So Public means available to other forms, Private means NOT available to other forms.
Let's give this a go in the IDE. Double click FrmSearchReplace in the Project Browser.
Now double click btnSearch. This will open a btnSearch_Click() method in the FrmSeachRe-
place.class (= all the code for the form).
Write the following code to the btnSeach click event:
FrmMain.btnSplit_Click
End
Next run the application.
In txaContent type: To be or not
In tbxSplit type: “ “ (a space)
In vbxSplit type: 4
Next click btnSearch to open FrmSearchReplace. In FrmSearchReplace click btnSearch and
see what happens in FrmMain.
What actually happened upon clicking btnSearch on the Search form is that code from anoth-
er form class got called by the current form Class and executed before returning.
So you can directly call Public methods from another class to be executed.
Indirectly the Private method ClearLines got called as well. With this difference that it was
called from a method (btnSplit_Click()) within its own class.
72
8. Your second application: TextPlayT(w)o
73
8. Your second application: TextPlayT(w)o
Message(StringToSearch)
End
StringToSearch is a string value that gets passed to the method upon calling it.
In FrmSearchReplace class write following code:
FrmMain.SearchString(tbxSearch.Text)
End
Now run the application, click btnSearch on FrmMain, write your name in the search field and
click btnSearch. You should see your name appear in a message box.
So the Text property of tbxSearch (although not being Public) is passed to another class as
an argument (StringToSearch) to be used in a Public method in that other class.
So passing arguments is one way of passing Private data to another Class. Keep that in
mind!
I hope this makes clear how passing arguments works. Now that you have seen it working
you know the search string can reach method SearchString in FrmMain all you need to do is
code for it to be found.
74
8. Your second application: TextPlayT(w)o
End
75
8. Your second application: TextPlayT(w)o
76
8. Your second application: TextPlayT(w)o
With the frame for choosing between Search and Search/Replace enabled and FrmSear-
chReplace prepared for Replacing you are set for the next step.
Me.Center
rbtSearch.Value = True
rbtSearch_Click
End
You use Public to declare a variable SearchReplace to pass a value to FrmSearchReplace to
determine whether to search or to search and replace.
rbtSearch is set to True so it is the default selection upon opening FrmMain. Next you ex-
ecute the rbtSearch click event. This is the next step you need to code.
Clicking on one of the RadioButtons has to set SearchReplace to value 1 or 2, that is all.
77
8. Your second application: TextPlayT(w)o
Datatypes
Datatypes determine the type of data a variable can contain when declared. The datatype also
determines the length of the space used by the data.
Gambas native datatypes are:
Type Description Default value
Boolean True or False False
Byte 0 to 255 0
Short -32.768 to 32.767 0
Integer -2.147.483.648 to 2.147.438.647 0
Long -9.223.372.036.854.775.808 to 9.223.372.036.854.775.807 0
Single single precision floating-point type 0.0
Float double precision floating-point type 0.0
Date Date and time each stored in an Integer Null
String A variable length string of characters Null
Variant Any datatype Null
Object Anonymous reference to any object Null
Pointer A memory address 0
More on datatypes see http://gambasdoc.org/help/cat/datatypes?v3
More on Floating Point Numbers: http://gambasdoc.org/help/cat/float?v3
More on single precision floating-point format:
https://en.wikipedia.org/wiki/Single_precision_floating-point_format
More on double precision floating point format:
https://en.wikipedia.org/wiki/Double_precision_floating-point_format
Code for event click of rbtSearch:
SearchReplace = 1 'search
End
SearchReplace = 2 'replace
End
With this code in place you have your means to know what FrmSearchReplace has to show
upon opening. If FrmMain Public variable SearchReplace is 1 it's a search, when 2 it's a re-
place.
Now let's make that happen. For this you need to code the Open event of FrmSearchRe-
place:
Select FrmMain.SearchReplace
Case 1
78
8. Your second application: TextPlayT(w)o
Me.Caption = "Search"
btnReplace.Visible = False
tbxReplace.Visible = False
Case 2
Me.Caption = "Search and Replace"
btnReplace.Visible = True
tbxReplace.Visible = True
End Select
End
Now run the application and see if all reacts as wanted
79
8. Your second application: TextPlayT(w)o
End
Now all that you need to do is run above code when button Replace is clicked.
In FrmSearchReplace write following code:
FrmMain.ReplaceString(tbxSearch.Text, tbxReplace.Text)
End
Again all you do is pass some arguments (being the search and replace strings) to the meth-
od ReplaceString to be dealt with accordingly.
The RadioButtons in this example are placed on FrmMain to explain interaction between forms
and Public variables and how to deal with these situations.
It would be better practice to place them on FrmSearchReplace.
80
8. Your second application: TextPlayT(w)o
In this chapter you have worked with several String functions. You have noticed by now that a
lot is possible using String functions.
You will come to learn that they can be useful in a lot of situations, like importing a comma
delimited file, extracting returned information from a linux command run or building a text editor
just to mention a few examples.
They are very powerful tools to use and some of them you will be using a lot when working
with text based information, so get familiar with them.
Now in Gambas IDE click menu File → Quit. This gets you ready for the next chapter.
81
9. Your third application: NumPlay
82
9. Your third application: NumPlay
83
9. Your third application: NumPlay
84
9. Your third application: NumPlay
85
9. Your third application: NumPlay
Print iSwitch
End
Print iSwitch will be executed when clicking on btnCalc giving us the current value of iSwitch
during run time. This will help you check if all works as expected.
Run the application, select subtract and next click btnCalc. If you pay attention in the console
output of the IDE you will see 1 appear when clicking btnCalc
Using the Print instruction will output to the IDE console during runtime. It is a way of check-
ing what is happening during runtime and comes in handy when something is not working as
expected to help you investigate what is actually happening.
Print instruction is typically used to output to the user in a command line Gambas application. A
simple Print followed by a string will output to the standard output (in IDE being the console, in
a command line application being the terminal it runs in).
Print can also used to output to Streams.
Streams are internal objects that Gambas creates for manipulating files, processes, sockets,
and many other objects that can be used as files.
More on Print see http://gambasdoc.org/help/lang/print?v3
Click another operator and next on btnCalc to see if all the Switch values meet your require-
ments.
Now that you have ensured yourself that iSwitch holds the proper value next step is to code
for the calculations based on iSwitch.
For this you need to code the Click event of btnCalc:
86
9. Your third application: NumPlay
As you will notice the calculations run well, but now try with values 10 and 0. As soon as you
try dividing you will get an error as you are not allowed to divide by zero.
87
9. Your third application: NumPlay
As you will also notice you application is not reacting. To stop it click the Stop button in the
IDE toolbar (located below the menu bar).
Catch
Print Error.Code
Error.Clear
End
The keyword Catch will execute whenever an error in btnCalc_Click occurs. Error.Code will
return the error number. Error.Clear will clear the error so the application doesn't hang.
Catch
This instruction indicates the beginning of the error management part of a function or a
procedure.
The catch part is executed when an error is raised between the beginning of the function
execution and its end. This error can be raised by the function itself, or by any other function
called during its execution, provided that this deeper function has no catch part itself: the
deeper the catch part is, the more priority it has.
More on Catch see http://gambasdoc.org/help/lang/catch?v3
More on Error management see http://gambasdoc.org/help/cat/error?v3
Error
Use this class for managing errors raised while the interpreter is running.
Do not mix up with ERROR (with Capital letters)!!
More on Error see http://gambasdoc.org/help/comp/gb/error?v3
More on Error management see http://gambasdoc.org/help/cat/error?v3
Run the application and enter 10 and 0 and do a division. The console will output 26
88
9. Your third application: NumPlay
Catch
Select Error.Code
Case 26
Message.Warning(“You are not allowed to divide by zero!!”)
vbxNum2.SetFocus
Case Else
Print Error.Code
End Select
Error.Clear
End
Error.Code holds Integer values. And since this might be the first in more possible errors a
Select Case is used instead of an If Then for possible further errors to occur. For now if an
other error than 26 occurs you will see its number in the Console of the IDE.
Now run the application again and see what happens when you try to divide by zero.
89
9. Your third application: NumPlay
As you can see the application no longer allows division by zero and informs the user. All hap-
pens without hanging the application.
90
9. Your third application: NumPlay
Catch
Select Error.Code
Case 26
Message.Warning(“You are not allowed to divide by zero!!”)
tbxNum2.SetFocus
Case Else
Print Error.Code
End Select
Error.Clear
End
Now hit <F5> to run the application and see what will happen if you simply start calculating
with text.
When started enter 1 in the two ValueBoxes and 1 in the two TextBoxes. Next click both but-
tons to see what happens.
91
9. Your third application: NumPlay
You will notice that calculating the text values seem to work out of the box.
Catch
Select Error.Code
Case 26
Message.Warning(“You are not allowed to divide by zero!!”)
tbxNum2.SetFocus
Case Else
Print Error.Code
92
9. Your third application: NumPlay
End Select
Error.Clear
End
As you can see three new functions are introduced. Mid(), a string function, INC is an arith-
metical function and Val() a Localization and Translation function.
As you have already worked with several string functions, and have been shown where to find
them, it is part of your learning process to get acquainted with the online Gambas documenta-
tion and learn to comprehend the function Mid(). Val() and INC are explained below.
Expression = Val(String)
Val converts a string into a boolean, a number or a date, according to the string contents.
Expression is the variable that will hold the converted value
String is the string to convert.
The order Val checks to determine where to convert to is:
- Date/Time → returns Date & Time
- Floating point number → returns a floating point number
- 64 bit Long Number → returns a long number
- Integer → returns an integer
- Boolean → returns matching boolean value (0 or -1)
- Otherwise → returns Null
Val is a Localization and Translation Function. These functions are useful when dealing with
translations (language) and localisation (currency settings and such).
More on Val see: http://gambasdoc.org/help/lang/val?v3
Overview of Localization and Translation Functions see:
http://gambasdoc.org/help/cat/localize?v3
INC
Increments a variable.
Variable can be any target or assignment, but MUST be numeric
Same as:
Variable = Variable + 1
or
Variable += 1
INC is a Arithmetical Function. These functions are useful when dealing with numeric data.
Note: The opposite of INC is DEC (decrements a variable).
More on INC see: http://gambasdoc.org/help/lang/inc?v3
Overview of Arithmetical Functions see: http://gambasdoc.org/help/cat/arith?v3
Time to run your application once more and see some results.
Type these strings into tbxOneLine and click CalcText after each entry:
2+4
45 / 0
3 ) 56
a–3
93
9. Your third application: NumPlay
You will notice that most of above either returns a result or gives you a message what is
wrong, except for the last one. It does nothing.
Of course it is possible to take care of this as well. Have a go at it yourself and see what you
can come up with.
The solution is provided on the next page, but really try figure out something yourself first be-
fore moving to the next page.
Remember, most learning takes place when things go wrong, not when everything works from
the beginning. It's the trying to make it work process that will stick much longer and build com-
prehension on the matter, not the copy/paste and run process.
Also know that of you come up with another solution to make it work doesn't make it wrong as
it works and you will have learned about Gambas doing so.
A little hint for on the road: Check out IsNumber() in the Gambas documentation.
94
9. Your third application: NumPlay
End
As you might noticed, instead of using a Switch to escape the event from running excessive
code I chose to use the Stop Event. It does exactly what is says, it stops the event from run-
ning any further.
STOP EVENT
This statement must be used in an event handler. It tells the interpreter that the event that
called the event handler must be cancelled.
More on STOP EVENT see: http://gambasdoc.org/help/lang/stopevent?v3
Overview of Event management: http://gambasdoc.org/help/cat/event?v3
95
9. Your third application: NumPlay
Illustration 96: Some extra controls added to play with date and time
First thing you might notice is that dbxDate.Value returns a number of days if put into an In-
teger. Second thing you might notice is the Format() function.
With format you can convert values to strings in a certain output format.
So the “dd-mm-yyyy” makes sure the value is only the date part and in this order '19-09-
2013'. If you would change it to “yyyy-mm-dd” it would look like '2013-09-19'.
Same goes for “hh:nn:ss” representing two digits for hours, minutes and seconds separated
by ':'
Make sure to have a look at the user defined formats in the Gambas documentation. There
are a lot of examples to be found. Link is in the box on the next page.
96
9. Your third application: NumPlay
Illustration 97: After Date is selected the other controls are updated
accordingly
97
9. Your third application: NumPlay
Now this is what you are about to do. Every 1000 milliseconds (1 second), tbxDate1 will show
current date/time in format “ddd mmm yyyy hh:nn:ss”, tbxDate2 will show current date/time in
format “hh:nn:ss:uu”.
To get current date/time you will use the function Now.
Timer
This class implements a timer object
A timer object raises events regularly, each time it is triggered. The amount of time between
each event is specified by the Delay property.
More on Timer see: http://gambasdoc.org/help/comp/gb/timer?v3
Right click the Timer object and click on its Timer event and add following code:
98
9. Your third application: NumPlay
Now
Returns current date and time.
Now is a Date and Time Function.
More on Now see: http://gambasdoc.org/help/lang/now?v3
Overview of Date and Time Functions see: http://gambasdoc.org/help/cat/time?v3
Time to run your application and see what happens. Just sit back and watch the tbxDate1 and
2 change. If nothing happens you forgot to set the Timer property Enabled to true.
Illustration 100: Every second the tbxDate1 and 2 change their content
99
9. Your third application: NumPlay
In the demonstrated code in 9.3.1, you as a developer need to know what value represents
what operator.
To make life easier you could implement enumeration. Enumeration can be used to declare a
list of integer constants. This will help you give a meaningful name to the different operator
values that need testing, as they are integers.
Using ENUM your code will look like this:
By using ENUM you can now test iSwicht in your code against something more meaningful
like PlusSign instead of 0 or DivideSign instead of 5.
It makes for more readable and easier maintained code in a later stage of development.
100
9. Your third application: NumPlay
Enumeration declaration
{Public | Private } ENUM Identifier [ = Value ] [, Identifier [ = Value ] ...]
This keyword declares an enumeration or a list of integer constants.
If the Value of a constant is not specidied, then it is the value of the previous constant plus one,
or zero for the first constant.
More on Enumeration declaration see: http://gambasdoc.org/help/lang/enumdecl?v3
More on ENUM see: http://gambasdoc.org/help/lang/enum?v3
In this chapter you have worked with Arithmetical, Date and time and localization and
translation functions.
You will have noticed in this and previous chapters that a lot is possible using functions.
You will come to learn that they can be useful in a lot of situations.
They are very powerful tools to use and some of them you will be using a lot, so get familiar
with them.
Now in Gambas IDE click menu File → Quit. This gets you ready for the next chapter.
101
10. Your fourth application: ImagePlay
102
10. Your fourth application: ImagePlay
Illustration 102: Create a new folder 'Images' in the project Data folder
Next, right click the folder Images and in menu select New → Image... Name the Image My-
Image, extension PNG, width and height 128 pixels.
Click the newly made image and make something, like colour the background, draw a circle.
Just play a bit with the Image editor to make some image.
103
10. Your fourth application: ImagePlay
Now first save the image. Use the Save Project button in the button bar below the menu. You
will know if a image is saved when the image is visible in the Project Browser before its
name. To understand compare Illustration on previous page (unsaved MyImage.png) and the
illustration below (saved MyImage.png and NextImage.png).
Next, in the Project Browser, right click MyImage.png ans select Copy. Now right click
folder Images and in menu select Paste.
Rename the image file by right clicking it and selecting Rename.. Name the image NextIm-
age.png and
Illustration 104: Image copied, edited and saved. That makes two works of
art.
The only goal of this little exercise is to end up with two different images sized 128 x128
pixels.
If you are missing the panel with image preview, left of the image editor, look for > and click
on it to make the panel appear. The > will change to < (see illustration below).
You will find more of these panels that can be visible or not. So now you know what to look
for.
104
10. Your fourth application: ImagePlay
105
10. Your fourth application: ImagePlay
Now right click the form and select Event → Open and add next code:
Me.Center
End
Time to run the application and have a look at what you just created.
Well the images should be there. But the button 'Switch Image' still needs some work. Goal is
to switch the images in the PictureBoxes when clicking button 'Switch Image'.
In the editor you used the PictureBox property Picture to add the image to the PictureBox. So
simply exchanging their properties should do the job. But for that you will need a temporary
storage for one of the two properties.
So you need to do something like:
1. Store picOne Picture property in the temporary storage
2. Store picTwo Picture property in picOne Picture property
3. Store the temporary storage in picTwo Picture property
For the temporary storage you need a variable of type Picture. This because the Picture prop-
erty of a PictureBox holds content of type Picture.
Picture
This class represents a picture.
The picture contents are stored in the display server, not in the process memory like an Image.
More on Picture see: http://gambasdoc.org/help/comp/gb.qt4/picture?v3
Back to coding the click event of btnSwitch:
106
10. Your fourth application: ImagePlay
Illustration 110: Clicking the button switches the images between the
PictureBoxes
Me.Center
lblDimOne.Text = pbxOne.Picture.Width & " x " & pbxOne.Picture.Height & " pixels"
lblDimTwo.Text = pbxTwo.Picture.Width & " x " & pbxTwo.Picture.Height & " pixels"
End
107
10. Your fourth application: ImagePlay
When switching the images nothing happens to the Labels, so time to make a new image. In
'Project Browser' right click Image folder to create SmallImage.png (64 x 64) and BigIm-
age.png (256 x 256).
Now go to the FrmMain in IDE and change the properties of pbxOne and pbxTwo. Make sure
pbxOne has LittleImage.png in its Picture property and pbxTwo has BigImage.png in its Pic-
ture property. Once done run the application again and see what it looks like.
108
10. Your fourth application: ImagePlay
When running the application you will see that the labels give the proper dimensions, but the
images aren't shown properly.
LittleImage.png is TopLeft in pbxOne, BigImage.png can only be seen partial, because of its
size being 256 x 256, where pbxTwo is 128 x 128. So that are some things that need atten-
tion.
Try clicking button 'Switch Image' and see what happens.
As you can see, the images switch, but the labels don't. This makes sense as you coded the
Form_Open event, meaning that only on opening the form the Labels get their content. There
is no code on the btnSwitch_Click event doing the same.
So more work is needed.
First you need to make sure that an image is shown in its total in the PictureBoxes, no matter
what its size is.
109
10. Your fourth application: ImagePlay
Second you need to make the Labels show the proper dimensions.
Let's get to work:
First set the properties of the both PictureBoxes to meet this:
Alignment → Center
Stretch → True
The property Stretch will make sure the image is adapted to meet the dimensions of the Pic-
tureBoxes, the Alignment will center the image in the PictureBoxes.
Next more code is needed to make the Labels show the proper dimensions.
You will find all working as expected, even when switching the images the labels show th
proper dimensions.
One thing you might have notices is that the code used for showing the label dimensions in
both Form_Open and btnSwitch_Click event are exactly the same. This means you can write
a routine with that code and call the routine from both events, rather than having same code
at two places.
Advantage is that if you need to change something to the code, it only needs to be changed
at one place.
As you only need this routine on FrmMain you will code for a Private routine.
Here is the full code for FrmMain:
110
10. Your fourth application: ImagePlay
Me.Center
ShowDimensions
End
Public Sub btnSwitch_Click()
End
Private Sub ShowDimensions()
lblDimOne.Text = pbxOne.Picture.Width & " x " & pbxOne.Picture.Height & " pixels"
lblDimTwo.Text = pbxTwo.Picture.Width & " x " & pbxTwo.Picture.Height & " pixels"
End
111
10. Your fourth application: ImagePlay
Picture.Load
Static Function Load (Path As String) As Picture
Loads a picture from the disk.
More on Picture see: http://gambasdoc.org/help/comp/gb.qt4/picture/load?v3
To be able to load the picture you will need a path. Since the images are within the project
folder some more explanation is needed.
For Gambas the Data folder presents the root folder. So addressing the Images folder will
give path: “Images”. If you need BigImage.png the path looks like: “Images/BigImage.png”16
When typing the code in IDE you will see that the auto-complete function will recognise the
path and files in there. Just hit Enter when proper file is selected instead of typing al.
16
More on paths and Gambas: http://gambasdoc.org/help/cat/path
112
10. Your fourth application: ImagePlay
End
Public Sub btnOneSmall_Click()
pbxOne.Picture = Picture.Load("Images/SmallImage.png")
End
Public Sub btnTwoNext_Click()
pbxTwo.Picture = Picture.Load("Images/NextImage.png")
End
Public Sub btnTwoBig_Click()
pbxTwo.Picture = Picture.Load("Images/BigImage.png")
End
Illustration 119: The pictures seem to load but the labels aren't adapted
113
10. Your fourth application: ImagePlay
Again, run the application to see if the adaptation to the code works.
This concludes this chapter. In Gambas IDE click menu File → Quit. This gets you ready for
the next chapter.
114
11. Your fifth application: SimpleTextEditor
115
11. Your fifth application: SimpleTextEditor
Once the menu editor is opened add 9 menu entries by clicking button Insert 9 times.
116
11. Your fifth application: SimpleTextEditor
Assuming Menu9 is the first and Menu1 the last in the list, this is what you need to do for
each of the menu entries17:
Menu9: Name → mnuFile; Caption → File
Menu8: Name → mnuFileNew; Caption → New; Click button Indent in Toolbar (see below)
Menu7: Name → mnuFileOpen; Caption → Open..; Click button Indent in Toolbar
Menu6: Name → Seperator1; Caption → empty; Click button Indent in Toolbar
Menu5: Name → mnuFileSave; Caption → Save; Click button Indent in Toolbar
Menu4: Name → mnuFileSaveAs; Caption → Save As...; Click button Indent in Toolbar
Menu3: Name → mnuFileClose; Caption → Close; Click button Indent in Toolbar
Menu2: Name → Seperator2; Caption → empty; Click button Indent in Toolbar
Menu1: Name → mnuFileQuit; Caption → Quit; Click button Indent in Toolbar
Illustration below is how the end result should look like in the Menu Editor.
Next close the Menu Editor and in IDE have a look at your form. Click on File to see what
happens.
17
You do this by clicking the menu entry in the menu editor list and next changing the proper-
ties in the fields below the menu list. The selected menu entry will be the one you are
editing.
117
11. Your fifth application: SimpleTextEditor
Me.Center
txaMain.Visible = False
End
Public Sub mnuFileNew_Click()
txaMain.Clear 'Needed if another text document is already loaded
txaMain.Visible = True
End
Now run the application and click menu File → New to see what will happen.
Illustration 127: Before and after clicking menu File -> New
118
11. Your fifth application: SimpleTextEditor
Next at the property Picture click on the first button behind the textbox of Picture to open the
Picture dialog. Select Tab Stock and select the New icon18.
18
Icons might differ from desktop to desktop, depending on type of desktop and themes selec-
ted.
119
11. Your fifth application: SimpleTextEditor
Click OK to close the Picture dialog after you selected the icon New. Next click OK again to
close the Menu Editor. Now run the application again and once running on your keyboard
press Ctrl + N and see what happens.
This should give you an new empty text area, same as when clicking the File → New entry.
So no extra coding to get the job done.
Now click on menu File to see your menu icon.
Now that you can create a new text file and are able to enter text into the TextArea, next step
will be to save the content of the TextArea to a file.
11.4.1 On a mission
Yes, I'm going to send you on a mission. A mission to:
19
Location in the meaning of path and file name.
120
11. Your fifth application: SimpleTextEditor
Illustration 131: Make sure your menu entry for Save has an icon and
keyboard entry
121
11. Your fifth application: SimpleTextEditor
...
122
11. Your fifth application: SimpleTextEditor
…
End
Public Sub mnuFileSave_Click()
If $bLoaded Then
'Just save the file
Else
'This means you have a new file
Print "New file"
'Now you will need a path and a file name to save to
Endif
End
Now run and make a new text file and watch the IDE console output. It should print 'New file'
when you click menu File → Save.
Next challenge you face is that you need some form of interaction with the user to provide the
application with a save path and a name of the file, for you to use when saving the file.
Dialog.SaveFile (gb.form.dialog)
Static Function SaveFile() As Boolean
Calls the file standard dialog to get the name of a file to save.
Returns TRUE if the user clicked on the Cancel button, and FALSE if the user clicked on the
OK button.
More on Dialog.SaveFile see: http://gambasdoc.org/help/comp/gb.form.dialog/dialog/savefile?
v3
More on Dialog see: http://gambasdoc.org/help/comp/gb.form.dialog/dialog?v3
So Dialog is what you will use, back to the code editor in IDE.
123
11. Your fifth application: SimpleTextEditor
Endif
End
File.Save (gb)
Static Sub Save(FileName As String, Data As String)
Save the contents of a string into a file.
File.Name (gb)
Static Function Name (Path As String)
Returns the name component of a file path (name component is filename and file extension).
More on File.Save see: http://gambasdoc.org/help/comp/gb/file/save?v3
More on File.Name see: http://gambasdoc.org/help/comp/gb/file/name?v3
More on File see: http://gambasdoc.org/help/comp/gb/file?v3
User.Home (gb)
Static Property Read Home As String
Returns the home directory of the current user.
More on User.Home see: http://gambasdoc.org/help/comp/gb/user/home
More on User see: http://gambasdoc.org/help/comp/gb/user
Run the application, start a new text file, type some text.
Next click File → Save. In the dialog form browse to a location you want to save the file, in
the Name filed type 'test.txt' and click button Save.
124
11. Your fifth application: SimpleTextEditor
125
11. Your fifth application: SimpleTextEditor
Run the application again open a new file, type some text, click File → Save and in the dialog
click Cancel.
Now that the file is saved you have a excuse to code opening a file, to see if the file was
really saved.
Dialog.OpenFile (gb.form.dialog)
Static Function OpenFile([Multi As Boolean]) As Boolean
Calls the file standard dialog to get the name of a file to open.
Returns TRUE if the user clicked on the Cancel button, and FALSE if the user clicked on the
OK button.
More on Dialog.OpenFile see: http://gambasdoc.org/help/comp/gb.form.dialog/dialog/openfile?
v3
More on Dialog see: http://gambasdoc.org/help/comp/gb.form.dialog/dialog?v3
So Dialog,OpenFile is what you will use, back to the Gambas IDE.
File.Load (gb)
Static Function Load(FileName As String) As String
Loads a file and returns its contents as a string.
More on File.Load see: http://gambasdoc.org/help/comp/gb/file/load?v3
More on File see: http://gambasdoc.org/help/comp/gb/file?v3
Run the application and try to open the file 'test.txt', you made and see if it works.
126
11. Your fifth application: SimpleTextEditor
You should see that it works just fine. But there is one thing you forgot. The saving part is
coded for a new text file, but not for an opened text file.
So first back to the mnuSave click event.
127
11. Your fifth application: SimpleTextEditor
Once added, run the application, open test.txt, add a line of text and save.
Close the application and start it again. Open test.txt and you should see a changed file.
20
You see that $bLoaded is being used all over the project. Now you know why it has been de-
clared Private.
128
11. Your fifth application: SimpleTextEditor
Now run the application and see the menu without and with opened text file.
This will work just test, but there is one exception when is will not work as expected. See if
you can discover it.
129
11. Your fifth application: SimpleTextEditor
Well, did you discover it? If not run the application again from scratch. Click on File → New
(or use Ctrl + N), type some text and try to save it.
Did you find it hard to save the text file? Well, I didn't manage. Guess all you need is some
more code to solve this problem.
So, when a new file is created you would like to be able to:
1. Save the file
2. Close the file (even without saving)
When closing a file make sure that $bLoaded is set to False, $sPathFileLoaded and txaMain
are empty.
Another thing to take care of is that when a new file is saved make sure that $bLoaded is set
to True and $sPathFileLoaded holds the path of the newly saved file.
Back to the editor:
130
11. Your fifth application: SimpleTextEditor
$bLoaded = True
Message.Info("File " & File.Name(Dialog.Path) & " saved.")
Endif
End
Public Sub mnuFileClose_Click()
txaMain.Clear
txaMain.Visible = False
$sPathFileLoaded = Null
$bLoaded = False
SetFileMenu
End
...
Private Sub SetFileMenuNew()
mnuFileSave.Enabled = True
mnuFileClose.Enabled = True
End
Run the application and all should be working correctly. Start a new text file and see f you can
save it. Save it and the Save as should appear as well. Next close it and the File menu should
adapt to the new situation and the TextArea should be gone.
Next start another new text file, now close it and again see the menu change accordingly.
One more thing, make sure that menu File → Open, File → Close and File → Quit all get an
icon and File → Quit gets a keyboard shortcut (Ctrl + Q).
131
11. Your fifth application: SimpleTextEditor
Now run the application, open a text file and save it with another name.
132
11. Your fifth application: SimpleTextEditor
Illustration 141: Notification that the file was saved using a new name
You might also have noticed that the code for Save As is, except for the dialog form caption,
exactly the same. So there is some more work to be done
You'll notice they are a lot shorter and pass an argument for the Dialog form caption. (being
'Save' and 'Save As').
This how the SaveDialog() routine looks lik (it is private because you only use it in the current
FrmMain.class):
133
11. Your fifth application: SimpleTextEditor
DialogCaption is the variable used to pass the argument. So calling SaveDialog(“Save”) will
pass the string “Save” to variable DialogCaption and use its value wherever DialogCaption is
used in the routine.
As you see, for a variable used as an argument in a method (or function) I use no prefix to the
variable name, but a name that describes what argument will be for. It's type I will know when
using the routine in code as the auto-help will tell me (see illustration above).
Run the application to see it all at work as it should.
You should have one working very simple TextEditor that you can actually use in real life situ-
ation. But there is still room for improvement.
134
11. Your fifth application: SimpleTextEditor
Another thing is that our form is rather small and when opening a large text file and next drag-
ging the form bigger the TextArea will remain small. Some work there as well.
And last but not least, wouldn't it be nice to have a toolbar with open, save and other buttons?
So a few more thing to do before the application suits the needs.
Next thing to do is to take care that when closing the application our change condition is
checked and when changed a possibility to save is offered.. This needs to be done at both
menu item Close and Quit.
Code for offering to save is not yet there but you might notice that it will probably be exactly
the same for both Close and Quit event.
Now when offering the user to save the file you need to give some options like 'Yes', 'No' and
'Cancel' and act accordingly.
135
11. Your fifth application: SimpleTextEditor
Now on several occasions Message has been used in the example applications and one of its
variants Message.Info (in this example application). Well, there is more you can do with Mes-
sage so time to have a closer look.
You will be using Message.Warning as that makes sense, you want to war users of unsaved
work.
Message
This class is used for displaying message boxes
All Message functions can have up to three buttons:
- The first button is always the default button
- The last button is always the cancel button
Message boxes are modal, meaning the program is paused until one button is clicked.
When a message box is closed the index of the clicked button is returned.
Message.Warning
Static Function Warning(Message As String [, Button1 As String, Button2 As String, Button 3 As
String) As Integer
Displays a warning message with up to three buttons.
The index of the button clicked by the user is returned
More on Message.Warning see: http://gambasdoc.org/help/comp/gb.qt4/message/warning?v3
More on Message see: http://gambasdoc.org/help/comp/gb.qt4/message?v3
As indicated above when showing the Message.Warning (with three buttons) the application
will pause until user has made his choise.
When clicking 'yes' you need to save before Close or Quit
When clicking 'No' you Close or Quit without saving
When clicking 'Cancel' the Close or Quit has to be aborted.
Lets try to code this in a new private function for this:
Why a function?
Well a function can do all a method can do, but it can also return something. In this case it re-
turns True if button Cancel was clicked in Message.Warning. That is why the function is de-
136
11. Your fifth application: SimpleTextEditor
clared As Boolean. The value after the word 'Return' has to be a Boolean as this is the value
returned when the function is called.
Since you will call this function from Close and Quit event it would be nice to know if 'Cancel'
was clicked. So when calling WarningIsCancelled() it will return either True or False.
When True, the warning was cancelled so the Closing or Quitting needs to be cancelled as
well. Hence the name of the function WarningIsCancelled, a name that gives meaning to what
the function actually does.
Now lets have a look at the changed code for Close and Quit event:
Time to run the application to see the effect of all the code.
First open a file, edit it and click File → Close
You should get a warning telling you that your file has changed and offering you the option to
save it.
137
11. Your fifth application: SimpleTextEditor
Now click Cancel to see what happens. You should go back to the file without closing.
Now click File → Close again and next click No. The application will close the file.
Now open the same file and see if the changes where saved. They shouldn't be as you
clicked 'No'.
Now make some changes and click File → Close again and select Yes. The file should close
and upon opening the changes should be in the newly opened file.
Try the same for File → Quit.
If all that is done, one question: Did you discover the bug in your application?...
138
11. Your fifth application: SimpleTextEditor
This actually makes sense as when loading a file to txaMain means a change form the point
of view of txaMain.
Here is the piece of code run before Change event is triggered.
After txaMain.Text = File.Load(Dialog.Path), instead of running the next line of code, the
change event for txaMain is triggered. So the Gambas Interpreter will first execute the txa-
Main_Change() event before returning to the line of code after loading the file.
That is where you need to take care of business as change is triggered upon opening and
$bChanged is set to true.
Adding following line should solve the problem.
Now try running the application again. Do NOT change anything to the file and click menu
File → Close.
It should work properly now. So one bug down, up to the next one.
Open a file, change a few things and next click on the x to close the window (and thus the ap-
plication). Next open the application again and open the file.
Did the changes save? I bet you they didn't, so there you have a second bug.
To catch the closing of a form by the user using x is done in the Form_Close() event.
For this you will code the Form_Close event and next cut and past the code of the mnuFile-
Quit_Click event to the Form_Close event. Next call the Form_Close event from
mnuFileQuit_Click event.
139
11. Your fifth application: SimpleTextEditor
Now run the application, open a file, change something and click x. You will get the warning.
Click Yes and file will save and application closes.
Open the same file and see if the changes saved. Now change again and click x. Select Can-
cel and you will see that the application, instead of cancelling will close.
To solve that problem you will need one more line of code:
STOP EVENT
STOP EVENT
This statement must be in an event handler. It tells the interpreter that the event that called the
event handler must be cancelled.
More on STOP EVENT see: http://gambasdoc.org/help/lang/stopevent?v3
More on Event Management see: http://gambasdoc.org/help/cat/event?v3
Now run the application again, open and change a file, click x and next Cancel and the applic-
ation should stay opened.
In short, second bug down.
140
11. Your fifth application: SimpleTextEditor
You will notice the window will resize, but the TextArea will not.
To solve this problem go to the FrmMain properties in the Gambas IDE. Set the FrmMain
property Arragement to Horizontal
Now run the application, open you big text file and drag the main window bigger.
141
11. Your fifth application: SimpleTextEditor
Illustration 147: The TextArea now does resize with the window...
TextArea does resize when dragging the window bigger, but not how you would like it. You
should try setting property Arrangement to Vertical as well and give it a go.
The one you need to make it work properly is Fill. So make sure to end there.
142
11. Your fifth application: SimpleTextEditor
Run the application and see what happens when clicking New in the Toolbar. Drag the win-
dow bigger and see what happens there.
Although the New button does produce a new empty text file, the forms looks a bit weird.
143
11. Your fifth application: SimpleTextEditor
Seems you need to fix the Arrangement of the FrmMain. Give it a go and try the different op-
tions.
Now that you probably figured out that none will work, set the FrmMain property Arrange-
ment to Vertical. Next set the txaMain property Expand to True.
Now give it another run. You should be able to make a new text file, drag the window bigger
and all should look just fine.
Now add a few more ToolButtons to hbxToolBar.
ToolButton: Name → tbnOpen; Width → 22; Height → 22; Picture→ select the Open icon
from stock 22.
ToolButton: Name → tbnSave; Width → 22; Height → 22; Picture→ select the Save icon
144
11. Your fifth application: SimpleTextEditor
Illustration 153: Make sure all ToolButtons are inside the HBox
Next code all the new ToolButtons. Just let them run the click event of the according menu
item.
Next take care that only those ToolButtons are enabled that need to be enabled, just like you
did with the menus.
For that you will need to go to the two private routines SetFileMenu and SetFileMenuNew.
They will need to look like this:
145
11. Your fifth application: SimpleTextEditor
You will notice how easy it is to make all this work because of a well set up code. Only a few
things need to be done to make all work.
Time for testing the application. Run and try your new buttons, see if they are enabled at the
proper times, if they work.
Make a new file with the New button, type some text and save it with the Save button. Close it
with the Close button and reopen with the Open button. Does all work as expected?
Open a file and change it, try to close it with the button. Do you get a warning that file has
been changed?
All should work as expected and like the menus worked.
146
11. Your fifth application: SimpleTextEditor
All that is left doing is make the ToolBar look a bit better. Simply set the property Spacing of
the hbxToolBar to True
147
11. Your fifth application: SimpleTextEditor
Illustration 158: Added menus with ToolBar menu item set checked
Run the application to see your new menus. Have a special look at menu View → Toolbar as
this one has a checkbox.
148
11. Your fifth application: SimpleTextEditor
Now when the menu item Toolbar is checked you want the ToolBar to be visible. When un-
checked it needs to be invisible.
For the About menu item in menu Help you will code a simple Message.
Open a text file and click menu View and see the Toolbar item checked. Now click the menu-
item Toolbar and see the Toolbar disappear (see illustration on next page).
149
11. Your fifth application: SimpleTextEditor
Illustration 162: Menu Help -> About shows some info on the
application
150
11. Your fifth application: SimpleTextEditor
151
11. Your fifth application: SimpleTextEditor
Third place to check is when a new document is saved (so it has a name) and when an exist-
ing document is saved as (so it will get another name).
This all happens in method SaveDialog. So that is where you need to add the code:
152
11. Your fifth application: SimpleTextEditor
Run your application once more and try some different things, like starting a new text docu-
ment and saving it, next save as. If you see the caption changing the application is finished
for now.
153
11. Your fifth application: SimpleTextEditor
Not visible on the screenshot is that at certain point in the code I add comment to explain to
myself (in a later stage) what I did there. Might sound strange, but believe me, I am very
happy that I give myself these presents.
This concludes this chapter.
In the next chapter you're going to continue to work with SimpleTextEditor.
154
12. End note for pre-release 1
To be continued...
P.S. If you encounter any irregularities in this release please report them back (see Ap-
pendix V) and help improve the guide.
155
13 Appendices
File commands
ls lists the current directory
ls -al lists the current directory (hidden files included)
cd dir change the directory dir (example: cd /usr/bin)
cd change to home directory
cd / change directory to root directory
mkdir dir make directory dir (example mkdir Gambas3)
rm file removes file file (example rm myinfo.txt)
rm -r dir removes directory dir (example rm Gambas3)
rm -f file forced remove file file (example rm -f myinfo.txt)
rm -fr dir forced remove directory dir (example rm -rf Gambas3)
System information
df show disk usage
du show directory usage
uptime show system uptime
uname -a show kernel information
free show memory and swap information
I
Appendix II: Subscribe to the official Gambas mailing lists/Forum
When you are experiencing problems installing Gambas and you don't manage to solve them
you can always report them on the Gambas mailing list.
For this you will first need to subscribe to the mailing list. Open a browser and go to the Gam-
bas website and click on the menu 'Mailing lists/Forums'
This will open an overview of the available mailing lists and a forum.
II
Then there is a Spanish and French user list and next the forum for those who dislike mailing
lists.
Option 1: Subscribe to Gambas Users mailing list
When clicking 'Gambas Users' you get to the page to register to the mailing list.
Once registered you will receive all posts on the mailing list in the inbox of the mail account
you signed up with. You will also be able to send mails to the list.
Option 2: Use the forum instead of the mailing list
If you dislike mailing list there is a second option. Click 'http://www.nabble.com/Gambas-
f3425.html' to go to the forum.
III
Illustration 171: Gambas mailing list Forum
On the forum you will find all the topics and posts from the mailing list. To post you will need
to register an account.
IV
Appendix III: Reporting problems on the official Gambas mailing list
When reporting your problems on the mailing list first consider a few good practices.
1. Search the official Gambas mailing list forum for an answer before asking questions
2. Provide details on your system when reporting your problem
3. Provide details on your problem when reporting your problem
4. Be clear on what goes wrong and where it goes wrong and the steps that took you there
5. Provide a source archive with a project that shows the problem
Just copy/paste into your mail or attach a text file you pasted the information into.
V
Appendix IV: White Island Software and GambasForum quick tour
On White Island Software and GambasForum a Project Collaboration Forum 'How to Gam-
bas 3' has been created open to the public21. Here is a quick tour to get you started on the
forum.
To go to White Islands Software and GambasForum open a web browser and type
http://whiteislandsoftware.com/index.php?page=start as destination.
Illustration 173: White Island and GambasForum (circled the login and join)
Once there log in or join (see illustration above). When logged in you will be brought to the
same page again but now with more details where the login used to be.
Click on Forum in the top menu (just behind Home). You will get an overview of all forums
present when scrolling down.
Forums are categorized into these categories with following forums per category 22:
➢ Website Community
➢ Website Community
➢ Gambas News
➢ General
➢ Introduce yourself
➢ General chat
➢ Graphic and Images
➢ Website comment topics
➢ The GambasForum Coder
➢ Gambas IDE
➢ Ask Quin
➢ Gambas version 3
➢ Gambas versions 1 and 2
➢ Raspberry Pi
➢ Gambas based projects
➢ Member's Lounges
➢ gbWilly
21
You can visit it as guest and read all information. To post questions on the forum you need
to make a free account.
22
Categories and forums as present on October 14th 2012.
VI
sholzy
➢
konaexpress
➢
➢ NatashaDaystar
➢ Piga Software
➢ Gambas Project hosting
➢ Important notices (Read-only)
➢ The Admin's lounge
➢ How To.../Howdo I...
➢ Domains
If you want to look for something or post something make sure to go to the proper category
and forum.
When you visit the GambasForum to check what you missed since your last visit there is an
easy option at the top left of your user name 'Post since last visit'. Click it and you will see
what you missed out on.
Illustration 174: Search, Post since last visit and Topics with unread posts
Another handy option is the 'search' button for searching the forum if you have some problem
with Gambas. If no answer to your problem can be found just start a new topic in the proper
category and forum.
'Topics with unread posts' can come in practical at times as well.
With this information you have the basics to get started on the forum. There is a lot more out
there like a software repository, guides and so on, but that is not what this guide is about.
VII
Appendix V: Getting help with the 'How to Gambas 3' guides
On White Island Software and GambasForum a Gambas based project 'How to Gambas 3'
has been created open to the public23.
It is set up so that people having trouble with the guide can go there and ask their questions
(or check if someone else asked the same) or do suggestions on the manual.
These questions and suggestions will be taken into account on improving the guides. So feel
free do make good use of this possibility.
First browse to the White Island Software and Gambas Forum24 and login (if you want to post
your problem).
Click on 'Forum' in the topmenu and scroll down to the category 'Gambas based projects'
where you will find the forum 'How to Gambas 3' under gbWilly.
Illustration 175: Gambas based projects with sub forum 'How to Gambas 3'
If you click the forum you will find several sub forums and some general topics.
Current sub forums are:
➢ Installing Gambas
This contains topics concerning the guide 'Installing Gambas'.
Post your questions and/or suggestions on the guide 'Installing Gambas' here.
➢ Building GUI Applications
This contains topics concerning the guide 'Building GUI Applications'.
Post your questions and/or suggestions on the guide 'Building GUI
Applications' here
➢ Project member Section
This section is for project contributors only. If you want to contribute send
a PM on the forum to gbWilly.
The number of sub forums will grow with the number of guides is the series.
23
You can visit it as guest and read all information. To post questions on the forum you need
to make a free account.
24
Link to website: http://whiteislandsoftware.com/index.php?page=start
VIII
Illustration 176: Sub forums and topics of 'How to Gambas 3' forum
Each sub forum will have its own topics. Make sure to post in the proper sub forum. So for
questions on this manual 'Building GUI Applications' you click Building GUI Applications to
see the topics present.
The topics are kind of self explaining, just post in the proper one and it will be picked up.
IX
Appendix VI: Application Gambas Learning – a learning aid for Gambas
Gambas Learning is an application to provide some aid to those learning Gambas.
25
This requires a working internet connection
X
Appendix VII: Overview of the 'How To Gambas 3' guides
Here is the list of guides published and planned:
➢ 1. Installing Gambas
First version published: November 10th, 2012
➢ 2. Building GUI Applications
First 11 chapters pre-published: September 29th, 2013
XI
14 Bibliography
Primary sources
Gambas website: Gambas 3 Documentation, URL: http://gambasdoc.org/help/?v3 [Last accessed 28/09/2013].
Gambas website: Reporting a problem, bug or crash, URL: http://gambasdoc.org/help/doc/report?view [Last accessed
14/10/2012]
Secondary sources
Wikipedia: Gambas, URL: http://en.wikipedia.org/wiki/Gambas [Accessed 09/11/2012]
Wikipedia: C Datatypes, URL: https://en.wikipedia.org/wiki/C_data_types [Accessed 02/03/2013]
Wikipedia: Object-oriented programming URL: http://en.wikipedia.org/wiki/Object-oriented_programming [Accessed
23/09/2013]
XII