1. No category

How to
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 allowed, 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 PROHIBITED.
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, EXPRESS, 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
1 HOW THIS GOT STARTED.........................................................................................1
2 FOREWORD................................................................................................................2
3 BEFORE YOU GET STARTED....................................................................................3
3.1 BACKGROUND INFORMATION......................................................................................................3
3.2 EXAMPLE CODE.....................................................................................................................3
3.3 GOOD PRACTICE...................................................................................................................3
3.4 TERMINAL.............................................................................................................................3
3.5 WARNING.............................................................................................................................4
3.6 CONTROLS AND MENUS...........................................................................................................4
4 INTRODUCTION..........................................................................................................5
4.1 WHAT IS GAMBAS?................................................................................................................5
5 SOME GOOD PRACTICES.........................................................................................6
5.1 FOLDER ORGANISATION............................................................................................................6
5.1.1 Development folder........................................................................................................ 6
5.1.2 Distributions folder......................................................................................................... 7
5.2 PROJECT ORGANISATION..........................................................................................................9
5.3 ORGANISING YOUR CODE.........................................................................................................9
5.3.1 Commenting your code................................................................................................ 10
5.3.2 Clear choices for names.............................................................................................. 11
5.3.3 Indenting code............................................................................................................. 12
5.3.4 Eliminate repeating code.............................................................................................. 13
6 A FIRST GUI APPLICATION: TEXTPLAY.................................................................14
6.1 WHAT WILL BE DONE IN THIS CHAPTER......................................................................................14
6.2 STARTING A NEW PROJECT.....................................................................................................14
6.3 CREATING A FORM AND CONTROLS...........................................................................................18
6.3.1 Placing controls on a form............................................................................................ 19
6.3.2 A closer look at the controls......................................................................................... 22
6.4 CODING, TESTING, CODING, TESTING.........................................................................................24
6.4.1 Objects, properties, events and methods.....................................................................24
6.4.2 Write some code and test (round 1).............................................................................24
6.4.3 Code some improvements and test (round 2)..............................................................27
7 EXTENDING APPLICATION TEXTPLAY..................................................................30
7.1 WHAT WILL BE DONE IN THIS CHAPTER......................................................................................30
7.2 OPEN AN EXISTING PROJECT...................................................................................................30
7.3 MODIFY MAIN FORM AND ADD CONTROLS....................................................................................31
7.3.1 Copy controls on the form............................................................................................ 33
7.3.2 A closer look at the controls......................................................................................... 34
7.4 CODING, TESTING AND ADAPTING.............................................................................................37
7.4.1 Coding and testing (round 1)........................................................................................ 37
7.4.2 Adapting, coding and testing (round 2).........................................................................38
7.4.3 Adding new controls, code and test (round 3)..............................................................41
7.4.4 Add some last controls, code and test (round 4)..........................................................46
7.5 A LAST REVIEW OF THE APPLICATION.........................................................................................53
7.5.1 Do you need a button Show?.......................................................................................53
7.5.2 Could iSwitch format be more clear?...........................................................................53
7.5.3 Should the button Add be enabled if no Add is checked?............................................54
7.5.4 Should the button Clear be enabled if there is nothing to clear?..................................54
7.6 ANSWERS TO THE LAST REVIEW ...............................................................................................54
7.6.1 Do you need a button Show?.......................................................................................54
7.6.2 Could iSwitch format be more clear?...........................................................................56
7.6.3 Should the button Add be enabled if no Add is checked?............................................56
7.6.4 Should the button Clear be enabled if there is nothing to clear?..................................57
8 YOUR SECOND APPLICATION: TEXTPLAYT(W)O.................................................59
8.1 WHAT WILL BE DONE IN THIS CHAPTER......................................................................................59
8.2 START A NEW PROJECT AND DESIGN THE FIRST FORM...................................................................59
8.3 PLAYING WITH TEXT THE OTHER WAY AROUND.............................................................................60
8.3.1 Some first coding to split the text.................................................................................60
8.3.2 Determine the number of splits....................................................................................64
8.4 SEARCH FOR TEXT...............................................................................................................68
8.4.1 Make a new form......................................................................................................... 68
8.4.2 Make FrmSearchReplace open from btnSearch on FrmMain......................................70
8.4.3 Project intermezzo: Form class interaction explained..................................................71
8.4.4 Back on track to code a Public method on FrmMain....................................................73
8.4.5 Lets search some string............................................................................................... 74
8.5 SEARCH AND REPLACE TEXT...................................................................................................76
8.5.1 Prepare the forms for Search and Replace..................................................................76
8.5.2 Making FrmSearchReplace appear depending on selection in FrmMain.....................77
8.5.3 Replace searched strings............................................................................................ 80
9 YOUR THIRD APPLICATION: NUMPLAY.................................................................82
9.1 WHAT WILL BE DONE IN THIS CHAPTER......................................................................................82
9.2 START A NEW PROJECT AND DESIGN A FORM...............................................................................82
9.3 DOING THE MATHS................................................................................................................83
9.3.1 Analyse the needs and determine a strategy...............................................................84
9.3.2 Implement error handling............................................................................................. 88
9.4 WORKING WITH NUMBERS IN TEXT VARIABLES AND TEXT CONTROLS..................................................90
9.4.1 Simple beginnings........................................................................................................ 91
9.4.2 Next challenge............................................................................................................. 92
9.5 HOW ABOUT DATE AND TIME...................................................................................................95
9.5.1 Adding some code....................................................................................................... 96
9.5.2 More date and time...................................................................................................... 97
9.6 ANOTHER APPROACH, ENUMERATE............................................................................................99
9.6.1 iSwitch enumerated..................................................................................................... 99
10 YOUR FOURTH APPLICATION: IMAGEPLAY....................................................102
10.1 WHAT WILL BE DONE IN THIS CHAPTER..................................................................................102
10.2 START A NEW PROJECT AND DESIGN A FORM..........................................................................102
10.3 LET ME SEE SOME IMAGES.................................................................................................103
10.3.1 Making some images............................................................................................... 103
10.3.2 Make the images appear.......................................................................................... 104
10.3.3 Code the labels........................................................................................................ 107
10.4 LOADING IMAGES USING CODE.............................................................................................111
10.4.1 The mission............................................................................................................. 112
10.4.2 Make the labels work again......................................................................................113
11 YOUR FIFTH APPLICATION: SIMPLETEXTEDITOR..........................................115
11.1 WHAT WILL BE DONE IN THIS CHAPTER..................................................................................115
11.2 START A NEW PROJECT AND DESIGN A FORM..........................................................................115
11.3 MAKING A MENU..............................................................................................................116
11.3.1 Coding the menu entry New.....................................................................................118
11.3.2 Adding Icon and keyboard shortcut to menu entry New...........................................119
11.4 SAVING YOUR FIRST TEXT FILE.............................................................................................120
11.4.1 On a mission............................................................................................................ 120
11.4.2 Lets save some text................................................................................................. 121
11.4.3 Get name and path to save to..................................................................................123
11.5 OPENING YOUR FIRST TEXT FILE..........................................................................................126
11.5.1 Code for opening..................................................................................................... 126
11.5.2 Make sure an opened file can be saved...................................................................127
11.6 LITTLE INTERMEZZO..........................................................................................................128
11.7 BACK ON TRACK FOR SAVE AS...........................................................................................132
11.7.1 Code Save As menu item......................................................................................... 132
11.7.2 Simplifying the code for saving................................................................................133
11.8 PUTTING THE DOTS ON THE I...............................................................................................134
11.8.1 Offer to save when closed after editing text file........................................................135
11.8.2 Bug!! What bug?!..................................................................................................... 138
11.8.3 Resizing the application window..............................................................................141
11.8.4 Adding a ToolBar...................................................................................................... 143
11.8.5 Reordering menu items............................................................................................ 147
11.8.6 Adding new menus................................................................................................... 148
11.8.7 Application caption................................................................................................... 150
11.9 A LAST NOTE ON CODE ORGANISATION...................................................................................153
12
END NOTE FOR PRE-RELEASE 1......................................................................155
13
APPENDICES............................................................................................................ I
14
BIBLIOGRAPHY....................................................................................................XII
List of Illustrations
Illustration 1: Organisation of 'Development' folder...........................................................6
Illustration 2: Organisation of 'Distributions' folder.............................................................8
Illustration 3: Application folder with version folders containing the packages...................9
Illustration 4: Organisation of a project folder in the Gambas IDE.....................................9
Illustration 5: Gambas 3.4.1 opening screen...................................................................14
Illustration 6: 'New project' screen step 1. Select the type of application........................15
Illustration 7: 'New project' screen step 2. Select the folder for the new project..............15
Illustration 8: Create a new folder for Learning projects..................................................16
Illustration 9: Select the folder 'Gambas3-Learning'........................................................16
Illustration 10: 'New project' screen step 3. Name the project folder and project ...........17
Illustration 11: Message when project has been created successfully............................17
Illustration 12: New project 'TextPlay' opened in Gambas 3 IDE.....................................18
Illustration 13: FMain in Sources folder of the project.....................................................18
Illustration 14: Empty form in IDE....................................................................................19
Illustration 15: Label icon in ToolBox...............................................................................20
Illustration 16: Label control drawn on the form..............................................................20
Illustration 17: TextBox icon in ToolBox...........................................................................20
Illustration 18: TextBox control drawn on the form...........................................................21
Illustration 19: Button icon in ToolBox..............................................................................21
Illustration 20: Two button controls drawn on the form....................................................21
Illustration 21: Select Alignment of the Label control.......................................................22
Illustration 22: Label1 aligned right..................................................................................23
Illustration 23: Label1 Text property changed..................................................................23
Illustration 24: Controls after changing the properties.....................................................23
Illustration 25: Select Event Click for button control........................................................25
Illustration 26: FMain.class..............................................................................................25
Illustration 27: Menu Debug -> Run to test the application..............................................26
Illustration 28: Application running with message shown.................................................27
Illustration 29: Message when no name entered.............................................................29
Illustration 30: Message when name entered..................................................................29
Illustration 31: Gambas welcome screen 'Recent projects'.............................................30
Illustration 32: Mouse appearance will change where the pointer is................................31
Illustration 33: Form dragged wider and Label and TextArea selected............................31
Illustration 34: Drag the buttons to the bottom of the form..............................................32
Illustration 35: Result after adapting the form..................................................................32
Illustration 36: Pasted controls on the form.....................................................................33
Illustration 37: Controls dragged to the spot you need them...........................................33
Illustration 38: Result after copy/pasting all needed controls...........................................33
Illustration 39: Label1 after changing the Text property...................................................34
Illustration 40: Name properties of both TextBoxes changed..........................................34
Illustration 41: Main form after the changes in the exercise............................................35
Illustration 42: Names of buttons changed in Fmain.class as well..................................36
Illustration 43: Main form after adding two more controls................................................36
Illustration 44: Result after clicking button Add................................................................37
Illustration 45: Hierarchy of the controls on main form....................................................38
Illustration 46: Hierarchy after adaptation........................................................................38
Illustration 47: Set selected controls NoTabFocus property to True................................39
Illustration 48: Clicking Add without filling in a name.......................................................40
Illustration 49: Three CheckBoxes and three RadioButtons............................................41
Illustration 50: All CheckBoxes selected, only one RadioButton......................................41
Illustration 51: Result of 2 lines selected.........................................................................43
Illustration 52: Clicked button Add with only Name selected...........................................45
Illustration 53: New controls added and adapted............................................................46
Illustration 54: Testing the new code...............................................................................49
Illustration 55: Selecting RadioButton 'Show' deselects RadioButton '1 line'...................50
Illustration 56: ToolBox tab Container showing Frame....................................................50
Illustration 57: Frame Show placed on form....................................................................51
Illustration 58: RadioButtons pasted into Frame Show....................................................51
Illustration 59: All RadioButtons placed in their Frames..................................................52
Illustration 60: RadioButtons show working as supposed................................................52
Illustration 61: No button Show but still doing the same job............................................55
Illustration 62: Main form in IDE design mode.................................................................60
Illustration 63: Main form when run from IDE..................................................................60
Illustration 64: Text splitted on the dot (.).........................................................................62
Illustration 65: Result of splitting on \n.............................................................................63
Illustration 66: Renewed result of splitting on "\n"...........................................................64
Illustration 67: Result of splitting on "\n" showing 2 lines.................................................65
Illustration 68: Split for 4 lines.........................................................................................67
Illustration 69: Next a split for 1 line (other lines are now cleared)..................................68
Illustration 70: Ad a new form to the project....................................................................68
Illustration 71: Dialog to name the form...........................................................................69
Illustration 72: FrmSearchReplace with controls placed..................................................69
Illustration 73: FrmSearchReplace opened from btnSearch............................................71
Illustration 74: Running btnSplit code from btnSearch on another form..........................72
Illustration 75: Interaction between methods in different form classes............................73
Illustration 76: Search string passed as argument of a Public method............................74
Illustration 77: Seems like search performs as expected................................................76
Illustration 78: Replace TextBox and Button added to FrmSearchReplace.....................76
Illustration 79: FrmSearch property Enabled set to true on FrmMain..............................77
Illustration 80: Search shown when search selected.......................................................79
Illustration 81: Search and Replace shown when search/replace selected.....................79
Illustration 82: Search still works well..............................................................................81
Illustration 83: Replace does a good job as well.............................................................81
Illustration 84: FrmMain after placing all controls............................................................83
Illustration 85: FrmMain when run...................................................................................83
Illustration 86: lblOperator shows selected Operator.......................................................84
Illustration 87: Console output in IDE..............................................................................86
Illustration 88: Calculating values 10 and 2.....................................................................87
Illustration 89: Division by zero error...............................................................................87
Illustration 90: Error 26 returned.....................................................................................89
Illustration 91: Division by zero now handled properly.....................................................90
Illustration 92: FrmMain after adding some controls........................................................90
Illustration 93: Calculating the text seems to work..........................................................91
Illustration 94: Division by zero taken care off.................................................................94
Illustration 95: Unknown operator taken care off.............................................................94
Illustration 96: Some extra controls added to play with date and time.............................96
Illustration 97: After Date is selected the other controls are updated accordingly...........97
Illustration 98: Timer object can be found in the toolbox on tab 'Special'.........................98
Illustration 99: Timer object can be anywhere on the form..............................................98
Illustration 100: Every second the tbxDate1 and 2 change their content.........................99
Illustration 101: Controls placed on FrmMain................................................................102
Illustration 102: Create a new folder 'Images' in the project Data folder........................103
Illustration 103: Made some modern art image.............................................................103
Illustration 104: Image copied, edited and saved. That makes two works of art............104
Illustration 105: Make panel appear..............................................................................104
Illustration 106: Opening the 'Select a picture' form......................................................105
Illustration 107: Image 'MyImage.png' in PictureBox picOne.........................................105
Illustration 108: Both images in their PictureBox...........................................................105
Illustration 109: Running ImagePlay for the first time....................................................106
Illustration 110: Clicking the button switches the images between the PictureBoxes....107
Illustration 111: Labels now showing the image dimensions.........................................108
Illustration 112: Two more png images made in the editor............................................108
Illustration 113: Running the application with the new images......................................109
Illustration 114: Images switch but labels show wrong dimensions...............................109
Illustration 115: All works as expected..........................................................................110
Illustration 116: All new controls placed on FrmMain.....................................................111
Illustration 117: Project folder structure.........................................................................112
Illustration 118: Auto-complete function of IDE will recognise the path.........................112
Illustration 119: The pictures seem to load but the labels aren't adapted......................113
Illustration 120: Loading images now adapts the Labels accordingly............................114
Illustration 121: FrmMain after placing the control.........................................................115
Illustration 122: Select Menu editor...............................................................................116
Illustration 123: Adding 9 menu entries in the Menu editor............................................116
Illustration 124: Indent the menu entry..........................................................................117
Illustration 125: The end result of editing the menu entries...........................................117
Illustration 126: There is a menu File on FrmMain in IDE..............................................118
Illustration 127: Before and after clicking menu File -> New.........................................118
Illustration 128: Set the keyboard shortcut for menu New.............................................119
Illustration 129: Selecting the new icon.........................................................................119
Illustration 130: File menu with the newly added icon for New......................................120
Illustration 131: Make sure your menu entry for Save has an icon and keyboard entry 121
Illustration 132: Ready to save my first file....................................................................124
Illustration 133: Dialog Save text file.............................................................................125
Illustration 134: Notification that the file has been saved...............................................125
Illustration 135: Dialog Open text file.............................................................................127
Illustration 136: Saved the changes to the text file........................................................128
Illustration 137: Part of the File menu disabled as should be........................................129
Illustration 138: Oops.., no way to save a new text file..................................................130
Illustration 139: The end result of some polishing of the File menu...............................131
Illustration 140: Save As dialog.....................................................................................132
Illustration 141: Notification that the file was saved using a new name.........................133
Illustration 142: The auto-help will know your new routine............................................134
Illustration 143: Closing after editing gives a warning and option to save.....................138
Illustration 144: Changed shown in Console means Change event is triggered............139
Illustration 145: Dragging the window bigger doesn't change the TextArea...................141
Illustration 146: Set the Arrangement property of FrmMain...........................................141
Illustration 147: The TextArea now does resize with the window...................................142
Illustration 148: Arrangement set to Fill does the job.....................................................142
Illustration 149: HBox is found on the Tab Container.....................................................143
Illustration 150: All new controls in place.......................................................................143
Illustration 151: A strange looking form, but New button works.....................................144
Illustration 152: Set txaMain property Expand to True...................................................144
Illustration 153: Make sure all ToolButtons are inside the HBox....................................145
Illustration 154: A running resizeable SimpeTextEditor with Toolbar..............................146
Illustration 155: Toolbar with property Spacing set to False..........................................147
Illustration 156: Toolbar with property Spacing set to True............................................147
Illustration 157: A click on Move Up button brings the item higher................................147
Illustration 158: Added menus with ToolBar menu item set checked.............................148
Illustration 159: A new menu View Toolbar....................................................................148
Illustration 160: With ToolBar checked..........................................................................149
Illustration 161: With Toolbar unchecked.......................................................................150
Illustration 162: Menu Help -> About shows some info on the application.....................150
Illustration 163: 'New text document' added to application caption...............................151
Illustration 164: Caption showing the name of the opened text file...............................152
Illustration 165: Save the new text document................................................................153
Illustration 166: After saving the caption changed.........................................................153
Illustration 167: FrmMain.class code organised in certain order...................................154
Illustration 168: Gambas website - Menu Mailing lists/Forums..........................................II
Illustration 169: Gambas website - Overview Mailing Lists & Forums...............................II
Illustration 170: Subscribe to the Gambas-user mailinglist...............................................III
Illustration 171: Gambas mailing list Forum.....................................................................IV
Illustration 172: Gambas IDE - System information form..................................................V
Illustration 173: White Island and GambasForum (circled the login and join)..................VI
Illustration 174: Search, Post since last visit and Topics with unread posts....................VII
Illustration 175: Gambas based projects with sub forum 'How to Gambas 3'................VIII
Illustration 176: Sub forums and topics of 'How to Gambas 3' forum...............................IX
Illustration 177: Topics in sub forum 'Building GUI Applications'......................................IX
Illustration 178: Gambas Learning - a learning aid for Gambas........................................X
Appendices
Appendix I: Linux command reference...............................................................................I
Appendix II: Subscribe to the official Gambas mailing lists/Forum....................................II
Appendix III: Reporting problems on the official Gambas mailing list................................V
Appendix IV: White Island Software and GambasForum quick tour.................................VI
Appendix V: Getting help with the 'How to Gambas 3' guides.......................................VIII
Appendix VI: Application Gambas Learning – a learning aid for Gambas.........................X
Appendix VII: Overview of the 'How To Gambas 3' guides..............................................XI
1. How this got started
1 How this got started
Somewhere in 2009 I finally decided to install Linux on one of my systems. After my first initial
exploring of the operating systems, the provided applications and more a new world opened
up to me.
I soon discovered the stability and power of Linux and moreover the power of an open source
community. So after exploring Linux a while I felt like programming. Since most of my last and
current work involved programming client interfaces for databases in VB, I went looking for a
good alternative on the Linux platform.
And then I found Gambas (at that time in version 2) and loved it right from the start. It's ease
of use and logic in syntax surprised me, captured me and never let me go. Since that day all
my coding that is not job related is done in Gambas1.
For me, as a professional application developer , finding my way in Gambas wasn't always
that easy. Documentation is very basic and explains the syntax of the language with little or
no examples. There are some guides out there, but they are scares. Nevertheless I manage
because of my years of experience with programming.
I can see how a new programmer might find it hard to understand how Gambas and Linux
work, then leave in disappointment and frustration.
Back in the old days, about every computer had a programming language and manual delivered along with it. A lot of young people in those days learned programming this way and
Gambas is an excellent tool to do just that on a Linux platform.
As it is based on BASIC (Beginners All purpose Symbolic Instruction Code), a language
many in the eighties learned themselves, it is perfect for a beginner to learn programming.
Although a lot has changed since Basic saw birth, it still is the same language, but much
more powerful because of Gambas providing an environment to make event driven GUI
(Graphical User Interface) applications. It's possible to build easy GUI applications doing
simple things in no time.
And that is what this series aims at. People new to programming and wanting to learn the
skills. So that is what will be covered in a simple manner, so any newbie can learn. Every part
of the series will cover a specific topic. And in time you will have all the basic skills to build
your own applications in Gambas 3.
Enjoy...
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 creating 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 Gambas 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 environment 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 applications.
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, localisation, the basics of loading and saving data to files and of handling images in your application. Besides that Gambas syntax and useful string, arithmetical and other functions are explained 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, compiling 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 general.
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 possibilities, 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 familiar 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 distribution and with your localisation settings.
2
3. Before you get started
3 Before you get started
You will need to have at least Gambas 3.3.x or higher, installed on your system 3. Installing
Gambas will not be covered in this book. 'How to Gambas 3 – Installing Gambas' covers the
installation of Gambas in detail and for different distributions.
You will also need to know some conventions used in this book for clear understanding of the
materials presented herein.
3.1 Background information
When explaining how to built and code in Gambas 3, I will sometimes provide extra background. This extra background is meant to give some deeper insight into the world of both
Linux and Gambas.
This background is not necessary for completing the examples, but will give you a better comprehension of Gambas in general.
This is how background information is presented in this book.
It will give you some more insight on the item being explained.
Background information will be placed in a yellow box.
3.2 Example code
Example code is used to explain Gambas using sample applications that get built up and explained in detail from the scratch.
'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.
3.3 Good Practice
If something is considered as a good practice it will be placed in a green box.
This is how good practice information is presented in this book.
It is advised to start using this good practice in applications you built.
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.
This is an important procedure.
Pay attention as things can go seriously wrong :-)
3.6 Controls and menus
When testing the applications built in Gambas you will need to do things like click on a button
to see if the code does what it is supposed to do.
When, for example, referring to the button with Cancel on it I will refer to it as: Click on the
button Cancel
When for example referring to a menu About... in the menu Help I will refer to it as: Click on
menu Help → About...
4
4. Introduction
4 Introduction
4.1 What is Gambas?
As the Gambas website states: 'Gambas almost means Basic'. With the 'G' for Gambas, the
'a' for almost, the 'm' for means and the 'bas' for Basic. A nice little playing on words.
According to the official website 'Gambas is a free development environment based on a Basic interpreter with object extensions'. It is comparable to a popular counterpart on an mainstream platform.
The person behind the project and main developer is Benoît Minisini from France with the
help of others.
Gambas provides you with an IDE for easy development of GUI applications. Gambas components provide you with extra syntax and functionality to code for things like database access, networking access, CGI web applications, internationalisation and more.
Visit the Gambas Introduction at the official Gambas website for more details.4
IDE or Integrated Development Environment is a software application that provides
comprehensive facilities to computer programmers for software development.1
In Gambas this means you have an environment where you can easily design your forms, put
controls on them (like buttons, text fields, check boxes and so on) and code them in a source
code window.
You get a tree view on the project so you can easily browse from one form design to another
and see other files like icons contained in the project.
The Gambas IDE also has a debugger so you can run applications in development time without
having to make executables or distribution packages, a thing the IDE does as well.
You can add or remove components to the project in the IDE and in this way add or remove
functionality to your applications.
1. Source: http://en.wikipedia.org/wiki/Integrated_development_environment
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.
Object-oriented programming (OOP) is a programming paradigm using "objects" – data
structures consisting of data fields and methods together with their interactions – to design
applications and computer programs.
Programming techniques may include features such as data abstraction, encapsulation,
messaging, modularity, polymorphism, and inheritance. Many modern programming languages
now support OOP, at least as an option1
1. Source: http://en.wikipedia.org/wiki/Object-oriented_programming
4
http://gambas.sourceforge.net
5
5. Some good practices
5 Some good practices
If you develop applications there are some good practices that can make your life easier. I'll
try to give an overview on how I organise my projects, code and more for Gambas. This is the
way I have done it for my own needs and it is a sort of evolution that took place over the
years of programming in different languages.
This doesn't have to be how you want to organise your projects, code and more, it is just a
suggestion that could prove useful.
5.1 Folder organisation
This is probably not the first thing most of you would think about but to me it is an important
one, especially when having several projects running.
Here is how I organise my folders for Gambas development. I develop in both Gambas 2 and
3. You can do it differently when only developing in Gambas 3.
First I create 2 folders in my home folder or in a folder made for it. One is called 'Development', the other 'Distributions'. This you can simply do from within your File Manager application beloning to your Linux distribution.
5.1.1 Development folder
In my case in the 'Development' folder I create a 'Gambas2' and a 'Gambas3' folder.
Within the 'Gambas3' folder I create following folders:
➢ Application documentation
➢ Gambas3-ArchivedApps
➢ Gambas3-GameZone
➢ Gambas3-Projects
➢ Gambas3-SourceOthers
➢ Gambas3-TestZone
➢ Gambas3-Tools
Illustration 1: Organisation of 'Development' folder
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 remember 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 deleted 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.
5.1.2 Distributions folder
This folder contains the distribution packages for all my applications. In my case in the 'Distributions' folder I create a 'Gambas2' and a 'Gambas3' folder.
Within the 'Gambas3' folder I create following folders:
➢ Archived
➢ Website
➢ Zone-Games
➢ Zone-HowToExamples
➢ Zone-Ideas
➢ Zone-Libraries
➢ Zone-MyTools
➢ Zone-PackageInstallers
➢ Zone-Projects
➢ Zone-Testing
1. Archived folder
The 'Archived' folder contains distribution packages of applications no longer maintained.
2. Website folder
7
5. Some good practices
Illustration 2: Organisation of 'Distributions' folder
The 'Website' folder contains information for website of the distributed applications and things
like online version files, data files beloning to certain applications and so on
3. Zone folders
Within the different 'Zone' folders there are folders named after the application they contain
distribution packages for.
Within the application folder there is a folder named after each version release number containing:
➢ A source package of that version of the application
➢ A folder for each distribution an installation package is made for
➢ (If needed) a gambas executable of that version of the application
1. Source package of that version of the application
The source packages will enable you to revert back to a previous version of the application.
2. A folder for each distribution an installation package is made for
The distribution specific folders will be made by the Gambas IDE upon making the packages
if you select so. They will contain both installation and source packages specific to that distribution.
3. A gambas executable of that version of the application
Executables make for easy quick testing by other developers or in a virtual machine. They are
not always required but come in handy in some situations.
8
5. Some good practices
Illustration 3: Application folder with version folders containing the
packages
Note that in Gambas 3 you can make packages for more than just the distributions shown
above.
5.2 Project organisation
Within the Gambas IDE you can also work on organising for your own benefit. It is good practice to make folders in there that contain specific data, like a folder for images or icons.
This can all be done from within the Gambas IDE.
Illustration 4: Organisation of a project folder in the
Gambas IDE
How this all is done will be discussed later in this guide.
5.3 Organising your code
One very important aspect of building applications is to make sure you still understand what
you where doing a year later, when you want to change parts of it or (re)use them somewhere
else.
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.
5.3.1 Commenting your code
A first good start is by putting comments into your code. Commenting in Gambas is easy. Just
start the line with '
What could you comment about. Well this is what I tend to do:
➢ Identify each class and its function
➢ Describe the functionality of each block of code in one line of comment
➢ Write comments at parts that need improvement (including ideas on improvement)
1. Identify each class and its function
This is an example of the identification comment in a class in one of my projects.
' Gambas class file
'
' --------------------------------------------------' Application: SysInfo
' Class: SysInfo
' Function: Library for system information retrieval
' Author: W.J.L. Raets
' GNU General Public Licence - Version 3
' --------------------------------------------------You could include more in there like maintenance or revisions you do in the code and the date
you did them.
This is especially useful in projects where more that one persons works on the same project.
This way all developers involved will have an idea on what has changed.
But even in your own personal projects you might be happy someday when looking back at ½
year old code for having done this.
2. Describe the functionality of each block of code in one line of comment
This again is an example of describing blocks of code by functionality in one of my projects
(see next page).
The (rest of code) blocks are quite long pieces of code, so I left them out. Without these
simple comments dividing the code into parts that are coded in that specific area I would get
lost in my own code. In the example on the next page I have made the comments bold.
So don't be sparse with commenting your application.
10
5. Some good practices
Static Public Sub ReadDesktopInfo()
Dim sWinMan, sWinManAid, sDeskAid As String
Dim iPosition, iPosB, iPosE, iSwitch As Integer
'======== Find x window manager ==============
Try Exec ["kwin", "--version"] To sWinMan
...(rest of code)
Else
CompWindowManager = Trim(sWinMan)
Endif
' === Determine desktop based on window manager ===
Select sWinManAid
Case "met"
'---- metacity & Gnome 2
… (rest of code)
Case "mut"
'---- mutter & Gnome 3
… (rest of code)
End
3. Write comments at parts that need improvement
Again, this will only help you. I have had to deal with code that worked on certain distributions
and gave errors on others.
Being clear with comments on what distros gave trouble and needed further investigation enabled me to gradually get it working on all distros.
Again an example of how that could look with the comments made bold.
Static Public Sub ReadDbInfo()
Dim sMySql, sSqlite, sPostGreSql As String
Dim iPosB, iPosE As Integer
'Stable on most returned distros - LXDE a bit troublesome
'TODO: sqlite3 needs testing results returned for analysing
'TODO: figure out sqlite retrieval on an LXDE based desktop
Try Exec ["mysql", "-V"] To sMySql
'==check for Mysql ==
… (rest of code)
End
And believe me, one day when you look back at an application you built and forgot about you
will be very happy with all your comments in your code.
Some special keywords like 'TODO: in your comments will generate an inline task. This
makes it easy tracking code, where things need to be done and also works very well as a reminder of things that still need to be done in your code.
Later in this guide I will go into this a bit further in an example application.
5.3.2 Clear choices for names
Picking the right names for variables you use in your code can make for more readable code.
Two things I tend to do are:
➢ Pick a name that describes the content
➢ Begin the name with a lower case letter identifying the type of content it represents
1. Pick a name that describes the content
11
5. Some good practices
Names of variables that suggest what their content will be, are easier to comprehend and remember 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 containing 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.
5.3.3 Indenting code
Another good practice for clear and readable code is indenting code.
For example say you want to check if some condition is met and do one thing or another depending on the result of the condition.
In Gambas you would code this with an If ...Then .. .Else. Lets say you want to test if our
sWinMan is empty or not. I will first give an example of less readable code without any indenting.
Static Public Sub Test()
Dim sWinMan As String
sWinMan = TextBox1.Text
If Len(sWinMan) = 0 Then
sWinMan = “Unable to trace”
Else
sWinMan = Trim(sWinMan)
Endif
End
Next the same code but with indenting applied for more readable and structured code.
Static Public Sub Test()
Dim sWinMan As String
sWinMan = TextBox1.Text
If Len(sWinMan) = 0 Then
sWinMan = “Unable to trace”
Else
sWinMan = Trim(sWinMan)
Endif
End
The indenting makes clear what part is executed if the condition is met and what part is executed if the condition isn't met.
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.
5.3.4 Eliminate repeating code
1. Subroutines and functions
When you find that you have code in a form class that repeats itself it would make for better
and more readable code to abstract it into a subroutine or function that can be called.
This also makes for easier maintenance for the code as you only need to change it at one
place in your form class, instead of several.
You will see examples of this in this guide.
2. Modules
When you find that you have code in several form classes repeating itself or performing likewise tasks, try to abstract it and place it in a module. This way it can be used within the entire
project.
This also makes for easier maintenance of the code as you only need to change it at one
place in the project instead on several forms classes.
Modules are actually exported classes, that is why they work for the entire project.
You will get to see some examples on using modules in this guide.
3. Classes
Classes can be considered as the templates for objects.
When having likewise code in modules in different applications you should consider making a
new project and copying the module code into classes, abstract some code and finally Export
these classes and make a library out of this application for installation on your or other
people's system.
Use this library in all the projects you have a need for its provided functionality.
This also makes for easier maintenance of the code as you only need to change it in one project (the library) instead of in each project over and over again.
The scope of this book does not cover libraries and classes, other than the Form classes.
13
6. A first GUI application: TextPlay
6 A first GUI application: TextPlay
Lets get started with using Gambas 3 and build a first simple GUI application.
6.1 What will be done in this chapter
Main focus will be creating a form with some controls, write some simple code for the controls
and run the application.
This will involve
➢ Opening Gambas IDE and make a new project
➢ Make a main form
➢ Place four controls on the form (Two buttons, a TextBox and a Label)
➢ Write some simple code
➢ Run the application from Gambas IDE
You can learn about:
➢ How to make a new project in Gambas3
➢ Working with the Gambas IDE
➢ Button, TextBox and Label controls
➢ Event driven programming, objects, methods and properties
➢ User interaction (input from user, output from application)
6.2 Starting a new project
First you start Gambas from terminal or menu depending on how you installed it5.
On first opening Gambas it should show the examples.
Illustration 5: Gambas 3.4.1 opening screen
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.
Illustration 6: 'New project' screen step 1. Select the
type of application
Select Graphical application as that is what you are going to build, a GUI application.
No further options need to be selected.
Illustration 7: 'New project' screen step 2. Select the
folder for the new project
15
6. A first GUI application: TextPlay
Browse to the folder /Development/Gambas36 and select it.
Now right click and select Create directory in the menu.
Illustration 8: Create a new folder for Learning projects
Name the folder Gambas3-Learning and select it.
Illustration 9: Select the folder 'Gambas3-Learning'
Next click button Next.
6
See 5.1. Folder organisation
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 located and the name the actual application will have. They can be different if you like.
Illustration 10: 'New project' screen step 3. Name the
project folder and project
For both 'Project name'7 and 'Project title'8 type TextPlay.
Next click the button OK and you get a message a new project has been created.
Illustration 11: Message when project has been created
successfully
7
8
Name of the folder the project will be located in and the name of installed executable.
Name of the actual application as used in a distro menu once installed.
17
6. A first GUI application: TextPlay
After clicking OK the Gambas 3 IDE opens with a new empty project named TextPlay.
Illustration 12: New project 'TextPlay' opened in Gambas 3 IDE
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.
6.3 Creating a form and controls
Next step is to create a form with some controls on it. Since you chose to create a new
'Graphical application' a form is already in place named FMain9.
You will find this form in the Project browser (zone 2) in the folder 'Sources'.
Illustration 13: FMain in Sources folder of the project
9
Note the small black arrow in the project browser in front of the FMain icon. That arrow indicates 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)
Illustration 14: Empty form in IDE
In the 'Working area' (zone 3) you see an empty form and at the right of it a box with 'Properties/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.
6.3.1 Placing controls on a form
First you will place a Label on the form.
For that you go to the ToolBox and hover your mouse over each of the icons until you find the
'Label' icon (a big A).
19
6. A first GUI application: TextPlay
Illustration 15: Label icon in
ToolBox
Click on the Label icon and next drag a rectangle on the form.
Illustration 16: Label control drawn on the form
This should give you a Label control.
Next search the ToolBox for a TextBox icon.
Illustration 17: TextBox icon
in ToolBox
20
6. A first GUI application: TextPlay
Click on the TextBox icon and next drag a rectangle on the form.
Illustration 18: TextBox control drawn on the form
This should give you a TextBox control.
Next search the Button icon in the ToolBox.
Illustration 19: Button icon in
ToolBox
Click on the Button icon and drag two rectangles on the form.
Illustration 20: Two button controls drawn on the form
This should give you two buttons.
21
6. A first GUI application: TextPlay
6.3.2 A closer look at the controls
First select the Label by clicking on it. The 'Properties/Hierarchy' Box will show properties of
the selected control, Label1.
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.
Illustration 21: Select Alignment of
the Label control
22
6. A first GUI application: TextPlay
This will align the text of the label to the right.
Illustration 22: Label1 aligned right
Next go to the 'Text' property and click on Label1 and type Enter your name:
Illustration 23: Label1 Text property changed
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'.
Illustration 24: Controls after changing the properties
Your end result should look like the illustration above.
23
6. A first GUI application: TextPlay
6.4 Coding, testing, coding, testing...
Now that you have finished the making and customising of the form and controls focus will go
to make it do something.
6.4.1 Objects, properties, events and methods
You will first need to understand some basics before continuing.
The form and all the controls you made are all objects.
There are different kinds of objects. Like the form is an object, each control is an object,
classes are objects. Some objects are creatable10, others are not.
As you have seen objects have properties, but objects can also have events and methods.
Properties are about the object. For example a Button control can have a property Text that
contains the text shown on the Button.
Events can happen to an object. For example a Button control can have the event click.
This means that when this event happens to the object you can make something happen (in
other word you need to code what needs to happen).
Methods can be done by an object. For example a Button control has the method Show.
You can use this method to show the Button or hide it.
This is a very basic explanation, but enough to comprehend what you will be doing next.
6.4.2 Write some code and test (round 1)
Now lets start with the fun part, the actual coding or writing Gambas code.
This is what you want to happen when running your code:
1. You want to type your name in the TextBox.
2. When clicking on Button 'Show' you want a message box with the name typed in the
TextBox.
3. When clicking on the Button 'Clear' you want to empty the contents of the TextBox.
Let's analyse this and divide it into two pieces:
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 being 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 clicking 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
Right click on button Show, select Event → Click.
Illustration 25: Select Event Click for button control
This will open the FMain.Class in a new tab in the 'Working Area'.
Illustration 26: FMain.class
25
6. A first GUI application: TextPlay
As you see the cursor is positioned in Public Sub Button1_Click().
In short this means that this Subroutine (Sub) belonging to object Button1 and taking place on
the Event Click is Public for Fmain.class.
Write this code for Public Sub Button1_Click():
Public Sub Button1_Click()
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():
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.
Next step is to test this little application.
For this you go to menu Debug → Run (or hit F5 on your keyboard).
Illustration 27: Menu Debug -> Run to test the application
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 appear. Click OK to close the message.
Illustration 28: Application running with message shown
Next click Clear and the TextBox will be empty.
So all seems to work as expected, but that doesn't mean you are ready yet as there certainly
is some room for improvement.
6.4.3 Code some improvements and test (round 2)
As you have seen the message box centres on the screen, the application is on the top-left of
the screen. It would look nicer if the application was centred on the screen as well.
Another thing that would be nice is that, in case no text is entered and the show button would
be clicked the message would ask you to enter some text first.
So these added requirements will mean you need to code some event belonging to Fmain to
make it appear centred on the screen.
To figure out what event to code for Fmain simply select Fmain (in case a control is selected
simply click on an empty space on the form to select it), right click and select menu Event →
Open. You will need the event Open because you want the form to centre when it opens12.
Write this code for Public Sub Form_Open():
Public Sub Form_Open()
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 TextBox1.
So you need to check the property Text if it is empty or not.
Change the code for Public Sub Button1_Click() to:
Public Sub Button1_Click()
If IsNull(TextBox1.Text) Then
'Test if name entered
Message(“First fill in a name”)
Else
Message(“The name entered is “ & TextBox1.Text)
Endif
End
IsNull(TextBox1.Text) will test if TextBox1.Text is empty13 and return True if it is. If true a message 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
Illustration 29: Message when no name entered
As you can see the application is now centred on the screen. Clicking Show results in a message to first fill in a name.
Now click OK enter a name and click Show again.
Illustration 30: Message when name entered
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
7 Extending application TextPlay
7.1 What will be done in this chapter
Main focus will be on adding some more controls and code to further explore Gambas and
run the application.
This will involve:
➢ Open an existing project for changes
➢ Add new controls (Radio Button, CheckBox, TextArea, Frame)
➢ Add/change code to events of some of the controls
➢ Run the application from IDE
You can learn about:
➢ Working with the Gambas IDE
➢ More controls
➢ More properties, events and methods
➢ User interaction
7.2 Open an existing project
First you start Gambas and it should open on the Recent Projects tab. If not click on it.
Illustration 31: Gambas welcome screen 'Recent projects'
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
7.3 Modify main form and add controls
Next step will bring us back to Fmain to redesign the form for some additional controls to be
added later.
To get get there just double click Fmain in the project browser.
Once you have the FMain in the 'Working Area' move your mouse to middle of the right border of the form.
Illustration 32: Mouse appearance will change where the pointer
is
Your pointer will change appearance and you will be able to drag the form wider. So drag the
form a bit wider.
Illustration 33: Form dragged wider and Label and TextArea
selected
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.
Illustration 34: Drag the buttons to the bottom of the form
Next select button Show, hold ctrl key and select button Clear. Drag them to the bottom of
the form.
Illustration 35: Result after adapting the form
Your form should look like in the illustration above.
32
7. Extending application TextPlay
7.3.1 Copy controls on the form
In the next step you are going to add a Label, TextBox and a Button to the form. Instead of
using the ToolBox and draw them you will simply copy and paste existing controls on the form.
For this first select the Label and TextBox and next press ctrl+c (to copy the controls). Next
press ctrl+v (to paste the controls on the form).
Illustration 36: Pasted controls on the form
Now drag the newly pasted controls below the ones already there.
Illustration 37: Controls dragged to the spot you need them
Next select one of the buttons, copy/paste it and drag it to the bottom-left of the form.
Illustration 38: Result after copy/pasting all needed controls
33
7. Extending application TextPlay
7.3.2 A closer look at the controls
Now that all the new controls are in place lets have a closer look at some of their properties.
First select the most top Label and check its Name property, Alignment property and Text
property in the 'Properties/Hierarchy' Box. Now select the other Label and do the same
check.
You will find one Label named Label1, the other named Label2. All other properties (except
for X and Y location on the form) are copied from Label1 to Label2 during the Copy/Paste of
Label1.
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:
Illustration 39: Label1 after changing the Text property
Next select TextBox1. Change the Name property to tbxFirstName. Next select TextBox2
and change the name property to tbxName.
Illustration 40: Name properties of both TextBoxes changed
Some more adaptations as a little exercise:
- Change the Name properties of the left button to btnShow
- Change the Name properties of the middle button to btnClear
- Change the Name properties of the right button to btnAdd
- Change the Text properties of the right button to Add
34
7. Extending application TextPlay
Illustration 41: Main form after the changes in the exercise
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
Illustration 42: Names of buttons changed in Fmain.class as well
You will notice that changing the name properties for Button1 and Button2 also changed their
names in the FMain.class.
Be aware that, when changing a Name property of a control on a form, only the form class the
control belongs to, will change the name in code as well.
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
Illustration 43: Main form after adding two more controls
The result should look like the illustration above.
36
7. Extending application TextPlay
7.4 Coding, testing and adapting
In this part you are first going to add new code, test it, improve it, test it again as so on.
You will not always start with the best solution but gradually work towards one and this is
done on purpose (you will be seeing more of that). This way you will learn what can and can't
be done in Gambas. You will learn what can go wrong and how to fix it. It is like learning to
ride a bicycle, it is falling down that makes for a greatest learning curve.
7.4.1 Coding and testing (round 1)
First focus will be to make the Add button do something. Since there are two input fields now
(tbxFirstName and tbxName) it would be nice to let the Add button 'add' both names together
and show them in lblResult, tbxResult and tarResult. Let's code for this.
Select button Add, right click and go to Event → Click
Type following code for Public Sub btnAdd_Click()
Public Sub bntAdd_Click()
Dim sResult As String
sResult = tbxFirstName.Text & “ “ & tbxName.Text
lblResult.Text = sResult
tbxResult.Text = sResult
txaResult.Text = sResult
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 tbxFirstName.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.
Illustration 44: Result after clicking button Add
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.
7.4.2 Adapting, coding and testing (round 2)
First have a look at the order controls will be selected when using the Tab key. For this go to
the 'Properties/Hierarchy' Box of Fmain and click on the Tab Hierarchy.
Illustration 45: Hierarchy of the controls on main form
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.
Illustration 46: Hierarchy after adaptation
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
Illustration 47: Set selected controls NoTabFocus property to True
This should take care of the Tab key order.
Now lets have a look at the code of btnClear and adapt it to meet your requirements.
Change code for Public Sub btnClear_Click() to:
Public Sub btnClear_Click()
'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
Public Sub bntAdd_Click()
Dim sResult As String
If IsNull(tbxFirstName.Text) Then
Message(“Fill in first name”)
tbxFirstName.SetFocus
Else
If IsNull(tbxName.Text) Then
Message(“Fill in name”)
tbxName.SetFocus
Else
sResult = tbxFirstName.Text & “ “ & tbxName.Text
lblResult.Text = sResult
tbxResult.Text = sResult
txaResult.Text = sResult
Endif
Endif
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.
Illustration 48: Clicking Add without filling in a name
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.
7.4.3 Adding new controls, code and test (round 3)
For the next part you need to go back to the form design.
Place three CheckBoxes and three RadioButtons on the form.
Illustration 49: Three CheckBoxes and three RadioButtons
Next run the application and click on the three CheckBoxes, then click on the three RadioButtons and note the difference.
Illustration 50: All CheckBoxes selected, only one
RadioButton
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
Here is what you need to do (yes, exercise time):
- Change RadioButton1 name properties to rbtLine1, Text properties to 1 Line
- Change RadioButton2 name properties to rbtLine2, Text properties to 2 Lines
- Delete RadioButton3
- Change CheckBox1 name properties to cbxFirstName, Text properties to Add
- Change CheckBox2 name properties to cbxName, Text properties to Add
- Change CheckBox3 Visible property to False
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:
Public Sub bntAdd_Click()
Dim sResult As String
If IsNull(tbxFirstName.Text) Then
Message(“Fill in first name”)
tbxFirstName.SetFocus
Else
If IsNull(tbxName.Text) Then
Message(“Fill in name”)
tbxName.SetFocus
Else
If rbtLine1.Value Then
sResult = tbxFirstName.Text & “ “ & tbxName.Text
Else
sResult = tbxFirstName.Text & “\n“ & tbxName.Text
Endif
lblResult.Text = sResult
tbxResult.Text = sResult
txaResult.Text = sResult
Endif
Endif
'1 line selected
'2 lines selected
'\n generates a new line
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 attention to the different result outputs when 2 Lines is selected.
42
7. Extending application TextPlay
Illustration 51: Result of 2 lines selected
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:
Public Sub bntAdd_Click()
Dim sResult As String
Dim iSwitch As Integer
'iSwitch will be used to determine what needs to be shown
iSwitch = 0
'
'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
43
7. Extending application TextPlay
'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
'
'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
If 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
End Select
lblResult.Text = sResult
txaResult.Text = sResult
Endif
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.
Select expression Case expression End Select
Select enables you to test for different results of one and the same expression.
Behind Case you need an expression
Each Case can be tested against the expression behind Select (as long as types match).
You can use Case Else for all other outcome if needed
End Select ends the code block.
Expression in example code above is iSwitch of type Integer. So behind the Case you need an
Integer value or expression to test possible outcome of iSwitch.
More on select see http://gambasdoc.org/help/lang/select?v3
44
7. Extending application TextPlay
In an expression you can use operators to make comparisons.
a < b → a smaller than b
a = b → a equals b
a <= b → a smaller than or equal to b
a > b → a bigger than b
a >= → a equal to or bigger than b
a <> b → a different from b
You can compare both number values and strings. For strings alphabetic order is used to
determine outcome.
10 = 11 → returns false
10 < 11 → returns true
“Word” = “None” → returns false
“Word” = “Word” → returns true
“Word” < “None” → returns false
“Word” >= “None” → returns true
More on operators evaluation order see http://gambasdoc.org/help/lang/evalorder?v3
More on string operators see http://gambasdoc.org/help/cat/stringop?v3
More on arithmetic operators see http://gambasdoc.org/help/cat/arithop?v3
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.
Illustration 52: Clicked button Add with only Name selected
It should all work as expected.
45
7. Extending application TextPlay
7.4.4 Add some last controls, code and test (round 4)
Lets complicate things a bit more by adding some more requirements.
First you would like to enter Country as well, and have a CheckBox to Add. Further more you
would like the option to present the information in 3 lines as well.
And last, but not least, you want to be able to determine what to Show when clicking button
Show. Outcome could be either first name, name or country.
So lets start with yet another exercise:
- Place a new Label and TextBox below Label2 and tbxName to hold the country information
- Name the new TextBox tbxCountry
- Adapt the properties of both controls to confirm to those of Label2 and tbxName
- Add a new RadioButton and name it rbtLine3
- Change rbtLine3 properties to confirm to the other two RadioButtons
- Make CheckBox3 visible again and name it cbxCountry
- Adapt properties to confirm to the other CheckBoxes
As you might notice the instructions get less detailed, so more will be up to you. This is done
intentionally. Just follow the logic of name and text properties already on the form and see if
you manage.
Don't forget to check the hierarchy of the controls on the form!
Illustration 53: New controls added and adapted
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.
Public Sub bntAdd_Click()
Dim sResult As String
Dim iSwitch As Integer
'iSwitch will be used to determine what needs to be shown
iSwitch = 0
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
Next add one line of code to the btnClear_Click routine
48
7. Extending application TextPlay
Public Sub btnClear_Click()
'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.
Illustration 54: Testing the new code
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.
Illustration 55: Selecting RadioButton 'Show' deselects
RadioButton '1 line'
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 RadioButtons 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).
Illustration 56: ToolBox tab Container showing Frame
Next select the Tab container in the ToolBox and click on Frame. Drag a frame on the form
where the cut RadioButtons used to be and name it frmShow. Set the Text to “Show”.
50
7. Extending application TextPlay
Illustration 57: Frame Show placed on form
Now with the frame selected do ctrl+v (or right click and select paste in menu)
Illustration 58: RadioButtons pasted into Frame Show
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.
Illustration 59: All RadioButtons placed in their Frames
Now let's recode the btnShow event click to meet our requirements (code see next page).
Illustration 60: RadioButtons show working as supposed
Now run and test the result. If all is well it should work.
52
7. Extending application TextPlay
Public Sub btnShow_Click()
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.
7.5.1 Do you need a button Show?
That is a very good question. You have made an application where you first need to select
what to show and then click the button Show to make it show.
So, could you not simply select what to show and it shows? That is for you to figure out.
Start with deleting the button Show. Now think about the next three questions and see if you
can answer them:
- When do you want this to happen?
- Where do you want this to happen?
- Do I have usable code in my project I can simply copy/paste?
The answer to the first question will give you the event to code, the second one the object(s)
to code (read: controls). Take a moment to think about this and try to solve it yourself, before
continuing to the answer.
A positive answer to the third question will make for a quick redo to meet the new demands.
Think about this as well and solve it yourself, before going to the answer.
7.5.2 Could iSwitch format be more clear?
As you gave seen you have used the variable iSwitch to be set accordingly to selections
made in the add CheckBoxes to determine what needs to be show in the Label and TextArea.
These are the values of iSwitch and what they represent:
Value
Represents
1
first name → 1 line
53
7. Extending application TextPlay
12
first name and name → 1 or 2 lines
2
name → 1 line
23
name and country → 1 or 2 lines
123
first name, name and country → 1, 2 or 3 lines
If you would add a next field the Value of iSwitch would get more complicated. So thinking
about these values and their format is something that can make life easier in a later stage of
development when things need to be added or changed.
So here are some more questions to think about:
- What format could do better?
- Can the current variables type (Integer) hold the improved format?
The answer to the first question will determine the outcome of the second. Again, think about
this as well and solve it yourself, before going to the answer.
7.5.3 Should the button Add be enabled if no Add is checked?
Again, good question. Should it be enabled or would it be better to enable it when a Add gets
checked and disabled when no Add is checked?
Again think about the next two questions and see if you can answer them:
- When do you want this to happen?
- Where do you want this to happen?
The answer to the first question will give you the event to code, the second one the object to
code. Take a moment to think about this and try to solve it yourself, before continuing to the
answer.
7.5.4 Should the button Clear be enabled if there is nothing to clear?
The questions keep coming. Wouldn't it be better to have button Clear enabled when TextArea and Label have content and have it disabled when no content present?
And again think about the next two questions and see if you can answer them:
- When do you want this to happen?
- Where do you want this to happen?
The answer to the first question will give you the event to code, the second one the object to
code. Take a moment to think about this and try to solve it yourself, before continuing to the
answer.
7.6 Answers to the last review
Here you will find all answers to the questions posed in 7.5. Make sure that you have first
tried to solve the answers yourself and don't be afraid of failure. There is no such thing as failure, only lessons to be learned.
And discovering how to do these thing yourself by failing and trying all over again is the method with the biggest learning curve that sticks the longest.
This is one of the main reasons I choose to start examples with code that can be improved
and show you the improvements step by step. In this way they will make more sense.
So after you tried and succeeded or not have a look at how I did it and keep in mind that
there are other possibilities as well. You might have solved it differently and have it working
just as well.
7.6.1 Do you need a button Show?
Judging the illustration on the next page I would say you don't.
54
7. Extending application TextPlay
Illustration 61: No button Show but still doing the same
job
The questions and their answers:
- When do you want this to happen?
→ As soon as one of the RadioBoxes in Frame show is clicked → RadioBoxes Click event
- Where do you want this to happen?
→ On rbtShow1, rbtShow2 and rbtShow3
- Do I have usable code in my project I can simply copy/paste?
→ parts of the btnShow code are usable
Code example:
Public Sub rbtShow1_Click()
If IsNull(tbxFirstName.Text) Then
Message(“First fill in a first name”)
Else
Message(“The first name entered is “ & tbxFirstName.Text)
Endif
End
Public Sub rbtShow2_Click()
If IsNull(tbxName .Text) Then
Message(“First fill in a name”)
Else
Message(“The name entered is “ & tbxName.Text)
Endif
End
55
7. Extending application TextPlay
Public Sub rbtShow3_Click()
If IsNull( tbxCountry .Text) Then
Message(“First fill in a country”)
Else
Message(“The country entered is “ & tbxCountry.Text)
Endif
End
Code, run and test is all that is left.
7.6.2 Could iSwitch format be more clear?
It sure can be more clear. Let's look at the questions and their answers:
- What format could do better?
→ Example:
100 → first item needs to be shown
110 → first and second item need to be shown
111 → all items need to be shown
001 → third item needs to be shown
101 → first and third item needs to be shown
….
- Can the current variables type (Integer) hold the improved format?
→ No it can't, you would need a String, because in Integer 001 would become 1. You want it
to remain 001, hence a String and in code quote “001”!!
Feel free to adapt your code to meet the new requirements. Make sure to change iSwitch into
String and adapt all 1, 12, 2, 23, 13 and 123 values accordingly. Change the iSwitch -1 value
to “000”, indicating nothing to be shown.
7.6.3 Should the button Add be enabled if no Add is checked?
No it should not be enabled. Again let's have a look at the questions and answers:
- When do you want this to happen?
→ When form opens, no Add is checked so button should be disabled → Form open event
→ When one of the Add gets checked button should be enabled → CheckBox Click event
→ When all Adds get deselected the button should disable → CheckBox Click event
- Where do you want this to happen?
→ On Fmain and cbxFirstName, cbxName and cbxCountry
Code to disable the button Add on opening the form:
Public Sub Form_Open()
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
Public Sub cbxFirstName_Click()
If (cbxFirstName.Value = 0) And (cbxName.Value = 0) And (cbxCountry.Value = 0) Then
btnAdd.Enabled = False
Else
btnAdd.Enabled = True
Endif
End
'– Since code for other checkboxes is same use cbxFirstName_Click routine to do the job -Public Sub cbxName_Click()
cbxFirstName_Click
End
Public Sub cbxCountry_Click()
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.
7.6.4 Should the button Clear be enabled if there is nothing to clear?
No it should not be enabled. And again let's have a look at the questions and answers:
- When do you want this to happen?
→ When form opens, no content so button should be disabled → Form open event
→ When Text is Added button should be enabled → btnAdd Click event
→ When Text is Cleared button should be disabled → btnClear Click event
- Where do you want this to happen?
→ On Fmain and btnAdd and btnClear
Code to disable the button Clear on opening the form:
Public Sub Form_Open()
Me.Center
btnAdd.Enabled = False
btnClear.Enabled = False
End
Add this code to the btnAdd_Click event:
57
7. Extending application TextPlay
Public Sub btnAdd_Click()
….
…..
Endif
'– Add this line at the end of the routine
btnClear.Enabled = True
End
Add this code to the btnClear_Click event:
Public Sub btnClear_Click()
….
…..
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 demonstration 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
8 Your second application: TextPlayT(w)o
8.1 What will be done in this chapter
Main focus will be string functions, for that you will built a new application.
This will involve
➢ Opening Gambas IDE and make a new project
➢ Make a main form
➢ Place fourteen controls on the form (1 TextArea, 5 TextBoxes, 2 buttons, 1 frame, 2
RadioButtons, 1 ValueBox, 2 labels)
➢ Make a search and replace form
➢ Place four controls on the form (2 TextBoxes, 2 buttons)
➢ Write some code
➢ Run the application from Gambas IDE
You can learn about:
➢ Working with the Gambas IDE
➢ Working with more than one form
➢ How to interact between forms
➢ Meaning of Subroutines, Public and Private
➢ Working with numbers
➢ Working with String functions to search and replace text
➢ Working with String functions to split text and more
➢ User interaction (input from user, output from application)
8.2 Start a new project and design the first form
Open Gambas3 IDE and start a new graphical application project named TextPlayT(w)o.
Right click Fmain and select Rename.. in the menu and name it FrmMain.
Place following controls on FrmMain with some properties pre-set:
1 TextArea: Name → txaContent; Text → empty
1 Label: Text → Split character; Alignment → Right
1 TextBox: Name → tbxSplit ; Text → empty
1 Label: Text → Number of splits; Alignment → Right
1 ValueBox: Name → vbxSplit
1 Button: Name → btnSplit; Text → Split
4 TextBoxes: Name → tbxLine1...tbxLine4; Text → empty; ReadOnly → True
1 Frame: Name → fraSearch; Text → Search or Search/Replace; Enabled → False
1 RadioButton (in fraSearch): Name → rbtSearch; Text → Search
1 RadioButton (in fraSearch): Name → rbtReplace; Text → Search/Replace
1 Button: Name → btnSearch; Text → Search; Enabled → False
When finished with placing all controls and setting all properties accordingly you should have
something like in the illustrations on the next page.
First illustration (62) shows the form in the IDE designer.
Second illustration (63) shows the form when run.
59
8. Your second application: TextPlayT(w)o
Illustration 62: Main form in IDE design mode
Illustration 63: Main form when run from IDE
8.3 Playing with text the other way around
In TextPlay(w)o you are going to start with doing the opposite of TextPlay. In TextPlay you had
input in TextBoxes and it was put together in a TextArea.
In this example you will get your input in the TextArea (one big string) and need to split it to fit
in the TextBoxes (several strings).
8.3.1 Some first coding to split the text
You start with some code to make FrmMain centre upon opening.
60
8. Your second application: TextPlayT(w)o
Public Sub Form_Open()
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 TextBoxes (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().
StringArray = Split(String As String [, Separators As String, Escape As String, ...])
Split enables you to split a string using the Separator to determine where to Split the string.
String is the string to split
Separators are the characters used to split the text. By default the seperators are not returned.
StringArray is an array of strings into where the results of Split are returned. So it contains all
the splitted string results as separate strings in one array of strings.
Split has more options than mentioned above.
Split is a String Function. String functions are functions that can be used to do work with
Strings.
More on Split see http://gambasdoc.org/help/lang/split?v3
Overview of String Functions see: http://gambasdoc.org/help/cat/string?v3
As the splitting needs to take place when btnSplit is clicked you will start with coding this
event:
Public Sub btnSplit_Click()
Dim sSplit As String[]
'String followed by [ and ] declares a string array
Dim sText As String
Dim iX As Integer
iX = 1
' Used to determine what txbLine to output to
sSplit = Split(txaContent.Text, tbxSplit.Text)
For Each sText In sSplit
Select iX
Case 1
tbxLine1.Text = sText
Case 2
tbxLine2.text = sText
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
For Each Variable In Expression Next
Repeats a loop while enumerating the object in expression
Expression must be a reference to a enumerable object like a collection or an array
Variable is the reference to the item in the enumerable object in Expression
In above code sText (variable) stands for each string item in the string array sSplit (expression)
More on For Each see http://gambasdoc.org/help/lang/foreach?v3
Now run the application and:
1. in txaContent type: Split.On.Dot.Please
1. in tbxSplit type: .
3. click btnSplit
Illustration 64: Text splitted on the dot (.)
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
Line 3 above is empty and this is line 4
1. in tbxSplit type: \n
3. click btnSplit
Illustration 65: Result of splitting on \n
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:
Public Sub btnSplit_Click()
Dim sSplit As String[]
'String followed by [ and ] declares a string array
Dim sText As String
Dim iX As Integer
iX = 1
' Used to determine what txbLine to output to
Select tbxSplit.Text
Case “\\n”
' To check for a line feed
tbxSplit.Text = Chr(10) ' To split on a line feed (=Chr(10))
End Select
sSplit = Split(txaContent.Text, tbxSplit.Text)
For Each sText In sSplit
Select iX
Case 1
tbxLine1.Text = sText
Case 2
tbxLine2.text = sText
Case 3
tbxLine3.Text = sText
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
Chr(Code As Integer) As String
Returns the character for the Code (with Code being the ASCII code)
Code needs to be a Integer value from 0 to 255
In above code Chr(10) stands for a line feed.
More on Chr() see http://gambasdoc.org/help/lang/chr?v3
Overview of String Functions see: http://gambasdoc.org/help/cat/string?v3
Now run the application again and do the same test as done before.
Illustration 66: Renewed result of splitting on "\n"
Seems you have a perfect split on “\n” or a line feed.
Note that once clicking btnSplit the content of tbxSplit contains Chr(10). Because TextBoxes
are single line they represent it with this symbol instead of going to a new line.
8.3.2 Determine the number of splits
Now that the split works as needed focus is on the numbers of splits you want.
Step 1: Implement to take number of splits into account
As you have 4 lines to show the splitted strings it would be great if you entered 2 in number of
splits and only 2 where shown, or enter 1 and only one is shown.
So you will again need to recode btnSplit event to make that happen:
64
8. Your second application: TextPlayT(w)o
Public Sub btnSplit_Click()
Dim sSplit As String[]
'String followed by [ and ] declares a string array
Dim sText As String
Dim iX, iNumSplits As Integer
iX = 1
' Used to determine what txbLine to output to
iNumSplits = vbxSplit.Value ' Used to determine number of splits
Select tbxSplit.Text
Case “\\n”
' To check for a line feed
tbxSplit.Text = Chr(10) ' To split on a line feed (=Chr(10))
End Select
sSplit = Split(txaContent.Text, tbxSplit.Text)
For Each sText In sSplit
If iX <= iNumSplits Then
Select iX
Case 1
tbxLine1.Text = sText
Case 2
tbxLine2.text = sText
Case 3
tbxLine3.Text = sText
Case 4
tbxLine4.Text = sText
End Select
iX = iX + 1
Endif
Next
End
Now check if it works by running the application
Illustration 67: Result of splitting on "\n" showing 2 lines
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:
Public Sub btnSplit_Click()
Dim sSplit As String[]
'String followed by [ and ] declares a string array
Dim sText As String
Dim iX, iNumSplits As Integer
iX = 1
' Used to determine what txbLine to output to
iNumSplits = vbxSplit.Value ' Used to determine number of splits
ClearLines
'This starts a subroutine
Select tbxSplit.Text
Case “\\n”
' To check for a line feed
tbxSplit.Text = Chr(10) ' To split on a line feed (=Chr(10))
End Select
sSplit = Split(txaContent.Text, tbxSplit.Text)
For Each sText In sSplit
If iX <= iNumSplits Then
Select iX
Case 1
tbxLine1.Text = sText
Case 2
tbxLine2.text = sText
Case 3
tbxLine3.Text = sText
Case 4
tbxLine4.Text = sText
End Select
iX = iX + 1
Endif
Next
End
Private Sub ClearLines()
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'
[Static] {Public | Private} {Procedure | Sub} Identifier(Parameter As Datatype.....)
Identifier is the name of the subroutine or procedure
Parameter is/are values that can be passed to the subroutine/procedure when calling it. You
have to declare a data type for each parameter used.
A subroutine or procedure does not return any values. Use a function for that.
More on Sub see http://gambasdoc.org/help/lang/sub?v3
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
Illustration 68: Split for 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)
Seems that all is working as expected.
8.4 Search for text
For this part you first need to make a new form. The new form is going to serve as a window
to enter the search string.
8.4.1 Make a new form
To make a new form in the Project Browser right click Sources. In the menu select New →
Form.
Illustration 70: Ad a new form to the project
68
8. Your second application: TextPlayT(w)o
Name the form FrmSearchReplace.
Illustration 71: Dialog to name the form
Place following controls on FrmSearchReplace with some properties pre-set:
1 TextBox: Name → tbxSearch ; Text → Enter a string to search...
1 Button: Name → btnSearch; Text → Search
Illustration 72: FrmSearchReplace with controls placed
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)
Public Sub Form_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
8.4.2 Make FrmSearchReplace open from btnSearch on FrmMain
Double click FrmMain in the Project Browser and next select btnSearch.
As you might remember btnSearch was disabled. So in btnSearch properties set enabled to
True. Next right click the selected btnSearch and in the menu select Event → Click.
This will open the Tab FrmMain.class ready to code the click event of btnSearch.
Public Sub btnSearch_Click()
FrmSearchReplace.Show
End
What you do here is call the method Show of FrmSearchReplace. So you tell the FrmSearchReplace 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
Illustration 73: FrmSearchReplace opened from btnSearch
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.
8.4.3 Project intermezzo: Form class interaction explained
You already had a first glimpse at Private and Public declarations. With two forms at hand this
is going to start making sense.
The requirement of having to search a string entered in a TextBox on one form to be
searched in a TextArea on another form and then have the result selected in that TextArea requires you to understand the difference in Private and Public.
They are the basis of what will and will not be available to other Form classes to use in their
code.
By default coded events (named subs, procedures or methods) of controls you draw on a
form are Public.
So in our project what can one form use from the other?
Let's make an overview and see what is available and what is not.
Public in FrmSearchReplace are:
Methods
Form_Open
Private in FrmSearchReplace are:
Methods
Public in FrmMain are:
Methods
Form_Open
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 FrmSeachReplace.class (= all the code for the form).
Write the following code to the btnSeach click event:
Public Sub btnSearch_Click()
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.
Illustration 74: Running btnSplit code from btnSearch on another form
What actually happened upon clicking btnSearch on the Search form is that code from another 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
Illustration 75: Interaction between methods in different form classes
You can now remove the code from btnSearch in FrmSearchReplace class as it was just an
example.
Back to our problem to solve in this project.
There are two possible approaches:
1. Code the searching on form FrmSearchReplace
2. Code the searching on form FrmMain
In both approaches it comes down to get the string that needs to be searched and perform a
search. The code for searching will not be that different. What it comes down to is what is the
best approach in getting the string and next selecting it when found.
Let's have a look at both approaches and see what fits best.
1. Code the searching on form FrmSearchReplace
So what you need to get is the content from txaContent.Text. This means declaring a Public
variable as String and make sure every time txaContent.Text is changed the string is passed
to the variable.
Next search can be performed and then somehow the result has to be selected in txaContent
while it isn't even Public!!
All in all a tough road to walk that requires a lot of extra coding.
2. Code the searching on form FrmMain
What you need here is pass the string to be searched from FrmSearchReplace to FrmMain,
perform the search and select the result in txaContent.
As all takes place on FrmMain this is a much easier approach. All that needs to be done is
pass a string from one form to another, nothing more.
What you need is a method (sub or procedure) on FrmMain that can pass an argument, perform the search and select the result.
8.4.4 Back on track to code a Public method on FrmMain
First check out how passing arguments in a methods works.
73
8. Your second application: TextPlayT(w)o
In FrmMain class write following code:
Public Sub SearchString(StringToSearch As String)
Message(StringToSearch)
End
StringToSearch is a string value that gets passed to the method upon calling it.
In FrmSearchReplace class write following code:
Public Sub btnSearch_Click()
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!
Illustration 76: Search string passed as argument of a Public method
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.
8.4.5 Lets search some string
Search a string and select it in tarContent when found is the mission to complete.
For that you need to code the method SearchString in FrmMain class:
74
8. Your second application: TextPlayT(w)o
Public Sub SearchString(StringToSearch As String)
Dim iB, iL As Integer
iB = 1
iB = InStr(tarContent.Text, StringToSearch, iB) 'Determines the start position of string found
iL = Len(StringToSearch)
'Determines length of the string
If iL > 0 Then
tarContent.Select(iB - 1, iL)
'Select the found string only when length > 0
Endif
End
Position = Instr(String As String , Substring As String [, Start As Integer, ...])
Instr enables you to search a string to determine its start position.
Position is the start position of the string found (0 when nothing found)
String is the string value that will be searched
SubString is the string value that you are searching for
Start is the position you want the search to begin
Instr has more options than mentioned above.
Instr is a String Function. String functions are functions that can be used to do work with
Strings.
More on Instr see http://gambasdoc.org/help/lang/instr?v3
Overview of String Functions see: http://gambasdoc.org/help/cat/string?v3
Length = Len(Args As String)
Len enables you to determine the length of a string
Length is the length of the string in arguments Args (0 when empty)
Args is the string value you want to determine the length of
Lenght is determined by byte count of the string. ASCII characters take up one byte.
Characters like ü or é (UTF-8) take up two bytes and thus will count for two!!
Len is a String Function. String functions are functions that can be used to do work with
Strings.
More on Len see http://gambasdoc.org/help/lang/len?v3
Overview of String Functions see: http://gambasdoc.org/help/cat/string?v3
Now run the application and do some testing.
In txaContent write:
I am looking for my name
Have you seen my name
It is Willy they tell me
Please search for my name
Next click btnSearch on the main form to open the Search form.
In the Search form type “Willy” (without the quotes) and click Search.
Willy should be selected in txaContent on the main form.
75
8. Your second application: TextPlayT(w)o
Illustration 77: Seems like search performs as expected
All should work as expected and select the searched string when found, select nothing when
nothing is found.
8.5 Search and replace text
Before you can start searching and replacing string you will need to add some controls to you
current FrmSearchReplace.
8.5.1 Prepare the forms for Search and Replace
In the IDE click FrmSearchReplace in the Project Browser.
Place following controls on FrmSearchReplace with some properties pre-set:
1 TextBox: Name → tbxReplace ; Text → Enter the replace string...
1 Button: Name → btnReplace; Text → Replace
Fastest method is to select tbxSearch and btnSeach, copy and paste them onto the form,
drag them to the proper location and adapt the properties Name and Text.
Illustration 78: Replace TextBox and Button added to FrmSearchReplace
Next click FrmMain in the Project Browser
Select fraSearch and set the property Enabled to True
76
8. Your second application: TextPlayT(w)o
Illustration 79: FrmSearch property Enabled set to true on FrmMain
With the frame for choosing between Search and Search/Replace enabled and FrmSearchReplace prepared for Replacing you are set for the next step.
8.5.2 Making FrmSearchReplace appear depending on selection in FrmMain
When clicking button Search on FrmMain you want FrmSearchReplace to appear different
depending on what was selected in the fraSearch (a Frame).
When Search is selected FrmSearchReplace has to:
- have caption Search
- show search field
- show search button
When Search/Replace is selected FrmSearchReplace has to:
- have caption Search and Replace
- show search and replace fields
- show search button
- show replace button
You will start with FrmMain to get the fraSearch and RadioButtons to work:
' -- Used to determine how FrmSearchReplace is shown 1=search, 2=replace -Public SearchReplace As Byte
Public Sub Form_Open()
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 execute 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
Boolean
Byte
Short
Integer
Long
Single
Float
Date
String
Variant
Object
Pointer
Description
True or False
0 to 255
-32.768 to 32.767
-2.147.483.648 to 2.147.438.647
-9.223.372.036.854.775.808 to 9.223.372.036.854.775.807
single precision floating-point type
double precision floating-point type
Date and time each stored in an Integer
A variable length string of characters
Any datatype
Anonymous reference to any object
A memory address
Default value
False
0
0
0
0
0.0
0.0
Null
Null
Null
Null
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:
Public Sub rbtSearch_Click()
SearchReplace = 1 'search
End
Code for event click of rbtReplace:
Public Sub rbtReplace_Click()
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 replace.
Now let's make that happen. For this you need to code the Open event of FrmSearchReplace:
Public Sub Form_Open()
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
Illustration 80: Search shown when search selected
Illustration 81: Search and Replace shown when search/replace selected
79
8. Your second application: TextPlayT(w)o
8.5.3 Replace searched strings
To replace a string you again will write a Public method for FrmMain that does all the replacing.
In FrmMain write following code:
Public Sub ReplaceString(StringToReplace As String, StringToReplaceWith As String)
txaContent.Text = Replace(txaContent.Text, StringToReplace, StringToReplaceWith)
End
Now all that you need to do is run above code when button Replace is clicked.
In FrmSearchReplace write following code:
Public Sub btnReplace_Click
FrmMain.ReplaceString(tbxSearch.Text, tbxReplace.Text)
End
Again all you do is pass some arguments (being the search and replace strings) to the method ReplaceString to be dealt with accordingly.
Result = Replace(String As String, Pattern As String, ReplaceString As String[, ...])
Replace enables you to search a string and replace it with another string.
Result is the outcome of String with Pattern replaced by ReplaceString
String is the string value that will be searched
Pattern is the string value that you are searching for
ReplaceString is the string value that Pattern will be replaced by
Replace has more options than mentioned above.
Replace is a String Function. String functions are functions that can be used to do work with
Strings.
More on Replace see http://gambasdoc.org/help/lang/replace?v3
Overview of String Functions see: http://gambasdoc.org/help/cat/string?v3
Now run the application for some testing
In txaContent write:
Try to replace Willy
with silly if you can
First search for it, next click Replace
So go ahead type above lines, next type Willy in Search field and click button Search. If that
works type silly in the Replace field and click button Replace.
If all is well Willy should now be silly (see illustrations on the next page).
Play with it for a while and see what can and can't be done.
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
Illustration 82: Search still works well
Illustration 83: Replace does a good job as well
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
9 Your third application: NumPlay
9.1 What will be done in this chapter
Main focus will be numerical data, for that you will built a new application.
This will involve
➢ Opening Gambas IDE and make a new project
➢ Make a main form
➢ Place a number of controls on the form
➢ Write some code
➢ Run the application from Gambas IDE
You can learn about:
➢ Working with the Gambas IDE
➢ Working with numeric data, date and time
➢ Error handling
➢ Working with Arithmetical functions and Date & Time functions
➢ Working with Localization and Translation functions
➢ Transfer numeric data in strings to numerical data types
➢ User interaction (input from user, output from application)
➢ Enumeration
9.2 Start a new project and design a form
Open Gambas3 IDE and start a new graphical application project named NumPlay.
Rename form FMain to FrmMain. Do this by right clicking FMain in the Project Browser and
next click Rename.
Place following controls on FrmMain with some properties pre-set:
1 ValueBox: Name → vbxNum1
1 ValueBox: Name → vbxNum2
1 Label: Name → lblOperator ; Text → empty; Alignment → Right
1 Separator
1 ValueBox: Name → vbxResult
1 Label: Name → lblResult ; Text → empty; Alignment → Right
1 Button: Name → btnCalc; Text → Calculate
1 Frame: Name → fraOperator; Text → Operator
1 RadioButton (in fraOperator): Name → rbtAdd; Text → +
1 RadioButton (in fraOperator): Name → rbtSubtract; Text → 1 RadioButton (in fraOperator): Name → rbtMultiply; Text → *
1 RadioButton (in fraOperator): Name → rbtDivide Text → /
1 RadioButton (in fraOperator): Name → rbtPower Text → ^
When finished with placing all controls and setting all properties accordingly you should have
something like in the illustrations on the next page.
First illustration (84) shows the form in the IDE designer.
Second illustration (85) shows the form when run.
82
9. Your third application: NumPlay
Illustration 84: FrmMain after placing all controls
Illustration 85: FrmMain when run
9.3 Doing the maths
In NumPlay you are going to work with numbers and calculations. Along the road you'll also
have a look at numerical data shown in text based controls and in using input from text based
controls for calculations.
83
9. Your third application: NumPlay
9.3.1 Analyse the needs and determine a strategy
Based on the operator clicked you need to do some things.
To begin with lblOperator needs to show the calculation operation to be done when clicking
btnCalc. Lets start by doing this first.
You know that each RadioButtons text property holds the operation. This only needs to put
placed in the lblOperator text property. For this you need to code the Click event of each RadioButton:
Public Sub Form_Open()
Me.Center
rbtAdd_Click
'To ensure lblOperator shows +
End
Public Sub rbtAdd_Click()
lblOperator.Text = rbtAdd.Text
End
Public Sub rbtSubtract_Click()
lblOperator.Text = rbtSubtract.Text
End
Public Sub rbtMultiply_Click()
lblOperator.Text = rbtMultiply.Text
End
Public Sub rbtDivide_Click()
lblOperator.Text = rbtDivide.Text
End
Public Sub rbtPower_Click()
lblOperator.Text = rbtPower.Text
End
Now run the application and see what happens when clicking the RadioButtons.
Illustration 86: lblOperator shows selected Operator
84
9. Your third application: NumPlay
Next challenge is to make the calculations based on the selected operator.
So when clicking btnCalc you need to perform the selected operation on the values entered in
vbxNum1 and vbxNum2 and return the result in vbxResult.
Clearly the Operation selection is centrally crucial in all that needs to happen. Somehow
when clicking btnCalc you need to determine what RadioButton is selected and act accordingly.
There are several possible approaches, one of them is using a switch that is set when a RadioButton is clicked.
This is how the switch value could represent the Operator
Operator:
+
*
/
^
Switch value:
0
1
2
3
4
To implement this some code needs to be added:
Private iSwitch As Integer
Public Sub Form_Open()
Me.Center
rbtAdd_Click
'To ensure lblOperator shows +
End
Public Sub rbtAdd_Click()
lblOperator.Text = rbtAdd.Text
iSwitch = 0
End
Public Sub rbtSubtract_Click()
lblOperator.Text = rbtSubtract.Text
iSwitch = 1
End
Public Sub rbtMultiply_Click()
lblOperator.Text = rbtMultiply.Text
iSwitch = 2
End
Public Sub rbtDivide_Click()
lblOperator.Text = rbtDivide.Text
iSwitch = 3
End
Public Sub rbtPower_Click()
lblOperator.Text = rbtPower.Text
iSwitch = 4
End
Public Sub btnCalc_Click()
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
Illustration 87: Console output in IDE
Using the Print instruction will output to the IDE console during runtime. It is a way of checking 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 requirements.
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
Public Sub btnCalc_Click()
Select iSwitch
Case 0
vbxResult.Value = vbxNum1.Value + vbxNum2.Value
Case 1
vbxResult.Value = vbxNum1.Value – vbxNum2.Value
Case 2
vbxResult.Value = vbxNum1.Value * vbxNum2.Value
Case 3
vbxResult.Value = vbxNum1.Value / vbxNum2.Value
Case 4
vbxResult.Value = vbxNum1.Value ^ vbxNum2.Value
End Select
End
Now run the application, enter 10 and 2 for values and try all calculations.
Illustration 88: Calculating values 10 and 2
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.
Illustration 89: Division by zero error
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).
9.3.2 Implement error handling
This is a good time to introduce some error handling. What you would like to know is the error
code. This is a number that can be used to indicate what went wrong.
Add some code to the btnCalc click event:
Public Sub btnCalc_Click()
Select iSwitch
Case 0
vbxResult.Value = vbxNum1.Value + vbxNum2.Value
Case 1
vbxResult.Value = vbxNum1.Value – vbxNum2.Value
Case 2
vbxResult.Value = vbxNum1.Value * vbxNum2.Value
Case 3
vbxResult.Value = vbxNum1.Value / vbxNum2.Value
Case 4
vbxResult.Value = vbxNum1.Value ^ vbxNum2.Value
End Select
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
Illustration 90: Error 26 returned
Now that you know that error 26 occurs when trying to divide by zero you can Catch the error
and code it to do what you would like to happen.
In this case you would like to notify the user that it is not allowed to divide by zero and maybe
even set the focus to the second value.
Adapt the code for Catch accordingly
Public Sub btnCalc_Click()
Select iSwitch
Case 0
vbxResult.Value = vbxNum1.Value + vbxNum2.Value
Case 1
vbxResult.Value = vbxNum1.Value – vbxNum2.Value
Case 2
….
End Select
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
Illustration 91: Division by zero now handled properly
As you can see the application no longer allows division by zero and informs the user. All happens without hanging the application.
9.4 Working with numbers in text variables and text controls
Next you will have a look if numbers entered in a text control or held by a text variable (String)
can be used for calculations.
Place following controls on FrmMain with some properties pre-set:
1 TextBox Name → tbxNum1
1 TextBox: Name → tbxNum2
1 TextBox: Name → tbxResult
1 Button: Name → btnCalcText; Text → Calc text
1 TextBox: Name → tbxOneLine
When finished with placing all controls and setting all properties accordingly you should have
something like in the following illustrations.
Illustration 92: FrmMain after adding some controls
90
9. Your third application: NumPlay
9.4.1 Simple beginnings
As the title says, you are going to begin simple. Simple in this case means you right clicl on
button 'Call Text' and in pop p menu select Event → Click.
This will bring you to the code editor ready to code the click event of btnCalcText.
Now copy all the code in between Public Sub btnCalc_Click() and End () (so the code of
the entire routine except Public Sub … and End()) and paste it into the Public Sub btnCalcText_Click() event.
Next change all vbx... control names to tbx.. control names and the .Value to .Text. The result
should look like below
Public Sub btnCalcText_Click()
Select iSwitch
Case 0
tbxResult.Text = tbxNum1.Text + tbxNum2.Text
Case 1
tbxResult.Text = tbxNum1.Text – tbxNum2.Text
Case 2
tbxResult.Text = tbxNum1.Text * tbxNum2.Text
Case 3
tbxResult.Text = tbxNum1.Text / tbxNum2.Text
Case 4
tbxResult.Text = tbxNum1.Text ^ tbxNum2.Text
End Select
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 buttons to see what happens.
Illustration 93: Calculating the text seems to work
91
9. Your third application: NumPlay
You will notice that calculating the text values seem to work out of the box.
9.4.2 Next challenge
Let's try something more challenging. Let's say you want to type '2 + 3' into txbOneLine, next
click btnCalcText and see the result in tbxResult. Something quite different.
For this you will need to get the two numbers and the operator out of a string. You can use
string functions to get this done.
Next you will need to transform the string numbers to numbers and determine what operator
to use on the two numbers. Last step is to return the result to tbxResult.
So back to the code editor in IDE to change the code to:
Public Sub btnCalcText_Click()
Dim sOperator, sHelp As String
Dim iB As Integer
Dim iNum1, iNum2 As Float
'-- find the first number –
iB = 1
iB = InStr(tbxOneLine.Text, " ", iB)
sHelp = Mid(tbxOneLine.Text, 1, iB – 1)
iNum1 = Val(sHelp)
'-- find the operator –
INC iB
sOperator = Mid(tbxOneLine.Text, iB, 1)
'-- find the next number –
iB = InStr(tbxOneLine.Text, " ", iB)
sHelp = Mid(tbxOneLine.Text, iB + 1, Len(tbxOneLine.Text) – iB)
iNum2 = Val(sHelp)
Select sOperator
Case "+"
tbxResult.Text = iNum1 + iNum2
Case "-"
tbxResult.Text = iNum1 – iNum2
Case "*"
tbxResult.Text = iNum1 * iNum2
Case "/"
tbxResult.Text = iNum1 / iNum2
Case "^"
tbxResult.Text = iNum1 ^ iNum2
Case Else
'– show a warning if an illegal operator is provided -Message.Warning("Unknown operator: " & sOperator)
End Select
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 arithmetical 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 documentation 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.
Illustration 94: Division by zero taken care off
Illustration 95: Unknown operator taken care off
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 before 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 comprehension 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
Public Sub btnCalcText_Click()
...
sHelp = Mid(tbxOneLine.Text, 1, iB – 1)
If IsNumber(sHelp) Then
iNum1 = Val(sHelp)
Else
Message.Error(sHelp & " is no number")
Stop Event
Endif
'-- find the operator –
iB += 1
...
sHelp = Mid(tbxOneLine.Text, iB + 1, Len(tbxOneLine.Text) – iB)
If IsNumber(sHelp) Then
iNum2 = Val(sHelp)
Else
Message.Error(sHelp & " is no number")
Stop Event
Endif
Select sOperator
...
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 running 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
9.5 How about date and time
Next to numbers you will probably need to handle date and time information in some of the
applications you plan to built.
Let's have a look at that.
Place following controls on FrmMain with some properties pre-set:
1 DateBox Name → dbxDate
1 TextBox: Name → tbxDate1
1 TextBox: Name → tbxDate2
1 ValueBox: Name → vbxDate
When finished with placing all controls and setting all properties accordingly you should have
something like in the following illustrations.
95
9. Your third application: NumPlay
Illustration 96: Some extra controls added to play with date and time
9.5.1 Adding some code
First thing you are going to do is make sure that when selecting a date, the value representing the date is shown in vbxDate, the date part is shown in tbxDate1 and the time part is
shown in tbxDate2.
Select the DateBox and right click. In menu select Event → Change. Next type following
code:
Public Sub dbxDate_Change()
Dim iDays As Days
If Not IsNull(dbxDate.Value) Then
iDays = dbxDate.Value
vbxDate.Value = iDays
tbxDate1.Text = Format(dbxDate.Value, "dd-mm-yyyy")
tbxDate2.Text = Format(dbxDate.Value, "hh:nn:ss")
Endif
End
First thing you might notice is that dbxDate.Value returns a number of days if put into an Integer. 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-092013'. 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
String = Format(Expression, [, Format ])
Converts the expression into a string by using the format that depends on the type of
expression
Expression is the variable that will hold the value that will be converted
Format is the format description (how it needs to be returned)
The function can format date, times, numbers and currency.
Format is a Localization and Translation Function. These functions are useful when dealing
with translations (language) and localisation (currency settings and such).
More on Format see: http://gambasdoc.org/help/lang/format?v3
More on user defined formats see: http://gambasdoc.org/help/cat/userformat?v3
Overview of Localization and Translation Functions see:
http://gambasdoc.org/help/cat/localize?v3
Run the application and see what it returns when selecting a date. Next try the selecting the
next day and see the value below the DateBox go up with 1.
Illustration 97: After Date is selected the other controls are updated
accordingly
9.5.2 More date and time
To learn some more about date and time you will need to add one more control to your form.
This control is a special control named Timer.
You place it on your form but it will not be seen during runtime. Check the illustration on the
next page to see where it is located.
Place following control on FrmMain with some properties pre-set:
1 Timer Name → tmrInterval; Enabled → True
The Timer is a virtual object that gets triggered in a certain interval and runs the code you
would like. The interval is determined by setting the Timer property Delay (in milliseconds).
The timer can be placed anywhere on the form itself.
97
9. Your third application: NumPlay
Illustration 98: Timer object can be found in the toolbox on tab
'Special'
Illustration 99: Timer object can be anywhere on the form
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
Public Sub tmrInterval_Timer()
tbxDate1.Text = Format(Now, "ddd mmm yyyy hh:nn:ss")
tbxDate2.Text = Format(Now, "hh:nn:ss:uu")
End
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
9.6 Another approach, enumerate
It was brought to my attention by Alain, one or our contributors, that NumPlay provided an excelent occasion to explain enumerating. So, thanks to Alain, here is a little extra added to the
chapter.
9.6.1 iSwitch enumerated
Earlier on (in 9.3.1) you used the Integer variable iSwitch and based on its value determined
what operator to use.
This is how the switch value represented the Operator in 9.3.1:
Operator:
+
*
/
^
Switch value:
0
1
2
3
4
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:
Private iSwitch As Integer
'– line below is added -Private ENUM PlusSign=0, MinusSign=1, MultiplySign=2, DivideSign=3, PowerSign=4
Public Sub Form_Open()
Me.Center
rbtAdd_Click
'To ensure lblOperator shows +
End
Public Sub rbtAdd_Click()
lblOperator.Text = rbtAdd.Text
iSwitch = PlusSign
'← changed
End
Public Sub rbtSubtract_Click()
lblOperator.Text = rbtSubtract.Text
iSwitch = MinusSign
'← changed
End
Public Sub rbtMultiply_Click()
lblOperator.Text = rbtMultiply.Text
iSwitch = MultiplySign
'← changed
End
Public Sub rbtDivide_Click()
lblOperator.Text = rbtDivide.Text
iSwitch = DivideSign
'← changed
End
Public Sub rbtPower_Click()
lblOperator.Text = rbtPower.Text
iSwitch = PowerSign
'← changed
End
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
10 Your fourth application: ImagePlay
10.1 What will be done in this chapter
Main focus will be images. for that you will built a new application.
This will involve
➢ Opening Gambas IDE and make a new project
➢ Make a main form
➢ Place a number of controls on the form
➢ Write some code
➢ Run the application from Gambas IDE
You can learn about:
➢ Working with the Gambas IDE
➢ Working with images
➢ Working with project file paths
➢ User interaction (input from user, output from application)
10.2 Start a new project and design a form
Open Gambas3 IDE and start a new graphical application project named ImagePlay.
Rename form FMain to FrmMain. Do this by right clicking FMain in the Project Browser and
next click Rename.
Place following controls on FrmMain with some properties pre-set:
1 PictureBox: Name → pbxOne; Width → 128; Height → 128
1 PictureBox: Name → pbxTwo; Width → 128; Height → 128
1 Label: Name → lblDimOne ; Text → empty; Alignment → Center
1 Label: Name → lblDimTwo ; Text → empty; Alignment → Center
1 Button: Name → btnSwitch; Text → Switch Image
When finished with placing all controls and setting all properties accordingly you should have
something like in the next illustration.
Illustration 101: Controls placed on FrmMain
102
10.
Your fourth application: ImagePlay
10.3 Let me see some images
10.3.1 Making some images
Before getting started with coding, you will need some images. You will create some new
ones right in the Gambas IDE.
First, in the Project Browser, right click the folder Data and in the menu click New → Folder.
Name the folder Images
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 MyImage, 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.
Illustration 103: Made some modern art 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 NextImage.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).
Illustration 105: Make panel appear
You will find more of these panels that can be visible or not. So now you know what to look
for.
10.3.2 Make the images appear
Mission is to make the images you have just created visible. For this you will go the the properties of both images and set the Picture property.
For this first select pbxOne and in the Properties/Hierarchy panel look for Picture. Click the
… to open the 'Select a Picture' form. In the left pane click open the folder Image and select
MyImage.png in the right panel.
104
10.
Your fourth application: ImagePlay
Illustration 106: Opening the 'Select a picture' form
Next click OK and see the image in the Form Designer.
Illustration 107: Image 'MyImage.png' in PictureBox picOne
Now do the same for pbxTwo, but use NextImage.png
Illustration 108: Both images in their PictureBox
105
10.
Your fourth application: ImagePlay
Now right click the form and select Event → Open and add next code:
Public Sub Form_Open()
Me.Center
End
Time to run the application and have a look at what you just created.
Illustration 109: Running ImagePlay for the first time
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 property 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
Public Sub btnSwitch_Click()
Dim picTemp As Picture
picTemp = pbxOne.Picture
pbxOne.Picture = pbxTwo.Picture
pbxTwo.Picture = picTemp
End
Run the application and click 'Switch picture' to see if it works.
Illustration 110: Clicking the button switches the images between the
PictureBoxes
10.3.3 Code the labels
There are still two labels on the form that need some coding. The labels will be used to show
the dimensions of the loaded image in the PictureBoxes above.
For this you will need to read the Picture properties Width and Height.
Back to coding:
Public Sub Form_Open()
Me.Center
lblDimOne.Text = pbxOne.Picture.Width & " x " & pbxOne.Picture.Height & " pixels"
lblDimTwo.Text = pbxTwo.Picture.Width & " x " & pbxTwo.Picture.Height & " pixels"
End
Run the application to see the result.
107
10.
Your fourth application: ImagePlay
Illustration 111: Labels now showing the image dimensions
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 BigImage.png (256 x 256).
Illustration 112: Two more png images made in the editor
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 Picture property. Once done run the application again and see what it looks like.
108
10.
Your fourth application: ImagePlay
Illustration 113: Running the application with the new images
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 attention.
Try clicking button 'Switch Image' and see what happens.
Illustration 114: Images switch but labels show wrong dimensions
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 PictureBoxes, the Alignment will center the image in the PictureBoxes.
Next more code is needed to make the Labels show the proper dimensions.
Public Sub btnSwitch_Click()
Dim picTemp As Picture
picTemp = pbxOne.Picture
pbxOne.Picture = pbxTwo.Picture
pbxTwo.Picture = picTemp
lblDimOne.Text = pbxOne.Picture.Width & " x " & pbxOne.Picture.Height & " pixels"
lblDimTwo.Text = pbxTwo.Picture.Width & " x " & pbxTwo.Picture.Height & " pixels"
End
Now run the application again.
Illustration 115: All works as expected
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
Public Sub Form_Open()
Me.Center
ShowDimensions
End
Public Sub btnSwitch_Click()
Dim picTemp As Picture
picTemp = pbxOne.Picture
pbxOne.Picture = pbxTwo.Picture
pbxTwo.Picture = picTemp
ShowDimensions
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
10.4 Loading images using code
Last part of image handling you will have a look at is loading the images using code.
For this you will need to add some more controls to the form.
Place following controls on FrmMain with some properties pre-set:
1 Button: Name → btnOneMy; Text → Load My
1 Button: Name → btnOneSmall; Text → Load Small
1 Button: Name → btnTwoNext Text → Load Next
1 Button: Name → btnTwoBig; Text → Load Big
When finished with placing all controls and setting all properties accordingly you should have
something like in the next illustration.
Illustration 116: All new controls placed on FrmMain
111
10.
Your fourth application: ImagePlay
10.4.1 The mission
Now that controls are in place this is what needs to be done:
1. btnOneMy needs to load MyImage.png into pbxOne upon clicking
2. btnOneSmall needs to load SmallImage.png into pbxOne upon clicking
3. btnTwoNext needs to load NextImage.png into pbxTwo
4. btnTwoBig needs to load BigImage.png into pbxTwo
To load an image into a PictureBox property Picture you will use Picture.Load.
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.
Illustration 117: Project
folder structure
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.
Illustration 118: Auto-complete function of IDE will recognise the path
16
More on paths and Gambas: http://gambasdoc.org/help/cat/path
112
10.
Your fourth application: ImagePlay
The code looks like this:
Public Sub btnOneMy_Click()
pbxOne.Picture = Picture.Load("Images/MyImage.png")
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
After this all it takes is run and test.
Illustration 119: The pictures seem to load but the labels aren't adapted
10.4.2 Make the labels work again
Because you made a routine for updating the labels content, it shouldn't be to hard to get the
labels to work as needed.
Simply call the routine from each button click event should do the trick.
This is what is looks like:
113
10.
Your fourth application: ImagePlay
Public Sub btnOneMy_Click()
pbxOne.Picture = Picture.Load("Images/MyImage.png")
ShowDimensions
End
Public Sub btnOneSmall_Click()
pbxOne.Picture = Picture.Load("Images/SmallImage.png")
ShowDimensions
End
Public Sub btnTwoNext_Click()
pbxTwo.Picture = Picture.Load("Images/NextImage.png")
ShowDimensions
End
Public Sub btnTwoBig_Click()
pbxTwo.Picture = Picture.Load("Images/BigImage.png")
ShowDimensions
End
Again, run the application to see if the adaptation to the code works.
Illustration 120: Loading images now adapts the Labels accordingly
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
11 Your fifth application: SimpleTextEditor
11.1 What will be done in this chapter
Main focus will be loading and saving data and menus. for that you will built a new application.
This will involve
➢ Opening Gambas IDE and make a new project
➢ Make a main form
➢ Place a number of controls on the form
➢ Make a menu and a toolbar
➢ Write some code
➢ Run the application from Gambas IDE
You can learn about:
➢ Working with the Gambas IDE
➢ Saving data to file
➢ Opening a saved file
➢ Making menus and coding them
➢ Making Toolbars and coding them
➢ Working with local file paths
➢ User interaction (input from user, output from application)
11.2 Start a new project and design a form
Open Gambas3 IDE and start a new graphical application project named SimpleTextEditor.
Rename form FMain to FrmMain. Do this by right clicking FMain in the Project Browser and
next click Rename.
Place following control on FrmMain with some properties pre-set:
1 TextArea: Name → txaMain; Text → empty
When finished with placing the control and setting all properties accordingly you should have
something like in the next illustration.
Illustration 121: FrmMain after placing the control
115
11.
Your fifth application: SimpleTextEditor
11.3 Making a menu
Believe it or not, in this chapter you are going to build a full functional text editor.
With the form made you already can enter text in the TextArea. Only thing missing is saving it
to a text file. For that you could add a save button, but that is not what you will be doing here.
To make a menu right click FrmMain in the IDE and select Menu editor... or press Ctrl + E.
Illustration 122: Select Menu editor...
Once the menu editor is opened add 9 menu entries by clicking button Insert 9 times.
Illustration 123: Adding 9 menu entries in the Menu editor
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 124: Indent the menu entry
Illustration below is how the end result should look like in the Menu Editor.
Illustration 125: The end result of editing the menu entries
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 properties in the fields below the menu list. The selected menu entry will be the one you are
editing.
117
11.
Your fifth application: SimpleTextEditor
Illustration 126: There is a menu File on FrmMain in IDE
11.3.1 Coding the menu entry New
Now click on New in the newly made File menu and you will be taken to the code editor to the
click event of this menu entry.
Lets add some code to FrmMain:
Public Sub Form_Open()
Me.Center
txaMain.Visible = False
End
Public Sub mnuFileNew_Click()
txaMain.Clear
txaMain.Visible = True
'Needed if another text document is already loaded
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
11.3.2 Adding Icon and keyboard shortcut to menu entry New
Back to the Menu Editor to add an icon and a keyboard shortcut.
Once in Menu Editor click on the menu entry for New and set shortcut to CTRL and N
Illustration 128: Set the keyboard shortcut for menu New
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.
Illustration 129: Selecting the new icon
18
Icons might differ from desktop to desktop, depending on type of desktop and themes selected.
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.
Illustration 130: File menu with the newly added icon
for New
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 Saving your first text file
When you want to save a newly made text file you will want to browse for a location, but when
the file has been opened for editing you will already know where to save.
So, what we actually have when saving a file is two situations:
1. New text file → no known location19
2. Existing text file → known location (as it has been opened from somewhere)
If you compare this to Save As you will have only one situation:
1. Existing text file → unknown location (although it has been opened from somewhere)
Seems that one thing you need to know is whether a text file is new or has been opened.
And it also seems that the actions required for saving a new text file are the same as doing a
save as for an existing text file.
Another thing of importance is, that when saving an existing file you will need to know its location (being path and full name).
These are the factors that will determine our approach in saving text files.
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
1. Add a save icon to menu save
2. Add the keyboard entry Ctrl + S to the save menu
3. Have the code editor ready for coding the click event for the Save menu
Your menu should look like the illustration on the next page. If you don't know how, read the
back the part on how you did this for the menu entry New.
Illustration 131: Make sure your menu entry for Save has an icon and
keyboard entry
Menus and keyboard shortcuts
If you take a closer look at menus in common applications like web browsers, document
managers, mail clients or whatever, you will notice that menus have a certain order and that
this is actually of importance.
Why could this be important? Imagine one developer of applications placing a File menu on a
different location, another one placing Save in menu entry Edit, another one thing that Quit is
better of in menu Misc. That would create a lot of confusion amongst people using the different
applications as they would have to search for a function in different places depending on the
application they are using.
So having some sort agreement on menus makes life easier for those using your applications.
No user will expect the File menu to be at another location than right at the beginning of the
menu. No user will look for Save in any other menu that File. So in all it makes sense.
Same for keyboard shortcuts. If you would use Ctrl + S to open a file, a lot of users would get
confused as they are used to Ctrl + S for saving.
There are some directives for both Gnome and KDE development. These directives are known
as Human interface guidelines or hig. Have a look at them if you plan on designing applications
with menus, so you can make menus that appeal to the already present 'menu 'intuition of the
people using them.
More on Human interface guidelines: https://en.wikipedia.org/wiki/Human_interface_guidelines
Gnome hig on menus: https://developer.gnome.org/hig-book/stable/menus.html.en
KDE hig on menus: http://techbase.kde.org/Projects/Usability/HIG/Menu_Bar
11.4.2 Lets save some text
Now that all is a place you can start working for a solution based on the earlier analysis
made.
121
11.
Your fifth application: SimpleTextEditor
If a file is opened you know two things:
1. its location
2. that it is NO new file
So you could work with a variable that is set to true when a file is loaded. When false this
means you have a new file and no location. When true you have an existing file and a location. Expect that this variable will be needed all over the FrmMain, so best make it a Private
variable.
You have learned about the difference between Private and Public.
Private meaning that it can only be used within the class (in our case FrmMain.Class),
Public meaning you can use it in other classes as well (remember the search and replace example in TextPlay(T)wo).
Variables versus Private variables versus Public variables
For 'regular' variables you use Dim to declare them. Their reach is the Function or Method they
are declared in. You can't use them outside the function or method where they where declared.
As shortly discussed in chapter 5. Some good practices, and seen in the examples so far, I
precede my variable names with a letter like s or I. This is to identify the type of variable.
For Private variables you use Private to declare them. Their reach is the entire class they are
declared in. You can use them in any function or method within the class they where declared.
You can't use them in other classes.
When using Private variables I use the same convention as for 'regular' variables but add a $
sign in front of the letter to make them stick out and know as Private variables.
For Public variables you use Public to declare them. Their reach is the entire class they are
declared in and all other classes in the project. You can use them in any function or method
within the project they where declared. You can use them in other classes.
For Public variables I don't use the same convention as for 'regular' variables. I give them a
meaningful name beginning with a capital letter and no indication of type.
Some examples:
Type
String
Integer, Long, Short, Byte
Float
Boolean
Object (handle)
Collection
Arrays
'Regular'
Private
Public
sMyName
$sMyName
MyName
iMyNum
$iMyNum
MyNum
fMyNum
$ fMyNum
MyNum
bIsLoaded
$bIsLoaded
IsLoaded
hFileToLoad
$hFileToLoad
FileToLoad
cMyColl
$cMyColl
MyColl
determined by type (e.g Array of strings → sNames)
This approach is one that has grown throughout years of application development in other
languages. It is almost the same as the naming convention used in the in Gambas written
components source code and in the official examples.
I have nick named my naming approach the 'gbwilly convention' :)
Up to some coding. Add the following to FrmMain.class:
Private $bLoaded As Boolean = False
Public Sub Form_Open()
...
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.
11.4.3 Get name and path to save to
To interface with the user for getting a save path and file name you will be using Dialog.
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.
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
'--- START OF ADDED CODE ---Dialog.Title = Application.Title & (" - Save text file")
Dialog.Path = User.Home
If Dialog.SaveFile() Then Return
File.Save(Dialog.Path, txaMain.Text)
Message.Info("File " & File.Name(Dialog.Path) & " saved.")
'--- END OF ADDED CODE ----
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.
Illustration 132: Ready to save my first file
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
Illustration 133: Dialog Save text file
You will receive notification when saved.
Illustration 134: Notification that the file has been saved
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.
11.5 Opening your first text file
Opening the text file is kind of reverse to saving a text file.
For opening the text file you will need the user to browse to the file and select it. Next load the
content of the text file into txaMain.
Make sure to keep track of the fact that the file was loaded ($bLoaded) and to keep track of
its location (path and file name). So you need another variable to store the location. Best go
Private again as you might need it in more than one method.
11.5.1 Code for opening
To interface with the user for getting a file you will be using Dialog again.
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.
Private $bLoaded As Boolean = False
Private $sPathFileLoaded As String
…
Public Sub mnuFileOpen_Click()
Dialog.Title = Application.Title & (" - Open text file")
Dialog.Path = User.Home
If Dialog.OpenFile() Then Return
txaMain.Text = File.Load(Dialog.Path)
txaMain.Visible = True
'Make the TextArea visible once file loaded
$sPathFileLoaded = Dialog.Path
'Store the full path of the loaded file
$bLoaded = True
'Set to True indicating NO new file
End
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
Illustration 135: Dialog Open text file
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.
11.5.2 Make sure an opened file can be saved
You can go straight to the IDE as you have managed to gather all intelligence (like a detective) on the opened file, the job should be easy.
Public Sub mnuFileSave_Click()
If $bLoaded Then
'Just save the file
'--- START OF ADDED CODE ---File.Save($sPathFileLoaded, txaMain.Text)
Message.Info("File " & File.Name($sPathFileLoaded) & " saved.")
'--- END OF ADDED CODE ---Else
'This means you have a new file
127
11.
Your fifth application: SimpleTextEditor
Once added, run the application, open test.txt, add a line of text and save.
Illustration 136: Saved the changes to the text file
Close the application and start it again. Open test.txt and you should see a changed file.
11.6 Little intermezzo
Time to have a look at the menu and how it looks. The fact that you can save, even when no
text file opened is at least disturbing. Just try it, run the application, do NOT open a file or create a new one and click menu File → Save. The application will not crash, but save an empty
file. But it does look odd.
So the file menu should behave according to the file being opened or not. When no file there
are some menu items you would like to see disabled.
These are:
1. Save
2. Save as...
3. Close
You know that $bLoaded will tell you if an application is loaded, so every time this Boolean is
changed, these menus need to change.
For this you will create a Private method that sets the above mentioned menu items to enabled or disabled according to the value in $bLoaded20.
Back to editing the code in the IDE.
Private Sub Form_Open()
...
SetFileMenu
'Add to the end of the Form_Open event
End
20
You see that $bLoaded is being used all over the project. Now you know why it has been declared Private.
128
11.
Your fifth application: SimpleTextEditor
Public Sub mnuFileOpen_Click()
…
SetFileMenu
'Add to the end of the mnuFileOpen_Click event
End
Public Sub mnuFileQuit_Click()
Me.Close
'About time you can close the application
End
Private Sub SetFileMenu()
If $bLoaded Then
mnuFileSave.Enabled = True
mnuFileSaveAs.Enabled = True
mnuFileClose.Enabled = True
Else
mnuFileSave.Enabled = False
mnuFileSaveAs.Enabled = False
mnuFileClose.Enabled = False
Endif
End
Now run the application and see the menu without and with opened text file.
Illustration 137: Part of the File menu disabled as
should be
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.
Illustration 138: Oops.., no way to save a new text
file..
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:
Public Sub mnuFileNew_Click()
…
SetFileMenuNew
'Add to the end of the mnuFileNew_Click event
End
Public Sub mnuFileSave_Click()
…
Else
…
$sPathFileLoaded = Dialog.Path
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).
Illustration 139: The end result of some polishing of
the File menu
131
11.
Your fifth application: SimpleTextEditor
11.7 Back on track for Save As
Now all that is left for coding in the File menu is Save As...
You have arranged that the Save As menu item will only be seen when an existing project is
opened or a new one has been saved.
11.7.1 Code Save As menu item
What needs to happen when Save As is launched is actually about the same as when a new
document gets saved. The user will get a dialog to determine path and new file name. You
need to save to this user determines path and file name.
The code is as follows:
Public Sub mnuFileSaveAs_Click()
Dialog.Title = Application.Title & (" - Save As text file")
Dialog.Path = User.Home
If Dialog.SaveFile() Then Return
File.Save(Dialog.Path, txaMain.Text)
$sPathFileLoaded = Dialog.Path
$bLoaded = True
Message.Info("File " & File.Name(Dialog.Path) & " saved.")
End
Now run the application, open a text file and save it with another name.
Illustration 140: Save As dialog
132
11.
Your fifth application: SimpleTextEditor
You will see that this works as expected.
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
11.7.2 Simplifying the code for saving
This common code makes for a perfect example for a routine that can be called for both situation, simplifying your code, lessening the mount of code and making for better maintainable
code as you only need to modify code at one place instead of two.
Here is what you the changed Save and Save As event will look like:
Public Sub mnuFileSave_Click()
If $bLoaded Then
'Just save the file
File.Save($sPathFileLoaded, txaMain.Text)
Message.Info("File " & File.Name($sPathFileLoaded) & " saved.")
Else
SaveDialog(“Save”)
Endif
End
Public Sub mnuFileSaveAs_Click()
SaveDialog(“Save As”)
End
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
Private Sub SaveDialog(DialogCaption As String)
Dialog.Title = Application.Title & (" - " & DialogCaption)
Dialog.Path = User.Home
If Dialog.SaveFile() Then Return
File.Save(Dialog.Path, txaMain.Text)
$sPathFileLoaded = Dialog.Path
$bLoaded = True
Message.Info("File " & File.Name(Dialog.Path) & " saved.")
End
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.
Illustration 142: The auto-help will know your new 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 situation. But there is still room for improvement.
11.8 Putting the dots on the i
There is of course always room for improvement. Improving an application can take place on
many front like its functionality, its user friendliness, its looks, its bugs fixed just to name a
few.
You are going to focus on one improvement in functionality. It is more a lack of functionality
that needs to be implemented and that is rather disturbing.
You might have noticed that, when editing a file and next closing it the application will NOT
warn you about the file being changed and offering you an option to save it.
Another thing that will come around the corner when implementing this functionality is the x
on the main form. Users can use this to close the window (and thus the application) circumventing all your code to catch the 'file is edited and thus question for saving' code upon closing.
134
11.
Your fifth application: SimpleTextEditor
Another thing is that our form is rather small and when opening a large text file and next dragging 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.
11.8.1 Offer to save when closed after editing text file
The first thing you need to do is determine whether a file is changed or not. For this another
private variable is introduced $bChanged (a Boolean).
The control you need to check for changes is txaMain, so that is where $bChanged needs to
be set to true. TxaMain has a Change event and that is the one you need to code.
Not very much code needed to do the job:
Private $bChanged As Boolean = False
Public Sub txaMain_Change()
$bChanged = True
End
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.
Public Sub mnuFileClose_Click()
If $bChanged Then
'offer option to save
Else
txaMain.Clear
'← will trigger a change event and set $bChanged to true
txaMain.Visible = False
$bLoaded = False
$bChanged = False
'← set to false (see comment above)
$sPathFileLoaded = Null
SetFileMenu
Endif
End
Public Sub mnuFileQuit_Click()
If $bChanged Then
'offer option to save
Else
Me.Close
Endif
End
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 Message 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:
Private Function WarningIsCancelled() As Boolean
Dim iAnswer As Integer
iAnswer = Message.Question("File has been changed!\nDo you want to save the project?",
"Yes", "No", "Cancel")
Select iAnswer
Case 1
mnuFileSave_Click
'<-- Yes: Let the code at the FileSave menu handle the saving
Return False
Case 2
Return False
'<-- No: So no saving
Case Else
Return True
'<-- Cancel: So cancelled
End Select
End
Why a function?
Well a function can do all a method can do, but it can also return something. In this case it returns 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:
Public Sub mnuFileClose_Click()
If $bChanged Then
If Not WarningIsCancelled() Then
txaMain.Clear
'← Message.Warning received a yes or no
txaMain.Visible = False
$bLoaded = False
$bChanged = False
$sPathFileLoaded = Null
SetFileMenu
Endif
Else
txaMain.Clear
txaMain.Visible = False
$bLoaded = False
$bChanged = False
$sPathFileLoaded = Null
SetFileMenu
Endif
End
Public Sub mnuFileQuit_Click()
If $bChanged Then
If Not WarningIsCancelled() Then
Me.Close
Endif
Else
Me.Close
Endif
End
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
Illustration 143: Closing after editing gives a
warning and option to save
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?...
11.8.2 Bug!! What bug?!
When you intend something to work a certain manner to provide certain functionality and it
doesn't do that job under all circumstances, then you can call that a bug.
Try opening a text file, do NOT change the file and click File → Close. What happens? Do
you get a warning that your file has been changed when it isn't?
Something does seem to trigger the Change event of txaMain. First lets add a Print statement
to the Change event so you can check in console when it is triggered.
Public Sub txaMain_Change()
$bChanged = True
Print “Changed”
End
Now run the application keep your eye on the console.
When launching the application nothing happens in the console.
When clicking File → Open nothing happens in the console.
When selecting a file and clicking OK → console shows 'Changed'
138
11.
Your fifth application: SimpleTextEditor
Illustration 144: Changed shown in Console means Change event is
triggered
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.
Public Sub mnuFileOpen_Click()
Dialog.Title = Application.Title & (" - Open text file")
Dialog.Path = User.Home
If Dialog.OpenFile() Then Return
txaMain.Text = File.Load(Dialog.Path) '← triggers the change event
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 txaMain_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.
Public Sub mnuFileOpen_Click()
Dialog.Title = Application.Title & (" - Open text file")
Dialog.Path = User.Home
If Dialog.OpenFile() Then Return
txaMain.Text = File.Load(Dialog.Path)
$bChanged = False
'← Add this line
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 application). 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 mnuFileQuit_Click event to the Form_Close event. Next call the Form_Close event from
mnuFileQuit_Click event.
139
11.
Your fifth application: SimpleTextEditor
Public Sub Form_Close()
f $bChanged Then
If Not WarningIsCancelled() Then
Me.Close
Endif
Else
Me.Close
Endif
End
Public Sub mnuFileQuit_Click()
Form_Close
End
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 Cancel and you will see that the application, instead of cancelling will close.
To solve that problem you will need one more line of code:
Public Sub Form_Close()
f $bChanged Then
If Not WarningIsCancelled() Then
Me.Close
Else
'← add this
Stop Event
'← and this
Endif
Else
Me.Close
Endif
End
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 application should stay opened.
In short, second bug down.
140
11.
Your fifth application: SimpleTextEditor
11.8.3 Resizing the application window
Check if you have got a ReadMe file or some other text file with a good quantity of text and
open it using SimpleTextEditor.
You will notice that with a lot of text a bigger size window would be better. So go to the border
of the SimpleTextEditor window and drag it bigger.
Illustration 145: Dragging the window bigger doesn't change the
TextArea
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
Illustration 146: Set the Arrangement property of FrmMain
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.
Illustration 148: Arrangement set to Fill does the job
142
11.
Your fifth application: SimpleTextEditor
11.8.4 Adding a ToolBar
To add a ToolBar you will need to go back to the design of your form and make some room
below your menu and above your TextArea.
Next add a Hbox above the TextArea.
HBox: Name → hbxToolBar
Illustration 149: HBox is found on the Tab Container
Now select the Hbox and add a ToolButton:
ToolButton: Name → tbnNew; Width → 22; Height → 22; Picture→ select the New icon from
stock 22.
You result should look like the illustration below. Check the hierarchy to see if tbnNew is actually placed inside the hbxToolBar (very important).
Illustration 150: All new controls in place
Next double click tbnNew and code its Click event:
Public Sub tbnNew_Click()
mnuFileNew_Click
End
Run the application and see what happens when clicking New in the Toolbar. Drag the window 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
Illustration 151: A strange looking form, but New button works..
Seems you need to fix the Arrangement of the FrmMain. Give it a go and try the different options.
Now that you probably figured out that none will work, set the FrmMain property Arrangement to Vertical. Next set the txaMain property Expand to True.
Illustration 152: Set 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
from stock 22.
ToolButton: Name → tbnSaveAs; Width → 22; Height → 22; Picture→ select the SaveAs
icon from stock 22.
ToolButton: Name → tbnClose; Width → 22; Height → 22; Picture→ select the Close icon
from stock 22.
The result should look like illustration below. Make sure the buttons are inside the Hbox.
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.
Public Sub tbnOpen_Click()
mnuFileOpen_Click
End
Public Sub tbnSave_Click()
mnuFileSave_Click
End
Public Sub tbnSaveAs_Click()
mnuFileSaveAs_Click
End
Public Sub tbnClose_Click()
mnuFileClose_Click
End
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
Private Sub SetFileMenu()
If $bLoaded Then
mnuFileSave.Enabled = True
mnuFileSaveAs.Enabled = True
mnuFileClose.Enabled = True
tbnSave.Enabled = True
tbnSaveAs.Enabled = True
tbnClose.Enabled = True
Else
mnuFileSave.Enabled = False
mnuFileSaveAs.Enabled = False
mnuFileClose.Enabled = False
tbnSave.Enabled = False
tbnSaveAs.Enabled = False
tbnClose.Enabled = False
Endif
'← added
'← added
'← added
'← added
'← added
'← added
End
Private Sub SetFileMenuNew()
mnuFileSave.Enabled = True
mnuFileClose.Enabled = True
tbnSave.Enabled = True
tbnClose.Enabled = True
'← added
'← added
End
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.
Illustration 154: A running resizeable SimpeTextEditor with Toolbar
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
Illustration 155: Toolbar with property Spacing set to False
Illustration 156: Toolbar with property Spacing set to True
That wasn't to hard.
11.8.5 Reordering menu items
One more thing before this chapter comes to an end. In most applications you will find the
menu item Close just above Save. You have it below SaveAs. Lets make a change.
Open the Menu Editor. Select the menu item Close and click the Move Up button twice.
Illustration 157: A click on Move Up button brings the item higher
147
11.
Your fifth application: SimpleTextEditor
11.8.6 Adding new menus
You can also easily add a new menu. And that is your next mission. Add these menu items to
the bottom of the current ones
Menu4: Name → mnuView; Caption → View
Menu3: Name → mnuViewToolBar; Caption → Toolbar; Checked → True;Click button Indent
in Toolbar
Menu2: Name → mnuHelp; Caption → Help
Menu1: Name → mnuHelpAbout; Caption → About... Click button Indent in Toolbar
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.
Illustration 159: A new menu View Toolbar
148
11.
Your fifth application: SimpleTextEditor
Now when the menu item Toolbar is checked you want the ToolBar to be visible. When unchecked it needs to be invisible.
For the About menu item in menu Help you will code a simple Message.
Public Sub mnuViewToolBar_Click()
If mnuViewToolBar.Checked Then
mnuViewToolBar.Checked = False
hbxToolBar.Visible = False
Else
mnuViewToolBar.Checked = True
hbxToolBar.Visible = True
Endif
End
Public Sub mnuHelpAbout_Click()
Message.Info(Application.Name & " " & Application.Version & "\nAn example application by
W. Raets\n\nGNU General Public License version 3")
End
For the mnuViewToolBar you check its checked status and change it. Clicked when the Toolbar item was checked will uncheck it and vice versa. Besides that it will make the ToolBar
hbxToolBar visible or invisible accordingly.
The mnuHelpAbout code is just a simple Message.Info.
Have a look at your result.
Illustration 160: With ToolBar checked
Open a text file and click menu View and see the Toolbar item checked. Now click the menuitem Toolbar and see the Toolbar disappear (see illustration on next page).
149
11.
Your fifth application: SimpleTextEditor
Illustration 161: With Toolbar unchecked
Click menu Help → About... to see your About screen.
Illustration 162: Menu Help -> About shows some info on the
application
11.8.7 Application caption
The last 'dot to put on the I' is the application caption. Default it shows the applications name,
but it could be used differenty.
When a text file is open it could show the application name and the name of the text file.
When a new text document is made it could show application name and 'new text document'.
As the caption has to be set according to the current state of the text loaded into txaMain, it is
going to be needed at more than one place in our FrmMain.class. A private routine would be
the proper road to take.
Basically there are two situation:
150
11.
Your fifth application: SimpleTextEditor
1. No document loaded → no file name
2. Document loaded → file name known or file name is 'new text document'
If you write a private method that sets the caption these file names need to get passed to the
private method. For that you use an argument, but since there is not always a file name to
pass you need to make the argument Optional, meaning you can provide the argument when
calling the method but you don't need to.
Back to the code editor in IDE to write the routine:
Private Sub SetAppCaption(Optional AppCaption As String)
If IsNull(AppCaption) Then
Me.Caption = Application.Name
Else
Me.Caption = Application.Name & “ - “ & AppCaption
Endif
End
Because AppCaption is an optional argument, meaning it can be empty, you need to check
what cause of action to take when empty (IsNull).
Next step is to check at what places the method SetAppCaption needs to be called.
First place is when a new document is made. The caption will need to show 'New text document' alongside the application name.
Public Sub mnuFileNew_Click()
txaMain.Clear
txaMain.Visible = True
SetAppCaption(“New text document”)
End
Now run the application and click button New in the Toolbar.
Illustration 163: 'New text document' added to
application caption
151
11.
Your fifth application: SimpleTextEditor
Second place to check is when opening a text file.
Public Sub mnuFileOpenClick()
...
txaMain.Text = File.Load(Dialog.Path)
'← this is where the file gets loaded
SetAppCaption(File.Name(Dialog.Path)) '← this is where you set the caption
...
End
Again run and open a text file and see the file name appear in the caption.
Illustration 164: Caption showing the name of the opened
text file
Third place to check is when a new document is saved (so it has a name) and when an existing 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:
Public Sub SaveDialog()
...
File.Save(Dialog.Path, txaMain.Text)
'← this is where the file gets saved
SetAppCaption(File.Name(Dialog.Path)) '← this is where you set the caption
...
End
And last but not least, the caption should be set when opening the form:
Public Sub Form_Open()
Me.Center
SetAppCaption()
...
'← this is where you set the caption (no name known)
152
11.
Your fifth application: SimpleTextEditor
Run your application once more and try some different things, like starting a new text document and saving it, next save as. If you see the caption changing the application is finished
for now.
Illustration 165: Save the new text document
Illustration 166: After saving the caption changed
11.9 A last note on code organisation
Since no application is really free of maintenance, you should organise your code in such
manners that, in a later stage (this can be months and other applications later), you understand what you have been doing in the past.
Comment can contribute, as can ordering your code.
On the next illustration a screenshot of the code of this project in my IDE. You will see that I
placed all menu code together, all toolbar code together, all private routines together. All these
groups have a comment indicating where they start.
153
11.
Your fifth application: SimpleTextEditor
Illustration 167: FrmMain.class code organised in certain order
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
12 End note for pre-release 1
This work is not finished yet. More chapters will be added as soon as possible and current
ones might be further revised.
Planned for the next chapter (actually this chapter 12) is printing.
After that you will be diving into some more complex situations when it comes to handling
data and saving it, you will learn some new more complex controls and have a closer look at
what is possible with form classes. This journey will take several chapters.
And what will be next I'm not sure about, a closer look at the IDE will be part of it fir sure. Expect at least 6 or 7 more chapters added to the final release. Maybe in between another prerelase will become available, a bit depending on how long things take to write.
Meanwhile I hope you enjoyed the first 11 chapters and working with Gambas. Make sure to
install the application GambasLearning (see Appendix VI) , for updated information on this
and other 'How To Gambas'-guides and more to help the beginning Gambas developer.
To be continued...
P.S. If you encounter any irregularities in this release please report them back (see Appendix V) and help improve the guide.
155
13 Appendices
Appendix I: Linux command reference
If you are new to Linux, here are some commands that could be useful when installing Gambas from the official website or from SVN.
File commands
ls
ls -al
cd dir
cd
cd /
mkdir dir
rm file
rm -r dir
rm -f file
rm -fr dir
lists the current directory
lists the current directory (hidden files included)
change the directory dir (example: cd /usr/bin)
change to home directory
change directory to root directory
make directory dir (example mkdir Gambas3)
removes file file (example rm myinfo.txt)
removes directory dir (example rm Gambas3)
forced remove file file (example rm -f myinfo.txt)
forced remove directory dir (example rm -rf Gambas3)
System information
df
du
uptime
uname -a
free
show disk usage
show directory usage
show system uptime
show kernel information
show memory and swap information
Installation from source
./configure
make
make install
Configure the package
Compile the package
Install the package
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 Gambas website and click on the menu 'Mailing lists/Forums'
Illustration 168: Gambas website - Menu Mailing lists/Forums
This will open an overview of the available mailing lists and a forum.
Illustration 169: Gambas website - Overview Mailing Lists & Forums
For reporting your problems use the 'Gambas Users' list.
The 'Gambas Developers” and 'Gambas Subversion Commits” lists are meant for those
working on the development of Gambas3 (or those just curious)
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.
Illustration 170: Subscribe to the Gambas-user mailinglist
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/Gambasf3425.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
When having problems provide these details on your system:
1. Kernel information (use uname -a in a terminal)
2. Distribution name and version (Example: Linux Mint 13 Maya)
3. Desktop used (Examples are: Gnome, KDE, LXDE, xfce, Mate, Cinnamon,...)
4. Gambas version
All this can be found in the Gambas IDE menu ? → System informations...
Illustration 172: Gambas IDE - System information form
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 Gambas 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
22
You can visit it as guest and read all information. To post questions on the forum you need
to make a free account.
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
24
You can visit it as guest and read all information. To post questions on the forum you need
to make a free account.
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.
Illustration 177: Topics in sub forum 'Building GUI Applications'
Three topics are of importance:
➢
Suggestions for improvements
➢
Problems with instructions in the manual
➢
Other questions
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.
Illustration 178: Gambas Learning - a learning aid for Gambas
The application provides you with:
➢ an overview and download of the 'How To Gambas 3' guides (most recent version)
➢ Gambas 3 code snippets for common tasks
➢ a direct access to the Gambas 3 language index
➢ a direct access to the Gambas 3 component index
➢ a direct access to the Gambas 3 error messages index
➢ a direct access to the How To Gambas forum
The application receives remote metadata updates25 on the number, version and state of
guides available. New code snippets that are available are also part of the metadata updates
of Gambas Learning and will update the code snippets seen in Gambas Learning.
For more screenshots and download visit:
http://howtogambas.org/
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