1.BGGV3 Book

A Beginner's Guide to Gambas Revised Edition
Copyright Notice for the printed version of this work:

A Beginner's Guide to Gambas Version 3 (this work) is copyright 200!20"" by #ohn $%
&ittinghouse' a(( rights are reser)ed% *ersona( use o+ this materia( is permitted% ,owe)er'
permission to reprint-repub(ish this materia( +or ad)ertising or promotiona( purposes or +or
creating new co((ecti)e works +or resa(e or redistribution to ser)ers or (ists' or to reuse any
copyrighted component o+ this work in other works must be obtained +rom the author' #ohn $%
&ittinghouse% .he author grants a perpetua( (icense to the Gambas user!community +or use
o+ the e(ectronic )ersion o+ this printed work under the terms and conditions o+ the
/pen0ontent 1icense printed on the +o((owing page%
1
Copyright Notice for the electronic (online) version of this work, based on the
OpenContent License (OPL, !ersion "#$, %u&' "(, "))*#
.his document out(ines the princip(es under(ying the /pen0ontent (/0) mo)ement and may be redistributed pro)ided it remains una(tered%
2or (ega( purposes' this document is the (icense under which /pen0ontent is made a)ai(ab(e +or use% .he origina( )ersion o+ this document
may be +ound at http3--opencontent%org-op(%shtm( %
1405675
.erms and 0onditions +or 0opying' 8istributing' and 9odi+ying
4tems other than copying' distributing' and modi+ying the 0ontent with which this (icense was distributed (such as using' etc%) are outside the
scope o+ this (icense%
"% :ou may copy and distribute e;act rep(icas o+ the /pen0ontent (/0) as you recei)e it' in any medium' pro)ided that you conspicuous(y
and appropriate(y pub(ish on each copy an appropriate copyright notice and disc(aimer o+ warranty< keep intact a(( the notices that re+er to
this 1icense and to the absence o+ any warranty< and gi)e any other recipients o+ the /0 a copy o+ this 1icense a(ong with the /0% :ou may
at your option charge a +ee +or the media and-or hand(ing in)o()ed in creating a uni=ue copy o+ the /0 +or use o++(ine' you may at your option
o++er instructiona( support +or the /0 in e;change +or a +ee' or you may at your option o++er warranty in e;change +or a +ee% :ou may not
charge a +ee +or the /0 itse(+% :ou may not charge a +ee +or the so(e ser)ice o+ pro)iding access to and-or use o+ the /0 )ia a network (e%g%
the 4nternet)' whether it be )ia the wor(d wide web' 2.*' or any other method%
2% :ou may modi+y your copy or copies o+ the /pen0ontent or any portion o+ it' thus +orming works based on the 0ontent' and distribute such
modi+ications or work under the terms o+ 7ection " abo)e' pro)ided that you a(so meet a(( o+ these conditions3
a) :ou must cause the modi+ied content to carry prominent notices stating that you changed it' the e;act nature and content o+ the changes'
and the date o+ any change%
b) :ou must cause any work that you distribute or pub(ish' that in who(e or in part contains or is deri)ed +rom the /0 or any part thereo+' to
be (icensed as a who(e at no charge to a(( third parties under the terms o+ this 1icense' un(ess otherwise permitted under app(icab(e 2air >se
(aw%
.hese re=uirements app(y to the modi+ied work as a who(e% 4+ identi+iab(e sections o+ that work are not deri)ed +rom the /0' and can be
reasonab(y considered independent and separate works in themse()es' then this 1icense' and its terms' do not app(y to those sections when
you distribute them as separate works% But when you distribute the same sections as part o+ a who(e which is a work based on the /0' the
distribution o+ the who(e must be on the terms o+ this 1icense' whose permissions +or other (icensees e;tend to the entire who(e' and thus to
each and e)ery part regard(ess o+ who wrote it% 5;ceptions are made to this re=uirement to re(ease modi+ied works +ree o+ charge under this
(icense on(y in comp(iance with 2air >se (aw where app(icab(e%
3% :ou are not re=uired to accept this 1icense' since you ha)e not signed it% ,owe)er' nothing e(se grants you permission to copy' distribute
or modi+y the /0% .hese actions are prohibited by (aw i+ you do not accept this 1icense% .here+ore' by distributing or trans(ating the /0' or by
deri)ing works here+rom' you indicate your acceptance o+ this 1icense to do so' and a(( its terms and conditions +or copying' distributing or
trans(ating the /0%
6/ $A&&A6.:
?% B50A>75 .,5 /*560/6.56. (/0) 47 14056758 2&55 /2 0,A&G5' .,5&5 47 6/ $A&&A6.: 2/& .,5 /0' ./ .,5 5@.56.
*5&94..58 B: A**140AB15 1A$% 5@05*. $,56 /.,5&$475 7.A.58 46 $&4.46G .,5 0/*:&4G,. ,/185&7 A68-/& /.,5&
*A&.457 *&/V485 .,5 /0 AA7 47A $4.,/>. $A&&A6.: /2 A6: B468' 54.,5& 5@*&57758 /& 49*1458' 4601>846G' B>. 6/.
1494.58 ./' .,5 49*1458 $A&&A6.457 /2 95&0,A6.AB414.: A68 24.6577 2/& A *A&.40>1A& *>&*/75% .,5 56.4&5 &47B
/2 >75 /2 .,5 /0 47 $4., :/>% 7,/>18 .,5 /0 *&/V5 2A>1.:' 46A00>&A.5' /& /.,5&$475 >6A005*.AB15 :/>
A77>95 .,5 0/7. /2 A11 650577A&: &5*A4& /& 0/&&50.4/6%
% 46 6/ 5V56. >61577 &5C>4&58 B: A**140AB15 1A$ /& AG&558 ./ 46 $&4.46G $411 A6: 0/*:&4G,. ,/185&' /& A6:
/.,5& *A&.: $,/ 9A: 94&&/& A68-/& &5847.&4B>.5 .,5 /0 A7 *5&94..58 AB/V5' B5 14AB15 ./ :/> 2/& 8A9AG57'
4601>846G A6: G565&A1' 7*504A1' 4604856.A1 /& 0/675C>56.4A1 8A9AG57 A&4746G />. /2 .,5 >75 /& 46AB414.: ./
>75 .,5 /0' 5V56 42 7>0, ,/185& /& /.,5& *A&.: ,A7 B556 A8V4758 /2 .,5 */774B414.: /2 7>0, 8A9AG57%
2
Acknowledgements
+ ,ou&d &i-e to than- .r# %ohn Rittinghouse /or the ama0ing opportunit' to contribute to this
boo-, A Beginner's Guide to GA1BA2, Revised Edition, /rom the 3&earner's3 point o/ vie,# +
began b' bu'ing his boo- and o//ering some ideas /or a /uture revised edition, and turned into
a contributor to the revised edition 44 evidence o/ an astounding absence o/ vanit' on his part#
+ especia&&' ,ant to dedicate m' portion o/ the ,or- on the 2econd Edition to m' son, +an,
,hose in5uiring mind and cease&ess e6periments ,ith operating s'stems introduced me to
Linu6 and to the Open 2ource ,or&d#
As a &ong4time Basic programmer, + ,as e&ated to /ind the Gambas version o/ Basic avai&ab&e
/or Linu6 and 7reeB2., ,ith ongoing deve&opment /or other operating s'stems# Beno8t
1inisini and his co&&eagues, ,ho have brought us the Gambas &anguage /ree o/ charge, ,ith its
outstanding +.E and component e6tensions, are to be congratu&ated and than-ed /or their
continuing ,or-# A sma&& mone' contribution to the pro9ect ,ou&d not be a bad idea i/ 'ou
can do so#
7ina&&', + ,ant to e6press m' appreciation /or a&& o/ the programmers and end4users ,ho ,rite
code /or open source pro9ects and app&ications, use open source so/t,are, /i&e bug reports,
provide he&p to others on on&ine /orums, and contribute mone' to pro9ects ,here it's needed#
Obvious&', as e6emp&i/ied b' the Gambas programming &anguage and its associated
communit', Open 2ource engages some o/ the best ta&ent and best e//ort avai&ab&e#
%on :icho&son
1arch, ;$""
+t has been near&' /ive 'ears since + /irst pub&ished Gambas /or Beginners# As one o/ the more
aspiring pro9ects in the open source communit', + have had the privi&ege o/ monitoring its
progress and seeing it deve&op /rom its in/anc' to become a re&iab&e programming resource in
the Linu6 communit'# <hi&e + had considered doing an update /or some time, /or various
reasons, + ,as not ab&e to do so# +t ,as a p&easant surprise ,hen %on :icho&son contacted me
to as- about the 5uir-s he had /ound in the boo- as the product transcended /rom version "#$
to its current state# A/ter some discussion, + invited %on to provide comments and /eedbac- as
he ,ent through the boo-# +n a ver' short time, it became c&ear that %on ,as ab&e to do so
much more# + invited him to co4author the revision and ro&&ed up m' s&eeves ,ith him to go
bac- to ,or- on this pro9ect# =e has been a great resource and strong contributor and has
provided innumerab&e suggestions and a ne,, /resh perspective to the understanding o/ the
&anguage /rom the e'es o/ an abso&ute beginner# Chapter b' chapter, &ine b' &ine, %on has
revie,ed content and code to ensure ,e have provided the most accurate, updated
in/ormation avai&ab&e /or programming Gambas#
3
As ,ith the previous version o/ this boo-, + made a commitment to provide an open source
version to the Gambas programming communit'# .etai&s o/ ,here this e&ectronic version can
be obtained /or /ree are provided at the bac- o/ the boo-# 1' intent in supporting the Gambas
communit' has been to he&p those ne, to the &anguage to mudd&e through the m'riad, poor&'
documented ,eb sites and approach &earning the &anguage in a structured and meaning/u&
manner# >he e6amp&e programs in this boo- are designed to 5uic-&' bui&d programming s-i&&s
and ma6imi0e the understanding o/ the Gambas &anguage and a&& o/ the po,er it provides to
the open source communit'# + hope 'ou /ind this re/erence ,orth' o/ 'our co&&ection#
%ohn <# Rittinghouse, Ph#.#, C+21, CR+2C
1arch, ;$""
4
Table of Contents
Acknowledgements....................................................................................................................................3
Chapter 1 - Introducing Gambas..............................................................................................................13
Gambas Architecture...........................................................................................................................13
The Gambas rogramming !n"ironment............................................................................................1#
Gambas I$! Components..............................................................................................................1%
Chapter 2 & 'anguage Concepts..............................................................................................................24
Gambas (ariables) $ata-t*pes and Constants.....................................................................................2#
(ariable Assignment......................................................................................................................2+
Assignment ,sing The -IT. /tatement.......................................................................................30
1perators and !2pressions..................................................................................................................30
Arithmetic 1perators......................................................................................................................31
Comparison operators ....................................................................................................................31
'et3s /tart Coding Gambas.............................................................................................................31
/tring 1perators..............................................................................................................................43
Chapter 3 - 4e*words and rogram 5low Control..................................................................................4#
The 6I7T /tatement.....................................................................................................................4#
The I5 /tatement.............................................................................................................................48
The /!'!CT 9 CA/! /tatement....................................................................................................4%
G1T1 and 'A:!'/......................................................................................................................4+
The 516 9 7!;T /tatement...........................................................................................................4+
$1 <-.I'!= '11......................................................................................................................#0
-.I'! <!2pression= -!7$ 'oops .............................................................................................#2
The 6!!AT ,7TI' loop ............................................................................................................#2
$e>ining and ,sing Arra*s in Gambas...............................................................................................#3
Collections...........................................................................................................................................##
The 516 !AC. /tatement............................................................................................................##
Chapter 4 & The Gambas Tool:o2..........................................................................................................#?
The :utton Control..............................................................................................................................#+
Common Control roperties...........................................................................................................80
:utton @ethods..............................................................................................................................8%
:utton !"ents.................................................................................................................................?8
The icture Class.................................................................................................................................?8
Chapter # & Controls >or ,ser Input.........................................................................................................?%
Te2t'abel.............................................................................................................................................%0
Te2t:o2...............................................................................................................................................%2
Combo:o2...........................................................................................................................................%4
'ist:o2................................................................................................................................................%?
5rame...................................................................................................................................................%+
Toggle:utton.......................................................................................................................................+0
Checkbo2.............................................................................................................................................+1
anel....................................................................................................................................................+2
#
6adio:utton.........................................................................................................................................+3
Chapter 8 & @enus) @odules) $ialogs and @essage :o2es....................................................................+#
The Gambas @enu !ditor...................................................................................................................+8
:uilding @enus...................................................................................................................................++
$ialogs...............................................................................................................................................101
@odules.............................................................................................................................................103
@essage:o2es...................................................................................................................................111
In>ormation @essages...................................................................................................................111
Auer*9Con>irm @essages.............................................................................................................113
!rror @essages.............................................................................................................................114
-arning or Alert @essages..........................................................................................................114
$elete @essages...........................................................................................................................11#
$ialog Class 5ile-related 5unctions..................................................................................................118
$ialog 1pen5ile 5unction............................................................................................................118
$ialog /a"e5ile 5unction.............................................................................................................11?
$ialog /elect$irector* 5unction..................................................................................................11%
Complete !2ample 'isting................................................................................................................11+
@@ain.module listing.......................................................................................................................122
Chapter ? & /trings and $ata Con"ersion..............................................................................................124
/tring 5unctions................................................................................................................................124
'en................................................................................................................................................124
,pperB9,caseB9,case - 'owerB9'caseB9'case ...........................................................................12#
TrimB) 'TrimB) and 6TrimB........................................................................................................128
'e>tB) @idB) and 6ightB ..............................................................................................................12?
/paceB...........................................................................................................................................12%
6eplaceB ......................................................................................................................................12+
/tringB .........................................................................................................................................130
/ubstB ..........................................................................................................................................130
In/tr..............................................................................................................................................132
6In/tr............................................................................................................................................133
/plit...............................................................................................................................................134
$ata Con"ersion................................................................................................................................13#
Asc and ChrB ...............................................................................................................................13#
:inB..............................................................................................................................................138
C:ool ...........................................................................................................................................13?
C:*te............................................................................................................................................13?
C$ate............................................................................................................................................13%
C5loat...........................................................................................................................................13+
CInt 9 Cinteger and C/hort ..........................................................................................................13+
C/tr 9 C/tring ..............................................................................................................................140
.e2B..............................................................................................................................................141
Con"B ...........................................................................................................................................141
(al and /trB .................................................................................................................................142
/trB ...............................................................................................................................................142
5ormatB.........................................................................................................................................14#
8
$atat*pe management ......................................................................................................................14?
T*pe1>..........................................................................................................................................14%
Chapter % & Ad"anced Controls.............................................................................................................14+
Icon(iew Control..............................................................................................................................14+
'ist(iew Control...............................................................................................................................1#%
,sing the G: Icon !dit Tool.............................................................................................................182
The Tree(iew Control.......................................................................................................................184
The Grid(iew Control.......................................................................................................................1?1
The Column(iew Control.................................................................................................................1?#
'a*out Controls & .:o2) (:o2) .anel and (panel.......................................................................1?+
.:o2 and (:o2...........................................................................................................................1%0
.anel and (panel.......................................................................................................................1%0
The Tab/trip Control.........................................................................................................................1%4
Chapter + & -orking with 5iles.............................................................................................................1+1
Access................................................................................................................................................1+1
$ir......................................................................................................................................................1+2
!o>.....................................................................................................................................................1+3
!2ist...................................................................................................................................................1+3
Is$ir...................................................................................................................................................1+4
/tat ....................................................................................................................................................1+4
Temp 9 TempB ..................................................................................................................................1+#
1!7 and C'1/!............................................................................................................................1+8
'I7! I7,T.....................................................................................................................................1+?
6!A$) /!!4) -6IT! and 5',/..................................................................................................1+%
C1C) 4I'' and 6!7A@!.............................................................................................................200
@4$I6) 6@$I6...............................................................................................................................200
Chapter 10 & @ath 1perations...............................................................................................................220
recedence o> 1perations..................................................................................................................220
Abs.....................................................................................................................................................220
Acs 9 ACos.........................................................................................................................................221
Acsh 9 ACosh.....................................................................................................................................221
Asn 9 A/in.........................................................................................................................................222
Asnh 9 A/inh.....................................................................................................................................222
Atn 9 ATan.........................................................................................................................................223
Atnh 9 ATanh.....................................................................................................................................224
Cos.....................................................................................................................................................224
Cosh...................................................................................................................................................22#
$eg and 6ad......................................................................................................................................22#
!2p.....................................................................................................................................................228
5i2 and 5rac.......................................................................................................................................22?
Int.......................................................................................................................................................22?
'og.....................................................................................................................................................22%
'og10.................................................................................................................................................22+
@a2 and @in.....................................................................................................................................22+
i........................................................................................................................................................230
?
6andomiDe and 6nd..........................................................................................................................230
6ound................................................................................................................................................232
/gn.....................................................................................................................................................232
/in......................................................................................................................................................233
/inh....................................................................................................................................................233
/Er.....................................................................................................................................................234
Tan.....................................................................................................................................................234
Tanh...................................................................................................................................................23#
Chapter 11 & 1bFect-1riented Concepts................................................................................................242
5undamentals o> 1bFect 1riented rogramming...............................................................................243
1bFects..........................................................................................................................................243
$ata Abstraction...........................................................................................................................244
!ncapsulation................................................................................................................................244
ol*morphism...............................................................................................................................244
Inheritance....................................................................................................................................244
The Gambas Approach to 11.........................................................................................................24#
Gambas Classes............................................................................................................................24#
/ample programG Contacts................................................................................................................248
The Contact class..........................................................................................................................248
Contact.Get$ata @ethod..............................................................................................................24?
Contact.ut$ata @ethod...............................................................................................................24+
5@ain.class >ile.............................................................................................................................2#2
5@ain Constructor........................................................................................................................2#3
5ormH1pen /ubroutine................................................................................................................2#4
Adding Controls to 5@ain.5orm..................................................................................................2##
,pdate5ormIJ /ubroutine.............................................................................................................2#?
(alidating ,ser Input...................................................................................................................283
Adding a /earch 5eature...............................................................................................................28#
,pdating an !2isting 6ecord........................................................................................................28?
$eleting a Contact 6ecord............................................................................................................28%
/a"ing $ata...................................................................................................................................2?0
Chapter 12 & 'earning to $raw..............................................................................................................2?2
$raw roperties.................................................................................................................................2?2
:ackground and 5oreground........................................................................................................2?2
Clip...............................................................................................................................................2?3
5illColor) 5ill/t*le) 5ill;) 5illC...................................................................................................2?3
5ont...............................................................................................................................................2?4
In"ert.............................................................................................................................................2?4
'ine/t*le9'ine-idth....................................................................................................................2?4
Transparent...................................................................................................................................2?#
$raw @ethods...................................................................................................................................2?#
Te2t9Te2t.eight9Te2t-idth.........................................................................................................2??
$raw rimiti"esG oint96ect9!llipse9'ine....................................................................................2?%
$raw rimiti"esG ol*gon and ol*line.......................................................................................2%#
Image9icture9Tile........................................................................................................................2%+
%
$rawing with a $rawing obFect....................................................................................................2+?
Chapter 13 & !rror @anagement............................................................................................................300
General Concepts o> !rror @anagement...........................................................................................300
!rror .andling..............................................................................................................................300
:oundar*-6elated !rrors..............................................................................................................301
Calculation !rrors.........................................................................................................................301
Initial and 'ater /tates..................................................................................................................301
Control 5low !rrors......................................................................................................................302
!rrors in .andling or Interpreting $ata........................................................................................302
6ace and 'oad Conditions............................................................................................................303
lat>orm and .ardware Issues......................................................................................................303
/ource) (ersion) and I$ Control !rrors.......................................................................................304
Testing !rrors...............................................................................................................................304
Test lan 6e"iews.........................................................................................................................304
Gambas !rror management...............................................................................................................30#
T6C statement... I5 !6616........................................................................................................30#
Catch and 5inall* /tatements.......................................................................................................308
Gambas !"ent management..............................................................................................................310
Chapter 14 & @ouse) 4e*board and :it 1perations..............................................................................312
@ouse 1perations..............................................................................................................................312
4e*board 1perations.........................................................................................................................318
:it 1perations....................................................................................................................................31%
Chapter 1# & @*/A' and Gambas........................................................................................................328
:lob Class..........................................................................................................................................32?
Connection Class...............................................................................................................................32?
Connection roperties...................................................................................................................32%
The Concept o> a Transaction.......................................................................................................330
Connection Class @ethods...........................................................................................................331
6esult 1bFects...............................................................................................................................33#
$: Class............................................................................................................................................338
$atabase............................................................................................................................................338
$atabase,ser.....................................................................................................................................338
5ield...................................................................................................................................................33?
Inde2..................................................................................................................................................33?
Table..................................................................................................................................................33?
The $atabase !2ample rogram.......................................................................................................33?
Chapter 18 & Global Gambas.................................................................................................................3#1
InternationaliDation............................................................................................................................3#1
'ocaliDation.......................................................................................................................................3#1
,ni"ersal Character /et I,C/J.........................................................................................................3#1
,T5-%................................................................................................................................................3#3
5ile /*stem /a>e ,C/ Trans>ormation 5ormat.....................................................................................3#3
5//9,T5................................................................................................................................................3#3
.ow to translate in Gambas..............................................................................................................3#4
+
Illustration Index
5igure 1G The Gambas Architecture.........................................................................................................14
5igure 2G The Gambas opening I-elcomeJ screen..................................................................................1#
5igure 3G The Gambas roFect Creation -iDard......................................................................................18
5igure 4G Choosing or creating a proFect director*..................................................................................18
5igure #-ro"iding a name and title >or the proFect.................................................................................1?
5igure 8G roFect creation con>irmation dialog........................................................................................1?
5igure ?G The Gambas I$! a>ter creating a new proFect.........................................................................1%
5igure %G The Gambas I$! showing a >orm in design "iew and displa*ing the properties window.......1+
5igure +G Gambas class page in edit code "iew.......................................................................................20
5igure 10G Gambas I$! 5ile menu..........................................................................................................20
5igure 11 - The Gambas I$! (iew @enu...............................................................................................21
5igure 12G The Gambas I$! roFect @ake @enu...................................................................................21
5igure 13G The Gambas $ebug @enu......................................................................................................21
5igure 14G The Gambas I$! (iew menu.................................................................................................22
5igure 1#G The Gambas I$! main menu and toolbar..............................................................................22
5igure 18G ,sing @@ain to de"elop console applications......................................................................32
5igure 1?G A $i"ision b* Kero !rror $ialog............................................................................................38
5igure 1%G Clari>*ing the 5or 7e2t loop structure...................................................................................##
5igure 1+G The Gambas Toolbo2.............................................................................................................#%
5igure 20G 5irst button code results..........................................................................................................83
5igure 21G $emonstrating >ont capabilities..............................................................................................8#
5igure 22G The dotted line indicates >ocus >or a control..........................................................................8+
5igure 23G 'a*out >or the 5@ain >orm >or the second proFect.................................................................?0
5igure 24G A partiall* constructed >orm with our >irst >our controls.......................................................?1
5igure 2#G The Gambas !"ent @enu.......................................................................................................?2
5igure 28G Adding the 5un:tn to our >orm..............................................................................................?4
5igure 2?G Initial displa* o> our >orm.......................................................................................................?#
5igure 2%G 5igure 10G The progress bar when the 5un:tn is clicked three times. ..................................?#
5igure 2+G Third roFect >inal results.......................................................................................................?%
5igure 30G ,sing .T@' to >ormat a te2t label........................................................................................%0
5igure 31G @odi>ied Te2t'abel output using .T@' >ormatting.............................................................%1
5igure 32G Adding a ToolTip to in>orm the user how to show9hide a control.........................................%3
5igure 33G 1ur Combo:o2......................................................................................................................%4
5igure 34G The !dit 'ist ropert* editor..................................................................................................%#
5igure 3#G 5ormatting a Te2t'abel with .T@'......................................................................................%8
5igure 38G ,sing plus and minus buttons to alter the Combo:o2 list.....................................................%8
5igure 3?G -hat our 'ist:o2 will look like.............................................................................................%%
5igure 3%G The 'ist:o2 edit list propert* editor......................................................................................%%
5igure 3+G -hat the e2ample >rame we build will look like....................................................................+0
5igure 40G A anel control containing 6adio:uttons..............................................................................+3
5igure 41G Third roFect >inal results.......................................................................................................+4
10
5igure 42G @enu proFect >inal result........................................................................................................+#
5igure 43G The Gambas @enu !ditor when it starts................................................................................+8
5igure 44G !diting menu entries in the @enu !ditor...............................................................................+?
5igure 4#G The Gambas @enu !ditor....................................................................................................100
5igure 48G A >ormatted te2t label displa*ing the color "alue.................................................................103
5igure 4?G /electing colors and >onts.....................................................................................................110
5igure 4%G @aking a new de>ault >ont >or the Te2t'abel1 control........................................................111
5igure 4+G An In>ormation @essage:o2...............................................................................................112
5igure #0G A checked menu item...........................................................................................................112
5igure #1G A Auestion @essage:o2......................................................................................................113
5igure #2G An !rror @essage:o2..........................................................................................................114
5igure #3G A -arning @essage:o2.......................................................................................................11#
5igure #4G A $elete @essage:o2 with three buttons............................................................................118
5igure ##G The 1pen 5ile $ialog in Gambas.........................................................................................11?
5igure #8G The /a"e 5ile $ialog in Gambas..........................................................................................11?
5igure #?G The /elect$irector* dialog...................................................................................................11%
5igure #%G Choosing the !2plorer e2ample...........................................................................................1#0
5igure #+G 'a*out >or our 'ist(iew e2ample........................................................................................1#%
5igure 80G Creating a new Icon image in G:........................................................................................183
5igure 81G The Icon !ditor Toolbo2......................................................................................................183
5igure 82G 1ur sEuare icon image..........................................................................................................183
5igure 83G 1ur circle icon image...........................................................................................................183
5igure 84G Tree"iew e2ample.................................................................................................................184
5igure 8#G -hat our Grid(iew will look like........................................................................................1?1
5igure 88G 1ur Column(iew e2ample...................................................................................................1?#
5igure 8?G 1ur editable Column(iew e2ample.....................................................................................1?%
5igure 8%G 'a*out proFect icons.............................................................................................................1%1
5igure 8+G 5orm1 design mode showing la*out o> our controls............................................................1%1
5igure ?0G 'a*out program at program startup......................................................................................1%4
5igure ?1G A Tab/trip control................................................................................................................1%#
5igure ?2G Tabbed >orm design la*out...................................................................................................1%8
5igure ?3G Tab0 la*out...........................................................................................................................1%8
5igure ?4G Tab1 la*out...........................................................................................................................1%?
5igure ?#G Tab2 Tool:utton la*out with icons......................................................................................1%%
5igure ?8G Tab3 la*out with a Combo:o2.............................................................................................1%%
5igure ??G Tab4 la*out with a Timer.....................................................................................................1%+
5igure ?%G The 5ile1psAT program at runtime.....................................................................................201
5igure ?+G The sample application in design mode...............................................................................201
5igure %0G /ample application icons......................................................................................................202
5igure %1G 5orm1.>orm design mode.....................................................................................................21#
5igure %2G 5inished Contacts program...................................................................................................2#2
5igure %3G Toolbar icons used in our sample program..........................................................................2##
5igure %4G 5@ain as seen in design mode..............................................................................................2#?
5igure %#G $esigning the search >orm....................................................................................................28#
5igure %8G 1ur >inished program running on the 'inu2 @int desktop..................................................2?1
11
5igure %?G g>2$emo 5@ain la*out........................................................................................................2?#
5igure %%G 6esults o> clicking the Te2t :utton......................................................................................2?%
5igure %+G 6esults o> In"6ect button click. 7ote the tin* black crosshair center screen......................2%0
5igure +0G ,sing the !llipses button to demonstrate drawing lines and ellipses...................................2%3
5igure +1G 1utput a>ter clicking the 5ill6ect button..............................................................................2%#
5igure +2G ,sing $raw.ol*gon to draw a triangle...............................................................................2%?
5igure +3G ,sing $raw.ol*line to draw lines.......................................................................................2%+
5igure +4G ,sing tiled images as a background on a >orm.....................................................................2+?
5igure +#G 'oading and displa*ing graphics in Gambas3......................................................................2++
5igure +8G !rror results caught with T6C.............................................................................................308
5igure +?G CATC. test program opening screen..................................................................................30%
5igure +%G $i" b* Kero error caught b* CATC....................................................................................30%
5igure ++G The Te2t'abel updated with error in>o.................................................................................30%
5igure 100G In>o message that the error is cleared.................................................................................30%
5igure 101G @ain screen a>ter error has been cleared............................................................................30+
5igure 102G $e>ault Gambas error dialog..............................................................................................30+
5igure 103G 1ur e"ent was raised..........................................................................................................311
5igure 104G @ouse1ps program running...............................................................................................31#
5igure 10#G The 4e*board 1perations program running.......................................................................31%
5igure 108G The :it1ps program in design mode..................................................................................320
5igure 10?G 1ur bit1ps program running..............................................................................................32#
5igure 10%G The 5@ain >orm in design mode........................................................................................33%
5igure 10+G 56eEuest 5orm in design mode..........................................................................................33+
5igure 110G Choosing the Translate option in Gambas..........................................................................3##
5igure 111G The Translate $ialog in Gambas........................................................................................3##
12
Chapter 1 - Introducing Gambas
Gambas ,as initia&&' created b' Beno8t 1inisini, a resident o/ the suburbs o/ Paris#
According to 1inisini, Gambas is a Basic &anguage ,ith ob9ect e6tensions# >he name itse&/ is a
p&a' on the ,ords 3Gambas a&most means Basic3 and, according to 1inisini, Gambas evo&ved
because o/ his persona& programming e6periences ,ith the 1icroso/t !isua& Basic
?
so/t,are
product
"
# Rather than contend ,ith the horrendous number o/ bugs and idios'ncrasies he
/ound in that product, he decided to create Gambas#
Gambas is &icensed under the G:@ Pub&ic License
;
and has ta-en on a &i/e o/ it's o,n
due to its immense popu&arit'# Gambas runs on most Linu6 p&at/orms and the current (at the
time o/ this ,riting stab&e version is Re&ease ;#;;# 1inisini ma-es it ver' c&ear that Gambas
is not compatib&e ,ith !isua& Basic and it ,i&& never be made compatib&e# >he s'nta6 and
interna& ,or-ings o/ Gambas are /ar better and more user /riend&'# 1inisini stated that he
too- /rom !isua& Basic ,hat he /ound use/u& the Basic &anguage, the deve&opment
environment, and the abi&it' to 5uic-&' and easi&' ma-e programs ,ith graphica& user
inter/aces#
1inisini dis&i-ed the overa&& poor &eve& o/ programming common among man' !isua&
Basic programs# >his prob&em ma' be due to the AenforcedB use o/ bad programming
practices that have been imposed on deve&opers as a resu&t o/ the ,ide arra' o/ bugs and
strange idios'ncrasies o/ the proprietar' !B &anguage# Gambas ,as deve&oped to be as
coherent, &ogica& and re&iab&e as possib&e# Because it ,as deve&oped ,ith an approach
designed to enhance programming st'&e and capture the best /eatures the Basic programming
&anguage had to o//er, the addition o/ ob9ect4based programming has a&&o,ed Gambas to
become a popu&ar, modern, stab&e, usab&e programming environment /or Linu6 deve&opers#
Gambas Architecture
Ever' program ,ritten ,ith Gambas Basic (hereina/ter re/erred to as GB is comprised
o/ a set o/ pro9ect /i&es# Each /i&e ,ithin a pro9ect describes a c&ass# >he c&ass /i&es are initia&&'
compi&ed and subse5uent&' e6ecuted b' the Gambas interpreter# >his is ver' simi&ar to ho,
%ava ,or-s# Gambas is made up o/ the /o&&o,ing programsC
A compi&er
An interpreter
An archiver
A graphica& user inter/ace component
A deve&opment environment
7igure " be&o, is an i&&ustration o/ the overa&& architecture o/ Gambas# +n Gambas, a
1 The reader is encouraged to "isit httpG99gambas.source>orge.net9inde2.html to learn more about the Gambas proFect.
2 (isit httpG99www.gnu.org9licenses9licenses.htmlLG'
13
pro9ect contains c&ass /i&es, /orms, modu&es, and data /i&es# A Gambas pro9ect is stored in a
sing&e director'# Compi&ing a pro9ect uses an incrementa& compi&e method that on&' re5uires a
re4compi&ation o/ the modi/ied c&asses# Ever' e6terna& re/erence o/ a c&ass is reso&ved
d'namica&&' at run time# >he Gambas archiver trans/orms the entire pro9ect director'
structure into a standa&one e6ecutab&e# >he Gambas deve&opment environment ,as ,ritten
,ith Gambas to demonstrate the /antastic capabi&ities o/ the &anguage#
2ome other /eatures that set Gambas apart /rom other &anguages inc&ude the /act that
Gambas has an e6tensib&e component architecture that a&&o,s programmers to e6tend the
&anguage# An'one can ,rite components as shared &ibraries that d'namica&&' add ne, native
c&asses to the interpreter# >he component architecture is documented on&ine in the Gambas
Wiki encyclopedia#
D
<e ,i&& cover Gambas components in greater detai& &ater in this boo-#
B' de/au&t, the Gambas +nterpreter is a conso&e4based (te6t4on&' program# >he component
architecture
(
is used to support the graphica& user inter/ace (G@+ portion o/ the &anguage#
Because the G@+ is imp&emented as a Gambas component, it has the abi&it' to be independent
o/ an' speci/ic G@+ too&-it# <ith Gambas, 'ou can ,rite a program and choose ,hich too&-it,
such as G>EF
G
, Ht
I
, etc#, to use &ater# >he current re&ease o/ Gambas imp&ements the
graphica& user inter/ace ,ith the Ht too&-it# >he G@+ components are derived direct&' /rom
3 /ee the Gambas -iki at httpG99gambas.source>orge.net9inde2.html >or more details.
4 /ee httpG99gambas.source>orge.net9architecture.html >or the original rendition o> this graphic.
# /ee httpG99www.gtk.org9 >or more in>ormation on GT4M.
8 /ee httpG99www.trolltech.com9products9gt9 >or more in>ormation on the Et product.
14
Figure 1: The Gambas Architecture.
the Ht &ibrar'# +t is recommended that the reader consu&t ,ith the Ht documentation
J
to
better understand the G@+ contro&s# A G>EF component ,ith a near&' identica& inter/ace to
the Ht component has been imp&emented#
Another /eature o/ Gambas that sets it apart /rom other programming &anguages is the
capabi&it' o/ an' ,indo, or dia&og bo6 to be used &i-e a contro&# >his /eature is not direct&'
supported in other programming &anguages# A&so, Gambas pro9ects are easi&' trans&atab&e,
into a&most an' other &anguage# <e ,i&& demonstrate this /eature &ater in the boo-#
The Gambas Programming Environment
7or no,, &et's ta-e a 5uic- tour and introduce 'ou to the Gambas programming
environment# A&& o/ the e6amp&es and code ,ritten /or this boo- ,ere deve&oped using
Gambas version ;#;; running on @buntu Linu6 "$#$(
*
and tested using both Gambas version
;#J running on .ebian
)
G#$I, and Gambas D#$ A&pha running on @buntu Linu6 "$#$(# >he'
shou&d ,or- on an' p&at/orm ,here 'ou can insta&& Gambas success/u&&'# 7or man' Linu6
users, it is as simp&e as the c&ic- o/ a button using the so/t,are insta&&ation /eatures o/ 'our
speci/ic distribution#
<hen 'ou /irst start the Gambas program, 'ou ,i&& be presented ,ith an opening
screen simi&ar to that /ound in 7igure ; above# >he ,e&come screen a&&o,s 'ou to create a ne,
pro9ect, open an e6isting pro9ect, vie, and se&ect /rom recent pro9ects, &oo- at e6amp&es, or
5uit# 7or our 5uic- tour o/ Gambas, ,e are going to se&ect the :e, Pro9ect option and create
? /ee httpG99doc.trolltech.com94.?9inde2.html >or more in>ormation.
% /ee httpG99www.ubuntu.com9 >or ,buntu in>ormation.
+ /ee httpG99www.debian.org9 >or $ebian in>ormation.
1#
Figure 2: The Gambas opening (Welcome) screen.
our /irst Gambas pro9ect# Kou ,i&& see a dia&og simi&ar to 7igure D be&o, appear#
7or our e6amp&e, choose the /irst se&ection, ACreate a graphical projectB and c&ic- the
Next button at the bottom o/ the dia&og# >he ne6t dia&og that 'ou see (sho,n as 7igure
( be&o, re5uires 'ou to se&ect 'our pro9ect director'# Kou have the abi&it' to create a ne,
/o&der on 'our &oca& /i&e s'stem at this step#
C&ic- the Next button at the bottom o/ the dia&og to continue to the ne6t step o/ the
,i0ard, Pro9ect +n/ormation# >he most important thing to remember about this screen is that
it is the &ast chance 'ou have to bac- up and ma-e changes be/ore 'our ne, pro9ect is created#

18
Figure 3: The Gambas Project reation Wi!ar".
Figure #: hoosing or creating a project "irector$.
At this section o/ the ,i0ard, 'ou need to speci/' the name o/ the pro9ect as it ,i&& be
stored on dis-# +n Gambas, a pro9ect is se&/4contained and a&,a's stored in its o,n pro9ect
/o&der# >he Gambas +.E does not care ,here 'ou choose to &ocate 'our /i&es as it ,i&& -eep a&&
the re5uired /i&es /or 'our pro9ect in the /o&der 'ou name (e#g#, Ch"LListingL"# >he /o&der
name 'ou choose as the name /or the pro9ect is ,hat ,i&& be created and used on 'our s'stem#
>he tit&e o/ the pro9ect ,i&& be ,hat 'ou speci/' in the second te6t input /ie&d o/ the dia&og# 7or
no,, 9ust /i&& out the dia&og as sho,n in 7igure G above and c&ic- the Next button# Kou
shou&d see the /o&&o,ing pro9ect creation con/irmation dia&ogC
>his dia&og is simp&' a con/irmation screen o/ the choices 'ou have made# C&ic- the
OK button to continue to the +.E and 'our ne, pro9ect# Once 'ou have c&ic-ed on the AOKB
button to /inish this ,i0ard, Gambas ,i&& present 'ou ,ith the Gambas integrated
deve&opment environment (+.E as sho,n in 7igure J be&o,#
1?
Figure %&Pro'i"ing a name an" title (or the project.
Figure ): Project creation con(irmation
"ialog.
Gambas IDE Components
>he Project Explorer (seen on the &e/t side o/ 7igure * be&o, is the main navigation
too& used in the Gambas +.E# +t sho, 'ou a >ree!ie, o/ the t'pes o/ /i&es /ound ,ithin 'our
pro9ect (i.e., class files, forms, modules, and other types of files such as data and picture or
icon files). The Pro9ect E6p&orer a&&o,s 'ou to per/orm most Gambas pro9ect management
operations, such as opening and saving pro9ects, bui&ding e6ecutab&es, running 'our program
or debugging it, sho,ing or hiding various Gambas dia&ogs, etc# 7rom the >ree!ie, in the
Pro9ect E6p&orer, 'ou ,i&& see the items &isted as /o&&o,sC
1odu&es
C&asses
7orms
.ata
Modules disp&a' the modu&es 'ou've ,ritten /or 'our pro9ect# 1odu&es are simp&' sets
o/ subroutines and /unctions to be used an',here in 'our program# @n&i-e c&asses, 'ou can't
ma-e ob9ects out o/ them at run time and the' have no event hand&ers#
Clsses &ists the c&ass /i&es 'ou've created /or 'our pro9ect# C&asses are basica&&'
temp&ates that can be used to ma-e ob9ects out o/ at run time, ,ith code to de/ine properties,
1%
Figure *: The Gambas +,- a(ter creating a ne. project.
methods and event hand&ers /or each ob9ect 'ou create#
!or"s &ists the various /orms 'ou create /or 'our pro9ect# 7orms are the ,indo,s the
user actua&&' interacts ,ith#
#t &ists the other /i&es in 'our pro9ect# >hese can inc&ude an' other -ind o/ /i&e used
to bui&d 'our pro9ect, such as graphic /i&es, icons, bitmaps, te6t or =>1L /i&es, and even media
/i&es# At the bottom o/ the Pro9ect E6p&orer, 'ou ,i&& /ind the $ttus %r ,hich is used to
indicate ,hat Gambas is current&' doing#
<hen 'ou start to deve&op a pro9ect in Gambas, 'ou ,i&& usua&&' ,ant to begin ,ith a
main /orm# >he main /orm is ,here the program startup and initia&i0ation ,i&& occur and it is
usua&&' the /irst thing 'our user ,i&& see ,hen the' e6ecute (or run the app&ication 'ou have
bui&t# B' de/au&t, this /orm is named 71ain# >his is the /orm 'ou ,i&& add contro&s to and
speci/' ,hat actions are to be ta-en ,hen the user interacts ,ith those contro&s# 2uch
interactions bet,een the user and the G@+ are re/erred to as events#
>he contro&s Gambas uses are /ound in the >oo&bo6 /ound on the &o,er right corner o/
7igure * be&o,# Kou can change the appearance and behavior o/ the contro&s b' setting the
properties /or each contro&# Properties can be seen and changed /rom ,ithin the properties
,indo, sho,n on the right o/ side o/ 7igure * be&o,# Kou can see a /orm under construction
(,ith no contro&s added at this point disp&a'ed as the gra'ed rectang&e center4screen#
A c&ass page is being coded in 7igure ) be&o,# Kou ,i&& ,or- ,ith modu&es, c&asses and
1+
Figure /: The Gambas +,- sho.ing a (orm in "esign 'ie. an"
"ispla$ing the properties .in"o..
/orms as tabbed pages in the +.E ,indo,, simi&ar to those sho,n in these e6amp&es# 7rom
the /igure be&o,, 'ou can see that the s'nta6 o/ Gambas is ver' simi&ar to that o/ other visua&
basic &anguages, but not enough to be interchangeab&' used#
>he Gambas deve&opment environment provides the /eatures such as s'nta6
high&ighting o/ Gambas code, =>1L and C22 /i&es, automatic comp&etion o/ -e',ords, a G@+
/orm editor and integrated debugger, an icon editor, and a string trans&ator# 2ome other
/eatures o/ this code editing environment inc&ude co&or4coding /or -e',ords, &ine numbering
(use/u& /or debugging, and structured indentation#
:o,, &et's consider the menus and buttons /ound at the top4&e/t corner o/ the Pro9ect
E6p&orer# >he menus contro& a&& the main Gambas management tas-s# >he 7i&e menu (7igure
"$ ,i&& a&&o, 'ou to open a pro9ect, save a pro9ect, create a ne, pro9ect, open some Gambas
e6amp&e pro9ects, or 5uit using Gambas#
20
Figure 0: Gambas class page in e"it co"e 'ie..
Figure 11: Gambas +,- File menu.
>he Pro9ect 1enu is ,here program compi&ation occurs# Kou can create the program
e6ecutab&e, ma-e a source archive or an insta&&ation pac-age /rom this menu b' choosing the
1a-e menu item and se&ecting the appropriate entr'# >his menu a&so provides house-eeping
/unctions and opens a dia&og ,ith a range o/ options, inc&uding trans&ating 'our program into
another &anguage#

>he .ebug 1enu &ets 'ou run 'our program inside the +.E, and o//ers contro&s to
iso&ate prob&ems ,ith 'our programming code# <hen 'our e6ecutab&e is running, 'ou can
pause it, stop it, step /or,ard through the code b' e6ecutab&e statement, or /inish the
e6ecuting process and return to programming# +/ 'ou have set brea-points in the code edit
,indo,, 'ou can a&so c&ear them using this menu#
21
Figure 12: The Gambas +,-
Project 2a3e 2enu.
Figure 13: The Gambas ,ebug 2enu.
Figure 11 & The Gambas +,- 4ie. 2enu.
>he !ie, menu ,i&& a&&o, 'ou to bring up the Pro9ect E6p&orer, the Properties pane, or
vie, the >oo&Bo6 pane# Kou can open a conso&e /rom here# <hen the Properties ,indo, is
open (as sho,n in 7igure *, on the right4hand side o/ the picture, the =ierarch' option
appears as a page tab, and this page sho,s 'ou 'our pro9ect's c&ass hierarch'# 7ina&&', /rom
this menu, 'ou can c&ose a&& o/ the ,indo,s that are current&' open in the +.E#
7igure "G be&o, sho,s 'ou the 7i&e menu and too&bar# >he &ool%r buttons provide
sing&e4c&ic- access to the most common menu items# =overing 'our mouse cursor over one o/
the buttons ,i&& disp&a' a &ool&ip that ,i&& te&& 'ou ,hat menu action that particu&ar button
,i&& per/orm#
7rom the Pro9ect E6p&orer &ree'iew 'ou can doub&e c&icon a /orm and it ,i&& pop up
/or 'ou to edit (as sho,n in 7igure ) above# Editing /orms is simp&' a matter o/ se&ecting
,hat t'pe o/ contro& 'ou'd &i-e to p&ace on the /orm and then using the mouse to resi0e (dra,
and position it on 'our /orm#
Right c&ic-ing on the /orm or an' o/ its chi&dren (contro&s ,i&& sho, 'ou a pop4up
menu that ,i&& a&&o, 'ou to per/orm operations on the contro&, edit its properties or de&ete it#
>he current&' se&ected contro& is indicated b' /our b&ac- s5uares ca&&ed hand&es# C&ic-ing on a
hand&e and using the mouse to drag the contro& ,here 'ou ,ant it ,i&& a&&o, 'ou to move or
resi0e the contro&# .oub&e c&ic-ing on a contro& ,i&& bring up the code editor ,indo, and
disp&a' an' e6isting event hand&er /or the contro& or disp&a' a de/au&t event hand&er i/ there
have been none speci/ied#
>he Gambas Code Editor enab&es 'ou to ,rite code to hand&e events /or the contro&s
'ou've p&aced on 'our /orm# +n the too&bo6 ,indo,, the 2e&ection >oo& is the on&' item in the
too&bo6 that isn't actua&&' a contro&# >he se&ection too& simp&' gives 'ou contro& o/ the de/au&t
mouse pointer# Kou use this pointer to se&ect contro&s and per/orm positioning and resi0ing
operations on /orms and their associated contro&s#
22
Figure 1%: The Gambas +,- main menu an" toolbar.
Figure 1#: The Gambas +,- 4ie. menu.
7rom the 7i&e 1enu at the top o/ the +.E, choose the Huit option and save this pro9ect#
<hen ,e reopen it, a&& 'our ,or- ,i&& be saved# +n the ne6t chapter, ,e ,i&& begin to cover the
essentia&s 'ou need to -no, in order to program e//ective&' ,ith Gambas#
<e ,i&& come bac- to this pro9ect to deve&op a program that uses the G@+ a/ter ,e &earn
a bit more about the GB coding environment, the primar' &anguage concepts that are re5uired
to use GB, and some basics about data4t'pes and variab&es#
23
Chapter 2 Language Concepts
+n this chapter, ,e ,i&& begin to &earn the basic concepts needed to master the Gambas
programming &anguage# >he topics ,e ,i&& cover in this chapter inc&ude &earning about
Gambas data4t'pes, constants, and variab&es and ho, to dec&are and assign va&ues to those
constants and variab&es# <e ,i&& &earn about the basic arithmetic operators, comparison
operators, and string operators# <hen ,e start ,riting program code, the code ,i&& be
organi0ed in Acode b&oc-sB that ,i&& &oo- something &i-e thisC
PUBLIC SUB Main()
DIM variable as variable type
DIM another variable as another variable type
statement...expression
more like it...etc.
!D
<e ,i&& &earn more about code b&oc-s &ater, but &et's &oo- at the -e',ords in bo&d#
P(%)*C &ets other parts o/ 'our program (other 3c&asses3 access this code b&oc-#
>he -e',ord $(% comes /rom the ,ord AsubroutineB, and in Gambas it is a -e',ord to
dec&are a procedure 44 some bod' o/ code ,ritten to do a speci/ic 9ob# >he 2@B
-e',ord is s'non'mous ,ith the P+OCE#(+E -e',ord, and these t,o can be used
in code interchangeab&'#
:ote that a $(% has some simi&arit' to a !(NC&*ON, but ,ith one big di//erenceC a
/unction has &imited scope# >he on&' 9ob o/ a !(NC&*ON is to accept parameters
/rom some part o/ a program, process the parameters and return a va&ue to that same
p&ace in the program ,here the !(NC&*ON ,as ca&&ed# +n Gambas, procedures and
/unctions together are re/erred to as AmethodsB#
+n this particu&ar case, Min() signa&s to Gambas that the instructions inside this code
b&oc- ,i&& be the instructions that create the initia& conditions o/ the running program#
>here/ore, the page that this code appears on ,i&& be the Astartup classB /or 'our
program#
>he -e',ord #*M comes /rom the ,ord AdimensionB# .imensioning a variab&e means
that the program sets aside a speci/ic b&oc- o/ memor', o/ a speci/ic si0e, to ho&d the
data represented b' that variab&e#
EN# mar-s the end o/ this procedure#
2o, &oo-ing at the entire /irst &ine ,e can see that this &ine describes a 3method3 (a
$(% that ,i&& a&&o, Gambas to use the 3c&ass /i&e3 or 3modu&e /i&e3 containing this code b&oc-
as the startup c&ass# >his ,i&& be the /irst section o/ code that Gambas ,i&& &oo- /or, ,hen 'ou
run 'our program# Bet,een the /irst &ine and EN#, 'ou can use more Gambas code to
describe the other events that 'ou ,ant to happen ,hen the program starts#
24
Gambas !ariab&es, .ata4t'pes and Constants
!ariab&es must be de/ined at the beginning o/ a c&ass, method or /unction# !ariab&e
dec&arations can either be local to a procedure or /unction or the' can be dec&ared global to a
c&ass# A g&oba& variab&e is accessib&e ever',here in the class it is dec&ared# >he /ormat o/ a
g&oba& variab&e dec&aration in Gambas ta-es the /o&&o,ing genera& /ormC
"S#$#IC%(PUBLIC&P'I($#) I)enti*ier "$rray )eclaration% $S "!+% Data,type
+/ the P(%)*C -e',ord is speci/ied, it is a&so accessib&e to the other c&asses that have
an' re/erence to an ob9ect o/ that c&ass# +/ the P+*',&E -e',ord is speci/ied, it is not
accessib&e outside the c&ass in which it was defined# +/ the $&,&*C -e',ord is speci/ied,
the same variab&e ,i&& be shared ,ith ever' ob9ect o/ the c&ass ,here it is dec&ared# +/ the
NE- -e',ord is speci/ied, the variab&e is initia&i0ed ,ith (i.e., instantiated with a ne,
instance o/ the c&ass using the data4t'pe speci/ied# 7or &oca& variab&e dec&arations, the /ormat
is &i-e thisC
DIM I)enti*ier $S Datatype
>his ,i&& dec&are a &oca& variab&e in a procedure or /unction# >his variab&e is on&'
accessib&e to the procedure or /unction ,here it is dec&ared# An e6amp&e o/ severa& &oca&
dec&arations is sho,n be&o,C
DIM i(al-e $S I!#.'
DIM stMy!ame $S S#'I!.
DIM *MyMatrix"/0 /% $S 1L2$#
DIM oMy2b3ect $S 2B4C#
>here are current&' e&even basic data4t'pes a programmer can use to ,rite program
code in Gambas# >hese data4t'pes inc&ude the /o&&o,ingC
:oolean :*te /hort ointer
Integer 'ong 5loat /ingle
$ate /tring (ariant 1bFect
%oolen dt.types can contain on&' a sing&e va&ue, either >R@E or 7AL2E# >R@E is
de/ined as " and 7AL2E is de/ined as $# >he dec&aration o/ a Boo&ean variab&e occupies " b'te
o/ memor' and the de/au&t va&ue is 7AL2E# An e6amp&e o/ a variab&e dec&aration /or a Boo&ean
variab&e &oo-s &i-e thisC
S#$#IC P'I($# b.ri) $S Boolean
>'pica&&', a programmer ,ou&d use a Boo&ean data4t'pe ,hen the on&' va&ues /or the
2#
variab&e ,ou&d be 'esMno, >R@EM7AL2E, "M$, etc# +/ the va&ues used in 'our program cou&d be
an'thing e&se, Boo&ean ,ou&d be an inappropriate se&ection /or the variab&e data4t'pe#
Another thing to note in the variab&e dec&aration above is the p&acement o/ the &o,ercase &etter
b in /rom o/ the variab&e name#
Good programming convention encourages this practice, -no,n as the =ungarian
:otation
"$
, as it a&&o,s the programmers to -no, ,hat data4t'pe the variab&e is b' simp&'
-no,ing that the '/0 stands /or Boo&ean# <hat happens ,hen a programmer ,ants to use a
B'te data4t'pe instead o/ a Boo&ean data4t'peN >'pica&&', a second &etter is added to the
variab&e dec&aration so rather than using 0/0 in /ront o/ the variab&e name the programmer
,ou&d use 0/y0 as be&o,C
S#$#IC P'I($# bySomethin5 $S Byte
>he &etters 'r' 0s0, 0i0, 0f0, 0d0, 0st0, 0v0 and 0o0 are common&' used notations ,hen
dec&aring variab&es ,hi&e programming in Gambas# +t is good programming practice to /orce
'ourse&/ to adhere to this techni5ue so that others can pic- up 'our code and use it ,ithout
having to search around to /ind the data4t'pe /or each variab&e encountered# 2ome
programmers even use more than the /irst &etter(s to name their variab&es# 7or e6amp&e, the'
,ou&d code IntMyNumber or ByteSomething#
>he %yte dt.type can contain va&ues /rom $ to ;GG and occupies one b'te o/
memor' ,hen dec&ared# >he de/au&t va&ue ,hen a B'te data4t'pe is dec&ared is $# +/ 'ou are
certain 'our va&ues ,i&& not e6ceed ;GG then this data4t'pe is appropriate /or use# +/ it is
possib&e that the va&ues assigned to this variab&e ,ou&d e6ceed ;GG, then the &i-e&' resu&t
,ou&d be a program crash at run time#
+t is better to use the $hort dt.type or an *nteger dt.type /or such situations#
7or a 2hort data4t'pe, va&ues can range /rom 4D;JI* to FD;JIJ# 2hort data4t'pes occup' t,o
b'tes o/ memor' and de/au&t to a 0ero va&ue ,hen dec&ared# +nteger data4t'pes occup' t,ice
as much memor', ta-ing up /our b'tes# >he range o/ va&ues 'ou can use ,ith the +nteger data4
t'pe is /rom 4;,"(J,(*D,I*( to F;,"(J,(*D,I(J, and the +nteger data4t'pe can accept numbers
,ritten in decima&, he6adecima& or binar'#
>he )ong dt.type is an eight4b'te integer va&ue, that accepts integers bet,een
4),;;D,DJ;,$DI,*G(,JJG,*$* and ),;;D,DJ;,$DI,*G(,JJG,*$J# E6amp&es o/ 2hort and +nteger
data4t'pe variab&e dec&arations areC
S#$#IC PUBLIC sSomeShort $S Short
S#$#IC PUBLIC iSomeInte5er $S Inte5er
<hen integers ,i&& not ,or- /or 'our purposes, Gambas provides 'ou ,ith the !lot
dt.type1 >his data4t'pe a&&o,s 'ou to use /&oating point numbers /or 'our program# 7&oat
data4t'pes are &i-e .oub&e data4t'pes used in C and !B# >he range o/ va&ues /or /&oat data4
10 .ungarian 7otation I.7J is a naming con"ention originated b* Charles /imon*i o> @icroso>t. It was >irst presented in
his thesis and is widel* used throughout the source code o> the -indows operating s*stem) among other places.
28
t'pe variab&es is /rom 4"#J)JI)D"D(*I;D;ED$* to 4(#)($IGI(G*(";(JE4D;( /or negative
va&ues and /rom (#)($IGI(G*(";(JE4D;( to "#J)JI)D"D(*I;D;ED$* /or positive va&ues#
7&oat variab&es occup' eight b'tes o/ memor' and de/au&t to a 0ero va&ue ,hen dec&ared# A
samp&e dec&aration /or a /&oat ,ou&d be as /o&&o,sC
DIM *'a)i-s $S 1loat
Gambas a&so provides the 2ing&e data4t'pe, ,hich ho&ds a (4b'te /&oating point va&ue bet,een
4"#J$"(""*E4D* and "#J$"(""*EFD*#
>he &ast numeric data4t'pe ,e have in Gambas is the #te dt.type# .ate variab&es
a&so ta-e up eight b'tes o/ memor'# >he date portion o/ the date is stored in a /our b'te
integer and the time portion is stored in a /our b'te integer# +t is stored as 23er4 Month4
#y 524 6ours4 Minutes4 $econds5 and is usua&&' used ,ith the Gambas bui&t4in .ate and
>ime /unctions, ,hich ,e ,i&& e6p&ain about &ater in this boo-# >he date data4t'pe de/au&ts to
a :@LL va&ue ,hen initia&i0ed# =ere is ho, to dec&are a .ate data4t'peC
DIM ))ate $S Date
DIM )time $S Date
2trings, !ariants and Ob9ects are the non4numeric data4t'pes supported in Gambas# A
$tring dt.type is a series o/ 0ero or more characters that are treated as a sing&e entit'#
2trings can contain a&phanumeric data# A&phanumeric means that the data can contain an'
combination o/ &etters and integers or specia& characters such as 789:;#
2trings, ,hen dec&ared ta-e /our b'tes o/ memor'# >his means the ma6imum si0e /or a
string is ( b'tes O * bits per b'te, or D; bits s5uared (",$;( b'tes# 2tring variab&es de/au&t to a
:@LL va&ue ,hen dec&ared# .ec&are a string variab&e 9ust &i-e 'ou ,ou&d an' other variab&eC
S#$#IC PUBLIC stSomeStrin5 $S Strin5
>he 'rint dt.type is used ,hen 'ou do not -no, ,hat -ind o/ data4t'pe the
variab&e ,i&& be receiving# 7or e6amp&e, i/ reading data /rom a /i&e, 'ou cou&d read an integer, a
string, a sing&e character, /&oating point numbers, etc# >o ensure the data is p&aced in a
variab&e ,ithout causing a program crash, the variant data4t'pe is used#
Kou can then test the variant data using some bui&t4in /unctions o/ Gambas to
determine the data4t'pe or 'ou can 9ust convert the data to the data4t'pe 'ou need using a
conversion /unction# <e ,i&& demonstrate this &ater in the boo-# 7or no,, it is on&' important
that 'ou understand that variant data4t'pes e6ist and that the' are used ,hen 'ou are not sure
o/ the t'pe o/ data the variab&e ,i&& ho&d#
>he O/ject dt.type is a specia& data4t'pe that ho&ds and re/erences ob9ects such as
contro&s and /orms# Later, ,hen ,e begin to discuss OO programming, ,e ,i&& cover the use o/
ob9ect data4t'pes in greater detai&#
2?
>he native Pointer datat'pe represents an address in memor'# +t can be dec&ared &i-e
thisC
DIM (ar $S Pointer
>his is e5uiva&ent to the +nteger datat'pe on D; bits s'stems# +n the I(4bit version o/
Gambas, a Pointer is e5uiva&ent to the Long datat'pe# +n Gambas D, Pointer is a true data t'pe
and 'ou cannot rep&ace a pointer ,ith an integer number# >he tab&e sho,n on the /o&&o,ing
page is presented as a convenient re/erence# :o, that 'ou have &earned a &itt&e about a&& o/ the
di//erent t'pes o/ data that Gambas supports, ,e ,i&& start to &oo- at ,hat 'ou can do ,ith
those#
<hen using 'our variab&es in Gambas programs, the' can be represented b' data that
changes (e.g., it is a variable) or the' can be represented b' data that remains constant
throughout the program# >his t'pe o/ data is -no,n as a Constnt in Gambas# Gambas
constants is used to represent a :@LL ob9ect re/erence, a 0ero &ength string, a :@LL date, or
an uninitia&i0ed variant# E6amp&es o/ constants inc&ude the va&ues :@LL, >R@E and 7AL2E#
Gambas data-types
N"e #escription Me"ory si<e #efult
Boo&ean >rue or 7a&se " b'te 7AL2E
B'te $ ### ;GG " b'te $
2hort 4D;JI* ### FD;JIJ ; b'tes $
+nteger 4;"(J(*DI(* ### F;"(J(*DI(J
(base"$, he6 and binar'
( b'tes
$
Long 4),;;D,DJ;,$DI,*G(,JJG,*$*###
F),;;D,DJ;,$DI,*G(,JJG,*$J
* b'tes
$
7&oat 2imi&ar to the doub&e data4t'pe in C * b'tes $
2ing&e 4"#J$"(""*E4D*### "#J$"(""*EFD* ( b'tes $
.ate .ateMtime, each stored in a ( b'te integer# * b'tes :@LL
2tring A re/erence to a variab&e &ength string# ( b'tes :@LL
!ariant Can consist o/ an' data4t'pe# "; b'tes :@LL
Ob9ect An indirect re/erence to an ob9ect# ( b'tes :@LL
Pointer A memor' address# ( b'tes on D; bit s'stems
* b'tes on I( bit s'stems
$
>o dec&are a constant in Gambas use the /o&&o,ing /ormatC
( PUBLIC & P'I($# ) C2!S# I)enti*ier $S Datatype 6 val-e
>his dec&ares a c&ass g&oba& constant# >his constant is accessib&e ever',here in the c&ass
it is dec&ared# +/ the P(%)*C -e',ord is speci/ied, it is a&so accessib&e to the other c&asses
2%
having a re/erence to an ob9ect o/ this c&ass# Constant va&ues must be Boo&ean, integers,
/&oating point or string data4t'pes# =ere are some e6amp&es o/ constant dec&arationsC
PUBLIC C2!S# M$781IL $S Inte5er 6 /9
P'I($# C2!S# M$.IC8:$D' $S Strin5 6 ;< .ambas *orm *ile;
>he bui&t4in constants 'ou ,ou&d use in Gambas are &isted in the tab&e be&o,C
Gambas Constants
Constnt Ex"ple
>he >R@E va&ue# >R@E
>he 7AL2E va&ue# 7AL2E
+nteger numbers# $, GI;, "J, 4D;JI)
=e6adecima& short signed integers# P="$$7D, P=7$77, P7777
=e6adecima& signed integers# P="AB7DD;E, P"CB7D$;E
=e6adecima& unsigned integers# P=*$A$P, P=7C77P
Binar' integers# PQ"$"$""""$", R"$"$$$$""
7&oating point numbers# "#"""$, 4G#D(")EF(
2tring constants# 3=e&&o, Gambas <or&dS3
2tring constants to be trans&ated# (3>his is ver', ver' coo&3
:@LL constant M void string# :@LL
String constants can a&so contain the /o&&o,ing escape charactersC
Escpe chrcter ,$C** e=uivlent
Tn C=RU("D
Tr C=RU("$
Tt C=RU()
TB .oub&e 5uote
TT Bac-s&ash
T66 C=RU(P=66
Kou can ,rite a string constant in severa& successive parts# 7or e6amp&e, A1' sonB A is A
Asi6teenB is seen b' Gambas as A1' son is si6teenB#
Variable Assignment
A programmer can assign an' va&ue to a variab&e in Gambas b' using the /o&&o,ing
genera& /ormatC

2+
(ariable 6 xpression
>his assignment statement assigns the va&ue o/ an e6pression to one o/ the /o&&o,ing
e&ementsC

A &oca& variab&e
A /unction parameter
A g&oba& (c&ass variab&e
An arra' e&ement
A pub&ic ob9ect variab&e or propert'
=ere are some e6amp&e o/ variab&e assignmentsC
iMy(al 6 =>?@
stMy!ame 6 ;2rAell;
*My!-m 6 =B/.@C
Assignment Using The WITH Statement
>his statement is most common&' used to set properties /or contro&s# >he e6pression
that e6ists bet,een the -*&6 keyword and the EN# -*&6 instruction is used# >he
e6pression ,i&& begin ,ith dot notation, i#e#, #>e6t cou&d be used# <+>= assigns the dotted
e6pression on the &e/t o/ the e5ua& sign the va&ue /ound on the right side o/ the e5ua& sign#
Epression must be an ob9ect# =ere is a samp&e o/ ho, the <+>= structure &oo-sC
+I#: xpression
.ob3ect 6 Dsomethin5E
!D +I#:
As an e6amp&e, the code be&o, is code e5uiva&ent to h%utton1&ext > ?Exit?
+I#: hB-tton
.#ext 6 ;xit;
!D +I#:
Operators and Epressions
:o, that ,e -no, ho, to dec&are variab&es and constants and ho, to assign va&ues to
these variab&es and constants, &ets ta-e a &oo- at the operations that can be per/ormed ,ith
them# <e ,i&& begin ,ith arithmetic operators then ta-e a &oo- at comparison operators and
string operators#
30
Arithmetic Operators
A&& o/ the basic arithmetic operations are supported in Gambas# >hese operators
inc&ude addition, subtraction, mu&tip&ication, and division# >he standard s'mbo&s /or these
operations are '@', '.', ';', and 'A'# 7or e6amp&e, Nu"/er @ Nu"/er ,i&& add t,o numbers#
<hen a va&ue or variab&e is preceded b' a minus sign, .BBB4 /or e6amp&e, Gambas computes
the opposite sign o/ that number# >he va&ue Vero is the opposite o/ itse&/#
:o,, ,e ,i&& start to ,rite some Gambas code using the Gambas termina& app&ication
/eature# >he conso&e ,indo, ,i&& disp&a' our output so &ets use Gambas to e6periment ,ith
the operators as ,e &earn about them#
Comparison operators
Comparison o/ t,o variab&es re5uires /inding ans,ers to 5uestions &i-e !does x e"ual
y# or !is a less than b## >he /o&&o,ing comparisons are supported in GambasC
Opertor Mening Ex"ple
> +s e5ua& to +7 a W b >=E: ###
CD +s not e5ua& +7 a XY c >=E: ###
C +s &ess than +7 a X d >=E: ###
D +s greater than +7 a Y e >=E: ###
C> +s &ess than or e5ua& to +7 a XW / >=E: ###
D> +s greater than or e5ua& to +7 a YW g >=E: ###
Let's Start Coing Gambas
:o, that ,e -no, about data4t'pes and variab&e assignments, &ets get our /eet ,et ,ith
Gambas# 2tart Gambas and /rom the 7i&e 1enu se&ect :e, Pro9ect# As 'ou go through the
:e, Pro9ect <i0ard, se&ect a Command4&ine app&ication and c&ic- Next# P&ace this
pro9ect in a director' ca&&ed CommandlineTest and name it CommandlineTest# .on't ,orr'
about an' o/ the other options# %ust c&ic- Next unti& the ,i0ard comp&etes#
Once the +.E appears ,ith 'our ne, pro9ect ,e ,i&& need to create a startup c&ass in
order to run our code# +n Gambas, a command &ine app&ication is based on a specia& c&ass
ca&&ed a Amodu&eB, ,hich is a A2>A>+CB c&ass (,e ,i&& ta&- more about the 2>A>+C dec&aration
&ater#
7rom the Pro9ect E6p&orer /ind the >ree!ie, item ca&&ed Modules and doub&e4c&ic-
the mouse on the icon &abe&ed A11ainB# >his is a&,a's 'our de/au&t modu&e /or a command
&ine app&ication# >he code ,indo, ,i&& appear simi&ar to the /igure sho,n be&o,# +nside the
,indo,, 'ou shou&d &oo- something ver' simi&ar to the /igure &e/t#
31
+n Gambas, ,hen ,e start ,riting programs, the code ,i&& be organi0ed in Acode b&oc-sB that
,i&& &i-e&' &oo- something &i-e thisC
PUBLIC SUB Main()
DIM variable as variable type
DIM another variable as another variable type
statement...expression
more like it...etc.
!D
<e ,i&& &earn more about code b&oc-s &ater in the boo-, but &et's &oo- at some o/ the
more signi/icant -e',ords sho,n above in bo&d &etters, starting ,ith P(%)*C it &ets other
parts o/ 'our program (other 3c&asses3 access this code b&oc-# $(% comes /rom the ,ord
AsubroutineB, and in Gambas it is a -e',ord to dec&are a procedure some bod' o/ code
,ritten to do a speci/ic 9ob# >he $(% -e',ord is s'non'mous ,ith the P+OCE#(+E
-e',ord, and these t,o can be used in code interchangeab&'# :ote that a 2@B has some
simi&arit' to a !(NC&*ON, but ,ith one big di//erenceC a /unction has &imited scope its
on&' 9ob is to accept parameters /rom some part o/ a program, process the parameters and
return a va&ue to that same p&ace in the program ,here the !(NC&*ON ,as ca&&ed# +n
32
Figure 1): 5sing 22ain to "e'elop console applications.
Gambas, procedures and /unctions together are re/erred to as AmethodsB# +n this particu&ar
case, Min() signa&s to Gambas that the instructions inside this code b&oc- ,i&& be the
instructions that create the initia& conditions o/ the running program#
>he -e',ord #*M comes /rom the ,ord AdimensionB# .imensioning a variab&e means
that the program sets aside a speci/ic b&oc- o/ memor', o/ a speci/ic si0e, to ho&d the data
represented b' that variab&e# EN# mar-s the end o/ this procedure# 2o, &oo-ing at the entire
/irst &ine o/ code, ,e can see that this &ine describes a method (i#e#, a $(% that ,i&& a&&o,
Gambas to use the c&ass or modu&e /i&e containing this code b&oc- as the startup c&ass# >his
,i&& be the /irst section o/ code that Gambas ,i&& &oo- /or, ,hen 'ou run 'our program#
Bet,een the /irst &ine and EN#, 'ou ,i&& use Gambas code to describe the other events that
'ou ,ant to happen ,hen the program starts# :o,, &et's ta-e a &oo- at some other important
Gambas -e',ords 'ou shou&d -no, a bit more about be/ore ,e proceed#
E!D" #ETU#! an $UIT Statements
>he EN# -e',ord indicates the end o/ a procedure or a /unction# >here are
di//erences /rom !B ,hen using EN## +n !B, the End command c&oses a&& /orms and /i&es
and terminates the program# +n Gambas, the EN# command ,or-s more &i-e !B's End
!unction combined ,ith !B's End $u/1 +t c&oses the /unction or subroutine# 7or simi&ar
/unctiona&it' to !B's End command, use the E(*& command# +t ends the program
immediate&'# A&& ,indo,s are c&osed, and ever'thing is /reed up in memor' as c&ean&' as
possib&e#
+n Gambas, ,hen 'ou ,ish to e6it a routine, 'ou can use the RE>@R: command#
@sua&&', +E&(+N is used to return a va&ue to the ca&&ing procedure# >he /ormat o/
+E&(+N isC
'#U'! " xpression %
<hen Gambas e6ecutes the +E&(+N command, it 5uits a procedure or a /unction and
comp&etes its ,or- b' returning the va&ue o/ Epression# :o,, enter the /o&&o,ing code a/ter
the 0 F"/s "odule file &ine (note that comments in Gambas start ,ith the $ %a&a., a tic&
mar&') and e6ist bet,een the P(%)*C $(% Min() and EN# statements# Once 'ou have
entered the code sho,n be&o, in the Gambas code ,indo,, c&ic- the D button on the >oo&Bar
to e6ecute 'our program# =ere is the code 'ou ,ant to tr' /irstC
PUBLIC SUB Main()
DIM n $S Inte5er
DIM r $S Inte5er
n 6 /
r 6 ,F
P'I!# ;Di) yo- knoA that ;G nG ; H ;G rG ; eI-als ;G n H rG ;J;
!D
33
+/ a&& goes ,e&&, 'ou ,i&& see the conso&e ,indo, respond ,ith the /o&&o,ingC
Di) yo- knoA that / H ,F eI-als /J
.on't ,orr' about the s'nta6 o/ the P+*N& statement or the use o/ the -e',ord #*M used to
dec&are our variab&es /or no,# <e ,i&& cover these -e',ords &ater in the boo-#
>o subtract va&ues, use the /ormat Nu"/er . Nu"/er and Gambas ,i&& subtract the
second number /rom the /irst#
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 ?
' 6 C
P'I!# ;666K ;G !,'G
!D
>he conso&e ,i&& respond ,ith the /o&&o,ingC
66K /
>o mu&tip&' numbers, ,e use the /ormat o/ Nu"/er ; Nu"/er and Gambas ,i&&
mu&tip&' the t,o numbers# =ere is another conso&e e6amp&e to tr'C
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 ?
' 6 C
P'I!# ;666K ;G ! L 'G
!D
66K @9
.ivision is no di//erent than mu&tip&ication# @se the /ormat o/ Nu"/er A Nu"/er to
have Gambas divide t,o numbers# A division b' 0ero error ,i&& occur i/ the va&ue o/ the
number to the right o/ the s&ash is 0ero# >r' this conso&e e6amp&eC
PUBLIC SUB Main()
DIM ! $S Inte5er
34
DIM ' $S Inte5er
! 6 >
' 6 /
P'I!# ;666K ;G ! M 'G
!D
66K /
:o, tr' using the T to divide instead o/ the M characterC
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 >
' 6 C
P'I!# ;666K ;G ! N 'G
!D
>he conso&e ,i&& respond ,ith the 5uotientC
66K =
>his operation is ca&&ed Ainteger divisionB# +/ 'ou use a bac-s&ash to divide numbers, i#e#,
Nu"/er G Nu"/er Gambas computes the =uotient o/ the t,o numbers, ,ithout the
remainder# A division b' 0ero error ,i&& occur i/ the va&ue o/ the number to the right o/ the
bac-s&ash is 0ero# , G % is the e5uiva&ent o/ *N&(,A%)# >o get the remainder, ,e can use the
bui&t4in MO# /unction &i-e thisC
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 >
' 6 C
P'I!# ;666K ;G ! N 'G ; an) the remain)er isO ;G> M2D CG
!D
>he conso&e responds ,ithC
666K = an) the remain)er isO @
@sing Nu"/er MO# Nu"/er computes the re"inder o/ the 5uotient o/ the t,o
numbers# A division b' 0ero error ,i&& occur i/ the va&ue o/ the number to the right o/ the
3#
MO# operator is 0ero# 7ina&&', ,e can test the .ivision b' Vero error b' t'ping this e6amp&eC
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 >
' 6 9
P'I!# ;666K ;G ! M 'G
!D
Gambas ,i&& respond ,ith the /o&&o,ingC
NO!" Clic& the Stop button when you see this dialog appear.
+n order to raise a number to a given po,er (e6ponent, use the /ormat o/ Nu"/er 9
Power and Gambas raises :umber to the po,er the Power operator speci/ied# >r' thisC
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 B
' 6 /
P'I!# ;666K ;G ! P 'G
!D
66K ?
Gambas a&so has the abi&it' to support &ogica& arithmetic operations
""
# @sing the /ormat
o/ Nu"/er ,N# Nu"/er instructs Gambas to use the ,N# operator (,N# stating Aboth
are trueB to compute the mathematica& ,N# o/ the binar' va&ues o/ both o/ the numbers#
>r' thisC
11 In Gambas2) it will allow the use o> concatenated operators. 5or e2ample) a MN 2 or : 9N 4 will work Fust as i> *ou
were programming in C or CMM.
38
Figure 1*: A ,i'ision b$ 6ero -rror
,ialog.
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 9
' 6 9
P'I!# ;6K ;G! $!D 'G; is the $!D res-lt o* ;G!G; an) ;G'
' 6 =
! 6 =
!D
>he conso&e ,indo, responds ,ithC
6K 9 is the $!D res-lt o* 9 an) 9
6K 9 is the $!D res-lt o* 9 an) =
6K = is the $!D res-lt o* = an) =
>he A:. operator can on&' be true (" i/ both terms are true# Li-e,ise, Nu"/er O+
Nu"/er used the O+ operator (O+ stating Aat &east one is trueB and computes the
mathematica& O+ o/ the binar' va&ue o/ the t,o numbers#
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 9
' 6 9
P'I!# ;6K ;G! 2' 'G; is the 2' res-lt o* ;G!G; 2' ;G'
' 6 =
! 6 =
!D
6K 9 is the 2' res-lt o* 9 2' 9
6K = is the 2' res-lt o* 9 2' =
6K = is the 2' res-lt o* = 2' =
>he OR operator can on&' be true (" i/ one or both terms are true#
3?
(umber HO+ (umber uses the HO+ operator (QO+4 IExclusive O+J4 stating that
Aone and on&' one is trueB and computes the mathematica& e6c&usive OR o/ the binar' va&ue
o/ the t,o numbers#
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 9
' 6 9
P'I!# ;6K ;G! 72' 'G; is the 72' res-lt o* ;G !G ; 72' ;G '
' 6 =
! 6 =
!D
6K 9 is the 72' res-lt o* 9 72' 9
6K = is the 72' res-lt o* 9 72' =
6K 9 is the 72' res-lt o* = 72' =
>he QOR operator can on&' be true (" i/ one and on&' one term is true# Additiona&&', the
/o&&o,ing operators manipu&ate one or more numeric va&ues and return a numeric va&ueC
DC & I!C & LIQ & !2#
>he #EC operator is used to decrement a va&ue b' one# >he *NC operator ,i&&
increment the va&ue b' one# >he variab&e can be an' target o/ an assignment but must be a
numeric va&ue#
PUBLIC SUB Main()
DIM ! $S Inte5er
DIM ' $S Inte5er
! 6 C
' 6 C
DC !
I!C '
P'I!# ;666K ;G !G ; & ;G 'G
!D
66K @ & F
3%
)*KE is used to per/orm a Boo&ean comparison o/ a string# +t ta-es the /ormat o/
$tring )*KE Pttern and it returns >R@E i/ the 2tring matches the Pattern# >he pattern can
contain the /o&&o,ing pattern4matching characters C
; 1atch any number o/ an' t'pe o/ character# +/ 'ou on&' ,ant to match the /irst
&etter o/ a string, then use one O at the end o/ 'our Pattern# +/ 'ou ,ant to search /or 'our
character or string in an' position in the 2tring, use t,o O characters one at the start o/ the
Pattern and one at the end#
K A p&aceho&der to indicate the &ocation in the 2tring, ,here 'our Pattern ,i&& start
tr'ing to match ,ith a character or string #
2/c5 1atch an' character speci/ied bet,een the brac-et s'mbo&s#
2x.y5 1atch an' character that e6ists in the interva& 64'#
92x.y5 1atch an' character that does not e6ist in the interva& 64'#
Additional Considerations: Any Pattern that uses the placeholder (?) does not need the initial *, because you will specify the exact
location(s) in the string for the matching search, when you create the Pattern. The !"# function is not case sensiti$e in most situations. %owe$er, any
Pattern that uses the inter$al syntax (&x'y() is case sensiti$e in relation to its )tring.
=ere is an e6amp&eC
PUBLIC SUB Main()
P'I!# ;'ittin5ho-se; LIQ ;'L;
!D
#'U
>he specia& character G prevents the ne6t character /o&&o,ing it in a string /rom being
interpreted as a generic part o/ the string# >hin- o/ the T character as a contro& code# >r' thisC
PUBLIC SUB Main()
P'I!# ;Samson; LIQ ;SL;
P'I!# ;.ambas; LIQ ;J"$a%L;
P'I!# ;Leonar); LIQ ;."$a%NNL;
P'I!# ;$l*re); LIQ ;."$a%L;
!D
3+
#'U
#'U
1$LS
1$LS
7or a deeper understanding o/ L+EE, tr' the /o&&o,ing variations o/ the L+EE
statement# Bet,een the P@BL+C 2@B 1A+:( and E:. statements, t'pe these PR+:>
statements C
P'I!# ;Simple; LIQ ;siL;
>his returns >R@E# A sing&e 3O3 character at the E:. o/ the search pattern &ets 'ou /ind a
character (or string in the +:+>+AL PO2+>+O: O:LK o/ the string o/ the string being
searched# +t is not case sensitive#
P'I!# ;.ambas; LIQ ;sL;
>his returns 7AL2E# +/ a character in the string is possib&' :O> in the initia& position, 'ou
need to put one 3O3 character at EAC= E:. o/ the search pattern#
P'I!# ;.ambas; LIQ ;LsL;
>his returns >R@E because ,hen 'ou have 3O3 at BO>= ends o/ the search pattern, 'ou can
match the 3s3 in an' position#
P'I!# ;Simple; LIQ ;LimplL;
>his returns >R@E because the pattern to be matched can be a string, as ,e&& as a sing&e
character#

P'I!# ;.ambas; LIQ ;ambas;
>his returns 7AL2E because 3ambas3 is &itera&&' not 3Gambas3# <ithout the 3O3 character, the
search pattern ,i&& on&' match the string i/ it is &itera&&' the same as the search pattern#
P'I!# ;.ambas; LIQ ;5amB$S;
>his returns >R@E since 3Gambas3 is &itera&&' 3gamBA23, so no 3O3 is needed to return a
match# Again, the L+EE /unction is (usua&&'S not case sensitive#

P'I!# ;.ambas; LIQ ;LbbL;
>his returns 7AL2E# >he search pattern 3bb3 is not matched 44 the string on&' contains one
40
3b3#
P'I!# ;.ambas; LIQ ;L"bbcyn%L;
>his returns >R@E# >he Z##[ (brac-et s'mbo&s a&&o, the search pattern to match A:K sing&e
character o/ a string inside the brac-ets to an' o/ the same character in the string#

P'I!# ;.ambas; LIQ ;JJmbL;
>his returns >R@E# >he 3N3 (5uestion mar- is a p&aceho&der# +t a&&o,s 'ou to search /or a
speci/ic character or substring in a speci/ic position (counting /rom the &e/t in the 2tring
being searched#
P'I!# ;.ambas; LIQ ;JaJJJ"psy%L;
>his returns >R@E# >he 3N3 ho&ds the p&ace o/ the "st, Drd, (th and Gth positions o/ the string
being searched# 3a3 is being searched /or in ;nd position, and the Z##[ a&&o,s either ApB or AsB
or A'B to be matched to the Ith position#
P'I!# ;Simple; LIQ ;JJpL;
>his returns 7AL2E# >his search pattern &oo-s /or 3p3 in the Drd position# +n the ,ord
32imp&e3, the actua& &ocation is in the (th position#

P'I!# ;iDealiRe; LIQ ;L"B,D%L;
>his returns >R@E# @ppercase 3.3 &ies in the interva& B4.#
P'I!# ;i)ealiRe; LIQ ;L"b,)%L;
>his returns >R@E# Lo,ercase 3d3 &ies in the interva& b4d#
P'I!# ;iDealiRe; LIQ ;L"b,)%L;
>his returns 7AL2E# @ppercase 3.3 does not &ie in the interva& b4d# Note that only in
inter#al statements $%x&y'( is the )I*! function case sensiti#e+ +n order to match
&etters in mi6ed uppercase and &o,ercase strings, 'ou need to test the string t,ice ,ith L+EE#

P'I!# ;C$'B2!; LIQ ;LP"P,(%LE
>his returns 7AL2E 44 3R3 &ies in the interva& 3P4!3#
P'I!# ;Pl-m; LIQ ;LP"s,A%L;
>his returns 7AL2E 44 3u3 &ies in the interva& 3s4,3
41
P'I!# ;roman; LIQ ;JJ"Pn,r%L;
>his returns >R@E 44 3m3, the &etter in the Drd position o/ the string, does :O> &ie in the
interva& 3n4r3, even though the /irst t,o &etters o/ the string .O &ie in the interva&#

P'I!# ;Leonar)Lo; LIQ ;LNNLL;
>his returns >R@E# >his search pattern &oo-s /or 3O3 in the string# (>hin- o/ 3LeonardOo3 as a
hip4hop name, because other,ise + can't thin- o/ a reason to search /or 3O3#
2ince 3;3 is used in the L+EE /unction s'nta6, ,e need to distinguish our 3;3 /rom the
/unctiona& s'mbo& 3;3# >o indicate the correct 3O3, ,e deactivate it as a /unctiona& s'mbo&, b'
p&acing a contro& code 3T3 in /ront o/ it# But since 3TO3 can a&so be a specia& character or code,
,e use another 3T3 to deactivate that# >he resu&t is a search pattern &i-e thisC 3O##TG;##O3, ,here
the O that sho,n in /old is the character that ,e ,ant to match# )lternatively, and perhaps
preferentially, you can use this notation with e"ual success* PR+:> 3LeonardOo3 L+EE
3OZO[O3
>he NO& operator is used to return a resu&t o/ an e6pression# >he /ormat is as /o&&o,sC
+esult > NO& Expression
<hen Gambas eva&uates this e6pression, it computes the &ogica& :O> o/ the e6pression# +/ the
e6pression is a string or an ob9ect, Gambas returns >R@E i/ the e6pression is :@LL# =ere are
some e6amp&es to tr' on 'our conso&eC
PUBLIC SUB Main()
P'I!# !2# #'U
P'I!# !2# 1$LS
P'I!# !2# ==
P'I!# !2# ;.ambas;
P'I!# !2# ;;
!D
1alse
#r-e
,=B
1alse
#r-e
42
String Operators
+n Gambas, ,hen 'ou ,ant to compare or concatenate strings, 'ou can use the string
operators# >hese operators a&&o, 'ou to concatenate strings and /i&e paths, per/orm L+EE
operations as e6p&ained above, determine i/ strings are e5ua& or not e5ua&, &ess than, greater
than, &ess than or e5ua& to, or greater than or e5ua& to each other# =ere are some things to tr'
using Gambas conso&eC
PUBLIC SUB Main()
DIM a $S Strin5
DIM b $S Strin5
a 6 ;ham;
b 6 ;b-r5er;
P'I!# ;666K ;G $ G B
a 6 ;.ambas;
b 6 =
P'I!# ;666K ;G $ G ; is n-mber ; G B
!D
666K hamb-r5er
666K .ambas is n-mber =
>he /o&&o,ing tab&e o/ string operations is sho,n /or 'our convenience#
Gambas String Operations
$tring Opertion +esult to deter"ine
2tring P 2tring Concatenate t,o strings#
2tring PM 2tring Concatenate t,o strings that contain /i&e names# Add a path
separator bet,een the t,o strings i/ necessar'#
2tring )*KE Pattern Per/orm pattern matching using the )*KE operator#
2tring W 2tring .etermine i/ the t,o strings are e5ua&#
2tring XY 2tring .etermine i/ the t,o strings di//erent#
2tring X 2tring .etermine i/ the /irst string is &o,er than the second string
2tring Y 2tring .etermine i/ the /irst string is greater than the second string
2tring XW 2tring .etermine i/ /irst string is &o,er or e5ua& to second string
2tring YW 2tring .etermine i/ /irst string is greater or e5ua& to second string
(ote* all string operator comparisons are case sensitive.
43
7ote that Gambas is not case-sensiti"e in the use o> *our "ariable names) allowing the "ariables
OaP and ObP to be used as OAP and O:P. To make it eas* on *oursel>) it is better to keep *our code as
consistent as possible. .owe"er *ou dimension *our "ariables) keep consistent spellings as *ou write
*our programs.
44
Chapter 3 - Keywords and Program Fow
Contro
+n Gambas, the programmer contro&s the program b' using -e',ords and conditiona&
e6pressions# Gambas is an event driven &anguage# >he programmer has the abi&it' to direct
,hat happens ,henever an' event occurs# >he programmer uses Gambas -e',ords (,hich
are reserved ,ords ,ith ver' speci/ic s'nta6 to create instructions that guide ,hat the
program ,i&& do in a given circumstance# Conditiona&s are tests o/ an e6pression or a variab&e#
>he test cou&d be an eva&uation o/ the resu&t o/ an operation or comparison o/ e5ua&it', /or
e6amp&e# Gambas uses about ;G$ -e',ords and native /unctions# >he /o&&o,ing tab&e sho,s a
sma&& subset o/ the Gambas -e',ords current&' supportedC
BREAK CASE CONTINUE DEC DEFAULT DO
ELSE END ENDIF FOR FOR EACH GOTO
IF INC LOOP NEXT PRINT QUIT
REPEAT RETURN SELECT STEP TRUE THEN
TO UNTIL WAIT WEND WHILE WITH
>he best ,a' to understand ,hat these -e',ords and conditiona&s mean is to gradua&&'
introduce them ,ith e6amp&es# Rather than go through the &ist o/ -e',ords in a&phabetica&
order, &et's ta-e the approach o/ introducing them based on the t'pe o/ /unctiona&it' the'
support# <e ,i&& start ,ith the most basic statements and commands and progress through
the more comp&e6 ones as ,e continue# Let's start ,ith the Gambas PR+:> statement#
The %#I!T Statement
>he PR+:> statement prints e6pressions to the standard output# >he e6pressions are
converted to strings b' the 2tr( /unction# PR+:> ta-es the /ormat o/C
P'I!# xpression "(G&0) xpression ...% "(G&0)%
Brac-ets used in the s'nta6 de/inition above indicate optiona& parameters# +/ there is
no semi4co&on or comma after the last epression, a ne,&ine character is automatica&&'
printed a/ter the &ast e6pression# +/ a comma is used instead o/ a semi4co&on to separate
e6pressions, then a tab character (A2C++ code ) is printed bet,een output va&ues to separate
the e6pressions# PR+:> can a&so used to direct output to a /i&e# <e ,i&& discuss printing to
/i&es ,hen ,e get to the section on +nput and Output# <hen using PR+:> to ,rite output to a
/i&e, e6pressions are sent to the stream +ile and this /ormat is usedC
P'I!# < 1ile0 xpression"(G&0) xpression ...% "(G&0)%
4#
=ere is something to tr' using PR+:>C
PUBLIC SUB Main()
DIM b $S Inte5er
b 6 =
P'I!# ;666K ; S ;b isO ; S B
P'I!# ;666K ;0 ; b isO;0 B Tinserts a tab
P'I!# ;666K ;G ;b isO ; S B Tcatenates Aitho-t Ahitespace
!D
>he conso&e disp&a's the /o&&o,ing outputC
666K b isO =
666K b isO =
666K b isO =
:ote above that the variab&e AbB is a&so ,ritten as ABB# 7or variab&e names, the case is not
important, but it ma' be con/using to s,itch bet,een cases#
The I& Statement
>he +7 statement is used to ma-e a decision# +7 is one o/ the most common structures
used b' programmers to ma-e comparisons and decisions based on the resu&t o/ that
comparison# @sing +7 &ogic, 'our program can per/orm comparisons using operators 'ou have
&earned about and subse5uent&' ma-e decisions based on the resu&t o/ such comparisons# +7
ta-es the genera& /orm o/C
I1 xpression #:!
)o somethin5...
" LS I1 xpression #:!
)o somethin5 else... %
" LS
)o somethin5 completely )i**erent... %
!DI1
=ere is an e6amp&e using +7 that 'ou can tr' on the conso&eC
PUBLIC SUB Main()
DIM b $S Inte5er
b 6 =
I1 b 6 = #:!
P'I!# ;666K ; S ;.ambas is n-mber ; S BG
LS I1 b UK = #:!
P'I!# ;Sho-l) not print meV;G
48
LS
P'I!# ;Somethin5 ba) is happenin5;
!DI1
!D
666K .ambas is n-mber =
Kou can ,rite a comp&ete *! 111 &6EN statement on one &ine, provided that there is on&' one
resu&t, and it is ,ritten 9ust a/ter the &6EN -e',ord# 7or e6amp&eC
PUBLIC SUB Main()
DIM a $S Inte5er
DIM b $S Inte5er
a 6 =9
b 6 =
I1 b U a #:! P'I!# DWes0 = is still less than =9.E
!D
Wes0 = is still less than =9.
7urthermore, 'ou can ta-e a shortcut b' putting severa& test e6pressions on the same &ineC
PUBLIC SUB Main()
DIM a $S Inte5er
DIM b $S Inte5er
DIM C $S Strin5
DIM D $S Strin5
a 6 =9
b 6 =
C 6 ;re);
D 6 ;yelloA;
I1 b U a $!D I1 C 6 ;re); $!D I1 D 6 ;yelloA; #:! P'I!# ;very con)ition on this line is #'U0 so the I1..#:! statement
ret-rne) #'U.; To* co-rse0 -sin5 this metho)0 $LL o* this text m-st be on one line in the ID
I1 b K a 2' I1 C 6 ;5reen; 2' I1 D 6 ;yelloA; #:! P'I!# ;#he I1..#:! statement ret-rne) #'U Ahen it reache) the *irst
case o* a #'U con)ition.;
!D
4?
very con)ition on this line is #'U0 so the I1..#:! statement ret-rne) #'U.
#he I1..#:! statement ret-rne) #'U Ahen it reache) the *irst case o* a #'U con)ition.
(ote* ,ou are not allowed to mi )(- .+ and /0 .+ epressions on the same line.
The SELECT ' CASE Statement
>he 2ELEC> statement eva&uates an e6pression, comparing it to each CA2E speci/ied,
and ,i&& e6ecute the code enc&osed in the matching CA2E statement i/ the e6pression
eva&uated is >R@E# +/ no CA2E statement matches the e6pression under eva&uation, the
.E7A@L> or CA2E EL2E statement is e6ecuted# >he 2ELEC>MCA2E statement a&&o,s a
programmer to bui&d a code b&oc- capab&e o/ eva&uating man' e6pression resu&ts ,ithout
having to code an e6cessive amount o/ +7MEL2E+7MEL2E statements# >he /ormat o/ the
2ELEC> statement isC
SLC# xpression
"C$S xpression "0 xpression ...%
"C$S xpression "0 xpression ...%
"C$S LS & D1$UL# ...%
!D SLC#
=ere is some code to sho, 'ou ho, to use the 2ELEC> statementC
PUBLIC SUB Main()

DIM A $S Inte5er
A 6 =
T S#$'#O is a L$BL0 -se) Aith .2#2 explaine) beloA.
S#$'#O
P'I!# ;#he val-e o* A isO ; S A
SLC# C$S A
C$S =
I!C A
.2#2 S#$'#
C$S B
I!C A
.2#2 S#$'#
C$S /
I!C A
.2#2 S#$'#
C$S LS
P'I!# ;#he variable A has no han)ler *orO ; S A
4%
!D SLC#
P'I!# ;1inal val-e o* A ISO ; S A
!D
>he conso&e shou&d respond ,ith the /o&&o,ing outputC
#he val-e o* A isO =
#he val-e o* A isO B
#he val-e o* A isO /
#he val-e o* A isO @
#he variable A has no han)ler *orO @
1inal val-e o* A ISO @
Because the variab&e , ,as incremented to the va&ue o/ ( and there ,as to C,$E to
hand&e that va&ue, the C,$E E)$E b&oc- is e6ecuted# CA2E EL2E can a&so be ,ritten as
C,$E #E!,()&# Either ,a', it is ,here code de/au&ts to ,hen no case satis/ies the va&ue o/
the variab&e being chec-ed#
GOTO an LA(ELS
:ote the use o/ the LABEL named $&,+&L in the previous code e6amp&e# >he co&on
must be used ,ith the &abe& name and it must /o&&o, it ,ithout an' spaces bet,een the &abe&
and the co&on# Labe&s are the targets ,here a FO&O instruction ,i&& direct program /&o,#
<hi&e the use o/ FO&O shou&d be 9udicious it is sometimes necessar'# +t is used in the above
e6amp&e to demonstrate ho, to use FO&O and LABEL2# Later, ,hen ,e stud' &ooping
structures, ,e ,i&& re,rite this code to use a Gambas &ooping mechanism#
The &O# ' !E)T Statement
1an' times ,hen ,riting code, programmers /ind the need to iterate through a set o/
va&ues (ca&&ed &ooping to process data# >he !O+ statement is a &ooping statement common&'
used in programs# +t ta-es the genera& /orm o/C
12' (ariable 6 xpression #2 xpression " S#P xpression % ... !7#
>he !O+ statement repeats a &oop ,hi&e at each iteration o/ the &oop incrementing a
variab&e# :ote that the variab&e must be a numeric data4t'pe (i#e#, a b'te, a short, an integer or
a /&oating point number and it must be dec&ared as a &oca& variab&e# +/ the initia& e6pression
the !O+ statement eva&uates is higher than the &O e6pression (/or positive $&EP va&ues or
i/ the initia& e6pression is &ess than the &O E6pression (/or negative $&EP va&ues the &oop
,i&& not be e6ecuted at a&&# >he $&EP -e',ord a&&o,s the programmer to de/ine the si0e o/ the
interva& incremented bet,een &oop iterations# =ere is an e6amp&eC
4+
PUBLIC SUB Main()
DIM I $S Inte5er
DIM 4 $S Inte5er
4 6 =
12' I 6 = #2 B= S#P /
P'I!# ;L22P iterationO ; S 4 S ;0 I is eI-al toO ; S I
I!C 4
!7#
P'I!# ;4 ISO ; S 4 S ; an) I isO ; S I
!D
>his code resu&ts in the /o&&o,ing outputC
L22P iterationO =0 I is eI-al toO =
L22P iterationO B0 I is eI-al toO @
L22P iterationO /0 I is eI-al toO X
L22P iterationO @0 I is eI-al toO =9
L22P iterationO C0 I is eI-al toO =/
L22P iterationO F0 I is eI-al toO =F
L22P iterationO X0 I is eI-al toO =>
4 ISO ? an) I isO BB
:ote that once the va&ue o/ % e6ceeds the test o/ ;" in the &oop, the &oop stops and code
/&o, moves past the NEH& statement# >he va&ue o/ % remains unchanged ,hen e6iting the
&oop# E6periment ,ith the code above, changing the 2>EP va&ue /rom D to ", /or e6amp&e# >r'
to modi/' the !O+ statement &i-e thisC
12' I 6 B= to = S#P ,=
Gambas a&so provides a !O+ E,C6 &ooping structure that a&&o,s 'ou to iterate
through the va&ues o/ a co&&ection, arra', enumerab&e c&asses, etc#, ,ithout the need to
maintain an integer counter# <e ,i&& /u&&' cover the detai&s o/ !O+ E,C6 ,hen ,e discuss
co&&ections &ater in this boo-# At this point in 'our introduction to Gambas, 'ou are
encouraged to p&a' around ,ith the code in the e6amp&es and change variab&e va&ues, practice
using the P+*N& statement, etc# Get to -no, the conso&e and 'ou ,i&& 5uic-&' &earn it is a
great too& to test e6pressions, code segments, etc# .o not be a/raid to e6periment ,ith
GambasS >he ver' ,orst thing that can happen is 'our program b&o,s up and 'ou have to
restart 'our computer un&i-e&', but indeed possib&e# P&a' around and get com/ortab&e ,ith
Gambas# +t is the best ,a' to &earn#
!O "#$%&E' &OOP
>he #O 2-6*)E5 )OOP structure begins e6ecution o/ a &oop that ,i&& not end unti& a
condition is met or code ,ithin the &oop structure /orces an e6it# >he code e6ecuted in the
#0
&oop is de&imited b' the -e',ords #O and )OOP# +/ the optiona& -e',ord -6*)E is not
speci/ied, the &oop ,ou&d e6ecute /orever (an infinite loop) or unti& some condition ,ithin the
&oop structure /orced an e6it# +/ the optiona& -e',ord -6*)E is speci/ied, the &oop is stopped
once the eva&uated resu&t o/ the e6pression becomes !,)$E# +n other ,ords, while the
resu&ts o/ this e6pression are >R@E, continue to iterate (do the &oop# +/ the e6pression is
7AL2E ,hen the &oop is started, the &oop ,i&& not be e6ecuted at a&&# =ere is the /ormat o/ the
.O LOOPC
D2 " +:IL xpression %
...
L22P
>he /o&&o,ing code e6amp&e shou&d he&p 'ou better understand ho, to use the #O 111
-6*)E )OOPC
PUBLIC SUB Main()
DIM a $S Inte5er
a 6 =
D2 +:IL a U6 C
I1 a 6 = #:!
P'I!# ;:ello +orl)0 loopin5 ; S a S ; time.;
LS
P'I!# ;:ello +orl)0 loopin5 ; S a S ; times.;
!DI1
I!C a
L22P
DC a
P'I!#
P'I!# ;.oo)bye +orl)0 I loope) a total o*O; S a S ; times.;
!D
>he conso&e prints the /o&&o,ingC
:ello +orl)0 loopin5 = time.
:ello +orl)0 loopin5 B times.
:ello +orl)0 loopin5 / times.
:ello +orl)0 loopin5 @ times.
:ello +orl)0 loopin5 C times.
.oo)bye +orl)0 I loope) a total o*O C times.
#1
#$%&E *E+pression, #EN! Loops
>his &oop structure begins a &oop de&imited b' the -6*)E ### -EN# instructions# >he
&oop is repeated ,hi&e Epression is >R@E# +/, on initia& entr', the e6pression is 7AL2E, the
&oop is never e6ecuted# >he #O -6*)E )OOP and -6*)E ### -EN# structures are
e5uiva&ent# >r' this codeC
PUBLIC SUB Main()
DIM a $S Inte5er
a 6 =
+:IL a U6 C
I1 a 6 = #:!
P'I!# ;:ello +orl)0 +:IL...+!D loopin5 ; S a S ; time.;
LS
P'I!# ;:ello +orl)0 +:IL...+!D loopin5 ; S a S ; times.;
!DI1
I!C a
+!D
DC a
P'I!# ;.oo)bye0 +:IL...+!D loope) a total o*O ; S a S ; times.;
!D
>he conso&e shou&d print the /o&&o,ingC
:ello +orl)0 +:IL...+!D loopin5 = time.
:ello +orl)0 +:IL...+!D loopin5 B times.
:ello +orl)0 +:IL...+!D loopin5 / times.
:ello +orl)0 +:IL...+!D loopin5 @ times.
:ello +orl)0 +:IL...+!D loopin5 C times.
.oo)bye0 +:IL...+!D loope) a total o*O C times.
The (EPEAT )NT%& loop
>his &oop structure begins to e6ecute code that is de&imited b' the -e',ords +EPE,&
and (N&*)# A repeat &oop ,i&& a&,a's e6ecute at &east once, even i/ the (N&*) va&ue is
initia&&' 7AL2E# =ere is a samp&e to tr' on the conso&eC
PUBLIC SUB Main()
DIM a $S Inte5er
a 6 =
'P$#
I1 a 6 = #:!
P'I!# ;:ello +orl)0 'P$# U!#IL loopin5 ; S a S ; time.;
#2
LS
P'I!# ;:ello +orl)0 'P$# U!#IL loopin5 ; S a S ; times.;
!DI1
I!C a
U!#IL a K C
DC a
P'I!#
P'I!# ;.oo)bye0 'P$# U!#IL loope) a total o*O ; S a S ; times.;
!D
>he conso&e shou&d print the /o&&o,ingC
:ello +orl)0 'P$# U!#IL loopin5 = time.
:ello +orl)0 'P$# U!#IL loopin5 B times.
:ello +orl)0 'P$# U!#IL loopin5 / times.
:ello +orl)0 'P$# U!#IL loopin5 @ times.
:ello +orl)0 'P$# U!#IL loopin5 C times.
.oo)bye0 'P$# U!#IL loope) a total o*O C times.
!efining and )sing Arrays in Gambas
>here are t,o -inds o/ arra's that can be used in Gambas# >he /irst t'pe o/ Gambas
arra' ,or-s &i-e arra's used in the %ava programming &anguage# >he other t'pe o/ arra' that
is used in Gambas is -no,n as a :ative arra'# <hen using 1ava2li&e arra's, 'ou must
remember that the arra's are ob9ects o/ the /o&&o,ing c&assesC +ntegerZ[, 2tringZ[, Ob9ectZ[,
.ateZ[, and !ariantZ[# A&& o/ these t'pes o/ 1ava2li&e arra's can have on&' one dimension#
Kou dec&are them &i-e thisC
DIM My$rray $S !+ Inte5er"%
Arra's are a&,a's initia&i0ed as void at startup# >he' are d'namic, and have a &ot o/
use/u& methods app&'ing to them# <hen using sing&e4dimension arra's, these are the right
choice# (ative arrays on the other hand can support mu&tidimensiona& imp&ementations or
arra's ,ith arra's ob9ects o/ the /o&&o,ing c&assesC +nteger, 2tring, Ob9ect, .ate, and !ariant#
>he' are dec&ared &i-e thisC
DIM My$rray"Dim=0 DimB0 ... % $S Inte5er
DIM My$rray"Dim=0 DimB0 ... % $S Strin5
DIM My$rray"Dim=0 DimB0 ... % $S (ariant
Each native datat'pe has an associated arra' data4t'pe ,hose name is the name o/ that
native datat'pe /o&&o,ed b' s5uare brac-etsC %oolen254 %yte254 $hort254 *nteger254
#3
$ingle254 !lot254 $tring254 #te254 'rint254 Pointer254 and O/ject251 :ative arra's
can have up to eight dimensions# >he' are :O> ob9ects# >he' are a&&ocated on the stac- i/ 'ou
dec&are them &oca& to a /unction# >he' are a&&ocated inside the ob9ect data i/ 'ou dec&are them
as g&oba& in scope# :ative arra's are not d'namic # >he' can't gro, or shrin- once the' are
dec&ared# Kou can on&' on&' set or get data /rom an e&ement in these t'pes o/ arra's# =ere is
an e6amp&e o/ using a three4dimensiona& native arra' in Gambas# +n this e6amp&e, the arra' is
/i&&ed ,ith integer va&ues ranging /rom $ to ;I# Enter this code in 'our conso&e code ,indo,C
PUBLIC SUB Main()
DIM i $S Inte5er
DIM ii $S Inte5er
DIM iii $S Inte5er
DIM narMatrix"/0 /0 /% $S Inte5er
12' i 6 9 #2 B
12' ii 6 9 #2 B
12' iii 6 9 #2 B
P'I!# i0 ii 0 iii S ; 66K ;G Tnote that DGE prevents a neAline.
narMatrix"i0 ii0 iii% 6 iL> H iiL/ H iii
P'I!# narMatrix"i0 ii0 iii%
!7#
!7#
!7#
!D
<hen 'ou e6ecute this code, 'our output in the conso&e ,indo, shou&d be simi&ar to ,hat is
sho,n hereC
9 9 9 66K 9
9 9 = 66K =
...
B B = 66K BC
B B B 66K BF
>o ma-e the !O+11NEH& &ogic ver' c&ear, here is that code b&oc- ,ith vertica& &ines
connecting the paired -e',ords o/ each separate &oopC
#4
7rom &oop iteration $ to ;, there are three e6ecution steps# Each o/ the three
!O+##NEH& &oop iterations e6ecutes three c'c&es, /or each o/ the three times that contro&
passes to it# >here/ore, D6D6D c'c&es e5ua&s ;J c'c&es# 2tarting the &oop counter ,ith i W $ and
iterating /rom $ to ;I iterations ma-es a tota& o/ ;J c'c&es#
Co**ections
Co&&ections are groups o/ ob9ects imp&emented ,ith a hash tab&e# Co&&ection ob9ects use
-e's that are imp&emented as string data4t'pes# >he data va&ues corresponding to an'
co&&ection -e' is a !ariant data4t'pe# Ob9ects in a co&&ection are enumerab&e# N()) is used
,hen nothing is associated ,ith a given -e'# Conse5uent&', associating N()) ,ith a -e' has
the same e//ect as removing it /rom the co&&ection# >he si0e o/ the interna& hash tab&e gro,s
d'namica&&' as data is inserted# >his c&ass is created using this genera& /ormatC
DIM hCollection $S Collection
hCollection 6 !+ Collection ( "Mo)e $S Inte5er% )
:ote the ,ord E,C6 a/ter the !O+ statement# >he !O+ E,C6 construct is
discussed ne6t# A&so, ,e ,i&& go into much greater detai& about co&&ections &ater in this boo-
,hen ,e ta&- about ob9ect4oriented programming# <e ,i&& deve&op an app&ication that ma-es
e6tensive use o/ co&&ections# 7or no,, 9ust note that co&&ection e&ements are enumerated in the
order in ,hich the' ,ere inserted into the co&&ection# =o,ever, i/ 'ou rep&ace the va&ue o/ an
a&read' inserted -e', the origina& insertion order is -ept#
The &O# EACH Statement
>he !O+ E,C6 statement e6ecutes a &oop ,hi&e simu&taneous&' enumerating an
ob9ect# >he Epression must be a re/erence to an enumerab&e ob9ect such as a co&&ection or an
arra'# >he order o/ enumeration in not necessari&' predictab&e# >he genera& /ormat o/ the
statement isC
12' $C: xpression ... !7#
12' $C: (ariable I! xpression ... !7#
##
Figure 1/: lari($ing the For 7e8t loop structure.
>his s'nta6 must be used ,hen Epression is an enumerab&e ob9ect that is not a
container# 7or e6amp&e, an ob9ect returned as the resu&t o/ a database 5uer'# 7urthermore,
,hen ,e sa' that the ob9ect is Aenumerab&eB, ,e mean that it has a bui&t4in &ist structure, even
i/ the numerica& order o/ the &ist items is on&' created ,hen the 7OR EAC= &oop e6ecutes# +n
the co&&ection be&o,, ,e can use integers as -e's, but the' are automatica&&' converted to the
string data4t'pe ,hen ,e assign them as -e's# >he statements above create a ne, co&&ection
ob9ect# Enter the /o&&o,ing code into 'our conso&e code ,indo, and run it#
PUBLIC SUB Main()
DIM MyDict $S !+ Collection
DIM strlement $S Strin5
MyDict";absol-te;% 6 /
MyDict";basic;% 6 =
MyDict";carpet;% 6 DBE
MyDict"Drain)ropE% 6 DcatE
12' $C: strlement I! MyDict
P'I!# strlement S ; ; G
!7#
!D
Kour conso&e shou&d disp&a' this outputC
/ = B cat
At this point, 'ou shou&d be getting a prett' good /ee& /or the s'nta6 and structure o/
Gambas# <e are going to move a,a' /rom conso&e4based (termina& app&ications and return
to our /irst pro9ect to begin e6p&oring the Gambas >oo&Bo6 and &earn ho, to deve&op a G@+4
based program# +t is time to ta-e a brea- and ,hen 'ou come bac- to the ne6t chapter, 'ou
,i&& be re/reshed and read' to code# Ah, hec-S +/ 'ou 9ust can't ,ait to 9ump in, go ahead and
turn the pageS
#8
Chapter ! "he Gambas "oo#o$
>he Gambas >oo&Bo6 consists o/ man' contro&s# As o/ this ,riting using re&ease (;#;;,
the /o&&o,ing contro&s are current&' supportedC
2e&ect RadioButton >e6tArea >ab&e!ie, =Pane& E6pander
Labe& >ogg&eButton List!ie, !a&ueBo6 !Pane& ListContainer
>e6tLabe& >oo&button >ree!ie, Co&orChooser =2p&it 2idePane&
2eparator 2&ider +con!ie, .ateChooser !2p&it >oo&Pane&
PictureBo6 2cro&&Bar Co&umn!ie, .irChooser Pane& <i0ard
1ovieBo6 ListBo6 Grid!ie, 7i&eChooser 7rame Embedder
ProgressBar ComboBo6 Co&orButton 7ontChooser >ab2trip >ra'+con
Button >e6tBo6 .ir!ie, =Bo6 2cro&&!ie, >imer
Chec-Bo6 2pinBo6 7i&e!ie, !Bo6 .ra,ingArea
As 'ou can see, there is a ,ide se&ection o/ too&s /or 'ou to p&a' ,ith in Gambas# Our
introduction to the too&s (which are also called controls ,i&& teach 'ou about ,hat each
contro& does, ,hat properties, methods, and events 'ou can use to direct the behavior o/ the
inter/ace 'ou are bui&ding, and ho, to code the contro& to ma-e it ,or- e6act&' as 'ou desire#
A&ong the ,a', ,e ,i&& be bui&ding severa& simp&e pro9ects to get 'ou more e6perienced
in using the Gambas +.E# A&& o/ the contro&s in the >oo&Bo6 are bui&t4in using the g/1=t
co"ponent1 >his component imp&ements the Graphica& @ser +nter/ace c&asses# +t is based
on the Ht &ibrar'# =ere is a &ist o/ some o/ the various /unctiona&it' the g/1=t co"ponent
providesC
C&ipboard +con!ie,
Containers Ee'board and 1ouse
.rag and .rop 1enus
.ra,ing List!ie,, >ree!ie, and Co&umn!ie,
7onts Printing
<e ,i&& cover other components &ater in this boo-# +n 7igure *, 'ou see an e6amp&e o/ a
7orm# >his is the de/au&t too&-it /or the gb#5t component# >he too&-it /or G>EF is some,hat
di//erent# <hen 'ou start a Gambas pro9ect and se&ect a AGraphica& app&icationB, Gambas ,i&&
&oad a de/au&t too&-it based on 'our des-top s'stemC Ht /or the E.E des-top, G>EF /or
Gnome# >here/ore, i/ 'ou pre/er a speci/ic too&-it other than the de/au&t /or 'our s'stem, 'ou
must choose it at pro9ect creation#
NO&EL For se'eral reasons9 :t is the more reliable an" complete tool3it (or Gambas at the time o(
this .riting. For no.9 let;s ta3e a <uic3 loo3 at the :t Tool=o8 again an" re'ie. the icons therein.
#?
7rom the top &e/t o/ 7igure ", the contro&s in the >oo&Bo6 (Ro, " areC
2e&ect
Labe&
>e6tLabe&
2eparator
PictureBo6
1ovieBo6
ProgressBar
Button
Chec-Bo6
RadioButton
>ogg&eButton
>oo&Button
2&ider
2cro&&Bar
On the second ro, 'ou ,i&& /indC
ListBo6
ComboBo6
>e6tBo6
2pinBo6
>e6tArea
List!ie,
>ree!ie,
+con!ie,
Co&umn!ie,
Grid!ie,
Co&orButton
.ir!ie,
7i&e!ie,
>ab&e!ie,
#%
Figure 10: The Gambas Toolbo8.
On the third ro, ,e haveC
!a&ueBo6
LC.:umber
.ia&
Editor
>e6tEdit
>he genera& approach to programming Gambas is to design the &a'out o/ 'our /orms,
p&ace the contro&s that ma-e up 'our inter/ace to the user on the /orm, determine and hand&e
the various events that can occur ,ith each contro& using a combination o/ bui&t4in Gambas
methods and 'our o,n code, and direct the operations o/ the program using inputMoutput
data# +/ it sounds simp&e, it is because once 'ou understand the mechanics o/ it a&&, it is
simp&e# Once 'ou get used to programming event4driven app&ications in Gambas, it ,i&&
become second nature to 'ou#
>he /irst group o/ contro&s ,e are going to &earn about are te6t4oriented in nature and
serve to either disp&a' or gather te6t data or to generate an event that 'ou can ,rite code /or,
such as pushing a button# >hese contro&s areC
Button
Labe&
>e6tLabe&
>e6tBo6
+nputBo6
>e6tArea
The +utton Contro*
>his c&ass ob9ect inherits its attributes /rom the Control c&ass, as do a&& the contro&s in
the Gambas >oo&Bo6# @sing this contro& imp&ements a push button on a /orm# A push button
can disp&a' te6t, a picture, or both# Kou have the abi&it' to set one button inside a ,indo, to
be the #efult /utton# >hen, ,hen the user presses the +E&(+N -e', it ,i&& activate that
button automatica&&'# A&so, 'ou can set one button inside a ,indo, to be the Cncel /utton#
Pressing the E2C -e' ,i&& activate the Cance& button automatica&&'# >his c&ass is creatab&e,
meaning that 'ou can ,rite code to d'namica&&' generate a button on a /orm at run4time# >o
dec&are a button ob9ect, the /ormat be&o, is usedC
DIM hB-tton $S B-tton
hB-tton 6 !+ B-tton ( Parent $S Container )
>he Container, in most cases, ,i&& be the /orm ,here 'ou p&ace the button# +t cou&d be
an' container ob9ect, ho,ever# >his code ,i&& create a ne, push button contro&# :ote the
variab&e name is preceded b' the &o,ercase &etter h. >his is a standard convention
#+
programmers use to re/er to the hand&e (handles are really references to something o/ an
ob9ect# 2ince Gambas supports ob9ect4oriented programming, ,e ,i&& gradua&&' introduce OO
(/bject2/riented concepts to 'ou as ,e encounter them# >he term Bo/jectB in Gambas is a
short ,a' o/ re/erring to a data structure that provides properties, variab&es, methods and
events# One -ind o/ ob9ect is a A/ormB, ,hich is an ob9ect o/ the bui&t4in Gambas c&ass named
A7ormB# A /orm might contain other ob9ects &i-e buttons or chec-bo6es# Ob9ects aren't
necessari&' graphica& in nature 44 another -ind o/ ob9ect might be an arra' o/ integers or
strings#
A AclssB in Gambas is the description o/ a&& o/ the pub&ic properties, methods, and
events be&onging to ob9ects# O/ course, there can be man' ob9ects co&&ected in a c&ass,
inc&uding /orms# A c&ass can contain a /orm's description, inc&uding the buttons, bo6es, etc#
that the user interacts ,ith, and a&& o/ the events that are connected ,ith those ob9ects#
Gambas' bui&t4in c&asses are not direct&' visib&e, but the c&asses that a programmer
creates in the +.E are contained in c&ass /i&es# >hese /i&es are in p&ain te6t /ormat, visib&e to
the programmer either in the +.E or separate&' ,ith a te6t editor# +n addition, /orms and
modu&es are c&asses created b' the programmer thus, /orm /i&es and modu&e /i&es are a&so
stored in p&ain te6t, and are a&so direct&' readab&e ,ith a te6t editor# >hese /i&es are a&& &ocated
in the /o&ders /or each Gambas programming pro9ect# >here/ore, ,hen ,e re/er to the
programmer ,riting code /or a c&ass, ,e are re/erring both to the programming concept o/ a
Ac&assB as ,e&& as an actua& human4readab&e c&ass /i&e# OO ,i&& be covered in much greater
detai& in Chapter "" o/ this boo-#
Genera&&', ob9ects are created /rom a c&ass b' assigning a cop' o/ the ob9ect to a
variab&e, in this case h%utton# >his process, -no,n as instantiating an ob9ect occurs ,hen
hButton is assigned a va&ue using the :E< -e',ord# <hat the &ine be&o, means is hButton
,i&& be instantiated as a :E< Button ob9ect and Prent is the propert' (read only that ,i&&
read a method (thin- o/ methods as /unctions that set or get a va&ue that is imp&emented
inside the Container c&ass# >he Container c&ass is used because it is the parent c&ass o/ ever'
contro& that can contain other contro&s# :o,, this &ine o/ code shou&d ma-e per/ect sense to
'ouC
hB-tton 6 !+ B-tton ( Parent $S Container )
Common Control %roperties
Button properties are attributes that 'ou can set or read using the propert' ,indo, or
b' using code in 'our program# 7or e6amp&e, the &ine o/ code be&o, ,i&& set the >e6t propert'
o/ a buttonC
hB-tton.#ext 6 D2QE
:ote the /ormat o/ the statement above# Control1Property > !xpression is the standard
convention used /or setting or getting attribute in/ormation /rom a contro&# +n the term
80
Control1Property 'ou see an e6amp&e o/ Adot notationB# >his is used in Ob9ect4Oriented
Programming, ,here the connection bet,een the ob9ect and its properties or methods is
indicated b' a AdotB# 1an' o/ the properties /or contro&s are common among a&& contro&s, so
,e ,i&& ta-e the time no, to e6p&ain a&& o/ the button properties here# Later in the boo-, ,e
,i&& on&' e6p&ain the properties that are uni5ue to a given contro& ,hen ,e encounter them#
Background is de/ined as P+OPE+&3 %ckground ,$ *nteger
>his integer va&ue represents the co&or used /or the contro& bac-ground# +t is
s'non'mous ,ith the Bac-ground propert'#, ,hich ,i&& be e&iminated in GambasD# :ote that
P+OPE+&3 is a prede/ined data4t'pe used interna&&' in Gambas# Kou can use the Gambas
prede/ined constants /or co&or to set common co&or va&uesC
Black Bl-e Cyan DarkBl-e DarkCyan Dark.ray
Dark.reen DarkMa5enta Dark'e) DarkWelloA De*a-lt .ray
.reen Li5ht.ray Ma5enta 2ran5e Pink 'e)
#ransparent (iolet +hite WelloA
>o set the Bac-ground propert' /or hButton to red, 'ou ,ou&d use this codeC
hB-tton.Back5ro-n) 6 Color.'e)
A&ternative&', i/ 'ou -no, the RGB (red, green, b&ue or =2! (hue, saturation, va&ue
va&ues /or a speci/ic co&or, Gambas provides a means to convert those va&ues to an integer
va&ue that can be passed on to the Bac-ground (or other color2related propert'# >he c&ass
Co&or provides t,o methods, RGB and =2! that 'ou can use# =ere is ho, those /unctions are
de/inedC
S#$#IC 1U!C#I2! '.B (' $S Inte5er0 . $S Inte5er0 B $S Inte5er "0 $lpha $S Inte5er % ) $S Inte5er
>he +F% /unction returns a co&or va&ue /rom its red, green and b&ue components# 7or the
=2! /unction, use thisC
S#$#IC 1U!C#I2! :S( (:-e $S Inte5er0 Sat $S Inte5er0 (al $S Inte5er) $S Inte5er
6$' returns a co&or va&ue /rom its hue, saturation and va&ue components# >o use one o/
these /unctions to set the button's bac-ground co&or, here is ,hat 'ou cou&d codeC
hB-tton.Back5ro-n) 6 Color.'.B(BCC0BCC0BCC)
>his ,ou&d set the button's bac-ground co&or to ,hite# >his is most use/u& ,hen 'ou are
tr'ing to set co&ors ,hose va&ues /a&& outside the de/au&t co&or constant va&ues provided ,ith
Gambas#
81
Border 4 >his propert' is another common attribute /ound on man' contro&s# >his
c&ass is static# >he constants used b' the Border propert' inc&ude the /o&&o,ingC Etched,
(one, 3lain, 0aised, and Sun&en# >o set the border propert' /or our button, ,e cou&d use this
codeC
hB-tton.Bor)er 6 Bor)er.Plain
,ancel is de/ined as P+OPE+&3 Cncel ,$ %oolen and it is used to stipu&ate
,hether or not the button is activated ,hen the E2C -e' is pressed# >he /o&&o,ing code ,ou&d
trigger this button i/ the user pressed the E2C -e' on their -e'board#
hB-tton.Cancel 6 #'U
+/ the Cance& propert' is used in 'our program, it ,ou&d a&&o, 'ou to hand&e the event and
grace/u&&' e6it the /orm 9ust as i/ the user had c&ic-ed a Huit, E6it or Cance& button#
,aption is de/ined as P+OPE+&3 Cption ,$ $tring and the Caption propert' is
s'non'mous ,ith the >e6t propert'# >he /o&&o,ing code
hB-tton.Caption 6 D2QE
is the same as
hB-tton.#ext 6 D2QE
and can be used interchangeab&'# Let's tr' some code no, b' stating Gambas# :e6t, open up
the pro9ect ,e created named 7irstPro9ect# 7rom the >ree!ie,, doub&e4c&ic- 'our mouse
cursor on the 71ain /orm and the b&an- /orm ,i&& open up# .oub&e4c&ic- an',here on the
b&an- /orm and 'ou ,i&& see the code ,indo,# +t shou&d &oo- &i-e thisC
T .ambas class *ile
PUBLIC SUB 1orm82pen()
!D
:o,, enter this code bet,een the P(%)*C $(% !or"MOpen() and EN# statements so it
&oo-s &i-e thisC
DIM hB-tton $S B-tton
hB-tton 6 !+ B-tton (M) $S ;hB-tton;
hB-tton.7 6 B=C
hB-tton.W 6 F9
hB-tton.+i)th 6 B99
82
hB-tton.:ei5ht 6 @9
hB-tton.nable) 6 #'U
hB-tton.#ext 6 ;Click or press SC to Y-it;
hB-tton.Bor)er 6 #'U
hB-tton.De*a-lt 6 #'U
hB-tton.Cancel 6 #'U
hB-tton.ShoA
!D
A/ter the P@BL+C 2@B 7ormLOpen('s E:. statement, add this routineC
PUBLIC SUB hB-tton8Click()
1Main.Close
!D
Once 'ou have entered the code above, c&ic- the green program run button and 'ou
shou&d see something simi&ar to ,hat is sho,n in the /igure above# 2imp&' c&ic- the button or
press the E2C -e' to e6it this program# Congratu&ationsS Kou have 9ust created 'our /irst G@+4
based program in GambasS Kes, it is a &itt&e bit ug&' but remember, 'ou did it the hard ,a',
using code instead o/ ta-ing advantage o/ the Gambas >oo&Bo6# :o,, save 'our pro9ect and
e6it Gambas /or no, and ,e ,i&& proceed ,ith &earning more about the >oo&Bo6#
Progr""ing &ipL
Al.a$s tr$ use pre"e(ine" constants i( the$ are a'ailable instea" o( har"&co"ing numeric 'alues to
ensure portabilit$. For e8ample9 3e$ co"es an" mouse st$les ha'e the same names as the$ are
"e(ine" as constants9 but their numeric 'alues are totall$ "i((erent. The gb.gt3 component .ill not
.or3 .ith gb.<t co"e i( $ou "o not use those pre"e(ine" constants. There(ore9 .hen .riting co"e9 it is
imperati'e to use pre"e(ine" constants instea" o( numeric 'alues. +( not9 the co"e .ill not be
portable.
,ursor is de/ined as P+OPE+&3 Cursor ,$ Cursor and 'ou can use the Cursor
83
Figure 21: First button co"e results.
propert' /or assigning a custom cursor to a contro&# >his c&ass imp&ements a custom mouse
cursor# >his c&ass is creatab&e# =ere is ho, to dec&are a cursor ob9ect variab&e and instantiate a
cursor ob9ectC
DIM hC-rsor $S C-rsor
hC-rsor 6 !+ C-rsor (MyPic $S Pict-re "0 7 $S Inte5er0 W $S Inte5er%)
>he code /ormat above can be used to create a ne, cursor /rom a Picture ob9ect and set
an optiona& hot spot# +/ it is not speci/ied, the de/au&t hotspot is the top &e/t o/ the picture#
Cursor has t,o properties, Q and K, that can be used to set or get the current mouse position#
=ere is an e6amp&e that sho,s 'ou ho, to use a Cursor ob9ect in 'our programC
DIM hPict $S Pict-re
DIM hC-rsor $S C-rsor
hPict 6 Pict-re";torric.pn5;%
hC-rsor 6 !+ C-rsor(hPict)
M.C-rsor 6 hC-rsor
-efault is de/ined as P+OPE+&3 #efult ,$ %oolen and 'ou use the .e/au&t
propert' to indicate ,hether or not the button is activated ,henever the RE>@R: -e' is
pressed# @sing the code be&o,, it ,ou&d /orce the user to actua&&' c&ic- a button rather than
hit the RE>@R: -e' to activate it# Genera&&', ,hen creating an OEMCance& t'pe dia&og, 'ou
,ou&d ,ant to set one o/ the buttons to a de/au&t action using this propert'# >hin- about 9ust
hitting the RE>@R: -e' in a ,i0ard to accept the de/au&t settings and move on#
hB-tton.De*a-lt 6 1$LS
-esign is de/ined as P+OPE+&3 #esign ,$ %oolen and it indicates that the
contro& is in design mode# >his means that ,hen the .esign propert' is set to >R@E, contro&s
in design mode 9ust dra, themse&ves and ,i&& not react to an' input event# >his propert' is
used b' the Gambas .eve&opment Environment to disp&a' contro&s in the /orm editor# <hat
this rea&&' means is 'ou do not need to ,orr' about this propert'#
-rop is de/ined as P+OPE+&3 #rop ,$ %oolen and is used to chec- to see i/ a
contro& accept the drop /rom a drag and drop operation# >he .rop propert' is either >R@E or
7AL2E and 'ou can chec- the va&ue be/ore tr'ing to drop something onto the contro& b' using
code &i-e thisC
I1 hB-tton.Drop 6 1$LS #:!
hB-tton.#ool#ip 6 ;!o Drops alloAe);
LS
hB-tton.#ool#ip 6 ;Drop somethin5 here;
!DI1

!nabled is de/ined as P+OPE+&3 En/led ,$ %oolen and it indicates that the
84
contro& is enab&ed# >o disab&e a contro&, simp&' set it's Enab&ed propert' to 7AL2E#
I1 xpression 6 1$LS #:!
hB-tton.nable) 6 #'U
LS
hB-tton.nable) 6 1$LS
!DI1
>he !xpand propert' is de/ined as P+OPE+&3 Expnd ,$ %oolen and and it
indicates that the contro& is ab&e to e6pand i/ it is inc&uded in a container that d'namica&&' re4
arranges its contents#
.ont is de/ined as P+OPE+&3 !ont ,$ !ont and it returns or sets the /ont used to
dra, te6t in the contro&# >o set 7ont propert' attributes, code &i-e this can be usedC
hB-tton.1ont.!ame 6 ;L-ci)a;
hB-tton.1ont.Bol) 6 #'U
hB-tton.1ont.Italic 6 1$LS
hB-tton.1ont.SiRe 6 ;=9;
hB-tton.1ont.Strike2-t 6 1$LS
hB-tton.1ont.Un)erline 6 1$LS
>he output o/ the above code ,ou&d be as /o&&o,sC
.oreground is de/ined as P+OPE+&3 !oreground ,$ *nteger and this integer
va&ue represents the co&or used /or the contro& /oreground# +t is s'non'mous ,ith the
7oreground propert'# Kou can use the Gambas prede/ined constants /or co&or to set co&or
va&ueC
Black Bl-e Cyan DarkBl-e DarkCyan Dark.ray
Dark.reen DarkMa5enta Dark'e) DarkWelloA De*a-lt .ray
.reen Li5ht.ray Ma5enta 2ran5e Pink 'e)
#ransparent (iolet +hite WelloA
>o set the 7oreground propert' /or hButton to red, 'ou ,ou&d use this codeC
hB-tton.1ore5ro-n) 6 Color.'e)
8#
Figure 21: ,emonstrating (ont capabilities.
As ,ith the Bac-ground propert', i/ 'ou -no, the RGB or =2! va&ues /or a speci/ic
co&or, 'ou can pass them to the 7oreground propert' ,ith this codeC
hB-tton.1ore5ro-n) 6 Color.'.B(BCC0BCC0BCC)
>his ,ou&d set the button's /oreground co&or to ,hite#
>he / propert' is de/ined as 01O0!12 / 3S Integer and it is used to set or return
the 6 position o/ the contro&# H is the same as Le/t propert'# >he 2 propert' is de/ined as
01O0!12 2 3S Integer and it is used to set or return the ' position o/ the contro& (top
&e/t corner#

>he 4eight propert' is de/ined as 01O0!12 4eight 3S Integer and it is used to
set or return the height o/ the contro&# +t is s'non'mous ,ith the 6 propert' and can be used
interchangeab&'# >his va&ue describes ho, ta&& the contro& is /rom the 6 position moving do,n
4eight pi6e&s# >he Width propert' is de/ined as 01O0!12 Width 3S Integer and it is
used to set or return the ,idth o/ the contro&# +t is s'non'mous ,ith the - propert' and can
be used interchangeab&'# >his va&ue describes ho, ,ide the contro& is /rom the 6 position to
the right Width pi6e&s#
>he 4andle propert' is de/ined as P+OPE+&3 +E,# 6ndle ,$ *nteger and is
used to return the interna& Q"" ,indo, hand&e o/ the contro&# +t is a read4on&' attribute# +t is
s'non'mous ,ith the Id ( P+OPE+&3 +E,# *d ,$ *nteger #
>he Mouse propert' is de/ined as P+OPE+&3 Mouse ,$ *nteger and is used to
set or return the appearance o/ the cursor to a prede/ined image ,hen it hovers inside the
boundaries o/ the contro&# Prede/ined va&ues /or the 1ouse propert' are sho,n in the tab&e
be&o,C
C-rsor shape (al-e C-rsor shape (al-e C-rsor shape (al-e
Arrow 0 SizeH 6 SizeV 5
Blank 10 SizeN 5 SizeW 6
Cross 2 SizeNE 7 SplitH 12
Custom -2 SizeNESW 7 SplitV 11
e!ault -1 SizeNW " #e$t %
Horizontal 0 SizeNWSE " Verti&al 1
'ointin( 1) SizeS 5 Wait )
SizeAll * SizeSE "
SizeE 6 SizeSW 7
>he Next propert' is de/ined as P+OPE+&3 +E,# Next ,$ Control and it is used
to return the ne6t contro& having the same parent ,ithin a Container# +t is use/u& ,hen
88
iterating through a series o/ contro&s to set /ocus# <e ,i&& discuss this propert' in more detai&
,hen ,e discuss the 2et7ocus( method# >o get the previous contro&, one ,ou&d use the
0re#ious propert', de/ined as P+OPE+&3 +E,# Previous ,$ Control1 >his propert'
returns the previous contro& having the same parent#
>he 0arent propert' is de/ined as P+OPE+&3 +E,# Prent ,$ Control and is
used to return the container that ho&ds the contro&# +t is a read4on&' propert'#
>he 0icture propert' is de/ined as P+OPE+&3 Picture ,$ Picture and returns or
sets the picture sho,n on a contro& (i#e#, a button# <e ,i&& discuss the Picture c&ass &ater in
this chapter#
>he Screen/ propert' is de/ined as P+OPE+&3 +E,# $creenH ,$ *nteger and
it returns the position o/ the &e/t border o/ the contro& in screen coordinates# @sua&&', it is
used in con9unction ,ith 2creenK#
>he Screen2 propert' is de/ined as P+OPE+&3 +E,# $creenH ,$ *nteger and
returns the position o/ the top border o/ the contro& in screen coordinates#
>he ag propert' is de/ined as P+OPE+&3 &g ,$ 'rint and is used to return or
sets the contro& tag# >his propert' is intended /or use b' the programmer and is ne#er used
b' the component# +t can contain an' !ariant va&ue#
>he ext propert' is de/ined as P+OPE+&3 &ext ,$ $tring and returns or sets the
te6t disp&a'ed in the button# +t is a&most a&,a's used and it's va&ue can be changed
d'namica&&'# <e have a&read' used this propert' in the e6amp&e aboveC
hB-tton.#ext 6 ;Click or press SC to Y-it;
>he oolip propert' is de/ined as PROPER>K >oo&>ip A2 2tring and returns or sets
the too&tip (a tooltip is the little bo of tet that pops up over a control when the mouse
hovers over it for a few seconds#
hB-tton.#ool#ip 6 ;Click meV;

>he op propert' is de/ined as P+OPE+&3 &op ,$ *nteger and returns or sets the
position o/ the top border o/ the contro& re&ative to its parent#
>he 5alue propert' is de/ined as P+OPE+&3 'lue ,$ %oolen and it is used to
activate the contro& (i#e#, ma-e the button c&ic-# >his is done i/ 'ou set this propert' to >R@E#
Reading this propert' ,i&& a&,a's return a va&ue o/ 7AL2E#
>he 5isible propert' is de/ined as P+OPE+&3 'isi/le ,$ %oolen and it indicates
i/ the contro& is visib&e or not# 2etting this propert' to 7AL2E ,i&& ma-e it disappear /rom
vie,# Converse&', setting it to >R@E ma-es it appear#
8?
>he Window propert' is de/ined as P+OPE+&3 +E,# -indow ,$ -indow and
returns the top4&eve& ,indo, that contains the contro&#
At this point, ,e have covered a&& o/ the properties /or the Button Contro& and 'ou
shou&d have a prett' good understanding o/ ,hat the' are used /or and ho, to use them#
Remember that most o/ these properties are common to man' contro&s# :e6t, ,e ,i&& cover
the methods (things 'ou can do ,ith the button and provide 'ou some e6amp&es o/ ho, to
use them#
(-tton .ethos
1ethods are the bui&t4in routines provided /or a contro& that a&&o, 'ou to do things &i-e
sho, it, hide it, move it, etc# =ere are the methods supported b' the Button contro&C -elete6
-rag6 Grab6 4ide6 )ower6 Mo#e6 1aise6 1efresh6 1esi7e6 Set.ocus6 and Show#
@sua&&', a method is ca&&ed in response to some event# <e ,i&& discuss events in the ne6t
section# Let's ta-e a &oo- at the methods used ,ith ButtonC
>he -elete method is de/ined as $(% #elete() and ,hen invo-ed it destro's the
contro&# +t is important to -no, that a destro'ed contro& becomes an inva&id ob9ect# <hat this
means is that once 'ou have destro'ed it, ensure no other code subse5uent&' re/erences it#
>he -rag method is de/ined as $(% #rg ( #t ,$ 'rint 2 4 !or"t ,$
$tring 5 ) and ,hen invo-ed it starts a drag P drop process# .ata is the data to be dragged#
+t can be a 2tring or an +mage# +/ .ata is a te6t string, then 'ou can speci/' in +ormat the
1+1E >KPE o/ the te6t being dragged# 7or e6amp&e, 1+1E >KPE Ate6tMhtm&B#
>he Grab method is de/ined as !(NC&*ON Fr/ ( ) ,$ Picture and it grabs a
picture o/ the contro& and returns it#
>he 4ide method and the Show method are de/ined as $(% 6ide() and $(%
$how() and the' simp&' hide or sho, the contro&# =ere is ho, the' ,ou&d be usedC
I1 xpression 6 #'U #:!
hB-tton.:i)e
LS
hB-tton.ShoA
!DI1
>he )ower method and 1aise method are de/ined as $(% )ower() and $(%
+ise()# Lo,er sends the contro& to the bac-ground o/ its parent# Raise brings the contro& to
the /oreground o/ its parent# As an e6amp&e o/ ho, these methods ,or-, &et's go bac- to our
pro9ect, 7irstPro9ect# Change the code in the hButtonLC&ic-( routine# 7irst, se&ect and cop'
a&& o/ the the code in 'our P)+&%C ,)+ -orm.Open/011EN! b&oc-, and paste it into 'our
P)+&%C ,)+ h+utton.C*ick/011EN! b&oc-#
8%
A/ter the hButton#2ho, &ine, and be/ore 71ain#CLO2E, add the /o&&o,ing codeC
hB-tton.#ext 6 D2-chVE
+$I# B.9
hB-tton.:i)e
+$I# =.C
hB-tton.ShoA
hB-tton.#ext 6 DBetter noAV ,, 5oo)byeVE
+ait =.9
Once 'ou have entered the code, run the program and see ,hat happens# <hen 'ou
c&ic- the button it ,i&& disappear and the hButton#>e6t ,i&& change# A/ter t,o seconds, it ,i&&
reappear and change the &abe& again# A&so, note that ,e s&ipped in a ne, command /or 'ou to
tr' -,*&# <A+> ta-es a /&oating point va&ue as a parameter that represents seconds or
/ractions o/ seconds e6pressed as decima& va&ues# :umbers &ess than " are processed as
mi&&iseconds# <A+> "#G ,ou&d pause e6ecution /or ",G$$ mi&&iseconds# +/ 'ou speci/' <A+>
,ithout a parameter, it ,i&& re/resh the inter/ace and it does not a&&o, the user to interact ,ith
the app&ication#
>he Mo#e method is de/ined as $(% Move ( H ,$ *nteger4 3 ,$ *nteger 2 4
-idth ,$ *nteger4 6eight ,$ *nteger 5 ) and is used to move andMor resi0e the contro&#
hB-tton.Move(hB-tton.7 , C90 hB-tton.W Z B9)
>he 1efresh method is de/ined as $(% +efresh ( 2 H ,$ *nteger4 3 ,$ *nteger4
-idth ,$ *nteger4 6eight ,$ *nteger 5 ) and is used to redra, the contro&, or in some
instances, 9ust a portion o/ it#
>he 1esi7e method is de/ined as $(% +esi<e ( -idth ,$ *nteger4 6eight ,$
*nteger ) and is used to resi0e the contro&#
>he Set.ocus method is de/ined as $(% $et!ocus ( ) and 'ou ca&& this method to
give /ocus to the contro&# 7ocus is rough&' e5uated to ,here the te6t cursor ,ou&d be &ocated#
<hen a contro& has /ocus it is usua&&' indicated visua&&' in some manner# 7or e6amp&e, a
button ,ith /ocus ma' have a sma&& dotted &ine around it to indicate ,here /ocus contro& is on
the /ormC
8+
Figure 22: The "otte" line in"icates (ocus
(or a control.
<e have covered a&& o/ the methods avai&ab&e /or the Button c&ass (contro& and ,i&& no,
begin discussing the events /or that c&ass# As a change o/ pace, &et's tr' to &earn about events
,ith a more hands on approach# <e can do this b' bui&ding a ne, program and &earning ,hat
the events do and ho, to use them# C&icon 7i&eY:e, on the top menu bar, or 9ust c&icon
the b&an- document icon to start a ne, pro9ect >his ,i&& c&ose the current pro9ect and initiate
the :e, Pro9ect <i0ard# 2e&ect AHt graphica& app&icationB and go through the ,i0ard 9ust &i-e
,e did ,ith the pro9ect 7irstPro9ect# :ame this pro9ect 2econdPro9ectH># Once the +.E
appears, doub&e4c&icon the A71ainB icon in the >ree!ie, ,indo,# >his /irst /orm ,i&&
a&,a's be named A71ain#/ormB# 7or this pro9ect, ,e are going to p&ace three Labe& contro&s
on the /orm, as sho,n be&o,# <e ,i&& use the /orm too&s provided in the too&bo6 in the &o,er
right4hand corner o/ the +.E#
Create the &abe&s b' c&ic-ing on the ALabe&B icon in the too&bo6, then c&ic-ing and
dragging the mouse cursor in the /orm, to ma-e rectang&es# <hen a /orm has been created, it
,i&& automatica&&' be se&ected, and 'ou can use the border hand&es to resi0e them as
appropriate# Kou can c&icon these ob9ects at an' time and resi0e or grab4and4move them,
and 'ou can a&so move them b' pressing do,n on 'our -e'board's cursor (arro, -e's, as
,e&&#
>he &abe&s, buttons, etc#, ,i&& automatica&&' be named in the order that 'ou create them#
Kou can a&so change the names, i/ desired# >he /irst &abe&'s te6t caption is set ,ith the
Labe&#>e6t propert' c&icon the Labe&" bo6 ,hich 'ou created, and /ind A>e6tB on the
Properties tab to the right o/ the /orm (i/ it is not visib&e, press !N on 'our -e'board, to togg&e
the tabs into vie,# >he setting /or Labe&" shou&d be A=ere is theB\ /or Labe&; AGambas
1ascotB\ and /or Labe&D A44444YB, ,hich points to a PictureBo6 contro& (,here the shrimp
&ives# :e6t, create the PictureBo6 contro& Picture%oxO#
?0
Figure 23: >a$out (or the F2ain (orm (or the secon"
project.
>o obtain the graphic o/ the Gambas mascot, 'ou can go to the o//icia& Gambas ,eb
site
";
and right c&icon the mascot# Choose to save the image and save it as Agambas
mascot#pngB on 'our computer# 1ove the /i&e to the data director' in the 2econdPro9ect
/o&der# () 5ambas "uir& is that the file eplorer dialogs don$t seem to be dynamic. /nce
they have initiali6ed, changes made outside the 5ambas environment are not updated
dynamically.) Once 'ou have done this, 'ou can set the Picture propert' /or PictureBo6" to
the /i&e named Agambas mascot#pngB# At this point, the top o/ 'our /orm shou&d &oo- &i-e the
/igure be&o,#
:o,, se&ect the Progress%r contro& /rom the >oo&Bo6 and p&ace it on the /orm so it
&oo-s &i-e that sho,n in 7igure "J above# 7ina&&', ,e have three buttons to add to the /orm#
:ame these buttons 7unBtn, :o7unBtn, and HuitBtn# A&& o/ the necessar' contro&s /or our
e6amp&e have been added to the /orm at this point# >r' to get the &a'out to &oo- as c&ose to the
picture sho,n in the /igure above as possib&e# At this point, 'ou ma' be as-ing ,hat a&& o/ this
is going to accomp&ishN Remember, ,e are going to &earn ho, to use events ,ith these
contro&s# <e have p&aced the contro&s ,here ,e ,ant them and no, the ne6t step is to decide
,hat events ,e are going to hand&e#
7or this e6ercise, ,e are going to hand&e mouse events ,hen the mouse moves over
&abe&s# +/ the mouse moves o// o/ the main ,indo, (!Min1for" or bac- onto it ,e ,i&&
hand&e those events# <e ,i&& a&so hand&e button c&ic-s and the E2C -e' i/ it is pressed#
Let's begin b' setting the ProgressBar"#!a&ue to G$R ,hen the program starts# >hat is
hand&ed ,ith the initia&i0ation routine ,hen opening the /orm at program runtime, as sho,n
be&o,C
T .ambas class *ile
Pro5ressBar=.(al-e 6 9.C9
Pro5ressBar=.Back5ro-n) 6 Black
Pro5ressBar=.1ore5ro-n) 6 WelloA
!D
12 The o>>icial Gambas site is httpG99gambas.source>orge.net9inde2.html .
?1
Figure 2#: A partiall$ constructe" (orm .ith our (irst (our
controls.
<hen the mouse moves over the startup /orm (our 5ambas program on the des&top,
,e ,ant to set the three top &abe&s' te6t properties to b&an- va&ues so it appears that the te6t
disappears# >his re5uires choosing an event handler# >o choose an event /rom the Gambas
+.E, move the mouse over the /orm (but not direct&' over a contro& and c&icit once# :e6t,
right c&ic- the mouse and 'ou shou&d see a menu pop4up, simi&ar to the one sho,n in the
/o&&o,ing /igure# Choose the Event se&ection item /rom the popup and pic- the Enter event#
Add this code, as sho,n be&o,C
PUBLIC SUB 1orm8nter()
Label=.#ext 6 ;;
LabelB.#ext 6 ;;
Label/.#ext 6 ;;
!D
Repeat this process to choose another event, the )eve event, so that ,hen the mouse
moves o// the program ,indo, ,e can detect that and do something about it# Add this codeC
PUBLIC SUB 1orm8Leave()
Pro5ressBar=.(al-e 6 9.C9
Label=.#ext 6 ;+asnTt that;
LabelB.#ext 6 ;some real;
Label/.#ext 6 ;*-n st-**J;
!D
?2
Figure 2%: The Gambas -'ent 2enu.
>he ne6t thing ,e ,ant to do is hand&e the situation (event that occurs ,hen the
mouse moves over an' o/ our &abe&s# +n this event, ,e are going to change the Labe&#>e6t
propert' o/ the a//ected &abe& to indicate that a mouse has been detected over the contro&#
2ing&e4c&ic- 'our mouse cursor on the /irst &abe& and ,hen the hand&es appear, right c&ic- and
choose the Enter event ,hen it appears on the Event submenu# +n the code ,indo,, /ind the
)/elOMEnter() subroutine and enter this codeC
PUBLIC SUB Label=8nter()
Label=.#ext 6 ;:ere is the;
!D
Repeat the same process /or the Labe&;#>e6t and Labe&D#>e6t properties# Kour code shou&d
&oo- &i-e thisC
PUBLIC SUB LabelB8nter()
LabelB.#ext 6 ;.ambas Mascot;
!D
PUBLIC SUB Label/8nter()
Label/.#ext 6 ;,,,,,K;
!D
<e a&so ,ant to detect and respond to events ,hen the mouse moves over our mascot
picture as ,e&&# C&ic- once on the PictureBo6" contro& and choose the Enter Event# Go to the
code ,indo, and ma-e the code &oo- &i-e thisC
PUBLIC SUB Pict-reBox=8nter()
Label=.#ext 6 ;;
LabelB.#ext 6 ;;
Label/.#ext 6 ;;
Pict-reBox=.Bor)er 6 Bor)er.Plain
!D
Repeat the process, choosing the )eve event and ensure 'our code is t'ped in the code
editor as /o&&o,sC
PUBLIC SUB Pict-reBox=8Leave()
Label=.#ext 6 ;+asnTt that;
LabelB.#ext 6 ;some real;
Label/.#ext 6 ;*-n st-**J;
Pict-reBox=.Bor)er 6 Bor)er.S-nken
!D
>he ne6t contro& that ,e ,ant to ta-e care o/ is the Huit button# .oub&e4c&icon it and
?3
the code ,indo, disp&a's the Euit%tnMClick() subroutine, ,hich responds to a C&ic- event#
Add the !or"O1Close &ine, as sho,n be&o,#
PUBLIC SUB Y-itBtn8Click()
1orm=.Close
!D
One additiona& change must be added to the Huit button# C&icon the Huit button in
the /orm, and the Properties tab ,i&& appear# 7ind the Cncel propert', and change it /rom
7a&se to >rue# >his ,i&& a&&o, the E$C -e' to c&ose the program, 9ust as i/ 'ou had c&ic-ed on
the Huit button#
:o,, ,e have to ,rite code /or the ProgressBar# :ote that at this time o/ ,riting, the
ProgressBar in G>EF does not ,or- correct&' one e6amp&e o/ ,h' ,e have a pre/erence /or
using Ht in Gambas# 7or our e6amp&e, ,e ,i&& increment the ProgressBar ,hen the 7unBtn is
c&ic-ed and decrement it ,hen the :o7unBtn is c&ic-ed#
.oub&e4c&icon the 7unBtn contro& and add this codeC
PUBLIC SUB 1-nBtn8Click()
Pro5ressBar=.(al-e 6 Pro5ressBar=.(al-e H 9.9=
I1 Pro5ressBar=.(al-e K 9.>> #:!
Pro5ressBar=.(al-e 6 9.9
!DI1
!D
?4
Figure 2): A""ing the Fun=tn to our (orm.
:e6t, doub&e4c&icon the :o7unBtn and add thisC
PUBLIC SUB !o1-nBtn8Click()
Pro5ressBar=.(al-e 6 Pro5ressBar=.(al-e Z 9.9=
I1 Pro5ressBar=.(al-e U 9.9= #:!
!DI1
!D
>hat is near&' a&& there is &e/t to doS :o,, save the pro9ect and c&ic- the run button# Kou
shou&d see something simi&ar to the /igure above on program start# :o,, c&ic- the AC&ic- me
/or more /unB button to see that the progress bar ,i&& change# C&icit three times and 'ou
shou&d see thisC
:ote the te6t /ie&d disappears ,hen the mouse enters the /orm# +/ 'ou move 'our mouse
over the mascot picture, 'ou shou&d see the &abe& te6t appear and disappear as 'ou move the
?#
Figure 2*: +nitial "ispla$ o( our (orm.
Figure 2/: Figure 11: The progress bar .hen the
Fun=tn is clic3e" three times.
mouse on and o// the picture# 7ina&&', 'ou can hit E2C or c&ic- the Huit button to e6it the
program# >he &ast event ,e are going to ,rite code /or in this e6amp&e is the dou/le.click
event# >his re5uires 'ou to once again choose an event handler#
7rom the Gambas +.E, move the mouse over the 7unBtn and c&icit once# :e6t, right
c&ic- the mouse and 'ou ,i&& see the menu pop4up a&&o,ing 'ou to choose Events# 7rom the
Events submenu, pic- the #/lclick event# Add this code, as sho,n be&o,C
PUBLIC SUB 1-nBtn8DblClick()
Pro5ressBar=.(al-e 6 Pro5ressBar=.(al-e H 9.=
I1 Pro5ressBar=.(al-e K 9.>9 #:!
!DI1
!D
Repeat this process /or the :o7unBtn and add this codeC
PUBLIC SUB !o1-nBtn8DblClick()
Pro5ressBar=.(al-e 6 Pro5ressBar=.(al-e , 9.=
I1 Pro5ressBar=.(al-e U 9.= #:!
!DI1
!D
:o,, save the pro9ect and c&ic- the run button# >his time, ,hen 'ou c&ic- the progress
bar it ,or-s 9ust as it did be/ore, but i/ 'ou doub&e4c&ic-, it ,i&& increment the va&ue b' "$ units
rather than b' one# Once 'ou e6it 'our program, save 'our pro9ect and e6it Gambas# :e6t, ,e
are going to &oo- at the the other events that can used ,ith the Button contro&#
(-tton E/ents
>he Button events ,e have used in our previous e6amp&e inc&ude the C&ic-, .b&C&ic-,
Enter, and Leave events# <e ,i&& reserve our discussion o/ the remaining events, name&'
.rag, .rag1ove, .rop, Lost7ocus and Got7ocus /or ,hen ,e dea& ,ith drag and drop
operations# >he 1enu, Ee'Press and Ee'Re&ease events ,i&& be covered ,hen ,e ta&- about
menu and -e'board operations# 7ina&&', ,hen ,e cover mouse operations, ,e ,i&& discuss the
1ouse.o,n, 1ouse1ove, 1ouse@p, and 1ouse<hee& events#
The Picture C*ass
Ear&ier in the chapter, ,hen ,e used the Picture contro& to p&ace our mascot on the
/orm in our second e6amp&e, ,e mentioned the Picture C&ass and said ,e ,ou&d cover it &ater#
<e&&, no, it is time to ta&- about the Picture C&ass# >his c&ass represents a picture and its
contents are stored in the disp&a' server, not in process memor' &i-e an +mage ,ou&d be
?8
norma&&' stored# Even i/ Q4<indo,s does not manage transparenc' ('et, each picture ob9ect
can have a mas- assigned ,ith it# >his can be set e6p&icit&' at the time the picture is
instantiated, or it can be set imp&icit&' ,hen &oading an image /i&e that has transparenc'
attributes, &i-e a P:G /i&e# <hen dra,ing on a picture having a mas-, both the picture and the
mas- are modi/ied# >his c&ass is creatab&e# +t is de/ined asC
DIM hPict-re $S Pict-re
and the process o/ instantiating it uses this /ormatC
hPict-re 6 !+ Pict-re ("+i)th $S Inte5er0 :ei5ht $S Inte5er0 #ransparent $S Boolean %)
>he code above ,i&& create a ne, picture ob9ect# +/ the <idth and =eight are not speci/ied, the
ne, picture is empt' (void# Kou can speci/' i/ the picture has a mas- ,ith the >ransparent
parameter# >he picture c&ass acts &i-e an arra'# 7or e6amp&eC
hPict-re 6 Pict-re " Path $S Strin5 %
,i&& return a Picture ob9ect /rom the interna& picture cache# +/ the picture is not present in the
cache, it is automatica&&' &oaded /rom the speci/ied /i&e# >o insert a picture in the cache, use
this ca&&C
Pict-re " Path $S Strin5 % 6 hPict-re
Properties /or this contro& inc&ude .epth, =eight, +mage, >ransparent, and <idth# >he
methods provided inc&ude C&ear, Cop', 7i&&, 7&ush, Load, Resi0e, and 2ave# <e ,i&& cover the
use o/ these methods and properties in &ater e6amp&es in this boo-# At this point, 'ou shou&d
have a so&id understanding o/ ho, to use the Gambas programming environment and it's
various too&s# +n the ne6t /e, chapters, ,e ,i&& present more contro&s ,ith more comp&e6
e6amp&es as the best ,a' to &earn is b' doing#
??
Chapter % Contros &or 'ser Input
+n our introduction to contro&s, ,e &earned about the most basic t'pes o/ contro&s and
events, name&' pictures, &abe&s, buttons, and a progress bar# <e a&so &earned ho, to detect
,hen the mouse is over a contro& and ,hat actions ,e can ta-e ,hen it moves on or o// the
contro&# >hese t'pes o/ contro&s a&& present data or respond to events &i-e the mouse or a
button c&ic-, but the' do not a&&o, users to choose /rom among a&ternatives such as pic-ing
items /rom a &ist or t'ping in their name, etc# +n this chapter, ,e ,i&& add to our arsena& o/
Gambas -no,&edge b' &earning ho, to accomp&ish those tas-s and respond to even more
events# <e are going to bui&d a program that ,i&& introduce 'ou to the /o&&o,ing contro&s and
teach 'ou ho, to use themC
>e6tLabe&
>e6tBo6
ComboBo6
ListBo6
>ogg&eButton
Pane&
7rame
Chec-bo6
RadioButton
=ere is ,hat our program ,i&& &oo- &i-e ,hen ,e are /inished ,ith itC
+n this e6ercise, ,e ,i&& &earn to put tit&es on our program ,indo,, use an input bo6 to
gather =>1L4/ormatted input /rom the user and disp&a' that resu&t in a ne, t'pe o/ &abe&, the
&ext)/el# <e ,i&& a&so &earn ho, to group and organi0e our contro&s on the /orm, using
?%
Figure 20: Thir" Project (inal results.
pane&s and /rames, and p&ace contro&s &i-e +dio%uttons and Check%oxes ,ithin those
organi0ationa& contro&s# 7ina&&', ,e ,i&& &earn ho, to use )ist%oxes and Co"/o%oxes to
a&&o, the user to se&ect /rom one o/ man' choices# A&ong the ,a', ,e ,i&& &earn a bit more
about event coding and tr' to ma-e it interesting#
Let's get started b' creating a ne, Pro9ect ,ith Gambas# 2tart Gambas and choose to
create a ne, pro9ect using a H> graphica& app&ication# Go through the ,i0ard ma-ing the
pro9ect trans&atab&e and the /orm contro&s pub&ic# 2e&ect the name &hirdProjectE& and put
it in a director' o/ 'our choosing# <hen the +.E starts, create a ne,, startup c&ass /orm b'
doub&e4c&ic-ing on the 71ain /orm icon# .oub&e4c&icon the b&an- /orm, and the code editor
,indo, ,i&& appear# Kou shou&d see something &i-e thisC
T .ambas class *ile
!D
:o,, ,e ,i&& start b' putting the tit&e o/ our program at the top o/ the ,indo, ,hen the
program runs# >o accomp&ish this, ,e ,i&& set the /orm's Caption propert' to the te6t ,e ,ant
to use as the tit&e# Enter this &ine in the 7ormLOpen( subroutineC
M.Caption 6 ; LLL #hir) Pro3ect LLL ;
>hat ta-es care o/ the te6t /or the ,indo, tit&e# :o,, i/ ,e &oo- at our /ina& resu&t
picture, ,e sti&& have to add our contro&s# <e ,i&& start at the top, adding the contro&s ,e
a&read' -no, aboutC )/el4 &ext%ox, and %utton# P&ace each contro& on the /orm as
sho,n in 7igure ;I above# :ame the contro&s 7abel8, Tet9o8, and :pdate9tn# >hese
contro&s ,ere used in the &ast chapter, so 'ou shou&d be com/ortab&e using them in 'our
programs# :e6t, ,e ,i&& add the Huit Button at the bottom right corner o/ the /orm# :ame
this contro& HuitBtn# :o,, &et's add the code /or these contro&s# .oub&e4c&ic- the mouse on
the HuitBtn and add this code to the Euit%tnMClick() subroutineC
1Main.Close
!D
7or the update button, ,e are going to trans/er the te6t the user t'ped into the >e6tBo6
contro& to the >e6tLabe&, re/&ecting an' =>1L /ormatting that the' entered# =ere is the code
needed /or thatC
PUBLIC SUB Up)ateBtn8Click()
#extLabel=.#ext 6 #extBox=.#ext
!D
?+
7rom this point on, ,e ,i&& be &earning to use ne, contro&s and /eatures o/ Gambas#
<e have a&read' ,ritten code to assign input data to the >e6tLabe&, so &et's ta-e the time no,
to &earn a&& ,e can about it# Be/ore ,e start, it is probab&' a good idea to go ahead and c&ic-
the save button on the +.E to save 'our ,or-#

Tet&abe*
>his c&ass is creatab&e and it inherits its attributes /rom the Contro& c&ass# Li-e
a&& o/ the contro&s that contain te6t, Gambas a&&o,s 'ou to set the /ormatting in the Properties
tab# +n >e6tLabe&, 'ou can setC A&ignment (Le/t, Center, or Right\ 7ont (>'pe/ace, 2i0e, Bo&d,
@nder&ine, 2tri-eout\ and both Bac-ground and 7oreground co&ors and shading# >e6tLabe&
a&so imp&ements a contro& capab&e o/ disp&a'ing simp&e =>1L te6t, 44 this is use/u& ,hen
creating and /ormatting contro&s that contain te6t in 'our code /or c&asses (i#e#, ,hen 'ou are
doing it the Ahard ,a'B not using a /orm to create these ob9ects# Kou can use =>1L
entities such as :lt and :gt to disp&a' characters &i-e C and D# 7or =>1L that re5uires the
use o/ 5uote mar-s, avoid 5uotes( I11 J) because it ,i&& not ,or-# 7or e6amp&e, do not enterC
U)iv ali5n6;center;K UbK #his AonTt Aork.UMbK
>'pe this insteadC
U)iv ali5n6centerKUbK #his Aill Aork.UbK
>he /igure be&o, sho,s 'ou an e6amp&e o/ ho, t'ping =>1L in the >e6tLabe& bo6 ,or-sC
O/ course, no one e6pects the app&ication user to /ormat their o,n te6t ,hen t'ping in a
>e6tBo6, using =>1L# +t is /ar more use/u& to ,rite the =>1L /ormatting into 'our string4
hand&ing code /or >e6tLabe&# >his ,a', Gambas &ets us inc&ude /ormatting e//ects that are not
other,ise avai&ab&e, un&ess 'ou created the >e6tLabe& ob9ect on a /orm# =ere are a /e, o/ the
=>1L tags that ,i&& ,or- in 'our >e6tLabe& code (and ,hen 'ou inc&ude them in code, the'
must be enc&osed in 5uotes (A##BC
ali5nmentO DU)iv ali5n6centerKE
(or 'ou ma' a&so use AleftB or ArightB in p&ace o/ the ,ord AcenterB
bol)O DUbKE..EUMbKE
%0
Figure 31: 5sing ?T2> to (ormat a te8t label.
-n)erscoreO DU-KE..EUM-KE
strikethro-5hO DUsKE..EUMsKE
+n =>1L, ,hen 'ou combine tags, the start tags and end tags must be in reverse order# 7or
e6amp&eC
DU)iv ali5n6centerKU-KUbKE...EUMbKUM-KE
One te6t attribute that 'ou cannot contro& in >e6tLabe& code is co&orC
DU12!# C2L2' 6 119999KUbKE S D#his Aill !2# Aork.E S DUbKUM12!#KE
>e6tLabe& is de/ined as #*M h&ext)/el ,$ &ext)/el and 'ou dec&are it &i-e thisC
h#extLabel 6 !+ #extLabel ( Parent $S Container )
<hat ,e ,ant to do no, is code the update button to ta-e advantage o/ these =>1L
/eatures# >o accomp&ish this, ,e need to modi/' the code ,e previous&' entered /or the update
button's c&ic- event# .oub&e4c&icon the @pdateBtn contro& and change the code to &oo- &i-e
thisC
PUBLIC SUB Up)ateBtn8Click()
#extLabel=.#ext6 ;U)iv ali5n6centerKU-KUbK; S #extBox=.#ext S ;UM-KUMbK;
!D
+n addition, change the code in the >e6tBo6"LLeave event to &oo- &i-e thisC
PUBLIC SUB #extBox=8Leave()
#extLabel=.#ext 6 DU)iv ali5n6centerKU-KUbKE S #extBox=.#ext S DUMbKUM-KE
#extBox=.#ext 6 Dnter text hereE
!D
+nstead o/ simp&' assigning the input te6t /rom the >e6tBo6 to the >e6tLabe&"#>e6t
propert', ,e are going to ma-e it &oo- /anc'# :o,, an'thing the user t'pes ,i&& automatica&&'
be centered, under&ined, in bo&d/ace and p&aced on the >e6tLabe&"# +/ 'ou save 'our pro9ect
and run it at this time, 'our resu&ts shou&d be &i-e that o/ the 7igure be&o,C
%1
Figure 31: 2o"i(ie" Te8t>abel output using ?T2> (ormatting.
Tet+o
Our ne6t tas- is to &earn more about the >e6tbo6 contro& ,e 9ust used# Kou a&read'
-no, that it is used to &et the user enter a &ine o/ te6t input and return that input to the
program as a string# >e6tBo6 inherits its attributes /rom the Contro& c&ass and this c&ass
imp&ements a sing&e &ine te6t edit contro&# >his c&ass is creatab&e and is dec&ared asC
DIM h#extBox $S #extBox
>o create and instantiate a ne, >e6tBo6 contro& in 'our code, 'ou can use this /ormatC
h#extBox 6 !+ #extBox ( Parent $S Container )
Let's tr' something e&se# 2uppose that ,e ,ant to stream&ine our app&ication so that
the user does not have to c&ic- the update button ,hen the' enter te6t# A&so, it ,ou&d be nice
to have the te6t /ie&d c&ear itse&/ i/ the mouse entered the contro& area and to put bac- the
de/au&t prompt ,hen ,hen the mouse is moved a,a' /rom the contro&# <e ,ou&d ,ant to
preserve ,hatever ,as t'ped into the /ie&d b' the user ,hen the mouse &eaves the contro& so
,e have to remember to assign the va&ue that is current&' in the >e6tBo6"#>e6t /ie&d to the
>e6tLabe&"#>e6t /ie&d# <e ,ant to continue to use the =>1L4capab&e /ormat capabi&ities o/
the >e6tLabe&#
<e ,i&& need to modi/' our code# 7irst, ,e must create the event hand&ers /or the
mouse entering the contro& and &eaving the contro&# C&ic- once on the >e6tBo6" contro& on the
/orm and right4c&ic- the mouse to se&ect the Event item# 7rom the Event submenu choose
Enter# Repeat this process and choose the )eve event# :o,, go to the code editor, /ind the
/irst subroutine named &ext%oxOMEnter() and insert the /o&&o,ing code bet,een the /irst
and &ast &ineC
#extBox=.Clear
>hat's it /or this routine# <e 9ust ca&& the bui&t4in method to c&ear the >e6tBo6 and ,e are
done# :o,, ,e sti&& need to go to the >e6tBo6"LLeave( subroutine and enter this codeC
#extLabel=.#ext 6 ;U)iv ali5n6centerK UbK; S #extBox=.#ext S ;UMbK;
#extBox=.#ext 6 ;Unter text hereK;
>he /irst &ine o/ code ,i&& use =>1L to /ormat and center the >e6tBo6"#>e6t string and
set it to a bo&d/ace /ont# >he ne6t &ine o/ code assigns the de/au&t prompt string ,e initia&&'
created to the >e6tBo6"#>e6t so ,hen the mouse &eaves ,e have saved ,hatever the user t'ped
and reset it to ,hat it &oo-ed &i-e be/ore the mouse entered the contro&# 2ave 'our ,or- and
run the program to see ho, it ,or-s#
>here are not rea&&' an' >e6tBo64uni5ue 1ethods to discuss, but ,hi&e ,e are &earning
%2
about events, &et's p&a' around ,ith the code a &itt&e and &earn about the 2ho, and =ide
methods and ho, the' ma' be used in a program# C&ic- once on the /orm (be care/u& not to
c&icon an' contro& on the /orm and right4c&ic- the mouse to se&ect the Event item# 7rom the
Event submenu choose Mouse#own# Repeat this process and choose the #/lClick event#
:o,, go to the code editor, /ind the subroutine !or"MMouse#own() and insert the
/o&&o,ing code bet,een the /irst and &ast &ineC
Up)ateBtn.:i)e
>hat is a&& ,e need to do to hide the @pdateBtn contro&# +/ 'ou user opts not to use the
button no,, a&& the need to do is c&ic- the /orm and it ,i&& hide the button# =o, do ,e bring it
bac-N .oub&e4c&ic- ,i&& do the tric- nice&'# 7rom the code editor, /ind the
!or"M#/lClick() subroutine and enter this codeC
Up)ateBtn.ShoA
Right no,, 'ou ma' be as-ing 'ourse&/ !4ow would the user ever &now this;# Good
point# Let's &et them -no, ,ith a >oo&>ip propert'# C&icon the @pdateBtn contro&# :o, go
to the propert' ,indo, and /ind >oo&>ip# On the right side o/ that entr' is an input /ie&d and
,ith a gra' bo6 ,ith three dots (#### >hat means another dia&og ,i&& ta-e p&ace ,hen 'ou c&ic-#
+n this case, it ,i&& open an edit ,indo, so 'ou can /ormat 'our >oo&>ip using =>1L# C&icit
and ,hen the edit dia&og appears, enter this te6t (or code, as 'ou ,ishC
Click UbK (or )o-ble,click)UMbK on the *orm to hi)e UbK (or shoA) UMbK me
:o,, save 'our ,or- and run the program to see ho, it ,or-s# =over the mouse over
the @pdate Button and the nice&' /ormatted >oo&>ip ,i&& appear# +t shou&d &oo- &i-e the 7igure
be&o,# Coo&, huhN
>here are a coup&e o/ >e6tBo64uni5ue events ,e cou&d discuss at this point, name&'
KeyPress and Key+elese, but ,e are going to ho&d o// on those unti& &ater in the boo-
,hen ,e start ,or-ing ,ith the -e'board direct&'# Read' to move onN <e are going to add
some se&ector contro&s to our program ne6t# >he ComboBo6 and ListBo6 a&&o, users to se&ect
/rom among severa& choices# <e ,i&& start ,ith the ComboBo6 /irst#
%3
Figure 32: A""ing a
ToolTip to in(orm the user
ho. to sho.@hi"e a control.
Combo+o
>he ComboBo6 contro& inherits its attributes /rom the Contro& c&ass# +t imp&ements a
te6t bo6 combined ,ith a popup &ist bo6# >his c&ass is creatab&e and is dec&ared using the
/ormat be&o,C
DIM hComboBox $S ComboBox
>o instantiate the variab&e ,e 9ust dec&ared, use this /ormatC
hComboBox 6 !+ ComboBox ( Parent $S Container )
>his ,i&& create a ne, ComboBo6 contro&# >his c&ass acts &i-e a read4on&' arra'# +n
other ,ords, dec&aring the variab&e, instantiating it, and retrieving a va&ue /rom code direct&'
,ou&d ,or- &i-e thisC
DIM hComboBox $S ComboBox
DIM hComboBoxItem $S .ComboBoxItem
DIM In)ex as Inte5er
hComboBoxItem 6 hComboBox"In)ex%
>he &ine o/ code above ,i&& return a combo4bo6 item /rom its integer inde6# :ote that
the 1Co"/o%ox*te" represents an item in the combo4bo6 popup &ist4bo6# >his c&ass is
virtua&# Kou cannot use it as a data4t'pe and it is not creatab&e# +t has a sing&e propert', >e6t
,hich returns a string va&ue representing the ComboBo6 item represented b' +nde6# <e are
going to create a ComboBo6 on our /orm no,# =ere is ,hat our contro& ,i&& &oo- &i-eC
OE, i agree it is not ver' /anc' and it probab&' ran-s -ind o/ &o, on the creativit' &ist,
but it ,i&& get the 9ob done and teach 'ou ,hat 'ou need to -no, to use ComboBo6es# >o
bui&d our ne, contro&, ,e ,i&& go to the Gambas >oo&Bo6 and se&ect the ComboBo6 contro&#
P&ace it on the /orm (refer to our initial +igure at the very beginning of this chapter to see
where it should go and tr' to get it as c&ose to ,hat 'ou see in that picture as 'ou can# Once
'ou are done ,ith that, c&icon it once i/ 'ou do not see the hand&es and go to the Properties
<indo,#
%4
Figure 33: Aur
ombo=o8.
7ind the List propert'# >he input bo6 to the right o/ this ,i&& enab&e a se&ector dia&og i/ 'ou
c&ic- inside it# C&ic- the se&ector dia&og button (remember, ,ith the three dotsN and it ,i&&
bring up the Edit &ist propert' .ia&og sho,n in the /igure above#
>o insert an item in the &ist, t'pe the item in the >e6tBo6 at the bottom o/ the editor#
>he /irst item in the &ist is the de/au&t# +t is most o/ten used to set a de/au&t se&ection (&i-e
(one or 3ic& something, etc# +n our case, t'pe Pic- an item and c&ic- insert# Add +tem",
+tem;, +temD, and +tem ( to the &ist# 1a-e sure the' appear in the order sho,n in the 7igure
above so it ,i&& &oo- right ,hen it runs# Once 'ou have it set the ,a' 'ou ,ant, 9ust c&ic- the
OE button and the editor ,i&& c&ose and save 'our ,or-# 2ave 'our pro9ect and run the
program to see ,hat it &oo-s &i-e on 'our /orm# <hen 'ou have /inished &oo-ing at the ,or-
,e have done so /ar, e6it the program and ,e ,i&& continue b' adding some code to process
ComboBo6 se&ections#
+/ the user se&ects something /rom the ComboBo6, the item ,i&& change and this change
generates an event that 'ou can hand&e# 7rom the /orm, se&ect the ComboBo6 contro& and
right4c&ic-# Choose Event and se&ect Change /rom the submenu# :o,, go to the code editor
and /ind the subroutine P(%)*C $(% Co"/o%oxOMChnge()1 Add the code so the
subroutine &oo-s &i-e thisC
PUBLIC SUB ComboBox=8Chan5e()
DIM res-lt $S Strin5
res-lt 6 #rim(ComboBox=.#ext)
#extLabel=.#ext 6 res-lt S ; Aas selecte) *rom the ComboBox;
!D

2ave 'our pro9ect and run the program to see ,hat happens# :otice that ,hen an item
is se&ected the >e6tLabe&"#>e6t va&ue is updated but does not have an' /anc' /ormatting that it
is capab&e o/# <e&&, that is eas' to /i6# Let's change the code &i-e thisC
%#
Figure 3#: The -"it >ist Propert$ e"itor.
DIM res-lt $S Strin5
res-lt 6 ;U)iv ali5n6centerK UbK; S #rim(ComboBox=.#ext) S ;UMbK;
#extLabel=.#ext 6 res-lt S ; Aas selecte).;
!D
Change the code and run the program again# Kou shou&d see something simi&ar to this in the
>e6tLabe&" contro&C
2o the rea& programmers out there are a&read' as-ing ho, to do this ,ith code, ehN +
thought 'ou ,ou&d never as-S 2erious&', it is not hard# Let's modi/' our program s&ight&' to
a&&o, d'namica&&' add or remove items /rom the ComboBo6# >o do this, ,e are going to need
a button that ,i&& indicate adding an item and another button to remove an item# Add t,o
buttons, one ca&&ed P&usBtn and the other ca&&ed 1inusBtn to the /orm, as sho,n be&o,C
.oub&e4c&icon the P&usBtn and insert this codeC
PUBLIC SUB Pl-sBtn8Click()
DIM Item $S Strin5
DIM !-mItems $S Inte5er
ComboBox=.'e*resh
!-mItems 6 ComboBox=.Co-nt
I1 !-mItems 6 9 #:!
Item 6 ;Pick an Item;
LS
Item 6 ;Item ; S Str(!-mItems)
!DI1
ComboBox=.'e*resh
ComboBox=.$))(Item0!-mItems)
!D
+n the code above, ,e dec&are t,o variab&es, .tem and (um.tems# +tem is a string and
:um+tems an +nteger# <e ,i&& use :um+tems to determine ho, man' items are a&read' in
the &ist# >his is done using the 1Count propert'# +/ there are no items in the &ist, ,e ,i&& set
our de/au&t prompt o/ APic- an +temB as +tem 0ero#
%8
Figure 3%: Formatting a Te8t>abel .ith ?T2>.
Figure 3): 5sing plus an" minus
buttons to alter the ombo=o8 list.
ComboBo6 arra's are 0ero4based, meaning the counting starts at 0ero, not one# +t the
:um+tems va&ue is 0ero ,e ,i&& create a de/au&t string# Other,ise, ,e are going to concatenate
the item number to the ,ord +tem so it ,i&& add to the ne6t open s&ot in the &ist# <e ca&& the
Re/resh method to /orce the ComboBo6 to re/resh its count propert' so i/ the user tries to
se&ect again it ,i&& be current# >he &ast &ine o/ code uses the #Add method to add the item to
the ComboBo6 item &ist# :o,, doub&e4c&icon the 1inusBtn and add this codeC
PUBLIC SUB Min-sBtn8Click()
DIM !-mItems $S Inte5er
T#he combobox array starts at Rero
ComboBox=.'e*resh
!-mItems 6 ComboBox=.Co-nt
I1 !-mItems K 9 #:!
DC !-mItems
I1 !-mItems UK 9 #:!
ComboBox=.'emove(!-mItems)
!DI1
ComboBox=.'e*resh
!DI1
!D
Removing e&ements /rom the &ist is much simp&er# <e on&' need an integer variab&e to
determine the number o/ e&ements in the &ist# Once again, this is done using the #Count
propert'# +n our e6amp&e, Count ,i&& return a va&ue o/ G the /irst time it is read# +/ there are
no items in the &ist, ,e ,i&& not do an'thing# Because the ComboBo6 items are stored in a
0ero4based arra', ,e must decrement the count b' one i/ it is not a&read' 0ero# :o,, save
'our pro9ect and run the program# >r' removing a&& the items in the &ist and re4inserting
them# Coo&, ehN 1ore coo& stu// to come ,ith the ListBo6, ,hich ,e discuss ne6t#
&ist+o
>he ListBo6 contro& a&so inherits its attributes /rom the Contro& c&ass# >he ListBo6
imp&ements a &ist o/ se&ectab&e te6t items# >his c&ass is creatab&e# >he /o&&o,ing code ,i&&
dec&are a ListBo6 and create itC
DIM hListBox $S ListBox
hListBox 6 !+ ListBox ( Parent $S Container )
Li-e the ComboBo6, this c&ass acts &i-e a read4on&' arra'#
DIM In)ex as Inte5er
DIM hListBox $S ListBox
DIM hListBoxItem $S .ListBoxItem
%?
hListBoxItem 6 hListBox"In)ex%
>he &ine o/ code above ,i&& return a ListBo6 item /rom its integer inde6# :ote that the
1)ist%ox*te" represents an item in the ListBo6 popup &ist4bo6# >his c&ass is virtua&# Kou
cannot use it as a data4t'pe and it is not creatab&e# +t has a sing&e propert', >e6t ,hich
returns a string va&ue representing the ListBo6 item represented b' +nde6# <e are going to
create a ListBo6 on our /orm no,# =ere is ,hat our ne, contro& ,i&& &oo- &i-eC
+n order to bui&d our ne, contro&, ,e ,i&& go to the Gambas >oo&Bo6 and se&ect the
ListBo6 contro&# P&ace it on the /orm (refer to our initial picture at the very beginning of this
chapter to see where it should go and tr' to get it as c&ose to ,hat 'ou see in that picture as
'ou can# Once 'ou are done ,ith that, c&icon it once i/ 'ou do not see the hand&es and go to
the Properties <indo,# 7ind the List propert'# >he input bo6 to the right o/ this ,i&& enab&e a
se&ector dia&og i/ 'ou c&ic- inside it# C&ic- the se&ector dia&og button (remember, ,ith the three
dotsN and it ,i&& bring up the Edit &ist propert' .ia&og (sho,n be&o,#
>his is e6act&' the same editor ,e used to bui&d the ComboBo6" contro&# >his time, ,e
are going to add items to the &ist and a&so &earn about the 2'stem c&ass# >he 2'stem c&ass is
part o/ the Gambas co"ponent &ibrar' and provides support /or a&& the c&asses inc&uded in
the interpreter b' de/au&t#
%%
Figure 3*: What our
>ist=o8 .ill loo3 li3e.
Figure 3/: The >ist=o8 e"it list propert$ e"itor.
>he 2'stem c&ass is static and provides read4on&' in/ormation about the operating
s'stem environment# >he properties o/ this c&ass that 'ou can read inc&ude Charset, .omain,
=ome, =ost, Language, Path, and @ser# @se the editor and enter the /o&&o,ing items in the
&istC
Charset
.omain
=ost
Language
Path
@ser
:e6t, doub&e4c&icon the ListBo6" contro& on the /orm# >his ,i&& ta-e 'ou to the code
editor and 'ou shou&d be in the P(%)*C $(% )ist%oxOMClick() subroutine# >he /o&&o,ing
code ,i&& sho, 'ou ho, to access these va&ues# Enter it as /o&&o,sC
PUBLIC SUB ListBox=8Click()
I1 #rim(ListBox=.#ext) 6 ;System.Charset; #:!
#extLabel=.#ext 6 System.Charset
LS I1 #rim(ListBox=.#ext) 6 ;Domain; #:!
#extLabel=.#ext 6 System.Domain
LS I1 #rim(ListBox=.#ext) 6 ;:ost; #:!
#extLabel=.#ext 6 System.:ost
LS I1 #rim(ListBox=.#ext) 6 ;Lan5-a5e; #:!
#extLabel=.#ext 6 System.Lan5-a5e
LS I1 #rim(ListBox=.#ext) 6 ;Path; #:!
#extLabel=.#ext 6 System.Path
LS I1 #rim(ListBox=.#ext) 6 ;User; #:!
#extLabel=.#ext 6 User.:ome
!DI1
!D
:o,, save 'our pro9ect and run the program# >r' se&ecting a&& the items in the &ist and
see ,hat in/ormation is returned# Lists and ComboBo6es are ver' eas' to imp&ement and use#
A great advantage o/ using these t'pes o/ se&ector components is that it virtua&&' e&iminates the
possibi&it' o/ a user t'ping data incorrect&'# +n the ne6t section, ,e are going to &earn ho, to
organi0e the contro&s on our /orm to better manage the presentation to contro&s to the user#
A&so, ,e ,i&& &earn ,h' /rames and pane&s are a good thing to consider ear&' in the
deve&opment process#
-rame
>he 7rame c&ass inherits its attributes /rom the Container c&ass# >his contro& is a
container ,ith an etched border and a &abe&# >his c&ass is creatab&e# .o dec&are and
%+
instantiate a 7rame, use this /ormatC
DIM h1rame $S 1rame
h1rame 6 !+ 1rame (Parent $S Container)
>he great thing about a /rame is that it ,or-s sort o/ &i-e a ,indo, ,ithin a ,indo,#
An' contro& 'ou p&ace in the /rame becomes a part o/ the /rame, in a manner o/ spea-ing#
<hat this means is that i/ 'ou put Chec-Bo6 contro&s or buttons or ,hatever in the /rame and
decide to move the /rame, the' a&& move ,ith it# >he' can be rearranged ,ithin the /rame, but
i/ the /rame moves, hides, etc#, so do the'# =ere is ,hat our /rame and the contro&s ,e ,i&&
add to it &oo- &i-eC
>o continue deve&opment o/ our pro9ect, ,e ,i&& /irst add a !r"e contro& to the /orm
(name it 7rame" and p&ace it simi&ar to that /ound in the 7igure at the beginning o/ this
chapter# :e6t, ,e ,i&& add t,o &oggle%utton contro&s (named >ogg&eButton" and
>ogg&eButton; and three Check%ox contro&s (named Chec-Bo6", Chec-Bo6;, and
Chec-Bo6D# Arrange them to &oo- &i-e the /igure above# Once 'ou have ever'thing p&aced
correct&' on the /orm, &et's go to the ne6t step and ,rite code /or the events ,e ,i&& respond to
in our program#
Togg*e+utton
>he >ogg&eButton contro& inherits its attributes /rom the Contro& c&ass and imp&ements
a togg&e button# >his means it either togg&es up or do,n# >his c&ass is creatab&e# >o dec&are
and instantiate this contro&, use the /ormatC
DIM h#o55leB-tton $S #o55leB-tton
h#o55leB-tton 6 !+ #o55leB-tton ( Parent $S Container )
.oub&e4c&icon the >ogg&eButton" contro& and add this code to the P(%)*C $(%
&oggle%uttonOMClick() subroutineC
PUBLIC SUB #o55leB-tton=8Click()
I1 #o55leB-tton=.(al-e 6 #'U #:!
+0
Figure 30: What the e8ample (rame .e
buil" .ill loo3 li3e.
1rame=.#ext 6 ;#o55le) = )oAn;
LS
1rame=.#ext 6 ;#o55le) = -p;
!DI1
!D
Repeat the previous step /or the >ogg&eButton; contro& and enter this codeC
PUBLIC SUB #o55leB-ttonB8Click()
I1 #o55leB-ttonB.(al-e 6 #'U #:!
1rame=.#ext 6 ;#o55le) B )oAn;
LS
1rame=.#ext 6 ;#o55le) B -p;
!DI1
!D
<hat ,e have done ,ith the code above is chec- the >ogg&eButton#!a&ue propert' to
see i/ it is >R@E, indicating that the button ,as c&ic-ed do,n# +/ 7AL2E, another c&ic- togg&ed
it to the up position# Regard&ess o/ the position it is at, ,e ,ant the 7rame"#>e6t to disp&a' the
status o/ the button &ast c&ic-ed# :o,, &et's move on to &earn about the Check%ox contro&s#
Checkbo
>he Chec-Bo6 c&ass inherits its attributes /rom the Contro& c&ass# >his c&ass
imp&ements a chec-4bo6 contro& and it is creatab&e# .ec&are and instantiate the variab&e &i-e
thisC
DIM hCheckBox $S CheckBox
hCheckBox 6 !+ CheckBox ( Parent $S Container )
<hen a Chec-Bo6 contro& is c&ic-ed in our program, ,e ,ant to detect the c&ic- event
and immediate&' respond# +n this case, ,e ,i&& change the Chec-bo6#>e6t propert' ,henever
the Chec-Bo6#!a&ue is chec-ed and turns out to be >R@E# >his ,i&& sho, that ,e caught the
c&ic- event and responded to the va&ue o/ >R@E or 7AL2E (chec-ed or unchec-ed# +/ the bo6
is unchec-ed, ,e ,i&& ,ant to return it to the !(ormal# state# 7or Chec-Bo6", doub&e4c&icon
the contro& and enter this code in the code editor /or the P(%)*C $(% Check%oxOMClick()
subroutineC
PUBLIC SUB CheckBox=8Click()
I1 CheckBox=.(al-e 6 #'U #:!
Checkbox=.#ext 6 ;I Aas picke);
LS
Checkbox=.#ext 6 ;Checkbox=;
+1
!DI1
!D
Repeat this process /or Check%oxB and Check%oxPC
PUBLIC SUB CheckBoxB8Click()
I1 CheckBoxB.(al-e 6 #'U #:!
CheckboxB.#ext 6 ;I Aas picke);
LS
CheckboxB.#ext 6 ;CheckboxB;
!DI1
!D
PUBLIC SUB CheckBox/8Click()
I1 CheckBox/.(al-e 6 #'U #:!
Checkbox/.#ext 6 ;I Aas picke);
LS
Checkbox/.#ext 6 ;Checkbox/;
!DI1
!D
:o,, save 'our pro9ect and run the program# Once 'ou have satis/ied 'ourse&/ that the'
,or- as ,e p&anned, end the program and ,e ,i&& continue our pro9ect b' adding the &ast t,o
contro&s that ,e are going to cover in this chapter, the Pnel and +dio%utton#
Pane*
>he Pane& c&ass inherits its attributes /rom the Container c&ass# >his c&ass imp&ements a
Pane& contro& ,ith a changeab&e border# >his c&ass is creatab&e# .ec&are and instantiate a
pane& &i-e thisC
DIM hPanel $S Panel
hPanel 6 !+ Panel ( Parent $S Container )
<e ,i&& /irst need to add a Pane& contro& to the /orm (name it Pane&" and p&ace it to
&oo- &i-e the Pane& /ound at the beginning o/ this chapter# :e6t, ,e ,i&& add t,o RadioButton
contro&s (named RadioButton" and RadioButton;# Arrange them to &oo- &i-e the /igure
sho,n be&o,# +n our program, ,e are going to use the Pane& to group our RadioButtons inside
it# =ere is ,hat this pane& ,i&& &oo- &i-e ,hen ,e are /inishedC
+2
(adio+utton
>he RadioButton c&ass inherits its attributes /rom the Contro& c&ass and is used to
imp&ement a radio button contro&# RadioButton contro&s that share the same parent (in this
case, the Pane& container are mutua&&' e6c&usive# On&' one RadioButton can be se&ected at
once# >he RadioButton c&ass is creatab&e so 'ou can dec&are and instantiate the RadioButton
&i-e thisC
DIM h'a)ioB-tton $S 'a)ioB-tton
h'a)ioB-tton 6 !+ 'a)ioB-tton ( Parent $S Container )
2e&ect the RadioButton contro& /rom the >oo&Bo6 and p&ace it on the /orm# :ame the
/irst RadioButton RadioButton" and repeat this process /or another, named RadioButton;#
Once 'ou have ever'thing p&aced correct&' on the /orm, &et's go to the ne6t step and ,rite
code# .oub&e4c&icon the /irst RadioButton and enter this codeC
PUBLIC SUB 'a)ioB-tton=8Click()
'a)ioB-tton=.#ext 6 ;:a:a 'BB;
'a)ioB-ttonB.#ext 6 ;'a)ioB-ttonB;
!D
Repeat this process /or the second oneC
PUBLIC SUB 'a)ioB-ttonB8Click()
'a)ioB-ttonB.#ext 6 ;:a:a 'B=;
'a)ioB-tton=.#ext 6 ;'a)ioB-tton=;
!D
:o,, save 'our pro9ect and run the program# +t shou&d resemb&e the /igure be&o,C
+3
Figure #1: A Panel control
containing Ba"io=uttons.
Once 'ou have satis/ied 'ourse&/ that ever'thing ,e have done in this chapter ,i&& ,or- as ,e
p&anned, ta-e a ,e&& deserved brea- and ,e ,i&& start /resh on the ne6t chapter#
+4
Figure #1: Thir" Project (inal results.
Chapter ( )enus* )odues* +iaogs and
)essage #o$es
A&most ever' G@+4based program 'ou encounter ,i&& use some combination o/ menus,
1essageBo6es, and standard dia&ogs to communicate ,ith the user# Gambas is not an'
di//erent# Additiona&&', there is no programming &anguage that provides ever'thing that a
programmer ,ou&d use as a pre4bui&t component# >hat is ,hat modu&es are used /or ,riting
,hat 'ou need outside the scope o/ ,hat Gambas provides# 7or e6amp&e, i/ 'ou need a
/unction that returns the name o/ a co&or based on ,hat is chosen in a standard co&or se&ection
dia&og, 'ou are going to have to ,rite one, and ,e ,i&& do 9ust that in our ne6t samp&e pro9ect#
+n this chapter, ,e ,i&& &earn ho, to use each o/ these contro&s and bui&d another e6amp&e
program to he&p 'ou &earn to master Gambas# =ere is a screenshot o/ the /ina& version o/ ,hat
our pro9ect ,i&& &oo- &i-eC
<e are going to create /our menus# Each menu ,i&& be used to demonstrate the
contro&s or standard dia&ogs ,e are going to &earn about in this chapter# <e ,i&& /irst bui&d the
menu, as sho,n above, then ,e ,i&& sho, 'ou ho, to use the standard co&or and /i&e dia&ogs,
1essageBo6es, and, as an added bonus, ,e ,i&& sho, 'ou ho, to create a modu&e in Gambas
and use it# >o begin our pro9ect, open Gambas and /rom the ,i0ard, in the A>'peB co&umn,
se&ect AH> graphica& app&icationB# :ame it 1enuPro9ect and chec- A+nternationa&i0ationB#
Once 'ou get to the +.E, doub&e4c&icon 71ain#
.oub&e4c&icon the /orm an',here outside a contro& boundar' and 'ou ,i&& get the
71ain#c&ass page# +mmediate&' a/ter '5ambas class file, t'pe
Color!ame $S Strin5
>his dimensions the g&oba& variab&e Co&or:ame#
>he dec&aration o/ the P(%)*C $(% !or"MOpen() subroutine appeared automatica&&' in
the code editor# +nsert this code in that empt' subroutineC
+#
Figure #2: 2enu project (inal result.
M.Caption 6 ; +orkin5 Aith Men-s ;
Add a Huit Button to the /orm, as sho,n above and enter this code to be e6ecuted ,hen a user
c&ic-s the Huit buttonC
1Main.Close
!D
:e6t, add a >e6tLabe&, named >e6tLabe&" to the ,indo, as sho,n in the 7igure above#
>hat ta-es care o/ the pre&iminaries /or our pro9ect# :o,, &et's see ho, to bui&d the menu and
use the standard dia&ogs provided b' Gambas#
The Gambas 2enu Editor
Gambas has a bui&t4in 1enu Editor# Kou can access it /rom the /orm ,indo, b'
pressing C&+).E or b' right4c&ic-ing on the /orm and se&ecting the 1enu Editor option /rom
the popup that appears# Either ,a', the 1enu Editor ,i&& appear as sho,n above#
<hen 'ou /irst start the 1enu Editor, the editor ,indo, ,i&&, o/ course, be b&an-# +t is
not an intuitive&' obvious too& to use, so &et's spend a minute to e6p&ain the 1enu Editor#
7irst, some common termino&og'# >he te6t that 'ou see running hori0onta&&' across the top o/
a /orm is re/erred to as a menu#
A menu can contain 1enu+tems (,hich are &isted vertica&&' be&o, the menu#
+8
Figure #3: The Gambas 2enu -"itor .hen it starts.
1enu+tems can contain sub1enus, ,hich are basica&&' ne, nested menus that be&ong to a
1enu+tem and ,i&& popup and disp&a' another &ist o/ 1enu+tems# 1enus can contain severa&
&a'ers o/ nested sub1enus#
>o insert a menu 'ou ,i&& have to use the *nsert button# >he Next button ,i&& move
the current menu cursor position to the ne6t item in the ,indo,# +t on&' moves do,n and
there is no previous button# +/ 'ou reach the end o/ the &ist, it ,i&& stop and the on&' thing 'ou
can do is c&ic- the mouse on a menu entr' or insert a ne, one# >he #elete button ,i&&
remove the menu entr' under the menu cursor#
>he /irst t,o and arro, buttons (up and do,n to the right o/ the .e&ete button
,i&& move the entr' under the menu cursor up or do,n the &ist o/ menu entries# +/ 'ou c&ic-
the or (un4indent or indent arro, buttons, the process ,i&& ,or- much &i-e indentation
in an out&ine ,or-s# >he indented item ,i&& become either a 1enu+tem or sub1enu+tem
depending on the &eve& o/ indentation#
+ndented items ,ith an e&&ipsis (three 111 preceding the name indicate 1enu+tems#
1ore than three dots preceding the name indicates it is a sub1enu+tem o/ the entr' at the
previous indentation &eve&# Once 'ou bui&d a menu or t,o, it ,i&& be eas' to understand#
<hen 'ou c&ic- the insert button, 'ou ,i&& see severa& ne, /ie&ds appear at the bottom o/
the 1enu Editor\ >he N"e /ie&d shou&d probab&' have been ca&&ed <ariable :ame because
that is ,hat this /ie&d is used /or# >his is the variab&e name that 'our code in the c&ass /i&e ,i&&
use to re/erence this particu&ar ob9ect#
>he Froup /ie&d re/ers to a Control Froup1 Contro& Groups are used in the Gambas
+.E to create and hand&e groups o/ contro&s as a sing&e entit'# <hen 'ou se&ect an' contro& on
a /orm, in the Properties dia&og, 'ou shou&d notice a Group propert' that doesn't correspond
to an' documented propert' o/ that contro&# >his specia& pseudo2property a&&o,s 'ou to assign
contro& groups# Essentia&&', ,hen that contro& is created at run4time, it ,i&& be treated as
+?
Figure ##: -"iting menu entries in the 2enu -"itor.
though 'ou had created it in code &i-e soC
myControl 6 !+ Col-mn(ieA(M) $S ;my.ro-p;
and its event hand&ers must be named &i-e soC
PUBLIC SUB my.ro-p8Click()
Kou can re/er to the contro& that generated the event ,ith the ),$& -e',ord, or 'ou
can assign a &g to each contro& to di//erentiate them b' using the tag va&ue#
Cption is the te6t that the end4user ,i&& see ,hen the program runs# &g is reserved
/or programmers to store data and is a common propert' /or near&' a&& contro&s# <e ,i&& cover
ho, to use the >ag propert' &ater# 7or no,, 'ou on&' need to -no, that it can contain A:K
!ariant t'pe data#
>he $hortcut Chec-Bo6es a&&o, 'ou to de/ine -e'board shortcut -e' combinations
&i-e Contro&4A to automatica&&' invo-e the c&ic- event /or that menu entr'# Remember, menu
entries basica&&' on&' respond to c&ic- events or -e'board shortcuts# >he Picture /ie&d a&&o,s
'ou to speci/' the /i&e name o/ an icon that ,i&& disp&a' ,ith the menu entr'# A previe,
,indo, (a#-#a#, a picture bo6 appears to the right o/ this /ie&d#
>he Chec-Bo6es to the right o/ the input /ie&ds, 'isi/le, En/led, and Checked re/er
to the state o/ the menu entr'# B' de/au&t, a&& menu entries are created to be enab&ed and
visib&e# Kou can speci/' i/ the item is chec-ed or not# +n code, 'ou can see i/ the entr' is
chec-ed or not b' &oo-ing at the menu entr''s Checked propert'# +t ,i&& return a >R@E or
7AL2E va&ue indicating the status o/ the item# =ere is an e6amp&e o/ ho, to togg&e a
chec-mar- on or o// ,hen a menu item is pic-edC
I1 Men-BItem=.Checke) #:!
Men-BItem=.Checke) 6 1$LS
LS
Men-BItem=.Checke) 6 #'U
!DI1
>he +7 statement ,i&& test the Chec-ed propert' o/ the 1enu;+tem" ob9ect and i/ the
Boo&ean va&ue is >R@E ,i&& set it to 7AL2E (togg&ing it# +/ the Boo&ean va&ue is :O> >R@E
the EL2E c&ause is e6ecuted, togg&ing the #Chec-ed va&ue to >R@E# >his &ogic can be used to
togg&e an' menu or sub1enu+tem#
A word of caution * use this (eature sparingl$ (or goo" G5+ "esign. 2an$ users (eel
o'er.helme" .hen the$ are presente" .ith too much ga"getr$ in an inter(ace.
+%
@ser inter/ace design has been a topic o/ considerab&e research, inc&uding on its
aesthetics# +n the past, standards have been deve&oped, as /ar bac- as the eighties, /or de/ining
the usab&it' o/ so/t,are products# >he +nternationa& 7ederation /or +n/ormation Processing
(+7+P user inter/ace re/erence mode& is o/ten used in @+ design# >he mode& proposes /our
dimensions to structure the user inter/aceC
>he inputMoutput dimension (the &oo-
>he dia&ogue dimension (the /ee&
>he technica& or /unctiona& dimension (the access to too&s and services
>he organi0ationa& dimension (the communication and co4operation support
>his mode& has great&' in/&uenced the deve&opment o/ the internationa& standard +2O
);(" describing the inter/ace design re5uirements /or usabi&it'# A /undamenta& rea&it' o/
app&ication deve&opment is that the user inter/ace is the primar' s'stem to the users# <hat
users need is /or deve&opers to bui&d app&ications that meet their needs and that are eas' to
use#
>oo man' deve&opers thin- that the' are artistic geniuses the' do not bother to /o&&o,
user inter/ace design standards or invest the e//ort to ma-e their app&ications usab&e, instead
the' mista-en&' be&ieve that the important thing is to ma-e the code c&ever or to use a rea&&'
interesting co&or scheme# :ot soS @ser inter/ace design is important /or severa& reasons#
7irst o/ a&&, the more intuitive the user inter/ace, the easier it is to use, and the easier it is to
use, the &ess e6pensive it is to support it# A good user inter/ace ma-es it easier it is to train
peop&e to use it, reducing 'our training costs# >he better 'our user inter/ace the more 'our
users ,i&& &i-e to use it, increasing their satis/action ,ith the ,or- that 'ou have done#
+ui*ding 2enus
:o,, &et's create our menu# <hen 'ou are /inished, it ,i&& &oo- something &i-e the
/igure sho,n be&o, ,hich is a screenshot ta-en /rom the menu editor# >he 1enu Editor is
avai&ab&e on&' ,hen a /orm is being designed#
>he /irst step in creating a menu is to enter the menu item's Zvariab&e[ name and it's
caption to be disp&a'ed to the user# >he caption can incorporate the ampersand (P /or an
access -e' designation, a&so -no,n as an acce&erator -e'# >his enab&es the user to see an
under&ined &etter in the menu and use the A&t -e' a&ong ,ith the acce&erator -e'#
++
>o begin, c&ic- the *nsert button# 7irst, ,e ,i&& insert the top4&eve& menus, Co&or.ia&og,
1essageBo6es, 7i&e.ia&ogs, and =e&p# >o ma-e this eas', use the tab&es be&o, to /i&& in the
input /ie&d dataC
Min Menu ('ri/le) N"e Froup Cption
0o(or8ia(og 9enu" 0o(or8ia(og
9essageBo;es 9enu2 9essageBo;es
2i(e8ia(ogs 9enu3 2i(e8ia(ogs
,e(p 9enu? ,e(p
:o,, &et's put the menu items into the /irst menu# >hese menu items ,i&& be&ong to the
Co&or.ia&og menuC
Color#ilog ('ri/le) N"e Froup Cption
2oreground 0o(or 9enu"4tem" 2oreground 0o(or
Background 0o(or 9enu"4tem2 Background 0o(or
2ont 9enu"4tem3 2ont
100
Figure #%: The Gambas 2enu -"itor.
A/ter 'ou have inserted these items ,ith the editor, ensure the' are positioned be&o, the
Co&or.ia&og entr' and indented one &eve&#
:o,, move the menu cursor over the second main menu entr', 1essageBo6es and ,e
,i&& insert the menu items /or this menu#
Messge%oxes ('ri/le) N"e Froup Cption
4n+o 9essage 9enu24tem" 4n+o 9essage
A(ert 9essages 9enu24tem2 A(ert 9essages
5rror 9essage sub9enu4tem" 5rror 9essage
$arning 9essage sub9enu4tem2 $arning 9essage
8e(ete 9essage sub9enu4tem3 8e(ete 9essage
Cuestion 9essage 9enu24tem3 Cuestion 9essage
Ensure the Error, <arning, and .e&ete entries are indented &-O &eve&s be&o, the menu
entr' /or A&ert 1essages#
>he /o&&o,ing menu items be&ong to the 7i&e.ia&ogs menu#
!ile#ilogs ('ri/le) N"e Froup Cption
/pen 2i(e%%% 9enu34tem" /pen 2i(e%%%
7a)e 2i(e%%% 9enu34tem2 7a)e 2i(e%%%
7e(ect 8ir 9enu34tem3 7e(ect 8ir
:o,, the &ast menu item /or the =e&p menu needs to be added#
6elp ('ri/le) N"e Froup Cption
About 9enu? About
>hat's a&& there is to itS C&ic- the OE button to &eave the menu editor and ,hen 'our return to
the /orm, a menu ,i&& be there# +/ it does not &oo- &i-e our e6amp&e, go bac- to the menu
editor and ad9ust the entries unti& it does# A/ter 'ou are comp&ete&' satis/ied ,ith the menu's
/ormat and appearance, the ne6t step is to code actions /or each menu c&ic- event# =o,ever,
be/ore ,e do that, ,e need to &earn about the standard dia&ogs and 1essageBo6es that are
provided in Gambas#
!ia*ogs
>he .ia&og c&ass is used to imp&ement a&& o/ the Gambas standard dia&ogs# >his c&ass
contains static methods used to ca&& the standard dia&og bo6es# >his c&ass is static# >he .ia&og
101
methods supported (i.e., the standard dialogs) areC Open7i&e, 2ave7i&e, 2e&ectCo&or,
2e&ect.irector', and 2e&ect7ont# >he properties supported b' this c&ass areC Co&or, 7i&ter,
7ont, Path, and >it&e#
Co&or is an integer va&ue that the 2e&ectCo&or .ia&og returns representing the co&or
se&ected# +t is interesting to note that Gambas has D; prede/ined co&or constants but the
standard 2e&ectCo&or .ia&og consists o/ (* co&ors# >his means 'ou cannot use the prede/ined
constants &i-e Red, B&ac-, etc#, ,ith an' sense o/ suret' in a CA2E statement or e&se,here#
<hen a co&or is chosen, ho, do 'ou determine i/ it is a prede/ined constant or another co&or
outside the range o/ the D; prede/ined in GambasN Kou ,rite a modu&e to determine that, o/
courseS <e ,i&& come bac- to this topic a/ter e6p&aining ho, to use the 2e&ectCo&or .ia&og#
<hen ,or-ing ,ith the /i&e4re&ated .ia&ogs, the 7i&ter and Path properties are returned#
7i&ter is de/ined as $&,&*C P+OPE+&3 !ilter ,$ $tring25 and it returns or sets the /i&ters
(i.e., categori6e by file etension, such as all .doc or .png files used in the standard /i&e
dia&ogs# >his propert' returns or receives a string arra'# Each e&ement in the arra' represents
one /i&ter to use ,hen the /i&e dia&og ca&& is made# Each /i&ter string must /o&&o, the /o&&o,ing
s'nta6C
>he /i&ter name#
A space#
An opening brac-et#
One or more /i&e patterns, separated b' semico&ons#
A c&osing brac-et#
=ere is an e6amp&e that a&so demonstrates the use o/ the .ia&og >it&e propert'C
Dialo5.#itle 6 ;Choose a *ile;
Dialo5.1ilter 6 ";Pict-res (L.pn5GL.3p5GL.3pe5);0;$ll *iles (L.L);%
Dialo5.2pen1ile
>he /i&e4re&ated .ia&og ca&&s (2e&ect.irector', Open7i&e .ia&og and 2ave7i&e .ia&og a&&
return the Path propert', ,hich is a string that contains the /i&epath se&ected# +n the case o/
the 2e&ect.irector' .ia&og ca&&, the string is truncated at the director' &eve&# :o,, &et's start
coding our /irst menu item, 7oreground Co&or#
7rom the /orm ,indo,, choose the 7oreground Co&or item /rom the menu ,e 9ust bui&t
and 'ou ,i&& be ta-en to the code ,indo, in a subroutine ca&&ed P(%)*C $(%
MenuO*te"OMClick() ,here 'ou ,i&& ,ant to insert this codeC
PUBLIC SUB Men-=Item=8Click()
Dialo5.#itle 6 ;Choose a *ore5ro-n) color;
Dialo5.SelectColor
#extLabel=.1ore5ro-n) 6 Dialo5.Color
#extLabel=.#ext 6 ;UbKColor selecte) AasUMbK ; S Color!ame S ;.;
102
!D
7irst, ,e set the >it&e o/ the .ia&og to AChoose a foreground colorB so the user has some
idea o/ ,hat the .ia&og is used /or# <e ca&& the standard dia&og ,ith #ilog1$electColor1
Once the user has pic-ed a co&or or cance&ed /rom the dia&og, ,e ,i&& p&ace the name o/
the co&or returned in the >e6tLabe&"#>e6t contro& ,e created at the beginning o/ our pro9ect#
<e choose the >e6tLabe& because it a&&o,s us to /ormat our output &i-e thisC
#extLabel=.#ext 6 ;UbKColor selecte) AasUMbK ;SStr[(Dialo5.Color) S ; .;
>he &ine o/ code above ,i&& set to bo&d/ace the AColor selected wsB part o/ the string,
concatenate the Co&or va&ue to the string a/ter converting the integer to a string using the $tr7
conversion /unction, and then concatenate the terminating punctuation to the string (we do
want it to loo& professional, don$t we;#
:o, run the code and 'ou shou&d see something &i-e thisC
<e&&, ;"JI$ is not ver' use/u& in/ormation# >his number is the interna& representation
o/ that greenish co&or that ,as se&ected# <e need to deve&op some method o/ -no,ing i/ the
co&or is red, b&ue, green, i#e#, a named co&or constant# >his is ,hat ,e ,ere a&&uding to in the
previous section about the prob&em ,ith co&ors# =ere is ,here modu&es come into p&a'#
2odu*es
<e are going to create a modu&e to return the name o/ a co&or i/ it is a prede/ined
constant# +/ not, ,e ,ant a string that te&&s us it is not a prede/ined co&or constant# Once ,e
de/ine our modu&e, ,e ,i&& come bac- and modi/' our code to use the modu&e# 7rom the
Pro9ect ,indo,, /ind 1odu&es in the >reevie, and se&ect a ne, modu&e, named 1odu&e"#
<hen the dia&og appears, &eave the Chec-Bo6es b&an- and 9ust ta-e the de/au&t name and c&ic-
OE# Kou ,i&& be presented ,ith a ne, code ,indo, tit&ed 1odu&e"#modu&e# +t shou&d start
out ,ith a comment &i-e thisC
103
Figure #): A (ormatte" te8t label "ispla$ing the color
'alue.
T .ambas mo)-le *ile
:o,, ,e ,i&& ,rite a&& the code /or our /unction, ,hich ,e ,i&& ca&& 2etCo&or:ame#
7irst, ,e must dec&are the /unction and identi/' ,hat input and output parameters it ,i&&
process# =ere is ho, ,e do thatC
PUBLIC 1U!C#I2! SetColor!ame ( i(al $S Inte5er) $S Strin5
<e dec&are a pub&ic 7unction that ta-es an integer parameter and returns a string
va&ue# >his modu&e ,i&& ta-e the integer va&ue that the 2e&ectCo&or .ia&og has returned and
chec- it against the D; prede/ined co&or constants used in Gambas# +/ it matches a prede/ined
co&or constant, ,e ,i&& set a temporar' string to the name o/ that co&or# +/ not, ,e ,i&& create a
string that identi/ies the constant va&ue and return that to the ca&&ing code# <e ,i&& need to
create a temporar' string variab&e to do this, so add this variab&e dec&aration as the /irst &ine o/
code inside the /unctionC
DIM rval $S Strin5
:o,, ,e have to add our CA2E 2ELEC> statement# +t ,i&& use the integer parameter
i!a& that is passed into the /unction /rom the ca&&ing subroutine# =ere is the /u&& &isting /or 'ou
to enterC
T$ll DIM )eclarations m-st be in the 1U!C#I2! or SUB be*ore the *irst exec-table comman).
DIM rval $S Strin5
SLC# i(al
C$S Color.Black
rval 6 ;Black;
C$S Color.Bl-e
rval 6 ;Bl-e;
C$S Color.Cyan
rval 6 ;Cyan;
C$S Color.DarkBl-e
rval 6 ;DarkBl-e;
C$S Color.DarkCyan
rval 6 ;DarkCyan;
C$S Color.Dark.ray
rval 6 ;Dark.ray;
C$S Color.Dark.reen
rval 6 ;Dark.reen;
C$S Color.DarkMa5enta
rval 6 ;DarkMa5enta;
104
C$S Color.Dark'e)
rval 6 ;Dark'e);
C$S Color.DarkWelloA
rval 6 ;DarkWelloA;
C$S Color..ray
rval 6 ;.ray;
C$S Color..reen
rval 6 ;.reen;
C$S Color.Li5ht.ray
rval 6 ;Li5ht.ray;
C$S Color.Ma5enta
rval 6 ;Ma5enta;
C$S Color.2ran5e
rval 6 ;2ran5e;
C$S Color.Pink
rval 6 ;Pink;
C$S Color.'e)
rval 6 ;'e);
C$S Color.#ransparent
rval 6 ;#ransparent;
C$S Color.(iolet
rval 6 ;(iolet;
C$S Color.+hite
rval 6 ;+hite;
C$S Color.WelloA
rval 6 ;WelloA;
D1$UL#
rval 6 Str[(ival) S ; an) it is not a pre)e*ine) color constant;
!D SLC#
'#U'! rval
!D
:otice that the string variab&e ArvlB ,as dimensioned using the #*M -e',ord, but that the
integer variab&e Ai'lB ,as automatica&&' dimensioned ,hen
,as dec&ared# >here/ore, Ai'lB does not use a #*M statement#
Once 'ou have comp&eted this code, save this modu&e /i&e and return bac- to the code
,indo, /or 71ain# <e have to modi/' our code in the MenuO*te"OMClick subroutine#
=ere is the ne, subroutineC
10#
Dialo5.SelectColor
Color!ame 6 Mo)-le=.SetColor!ame(Dialo5.Color)
#extLabel=.1oreColor 6 Dialo5.Color
!D
<e have added the &ine Co&or:ame W ### but have not dec&ared Co&or:ame 'et# >his
variab&e must be g&oba& because ,e are ca&&ing a modu&e to return the va&ue Co&or:ame# At
the ver' beginning o/ the 71ain#c&ass code /i&e, add this code 9ust be/ore the
PUBLIC SUB 1orm82pen()O
T .ambas class *ile
T )eclare a 5lobal variable to be -se) Aith o-r SetColor!ame mo)-le
Color!ame $S Strin5
:o,, ,hen the program e6ecutes, the variab&e ,i&& be -no,n# +n the code be&o,, the ca&& toC
,i&& return the string va&ue assigned to our Co&or:ame variab&e# <e ,ant to set the co&or o/
the /oreground te6t to the co&or 9ust pic-edC
#extLabel=.1orecolor 6 Dialo5.Color
:o,, ,e ,i&& ta-e the string and disp&a' it (/ormatted, o/ course b' assigning it to the
>e6tLabe&"#>e6t propert'#
>he /ina& version o/ our 1enu"+tem"LC&ic- routine shou&d &oo- &i-e thisC
Dialo5.SelectColor
!D
<e ,i&& ,ant to do the same thing /or the bac-ground co&or# >he second menu item in
108
the Co&or.ia&og menu is Bac-ground Co&or so &et's c&icon that /rom the +.E and code the
/o&&o,ingC
PUBLIC SUB Men-=ItemB8Click()
Dialo5.#itle 6 ;Choose a back5ro-n) color;
Dialo5.SelectColor
#extLabel=.BackColor 6 Dialo5.Color
!D
NoteL When $ou open a ne. project9 Gambas chec3s $our s$stem to "etermine .hether $ou use the
Gnome "es3top or C,-. =$ "e(ault9 i( $ou are using Gnome9 Gambas .ill loa" the GTCD graphic
librar$E i( $our are using C,-9 Gambas loa"s the :t librar$. As o( Gambas 'ersion 2.2.19 the GTCD
FelectFont .i"get "oes not .or3 correctl$9 an" there are other reporte" gaps in GTCD integration.
For this reason9 .e recommen" opening these projects as G:tH.
>he /ina& option in our /irst menu is to change the 7ont# >he 2e&ect7ont .ia&og is used
to accomp&ish this# Once again, go to the /orm menu and choose the 7ont option in the
Co&or.ia&og menu o/ our pro9ect to get the c&ic- event set in the code ,indo,# 7onts are
hand&ed in Gambas ,ith the 7ont c&ass# >his c&ass represents a /ont used /or dra,ing or
disp&a'ing te6t in contro&s# >his c&ass is creatab&e# +n order /or 'ou to dec&are a /ont variab&e,
use ,i&& need to used this /ormatC
DIM h1ont $S 1ont
h1ont 6 !+ 1ont ( " 1ont $S Strin5 % )
>he code above creates a ne, /ont ob9ect /rom a /ont description# >his c&ass acts &i-e a
read4on&' arra'# >his code creates a ne, /ont ob9ect /rom a /ont description and returns itC
DIM h1ont $S 1ont
h1ont 6 1ont " 1ont $S Strin5 %
>he properties that 'ou can use ,ith 7ont inc&udeC
Ascent
Bo&d
.escent
7i6ed
+ta&ic
:ame
Reso&ution
2i0e
2tri-eOut
10?
2t'&es
@nder&ine
=ere is an e6amp&e o/ ho, to use code to set the 7ont propertiesC
1orm=.1ont.!ame 6 ;Utopia;
1orm=.1ont.Bol) 6 #'U
1orm=.1ont.Italic 6 #'U
1orm=.1ont.SiRe 6 ;=@;
1orm=.1ont.Strike2-t 6 1$LS
1orm=.1ont.Un)erline 6 #'U
>he 7ont c&ass has three 1ethods 'ou can ca&&C =eight, >o2tring, and <idth# 6eight
is a /unction that returns the height o/ the te6t disp&a'ed ,ith the /ont# +t is dec&ared asC
1U!C#I2! :ei5ht ( #ext $S Strin5 ) $S Inte5er
&o$tring returns the /u&& name o/ a /ont as a description string# >his string is a
concatenation o/ a&& the /ont properties separated b' commas# +t is dec&ared asC
1U!C#I2! #oStrin5 ( ) $S Strin5
An e6amp&e ca&& to >o2tring ,ou&d beC
P'I!# $pplication.1ont.#oStrin5()
-idth is a /unction 9ust &i-e =eight but it returns the ,idth o/ the te6t disp&a'ed ,ith the
/ontC
1U!C#I2! +i)th ( #ext $S Strin5 ) $S Inte5er
:o,, &et's continue to enter our code /or our 1enuPro9ect program in the P(%)*C
$(% MenuO*te"PMClick() routine# 7irst, ,e ,i&& dec&are t,o &oca& variab&es, fontdata and
oldfontdata# <e ,ant to get the ne, /ont /rom the ca&& to the 2e&ect7ont .ia&og, but ,e a&so
,ant to retain the o&d /ont data in case ,e need it# :e6t, ,e dec&are t,o string variab&es, attr
and sel (attribute and se&ection to be used to set the /ont attribute string\ se&ection is a ,or-
string ,e ,i&& bui&d d'namica&&', based on the various se&ections the user cou&d ma-e in the
dia&og#
PUBLIC SUB Men-=Item/8Click()
DIM *ont)ata $S *ont
DIM ol)*ont)ata $S 1ont
DIM attr $S Strin5
DIM sel $S Strin5
10%
At this point, 'ou ma' be as-ing 'ourse&/ i/ 'ou cou&d not simp&' use the >o2tring
propert' to do this# Kes, but 'ou ,ou&d not &earn as much# Bear ,ith me and code a&ong# >he
/o&&o,ing &ine o/ code simp&' b&an-s out our attr stringC
attr 6 ;;
:o,, ,e assign the current >e6tLabe&"#/ont propert' to the oldfontdata variab&eC
ol)*ont)ata 6 #extLabel=.1ont
:e6t, &et's set the tit&e /or the dia&og and ca&& the 2e&ect7ont .ia&og ,ith these t,o &inesC
Dialo5.#itle 6 ; Pick a *ont... ;
Dialo5.Select1ont
<hen the user se&ects a /ont /rom the 2e&ect7ont .ia&og, ,e ,ant to assign the /ont se&ected to
the fontdata variab&eC
*ont)ata 6 Dialo5.1ont
At this point, ,e ,i&& chec- to see ,hat attributes the user has chosen and d'namica&&'
bui&d an output string# <e cou&d have bui&t this +7 >=E: EL2E statement to chec- ever'
propert' supported b' the 7ont c&ass, but ,e are not interested in a&& o/ them /or this e6ercise#
I1 *ont)ata.Italic #:!
sel 6 ; Italic;
attr 6 attr S sel
!DI1
I1 *ont)ata.Bol) #:!
sel 6 ; Bol);
attr 6 attr S sel
!DI1
I1 *ont)ata.Strikeo-t #:!
sel 6 ; Strikeo-t;
attr 6 attr S sel
!DI1
I1 *ont)ata.Un)erline #:!
sel 6 ; Un)erline;
attr 6 attr S sel
!DI1
:e6t, ,e ,i&& set the /ont in the >e6tLabe&" contro& to be ,hat the user se&ected and
disp&a' the d'namica&&' created string o/ /ont data to the userC
10+
#extLabel=.1ont 6 *ont)ata
#extLabel=.#ext 6 ;1ontO ;S*ont)ata.!ameS;0 ;SStr('o-n)(*ont)ata.SiRe)) S attr
<e ,i&& ,ait /ive seconds to &et the ta-e a &oo- at the resu&t, then give them a choice as
to ,hether or not the' ,ant to -eep these settings or revert bac- to the previous settings#
+$I# C.9

SLC# Messa5e.Y-estion(;Qeep the neA *ontJ;0 ;Wes;0;!o;0;DonTt knoA;)
C$S =
#extLabel=.#ext 6 ;#his is noA the )e*a-lt *ont.;
C$S B
#extLabel=.1ont 6 ol)*ont)ata
#extLabel=.#ext 6 ;'everte) to previo-s *ont settin5.;
C$S /
#extLabel=.#ext 6 ;!o chan5e Aas ma)e to )e*a-lt *ont.;
!D SLC#
!D
:ote that ,e have 9umped the gun a bit and introduced the use o/ 1essageBo6es
,ithout e6p&aining them# >hat is our ne6t tas-, but + ,anted to give 'ou a previe,# 2ave 'our
pro9ect and e6ecute it at this time# Kour resu&ts shou&d be simi&ar to this, depending on the
co&ors and /ont 'ou se&ectedC
And i/ 'ou decide to -eep it as the de/au&t, 'ou ,i&& see something &i-e thisC
110
Figure #*: Felecting colors an" (onts.
At this point in 'our &earning 9ourne', 'ou -no, ho, to do 5uite a bit in Gambas# <e
must continue this 9ourne' b' e6panding our abi&it' to dea& ,ith input and output /rom the
user# >he 1essageBo6es are another va&uab&e too& in our Gambas arsena&# Let's /ind out more
about using them#
2essage+oes
1essageBo6 contro&s are a 5uite hand' means o/ communicating in/ormation to the
user or getting ans,ers that are o/ the >R@EM7AL2E, KE2M:O t'pe# Genera&&' spea-ing,
1essageBo6es /a&& into one o/ /our broad categoriesC 5uer' andMor con/irmation, in/ormation,
,arning, and errorMa&ert noti/ications# >he Messge clss is used /or disp&a'ing these
1essageBo6es# >his c&ass is static and it can be used as a /unction# +t is dec&ared as
S#$#IC 1U!C#I2! Messa5e ( Messa5e $S Strin5 " 0 B-tton $S Strin5 % ) $S Inte5er
>he 1ethods that are supported b' the 1essage c&ass are +n/o, Huestion, .e&ete, Error,
and <arning# Kou have seen the 1essage#Huestion method used used a&read'# Each method
serves a speci/ic purpose and shou&d be used appropriate&' in 'our code# Let's start ,ith the
easiest 1essageBo6 method, the +n/ormation method#
In0ormation .essages
>he +n/o method is dec&ared asC
S#$#IC 1U!C#I2! In*o ( Messa5e $S Strin5 " 0 B-tton $S Strin5 % ) $S Inte5er
and it is used to disp&a' an in/ormation 1essageBo6, ,ith on&' one button# 2ince the user
does not have to ma-e a decision, the' on&' need to ac-no,&edge the message# =ence, on&'
one button is needed# =ere is ,hat our code ,i&& produceC
111
Figure #/: 2a3ing a ne. "e(ault (ont (or the Te8t>abel1
control.
>o continue bui&ding our e6amp&e program, /rom the /orm go to the 1essageBo6es
menu and c&icon +n/o 1essage menu item# +t ,i&& ta-e 'ou to the code editor ,indo, and
'ou ,i&& be in the MenuB*te"OMClicked() subroutine#
PUBLIC SUB Men-BItem=8Click()
Messa5e.In*o(;:ere is some in*ormation to consi)er.;)
!D
Prett' simp&e, ehN <hat i/ ,e ,anted to togg&e the chec-ed propert' va&ue /rom >R@E
to 7AL2E or vice versa each time this menu item ,as se&ected# 1odi/' the code above as
/o&&o,sC
LS
!DI1
!D
>he /igure above sho,s the chec-ed menu item# 2e&ecting it again ,i&& unchec- it#
<e&&, that ,as not too di//icu&t, ,as itN 2ee, Gambas ma-es things eas'# :o,, &et's move on to
the ne6t part#
112
Figure #0: An +n(ormation 2essage=o8.
Figure %1: A chec3e" menu item.
$-er1'Con0irm .essages
Huestion and .e&ete /a&& into this categor'# Huestion is de/ined asC
S#$#IC 1U!C#I2! Y-estion ( Messa5e $S Strin5 " 0 B-tton= $S Strin50 B-ttonB $S Strin50 B-tton/ $S Strin5 % ) $S Inte5er
+nvo-ing it disp&a's a 5uestion 1essageBo6 ,ith up to three buttons# >he inde6 o/ the button
c&ic-ed b' the user is returned# Let's go bac- to our previous code and e6amine it in detai&C
SLC# Messa5e.Y-estion(;Qeep the neA *ontJ;0 ;Wes;0;!o;0;DonTt knoA;)
C$S =
C$S B
C$S /
!D SLC#
Because the inde6 o/ the button c&ic-ed b' the user is returned, it is easiest to embed
the ca&& to 1essage#Huestion in a 2ELEC>MCA2E statement# 2ELEC> ta-es the integer return
va&ue and, because ,e -no, it can on&' be returned as CA2E ", ;, or D, ,e ,i&& not need to
ma-e a .E7A@L> section# <e cou&d, o/ course, but it is not necessar'# .epending on the
va&ue returned, ,e ,i&& either ta-e a ,es action, a (o action, or a -on$t &now action because
that is ,hat ,e speci/ied in our ca&& to the .ia&og (in the 2ELEC> statement above#
Let's ,rite ne, code /or our 1essageBo6es 1enu menu item Huestion no,# Choose it
/rom the /orm ,indo, and enter this codeC
PUBLIC SUB Men-BItem/8Click()
SLC# Messa5e.Y-estion(;Di) yo- like thisJ;0 ;Wes;0;!o;0;DonTt knoA;)
C$S =
#extLabel=.#ext 6 ;Like) it.;
C$S B
113
Figure %1: A :uestion 2essage=o8.
#extLabel=.#ext 6 ;Di) not like it.;
C$S /
#extLabel=.#ext 6 ;Di) not knoA.;
!D SLC#
!D
:otice that in the $E)EC& &ine, the /irst te6t b&oc- in 5uotes is a&,a's the 1essageBo6
te6t, and the ne6t three b&oc-s o/ te6t in 5uotes are a&,a's in se5uence /or Button", Button;,
and ButtonD# <hen 'ou e6ecute the program, ,hat 'ou shou&d see is sho,n above#
Error .essages
>he Error /unction disp&a's an error 1essageBo6, ,ith up to three buttons# >he inde6
o/ the button c&ic-ed b' the user is returned# Error is de/ined asC
S#$#IC 1U!C#I2! rror (Messa5e $S Strin5"0Btn= $S Strin50 BtnB $S Strin50 Btn/ $S Strin5%) $S Inte5er
Go to the /orm and c&ic- the Error 1essage sub1enu+tem to set up a c&ic- event and enter this
codeC
PUBLIC SUB s-bMen-Item=8Click()
Messa5e.rror(;+oAV #his Aas a mistake.;)
!D
=ere is ,hat 'ou shou&d see ,hen 'ou run the programC
Warning or Alert .essages
<arning messages disp&a' a ,arning 1essageBo6, ,ith up to three buttons# >he inde6
o/ the button c&ic-ed b' the user is returned# <arning is dec&ared asC

S#$#IC 1U!C#I2! +arnin5 (Messa5e $S Strin5"0Btn= $S Strin50 BtnB $S Strin50 Btn/ $S Strin5 % ) $S Inte5er
+n our e6amp&e program, error, ,arning and de&ete messages are part o/ the submenu ,e
114
Figure %2: An -rror 2essage=o8.
created to appear ,hen the menu item A&ert 1essages is activated#
>o code the ,arning message, ,e need to set the c&ic- event b' going to the menu and
c&ic-ing on the <arning 1essage sub1enu+tem# >his ,i&& put us in the code ,indo, ,here
,e ,i&& enter this codeC
PUBLIC SUB s-bMen-ItemB8Click()
Messa5e.+arnin5(;Wo- have been Aarne) abo-t thisV;)
!D
<hen 'ou e6ecute the program, here is ,hat 'ou shou&d seeC
.e&ete 1essages
>he .e&ete /unction disp&a's a de&etion 1essageBo6, ,ith up to three buttons# >he
inde6 o/ the button c&ic-ed b' the user is returned# .e&ete is dec&ared asC
S#$#IC 1U!C#I2! Delete (Messa5e $S Strin5 "0 Btn= $S Strin50 BtnB $S Strin50 Btn/ $S Strin5 % ) $S Inte5er
2et the c&ic- event /or the sub1enu+tem .e&ete 1essage and enter this codeC
PUBLIC SUB s-bMen-Item/8Click()
SLC# Messa5e.Delete(;DeleteJ;0 ;Wes;0;!o;0;Cancel;)
C$S =
#extLabel=.#ext 6 ;Delete) it;
C$S B
#extLabel=.#ext 6 ;!ot Delete);
C$S /
#extLabel=.#ext 6 ;Cancele)V;
!D SLC#
!D
<hen 'ou e6ecute the program, here is ,hat 'ou shou&d seeC
11#
Figure %3: A Warning 2essage=o8.
!ia*og C*ass -i*e3re*ated -unctions
>he standard dia&ogs provided ,ith Gambas a&so support /i&e operation such as opening
a /i&e, saving a /i&e, and choosing a director' path# >he' are prett' standard but the great
advantage is that 'ou don't have to bui&d them ever' time 'ou ,ant to ,rite a program#
Consistenc' in user inter/ace is no, demanded /rom users and an'thing &ess ma-es 'our
program &ess approachab&e and, resu&ting, &ess accepted b' users than it cou&d be# >his section
,i&& sho, 'ou ho, eas' it is to use Gambas standard dia&ogs /or /i&e operations#
Dialog Open&ile &-nction
>he Open7i&e .ia&og /unction ca&&s the /i&e standard dia&og to get the name o/ a /i&e to
open# >his /unction returns >R@E i/ the user c&ic-ed on the Cance& button, and 7AL2E i/ the
user c&ic-ed on the OE button# +t is dec&ared as /o&&o,sC
S#$#IC 1U!C#I2! 2pen1ile ( ) $S Boolean
7rom the e6amp&e program /orm ,indo,, c&icon the menu 7i&e.ia&ogs and se&ect the
7i&e open### menu item# >his sets up the c&ic- event and ,e ,i&& enter this codeC
PUBLIC SUB Men-/Item=8Click()
Dialo5.#itle 6 ; 2pen *ile... ;
Dialo5.2pen1ile
#extLabel=.#ext 6 ; 2P!O ; S Dialo5.Path
!D
>he code above simp&' sets the tit&e and ca&&s the standard dia&og# <hen the user
/inishes, the string va&ue returned /rom the Open7i&e .ia&og /unction is assigned to the
>e6tLabe&"#>e6t variab&e# =ere is ,hat it shou&d bring up ,hen 'ou run the codeC
118
Figure %#: A ,elete 2essage=o8 .ith three
buttons.
Prett' eas' stu//# 2aving /i&es is 9ust as eas'#
Dialog Sa/e&ile &-nction
>he 2ave7i&e .ia&og /unction a&so ca&&s the /i&e standard dia&og to get the name o/ a /i&e
to save# +t returns >R@E i/ the user c&ic-ed on the Cance& button, and 7AL2E i/ the user
c&ic-ed on the OE button# 2ave7i&e is dec&ared asC
S#$#IC 1U!C#I2! Save1ile ( ) $S Boolean
Create a c&ic- event /or our 7i&e 2ave### menu item and in the code ,indo, enter this codeC
PUBLIC SUB Men-/ItemB8Click()
Dialo5.#itle 6 ; Save *ile to... ;
Dialo5.Save1ile
#extLabel=.#ext 6 ;S$(O ; S Dialo5.Path
11?
Figure %): The Fa'e File ,ialog in Gambas.
Figure %%: The Apen File ,ialog in Gambas.
!D
Dialog SelectDirector1 &-nction
>he 2e&ect.irector' .ia&og /unction ca&&s the /i&e standard dia&og to get an e6isting
director' name# +t returns >R@E i/ the user c&ic-ed on the Cance& button, and 7AL2E i/ the
user c&ic-ed on the OE button# 2e&ect.irector' is dec&ared asC
S#$#IC 1U!C#I2! SelectDirectory ( ) $S Boolean
>his is the /ina& c&ic- event ,e need to code /or our program# Choose the 2e&ect .ir
menu item and enter this codeC
PUBLIC SUB Men-/Item/8Click()
Dialo5.#itle 6 ; Pick a )ir... ;
Dialo5.SelectDirectory
#extLabel=.#ext 6 ;S$( to DI'O ; S Dialo5.Path
!D
2ave 'our pro9ect and run the code# =ere is ,hat 'ou shou&d see /or 2e&ect.ir (right#
:o, ,e have ,ritten a&& the code needed to /inish our 1enuPro9ect program# 2ave it
and e6ecute the program# >he ne6t section presents the comp&ete c&ass /i&e /or 'ou to revie,#
+t is time /or us to move on to bigger and better things# +n the ne6t chapter, ,e ,i&& start
&earning ho, to hand&e input and output /rom the user b' using strings and /i&es#
11%
Figure %*: The Felect,irector$ "ialog.
Comp*ete Eamp*e &isting
T .ambas class *ile
T )eclare a 5lobal variable to be -se) Aith o-r SetColor!ame mo)-le
Color!ame $S Strin5 T$ 5lobal variable )oes not -se the DIM keyAor)0 an) it m-st come be*ore
Tthe PUBLIC SUB 1orm82pen() statement.
M.Caption 6 ; +orkin5 Aith Men-s ;
!D
1Main.Close
!D
Dialo5.SelectColor
!D
PUBLIC SUB Men-=ItemB8Click()
Dialo5.#itle 6 ;Choose a back5ro-n) color;
Dialo5.SelectColor
#extLabel=.BackColor 6 Dialo5.Color
!D
PUBLIC SUB Men-=Item/8Click()
DIM *ont)ata $S *ont
DIM ol)*ont)ata $S 1ont
DIM attr $S Strin5
DIM sel $S Strin5
attr 6 ;;
ol)*ont)ata 6 #extLabel=.1ont
Dialo5.#itle 6 ; Pick a *ont... ;
Dialo5.Select1ont
*ont)ata 6 Dialo5.1ont
I1 *ont)ata.Italic #:!
11+
sel 6 ; Italic;
attr 6 attr S sel
!DI1
I1 *ont)ata.Bol) #:!
sel 6 ; Bol);
attr 6 attr S sel
!DI1
I1 *ont)ata.Strikeo-t #:!
sel 6 ; Strikeo-t;
attr 6 attr S sel
!DI1
I1 *ont)ata.Un)erline #:!
sel 6 ; Un)erline;
attr 6 attr S sel
!DI1
#extLabel=.1ont 6 *ont)ata
#extLabel=.#ext 6 ;1ontO ; S *ont)ata.!ame S ;0 ; S Str('o-n)(*ont)ata.SiRe)) S attr
+$I# C.9
SLC# Messa5e.Y-estion(;Qeep neA *ontJ;0 ;Wes;0;!o;0;DonTt knoA;)
C$S =
C$S B
C$S /
!D SLC#
!D
LS
!DI1
!D
PUBLIC SUB s-bMen-Item=8Click()
Messa5e.rror(;+oAV #his Aas a mistake.;)
!D
120
PUBLIC SUB s-bMen-ItemB8Click()
Messa5e.+arnin5(;Wo- have been Aarne) abo-t thisV;)
!D
PUBLIC SUB s-bMen-Item/8Click()
SLC# Messa5e.Delete(;DeleteJ;0 ;Wes;0;!o;0;Cancel;)
C$S =
#extLabel=.#ext 6 ;Delete) it;
C$S B
#extLabel=.#ext 6 ;!ot Delete);
C$S /
#extLabel=.#ext 6 ;Cancelle)V;
!D SLC#
!D
PUBLIC SUB Men-BItem/8Click()
SLC# Messa5e.Y-estion(;Di) yo- like thisJ;0 ;Wes;0;!o;0;DonTt knoA;)
C$S =
#extLabel=.#ext 6 ;Like) it.;
C$S B
#extLabel=.#ext 6 ;Di) not like it.;
C$S /
#extLabel=.#ext 6 ;Di) not knoA.;
!D SLC#
!D
PUBLIC SUB Men-/Item=8Click()
Dialo5.#itle 6 ; 2pen *ile... ;
Dialo5.2pen1ile
#extLabel=.#ext 6 ; 2P!O ; S Dialo5.Path
!D
PUBLIC SUB Men-/ItemB8Click()
Dialo5.#itle 6 ; Save *ile to... ;
Dialo5.Save1ile
#extLabel=.#ext 6 ;S$(O ; S Dialo5.Path
!D
PUBLIC SUB Men-/Item/8Click()
Dialo5.#itle 6 ; Pick a )ir... ;
#extLabel=.#ext 6 ;S$( to DI'O ; S Dialo5.Path
!D
121
PUBLIC SUB Men-@Item=8Click()
Messa5e.In*o(;#his is all abo-tUbrKUbK .ambas Pro5rammin5UMbKV;)
!D
22ain1modu*e *isting
DIM rval $S Strin5 T$ local variable m-st be )imensione) in the 1U!C#I2! or SUB be*ore the *irst exec-table
comman).
SLC# i(al
C$S Color.Black
rval 6 ;Black;
C$S Color.Bl-e
rval 6 ;Bl-e;
C$S Color.Cyan
rval 6 ;Cyan;
C$S Color.DarkBl-e
rval 6 ;DarkBl-e;
C$S Color.DarkCyan
rval 6 ;DarkCyan;
C$S Color.Dark.ray
rval 6 ;Dark.ray;
C$S Color.Dark.reen
rval 6 ;Dark.reen;
C$S Color.DarkMa5enta
rval 6 ;DarkMa5enta;
C$S Color.Dark'e)
rval 6 ;Dark'e);
C$S Color.DarkWelloA
rval 6 ;DarkWelloA;
C$S Color..ray
rval 6 ;.ray;
C$S Color..reen
rval 6 ;.reen;
C$S Color.Li5ht.ray
rval 6 ;Li5ht.ray;
C$S Color.Ma5enta
rval 6 ;Ma5enta;
C$S Color.2ran5e
rval 6 ;2ran5e;
122
C$S Color.Pink
rval 6 ;Pink;
C$S Color.'e)
rval 6 ;'e);
C$S Color.#ransparent
rval 6 ;#ransparent;
C$S Color.(iolet
rval 6 ;(iolet;
C$S Color.+hite
rval 6 ;+hite;
C$S Color.WelloA
rval 6 ;WelloA;
D1$UL#
rval 6 Str[(ival) S ; an) it is not a pre)e*ine) color constant;
!D SLC#
'#U'! rval
!D
In the ne2t chapter) we will learn how to handle strings and per>orm "arious data con"ersion
acti"ities that are common in programming. The ad"antage *ou ha"e in dealing with strings) howe"er)
is that *ou are now programming using Gambas. It makes the task much easier than man*
con"entional programming languages) as *ou will soon see.
123
Chapter , -trings and +ata Con.ersion
One o/ the most important things a programmer needs to -no, is ho, to hand&e strings
and use the bui&t4in /unctions provided b' the deve&opment &anguage he or she ma' be
,or-ing ,ith# 1anipu&ating strings and converting /rom one data4t'pe to another is a&most
a&,a's re5uired ,hen programming# >he more adept a programmer is at using the bui&t4in
/unctions, the more &i-e&' it is their program ,i&& operate e//icient&'#
,tring -unctions
+n Gambas, there is a rich set o/ string /unctions# <e ,i&& use the conso&e /or this
chapter and &earn about the /o&&o,ing /unctionsC
Len
@pperUM@caseU and Lo,erUMLCaseU
>rimUMR>rimU and L>rimU
Le/tUM1idUMRightU
2paceU
Rep&aceU
2tringU
2ubstU
+n2tr
R+n2tr
2p&it
<e ,i&& need to create a ne, conso&e app&ication to do our ,or- in this chapter# 2tart
Gambas and create a ne, termina& app&ication named 2tring>ests# <hen the +.E appears,
doub&e4c&icon the 11ain document icon to create a ne, startup c&ass named
11ain#modu&e# >he code ,indo, shou&d appear and 'ou shou&d see something &i-e thisC
PUBLIC SUB Main()
!D
<e no, have a&& the pre&iminaries out o/ the ,a' and are read' to begin &earning about
the strings in Gambas# Kou ma' remember /rom an ear&ier chapter that in Gambas a string
data4t'pe is a re/erence to a variab&e &ength string# +t is /our b'tes in initia& si0e and ,hen it is
created it is initia&i0ed ,ith a :u&& va&ue#

Len
Len returns the &ength o/ a string# >he return va&ue is an +nteger# =ere is ho, )en
124
,ou&d be used in codeC
Len5th 6 Len ( Strin5 )
7rom the code ,indo,, &et's t'pe the /o&&o,ingC
PUBLIC SUB Main()
DIM iStrin5Len5th $S Inte5er
DIM s#estStrin5 $S Strin5
s#estStrin5 6 ;=B/@CFX?>9=B/@CFX?>9;
iStrin5Len5th 6 Len(s#estStrin5)
P'I!# ;66K ; S iStrin5Len5th S ; is the len5th o* o-r test strin5.;
s#estStrin5 6 ;=B/@C;
s#estStrin5 6 ;=B/@CFX?>9=;
!D
>he conso&e ,i&& respond ,ith thisC
66K B9 is the len5th o* o-r test strin5.
66K C is the len5th o* o-r test strin5.
66K == is the len5th o* o-r test strin5.
+t is important to -no, that string &ength begins counting at position ", not 0ero &i-e in
C, P'thon and some other &anguages# :o, that ,e can /ind out ho, man' characters are in a
string, &et's &earn ho, to convert the string /rom one case to another#
Upper2'Ucase2'Ucase 3 Lo4er2'Lcase2'Lcase
@pperU returns a string converted to upper case# @caseU and @case are s'non'nms /or
@pperU and can be used interchangeab&'# Lo,erU returns a string converted to &o,er case#
LcaseU and Lcase are s'non'ms /or Lo,erU and can a&so be used interchangeab&'# :ote that
these /unctions do not work ,ith @>74* strings ,ith a character code higher than ";*# =ere
is the standard Gambas &anguage s'nta6 /or using these /unctionsC
'es-lt 6 Upper[ ( Strin5 )
'es-lt 6 UCase[ ( Strin5 )
12#
>'pe this in the code ,indo, and e6ecute the programC
PUBLIC SUB Main()

s#estStrin5 6 ;abc)e*5;
P'I!# ;66K ; S s#estStrin5 S ; is o-r startin5 strin5.;
P'I!# ;66K ; S UCase[(s#estStrin5) S ; is noA -ppercase.;
P'I!# ;66K ; S LCase[(s#estStrin5) S ; is noA back to loAercase.;
P'I!# ;66K ; S Upper[(s#estStrin5) S ; is noA back to -ppercase.;
s#estStrin5 6 ;=B/abc@CF)e* X?>5hi\\\;
P'I!# ;66K ; S s#estStrin5 S ; is o-r startin5 strin5.;
P'I!# ;66K ; S UCase(s#estStrin5) S ; is noA -ppercase.;
P'I!# ;66K ; S LCase(s#estStrin5) S ; is noA back to loAercase.;
P'I!# ;66K ; S Upper(s#estStrin5) S ; is noA back to -ppercase.;
P'I!# ;66K ; S LoAer[(s#estStrin5) S ; is noA back to loAercase.;
!D
66K abc)e*5 is o-r startin5 strin5.
66K $BCD1. is noA -ppercase.
66K abc)e*5 is noA back to loAercase.
66K $BCD1. is noA back to -ppercase.
66K =B/abc@CF)e* X?>5hi\\\ is o-r startin5 strin5.
66K =B/$BC@CFD1 X?>.:I\\\ is noA -ppercase.
66K =B/abc@CF)e* X?>5hiRRR is noA back to loAercase.
66K =B/$BC@CFD1 X?>.:I\\\ is noA back to -ppercase.
66K =B/abc@CF)e* X?>5hiRRR is noA back to loAercase.
Trim2" LTrim2" an #Trim2
&ri"7 strips a,a' a&& ,hite spaces /rom either end o/ a string# +t ,i&& not strip ,hite
spaces a,a' a/ter the /irst non4,hitespace is encountered and basica&&' ignores a&& ,hitespace
unti& the &ast non4,hitespace character is encountered, ,hereupon it ,i&& begin to trim trai&ing
,hitespace# A ,hite space is an' character ,hose A2C++ code is stric&' &o,er than D;# >rimU
is basica&&' a ca&& to )tri"7 and +tri"7 simu&taneous&'# +t is used &i-e thisC
'es-lt 6 #rim[(Strin5)
128
>r' this on 'our conso&e see ho, the >rimU /unction ,or-sC
PUBLIC SUB Main()
DIM s'es-lt $S Strin5
DIM iLen5th $S Inte5er

P'I!# ; = B;
P'I!# ;=B/@CFX?>9=B/@CFX?>9;
s#estStrin5 6 ; Uabc)e* ;
iLen5th 6 Len(s#estStrin5)

P'I!# s#estStrin5 S ; is o-r startin5 strin5.;
P'I!# ;It is ; S Str[(iLen5th) S ; characters lon5;
s'es-lt 6 #rim[(s#estStrin5)
P'I!# s'es-lt S ;K is the res-lt o* #rim[ call.;
!D
>he conso&e responds ,ith thisC

= B
=B/@CFX?>9=B/@CFX?>9
Uabc)e*K K is o-r startin5 strin5.
It is =/ characters lon5
Uabc)e*K is the res-lt o* #rim[ call.
Le0t2" .i2" an #ight2
Left7 returns the /irst 7ength characters o/ a string# +/ 7ength is not speci/ied, the /irst
character o/ the string is returned# +/ 7ength is negative, a&& o/ the string e6cept the 27ength
&ast characters are returned# 2tandard Gambas &anguage s'nta6 isC
'es-lt 6 Le*t[ ( Strin5 " 0 Len5th % )
Mid7 returns a substring containing the 7ength characters /rom the /irst position# +/
7ength is not speci/ied, ever'thing /rom the start position is returned# +/ 7ength is negative,
ever'thing /rom the start position e6cept the 27ength &ast characters is returned# 2tandard
Gambas &anguage s'nta6 isC
'es-lt 6 Mi)[ ( Strin5 0 Start " 0 Len5th % )
+ight7 returns the 7ength &ast characters o/ a string# +/ 7ength is not speci/ied, the
&ast character o/ the string is returned# +/ 7ength is negative, a&& o/ the string e6cept the
12?
27ength /irst characters are returned# 2tandard Gambas &anguage s'nta6 isC
'es-lt 6 'i5ht[ ( Strin5 " 0 Len5th % )
>r' this on 'our conso&eC
PUBLIC SUB Main()

P'I!# ; = B;
P'I!# ;=B/@CFX?>9=B/@CFX?>9;
s#estStrin5 6 ;abc)e*5hi;

P'I!# ;It is ; S Str[(iLen5th) S ; characters lon5;

s'es-lt 6 Le*t[(s#estStrin50/)
P'I!# s'es-lt S ; is the res-lt o* Le*t[ call.;
s'es-lt 6 Mi)[(s#estStrin50@0/)
P'I!# s'es-lt S ; is the res-lt o* Mi)[ call.;
s'es-lt 6 'i5ht(s#estStrin50/)
P'I!# s'es-lt S ; is the res-lt o* 'i5ht[ call.;
!D
>he conso&e responds ,ith this\
= B
abc)e*5hi is o-r startin5 strin5.
It is > characters lon5
abc is the res-lt o* Le*t[ call.
)e* is the res-lt o* Mi)[ call.
5hi is the res-lt o* 'i5ht[ call.
Space2
2paceU returns a string containing 7ength spaces# 2tandard Gambas &anguage s'nta6 isC
Strin5 6 Space[ ( Len5th )
12%
>r' this on the conso&eC
PUBLIC SUB Main()

P'I!# ; = B;
P'I!# ;=B/@CFX?>9=B/@CFX?>9=B/@CF;
s#estStrin5 6 ;a;
P'I!# s#estStrin5 S Space[(B@) S ;R;
!D
= B
=B/@CFX?>9=B/@CFX?>9=B/@CF
a R
#eplace2
+eplce7 rep&aces ever' occurrence o/ the string Pattern in the string 2tring b' the
string Rep&ace2tring , and returns the resu&t# +/ 2tring is nu&&, then a nu&& string is returned# +/
Pattern is nu&&, then the string 2tring is returned# 2tandard Gambas &anguage s'nta6 is as
/o&&o,sC
'es-lt 6 'eplace[ ( Strin5 0 Pattern 0 'eplaceStrin5 )
>r' this program on 'our conso&eC
PUBLIC SUB Main()

s#estStrin5 6 ;abc=B/5hi;
s'es-lt 6 'eplace[(s#estStrin50;=B/;0 ;)e*;)
P'I!# s'es-lt S ; is the res-lt o* 'eplace call.;

s#estStrin5 6 ;a b c ) e * 5 h i;
s'es-lt 6 'eplace[(s#estStrin50; ;0 ;,;)

12+
s#estStrin5 6 ;NtaNtbNtcNt)e*;
s'es-lt 6 'eplace[(s#estStrin50;Nt;0 ;;)
!D
abc=B/5hi is o-r startin5 strin5.
abc)e*5hi is the res-lt o* 'eplace call.
a b c ) e * 5 h i is o-r startin5 strin5.
a,b,c,),e,*,5,h,i is the res-lt o* 'eplace call.
$ b c )e* is o-r startin5 strin5.
abc)e* is the res-lt o* 'eplace call.
String2
2tringU simp&' returns a string containing Length times the Pattern# @se this /ormatC
Strin5 6 Strin5[ ( Len5th 0 Pattern )
>r' this on the conso&eC
PUBLIC SUB Main()

P'I!# ; = B;
P'I!# ;=B/@CFX?>9=B/@CFX?>9=B/@CF;
s#estStrin5 6 ;a;

P'I!# s#estStrin5 S Strin5(B@0;.;) S ;R;
!D
= B
=B/@CFX?>9=B/@CFX?>9=B/@CF
a..................................................R
S-bst2
$u/st7 rep&aces arguments P", P;, etc# in a pattern ,ith the /irst, second, and
subse5uent Rep&ace2trings respective&', and return the resu&t# +/ Pattern is nu&&, then a nu&&
string is returned# 7or C deve&opers, this is not un&i-e a simp&i/ied sprint/# >his /unction is
130
ver' use/u& ,hen 'ou must concatenate strings that must be trans&ated# .o not use the P
operator inside the parentheses, containing the Pattern and Rep&ace2trings# <hen 'ou assign
strings to an order in the 2ubst statement, be care/u& ,ith the order o/ ,ords and phrases, as
the' ma' be reversed in di//erent &anguages# 2tandard Gambas &anguage s'nta6 isC
'es-lt 6 S-bst[( Pattern 0 'eplaceStrin5 "0 'eplaceStrin5 %)
>r' this &itt&e app&ication on 'our conso&eC
PUBLIC SUB Main()
DIM Lan510 Iam10 Lan5.0 Iam.0 Lan50 Iam $S Strin5
Lan51 6 ;en 1ran]aisO; Tin 1rench
Iam1 6 ;4e s-is pro5ramme-r )- .ambas;
Lan5. 6 ;a-* De-tschO; Tin .erman
Iam. 6 ;Ich bin .ambas Pro5rammierer;
Lan5 6 ;in n5lishOE
Iam 6 ;I am a .ambas pro5rammer;

P'I!# S-bst[(;1rench ,, S= SB;0 Lan510 Iam1) S ;V;
P'I!# S-bst[(;.erman ,, S= SB;0 Lan5.0 Iam.) S ;V;
P'I!# S-bst[(;n5lish ,, SB S=;0 Iam0 Lan5) S ;V;

!D
1rench ,, en 1ran]aisO 4e s-is pro5ramme-r )- .ambasV
.erman ,, a-* De-tschO Ich bin .ambas Pro5rammiererV
n5lish ,, in n5lishO I am a .ambas pro5rammerV
+/ 'ou are dimensioning mu&tip&e variab&es o/ the same data4t'pes, 'ou don't have to put them
a&& in separate &ines# Kou can put severa& on one &ine, separated b' commas, ,ith the t'pe
dec&aration at the endC
DIM a0 b0 c0...x $S Strin5
Observe that in the Eng&ish &ine in the code, the Patterns and the Rep&ace2tring variab&es are
intentiona&&' reversed, but the output in the conso&e is correct# >here is no re5uired order o/
the Rep&ace2tring variab&es in the 2ubstU statement# >he numbers in the Pattern are tags,
,hich re/er to the variab&es in the ordina& position ,here 'ou decided to put them# +/ it ma-es
sense to order the PatternM Rep&ace2tring as AP; P"B, or APD P" P;B, that is a&so acceptab&e#
131
InStr
*n$tr returns the position o/ the /irst occurrence o/ 2ubstring in 2tring# +/ 2tart is
speci/ied, the search begins at the position 2tart# +/ the substring is not /ound, +n2tr( returns
0ero#
Position 6 InStr ( Strin5 0 S-bstrin5 " 0 Start % )
>he /o&&o,ing code is a bit more invo&ved and ,i&& demonstrate the po,er o/ this
/unction# <e ,ant to /ind ever' space (set in the string at even4numbered positions and
print out the position ,here each space occurs# Enter this code in the conso&e code ,indo,C
PUBLIC SUB Main()
DIM iPosition $S Inte5er
DIM i!extCharPos $S Inte5er
DIM iCo-nter $S Inte5er

s#estStrin5 6 ;abc )e* 5hi;
iPosition 6 Instr(s#estStrin50; ;)
P'I!# s#estStrin5 S ; is o-r start strin5.;
P'I!# ;1irst space is at positionO ; S iPosition
i!extCharPos 6 iPosition H =
iPosition 6 Instr(s#estStrin50; ;0i!extCharPos)
P'I!# ;!ext space is at positionO ; S iPosition
P'I!#
s#estStrin5 6 ;a b c ) e * 5 h i 3 k l m n o p I r s t - v A x y R;
P'I!# ; = B / @ C F;
P'I!# ;=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9;
P'I!# s#estStrin5 S ; is o-r neA test strin5.;
P'I!#
P'I!# ;Len5th o* s#estStrin5 isO ; S iLen5th

iPosition 6 Instr(s#estStrin50; ;)
P'I!# ;1irst space is at positionO ; S iPosition
12' iCo-nter 6 iPosition #2 iLen5thMB
i!extCharPos 6 iPosition H =
iPosition 6 Instr(s#estStrin50; ;0i!extCharPos)
132
P'I!# ;!ext space is at positionO ; S iPosition
!7#
!D
>he resu&ting output isC
abc )e* 5hi is o-r start strin5.
1irst space is at positionO @
!ext space is at positionO ?
= B / @ C F
=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9=B/@CFX?>9
a b c ) e * 5 h i 3 k l m n o p I r s t - v A x y R is o-r neA test strin5.
Len5th o* s#estStrin5 isO C=
1irst space is at positionO B
!ext space is at positionO @
!ext space is at positionO F
.
.
!ext space is at positionO @F
!ext space is at positionO @?
!ext space is at positionO C9
R+n2tr
+*n$tr returns the position o/ the &ast occurrence o/ 2ubstring in 2tring, searching
/rom right to &e/t# +/ 2tart is speci/ied, the search stops at the position 2tart# +/ the substring is
not /ound, R+n2tr( returns 0ero# 2tandard Gambas &anguage s'nta6 isC
Position 6 'InStr ( Strin5 0 S-bstrin5 " 0 Start % )
Enter this code in the conso&eC
PUBLIC SUB Main()

DIM iPosition $S Inte5er

s#estStrin5 6 ;abc )e* abc )e* abc;
P'I!# ; = B;
P'I!# ;=B/@CFX?>9=B/@CFX?>9;
P'I!# s#estStrin5
133

iPosition 6 'Instr(s#estStrin50;abc;)
P'I!#
P'I!# ;last occ-rrence o* abc starts at positionO ; S iPosition
!D
= B
abc )e* abc )e* abc
last occ-rrence o* abc starts at positionO =X
Split
$plit sp&its a string into substrings de&imited b' the separator(s designated as
parameters# Escape characters can be speci/ied a&so# An' separator characters enc&osed
bet,een t,o escape characters are ignored in the sp&itting process# :ote that 2p&it ta-es on&'
three arguments so i/ 'ou ,ant to use severa& separators, 'ou shou&d pass them as the second
parameter, concatenated in a sing&e string# B' de/au&t, the comma character is the separator,
and there are no escape characters# >his /unction returns a string arra' /i&&ed ,ith each
detected substring# >he Gambas &anguage s'nta6 isC
$rray 6 Split ( Strin5 " 0 Separators 0 scape % )
=ere is a program to tr' on 'our conso&eC
PUBLIC SUB Main()
DIM a+or)$rray $S Strin5"%
DIM s+or) $S Strin5
T note Ae -se a space )elimiter
a+or)$rray 6 Split(;#his is in)ee) a very cool *eat-re o* .ambasV;0; ;)
12' $C: s+or) I! a+or)$rray
P'I!# s+or)
!7#
!D
#his
is
134
in)ee)
a
very
cool
*eat-re
o*
.ambasV
!ata Conversion
Asc an Chr2
Asc returns the A2C++ code o/ the character at position 3osition in the 2tring # +/
3osition is not speci/ied, the A2C++ code o/ the /irst character is returned# ChrU returns the
character ,hose A2C++ code is Code# A ,ord o/ cautionC Gambas uses the @>74* charset
interna&&', so an' character code greater than ";* ma' not have the same meaning as the'
,ou&d have ,ith another charset (/or e6amp&e, +2O**G)4"# =ere is the Gambas &anguage
s'nta6C
Co)e 6 $sc ( Strin5 " 0 Position % )
Character 6 Chr[ ( Co)e )
=ere is a samp&e program that i&&ustrates the use o/ both A2C and C=RUC
PUBLIC SUB Main()
DIM i$sciiCo)e $S Inte5er
DIM co-nter $S Inte5er
s#estStrin5 6 ;.ambas is 5reat.;
P'I!# ;Len5th o* s#estStrin5 isO ; S Str[(iLen5th)
12' co-nter 6 = #2 iLen5th
i$sciiCo)e 6 $sc(s#estStrin50co-nter)
I1 i$sciiCo)e UK /B #:!
P'I!# i$sciiCo)e S ; is charO ; S Chr(>) S Chr[(i$sciiCo)e)
LS
P'I!# i$sciiCo)e S ; is charO ; S Chr(>) S ;UspaceK;
!DI1
!7#
!D
13#
+n the code above, Chr() is used to represent the >AB character# >he resu&ting output /rom
the conso&e isC
Len5th o* s#estStrin5 isO =F
X= is charO .
>X is charO a
=9> is charO m
>? is charO b
>X is charO a
==C is charO s
/B is charO UspaceK
=9C is charO i
==C is charO s
/B is charO UspaceK
=9/ is charO 5
==@ is charO r
=9= is charO e
>X is charO a
==F is charO t
@F is charO .
(in2
BinU returns the binar' representation o/ a number# +/ .igits is speci/ied, the
representation is padded ,ith unnecessar' 0eros so that .igits digits are returned# =ere is the
ca&&ing convention /or BinUC
Strin5 6 Bin[ ( !-mber " 0 Di5its % )
E6amp&e code 'ou can tr' on the conso&eC
PUBLIC SUB Main()
DIM sBinaryCo)e $S Strin5
12' co-nter 6 9 #2 =C
sBinaryCo)e 6 Bin[(co-nter0@)
P'I!# sBinaryCo)e
!7#
!D
>he output shou&d &oo- &i-e thisC
138
9999
999=
99=9
99==
9=99
9=9=
9==9
9===
=999
=99=
=9=9
=9==
==99
==9=
===9
====
C(ool
CBoo& converts an e6pression into a Boo&ean va&ue# An e6pression is /a&se i/ an' o/ the
/o&&o,ing conditions are metC
A /a&se Boo&ean va&ue
A 0ero number
A 0ero &ength string
A nu&& ob9ect
Other,ise, the e6pression is true in a&& other cases# =ere is the Gambas &anguage s'nta6C
Boolean 6 CBool ( xpression )
=ere is an e6amp&eC
PUBLIC SUB Main()
P'I!# CBool(9) G ; ; G CBool(=)
!D
1$LS #'U
C(1te
CB'te converts an e6pression into a b'te# Epression is /irst converted into an integer#
13?
>hen, i/ this integer over/&o,s the b'te range, (4D;JIJ to D;JI* it is truncated#
Byte 6 CByte ( xpression )
E6amp&eC
PUBLIC SUB Main()
P'I!# CByte(;=X;)
P'I!# CByte(/BXF>)
P'I!# CByte(#'U)
!D
=X
=
BCC
CDate
C.ate converts an e6pression into a dateMtime va&ue# Be care/u&S >he current
&oca&i0ation is :O> used b' this /unction# Gambas &anguage s'nta6 isC
Date 6 CDate ( xpression )
E6amp&eC
PUBLIC SUB Main()
DIM sDateStrin5 $S Strin5
sDateStrin5 6 CDate(!oA)
P'I!# sDateStrin5G ; is o-r start time.;
+$I# =.9
P'I!# CDate(!oA)G ; is one secon) later.;
P'I!# CDate(sDateStrin5)G ; is still Ahere Ae starte).;
+$I# =.9
P'I!# !oAG ; is one secon) later.;
!D
9?MB=MB99C B9OCBO@9 is o-r start time.
9?MB=MB99C B9OCBO@= is one secon) later.
9?MB=MB99C B9OCBO@9 is still Ahere Ae starte).
13%
9?MB=MB99C B9OCBO@B is one secon) later.
C&loat
C7&oat converts an e6pression into a /&oating point number# Be care/u&S >he current
&oca&i0ation is :O> used b' this /unction# Gambas &anguage s'nta6 isC
1loat 6 C1loat ( xpression )
E6amp&eC
PUBLIC SUB Main()
DIM s1loatStrin5 $S Strin5
DIM *1loat!-m $S 1loat
s1loatStrin5 6 ;9.>>;
*1loat!-m 6 9.9=
P'I!# *1loat!-m H C1loat(s1loatStrin5)
P'I!# C1loat(;/.9H/;)
!D
=
/999
Considering &oca&i0ation (L"$: issues /or the use o/ C7LOA>, the di//erent usage o/ A,B
and A#B bet,een the @#2# and European &anguages re&ies on the de/au&t code page that is in use
,hen the app&ication is e6ecuted# >he code ,or-s but is entire&' dependent on the native code
page used on the e6ecutab&e p&at/orm, not the designMprogrammer p&at/orm# <hen
programming, shou&d L"$: be a consideration, a&,a's consider ,hat the end4user p&at/orm
shou&d be and program according&'# <e ,i&& discuss internationa&i0ation (+"*: and L"$:
&ater in this boo-#
CInt ' Cinteger an CShort
C+nt is s'non'mous ,ith C+nteger# Either ca&& converts an e6pression into an integer#
>he standard Gambas &anguage s'nta6 isC
Inte5er 6 CInt ( xpression )
Inte5er 6 CInte5er ( xpression )
C2hort converts an e6pression into a short integer# E6pression is /irst converted into an
13+
integer# >hen, i/ this integer over/&o,s the short range, it is truncated# =ere is the Gambas
&anguage s'nta6 /or C2hortC
Short 6 CShort ( xpression )
=ere is an e6amp&e that s&ight&' modi/ies the previous conso&e e6amp&e to sho, both o/
these /unctionsC
PUBLIC SUB Main()
s1loatStrin5 6 ;9.>>;
*1loat!-m 6 =B9.>9=
P'I!# *1loat!-m H C1loat(s1loatStrin5)
P'I!# CInt(*1loat!-m)G ; Aas a *loat0 noA an int.;
P'I!# CShort(*1loat!-m)G ; Aas a *loat0 noA a short.;
!D
>he resu&t isC
=B=.?>=
=B9 Aas a *loat0 noA an int.
=B9 Aas a *loat0 noA a short.
CStr ' CString
C2tr M C2tring converts an e6pression into a string# Be care/u&S >he current &oca&i0ation
is :O> used b' this /unction# =ere is ho, the Gambas &anguage s'nta6 /or C2tr ,or-sC
Strin5 6 CStr ( xpression )
Strin5 6 CStrin5 ( xpression )
E6amp&eC
PUBLIC SUB Main()
*1loat!-m 6 =B9.>9=
s1loatStrin5 6 CStr(*1loat!-m)
P'I!# s1loatStrin5G ; is noA a strin5.;
!D
140
Conso&e output isC
=B9.>9= is noA a strin5.
He+2
=e6U returns the he6adecima& representation o/ a number# +/ -igits is speci/ied, the
representation is padded ,ith unnecessar' 0eros so that .igits digits are returned# =ere is the
Gambas &anguage s'nta6C
Strin5 6 :ex[ ( !-mber " 0 Di5its % )
=ere is an e6amp&e programC
PUBLIC SUB Main()
12' co-nter 6 = #2 =C
P'I!# :ex[(co-nter0B)G; ;G
!7#
!D
>his is the resu&tC
9= 9B 9/ 9@ 9C 9F 9X 9? 9> 9$ 9B 9C 9D 9 91
Con/2
ConvU converts a string /rom one charset to another# A charset is represented b' a
string &i-e 3A2C++3, 3+2O4**G)4"3, or 3@>74*3# >he GA1BA2 interpreter interna&&' uses the
@>74* charset# >he charset used b' the s'stem is returned b' a ca&& to 2'stem#Charset# +t is
+2O4**G)4" on 1andra-e )#; operating s'stem, but it is @>74* on a Red=at Linu6 operating
s'stem# +n the /uture, near&' a&& Linu6 s'stems ,i&& probab&' be @>74* based# >he charset
used b' the graphica& user inter/ace is returned b' a ca&& to .es-top#Charset# +t is @>74* ,ith
the Ht component# >he Gambas &anguage s'nta6 isC
Converte)Strin5 6 Conv[(Strin5 $S Strin50 So-rceCharset $S Strin50 DestinationCharset $S Strin5 )
>he conversion re&ies on the iconv() G:@ &ibrar' /unction# =ere is a code e6amp&e to
tr'C
PUBLIC SUB Main()
DIM sStr $S Strin5
141
DIM iIn) $S Inte5er

sStr 6 Conv[(;.ambas;0 ;$SCII;0 ;BCDIC,US;)
12' iIn) 6 = #2 Len(sStr)
P'I!# :ex[($sc(Mi)[(sStr0 iIn)0 =))0 B)G ; ;G
!7#
!D
=ere is the outputC
CX ?= >@ ?B ?= $B
Val an Str2
!a& converts a string into a Boo&ean, a number or a date, according to the content o/ the
string# >he current &oca&i0ation is used to convert numbers and dates# >he conversion
a&gorithm uses the /o&&o,ing order o/ precedenceC

If string can ! int!r"r!t!# as a #at! $ ti%! &'it( #at! )r ti%! s!"arat)rs*+ t(!n t(! #at! $ ti%! is r!t,rn!#-
E.s! if string can ! int!r"r!t!# as a f.)ating ")int n,%!r+ t(!n a f.)ating ")int n,%!r is r!t,rn!#-
E.s! if string can ! int!r"r!t!# as a int!g!r n,%!r+ t(!n an int!g!r n,%!r is r!t,rn!#-
E.s! if string is TRUE )r FALSE+ t(! %atc(ing B)).!an /a.,! is r!t,rn!#-
E.s! NULL is r!t,rn!#-
2tandard Gambas &anguage s'nta6 isC
xpression 6 (al (Strin5)
2trU converts an e6pression into its printab&e string representation# +t is the e6act contrar' o/
!a&( # >he current &oca&i0ation is used to convert numbers and dates# Gambas &anguage
s'nta6 isC
Strin5 6 Str[ ( xpression )
>r' thisC
PUBLIC SUB Main()
DIM sDate#ime $S Strin5
DIM )Date $S Date
P'I!# !oAG ; is c-rrent system time.;
sDate#ime 6 (al(Str[(!oA))
P'I!# sDate#imeG ; is a strin5 representation o* c-rrent system time.;
P'I!# (al(sDate#ime)G ; is ($L conv o* the strin5 representation.;
142
)Date 6 (al(sDate#ime)
P'I!# )DateG ; is the D$# variable converte) Aith ($L.;
P'I!# Str()Date)G ; is a strin5 representation o* the )ate variable.;
!D
=ere is the outputC
9?MB=MB99C B=O@BO@C is c-rrent system time.
9?MB=MB99C B=O@BO@C is a strin5 representation o* c-rrent system time.
9?MB=MB99C B=O@BO@C is ($L conv o* the strin5 representation.
9?MB=MB99C B=O@BO@C is the D$# variable converte) Aith ($L.
9?MB=MB99C B=O@BO@C is a strin5 representation o* the )ate variable.
=ere is another samp&e program to tr'C
PUBLIC SUB Main()
DIM sInp-tLine $S Strin5
DIM val-e $S (ariant
D2 +:IL sInp-tLine UK ;I-it;
P'I!# ;66K ;G
LI! I!PU# sInp-tLine
I1 sInp-tLine 6 ;; #:!
sInp-tLine 6 ;UC'L1K;
!DI1
P'I!# ;Wo- type)O ;G sInp-tLine
val-e 6 (al(sInp-tLine)
P'I!#
I1 IsBoolean(val-e) #:!
P'I!# sInp-tLineG ; is Boolean.;
LS I1 IsDate(val-e) #:!
P'I!# sInp-tLineG ; is a )ate.;
LS I1 IsInte5er(val-e) #:!
P'I!# sInp-tLineG ; is an Inte5er.;
I1 val-e 6 9 2' val-e 6 = #:!
P'I!# ;It co-l) also be Boolean.;
!DI1
I1 val-e K 9 $!D val-e U BCC #:!
P'I!# ;It co-l) also be a Byte.;
143
!DI1
I1 val-e K ,/BXFX $!D val-e U /BXF? #:!
P'I!# ;It co-l) also be a short.;
!DI1
P'I!# ;,,,,,,,,,,,,,,;
LS I1 Is1loat(val-e) #:!
P'I!# sInp-tLineG ; is a *loat.;
LS I1 IsStrin5(val-e) #:!
P'I!# sInp-tLineG ; is a strin5.;
LS I1 Is!-ll(val-e) #:!
P'I!# sInp-tLineG ; is !ULL.;
LS
P'I!# sInp-tLineG ; is somethin5 else.;
!DI1
L22P
P'I!#
P'I!# ;+e are )oneV;
!D
>he output shou&d be simi&ar to thisC
66K tr-e
Wo- type)O tr-e
tr-e is Boolean.
66K B=@
Wo- type)O B=@
B=@ is an Inte5er.
It co-l) also be a Byte.
It co-l) also be a short.
,,,,,,,,,,,,,,
66K 9?MB/M9C =BOB/OCC
Wo- type)O 9?MB/M9C =BOB/OCC
9?MB/M9C =BOB/OCC is a )ate.
66K 4ohn
Wo- type)O 4ohn
4ohn is a strin5.
66K ,/BXCF
Wo- type)O ,/BXCF
144
,/BXCF is an Inte5er.
It co-l) also be a short.
,,,,,,,,,,,,,,
66K I-it
Wo- type)O I-it
I-it is a strin5.
+e are )oneV
:ote that the +s2tring /unction (used above and discussed be&o, is apparent&' e&iminated in
GambasD#
&ormat2
7ormatU converts an e6pression to a string b' using a /ormat that depends on the t'pe
o/ the e6pression# 7ormat can be a prede/ined /ormat (an integer constant or a user4de/ined
/ormat (a string that depicts the /ormat# +/ 7ormat is not speci/ied, gb#2tandard component
/ormats are used# >his /unction uses &oca&i0ation in/ormation to /ormat dates, times and
numbers# >he Gambas &anguage s'nta6 isC
Strin5 6 1ormat[ ( xpression " 0 1ormat % )
A user4de/ined number /ormat is described b' the /o&&o,ing charactersC
!or"t $y"/ol Mening
3F3 prints the sign o/ the number#
343 prints the sign o/ the number on&' i/ it is negative#
3]3 prints a digit on&' i/ necessar'#
3$3 a&,a's prints a digit, padding ,ith a 0ero i/ necessar'#
3#3 prints the decima& separator#
3R3 mu&tip&ies the number b' "$$ and prints a per4cent sign#
3E3 introduces the e6ponentia& part o/ a /&oat number# >he sign o/ the
e6ponent is a&,a's printed#
14#
A user4de/ined date /ormat is described b' the /o&&o,ing charactersC

!or"t $y"/ol Mening
3''3 prints 'ear using t,o digits#
3''''3 prints 'ear using /our digits#
3m3 prints month#
3mm3 prints month using t,o digits#
3mmm3 prints month in an abbreviated string /orm#
3mmmm3 prints month in it's /u&& string /orm#
3d3 prints da'#
3dd3 prints da' using t,o digits#
3ddd3 prints ,ee- da' in an abbreviated /orm#
3dddd3 prints ,ee- da' in its /u&& /orm#
3M3 prints date separator#
3h3 prints hour#
3hh3 prints hour using t,o digits#
3n3 prints minutes#
3nn3 prints minutes using t,o digits#
3s3 prints seconds#
3ss3 prints seconds using t,o digits#
3C3 Prints a time separator#
=ere is a program that demonstrates severa& e6amp&esC
PUBLIC SUB Main()
P'I!# ;,,,,,,,,,,,,,,,,,,,,,,,,,,,,,;
P'I!# ;User,)e*ine) n-meric 1ormat examplesO ;
P'I!# 1ormat[(Pi0 ;,<.<<<;)
P'I!# 1ormat[(Pi0 ;H9<.<<<9;)
P'I!# 1ormat[(Pi M =90 ;<<<.< ^;)
P'I!# 1ormat[(,== P ==0 ;<.<<<<;)
P'I!# ;,,,,,,,,,,,,,,,,,,,,,,,,,,,;
P'I!# ;User )e*ine) )ate an) time *ormat examplesO;
P'I!#
P'I!# 1ormat[(!oA0 ;mmM))Myyyy hhOnnOss;)
P'I!# 1ormat[(!oA0 ;mM)Myy hOnOs;)
P'I!# 1ormat[(!oA0 ;))) )) mmm yyyy;)
148
P'I!# 1ormat[(!oA0 ;)))) )) mmmm yyyy;)
!D
=ere is the outputC
,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
User,)e*ine) n-meric 1ormat examplesO
/.=@B
H9/.=@=F
/=.@ ^
,B.?CH==
,,,,,,,,,,,,,,,,,,,,,,,,,,,
User )e*ine) )ate an) time *ormat examplesO
9?MB=MB99C B=OCCO=@
?MB=M9C B=OCCO=@
S-n B= $-5 B99C
S-n)ay B= $-5-st B99C
!atatype management
1an' times ,hen chec-ing variab&es, it is important to -no, ,hat data4t'pe 'ou are
dea&ing ,ith# Gambas provides a host o/ /unctions /or that purpose# Kou can chec- /or the
/o&&o,ing data4t'pesC
IsBoolean M BooleanJ IsByte M ByteJ
IsDate M DateJ Is1loat M 1loatJ
IsInte5er M Inte5erJ Is!-ll M !-llJ
Is!-mber M !-mberJ Is2b3ect M 2b3ectJ
IsShort M ShortJ IsStrin5 M Strin5J
Each o/ the /unctions above are ca&&ed using the standard Gambas &anguage s'nta6 o/
Boolean'es-lt 6 IsBooleanJ ( xpression )
Boolean'es-lt 6 IsByteJ ( xpression )
Boolean'es-lt 6 IsDateJ ( xpression )
Boolean'es-lt 6 Is1loatJ ( xpression )
Boolean'es-lt 6 IsInte5erJ ( xpression )
Boolean'es-lt 6 Is!-llJ ( xpression )
Boolean'es-lt 6 Is!-mberJ ( xpression )
Boolean'es-lt 6 Is2b3ectJ ( xpression )
Boolean'es-lt 6 IsShortJ ( xpression )
Boolean'es-lt 6 IsStrin5J ( xpression )
14?
and the given /unction ,i&& return >R@E i/ an e6pression is o/ the data4t'pe 5ueried or 7AL2E
i/ it is not#
>'peO/
>'peO/ returns the t'pe o/ an e6pression as an integer va&ue# Gambas has de/ined
severa& prede/ined constants /or the data4t'pes returned b' this /unction# >he prede/ined
constants Gambas supports are sho,n in the tab&e be&o,# >he standard Gambas &anguage
s'nta6 /or this /unction isC
#ype 6 #ype2* ( xpression )
Predefined data-type constants
#t.type 'lue
gb#:u&& :u&& va&ue
gb#Boo&ean Boo&ean va&ue
gb#B'te B'te integer number
gb#2hort 2hort integer number
gb#+nteger +nteger number
gb#7&oat 7&oating point number
gb#.ate .ate and time va&ue
gb#2tring Character string
gb#!ariant !ariant
gb#Ob9ect Ob9ect re/erence
>hat's about a&& ,e ,i&& cover in this chapter# +n the ne6t chapter, ,e ,i&& return to the
Gambas >oo&Bo6 and start &earning to use some o/ the more advanced contro&s, such as
iconvie,, &istvie,, etc# Kou shou&d no, be ade5uate&' prepared to dea& ,ith more advanced
data hand&ing techni5ues re5uired /or those contro&s#
14%
Chapter / 0d.anced Contros
+n this chapter, ,e are going to stud' the a /e, o/ the more advanced contro&s, such as
the +con!ie,, List!ie,, Grid!ie,, Co&umn!ie, and >abstrip in order to &earn ho, to use
them# 7or the +con!ie, contro&, ,e are going to ta-e a di//erent approach this time, using one
o/ the e6amp&e programs provided b' Gambas# <e are going to use the E6p&orer program
,ritten b' Gambas creator Benoit 1inisini and go through ever' &ine o/ code to understand
e6act&' ,hat is going on in the program and ho, the +con!ie, contro& is used#

%con4iew Contro*
7irst o/ a&&, &et's consider a /eature that 'ou have seen be/ore, but 'ou ,i&& encounter
more /re5uent&' in this e6amp&e# Kou are /ami&iar ,ith subroutine dec&arations &i-eC
PUBLIC SUB 1orm8DblClick()
PUBLIC SUB hB-tton8Click()
PUBLIC SUB Combobox8Chan5e()
B' de/au&t, (ame=Event(ame is the name o/ the method ca&&ed in the event A&istenerB
(a detector bui&t into the Gambas interpreter, ,hen an event is raised# +n Chapter "D, 'ou ,i&&
read more about the Aevent4drivenB programming paradigm, but at this point 9ust note that
these subroutine names are not arbitrar'# Rather, the' con/orm to the s'nta6 needed to raise
bui&t4in Gambas events, ,here the name o/ the event is preceded b' the underscore character
(ALB# +n the /o&&o,ing code, ,e ,i&& encounter other events, &i-e LActivate, LRename, and
others, so remember that this s'nta6 is meaning/u&#
:oteC >he program AE6amp&esB that are inc&uded ,ith Gambas are set to Aread4on&'B# >his
prevents a&tering the programs in an' ,a', and prevents us /rom seeing the Properties setup
on the 71ain#/orm page# >his can ma-e some o/ the program operations seem a &itt&e
m'sterious# A /u&&' editab&e version o/ the E6p&orer program has been inc&uded in the .!.
that accompanies this boo- & it has been named E6p&orer"# Kou ma' pre/er to save that
version to dis-, and /o&&o, it ,hen stud'ing this section# Re/er to Appendi6 B /or A9ai&brea-B
instructions to enab&e editing /or an' o/ the programs /ound in Gambas E6amp&es#
2tart Gambas and se&ect the E6p&orer pro9ect /rom the 1isce&&aneous section o/ the
E6amp&e programs as sho,n in the /o&&o,ing /igure# Once 'ou se&ect the E6p&orer pro9ect, the
+.E ,i&& open up and ,e ,i&& need to get to the code# .o this b' doub&e4c&ic-ing on the c&ass
/i&e or i/ the /orm is a&read' up, doub&e4c&icon a contro& and then move to the top o/ the code
,indo,# Either ,a' ,i&& ,or- as &ong as 'ou start at the top o/ the code ,indo, ,here 'ou see
the /irst &ineC
3 Gambas class >ile
14+
>he /irst thing ,e see done in this code is the dec&aration o/ the program's g&oba&
variab&es# :ote that the' are pre/i6ed ,ith a 'U' character /or c&arit' in recogni0ing them# >he
>s3ath variab&e is dec&ared as PR+!A>E and used to ho&d the name o/ the current /i&e path#
P'I($# [sPath $S Strin5
>b4idden is a PR+!A>E Boo&ean variab&e that ,i&& act as a /&ag to be used to determine
+7 a /i&e is hidden or not# <e ,i&& use the $tt /unction to chec- its status# (2ee Chapter ) /or
an e6p&anation o/ the $tt /unction#
P'I($# [b:i))en $S Boolean
>bCtrl is a PR+!A>E Boo&ean used as a /&ag ,hen a C>RL -e' is pressed# +/ the user
ho&ds do,n the C>RL -e' ,hen doub&e4c&ic-ing on a /o&der it ,i&& open up in a ne, ,indo,#
P'I($# [bCtrl $S Boolean
>his is the /irst subroutine Gambas ,i&& e6ecute ,hen the program is runC
S#$#IC PUBLIC SUB Main()
>he ne6t t,o &ines ,i&& dec&are a &oca& variab&e /or the /orm ,e ,ant to disp&a' to the
user and create an instance o/ the /orm named +Eplorer, passing the parameter
System.4ome to a constructor, ,hich is identi/ied as =new(), and ,hich ta-es a string
1#0
Figure %/: hoosing the -8plorer e8ample.
parameter s3ath (2'stem#=ome the va&ue o/ ,hich ,e obtained /rom the 2'stem c&ass#
DIM h1orm $S 1orm
h1orm 6 !+ 1xplorer(System.:ome)
:o, that the /orm ob9ect has been &oaded into memor' (AinstanciatedB, sho, the
/ormC
h1orm.ShoA
!D
>his ne6t subroutine is the constructor that is ca&&ed ,hen the 1ain( subroutine is
activated and the 7E6p&orer /orm is instantiatedC
PUBLIC SUB 8neA(sPath $S Strin5)
!=new# is a specia& method ca&&ed ,hen a ne, ob9ect is instantiated# +t is used to set the initia&
conditions o/ the ne,&' created ob9ect# >he Lne, parameter(s comes direct&' /rom the
immediate&'4preceding :E< parameter(s#
<e ,i&& assign the path passed in (2'stem#=ome as a parameter to our g&oba& variab&e
UsPathC
[sPath 6 sPath
7ina&&', ,e must ca&& the subroutine Re/reshE6p&orer( to popu&ate the iconvie, contro&
named iv,E6p&orer to re/resh the disp&a' /or the ne, contro&C
'e*reshxplorer
!D
=ere is the Re/reshE6p&orer( subroutine# +t is essentia&&' the meat o/ the programC
P'I($# SUB 'e*reshxplorer()
7irst, ,e dec&are the &oca& variab&es# Let's start ,ith a string variab&e to ho&d /i&e namesC
DIM s1ile $S Strin5
:e6t, dec&are picture variab&es /or our icon imagesC parent director', /o&der and /i&eC
DIM hPictDir $S Pict-re
1#1

DIM hPict1ile $S Pict-re
c-ir is an arra' o/ strings (representing the names o/ /i&es or directoriesC
DIM cDir $S !+ Strin5"%
s(ame is a ,or- string used to represent /i&enames /ound in a director'C
DIM s!ame $S Strin5

>his ca&& increments the ABus'B propert' va&ue that is de/ined in the App&ication c&ass
(in the Ht &ibrar'# <hen this propert' is set to a va&ue greater than 0ero, the mouse cursor is
&oc-ed to a Abus'B state to sho, that the app&ication is bus', and does not respond to user4
initiated events# Kou increment this propert' at the start o/ a &ong 9ob and decrement at
the comp&etion o/ that 9ob, in order to prevent the user /rom inter/ering ,ith the 9ob
comp&etion#
I!C $pplication.B-sy
Once the !don$t interrupt me# /&ag is thro,n, ,e set the ,indo, tit&e to the s'stem path
and ca&& the bui&t4in Conv7 /unction to convert the s'stem charset (the set of characters the
operating system has provided as default) to ,hat the user has de/ined as the des-top charset
(the set of characters the user has chosen to see from their des&top). :ote that Conv is a
s'non'm /or Conv7 and 'ou can use either one interchangab&'#
M.#itle 6 Conv([sPath0 System.Charset0 Desktop.Charset)
:ote that, in the ne6t &ine o/ code, Aiv,E6p&orerB is a Contro& &ocated on our /orm,
,hich Benoit 1inisini created b' using the +con!ie, too& /rom the Ht /orm too&bo6, and so
this ob9ect be&ongs to the Gambas c&ass 3+con!ie,3# (+/ 'ou are using Gambas to vie, the
E6p&orer c&ass /i&e, ,hich is Aread4on&'B, the Properties tab and too&bo6 are not visib&e, so it
isn't immediate&' obvious ,hat iv,E6p&orer is# :o,, in the ne6t &ine, ,hatever ma' e6ist in
the icon vie, is ,iped out b' ca&&ing the +con!ie,'s C&ear methodC
ivAxplorer.Clear
:e6t, assign icons to the picture variab&es ,e dec&ared# <e have an icon to represent
/o&ders and one /or /i&esC
hPictDir 6 Pict-re";iconOM@?M)irectory;%
hPict1ile 6 Pict-re";iconOM@?M*ile;%
+/ the g&oba& path variab&e is not set to the highest &eve& (i.e., the parent) indicated b'
1#2
the 3M3 string, then ,e ,ant to create a /o&der that the user can c&ic- to go to the parent
director' o/ the current chi&d# <e add this /o&der to the iconvie, contro& named iv,E6p&orer
b' using its Add methodC
I1 [sPath UK ;M; #:! ivAxplorer.$))(;D..;0 ;..;0 hPictParDir)
+n the statement above, the #Add method ta-es three parameters# >he /irst is the name
o/ the -e', in this case A.##B ,hich is our -e' /or directories# >he second is the te6t p&aced
be&o, the icon in the iconvie,, and the /ina& parameter is the name o/ the variab&e that is a
hand&e to the /i&ename o/ the icon ,e ,ant to disp&a' ,ith this entr'# :o,, ,e ,i&& begin to
&oop through ever' /i&e in the current director' to see i/ it is a hidden /i&e or not and to tag each
/i&ename as either a director' or a /i&e#

12' $C: s1ile I! Dir([sPath)
Gambas initia&i0es strings to nu&& ,hen created, so the ver' /irst time ,e come here, the
Ub=idden va&ue ,i&& not be >R@E and the +7 stmt ,i&& be e6ecuted in the code be&o,C
I1 !2# [b:i))en #:!
>his ne6t &ine o/ code is a &itt&e tric-er to decipher# >he $tt /unction ta-es a /i&ename
string as its parameter# +n this case, the current path he&d in g&oba& variab&e >s3ath is
catenated ,ith the ,or- string s+ile using the :A s'mbo& combination# >his is a specia&
catenation s'mbo& used in Gambas speci/ica&&' to catenate /i&enames# >he $tt /unction is
ca&&ed ,ith the catenated /i&ename passed as a parameter and simu&taneous&' the
$tt16idden propert' is chec-ed# +/ the $tt16idden propert' is set to a >R@E va&ue, the
CO:>+:@E statement e6ecutes, /orcing program /&o, to the ne6t iteration o/ the 7OR &oop#
>his ,ho&e process basica&&' /orces the program to ignore an' hidden /i&es it encounters#
I1 Stat([sPath SM s1ile).:i))en #:! +is it -i..en/
C2!#I!U + i! so0 (o to ne$t loop iteration
!DI1 +12 Stat
!DI1 +12 N3# 45Hi..en
+/ ,e reached this point in the code, the /i&e ,as not hidden# :o,, ,e ,i&& use the bui&t4
in /i&e management /unction *s#ir to see i/ the current path and /i&e string (catenated in the
2tat ca&& is a /o&der or a /i&e# +/ ,e have a /o&der, ,e ,i&& add it to the c.ir string arra', /irst
tagging it ,ith a &etter '.' /or director' or '7' /or /i&e and then appending the /i&ename he&d in
the ,or-string s7i&e to the '.' or '7' tagC
I1 IsDir([sPath SM s1ile) #:! +it was a .ire&tor6
cDir.$))(;D; S s1ile) +we a.. 78 to t-e !ilename0 to ta( it as a .ire&tor6
LS +not a .ire&tor6 an. we a.. 728 to t-e !ilename0 to ta( it as a !ile
cDir.$))(;1; S s1ile)
1#3
!DI1
!7# + t-is is t-e en. o! t-e 239 loop:::
Once ever'thing is &oaded in the c.ir arra' ,ith the 7ORM:EQ> &oop ,e ca&& the bui&t4
in 2ort method and sort the arra' o/ stringsC
cDir.Sort
:o, that the c.ir arra' is sorted, ,e ,i&& &oop through the arra' using the 7OR EAC=
statement ,hich is used speci/ica&&' /or enumerated ob9ects in arra's or co&&ections#
12' $C: s1ile I! cDir
7or ever' string in the c-ir arra', ,e ,i&& /i&& the ,or- string s(ame ,ith the name o/
the /i&e# =o,ever, ,e have to remove the tag /irst# <e ,i&& use the Mid7 bui&t4in string
/unction to ta-e a&& the &etters o/ the string a/ter the /irst (our tag starting at position ; in the
stringC
s!ame 6 Mi)[(s1ile0 B)
:o,, ,e chec- the tag o/ the /i&ename using the string /unction )eft7C
I1 Le*t[(s1ile) 6 ;D; #:!
+/ the '.' tag is /ound, it is a director' and ,e add a director' to the +con!ie, contro&
using the Add method and our picture o/ a /o&der as the &ast parameter in the ca&&#
ivAxplorer.$))(s1ile0 s!ame0 hPictDir)
LS + ot-erwise it was a !ile an. we a.. it wit- a !ile i&on
ivAxplorer.$))(s1ile0 s!ame0 hPict1ile)
!DI1

>he /o&&o,ing &ine is commented out in 1inisini's code# =e set the 1Edit/le propert'
to >R@E in the /orm Properties tab, so this &ine is redundant here#
TivAxplorer.Item.)itable 6 #'U
!7# + e$it t-e 239 EACH ;oop
>he statements be&o, ,ere commented out but appear to have been used to a&ter the
sort order o/ the +con!ie, contro&# <e ,i&& simp&' s-ip over these comments and go to the
7+:ALLK statementC
+i<wE$plorer:Sorte. = 2A;SE
+i<wE$plorer:As&en.in( = #9>E
1#4
+i<wE$plorer:Sorte. = #9>E

1I!$LLW + t-is is t-e last instru&tion to e$e&ute in t-e su5routine
>he &ast thing ,e need to do is set the App&ication#bus' /&ag bac- to norma& stateC
DC $pplication.b-sy
+/ an error occurs, ,e ,i&& catch it ,ith the catch c&ause be&o,C
C$#C:
+/ an' error occurs, it shou&d pop up a message bo6 ,ith the error te6t disp&a'edC
Messa5e.rror(rror.#ext)

!D + o! our 9e!res-E$plorer routine
+/ 'ou are using Gambas to vie, the E6p&orer c&ass /i&e, ,hich is Aread4on&'B, 'ou aren't
ab&e to see the menu bar contro& on the /orm# =o,ever, 'ou can see the resu&ting menu bar
,hen 'ou run the program# +/ the user chooses the 5uit option /rom the menu, then this
routine e6ecutesC
PUBLIC SUB mn-Y-it8Click()
M.Close
!D
+/ the user se&ects the Re/resh option /rom the 7i&e menu (visib&e ,hen 'ou run the
program, ,e ,i&& ca&& the Re/reshE6p&orer subroutine described previous&'#
PUBLIC SUB mn-(ieA'e*resh8Click()
'e*reshxplorer
!D
>his subroutine is ca&&ed ,hen the activate event is triggered b' a user b' doub&e4
c&ic-ing on a /o&der in the +con!ie, contro&C
PUBLIC SUB ivAxplorer8$ctivate()
As a&,a's, ,e must dec&are our &oca& variab&es# <e dec&are s:e,Path as a string to
ho&d the /i&epath /or the target path the user c&ic-ed (either a ne, /o&der or the root /o&der#
A&so, i/ the contro& -e' (C>RL is pressed ,hen the destination is se&ected# ,e dec&are a ne,
/orm to sho, the destination contents, h7orm, in a separate ,indo,#
1##
DIM s!eAPath $S Strin5
DIM h1orm $S 1orm
>he /o&&o,ing *! statement &oo-s at the tag ,e put on the string to see i/ the destination
is a director' or the root &eve& o/ the s'stem# +/ ,e are at the root &eve&, then ,e simp&' return#
Other,ise, the code ,i&& assign the catenated va&ues o/ UsPath and the va&ue he&d b' the
),$&1Current1Key o/ the +con!ie, contro&# >his is obtained ,ith the Mid7 ca&& starting at
position ; (to b'pass our tag character#
I1 L$S#.C-rrent.Qey 6 ;D..; #:!
I1 [sPath 6 ;M; #:! '#U'!
s!eAPath 6 1ile.Dir([sPath)
LS
s!eAPath 6 [sPath SM Mi)[(L$S#.C-rrent.Qey0 B)
!DI1
<e chec- the ne,&' assigned string va&ue data4t'pe to ensure it is, in /act, a director'
and, i/ it is, ,e ,i&& subse5uent&' chec- to see i/ the user he&d do,n the contro& -e'#
Remember, ho&ding do,n the contro& -e' in our program ,i&& activate a ne, ,indo,, ,hich is
,h' ,e dec&ared the &oca& h7orm variab&e#
I1 IsDir(s!eAPath) #:!
+/ the contro& -e' ,as he&d do,n, ,e ,i&& togg&e the va&ue bac- to 7AL2E be/ore
instantiating a ne, ,indo,# >hen, ,e ,i&& move our contro& to be o//set "I pi6e&s right and
be&o, the current ,indo,, having the same height and ,idth using the h7orm#1ove method#
7ina&&', ,e sho, the /orm and re/resh the E6p&orer ,ith our Re/reshE6p&orer subroutine#

I1 [bCtrl #:!
[bCtrl 6 1$LS
h1orm 6 !+ 1xplorer(s!eAPath)
h1orm.Move(M.7 H =F0 M.W H =F0 M.+0 M.:)
h1orm.ShoA
LS
Othe,ise, the contro& -e' ,as not he&d do,n so ,e simp&' assign the s:e,Path va&ue to
the g&oba& UsPath and re/resh the e6p&orerC
[sPath 6 s!eAPath
'e*reshxplorer
!DI1
!DI1
!D
1#8
<hen the user c&ic-s this routine, it ca&&s our subroutine to sho, the hidden /i&es or, i/
the' are sho,ing, turn o// vie,ing o/ hidden /i&esC
PUBLIC SUB mn-(ieA:i))en8Click()
#o55le(ieA:i))en
!D
+/ the user chooses to sho, hidden /i&es in the e6p&orer b' se&ecting the 2ho, =idden
7i&es option, then this ne6t routine is e6ecuted# >he /irst &ine chec-s the va&ue o/ the
mnu!ie,=idden#Chec-ed propert' and togg&es the va&ue b' essentia&&' ma-ing Ub=idden
become ,hatever the &ogica& :O> va&ue o/ mnu!ie,=idden#Chec-ed is at the moment it is
chec-ed# +t then assigns the opposite va&ue to the propert' and re/reshes the vie, b' ca&&ing
Re/reshE6p&orer# >he resu&t is that the hidden /i&es are sho,n#
P'I($# SUB #o55le(ieA:i))en()
[b:i))en 6 !2# mn-(ieA:i))en.Checke)
mn-(ieA:i))en.Checke) 6 [b:i))en
'e*reshxplorer
!D
>his subroutine is e6ecuted ,hen the menu's about item is c&ic-ed# +t simp&' disp&a's a
message bo6 crediting the code to the Gambas /ounder, B# 1inisiniC
PUBLIC SUB mn-$bo-t8Click()
Messa5e(;Icon(ieA example Aritten byNnBeno_t Minisini;)
!D
>he ne6t subroutine is e6ecuted ,hen the user sing&e4c&ic-s on an item in the e6p&orer
and opts to rename the item# As it ,as origina&&' ,ritten, it does not chec- to see i/ the rename
actua&&' changed the item# 7or e6amp&e, i/ the user pressed E2C, the item ,ou&d revert to its
origina& name#
PUBLIC SUB ivAxplorer8'ename()
Messa5e(; T ; S Mi)[(L$S#.Item.Qey0 B) S ; T has been rename) to T ; S L$S#.Item.#ext S ; T ;)
!D
<e can remed' this b' changing the code to read &i-e thisC
PUBLIC SUB ivAxplorer8'ename()
I1 Mi)[(L$S#.Item.Qey0B) UK Last.Item.#ext #:!
Messa5e(; T ; S Mi)[(L$S#.Item.Qey0B) S ; T has been rename) to T ; S L$S#.Item.#ext S ; T ;)
LS
Messa5e(D T E S Mi)[(L$S#.Item.Qey0B) S D T Aas le*t -nchan5e).T E)
!DI1
1#?
!D
>he /ina& t,o subroutines togg&e the g&oba& variab&e UbCtr& ,henever the contro& -e' is
pressed or re&eased#
PUBLIC SUB ivAxplorer8QeyPress()
I1 Qey.Control #:! [bCtrl 6 #'U
!D
PUBLIC SUB ivAxplorer8Qey'elease()
I1 Qey.Control #:! [bCtrl 6 1$LS
!D
>here 'ou have it# Ever'thing 'ou need to -no, about using the +con!ie, contro& in a
coo& app&ication# :e6t, ,e ,i&& &oo- at the List!ie, contro&#
&ist4iew Contro*
>he )ist'iew contro& inherits Contro& and imp&ements a &ist o/ se&ectab&e te6t items
,ith icons# List!ie, items are inde6ed b' a -e'# >he' disp&a' a string and an icon# >his
contro& has an interna& cursor used /or accessing its items# Kou must use the Move methods (
1oveAbove, 1oveBe&o,, 1oveCurrent, 1ove7irst, 1oveLast, 1ove:e6t 1ovePrevious,
1ove>o to move the interna& cursor, and 'ou need to use the +tem propert' to get the te6t o/
the item the cursor points at# >his c&ass is creatab&e and the standard ca&&ing convention isC
DIM hList(ieA $S List(ieA
hList(ieA 6 !+ List(ieA ( Parent $S Container )
>he above code creates a ne, List!ie, contro& that acts &i-e a read4on&' arra'# Let's
create a program that ,i&& imp&ement the List!ie, contro&# Create a ne, pro9ect named
List!ie, that is a Ht graphica& user inter/ace t'pe pro9ect# <hen the +.E appears a/ter 'ou go
through the pro9ect ,i0ard, create a simp&e /orm that &oo-s &i-e the /igure be&o,#
1#%
Figure %0: >a$out (or our >ist4ie. e8ample.
7rom the &e/t top o/ the picture, 'ou have our List!ie, contro& named List!ie,", a
>e6tbo6 named >e6tbo6", and the +nsert +tem button named Button"# >here are t,o
radiobuttons, named RadioButton" and RadioButton; and the Remove +tem button named
Button;# At the botton o/ the /orm is a >e6tLabe& named >e6tLabe&" and the Huit button
named ButtonD#
Once 'ou have created the /orm and made it a startup c&ass, ,e need to add the /o&&o,ing code
to the code ,indo, to see ho, to imp&ement a List!ie, contro&C
T .ambas class *ile
sStat-s as Strin5
DIM picSI-are $S !+ Pict-re
picSI-are 6 picSI-are.Loa) (;sI-are.pn5;)
+n the above, ,e used the Picture c&ass variab&e 3pic25uare3 in order to return a va&ue (a
bitmap using the 3Load3 method# >he variab&e Apic25uareB then accepts the returned va&ue
(the bitmap# 2'nta6C Picture#Load(/i&ename Current&', Picture can accept #png, #9pg,
#bmp, #gi/, and #6pm /i&e /ormats# Actua&&', i/ 'ou dimension a Picture variab&e ,ith an' other
name, that a&so ,or-s# 7or e6amp&eC .+1 picQKV A2 :E< Picture, ,hich cou&d then be used
in the statementC pic25uare W picQKV#Load(3s5uare#png3# +t is mere&' /or convenience that
,e use pic25uare#Load in the code, since ,e have a&read' dimensioned pic25uare as a Picture
c&ass variab&e#
>he /o&&o,ing &ines ,i&& add an item to the List!ie, ,ith a starting entr'
List(ieA=.$)) (;ListItem=;0;ListItem=;0 picSI-are)
#extLabel=.#ext 6 List(ieA=.Item.#ext
List(ieA=8Click
!D
<hen the program begins and the /orm is /irst disp&a'ed on4screen, the routine above
is e6ecuted# <e create t,o &oca& variab&es /or our icons that ,i&& be used in the &ist and &oad
them into memor'# :e6t, ,e add a de/au&t -e' and item to the &ist using the List!ie,"#Add
method, speci/'ing the pic25uare icon to be associated ,ith this item# .on't ,orr' about the
icons /or no, ,e ,i&& create them &ast# :e6t, ,e need to create an event to re/resh the &ist
an'time an item is added or it is c&ic-ed on b' the user#
PUBLIC SUB List(ieA=8Click()
List(ieA=.Item.Selecte) 6 #'U +2irst0 i.enti!6 t-e item as sele&te.:
List(ieA=.MoveC-rrent +#-en0 mo<e t-e &ursor to t-e sele&te. item:
#extLabel=.#ext 6 List(ieA=.Item.#ext S sStat-s
!D
1#+
+n the List!ie,"LC&ic- subroutine, the /irst &ine o/ code identi/ies the current item as
Ase&ectedB b' setting the +tem#2e&ected to >R@E, then moves the interna& cursor to the most
current item# >his ,a', ,hen 'ou add an' ne, items, the' ,i&& automatica&&' be high&ighted#
7ina&&', the third &ine updates our >e6tLabe&"#>e6t va&ue ,ith the te6t o/ the current (or ne,&'
added se&ection and the current status (he&d in g&oba& var s2tatus A2 2tring appended# +/ the
user c&ic-s on the +nsert item button (we named it 9utton8, this ne6t routine is e6ecutedC
PUBLIC SUB B-tton=8Click()
.ec&are a &oca& variab&e, pic>o@se, /or our icon to be disp&a'edC
DIM pic#oUse $S !+ Pict-re
:e6t, chec- ,hich radioButton has been c&ic-ed# +/ the /irst button has been c&ic-ed, ,e
,i&& &oad the image /or s5uare#png, other,ise, circ&e#png is &oaded#
I1 #extbox=.#ext UK !ULL #:!
I1 'a)ioB-tton=.(al-e #:!
pic#oUse 6 pic#oUse.Loa)(;sI-are.pn5;)
LS
pic#oUse 6 pic#oUse.Loa)(;circle.pn5;)
!D I1
:o, ,e ,i&& add a ne, entr' ,ith a -e' and name in the te6t bo6C
List(ieA=.$))(#extbox=.#ext0#extbox=.#ext0pic#oUse)
>his empties out te6tbo6C
#extBox=.#ext 6 ;;
sStat-s 6 ; c-rrent.; Tset stat-s to Dc-rrentE
>his ca&& to the List!ie,"LC&ic- subroutine ,i&& update (re/resh our List!ie, contro&C
List(ieA=8Click
:e6t, ,e must ensure the ne, item is in the visib&e area o/ the contro&C
List(ieA=.Item.ns-re(isible
!D I1
!D
>he Button;LC&ic- subroutine is ca&&ed ,henever the user decides to de&ete the
current&' se&ected item in the List!ie, contro&#
180
PUBLIC SUB B-ttonB8Click()
>his ne6t &ine o/ code gets out cursor &ined up to the current se&ection# >he
1oveCurrent method moves the interna& cursor to the current item# +t returns a >R@E va&ue
i/ there is no current item, in ,hich case ,e ,i&& simp&' return as there is nothing to de&eteC
I1 List(ieA=.MoveC-rrent() #:! '#U'!
+/ ,e reached this point, ,e have moved the cursor to and need to remove the current
cursor itemC
List(ieA=.'emove(List(ieA=.Item.#ext)
C&ean up our >e6tLabe&"#>e6t disp&a' ,ith this ca&&C
#extLabel=.#ext 6 ;;
:o,, ,e need to update the cursor position to the ne, current item (since ,e are no,
pointed at a de&eted item# But /irst, ,e need to chec- the #Count propert' to see i/ ,e have
9ust de&eted the &ast item in the &ist# +/ the count is greater than 0ero, then ,e have items &e/t in
the &ist# Other,ise, the +7 statement ,i&& not be true and the code ,i&& be b'passedC
I1 List(ieA=.Co-nt K 9 #:!
List(ieA=.MoveC-rrent
A/ter the #Remove method is e6ecuted, the current item becomes the item be&o, the
removed item in the &ist, un&ess the removed item ,as the &o,est4do,n item on the &ist 44 in
that case, the current item becomes the ne, &o,est do,n item on the &ist# >his determines the
ne, position o/ the interna& cursor estab&ished b' #1oveCurrent#
List(ieA=.Item.Selecte) 6 #'U TSelects the c-rrent item
:ote that /or remova& o/ items, the order o/ #1oveCurrent and #+tem#2e&ected must be
reversed, compared to the List!ie,"LC&ic- subroutine#
sStat-s 6 D selecte).E
List(ieA=8Click Tthis Aill *orce an -p)ate o* the #extLabel text.
!D I1
!D
+/ the user c&ic-s their mouse on an item in the List!ie, contro&, this routine is ca&&ed#
<e ,i&& simp&' update the >e6tLabe&"#>e6t propert' ,ith the te6t o/ the item se&ected and
re/resh the List!ie, contro& b' ca&&ing our List!ie,"LC&ic- subroutine#
181
PUBLIC SUB List(ieA=8Select()
#extLabel=.#ext 6 List(ieA=.Item.#ext
sStat-s 6 D selecte).E
List(ieA=8Click
!D
+/ the user doub&e4c&ic-s their mouse on an item in the List!ie, contro&, it ,i&& raise the
LActivate event, indicating the user has pic-ed this item /or some action to occur# +n this
case, ,e ,i&& simp&' update the >e6tLabe&"#>e6t propert' ,ith the te6t o/ the item se&ected,
appended ,ith the ,ord AactivatedB, and re/resh the List!ie, contro& b' ca&&ing our
List!ie,"LC&ic- subroutine#
PUBLIC SUB List(ieA=8$ctivate()
#extLabel=.#ext 6 List(ieA=.Item.#ext S D activate).E
sStat-s 6 D activate).E
List(ieA=8Click
!D
:ote that the LActivate event is triggered b' a doub&e4c&ic-, 9ust &i-e .b&C&ic-#
=o,ever, .b&C&ic- is triggered A:K<=ERE on 'our contro&, inc&uding 'our items, scro&&bars,
buttons, or an' part o/ 'our contro&# >here/ore, i/ 'ou ,ant to enab&e users to doub&e4c&ic- an
item in a &ist, as in List!ie,, use LActivate#
+/ the user c&ic-s their mouse on the ButtonD (Huit button, this routine is ca&&ed# <e
,ant to e6it c&ean&' so ,e invo-e the c&ose method /or the /orm using the 1E#C&ose ca&&#
PUBLIC SUB B-tton/8Click()
M.Close
!D
)sing the G+ %con Edit Too*
As 'ou ma' a&read' be a,are, an icon is a sma&& pictogram used in graphica& user
inter/aces to supp&ement the presentation o/ te6tua& in/ormation to the user
"D
# 1odern
computers can hand&e bitmapped graphics ,ith ease, so icons are ,ide&' used to assist users#
+cons ,ere /irst deve&oped as a too& /or ma-ing computer inter/aces easier /or novices to grasp
in the ")J$s, at the Qero6 Pa&o A&to Research Center /aci&it'# +con4driven inter/aces ,ere &ater
popu&ari0ed b' the App&e 1acintosh, the Amiga and the 1icroso/t <indo,s operating
environments#

A computer icon usua&&' ranges /rom "I b' "I pi6e&s up to ";* b' ";* pi6e&s# 2ome
operating s'stems /eature icons up to G"; b' G"; pi6e&s# +con si0e can be re&ated to the si0e o/
13 6e>er to httpG99en.wikipedia.org9wiki9ComputerHicon >or more in>ormation about icons.
182
the graphica& output device or to the amount o/ in/ormation that must be disp&a'ed# !ision4
impaired users (due to such conditions as poor &ighting, tired e'es, medica& impairments,
bright bac-grounds, or co&or b&indness ma' need the abi&it' to use &arger icons#
At this point, a&& the code is created /or our List!ie, e6amp&e program# <e sti&& need to
create the circ&e#png and s5uare#png icons# <e ,i&& use the GB icon editor to do that# >o
bring up the icon editor, ,e ,i&& go to the Pro9ect <indo, in the +.E# +n the Pro9ect
>ree!ie,, /ind the .ata /o&der and right4c&ic- 'our mouse# Pic- the :e, item and the +mage
subitem# Kou ,i&& see this dia&og pop upC
2imp&' t'pe As5uareB in the :ame /ie&d and c&ic- o-# :o,, the icon editor appears and
'ou can create an icon# @se the rectang&e option /rom the +conEditor >oo&bo6 and create a
b&ue s5uare and save it ,ith the dis-4shaped icon#
183
Figure )1: reating a ne. +con image in G=.
Figure )3: Aur circle icon
image.
Figure )2: Aur s<uare icon
image.
Figure )1: The +con -"itor Toolbo8.
Repeat this process, creating another icon named Acirc&e#pngB and save that too# >hat is itS
Kour program is read' to run# >r' it out and see ho, the List!ie, contro& ,or-s#
The Tree4iew Contro*
>he >ree!ie, contro& ,or-s a&most identica&&' to the List!ie, contro&# >he chie/
di//erence is that the >ree!ie, supports nested Achi&drenB and a&&o,s 'ou to traverse /rom an
inner (chi&d &eve& out,ard to the parent o/ the chi&d, a&& the ,a' out to the top o/ the tree#
>his contro& adds a /e, methods speci/ica&&' /or the purpose o/ managing the traversa& o/ the
parentMchi&d trees# >ree!ie,, &i-e a&& other contro&s, inherits its attributes /rom the Contro&
c&ass# >his contro& imp&ements a tree vie, o/ se&ectab&e te6t items ,ith icons#
>ree vie, items are inde6ed b' a -e'# >he' disp&a' a string and an icon /or each item#
>his contro& has an interna& cursor used /or accessing its items# @se the 1ove methods (1ove,
1oveAbove, 1oveBac-, 1oveBe&o,, 1oveChi&d, 1oveCurrent, 1ove7irst, 1oveLast,
1ove:e6t, 1oveParent, 1ovePrevious, 1ove>o to move the interna& cursor, and the +tem
propert' to get the item it points at# >his c&ass is creatab&e# >he standard ca&&ing convention
isC
DIM h#ree(ieA $S #ree(ieA
h#ree(ieA 6 !+ #ree(ieA ( Parent $S Container )
>he code above creates a ne, >ree!ie, contro&# >his c&ass acts &i-e a read4on&' arra'C
DIM h#ree(ieA $S #ree(ieA
DIM h#ree(ieAItem $S .#ree(ieAItem
h#ree(ieAItem 6 h#ree(ieA " Qey $S Strin5 %
>he &ine o/ code above ,i&& returns a >ree!ie, item /rom its -e'# >he interna& cursor is moved
to the current item# :o,, &et's use an e6amp&e program /rom the .!. inc&uded ,ith this
boo-# 2tart Gambas and se&ect the >ree!ie," samp&e program (this is based on the >ree!ie,
e6amp&e /rom Gambas# <hen the +.E opens up, 'ou shou&d see thisC
184
Figure )#: Tree'ie. e8ample.
:e6t, doub&e4c&icon the >ree!ie," /orm and bring up the /orm# .oub&e c&icon the
/orm to open up the code edit ,indo, and 'ou ,i&& see the /o&&o,ing &isting, ,hich ,e ,i&&
dissect &ine b' &ine to understand ho, it ,or-sC
T .ambas class *ile
PUBLIC intvent!-mber $S Inte5er
>he g&oba& variab&e intEvent:umber is used to trac- the number o/ events that occur
/or our event stac-# Each time ,e process an event, ,e ,i&& increment this variab&e# <e
dec&are t,o &oca& Picture variab&es, pic1a&e and pic7ema&e and &oad them into memor' /or the
program b' using the Picture#Load method#
DIM picMale $S !+ Pict-re
DIM pic1emale $S !+ Pict-re
pic1emale.Loa)(;1emale.pn5;)
picMale.Loa) (;Male.pn5;)
T#his Aill pop-late o-r treevieA Aith o-r startin5 entries
T!oteO 3-st keep the entries text an) their keys the same to keep it simple
:e6t, ,e ,i&& add the starting va&ues o/ our >ree!ie, contro&# <e ,i&& add /our items to
the contro&# Each item -e' ,i&& be the same as the item name# >he items >ed and 2a&&' ,i&& be
chi&dren o/ item Bi&&, ,hi&e items 7ran- and Barbara ,i&& be chi&dren o/ 2a&&'#
#ree(ieA=.$)) (;Bill;0;Bill;0 picMale) TBill has no parent (in o-r #ree(ieA)0 so no @
th
parameter.
#ree(ieA=.$)) (;#e);0;#e);0picMale0;Bill;)
#ree(ieA=.$)) (;Sally;0;Sally;0pic1emale0;Bill;)
#ree(ieA=.$)) (;1rank;0;1rank;0picMale0;Sally;)
#ree(ieA=.$)) (;Barbara;0;Barbara;0pic1emale0;Sally;)T#he syntax isO #ree(ieA.$))(DQeyE0 E#extE0 Pict-re"name%0 DParent QeyE)
+n order to see the /u&& >ree!ie, a/ter opening the program, ,e indicate that the nodes shou&d
be e6panded b' de/au&tC
#ree(ieA=";Bill;%.xpan)e) 6 #'U
#ree(ieA=";Sally;%.xpan)e) 6 #'U
!D
((/TE* the 5ambas ?i&i documentation for this property lists it as Epand, not
Epanded. :sing Epand will (/T wor&.)
>he ne6t subroutine updates the >e6tLabe& so that ,e -no, ho, man' chi&dren an
18#
entr' has# <e /ind out ,hether the item c&ic-ed is a parent (determined b' ,hether or not it
has chi&dren# +/ the number o/ chi&dren is greater than one, ,e ,ant our &abe&
(>e6tLabe&"#>e6t to use the p&ura& /orm o/ chi&d# +/ there is on&' one chi&d, our &abe& ,i&& sa'
chi&d, and i/ there are none, ,e ,ant it to sa' the item has no chi&dren# <e use the +7
>=E:MEL2E statement to ma-e this chec-C
P'I($# SUB 'e*reshIn*o() TDeclare) P'I($# to protect s#ext *rom bein5 chan5e) elseAhere
DIM s#ext $S Strin5
I1 !2# #ree(ieA=.C-rrent #:! Ti* a c-rrent item )oes not exist0
#extLabel=.#ext 6 DE Tclear the #extLabel box.
'#U'! Tan) exit the s-bro-tine.
!DI1
+n the /o&&o,ing te6t b&oc-, note that the properties #Chi&dren, #>e6t, #Q, #K, #<, and #=
can a&& be read ,ithout p&acing 3>ree!ie,"3 in /ront# 2ince, b' de/au&t, the' read the
properties o/ the current item, it is not necessar' to t'pe >ree!ie,"#>e6t, etc# =o,ever, 'ou
CA: optiona&&' t'pe the &ong /orm, i/ 'ou ,ant to ma-e this e6p&icit#
+I#: #ree(ieA=.C-rrent #:!
I1 .Chil)ren K = #:!
s#ext 6 .#ext S D has no chil)ren.E
LS I1 .Chil)ren 6 9 #:!
s#ext 6 .#ext S D has = chil).E
!D I1
TIn the next line0 ;s#ext S6 ...; is eI-ivalent to ;s#ext 6 s#ext S ....;
s#ext S6 DUbrKItem rect is (D S .7 S D0E S .W S D0E S .+ S D0E S .: S D)E
TUbrK is :#ML *or ;line break;.
As previous&' discussed, a >e6tLabe& contro& can accept =>1L /ormatting#
#extLabel=.#ext 6 s#ext
!D

+/ the user enters data in the >e6tbo6 contro& and c&ic-s the +nsert :ame button
(9utton8, the /o&&o,ing c&ic-4event is e6ecuted# +t /irst dec&ares t,o &oca& variab&e# >he s+con
variab&e ,i&& determine ,hich picture to &oad based on ,hich RadioButton ,as c&ic-ed at the
time the +nsert :ame button ,as c&ic-ed# >he string variab&e, sParent, is assigned the va&ue o/
the current item's -e'# +/ the 1oveCurrent method tries to move the interna& cursor to the
current item and there is no item, it returns >R@E# Other,ise, 7AL2E ,i&& be returned and
,e assign the sParent string the va&ue o/ the -e' that is current#
DIM sParent $S Strin5
I1 #extbox=.#ext UK !ULL #:!
188
I1 'a)ioB-tton=.(al-e #:!
sIcon 6 ;Male.pn5;
LS
sIcon 6 ;1emale.pn5;
!D I1
T.ets the parent itemO the c-rrent item0 or nothin5 i* the treevieA is voi)
sParent 6 #ree(ieA=.Qey
:o,, ,e need to add the ne, entr' ,ith a -e' and a name o/ ,hat ,as in the te6t bo6#
<e ,i&& p&ace it in the >ree!ie, contro& as a chi&d o/ the current&' se&ected entr'# :ote that
the -e' names must be uni5ue or it ,i&& crash the program# <e cou&d use the E6ist method to
/ind out i/ a -e' e6ists ,ith the name >e6tbo6"#>e6t be/ore ma-ing the ca&& to the Add method,
but that ,as not done here# +/ ,e did that, the code ,ou&d ma-e a chec- simi&ar to thisC
I1 xist(#extbox=.#ext) UK #'U #:!
#ree(ieA=.$))(#extbox=.#ext0#extbox=.#ext0sIcon0 sParent)
!DI1
=o,ever, the code in the program simp&' /orces the Add method to ta-e the
>e6tbo6"#>e6t and put it in the &istC
#ree(ieA=.$))(#extbox=.#ext0#extbox=.#ext0Pict-re"sIcon%0 sParent).ns-re(isible
#extBox=.#ext 6 ;; T#his empties o-t textbox
'e*reshIn*o T#his -p)ates the label0 an) re*lects the neA n-mber o* ki)s.
!D I1
!D
>he ca&& to Ensure!isib&e ,i&& ma-e sure that the item ,e 9ust added to the &ist is in the
visib&e area o/ the contro&# +/ necessar', the contro& ,i&& scro&& so the item is visib&e# Rather
than sharing a &ine ,ith the #Add method, the same command cou&d a&so be used on a separate
&ineC
#ree(ieA=.Item.ns-re(isible
+/ the user ,ants to remove a name /rom the >ree!ie, b' c&ic-ing the Remove :ame
button (9utton@) then this subroutine is e6ecutedC
7irst o/ a&&, ,e must get the cursor &ined up to our current se&ection and ma-e sure that
the current item isn't an empt' or nu&& va&ue# +/ the 1oveCurrent method returns a true va&ue,
the &ist ,as empt' and ,e are done# >he code invo-es the RE>@R: ca&& and ,e 9ump bac- to
the ca&&ing process# Other,ise, ,hatever the current item is ,i&& be removed b' ca&&ing the
>ree!ie,"#Remove method in the second &ine, be&o,C
18?
I1 #ree(ieA=.MoveC-rrent() #:! '#U'!
TLets remove the c-rrent c-rsor item
+t is necessar' to de4se&ect the current item be/ore de&eting it, or e&se 'our de&etions ,i&&
&eave Aghost itemsB in the >ree!ie,, and a&so disorder the icons# >he current item is sti&&
current, even ,hen it is de4se&ected, and 'ou don't have to name another item as current the
Gambas interpreter ,i&& hand&e that# >here/ore, use the ne6t &ine to de4se&ect the item being
removed, then use the &ine a/ter that to remove it#
#ree(ieA=.C-rrent.Selecte) 6 1$LS
#ree(ieA=.'emove(#ree(ieA=.Item.#ext)
:o, ,e must move the cursor to the current item (since ,e are no, pointing at a
de&eted item# Be/ore ,e do that ,e need to chec- the count propert' to ma-e sure ,e didn't
de&ete the &ast item in the &ist# +/ ,e did, then ,e obvious&' don't run this part o/ the code# >he
+7 statement chec-s /or a count greater than 0ero and, i/ >R@E, ,i&& move to the current item,
se&ect it so the cursor is high&ighted, and update the contro& ,ith a ca&& to the >ree!ie,"LC&ic-
subroutine#
I1 #ree(ieA=.Co-nt K 9 #:!
#ree(ieA=.MoveC-rrent
T#his selects or Thi5hli5htsT o-r c-rrent item
#ree(ieA=.Item.Selecte) 6 #'U
T#his Aill -p)ate o-r label an) re*lect the neA n-mber o* ki)s
'e*reshIn*o
#ree(ieA=8Delete T#his Aill -p)ate the event stack.
!D I1
!D
+/ the user c&ic-s on the minus icon in the >ree!ie, contro&, it sets o// a Co&&apse event#
>he routine be&o, is ca&&ed# +t simp&' updates the event stac-, as described previous&', and
increments the event counter, intEvent:umber, b' one#
PUBLIC SUB #ree(ieA=8Collapse()
T#his 3-st -p)ates o-r event stack
Stack8vent8Lo5(DCollapseE)
!D
+/ the user doub&e4c&ic-s on an item in the >ree!ie, contro&, it sets o// a .b&LC&ic-
event# +t is basica&&' the same as an Activate event# >he routine be&o, is ca&&ed# +t simp&'
updates the event stac-, as described previous&', and increments the event counter,
intEvent:umber, b' one#
18%
PUBLIC SUB #ree(ieA=8DblClick()
Stack8vent8Lo5(DDblClickE)
!D
PUBLIC SUB #ree(ieA=8Select()
'e*reshIn*o
Stack8vent8Lo5(DSelectE)
!D
PUBLIC SUB #ree(ieA=8Delete()
Stack8vent8Lo5(DDeleteE)
!D
+/ the user c&ic-s on the p&us icon in the >ree!ie, contro&, it sets o// an E6pand event#
>he routine be&o, is ca&&ed# +t simp&' updates the event stac-#
PUBLIC SUB #ree(ieA=8xpan)()
Stack8vent8Lo5(Dxpan)E)
!D
#ext$rea=.#ext 6 ;;
!D
>he 6elp Q ,/out menu item generates a c&ic- event that ca&&s this ne6t subroutine# +t
simp&' gives credit to the origina& authors, C# Pac-ard and 7abien =utre&#
PUBLIC SUB $bo-t8Click()
Messa5e.In*o (;#ree(ieA example Aritten by C. Packar) an) 1abien :-trel.NnMo)i*ie) an) rename) by 4on !icholson)
!D
:ote that in the above te6t, 'ou can use the ATnB contro& code to ma-e a &ine brea- in a
1essageBo6# A&ternative&', 'ou cou&d brea- the string apart and concatenate ,ith PChr("$,
,hich a&so e6ecutes a &ine brea-#
+/ the user doub&e4c&ic-s on an item in the >ree!ie, contro&, it sets o// an Activate
event# +t is simi&ar to a .b&C&ic- event in that LActivate is triggered b' doub&e4c&ic-ing, 9ust
&i-e L.b&C&ic- is# =o,ever, the L.b&C&ic- event is raised ever',here in the contro&, even on
interna& scro&&bars, buttons, etc# @se LActivate ,hen 'ou ,ant to &imit the c&ic-ab&e area to
speci/ic item choices in a contro&, as in List!ie, and >ree!ie,# <hen the routine be&o, is
18+
ca&&ed, it simp&' updates the event stac-#
PUBLIC SUB #ree(ieA=8$ctivate()
Stack8vent8Lo5(D$ctivateE)
!D
>his ne6t routine is dead code# +t never gets e6ecuted because nothing creates an event
to get here# >o use it e//ective&', a menu item, Rename, shou&d be added to the =e&p menu
and it shou&d be ca&&ed /rom the 1enu+tem#C&ic- event# +/ this is done, then the event ,ou&d
be generated and 'ou cou&d ,rite a bit o/ code to get the ne, name /rom the user and change
it# >he event stac- ,ou&d be proper&' updated, /irst ,ith the rename event and then ,ith the
c&ic- event#
PUBLIC SUB #ree(ieA=8'ename()
Stack8vent8Lo5(D'enameE)
!D
Ever' subroutine uses the /o&&o,ing sub to update the event stac-# >he string variab&e
AaneventB is dec&ared in the sub dec&aration and receives the string parameter passed b' the
ca&&ing subroutines, above#
P'I($# SUB Stack8vent8Lo5(anevent $S Strin5)
T#his -p)ates o-r event stack an) )isplays the c-rrent no)e key.
DIM sQey as Strin5
In the ne2t line) the meaning o> the s*nta2 QT6C /tatementQis that T6C tries to e2ecute a
statement) without raising an error i> the attempt >ails.

#'W sQey 6 #ree(ieA=.Item.Qey
In the ne2t line) note that the new e"ent is concatenated with the e2isting TestArea1 bo2
contents) but that a line break IRnJ is included so that each new e"ent will be on its own line at the top
o> the stack.
#ext$rea=.#ext 6 Dvent(D S intvent!-mber S D)O D S anevent S D ItemO TO S sQey S DTNnE S #ext$rea=.#ext
intvent!-mber 6 intvent!-mber H =
!D
>hat is a&& there is to the >ree!ie, program# Kou can p&a' around ,ith the code and
imp&ement the suggestions made herein# Once 'ou are ab&e to understand ho, to use these
contro&s e//ective&', 'our GB inter/aces ,i&& become more sophisticated# :e6t, ,e ,i&& ta-e a
&oo- at the &ast t,o advanced vie, contro&s, the Grid!ie, and Co&umn!ie, contro&s#
1?0
The Grid4iew Contro*
>he Grid!ie, contro&, &i-e a&& the other contro&s in the too&bo6, inherits its attributes
/rom the Contro& c&ass# Grid!ie, imp&ements a contro& that disp&a's data in a grid# >his c&ass
is creatab&e# 2tandard ca&&ing convention /or Grid!ie, isC
DIM h.ri)(ieA $S .ri)(ieA
h.ri)(ieA 6 !+ .ri)(ieA ( Parent $S Container )
>he code above ,i&& create a ne, Grid!ie,# >his c&ass acts &i-e a read4on&' arra'# >o
retrieve the contents o/ a ce&& in the grid, use this code to dec&are a GridCe&& variab&e that can
read the Grid!ie, arra' ( the GridCe&& is a virtua& c&assC
DIM h.ri)(ieA $S .ri)(ieA
DIM h.ri)Cell $S ..ri)Cell
h.ri)Cell 6 h.ri)(ieA " 'oA $S Inte5er0 Col-mn $S Inte5er %
>he &ine above returns a ce&& /rom its ro, and its co&umn# Our e6amp&e program /or
this contro& ,i&& create a grid that is /our ro,s o/ three co&umns# <e ,i&& popu&ate the /irst
three ro,s ,ith te6t and the &ast ro, ,ith pictures# <e ,i&& ta-e the &ast ro, o/ te6t and
demonstrate ho, the a&ignment propert' ,or-s /or te6t data# Our program ,i&& have three
buttons, Huit, C&ear, and Reset#
>he Huit button ,i&& simp&' c&ose the program# C&ear ,i&& invo-e the Grid!ie,#C&ear
method to erase the contents o/ the grid and disp&a' empt' grid ce&&s# >he Reset button ,i&&
repopu&ate the contents o/ the grid ,ith the data the program started ,ith (i#e#, the data
popu&ated ,hen the /orm's constructor method ,as ca&&ed# Our program ,i&& &oo- &i-e thisC
>o begin, start Gambas and se&ect the :e, Pro9ect option, choosing to create a H>
pro9ect# 1a-e the pro9ect trans&atab&e and /orm contro&s pub&ic b' chec-ing the t,o bo6es in
the <i0ard# :ame the pro9ect Grid!ie,, and give it the Atit&eB o/ AGrid!ie, E6amp&eB#
1?1
Figure )%: What our Gri"4ie. .ill loo3 li3e.
<hen the +.E appears, ,e ,i&& need to go to the pro9ect ,indo, and bring up the +CO:
Editor# <e ,i&& create three icons, named GridPic, GridPic", and GridPic;, as sho,n above#
@se the "I pi6e&s b' "I pi6e&s setting, and tr' to get them reasonab&' c&ose to ,hat 'ou see in
the picture above i/ 'ou can#
:e6t, create a ne, startup c&ass /orm and put the Grid!ie, contro&, named Grid!ie,"
on the /orm as sho,n above# >hen add the three buttons to the right o/ the Grid!ie,, named
AHuitB (Button", AC&earB (Button;, and AResetB (ButtonD to the /orm# Create three
>e6tBo6es underneath the Grid!ie,, and use the Properties tab to set the de/au&t te6t on
>e6tBo6; to ARo,B and on >e6tBo6D to ACo&umnB# Add t,o more buttons beneath the
Grid!ie,, and name them A+nsert dataB (Button( and ARedo Ro,MCo&umnB (ButtonG#
7ina&&', add a >e6tLabe& contro& at the bottom o/ the /orm, named >e6tLabe&"# :o,, ,e have
the /orm designed and it &oo-s &i-e ,hat ,e e6pect#
.oub&e4c&icon the /orm, but not on a contro&, and the 7ormLOpen subroutine ,i&&
disp&a' in the code ,indo,# <e ,i&& set the caption to 'our program hereC
T .ambas class *ile
1Main.Caption 6 ; .ri)(ieA xample ;
!D
<hen the program starts, i/ a constructor e6ists, it is e6ecuted /irst# Our constructor
,i&& &oad our three icons and popu&ate the grid# 7irst, dec&are three &oca& variab&es /or the
pictures, hPic", hPic;, and hPicD, as sho,n be&o,C
PUBLIC SUB 8neA()
DIM hPic= $S Pict-re
DIM hPicB $S Pict-re
DIM hPic/ $S Pict-re

:o,, ,e must instantiate the picture variab&es and &oad the pictures#
hPic= 6 !+ Pict-re
hPic= 6 hPic=.Loa)(;.ri)Pic=.pn5;)
hPicB 6 !+ Pict-re
hPicB 6 hPicB.Loa)(;.ri)PicB.pn5;)

hPic/ 6 !+ Pict-re
hPic/ 6 hPic/.Loa)(;.ri)Pic/.pn5;)
>he ne6t thing ,e need to do is de/ine the dimensions o/ the grid# Our grid ,i&& have
three co&umns and /our ro,s, so ,e set the Co&umns and Ro,s properties using their virtua&
c&ass gridco&umn and gridro, propert', count to set the ro,s and co&umns as sho,n be&o,C
1?2

.ri)(ieA=.Col-mns.Co-nt 6 /
.ri)(ieA=.'oAs.Co-nt 6 @
<e can a&so de/ine the ,idth and height dimensions o/ the grid co&umns and ro,s#
Bear in mind that it is possib&e to set di//erent height va&ues /or ever' ro, and di//erent ,idth
va&ues /or ever' co&umn# <e ,i&& set the the < and = properties /or our ro,s and co&umns as
sho,n be&o,C
.ri)(ieA=.Col-mns.+i)th 6 =@@
.ri)(ieA=.'oAs.:ei5ht 6 /F

:e6t, ,e ,i&& popu&ate the grid ,ith some data, simp&' identi/'ing the ro,,co&umn
position ,ith te6tC
.ri)(ieA="909%.#ext 6 ;909;
.ri)(ieA="90=%.#ext 6 ;90=;
.ri)(ieA="90B%.#ext 6 ;90B;

.ri)(ieA="=09%.#ext 6 ;=09;
.ri)(ieA="=0=%.#ext 6 ;=0=;
.ri)(ieA="=0B%.#ext 6 ;=0B;
7or the &ast te6t ro,, ,e ,ant to demonstrate ho, to use the A&ignment propert'C
.ri)(ieA="B09%.$li5nment 6 $li5n.Center
.ri)(ieA="B0=%.$li5nment 6 $li5n.BottomLe*t
.ri)(ieA="B0B%.$li5nment 6 $li5n.#op'i5ht

A/ter setting the a&ignment properties /or each ce&& in the ro,, ,e ,i&& add te6tC

.ri)(ieA="B09%.#ext 6 ;B09;
.ri)(ieA="B0=%.#ext 6 ;B0=;
.ri)(ieA="B0B%.#ext 6 ;=0B;
7ina&&', ,e ,i&& add our three icons to the grid# :ote that, i/ ,e ,anted to, ,e cou&d a&so add
te6t to the same ce&&s the t,o datat'pes can e6ist and be disp&a'ed in a ce&& at the same time#
.ri)(ieA="/09%.Pict-re 6 hPic=
.ri)(ieA="/0=%.Pict-re 6 hPicB
.ri)(ieA="/0B%.Pict-re 6 hPic/
!D
>he constructor is comp&ete# :o,, doub&e4c&icon the Huit Button to get the
Button"LC&ic- event subroutine, ,here ,e ,i&& add our 1e#C&ose ca&& to shut do,n the
1?3
programC
M.Close
!D
>he C&ear button is ne6t# .oub&e4c&icon the C&ear Button to get the Button;LC&ic-
event subroutine, ,here ,e ,i&& add our code to reset the grid to b&an- va&uesC
.ri)(ieA=.Clear
!D
>he easiest ,a' to repopu&ate the data is to simp&' invo-e the constructor once again#
Add this code so that is ,hat ,e ,i&& do#
8neA
!D
:o,, a&&o, the user to edit te6t contained in the ce&&s# .oub&e4c&icon the A+nsert
dataB button (Button( and enter this codeC
PUBLIC SUB B-tton@8Click()
DIM ntere)Data $S Strin5
DIM 'oA $S Inte5er
DIM Col-mn $S Inte5er
Convert ,hatever ro,Mco&umn numbers the user t'pes into the >e6tBo6es into integers#
'oA 6 CInt(#extBoxB.#ext)
Col-mn 6 CInt(#extBox/.#ext)
+/ the user e6ceeds the permitted va&ues /or either the ro, inde6 or the co&umn inde6,
terminate the subroutine#
I1 'oA K / 2' Col-mn K B #:!
#extLabel=.#ext 6 ;UbKSorry0 'oAs m-st be 9,/ an) Col-mns m-st be 9,BUbK;
'#U'!
!DI1
ntere)Data 6 #extBox=.#ext
.ri)(ieA="'oA0 Col-mn%.#ext 6 #extBox=.#ext
!D
1?4
A&&o, the user to c&ic- one button to empt' the >e6tBo6es o/ the disa&&o,ed coordinates
and a&so empt' the error message in the >e6tLabe&# .oub&e4c&icon the AErase Ro,MCo&umnB
button (Button G and enter this codeC
PUBLIC SUB B-ttonC8Click()
#extBoxB.#ext 6 ;;
#extBox/.#ext 6 ;;
!D
7ina&&', ,hen the user c&ic-s around in the various ce&&s, the te6t contents and ce&&
coordinates ,i&& re/&ect in the >e6tBo6es# .oub&e4c&icon the Grid!ie, contro& on the /orm,
and enter this codeC
PUBLIC SUB .ri)(ieA=8Click()
DIM 'oA $S Inte5er
DIM Col-mn $S Inte5er
#extBox=.#ext 6 .ri)(ieA=.C-rrent.#ext
#extBoxB.#ext 6 .ri)(ieA=.'oA
#extBox/.#ext 6 .ri)(ieA=.Col-mn
!D
Our program is comp&ete# Run it and see ho, it ,or-s# A/ter 'ou are satis/ied that it
,or-s as advertised, c&ose it do,n and ne6t &et's &earn about the Co&umn!ie, contro& ne6t#
The Co*umn4iew Contro*
7or our ne6t e6amp&e, ,e are going to create a program that disp&a's data in a
Co&umn!ie,, as sho,n be&o,C
/tart a new proFect as a At graphical inter>ace program) and name it Column(iew. -hen the
I$! starts) open the 5@ain >orm) and use the toolbo2 to set up the Column(iew control and the three
button controls according to the >igure abo"e. Our simp&e e6amp&e ,i&& create three co&umns and
1?#
Figure )): Aur olumn4ie. e8ample.
/ive ro,s# <e ,i&& popu&ate the co&umn data ,ith the ro,,co&umn id o/ the particu&ar item# >o
do this, ,e ,i&& need to set the ,idth o/ each co&umn to be d'namica&&' ca&cu&ated based on the
,idth o/ the contro& and the number o/ co&umns speci/ied# <e ,i&& do this in the constructor#
<hen the program starts up, a&& ,e are going to do on the 7ormLOpen ca&& is set the ,indo,
caption, as sho,n in the 7ormLOpen( subroutine#
T .ambas class *ile
1orm=.Caption 6 ; Col-mn(ieA xample ;
!D
>he constructor method is ,here a&& the ,or- to popu&ate the contro& is done# <e need
to dec&are three &oca& integer variab&es, i,idth to ho&d the va&ue o/ the ca&cu&ated co&umn
,idth, iro,counter and ico&counter, ,hich are used /or our &oop structures#
PUBLIC SUB 8neA()
T )eclare o-r local vars
DIM iAi)th $S Inte5er
DIM iroAco-nter $S Inte5er
DIM icolco-nter $S Inte5er
Tset the n-mber o* col-mns to /
Col-mn(ieA=.Col-mns.Co-nt 6 /
Tcalc-late the col-mn Ai)th base) on the n-mber o* col-mns set
iAi)th 6 Col-mn(ieA=.+i)th M Col-mn(ieA=.Col-mns.Co-nt
T*or the *irst col-mn0 set the col-mn Ai)th an) a)) a col-mn title
Col-mn(ieA=.Col-mns"9%.+i)th 6 iAi)th
Col-mn(ieA=.Col-mns"9%.#ext6;1irstCol;
T*or the secon) col-mn0 set the col-mn Ai)th an) a)) a col-mn title
Col-mn(ieA=.Col-mns"=%.+i)th 6 iAi)th
Col-mn(ieA=.Col-mns"=%.#ext6;Secon)Col;
T*or the thir) col-mn0 set the col-mn Ai)th an) a)) a col-mn title
Col-mn(ieA=.Col-mns"B%.+i)th 6 iAi)th
Col-mn(ieA=.Col-mns"B%.#ext6;#hir)Col;
:o,, ,e need to set up the outer (ro, and inner (co&umn &oops# Basica&&', ,e ,i&&
&oop through ever' ever' ro, in the contro& and, at each ro,, ,e ,i&& &oop through each
co&umn, popu&ating the Co&umn!ie,"Zro,[Zco&umn[ arra' items ,ith a d'namica&&' bui&t
string o/ te6t that ,i&& represent the current position ,ithin the inner and outer &oop#

12' iroAco-nter 6 9 #2 @ T*or all *ive o* o-r roAs
Tcall the $)) metho) Aith "roA%"col% to a)) to Col-mn(ieA= control
Col-mn(ieA=.$))(iroAco-nter0 icolco-nter)Tstart o-ter (roA) loop
1?8
12' icolco-nter 6 9 #2 Col-mn(ieA=.Col-mns.Co-nt Z =
Ta)) text to the "roA%"col% item
Col-mn(ieA="iroAco-nter%"icolco-nter% 6 ;ColO ; S icolco-nter S ; 'oAO ; S iroAco-nter
!7# Tcol-mn
!7# TroA
!D To-r constr-ctor
>he Huit Button here ,or-s 9ust &i-e in the previous e6amp&e# >o get the Button"LC&ic-
event subroutine, doub&e4c&ic- and add the 1e#C&ose ca&& to shut do,n the programC
M.Close
!D
>he C&ear button is ne6t# .oub&e4c&icon the C&ear Button to get the Button;LC&ic-
event subroutine, ,here ,e ,i&& add our code to reset the grid to b&an- va&uesC
Col-mn(ieA=.Clear
!D
7or our Reset button, the easiest ,a' to repopu&ate the data is to simp&' invo-e the
constructor once again# Add this code to accomp&ish that#
8neA
!D
>hat is a&& there is to bui&ding and popu&ating the Co&umn!ie, contro&# >here are
severa& events that can be used to enhance the /unctiona&it' o/ our program# 7or e6amp&e, i/ a
user c&ic-ed on co&umn ; o/ ro, three, ,e cou&d use the LActivate event to a&&o, the user to
change the data /or that item# One method o/ accomp&ishing that is to modi/' the /orm as
sho,n in the /igure be&o,#
:e6t, add a >e6tLabe& to the bottom4&e/t o/ the Co&umn!ie,#contro&# P&ace a Labe&
underneath it, ,ith the te6t set as ARo,B# P&ace three >e6tBo6es underneath the Co&umn!ie,,
,ith three Labe&s underneath them, ,ith the te6t set as Co&umns ", ; and D# P&ace a Button to
the &o,er right o/ the Co&umn!ie,, and set the te6t as A@pdateB#
1??
Go to the top o/ the 71ain#c&ass page and insert the /o&&o,ing code immediate&' a/ter
the P(%)*C $(% !O+MMOPEN()111EN# %)OCKC
sQey as S#'I!. T$ 5lobal variable *or Aritin5 to the #extLabel.
1la5 $S Boolean T#his prevents incomplete )ata entry.
:e6t, go to the &ine that reads A!D To-r constr-ctorB# +n an empt' &ine immediate&' above that, t'pe
Initial#extBox
Go to the bottom o/ the code 'ou have a&read' input, and append this code to itC
T Start o* a))itional co)e
PUBLIC SUB Initial#extBox() T#his Aipes the #extBoxes clean0 *or clarity a*ter e)itin5.
sQey 6 Col-mn(ieA=.C-rrent.Qey TUp)ate the 'oA #extLabel in*ormation.
#extLabel=.#ext 6 CInt(sQey) H = TMost -sers Aill consi)er the *irst roA as 'oA =.
#extBox=.Clear
#extBoxB.Clear
#extBox/.Clear
1la5 6 1$LS
!D
+/ 'ou on&' ,ant to change data in one ro,Mco&umn &ocation, 'ou run the ris- o/ ,riting
/rom the other t,o (empt' >e6tBo6es (because 'ou update /rom a&& three >e6tBo6es at once#
>here/ore, /i&& the >e6tBo6es ,ith current data /irst, be/ore 'ou start editing# 2ince 'ou sing&e4
c&ic- to move around the Co&umn!ie,, 'ou ,ou&d have distracting and constant changes o/
&oaded data in the >e6tBo6es#, i/ ,e a&&o,ed editing a/ter sing&e4c&ic- events# >here/ore, it is
sa/er and c&eaner to &imit the &oading and updating o/ data to a doub&e4c&ic- LActivate event#
<e use the Boo&ean A7&agB variab&e to signa& this to the sub that hand&es updating#
PUBLIC SUB Col-mn(ieA=8$ctivate() T#his loa)s the c-rrent )ata.
sQey 6 Col-mn(ieA=.C-rrent.Qey
#extLabel=.#ext 6 CInt(sQey) H =
#extBox=.#ext 6 Col-mn(ieA=.C-rrent"9%
#extBoxB.#ext 6 Col-mn(ieA=.C-rrent"=%
1?%
Figure )*: Aur e"itable olumn4ie. e8ample.
#extBox/.#ext 6 Col-mn(ieA=.C-rrent"B%
1la5 6 #'U
!D
PUBLIC SUB B-tton@8Click() T#his alloAs yo- to -p)ate the )ata in the Col-mn(ieA.
I1 !2# 1la5 #:! '#U'! TPrevents over,Aritin5 )ata *rom empty #extBoxes. !o )o-ble,click (to loa) c-rrent )ata)0 no
e)itin5V
sQey 6 Col-mn(ieA=.C-rrent.Qey
Col-mn(ieA=.C-rrent"9% 6 #extBox=.#ext
Col-mn(ieA=.C-rrent"=% 6 #extBoxB.#ext
Col-mn(ieA=.C-rrent"B% 6 #extBox/.#ext
Initial#extBox
!D
PUBLIC SUB Col-mn(ieA=8Click() T#his -p)ates 'oA #extLabel0 *or *-n0
sQey 6 Col-mn(ieA=.C-rrent.Qey TAhen nothin5 else is 5oin5 on.
!D
Co&umn!ie, is ver' versiti&e in /act, 'ou can turn the /irst co&umn into a >ree!ie,SS
7or e6amp&e, i/ 'ou ,ere constructing a genea&og' program, 'ou ,ou&d use a&& o/ the same
s'nta6 as used ,ith >ree!ie,, /or the items that ,i&& be inserted into the /irst co&umn e6cept
'ou ,ou&d use ACo&umn!ie,"B instead o/ A>ree!ie,"BC
Col-mn(ieA=.$))(;Qey;0 ;!ame;0 pic.en)er0 DParentE)
2uccessive co&umns do not accept >ree!ie, s'nta6, so 'ou ,ou&d insert data in those ,ith the
ZRo,[ZCo&umn[ s'nta6 ,e have 9ust studied /or Co&umn!ie, (but not using Co&umn $ that's
no, occupied b' a >ree!ie,# 7or e6amp&e, Ro,$MCo&umn" cou&d ho&d birth date,
Ro,$MCo&umn" cou&d ho&d birth cit', etc# O/ course, 'ou ,ou&d use the appropriate co&umn
headings# =ave /unS
&ayout Contro*s 5 $+o6 4+o6 $Pane* and 4pane*
La'out properties determine the t'pe o/ positioning components ma' ta-e on that
pane&# 2ome La'outs a&&o, more e6act positioning than others, but each has its uses# >he bo6
&a'outs &a' out their chi&dren one a/ter the other# >he hori0onta& bo6 &a'out &a's out ,idgets in
a hori0onta& ro,, /rom &e/t to right, ,hi&e the vertica& bo6 &a'out &a's out ,idgets in a vertica&
co&umn, /rom top to bottom# Each pane& is given a La'out propert'# La'out properties can be
app&ied to a&& pane&s#
1?+
H(o+ an V(o+
Both o/ these c&asses are containers that arrange their chi&dren either hori0onta&&' or
vertica&&'# Li-e a&& other too&bo6 contro&s, the' inherit their attributes /rom the Container
c&ass# Both o/ these contro&s act &i-e a Pane& ,ithout a border ,hose Arrangement propert'
,ou&d be set to )rrange.4ori6ontal. >hese c&asses are creatab&e# 2tandard ca&&ing convention
to create a ne, =bo6 isC
DIM h:Box $S :Box
DIM h(Box $S (Box
h:Box 6 !+ :Box ( Parent $S Container )
h(Box 6 !+ (Box ( Parent $S Container )
H%anel an Vpanel
Both o/ these c&asses are containers that arranges their chi&dren /rom top to bottom,
and then &e/t to right /or the =pane& and &e/t to right, top to bottom /or the !Pane&# >he' are
both &i-e an ordinar' Pane& contro& ,ithout a border but ,hose Arrangement propert' ,ou&d
be set to )rrange.Top9ottom ( ,here a container stac-s its chi&dren /rom top to bottom\ i/ the
chi&dren contro&s can't /it vertica&&', a ne, co&umn o/ contro&s is started 9ust a/ter the previous
co&umn or )rrange.7eft0ight (,here a container stac-s its chi&dren /rom &e/t to right\ i/ the
chi&dren contro&s can't /it hori0onta&&', a ne, ro, o/ contro&s is started be&o, the previous
ro,# Both these t'pes o/ contro&s inherit their attributes /rom the Container c&ass# >his c&ass
is creatab&e# 2tandard ca&&ing convention isC
DIM h:Panel $S :Panel
DIM h(Panel $S (Panel
h:Panel 6 !+ :Panel ( Parent $S Container )
h(Panel 6 !+ (Panel ( Parent $S Container )
Let's create a simp&e program that ,i&& demonstrate each o/ these &a'out contro&s and
sho, ho, the' can be used in an app&ication# 7or this app&ication, start Gambas and create a
H> graphica& user inter/ace program# :ame it La'outs and doub&e4c&icon the 71ain icon to
open the startup c&ass /orm, 71ain#/orm# 7or this app&ication, ,e ,i&& need to use some icons#
1ost Linu64based distributions have icon /i&es stored in the /o&der namedC
/i&es'stemCMusrMshareMiconsMde/au&t4-deMD;6D;Mactions
Kour s'stem ma' be di//erent# Regard&ess o/ ,here 'ou /ind them, pic- out seven icons
and cop' them to the La'outs /o&der# 7or our purposes, an' seven ,i&& do but i/ 'ou can /ind
undo, redo, he&p, con/igure, co&ori0e, printer, and e6it t'pe icons it ,i&& be easier# =ere are the
icons ,e chose to use /or this pro9ectC
1%0
Our program is 5uite simp&e# <e are going to create an =Bo6, a !Bo6, an =Pane& and
a !Pane& and put some simp&e contro&s in each container# <e ,i&& simp&' update a te6t &abe&
to sho, ,hen something has been c&ic-ed# Our /orm ,i&& &oo- &i-e the one sho,n in /o&&o,ing
/igure (in design mode#
7rom the top &e/t o/ the /igure above, ,e start ,ith a !Bo6 and a >e6tLabe&# Be&o, the
>e6tLabe& is the =Bo6# <hen 'ou &oo- /or the !Bo6, =Bo6, =Pane& and !Pane& contro&s in
the Gambas >oo&bo6, 'ou ,i&& /ind them in the AContainerB tab# <hen 'ou create these
contro&s, GB ,i&& suggest de/au&t names /or each contro&# >a-e the de/au&t names /or each
contro& because our program uses those de/au&ts# P&ace three >oo&Buttons in the !Bo6 and
/our >oo&Buttons in the =Bo6#
:e6t, set the picture properties o/ each >oo&Button to the icons 'ou chose to use
(hope/u&&' the same as those above /or our pro9ect# Once 'ou have the icons disp&a'ed, ,e
need to start ,ith the /irst >oo&Button in the !Bo6 and doub&e4c&ic- to bring up the code
,indo,# Kou ,i&& need to do this /or each o/ the seven icons and add code as /o&&o,sC
T .ambas class *ile
PUBLIC SUB #oolB-tton=8Click()
#extLabel=.#ext 6 ;(ert Un)o clicke).;
!D
1%1
Figure )/: >a$out project icons.
Figure )0: Form1 "esign mo"e sho.ing la$out o( our controls.
PUBLIC SUB #oolB-ttonB8Click()
#extLabel=.#ext 6 ;(ert 'e)o clicke).;
!D
PUBLIC SUB #oolB-tton/8Click()
#extLabel=.#ext 6 ;(ert :elp clicke).;
!D
PUBLIC SUB #oolB-tton@8Click()
#extLabel=.#ext 6 ;:oriR Con*i5-re Btn clicke).;
!D
PUBLIC SUB #oolB-ttonC8Click()
#extLabel=.#ext 6 ;:oriR Color B-tton clicke).;
!D
PUBLIC SUB #oolB-ttonF8Click()
#extLabel=.#ext 6 ;:oriR Printer Btn clicke).;
!D
PUBLIC SUB #oolB-ttonX8Click()
#extLabel=.#ext 6 ;:oriR xit B-tton clicke).;
+$I# 9.C
M.Close
!D
>he ne6t contro& container ,e ,i&& create is the =Pane&, as sho,n in the /igure above#
<e ,i&& add /our radiobuttons and three regu&ar buttons to this container contro&#>r' to
arrange the buttons as sho,n in the /igure# Kou ,i&& see ,h' this is important once 'ou run
the program and see ho, the =Pane& rearranges the contro&s# Once again, doub&e c&icon
each radio button and add the /o&&o,ing codeC
#extLabel=.#ext 6 ;'a)ioBtn = clicke).;
!D
#extLabel=.#ext 6 ;'a)ioBtn B clicke).;
!D
PUBLIC SUB 'a)ioB-tton/8Click()
#extLabel=.#ext 6 ;'a)ioB-tton / clicke).;
1%2
!D
PUBLIC SUB 'a)ioB-tton@8Click()
#extLabel=.#ext 6 ;'a)ioB-tton @ clicke).;
!D
#extLabel=.#ext 6 ;B-tton = clicke).;
!D
#extLabel=.#ext 6 ;B-tton B clicke).;
!D
#extLabel=.#ext 6 ;B-tton / clicke).;
!D
>he &ast thing ,e ,i&& do is create the !Pane& ,ith three chec-bo6es# Remember to
arrange the chec-bo6es in 'our /orm &i-e those in the picture above to see ho, the contro&
rearranges them automatica&&'# Add this code ,hen 'ou have p&aced the chec-bo6es in the
!Pane&C
#extLabel=.#ext 6 ;Checkbox = checke).;
LS
#extLabel=.#ext 6 ;Checkbox = -nchecke).;
!DI1
!D
#extLabel=.#ext 6 ;Checkbox B checke).;
LS
#extLabel=.#ext 6 ;Checkbox B -nchecke).;
!DI1
!D
PUBLIC SUB CheckBox/8Click()
I1 CheckBox/.(al-e 6 #'U #:!
#extLabel=.#ext 6 ;Checkbox / checke).;
LS
1%3
#extLabel=.#ext 6 ;Checkbox / -nchecke).;
!DI1
!D
:o, save 'our ,or- and e6ecute this simp&e program# Kou shou&d see something simi&ar to
the /igure on the right# :otice ho, the radiobuttons in the =Pane& have a&igned vertica&&'
/rom RadioButton( to RadioButton" and, i/ there ,as room it p&aced the button contro&s to
the right and continued the a&ignment /rom top to bottom, &e/t to right# 7or the !Pane&, see
ho, the chec-bo6es a&igned themse&ves# >hese t'pes o/ contro&s are unpredictab&e in ho,
the' ,i&& &a'out their chi&dren# +t is best to use these in code d'namica&&' ,hen 'ou have to
create /orms on the /&' and do not have the opportunit' to &a' them out in a /i6ed pane& in
design mode#
>he !Bo6 and =Bo6 contro&s ho&d the >oo&Buttons and a&&o, 'ou to create ni/t' &itt&e
too&bars that ,or- ,e&& ,ith iconic driven contro&s, such as those depicted ,ith our icons#
Once 'ou have /inished p&a'ing around ,ith our &itt&e app&ication, c&ose the program and ,e
,i&& move on to &earn about >ab2trips#
The Tab,trip Contro*
>he GB >ab2trip contro& imp&ements a tabbed container contro&# Li-e a&& contro&s, it
inherits its attributes /rom the Container c&ass# >his c&ass is creatab&e# >his c&ass acts &i-e a
read4on&' arra'# >he standard ca&&ing convention isC
DIM h#abStrip $S #abStrip
h#abStrip 6 !+ #abStrip ( Parent $S Container )
DIM h#ab $S .#ab
1%4
Figure *1: >a$out program at program
startup.
h#ab 6 h#abStrip " In)ex $S Inte5er %
+nvo-ing the code above ,i&& return a virtua& tab ob9ect /rom its inde6# >ab2trips are
use/u& /or organi0ing and presenting in/ormation in se&/4contained units# >ab2trips a&&o, 'ou
to obtain input /rom users b' presenting a simp&e, eas' to /o&&o, inter/ace that can &itera&&'
guide them through a con/iguration or setup process# =ere is a samp&e o/ a >ab2trip in useC
>o demonstrate ho, eas' >ab2trips are to create, ,e ,i&& bui&d a sma&& app&ication that
imp&ements the tabbed inter/ace 'ou see above# Our app&ication ,i&& sho, 'ou ho, to use
tabbed contro&s to present in/ormation to a user and respond to it in 'our app&ications# 2tart
Gambas and create a ne, Ht graphica& user inter/ace program#
:ame the pro9ect >abs, c&ic- through the pro9ect creation ,i0ard and ,hen 'ou get to
the GB +.E, doub&e4c&icon 71ain# :e6t, 'ou ,i&& need to p&ace a >ab2trip contro& on the
ne, /orm# Once 'ou p&ace the >ab2trip, 'ou ,i&& on&' see one tab disp&a'ed# Kou must go to
the properties ,indo, and set the Count propert' to G to have the contro& &oo- &i-e the one ,e
sho, above# :ote that tab numbering starts at 0ero in Gambas# Each tab acts &i-e a container
/or the contro&s 'ou p&ace on it#
<e ,i&& a&so need to add a >e6tLabe& and a button to our /orm# >he >e6tLabe& ,i&& be
used to sho, the user actions in response to our tabbed inter/ace# >he button ,i&& be a Huit
button ,hich ,e ,i&& use to terminate the app&ication# Kou ,i&& a&so need to cop' the
con/igure, he&p, and e6it icons /rom the La'out pro9ect to the >abs /o&der so ,e can use them
,ith this pro9ect# GB is designed to contain a&& pro9ect ,or- /rom the +.E to the /o&der 'ou
create ,hen 'ou start a pro9ect# As a resu&t, 'ou need to move out o/ the +.E to cop' /i&es /rom
another /o&der to the current pro9ect (a 5uir- b' design, perhapsN#
An',a', &et's get going on this pro9ect# =ere is ,hat 'our /orm shou&d &oo- &i-e as 'ou
start to design the inter/aceC
1%#
Figure *1: A TabFtrip control.
7or >ab$ ,e ,i&& add a /rame and p&ace t,o radiobuttons in it, &i-e thisC
:e6t, doub&e c&icon each RadioButton and enter this codeC
#extLabel=.#ext 6 ;Wo- have clicke)OUbrKUcenterKUstron5K'a)ioB-tton=;
!D
#extLabel=.#ext 6 ;Wo- have clicke)OUbrKUcenterKUstron5K'a)ioB-ttonB;
!D
=ere is ,hat ,e ,i&& do /or >ab"C
1%8
Figure *3: Tab1 la$out.
Figure *2: Tabbe" (orm "esign la$out.
.oub&e4c&icon each chec-bo6 and enter this codeC
#extLabel=.#ext 6 ;Wo- have checke)OUbrKUcenterKUstron5KCheckBox=;
LS
#extLabel=.#ext 6 ;Wo- have -nchecke)OUbrKUcenterKUstron5KCheckBox=;
!DI1
!D
#extLabel=.#ext 6 ;Wo- have checke)OUbrKUcenterKUstron5KCheckBoxB;
LS
#extLabel=.#ext 6 ;Wo- have -nchecke)OUbrKUcenterKUstron5KCheckBoxB;
!DI1
!D
>he code above ,i&& determine ,hether the user is chec-ing an item or unchec-ing it b'
/irst &oo-ing at the !a&ue propert'# +/ it is >R@E, then the bo6 is a&read' chec-ed and ,e ,i&&
indicate that /act in the update o/ the >e6tLabe&"#>e6t# Other,ise, it is being unchec-ed and
,e ,i&& update the &abe& to state that /act#
7or >ab;, ,e are going to p&ace a Pane& contro& on the >ab and add three >oo&Buttons#
.o not ma-e the mista-e o/ p&acing one >oo&Button and tr'ing to cop' it and move the cop' to
the pane&# +t ,i&& not be recogni0ed as a chi&d o/ the pane& contro&# +t ,i&& appear on a&& tabs ( .
believe this is another "uir& of 5ambas)#
7or the Pane& to accept the >oo&Buttons as chi&dren, 'ou must individua&&' c&ic- the
>oo&Button on the >oo&Bo6 and create each one 9ust as 'ou did the /irst >oo&Button# 7or each
>oo&Button, assign the picture propert' the name o/ the icon ,e are using /or that button, as
1%?
Figure *#: Tab1 la$out.
sho,n hereC
>he ne6t step is to doub&e4c&icon each >oo&Button and add this codeC
PUBLIC SUB #oolB-tton=8Click()
#extLabel=.#ext 6 ;Wo- have clicke)OUbrKUcenterKthe Ustron5KCon*i5-re Icon;
!D
PUBLIC SUB #oolB-ttonB8Click()
#extLabel=.#ext 6 ;Wo- have clicke)OUbrKUcenterKthe Ustron5K:elp Icon;
!D
PUBLIC SUB #oolB-tton/8Click()
#extLabel=.#ext 6 ;Wo- have clicke)OUbrKUcenterKthe Ustron5Kxit Icon;
!D
:o,, ,e are going to add a ComboBo6 to >abD# :othing /anc', 9ust a simp&e
ComboBo6 ,ith three items# 2e&ect the ComboBo6 contro& and p&ace it on the tab as sho,n
be&o,C
1%%
Figure *%: Tab2 Tool=utton la$out .ith icons.
Figure *): Tab3 la$out .ith a
ombo=o8.
Remember, in order to set the items in the ComboBo6, 'ou need to go to the Properties
,indo, and se&ect the List propert'# A button ,ith three dots ,i&& appear (indicating that it
&eads to the List Editor and 'ou need to c&ic- that# Add the /o&&o,ing itemsC APic- somethingB
(to disp&a' as our de/au&t te6t, A>his thingB, A>hat thingB, and A2ome other thingB to the &ist#
7ina&&', ,e need to set an event /or the ComboBo6 b' sing&e4c&ic-ing on the ComboBo6 contro&
then right4c&ic-ing the mouse# Choose Events and se&ect the Change event# An'time the
ComboBo6 changes, ,e ,ant to disp&a' the changed te6t on our >e6tLabe&# :o,, add this
code in the Code Editor /or the ComboBo6"LChange( eventC
DIM comboitem $S Strin5
comboitem 6 ComboBox=.#ext
#extLabel=.#ext 6 ;Wo- picke) itemOUbrKUcenterKUstron5K ; S comboitem
!D
7or our &ast tab, >ab(, ,e are going to simp&' disp&a' the current time# >his ,i&&
re5uire use o/ the >imer contro&# <e are going to need to add a Labe& and a >imer contro& to
>ab(, as sho,n be&o,# >he >imer too& can be /ound in the 2pecia& tab o/ the Gambas too&bo6#
+n order /or the timer to ,or-, ,e must enab&e it ,hen the /orm /irst starts# .oub&e4
c&icon the /orm some,here e6cept on a contro& and 'ou ,i&& see the 7ormLOpen(
subroutine appear in the code ,indo,# Add this code to the routineC
1Main.Caption 6 ; Playin5 Aith #abStrips ;
#imer=.nable) 6 #'U
!D
>o actua&&' use the timer, ,e need to set an Event# <e do this b' sing&e4c&ic-ing on the
>imer contro& then right4c&ic-ing the mouse# Choose Events and se&ect the Timer event# Kou
,i&& be p&aced in the Code Editor and 'ou need to add a sing&e &ine o/ codeC
PUBLIC SUB #imer=8#imer()
Label=.#ext 6 Str[(!oA)
!D
1%+
Figure **: Tab# la$out .ith a Timer.
>his &ine o/ code ,i&& update the Labe&"#>e6t /ie&d ever' second that the >ab( is
disp&a'ed# +n e//ect, 'ou have created a c&oc- on the >ab b' doing this# >hat is a&& there is to it#
7ina&&', doub&e4c&icon 'our Huit button, and add this bit o/ codeC
M.Close
!D
Run the program and see that it ,or-s# :e6t, ,e move to /i&e operations in Chapter )#
1+0
Chapter 1 2or3ing with Fies
<e are going to introduce 'ou to the Gambas /i&e management and /i&e inputMoutput
(file iAo operations in this chapter# Gambas has a /u&&4/eatured set o/ /unctions and
subroutines to support near&' an' /i&e iMo operation 'ou ma' need to imp&ement in 'our
programs#
Access
.ir
Eo/
E6ist
+s.ir
Lo/
2tat
>emp M >empU
OPE: and CLO2E
+:P@>, L+:E +:P@>, and PR+:>
REA., 2EEE, <R+>E and 7L@2=
COPK, E+LL and RE:A1E
1E.+R and R1.+R
L+:E
Access
Access is a /unction used to determine i/ a /i&e is accessib&e or not# >he ca&&ing
convention is
$ccessible 6 $ccess ( Path " 0 Mo)e % )
>he Access /unction ca&& returns >R@E i/ the /i&e speci/ied b' Path is accessib&e# +/ the
va&ue o/ 1ode is g/1+ed, then the /unction returns >R@E i/ the /i&e can be read# >his is the
de/au&t va&ue /or a&& /i&es# +/ 1ode is g/1-rite, then Access returns >R@E i/ the /i&e can be
,ritten to# <hen g/1Exec is speci/ied /or 1ode, the /unction returns >R@E i/ the /i&e can be
e6ecuted# >he previous /&ags can be combined ,ith the OR operator# 7or a director', the
e6ecution /&ag means that the director' can be bro,sed# 7or e6amp&eC
P'I!# $ccess(;MhomeMbenoit;0 5b.+rite 2' 5b.xec)
,ou&d return
#r-e
,hi&e the statement
1+1
P'I!# $ccess(;Mroot;0 5b.+rite)
,i&& return
1alse
!ir
.ir returns a string arra' that contains the names o/ /i&es &ocated in -irectory that
match the speci/ied 7i&e pattern# +/ no pattern is speci/ied, an' /i&e name that e6ists in the
director' is returned# >he pattern ma' contain the same generic characters permitted /or the
L+EE operator# +n other ,ords, those characters /ound in the /o&&o,ing tab&eC
Feneric
chrcter
Mtches
O
An' number o/ an' character or string#
N
P&aceho&der to speci/' the string position(s /or the
searched4/or character(s
Zabc[
An' character bet,een the brac-ets#
Z64'[
An' character in the interva&#
Z^64'[
An' character not in the interva&#
>he specia& generic character G prevents the character /o&&o,ing it /rom being
interpreted as a generic# 2tandard ca&&ing convention isC
1ile name array 6 Dir ( Directory " 0 1ile pattern % )
=ere is an e6amp&e code segment to he&p 'ou
T Print a )irectory
SUB PrintDirectory(Directory $S Strin5)
DIM s1ile $S Strin5
12' $C: s1ile I! Dir(Directory0 ;L.L;)
P'I!# s1ile
!7#
!D
1+2
Eof
>he Eo/ /unction returns a Boo&ean va&ue o/ >R@E i/ ,e are at the end o/ the stream#
2tandard ca&&ing convention isC
Boolean 6 o* ( 1ile )
An e6amp&e o/ ho, Eo/ is used /o&&o,sC
...
2P! 1ile!ame 12' '$D $S <h1ile
+:IL !2# o*(h1ile)
LI! I!PU# <h1ile0 2neLine
P'I!# 2neLine
+!D
CL2S <h1ile
...
Eist
>he ca&&ing convention /or E6ist isC
Boolean 6 xist ( Path )
+t returns >R@E i/ a /i&e or a director' e6ists# NO&EL (sing R s directory identifier
does not work1 +/ the path speci/ied does not e6ist, 7AL2E is returned# =ere is an e6amp&e
o/ using E6ist to determine i/ a /i&e e6ists be/ore ca&&ing OPE: to read the /i&eC
...

DIM sC-rrent1ile!ame $S Strin5
sC-rrent1ile!ame 6 ;#he 'aven.txt;
I1 xist(sC-rrent1ile!ame) #:!
... Topen the *ile
LS
Messa5e.In*o(;1ile ; S sC-rrent1ile!ame S ; )oes not exist.;)
!DI1
...
1+3
%s!ir
>he /unction +s.ir returns >R@E i/ a path points to a director'# +/ the path does not
e6ist or is not a director', this /unction returns 7AL2E# >he ca&&ing convention isC
Boolean 6 IsDir ( Path )
2ome e6amp&es o/ ho, to use +s.ir, as provided on the Gambas <i-i /o&&o,C
P'I!# IsDir(;MetcMpassAor);)
1alse
P'I!# IsDir($pplication.:ome SM ;.5ambas;)
#r-e
P'I!# IsDir(;MAin)oAs;)
1alse
,tat
>he 2tat /unction returns in/ormation about a /i&e or a director'# >he 7i&e ob9ect
in/ormation returned inc&udes the t'pe, si0e, &ast modi/ication dateMtime, permissions, etc#
>he /o&&o,ing /i&e properties can be obtained using this /unctionC
#Group #=idden #LastAccess #LastChange
#Last1odi/ied #Lin- #1ode #Path
#Perm #2etG+. #2et@+. #2i0e
#2tic-' #>ime #>'pe #@ser
>he standard ca&&ing convention /or 2tat isC
1ile in*o 6 Stat (Path)
=ere is an e6amp&e o/ ho, to use 2tat and ,hat ,i&& be returned /rom the conso&eC
+I#: Stat(;Mhome;)
P'I!# .#ype 6 5b.Directory
P'I!# 'o-n)(.SiRe M =9B@)G ;Q;
!D +I#:
>he conso&e ,i&& respond ,ithC
1+4
#r-e
@Q
Let's divert our attention /or a moment to e6amine the s'nta6 above# As 'ou'&& reca&&
/rom Chapter ;, the A-*&611EN# -*&6B statement is main&' used to assign propert'
va&ues# An e6pression beginning ,ith a dot (A#B &ocated bet,een -*&6 and EN# -*&6
re/ers to the ob9ect named a/ter -*&6 5 in this case, the AMhomeB subdirector'# Ig/J is a
static c&ass that inc&udes a&& o/ the basic Gambas constants ,hich are used b' man' /unctions#
Ig/1#irectoryJ is the /&ag constant used b' the $tt1&ype propert' to designate a director'#
<hen the 2tat /unction ,as invo-ed ,ith a /i&e path argument, the $tt1&ype va&ue provided
,as compared to the g/1#irectory /&ag# 2ince $tt1&ype cannot be assigned a va&ue
di//erent /rom ,hat the s'stem reports, the e5uiva&ence in this case is not the resu&t o/ an
assignment# Gambas treats it as a Boo&ean test o/ ,hether or not this speci/ic path, as
reported b' the s'stem, had the g/1#irectory /&ag set to >R@E# $tt1$i<e returns the si0e o/
the /i&e or director'# +n order to PR+:> the director' si0e in -i&ob'te /orm, the va&ue (in b'tes
returned b' $tt1$i<e ,as divided b' "$;( b'tesM-i&ob'te, then rounded to the nearest
integer ,ith the Round /unction, ,hich ,e ,i&& encounter in Chapter "$#
Temp 7 Temp8
>empU returns a uni5ue /i&e name use/u& to create temporar' /i&es# >he /i&ename
created ,i&& be &ocated in the Mtmp director'# Ca&&ing convention isC
1ile name 6 #emp[("!ame%)
>he path that is returned has the /ormC
MtmpM5ambas."User ID%M"Process ID%M"!ame%.tmp
+/ no optiona& /i&ename pre/i6 is inc&uded, then Gambas ,i&& assign an integer instead, and
successive integers /or additiona& temporar' /i&es#
E6amp&esC
P'I!# #emp[()
returnsC
MtmpM5ambas.9M=BCCCM=.tmp
P'I!# #emp[(another)
returns
1+#
MtmpM5ambas.9M=BCCCManother.tmp
OPEN and C&O,E
OPEN and C)O$E ,or- as a team# OPEN opens a /i&e /or reading, ,riting, creating
or appending data# @n&ess the C+E,&E -e',ord is speci/ied, the /i&e must e6ist# +/ the
C+E,&E -e',ord is speci/ied, then the /i&e is created, or c&eared i/ it a&read' e6ists# +/ the /i&e
is opened /or ,riting, the path to it must be abso&ute because re&ative paths are, b' de/au&t,
assumed to re/er to /i&es that e6ist inside the current Gambas pro9ect or archive /o&der# Ca&&ing
convention /or OPEN isC
*ile 6 2P! pathM*ilename 12' " '$D&I!PU# % " +'I#&2U#PU# % " C'$# & $PP!D % " +$#C: %
+/ the ,PPEN# -e',ord is speci/ied, then the /i&e pointer is moved to the end o/ /i&e
9ust a/ter the /i&e is opened# +/ 'ou use *NP(& or O(&P(&, then the input4output are
bu//ered# +/ 'ou use the +E,# or -+*&E -e',ords, the input4output are not bu//ered# +/
the -,&C6 -e',ord is speci/ied, the /i&e is ,atched b' the interpreter using the /o&&o,ing
conditiona& guide&inesC
+/ at &east one b'te can be read /rom the /i&e, then the event hand&er 7i&eLRead( is
ca&&ed#
+/ at &east one b'te can be ,ritten into the /i&e, then the event hand&er 7i&eL<rite( is
ca&&ed#
Note /out IEndinnessJ nd I$tre"sJL For our purposes9 G-n"iannessH re(ers to the
b$te or"er o( b$tes store" in a "ata (ile. +( the most signi(icant b$te is store" in (irst position9
(ollo.e" b$ "ecreasingl$ signi(icant b$tes9 then the (ormat is Gbig&en"ianH. An e8ample o( the big&
en"ian concept .oul" be the number Gt.ent$&(ourH. +n Glittle&en"ianH (ormat9 the least signi(icant
b$te is encountere" (irst. The same number9 e8presse" in a little&en"ian (ormat9 .oul" be G(our an"
t.ent$H. -n"ianness is important .hen $ou .ant to rea" "ata (rom a GstreamH as binar$ "ata.
GFtreamH re(ers to access o( an$ (ile (rom a process9 .hether it;s a (inite stream li3e a (ile on "is39 or
an in(inite stream li3e "ata (rom a 'i"eocam or "ata transmitte" o'er the +nternet 'ia TP
(Transmission ontrol Protocol).
>he /o&&o,ing e6amp&es sho,s ho, to read data /rom a B1P /i&e, -no,n to use &itt&e4endian
/ormatC
DIM h1ile $S 1ile
DIM iData $S Inte5er
h1ile 6 2P! ;ima5e.bmp; 12' I!PU#
h1ile.Byte2r)er 6 5b.Littlen)ian
1+8
...
'$D <h1ile0 iData
C)O$E is the reciproca& /unction and simp&' c&oses an opened /i&e# 2'nta6 /or using
C)O$E isC
CL2S < 1ile
=ere is an e6amp&e that opens and c&oses a /i&eC
' Gambas C&ass 7i&e
sC-rrent1ile!ame $S Strin5
sC-rrent1ileLen5th $S Inte5er
DIM h1ileIn $S 1ile
h1ioleIn 6 2P! sC-rrent1ile!ame 12' '$D
sC-rrent1ileLen5th 6 Lo*(h1ileIn)
+:IL !2# o*(h1ileIn)
LI! I!PU# <h1ileIn0 sInp-tLine Texplaine) beloA
#ext$rea=.#ext6 #ext$rea=.#ext S Chr(=/) S Chr(=9) S sInp-tLine
+!D
CL2S h1ileIn
LS
!DI1
!D
&%NE %NP)T
)*NE *NP(& reads an entire &ine o/ te6t on the standard input# +t can be used on the
conso&e or ,ith /i&es# >he ca&&ing convention isC
LI! I!PU# (ariable
or, /or /i&es ,here the data is read /rom the stream 7i&eC
1+?
LI! I!PU# < 1ile 0 (ariable
=ere is an e6amp&e 'ou can tr' to see ho, )*NE *NP(& ,or-sC
S#$#IC PUBLIC SUB Main()
DIM h1ile $S 1ile
DIM lineCtr $S Inte5er
h1ile 6 2P! ;..M#he 'aven.txt; 12' '$D
+:IL !2# o*(h1ile)
LI! I!PU# <h1ile0 sInp-tLine
P'I!# Str(lineCtr) S Chr(>) S sInp-tLine
I!C lineCtr
+!D
CL2S <h1ile
!D
NO&EL Kou shou&d not use )*NE *NP(& ca&& to read data /rom a binar' /i&e because it ,i&&
&ose the &ine/eed characters# 7or reading data /rom binar' /i&es, use +E,# insteadC
'$D <h1ile0 2neLine0 Len5th
,here )ength is the ma6imum number o/ b'tes 'ou ,ant read## >he )ength can be an'
number, but 'ou shou&d &imit it to the ma6imum si0e o/ an' variab&e 'our program ,i&& use to
ho&d the read data#
(EA!6 ,EE96 #(%TE and -&),$
>he +E,# /unction reads data /rom the standard output# +t treats the input stream as
binar' data ,hose data t'pe is speci/ied b' the t'pe o/ the variab&e the data is stored in during
the read operation# >he binar' representation o/ the data shou&d be the same representation
created b' use o/ the -+*&E instruction# +/ <ariable is a string, 'ou can speci/' a &ength that
indicates the number o/ b'tes to read# +/ the va&ue o/ the 7ength parameter is negative, then
27ength b'tes are read /rom the end o/ stream# +/ no 7ength parameter is speci/ied /or a
string, the entire string is read /rom the stream# >he string va&ue then must have been ,ritten
,ith the -+*&E instruction# 2tandard ca&&ing convention /or +E,# isC
'$D (ariable " 0 Len5th %
+/ +E,# is used ,ith /i&e operations, the ca&&ing convention isC
'$D < 1ile 0 (ariable " 0 Len5th %
1+%
>he -+*&E /unction ,rites e6pressions to the standard output using their binar'
representation# +/ E6pression is a string, 'ou can speci/' a &ength that indicates the number o/
b'tes to ,rite# +/ no &ength is speci/ied /or a string va&ue, the entire string va&ue is ,ritten
direct&' to the stream# =ere is the ca&&ing convention /or ,riting to a standard output stream
(i#e#, the conso&eC
+'I# xpression " 0 Len5th %
and /or ,riting data to a /i&e, this is the conventionC
+'I# "< 1ile 0% xpression " 0 Len5th %
or
+'I# "< 1ile 0% xpression $S Datatype
>he $EEK /unction de/ines (or moves the position o/ the stream pointer, most o/ten
in preparation /or the ne6t readM,rite operation# +/ the position speci/ied b' the 7ength
parameter is negative, then the stream pointer is moved bac-,ards 27ength b'tes /rom the
end o/ the /i&e# >o move the stream pointer be'ond the end o/ the /i&e, 'ou must use the Lo/(
/unction# 2tandard ca&&ing convention isC
SQ < 1ile 0 Position
=ere are some e6amp&es o/ using $EEKC
T Move to the be5innin5 o* the *ile
SQ <h1ile0 9
T Move a*ter the en) o* the *ile
SQ <h1ile0 Lo*(<h1ile)
T Move =99 bytes be*ore the en) o* the *ile
SQ <h1ile0 ,=99
>he !)($6 /unction is ca&&ed to empt' (or /&ush the contents o/ a bu//ered data
stream# +/ no stream is speci/ied, ever' open stream is /&ushed# >'pica&&', !)($6 is ca&&ed
a/ter mu&tip&e ,rite operations and be/ore c&osing out a program or routine to ensure a&& data
he&d in a bu//er is ,ritten out to the /i&e be/ore e6iting# =ere is the ca&&ing convention /or
!)($6C
1LUS: " "<% 1ile %
1++
COP:6 9%&& and (ENA2E
>he COP3 /unction ,i&& cop' a source /i&e to a speci/ied destination /i&e# >he
destination path need not have the same name than the source path# Kou cannot cop'
directories recursive&' ,ith this /unction# >he ca&&ing convention /or this /unction isC
C2PW So-rce path #2 Destination path
=ere is an e6amp&e o/ ho, to use COP3C
T Save the 5ambas con*i5-ration *ile
C2PW User.:ome SM ;.5ambasM5ambas.con*; #2;MmntMsaveM5ambas.con*.save;
>he K*)) /unction removes a /i&e# >he ca&&ing convention is *I)) 0ath and ,hatever
e6ists in Path is permanent&' de&eted# MO'E moves a /i&e or /o&der to another &ocation, or
changes the name o/ a /i&e or /o&der /rom /ld name to (ew name# =ere are e6amp&es that do
both things & the /irst &ine changes the name in the current &ocation# >he second &ine moves
the /i&e to a di//erent /o&derC
M2( User.:ome SM ;#he 'aveno-s.txt; #2 User.:ome SM ;#he 'aven.txt;
M2( User.:ome SM ;#he 'aven.txt; #2 User.:ome SM ;P-blicM#he 'aven.txt;
29!%(6 (2!%(
>he MK#*+ /unction is used to create (ma-e a /o&der on 'our /i&e s'stem and
+M#*+ is used to remove a /o&der# Both /unctions ta-e a sing&e parameter, a 7i&e path and
name# >he ca&&ing convention isC
MQDI' User.:ome SM DDoc-mentsM.ambasMtestE
and
'MDI' User.:ome SM DDoc-mentsM.ambasMtestE
+n order to demonstrate most o/ the /i&e and +MO /unctions described in this chapter, ,e
are going to create an app&ication that ,i&& act as a simp&e te6t editor# >he intent here is not to
create a /u&&4b&o,n te6t editor, but to sho, 'ou ho, to use these /unctions in the conte6t o/ an
app&ication#
>he app&ication ,e ,i&& bui&d in this chapter is a &itt&e more comp&e6 than ,hat ,e have
seen so /ar in that ,e ,i&& be creating t,o /orms, an input /i&e, a he&p /i&e, and ,e ,i&& be using
5uite a /e, s'stem icons ,hich ,i&& be copied /rom the Linu6 O2 distribution's s'stem +con
/o&der(s# =ere is ,hat our app&ication ,i&& &oo- &i-e at runtimeC
200
+n this program, ,e ,i&& create a main menu, a te6t area to disp&a' and edit te6t ,ith,
and ,e ,i&& create t,o >e6tLabe& status e&ements at the bottom o/ the disp&a'# <e ,i&& a&so
introduce use o/ the >imer contro& (sho,n as the c&oc- in the picture be&o,# >his /orm,
named 71ain#/orm, ,i&& &oo- &i-e this in design modeC
>o start, &oad Gambas and create a ne, H> graphica& user inter/ace pro9ect# :ame it
7i&eOpsH> and ,hen 'ou get to the GB +.E, create a ne, /orm, 71ain, a startup c&ass# <hen
the /orm disp&a's on 'our screen, ,e are going to begin b' creating the menus# Kou can press
C>RLE to bring up the 1enu Editor# Add the /o&&o,ing items using the editor# 7or the
icons, 'ou ,i&& need to cop' icons /rom the same director' ,e speci/ied in the &ast chapter#
201
Figure *0: The sample application in "esign mo"e.
Figure */: The FileAps:T program at runtime.
1ost Linu64based distributions have icon /i&es stored in the /o&ders namedC
M home MusrMshareMiconsMde/au&t4-deMD;6D;Mactions
or
M home MusrMshareMiconsMde/au&t4-deMD;6D;Mapp&ications
Kour s'stem ma' be di//erent# Regard&ess o/ ,here 'ou /ind them, pic- out icons appropriate
/or our program and cop' them to the 7i&eOps /o&der# =ere are the "J icons chosen to use /or
this pro9ectC
+/ 'ou cannot /ind the e6act same icon, simp&' pic- one that is most appropriate and
save it ,ith the /i&e name /or that option as sho,n in the tab&es be&o,# +t is not crucia& that
ever' icon be e6act&' the same# +n /act, the 2e&ectA&& icon and =e&pAbout icon, ,hich aren't
/ound in the de/au&t#-de /o&der, can be created using the Gambas +con Editor, or copied /rom
the Gnome icons /o&der# Construct the /i&e menu using the /o&&o,ing tab&es# Remember to
associate a ApictureB ,ith each menu item that is be&o, the top &eve& menu items#
!ileMenu
'ri/le N"e Cption *con Property (filen"e)
7i&e:e,+tem 3:e,3 PictureZ3/i&ene,#png3[
7i&eOpen+tem 3Open###3 PictureZ3/i&eopen#png3[
7i&e2ave+tem 32ave###3 PictureZ3/i&esave#png3[
7i&e2aveAs+tem 32ave as###3 PictureZ3/i&esaveas#png3[
7i&ePrint2e&ect 3Print3 PictureZ3/i&eprint#png3[
7i&ePrint+tem Print (Gambas method (none
7i&e2'sPrint+tem Print (2'stem method (none
7i&eE6it+tem 3E6it3 PictureZ3e6it#png3[
202
Figure /1: Fample application icons.
EditMenu
Edit2e&ectA&&+tem 32e&ect A&&3 PictureZ3se&ecta&&#png3[
Edit@ndo+tem 3@ndo3 PictureZ3undo#png3[
EditRedo+tem 3Redo3 PictureZ3redo#png3[
EditCut+tem 3Cut3 PictureZ3editcut#png3[
EditCop'+tem 3Cop'3 PictureZ3editcop'#png3[
EditPaste+tem 3Paste3 PictureZ3editpaste#png3[
EditPre/s+tem 3Pre/erences3 PictureZ3con/igure#png3[

!or"tMenu
7ormatCo&or+tem 3Co&ors3 PictureZ3co&ori0e#png3[
7ormat7ont+tem 37ont3 PictureZ3/onts#png3[
6elpMenu
=e&pContents+tem 3Contents3 PictureZ3contents#png3[
=e&pAbout+tem 3About3 PictureZ3he&p4about#png3[
=ere is the code /or ,e ,i&& use /or 71ain# <e ,i&& go thru this &ine b' &ine so
ever'thing is /u&&' e6p&ained# <e start our program b' dec&aring t,o c&ass g&oba& variab&es,
sCurrent7i&e:ame and sCurrent7i&eLength#
' Gambas c&ass /i&e
sC-rrent1ile!ame $S Strin5
sC-rrent1ileLen5th $S Inte5er
<hen the program starts, this ne6t subroutine is ca&&ed# +t ca&&s a constructor, Lne,( to
initia&i0e# >he constructor is e6p&ained in the ne6t section# <hen our program starts, ,e are
going to have it automatica&&' &oad our de/au&t te6t /i&e, named A>he Raven#t6tB# >his /i&e ,as
copied o// the +nternet and 'ou can p&ace an' te6t /i&e in the 7i&eOps pro9ect /o&der to use /or
this pro9ect# %ust remember that the /i&ename has to be changed in the code be&o, i/ 'ou
choose not to use our de/au&t /i&ename#
203
DIM h1ileIn $S 1ile
<e ,i&& assign our /i&ename to the sCurrent7i&e:ame string variab&e and chec- to see i/
the /i&e e6ists in the pro9ect /o&der# +/ it e6ists, then the program ,i&& open the /i&e and get the
initia& /i&e &ength# <e ,i&& disp&a' the /i&ename and si0e in the 7orm"#Caption propert'# <hi&e
it is not customar' to disp&a' the /i&e si0e &i-e this, it is done here simp&' to demonstrate the
use o/ the Lo/ /unction#
h1ileIn 6 2P! sC-rrent1ile!ame 12' '$D
sC-rrent1ileLen5th 6 Lo*(h1ileIn) Tto shoA hoA to 5et *ile siRe
1Main.Caption 6 ; ; S sC-rrent1ile!ame S ;0 siReO ; S Str(sC-rrent1ileLen5th) S ; bytes.;
:o,, ,e ,i&& enter a &oop structure to read a&& the &ines o/ the te6t /i&e into our
>e6tArea"#>e6t propert'# <e ,i&& continue to &oop unti& ,e have reached the end o/ the /i&e#
As ,e read each &ine into memor' and assign it to the variab&e s+nputLine, ,e must remember
to add the CRL7 (a Carriage Return (Chr("D and a Line 7eed (Chr("$ to the end o/ the &ine
so it ,i&& disp&a' proper&' in the contro&#
LI! I!PU# <h1ileIn0 sInp-tLine
+!D
As soon as ,e e6it the &oop, meaning ,e have reached the end o/ the /i&e, ,e ,i&& c&ose
the /i&e#
CL2S h1ileIn
+/ our chec- to see i/ the /i&e e6ists /ai&ed, ,e ,ou&d enter this E)$E b&oc- o/ code and
disp&a' a message indicating that the /i&e did not e6ist# :e6t, ,e ca&& our
7i&eOpen+temLC&ic-( subroutine to have the user pic- a /i&e to open#
LS
1ile2penItem8Click() T *orce a *ile to be picke) i* no )e*a-lt.
!DI1
!D
>hat is a&& there is to the 7ormLOpen( subroutine# =ere is the constructor /or the /ormC
204
PUBLIC SUB 8neA()
#imer=.Delay 6 =999
#imer=.nable) 6 #'U
!D
>he constructor simp&' sets the timer de&a' to " second ("$$$ ms and sets the enab&ed
propert' to true# >he net e//ect here is that the timer ,i&& update itse&/ ever' second# <e ,i&&
imp&ement the timer contro& &ater in this code#
Let's no, turn our attention to the 7i&e _ :e, menu option# 7or a ne, /i&e to be created
b' the user, ,e must /irst b&an- out the te6t in the >e6tArea"#>e6t propert'# <e ,i&& prompt
the user /or a ne, /i&e name and save the b&an- /i&e to dis- to create it# <hatever changes the
user ,i&& ma-e ,i&& be saved on e6it or ,henever the user chooses to save /rom the menu# >he
&ast thing ,e do in this subroutine is set the 71ain#Caption propert' to the ne,&' saved
/i&ename#
PUBLIC SUB 1ile!eAItem8Click()
#ext$rea=.#ext 6 ;;
Dialo5.#itle 6 ;nter neA *ile name...;
Dialo5.1ilter 6 " ;#ext *iles (L.txt);0 ;$ll *iles (L.L); %
Dialo5.Save1ile
1orm=.Caption 6 Dialo5.Path
!D
>he ne6t routine is activated ,hen the user c&ic-s the 7i&e _ Open menu item#
PUBLIC SUB 1ile2penItem8Click()
>his routine re5uires t,o &oca& variab&es# h7i&e+n is the hand&e to the 7+LE ob9ect ,e
,i&& open and s+nputLine is a string variab&e that ,e ,i&& use to read the te6t /i&e into our
>e6tArea"#>e6t propert'#
DIM h1ileIn $S 1ile
%ust be/ore the ca&& to the standard dia&og, ,e can set the ,indo, caption (or tit&e
using the .ia&og#>it&e propert'# <e ,i&& a&so set a /i&ter /or the dia&og to on&' &oo- /or /i&es ,ith
a #t6t e6tension# As a &ast resort, ,e ,i&& &et the user choose to vie, a&& t'pes o/ /i&es b'
se&ecting the /i&ter O#O /rom ,ithin the dia&og#
Dialo5.#itle 6 ;Choose a text *ile;
Dialo5.1ilter 6 ";#ext *iles (L.txt);0 ;$ll *iles (L.L);%
20#
<hen the ca&& to .ia&og#Open7i&e is made, remember that it ,i&& return a >R@E va&ue i/
the user c&ic-s on the Cance& button, other,ise, 7AL2E is returned# <e ,i&& chec- /or a >R@E
va&ue and return i/ that is ,hat ,e get# Other,ise, it means the user se&ected a /i&e and ,e ,i&&
process it#
I1 Dialo5.2pen1ile() #:!
'#U'!
LS
>he /i&ename o/ the /i&e that ,as se&ected b' the user is stored in the .ia&og#Path
propert'# <e ,i&& assign that to the g&oba& variab&e sCurrent7i&e:ame so other parts o/ the
program ,i&& have access to it# <e ,i&& set the 71ain#Caption propert' to the name o/ the
ne,&' opened /i&e and c&ear the current >e6tArea" disp&a' b' invo-ing the C&ear method#
sC-rrent1ile!ame 6 Dialo5.Path
1Main.Caption 6 ; ; S sC-rrent1ile!ame S ; ;
#ext$rea=.Clear
:e6t, ,e ,i&& open the /i&e and read each &ine into memor' using the L+:E +:P@>
/unction and our string variab&e s.nput7ine# Once the data is stored in s+nputLine, ,e ,i&&
add it to the end o/ ,hatever is current&' stored in the >e6tArea"#>e6t propert' (e//ective&'
concatenating onto the end o/ the current te6t va&ue and add our CRL7 characters# Once ,e
reach the end o/ the /i&e, ,e ,i&& e6it the &oop and c&ose the /i&e#
2P! sC-rrent1ile!ame 12' '$D $S h1ileIn
+!D
CL2S h1ileIn
!DI1
!D
>he 7i&e Q 2ave menu item, ,hen c&ic-ed, ,i&& invo-e this subroutine# +t ,or-s a&most
&i-e the previous one e6cept that ,e a&read' -no, the name o/ the /i&e he&d in the g&oba&
variab&e sCurrent7i&e:ame# <hen ,e return /rom the standard dia&og ca&&, ,e update the
g&oba& variab&e ,ith ,hatever ,as returned not caring i/ the /i&e is the same name or not#
<hatever it is or has become ,i&& be saved#
PUBLIC SUB 1ileSaveItem8Click()
Dialo5.#itle 6 ;Save text *ile;
Dialo5.1ilter 6 " ;#ext *iles (L.txt);0 ;$ll *iles (L.L); %
I1 Dialo5.Save1ile() #:!
'#U'!
208
LS
1ile.Save(sC-rrent1ile!ame0 #ext$rea=.#ext)
!DI1
!D
>he ne6t subroutine ,e ,i&& code is the 7i&e2aveAs menu item# +/ the user ,ants to save
the e6isting /i&e under a di//erent /i&ename, this is the routine to hand&e that option# 7or this
subroutine, it ,i&& ,or- a&most identica&&' to the 7i&e2ave subroutine but ,e ,i&& need to chec-
to see i/ the /i&ename returned /rom the standard /i&e dia&og is actua&&' di//erent than the
current /i&ename# +/ it is di//erent, then ,e ,i&& save the /i&e under the ne, name# +/ the name
is the same, ,e ,i&& pop up a message bo6 and in/orm the user that no save action ,as ta-en
because the names ,ere identica&#

PUBLIC SUB 1ileSave$sItem8Click()
DIM s#mp!ame $S Strin5
<e use the &oca& string variab&e s>mp:ame to ma-e our chec-# 7irst o/ a&&, ,e need to
obtain the /u&& path to the app&ication and concatenate the current /i&ename to that, to get the
/u&&' 5ua&i/ied path name /or our /i&e# <e use the App&ication c&ass /or that purpose, chec-ing
the Path propert' to get the name and path o/ the running app&ication# :ote the use o/ the :A
operator ,hich is speci/ica&&' used to catenate /i&enames#
s#mp!ame 6 $pplication.Path SM sC-rrent1ile!ame
%ust as ,e did previous&', ,e ,i&& set the tit&e and /i&ter properties, then ca&& the
standard /i&e dia&og#
Dialo5.#itle 6 ;Save text *ile as...;
Dialo5.1ilter 6 ";#ext *iles (L.txt);0 ;$ll *iles (L.L);%
+/ the standard dia&og ca&& returns >R@E, the user has cance&ed out o/ the routine and
,e ,i&& simp&' return to the ca&&ing process (i#e#, our standard event &oop#
I1 Dialo5.Save1ile() #:!
'#U'!
+/ the /i&enames are the same, ,e ,i&& pop up the message bo6 and returnC
LS I1 s#mp!ame 6 Dialo5.Path #:!
Messa5e.In*o(;1ile not save)O name same as c-rrent *ile.;0 ;2Q;)
'#U'!
Other,ise, ,e set the g&oba& variab&e to the /i&ename returned /rom the standard /i&e
dia&og and ca&& the 2ave method, passing the /i&ename and our te6t as parameters# <e update
20?
the caption o/ the ,indo, as the &ast thing ,e do be/ore returning to the ca&&ing process#
LS
1ile.Save(sC-rrent1ile!ame0 #ext$rea=.#ext)
1Main.Caption 6 sC-rrent1ile!ame
!DI1
!D
Printing an' t'pe o/ item is prett' eas' in Gambas# Our 7i&e _ Print menu item ,i&&
invo-e this subroutine ,hen c&ic-ed# <e ,i&& dec&are our &oca& variab&es /irst and then
something e&se ,e M($& do be/ore ,e actua&&' tr' to print an'thing is ca&& the
Printer#2etup( subroutine# +t is mandatory to ca&& this /unction in GB#
PUBLIC SUB 1ilePrintItem8Click()
DIM iLe*tMar5in $S Inte5er
DIM i#opMar5in $S Inte5er
DIM i'i5htMar5in $S Inte5er
DIM iBottomMar5in $S Inte5er

DIM ars#xt#oPrint $S Strin5"%
DIM i#xtPosW $S Inte5er
DIM s#xtLine $S Strin5

DIM strMs5 $S Strin5
DIM iPrinter$rea+i)th $S Inte5er
DIM iPrinter$rea:ei5ht $S Inte5er
DIM aStrin5 $S Strin5
:ote the ne6t D &ines o/ code# >he ca&& to the Printer#2etup method automatica&&' opens
the printer dia&og contro&# >his dia&og c&oses b' the user se&ecting either OE or Cance&# <hen
it c&oses, this method returns >R@E i/ the user c&ic-ed on the Cance& button, and 7AL2E i/ the
user c&ic-ed on the OE button# >his a&&o,s 'ou to detect the user's intent, and e6it the print
9ob i/ needed#
A&so, be/ore 'ou ca&& the print dia&og, 'ou can over4ride the setup dia&og's de/au&t
settings /or properties &i-e si0e and reso&ution (and others so that 'ou don't have to set this
ever' time 'ou print something# 7or e6amp&e, A( is the de/au&t si0e in the print dia&og (and
standard outside the @nited 2tates, but in the @#2# most peop&e ,i&& e6pect to print on Letter4
si0ed (*#GQ"" paper#
Printer.SiRe 6 ;Letter;
:O>EC >=+2 <+LL BE APrinter.Paper 6 Printer.LetterB +: GA1BA2 D#
20%
Tol)er printers )o not seem to be set to DPI loAer than F99 in .B
Printer.'esol-tion 6 /99
I* yo- )o not incl-)e the next line o* co)e0 printin5 Aill procee) Aitho-t the printer )ialo5 bein5 calle).
I1 Printer.Set-p() #:! '#U'!
!2#O #:IS +ILL B DPrinter.Con*i5-re()E I! .$MB$S /.
, note /out the printer dilogC A(ter the user has ma"e 'arious choices9 the "ialog returns
'alues (or each propert$ that it can collect in(ormation about. The "ialog "oes nothing else I it;s up
to the programmer to rea" those parameters an" .rite co"e to ma3e use o( those choices. For
e8ample9 the "ialog allo.s the user to print (e.er than all o( the pages. ?o.e'er9 in our program9
.e ha'e not .ritten a routine to rea" that choice an" set that 'alue9 the .a$ .e "i" abo'e (or paper
si!e an" resolution.
7or a D$$ dpi printer, a va&ue o/ D$$ ,ou&d e5ua& a one inch margin# :o,, ,e set the
margin va&ues b' using the Printer properties (or the ones ,e over4rode above returned /rom
the Printer#2etup ca&&#
Tset le*t mar5in to one inch0 eI-al to the DPI o* the printer
iLe*tMar5in 6 Printer.'esol-tion
Tset top mar5in to one inch0 eI-al to the DPI o* the printer
i#opMar5in 6 Printer.'esol-tion
Tset ri5ht mar5in to one inch0 eI-al to the DPI o* the printer
i'i5htMar5in 6 Printer.'esol-tion
Tset top mar5in to one inch0 eI-al to the DPI o* the printer
iBottomMar5in6 Printer.'esol-tion
TDe*ine the Printable area Ai)th
iPrinter$rea+i)th 6 Printer.+i)th , iLe*tMar5in , i'i5htMar5in
TDe*ine the Printable area hei5ht
iPrinter$rea:ei5ht 6 Printer.:ei5ht , i#opMar5in , iBottomMar5in
Bui&d the output string /or our 1essage#+n/o ca&& and disp&a' that data to userC
strMs5 6 ;'esO ; S Str(Printer.'esol-tion) S ;0 +i)thO ; S Str(Printer.+i)th) S ;0 :ei5htO ; S Str(Printer.:ei5ht)
TshoA a Messa5eBox Aith )ata obtaine) *rom the printer set-p call
20+
messa5e.In*o(strMs5)
:e6t, ,e need to parse a&& o/ the content o/ the te6t in the >e6tArea" contro& into a
string arra'# +t is ver' eas' to do in GB and on&' ta-es a sing&e &ine o/ code# >o do this, ,e ,i&&
use the 2p&it /unction and set the de&imiter parameter to the 0Gn0 character ,hich designates
the end o/ the &ine o/ te6tC
ars#xt#oPrint 6 Split(#ext$rea=.#ext0 ;Nn;)
<e are read' to print# >o do so, 'ou M($& ca&& the Begin method and speci/' that 'ou ,ant
the Printer ob9ect to be the output device used b' the .ra, method#
DraA.Be5in(Printer) T InitialiRes the )raA ro-tine
+n our code be&o,, ,e have ca&&ed the .ra,#Rect /unction to dra, a border at one inch
margins around our page#
Tmake a bor)er aro-n) the pa5e

DraA.'ect(iLe*tMar5in0i#opMar5in0iPrinter$rea+i)th0iPrinter$rea:ei5ht)

TnoA Ae Aill loop thro-5h each line in the array an) print it
12' $C: s#xtLine I! ars#xt#oPrint
Tincrement the vertical (W) line position *or each line printe)
TDraA.#ext:ei5ht ret-rns the hei5ht in )ots (the -nit o* resol-tion
Tin )pi) o* every line in s#xtLine
i#xtPosW 6 i#xtPosW H DraA.#ext:ei5ht(s#xtLine)
T!oA0 test the line position ... i* is K the bottom o* the printer
Tarea then Ae nee) to reset it to Rero an) per*orm a neA pa5e
I1 i#xtPosW K6 (iPrinter$rea:ei5ht) #:!
i#xtPosW 6 9 Treinit the C-rrent #ext Position W
Printer.!eAPa5e
Tmake a bor)er aro-n) the neA pa5e
DraA.'ect(iLe*tMar5in0i#opMar5in0iPrinter$rea+i)th0iPrinter$rea:ei5ht)
!DI1 To-r test to see i* line *alls past bottom mar5in
:o,, ,e ma-e the ca&& to .ra,#>e6t to actua&&' print the te6t# >he /irst parameter
.ra,#>e6t ta-es is the string ob9ect sTt7ine representing our &ine o/ te6t to be printed /rom
the arra' o/ string arsTtTo3rint# >he ne6t t,o parameters, i7eftBargin and
(iTopBarginCiTt3os,) are used to de/ine the &e/t margin and the current vertica& >e6t K
position# Each &ine is incremented b' the va&ue (in dots he&d in the propert'
#rw1&ext6eight1 Optiona&&', 'ou can speci/' right and bottom margins, and an a&ignment
propert'# +n our case be&o,, ,e speci/ied the right margin, de/ined b' iPrinterArea<idth (as
210
,e ca&cu&ated above and omitted the bottom margin since it is maintained in the code o/ the
!O+ )OOP above# <e a&so added "$ to the dot va&ue o/ iLe/t1argin, to give some space
bet,een the &e/t side o/ the rectang&e and the beginning o/ each &ine# 7ina&&', ,e have
speci/ied the a&ignment o/ the te6t to be &e/t4a&igned#
T!oA Ae print the text line at the neA line position
DraA.#ext(s#xtLine0iLe*tMar5inH=90i#opMar5inHi#xtPosW0iPrinter$rea+i)th00$li5n.Le*t)
!7# Titeration o* the 12' L22P
>o /inish the print process, 'ou must remember to ca&& .ra,#EndC
DraA.n) T#hen print *inal contents an) e3ect last pa5e
!D
2ince our program on&' ,or-s ,ith te6t /i&es, there is an a&ternate, sometimes easier
method o/ printing# Kou can use the s'stem's bui&t4in pr (print command# +t is invo-ed using
the Gambas 2=ELL method# >his ca&& can a&&o, 'ou to print an' te6t /i&e /rom ,ithin 'our
program direct&' to the de/au&t printer# >o see ho, this method ,or-s, &et's add a menu item
to our program and tr' this# Go to the 71ain#/orm and press Print (s'stem method to
create a c&ic- event and add this codeC
PUBLIC SUB 1ileSysPrintItem8Click()
DIM aStrin5 $S Strin5

aStrin5 6 ;pr ,h N;; S sC-rrent1ile!ame S ;N; ; S ; ,oC U N;; S $pplication.Path SM sC-rrent1ile!ame S ;N; & lpr;

messa5e.In*o(aStrin50;2k;)
S:LL aStrin5
!D
+t &oo-s a &ot more di//icu&t that it rea&&' is# Let's go through the code# 7irst, ,e dec&are
a string variab&e, a2tring# :e6t ,e bui&d the string that ,i&& be passed o// to the s'stem as a
conso&e command# Because ,e must ensure the string is bui&t e6act&' as it ,ou&d have to be
t'ped /rom the conso&e, ,e must ensure it contains 5uote mar-s embedded in it# >he /irst part
o/ the stringC
;pr ,h
,i&& invo-e the s'stem command pr# >he 4h parameter speci/ies that ,e ,ant to have a header
printed on each page, in this case, it ,i&& be the current /i&e name, he&d in the variab&e
sCurrent7i&e:ame, ,hich is g&oba& in scope#
>he ne6t part o/ the string isC
NEE S sC-rrent1ile!ame S ;N;;
211
+n the /irst group o/ characters (TBB, TB is a s,itch that turns o// the second A as demar-ing a
te6t substring# <hen ,e pass the comp&eted string to the 2=ELL command, the /i&ename
must be enc&osed in &itera& 5uotation mar-s# >here/ore, a/ter the TB s,itch, the second A is 9ust
a &itera& opening 5uotation mar- /or the /i&ename# +n the group (ATBB /o&&o,ing the /i&ename,
the /irst A is the c&osing &itera& 5uote mar- /or the /i&ename, the /o&&o,ing TB restores the
demar-ing /unction o/ A /or te6t substrings, and the /ina& A is the mar-er /or the end o/ the /irst
substring# :ote that the Ps must be used inside the &itera& 5uotes to concatenate the 5uote
mar-s to the /i&ename# +/ the Ps ,ere used outside o/ the 5uotes, 'ou ,ou&d concatenate the
,ord AsCurrent7i&e:ameB, rather than the string va&ue contained in the g&oba& variab&e# >he
ne6t part isC
S D ,oC U NEE S $pplication.Path SM sC-rrent1ile!ame S DNE
,hich concatenates the 4o parameter (,hich speci/ies a margin o//set and a va&ue o/ G spaces#
>he X character is used on the command &ine to designate that the input stream (the /i&e to be
read to the printer comes /rom the /i&ename that /o&&o,s the X character# +n this case, ,e
need to de&imit our /i&ename ,ith 5uotes again, so the TB s,itch turns o// the norma& 5uote
demar-ing /unction, and the A that /o&&o,s the s,itch is the opening &itera& 5uote /or the
pathF/i&ename# Once again, the Ps that 9oin this pathF/i&ename string to the rest o/ the
substring must be inside the &itera& 5uotes# +n the /ina& group (ATB, the /irst A is the c&osing
&itera& 5uote /or the pathFsubstring, and the /o&&o,ing TB s,itch restores the demar-ing
/unction o/ the 5uote mar-s# >he &ast part o/ our command isC
& lpr;
>he _ character pipes the output to the &ine printer (&pr# >he /ina& A terminates the
comp&eted string that ,i&& describe the desired process to the 2=ELL command# +n a&&, it
ta-es one variab&e dec&aration and three &ines o/ code to print a /i&e using this techni5ue#
Either one ,i&& ,or- so choose the one that suits 'ou best# A&though the string that is passed
to 2=ELL is dense ,ith in/ormation, and the s'nta6 and spacing are critica&, peop&e ,ho are
e6perienced in using Linu6 commands /rom a termina& ,i&& /ind it /air&' straight/or,ard#
+/ the user c&ic-s on the 7i&e _ E6it menu item ,e cou&d simp&' c&ose the program#
=o,ever, ,e ,ant to give the user a chance to save be/ore e6it so ,e ,i&& pop up a 5uestion
dia&og to as- i/ the' ,ant to save the /i&e# +/ so, ,e ,i&& save it# +/ not, ,e simp&' e6it the
program#
PUBLIC SUB 1ilexitItem8Click()
DIM i'es-lt $S Inte5er

i'es-lt 6 Messa5e.Y-estion(;Save yo-r AorkJ;0;Wes;0;!o;0;Cancel;)
SLC# C$S i'es-lt
C$S =
1ile.Save(sC-rrent1ile!ame0 #ext$rea=.#ext)TSave0 then close.
212
C$S B TProcee) to close Aitho-t savin5.
C$S /
'#U'! T#erminate SLC#..!D SLC# Aitho-t save or close.
C$S LS
!D SLC#
M.close
!D
:ote that in the code above, 1essage#Huestion( tags the e&ements inside the
parentheses ,ith the -e'sC $, ", ;, and D# >he integer iResu&t ho&ds the -e' o/ the choice made
b' the user 44 $ never being a choice, since $ is the 5uestion# 1essage#Huestion ho&ds a
co&&ection, not an arra', and co&&ection -e's can be strings# >here/ore, it ,or-s e5ua&&' ,e&& to
dimension iResu&t A2 2tring, rather than A2 +nteger#
>hat's it /or the 7i&e 1enu# :o,, the rea& po,er o/ Gambas ,i&& become obvious as ,e
bui&d the code /or the Edit menu /unctions# 7rom this menu, ,e ,ant the user to be ab&e to
se&ect a&& te6t, undo, redo, cut, paste, cop' or ca&& a con/iguration routine# 7or our purposes,
the con/iguration routine ,i&& be prett' simp&e, but it shou&d be enough to sho, 'ou ho, to
accomp&ish the tas-#
+/ the user c&ic-s on the Edit _ 2e&ect A&& menu item, it ,i&& se&ect a&& the te6t in the
>e6tArea# >his is done be obtaining the &ength o/ the te6t using the >e6tArea"#Length
propert' and passing that va&ue to the >e6tArea"#2e&ection 1ethod ,ith a starting point o/
0ero and an ending point Length characters /rom that start point, as sho,n in the code be&o,#
PUBLIC SUB )itSelect$llItem8Click()
DIM ilen5th $S Inte5er
ilen5th 6 #ext$rea=.Len5th
#ext$rea=.Select(90ilen5th)
!D
>he code above cou&d a&so have been ,ritten in a more simp&i/ied manner ,ithout
using the +nteger variab&e i7ength# +t cou&d have been reduced to a sing&e &ine, as sho,n
be&o,C
PUBLIC SUB )itSelect$llItem8Click()
#ext$rea=.Select(90 #ext$rea=.Len5th)
!D
Either method ,i&& ,or- but the author's pre/erence is to use the second method as it
re/&ects the simp&icit' o/ Gambas ,hen programming# >his simp&icit' is seen in the use o/ the
bui&t4in @ndo, Redo, Cut, Paste and Cop' methods provided b' GB /or >e6tArea"#>e6t as ,e&&#
Gambas provides these methods so providing this capabi&it' /or 'our program users is a
simp&e matter o/ adding a sing&e &ine o/ code /or each menu item's c&ic- event, as sho,n be&o,C
213
PUBLIC SUB )itUn)oItem8Click()
#ext$rea=.Un)o
!D
PUBLIC SUB )it'e)oItem8Click()
#ext$rea=.'e)o
!D
PUBLIC SUB )itC-tItem8Click()
#ext$rea=.C-t
!D
PUBLIC SUB )itPasteItem8Click()
#ext$rea=.Paste
!D
PUBLIC SUB )itCopyItem8Click()
#ext$rea=.Copy
!D
NoteC since Gambas no. has the "e(ault (irst (orm name" GFmain.(ormH (essentiall$9 G(orm1H)9
succee"ing (orms ha'e the names GForm1.(ormH9 GForm2.(ormH9 etc.
Our Edit _ Pre/erences menu option ,i&& be used to sho, 'ou ho, to bring up a second
/orm in 'our program# <e ,i&& save the data gathered /rom the 7orm"#/orm in a con/iguration
/i&e named 7i&eOps#con/ and that ,i&& enab&e us to pass those saved va&ues bac- and /orth
bet,een the main /orm, 7orm"#/orm and the second /orm, 7orm;#/orm#
>his is the easiest ,a' to e6change data bet,een c&asses but it is possib&e to pass data as
parameters bet,een /orms# <e ,i&& discuss that &ater in this boo-# >he EditPre/s+temLC&ic-(
subroutine is prett' simp&e# <e 9ust sho, the second /orm#
PUBLIC SUB )itPre*sItem8Click()
1orm=.ShoA
!D
=ere is ,hat 7orm"#/orm ,i&& &oo- &i-eC
214
As 'ou can see, it is prett' basic# A >e6tLabe& is used to disp&a' the de/au&t path# >here
are t,o buttons, one to change the de/au&t path b' ca&&ing the standard .ia&og#2e&ect.irector'
routine and the other to return to the ca&&ing process, 7main#/orm in this case# =ere is the
code /or our 7orm"C
T .ambas class *ile
<hen the /orm is opened, ,e ,i&& disp&a' the caption APre/erencesB at the top o/ the ,indo,#
>he constructor routine Lne,( is ca&&ed automatica&&'#
1orm=.Caption 6 ; Pre*erences ;
!D
>he constructor ,i&& ca&& our subroutine ReadPre/s, passing the name o/ the con/iguration /i&e
as a parameter# +ile/ps.conf is the name ,e ,i&& use /or ho&ding our app&ication's con/ig data#
:e6t, ,e popu&ate the >e6tLabe&"#>e6t propert' ,ith the current de/au&t director', ,hich
de/au&ts to ,here the app&ication resides on dis-#
PUBLIC SUB 8neA()
'ea)Pre*s(;1ile2ps.con*;)
#extLabel=.#ext 6 $pplication.Path S ; is the )e*a-lt )irectory.;
!D
<hen the user c&ic-s the Change .e/au&t Path button, the /o&&o,ing routine is ca&&edC
#extLabel=.#ext 6 Dialo5.Path
!D
>he subroutine above simp&' ca&&s the Gambas standard dia&og /unction
.ia&og#2e&ect.irector' and updates the >e6tLabe&"#>e6t propert' ,ith ,hat the user has
21#
Figure /1: Form1.(orm "esign mo"e.
chosen as the de/au&t va&ue# <hen the user returns /rom this subroutine, the on&' other
option on the /orm is to c&ic- the Return button, ,hich e6ecutes this codeC
DIM MyCon*i5 $S Strin5
MyCon*i5 6 ;1ile2ps.con*;
+ritePre*s(MyCon*i5)
1orm=.Close
!D
As 'ou can see above, a &oca& string variab&e 1'Con/ig is dec&ared and set to the
con/iguration /i&ename 7i&eOps#con/# :e6t, ,e ca&& our <ritePre/s subroutine and pass the
va&ue o/ 1'Con/ig as a parameter# >hat /i&ename ,i&& be concatenated ,ith the ne,&' se&ected
path that the user sets in .ia&og#Path, ,i&& be stored in the /i&e and can be read b' an' other
c&ass that needs to /ind out this in/ormation# :ote, ho,ever, that this e2ercise ,i&& not resu&t in
'our ne, pre/erence being read /rom that con/iguration /i&e & ,e are sti&& reading the de/au&t
pre/erence /rom the 7i&eOps#con/ /i&e &ocated in our pro9ect /o&der, ,hen ,e ca&& the
ReadPre/s( subroutine# A workaround would be to create a new >ile in the proFect >older to hold
the location o> the con>iguration >ile) but chasing our con>iguration >ile around is not our purpose. -e
merel* want to show the use o> the $ialog.ath control.
=ere is the ReadPre/s( subroutine /or accomp&ishing this tas-C
PUBLIC SUB 'ea)Pre*s( *ilename $S Strin5)
T)eclare o-r local variables
DIM h1ileIn $S 1ile
Tsee i* the *ile alrea)y exists0 i* so open it.
I1 xist(*ilename) #:!
h1ileIn 6 2P! *ilename 12' '$D
Trea) o-r sin5le line o* )ata
Ti* there Aere more lines0 Ae co-l) set -p a +:IL !2# o* L22P
T-p)ate the )isplay )ata
#extLabel=.#ext 6 sInp-tLine
Tclose the *ile
CL2S < h1ileIn
LS
218
T there Aas no .con* *ile to open
Messa5e.In*o(;!o pre*erences .con* *ile present.;0;2Q;)
!DI1
!D
>he reciproca& routine, <ritePre/s( is sho,n be&o,C
PUBLIC SUB +ritePre*s( *ilename $S Strin5)
T)eclare o-r local variables
DIM MyPath $S Strin5
DIM h1ile2-t $S 1ile
Tnote Ae are -sin5 the Dialo5.Path val-e0 not $pplication.Path
MyPath 6 Dialo5.Path SM *ilename
I* Dialo5.Path UK DE TI* a neA path Aas set0 create the *ile *or Arite
h1ile2-t 6 2P! MyPath 12' +'I# C'$#
T print o-r )ata to the *ile
P'I!# < h1ile2-t0 MyPath
T close the *ile
CL2S < h1ile2-t
!DI1
!D
As 'ou ma' have a&read' /igured out, it is prett' simp&e but can easi&' be e6panded to
accommodate a&most an' set o/ con/iguration data 'our app&ication ma' need to store# Kou
are on&' &imited b' 'our imagination in Gambas# :o,, &et's &oo- at our 7ormat menu code# +n
the 7ormat menu, the on&' options ,e have are to change co&ors or /onts# <e are going to use
the Ht dia&ogs to accomp&ish both tas-s# =ere is ho, it is doneC
PUBLIC SUB 1ormatColorItem8Click()
T*irst0 pop -p a messa5e to explain hoA Ae are 5oin5 to Aork
Messa5e.In*o(;Select Back5ro-n) color *irst0 text color secon).;0;2Q;)
Tset )ialo5 caption to remin) the -ser Ae are selectin5 B$CQ.'2U!D
Dialo5.#itle 6 ; Select Back5ro-n) Color ;
Tcall the stan)ar) )ialo5 ro-tine to select color
Dialo5.SelectColor
T-p)ate o-r #ext$rea=.Backcolor Aith the val-e selecte).
#ext$rea=.BackColor 6 Dialo5.Color
Tset )ialo5 caption to remin) the -ser Ae are selectin5 12'.'2U!D
Dialo5.#itle 6 ; Select #ext Color ;
21?
Tcall the stan)ar) )ialo5 ro-tine to select color
Dialo5.SelectColor
T-p)ate o-r #ext$rea=.1oreColor Aith the val-e selecte).
#ext$rea=.1oreColor 6 Dialo5.Color
!D
2e&ecting the /ont and its attributes /or our program is 9ust as simp&e as it ,as to choose
co&ors# Basica&&', ,e ,i&& set the dia&og caption, ca&& the standard .ia&og#2e&ect7ont routine,
and update our >e6tArea"#7ont propert', &i-e thisC
PUBLIC SUB 1ormat1ontItem8Click()
Dialo5.#itle 6 ; Select *ont ;
Dialo5.Select1ont
#ext$rea=.1ont 6 Dialo5.1ont
!D
>his conc&udes our coding on 7orm"#C&ass# :o, ,e return to 7main#/orm# At the
beginning o/ our program, in the constructor routine, ,e had to enab&e the timer# >o actua&&'
ma-e the timer do an'thing, 'ou must program it# .oub&e4c&ic-ing on the timer contro& ,i&&
ta-e 'ou to the >imer"L>imer( subroutine, sho,n be&o,# +/ 'ou reca&&, ,e are going to have
our program disp&a' the current time on one &abe& and the current cursor position ,ithin the
te6t area on another &abe&# =ere is ho, ,e accomp&ish that tas-C
PUBLIC SUB #imer=8#imer()
T5et the time *or ri5ht noA an) convert to a strin5
Tto p-t in the #imeLabel.#ext property
#imeLabel.#ext 6 Str[(!oA)
TAe Aill 5et line an) col-mn )ata *rom the .Line an)
T.Col-mn properties o* the Label control an) -p)ate the
TPosLabel.#ext property Aith their val-esO
PosLabel.#ext 6 ;LineO ; S Str(#ext$rea=.Line) S ; ColO ; S Str(#ext$rea=.Col-mn)
!D
>he &ast menu is our =e&p menu# +t has t,o options, Contents and About#
PUBLIC SUB :elpContentsItem8Click()
T*or the DQDE )esktop0 yo- sho-l) -se this line
S:LL ;konI-eror *ileOMhomeM3onM.ambas8pro5ramsM1ile2psY#Mhelp.htmlE
T*or the .nome )esktop0 the 5nome,open comman) Aill open a *ol)er or *ile0 -sin5 the )e*a-lt broAser.
S:LL D5nome,open MhomeM3onM.ambas8pro5ramsM1ile2psY#Mhelp.htmlE
21%
!D
PUBLIC SUB :elp$bo-tItem8Click()
Messa5e.In*o(;UbKSimple #ext )itorUMbK by UbrK4ohn 'ittin5ho-se0 March0 B9==.;0 ;2Q;)
!D
21+
Chapter 14 )ath 5perations
Gambas per/orms mathematica& operations ,ith a &ibrar' o/ intrinsic and derived
/unctions# According to the on&ine enc'c&opedia <i-ipedia
"(
, Aan intrinsic function is a
function available in a given language whose implementation is handled specially by the
compiler. Typically, it substitutes a se"uence of automatically2generated instructions for the
original function call, similar to an inline function. Compilers that implement intrinsic
functions generally enable them only when the user has re"uested optimi6ation, falling bac&
to a default implementation provided by the language runtime environment otherwise#B
+ntrinsic /unctions are bui&t into the compi&er o/ a programming &anguage, usua&&' to
ta-e advantage o/ speci/ic CP@ /eatures that are ine//icient to hand&e via e6terna& /unctions#
>he compi&er's optimi0er and code generator /u&&' integrate intrinsic /unctions, ,hich can
resu&t in some surprising per/ormance speedups in ca&cu&ation# .erived /unctions, on the
other hand, are bui&t in Gambas b' using -no,n mathematica& /ormu&as to app&' speci/ic
a&gorithms that imp&ement intrinsic /unctions# A tab&e o/ derived /unctions and their
corresponding a&gorithms can be /ound at the end o/ this chapter#
Precedence of Operations
<hen 'ou use various operators in an e6pression in Gambas, there is a speci/ic
precedence o/ operations that Gambas uses to per/orm the operation# A ,e&&4de/ined protoco&
is /o&&o,edC
A&& e6pressions are simp&i/ied ,ithin parentheses /rom the inside outside
A&& e6ponentia& operations are per/ormed, proceeding /rom &e/t to right
A&& products and 5uotients are per/ormed, proceeding /rom &e/t to right
A&& sums and di//erences are per/ormed, proceeding /rom &e/t to right
Bearing in mind the order o/ operations (i#e#, the precedence, 'ou can use the
mathematica& /unctions in Gambas to per/orm 9ust about an' mathematica& operation needed
/or 'our programs# <e ,i&& cover each /unction, either intrinsic or derived in this chapter and
provide e6amp&es o/ ho, the' are used# >ab&e 6 at the end o/ this chapter provides 'ou ,ith
the o//icia& Adeve&operB hierarch' o/ operations, as de/ined in
Abs
Abs is an intrinsic /unction that returns the abso&ute va&ue o/ a number# >he abso&ute
va&ue o/ a number is its unsigned magnitude# 7or e6amp&e, Abs(4" and Abs(" both return "#
>he number argument can be an' va&id numeric e6pression# +/ number contains :u&&, an error
is returned\ i/ it is an initia&i0ed variab&e, 0ero is returned# 2tandard ca&&ing convention isC
14 /ee ,6'G httpG99en.wikipedia.org9wiki9IntrinsicH>unction.
220
$bs(n-mber)
>he /o&&o,ing e6amp&e uses the Abs /unction to compute the abso&ute va&ue o/ a number# >r'
this on 'our conso&eC
PUBLIC SUB MMain()
DIM My!-m $S (ariant
My!-m 6 $bs(,=.9//)
P'I!# My!-m
My!-m 6 $bs( B.CH,F.C)
P'I!# My!-m
!D
Acs 7 ACos
Acs M ACos is a derived /unction that computes the inverse cosine (arc4cosine o/ a
number# K W ACos(D returns the arc4cosine /or each e&ement o/ D# 7or rea& e&ements o/ D in
the domainZ4","[, ACos(D is rea& and in the range # 7or rea& e&ements o/ D outside the domain
Z4","[, ACos(D is comp&e6# >he ACos /unction operates e&ement4,ise on arra's# >he
/unction's domains and ranges inc&ude comp&e6 va&ues# A&& ang&es are returned in radians#
2'nta6 isC
val-e 6 $Cos ( !-mber )
E6amp&eC
P'I!# $cs(9.C)
=.9@X=>XCC==>X
P'I!# $cs(,=)
/.=@=C>BFC/C>
Acsh 7 ACosh
>he AcshMACosh is a derived /unction that computes the h'perbo&ic arc4cosine (inverse
h'perbo&ic cosine o/ a number D# +t operates e&ement4,ise on arra's# A&& ang&es are in
radians# >he domain inc&udes rea& numbers D such that D YW "# >he range o/ the h'perbo&ic
arc4cosine /unction is &imited to non4negative rea& numbers , such that , YW $# Ca&&ing
convention is as /o&&o,sC
val-e 6 $csh ( !-mber )
val-e 6 $Cosh ( !-mber )
221
=ere is an e6amp&e to tr' on the conso&eC
PUBLIC SUB Main()
DIM y $S (ariant
W 6 B
P'I!# $csh(W)
!D
=./=F>CX?>F>BC
Asn 7 A,in
Asn M A2in is a derived /unction that computes the arc4sine o/ a number# >he A2in(
/unction computes the principa& va&ue o/ the arc4sine o/ 6# >he va&ue o/ 6 shou&d be in the
range Z4","[# @pon success/u& comp&etion, Asn( returns the arc sine o/ 6, in the range Z4M;,
M;[ radians# +/ the va&ue o/ 6 is not in the range Z4","[ $#$ is returned# >he A2in( /unction
,i&& /ai& i/ the va&ue 6 is not in the range Z4","[# 2tandard ca&&ing convention isC
val-e 6 $sn ( !-mber )
val-e 6 $Sin ( !-mber )
=ere is an e6amp&eC
PUBLIC SUB Main()
DIM y $S (ariant
W 6 9.C
P'I!# $sn(W)
W 6 ,=.9
P'I!# $sn(W)
!D
9.CB/C>?XXCC>?
,=.CX9X>F/BFX>C
Asnh 7 A,inh
Asnh M A2inh is a derived /unction that computes the inverse h'perbo&ic sine
(hyperbolic arc2sine /or each e&ement o/ Q# >he A2inh /unction operates e&ement4,ise on
arra's# >he /unction's domains and ranges inc&ude comp&e6 va&ues# A&& ang&es are in radians#
222
val-e 6 $snh ( !-mber )
val-e 6 $Sinh ( !-mber )
An e6amp&e is as /o&&o,sC
PUBLIC SUB Main()
DIM y $S (ariant
W 6 B
P'I!# $snh(B)
!D
=.@@/F/C@XC=X>
Atn 7 ATan
Atn M A>an is an intrinsic /unction that computes the arc4tangent o/ a number# 7or rea&
e&ements o/ Q, A>an(Q is in the range Z4M;, M;[# >he A>an /unction operates e&ement4,ise
on arra's# >he /unction's domains and ranges inc&ude comp&e6 va&ues# A&& ang&es are in
radians# 2tandard ca&&ing convention isC
val-e 6 $tn ( !-mber )
val-e 6 $#an ( !-mber )
E6amp&eC
PUBLIC SUB Main()
DIM y $S (ariant
W 6 9.C
P'I!# $#an(W)
!D
9.@F/F@XF9>99=
223
Atnh 7 ATanh
AtnhMA>anh is a derived /unction that computes the inverse h'perbo&ic tangent (or
hyperbolic arc2tangent o/ a number# >he /unction operates e&ement4,ise on arra's# +t's
domains and ranges inc&ude comp&e6 va&ues# A&& ang&es are in radians# >he ca&&ing convention
o/ 3 > ,&nh(H) returns the h'perbo&ic arc4tangent /or each e&ement o/ Q#
val-e 6 $tnh ( !-mber )
val-e 6 $#anh ( !-mber )
=ere is an e6amp&e 'ou can tr' on the conso&e using Atanh(C
PUBLIC SUB Main()
DIM My'es-lt $S 1loat
DIM My!-m $S 1loat

My!-m 6 9.C
My'es-lt 6 $#anh(9.C)
P'I!# ;#he hyperbolic arc,tan5ent o* ; S My!-m S ; isO ; S My'es-lt
!D
9.C@>/9F=@@//@
Cos
Cos( in an intrinsic /unction that returns the cosine o/ an ang&e# >he Cos /unction
ta-es an ang&e and returns the ratio o/ t,o sides o/ a right triang&e# >he ratio is the &ength o/
the side ad9acent to the ang&e divided b' the &ength o/ the h'potenuse# >he resu&t &ies in the
range 4" to "# >o convert degrees to radians, mu&tip&' degrees b' M"*$# >o convert radians to
degrees, mu&tip&' radians b' "*$M # 2tandard ca&&in convention isC
'es-lt 6 Cos(n-mber)
>he number argument can be an' va&id numeric e6pression that e6presses an ang&e in
radians# >he /o&&o,ing e6amp&e uses the Cos /unction to return the cosine o/ an ang&eC
PUBLIC SUB Main()
DIM My$n5le $S 1loat
DIM MySecant $S 1loat
My$n5le 6 =./ T De*ine an5le in ra)ians.
224
MySecant 6 = M Cos(My$n5le) T Calc-late secant.
P'I!# ;Secant o* an5le ; S My$n5le S ; (in ra)ians) isO ; S MySecant
!D
Secant o* an5le =./ (in ra)ians) isO /.X/?//@=BX9XC
Cosh
Cosh is a derived /unction that computes the h'perbo&ic cosine o/ a number# >he Cosh
/unction operates e&ement4,ise on arra's# >he /unction's domains and ranges inc&ude
comp&e6 va&ues# A&& ang&es are in radians# 2tandard ca&&ing convention isC
(al-e 6 Cosh ( !-mber )
=ere is an e6amp&e to tr' on the conso&eC
PUBLIC SUB Main()
DIM My'es-lt $S 1loat
My$n5le 6 =.9 T $n5le expresse) in ra)ians.
My'es-lt 6 Cosh(My$n5le)
P'I!# ;Cosh() o* an5le ; S My$n5le S ; (in ra)ians) isO ; S My'es-lt
!D
Cosh() o* an5le = (in ra)ians) isO =.C@/9?9F/@?=C
!eg and (ad
.eg is an intrinsic conversion /unction that converts radians to degrees# Rad is a
reciproca& conversion /unction that converts degrees to radians# >he ca&&ing convention /or
.eg and Rad isC
(al-e 6 De5 ( $n5le )
(al-e 6 'a) ( $n5le )
An e6amp&e to tr' on the conso&e isC
PUBLIC SUB Main()
22#
P'I!# De5(Pi M B)
P'I!# 'a)(>9)
P'I!# 'a)(=?9) , Pi
!D
>9
=.CX9X>F/BFX>C
9
Ep
E6p is an intrinsic /unction that computes the e6ponentia& o/ a number# +t returns e
(the base o/ natura& &ogarithms, ,here the constant e is appro6imate&' ;#J"*;*; raised to a
po,er# >he number argument can be an' va&id numeric e6pression# +/ the va&ue o/ number
e6ceeds J$)#J*;J";*)D, an error occurs# >he E6p /unction comp&ements the action o/ the Log
/unction and is sometimes re/erred to as the anti4&ogarithm# >he ca&&ing convention isC
(al-e 6 xp ( !-mber )
=ere is an e6amp&eC
PUBLIC SUB Main()
P'I!# xp(=)
!D
B.X=?B?=?B?@C>
=ere is another e6amp&e that uses the E6p /unction to return e raised to a po,erC
PUBLIC SUB Main()
DIM My:Sin $S 1loat T De*ine an5le in ra)ians.
My$n5le 6 =./ TCalc-late the hyperbolic sine.
My:Sin 6 (xp(My$n5le) , xp(,= L My$n5le)) M B
P'I!# My:Sin
!D
228
=.F>?/?B@/XB>/
-i and -rac
7i6 is an intrinsic /unction that returns the integer part o/ a number# 7rac is an
intrinsic /unction that computes the /ractiona& part o/ a number# :ote that in the e6amp&e
be&o,, 7rac( returns the abso&ute va&ue o/ the /ractiona& resu&t o/ 4# >he standard ca&&ing
convention isC
(al-e 6 1ix ( !-mber )
(al-e 6 1rac ( !-mber )
E6amp&eC
PUBLIC SUB Main()
P'I!# 1ix(Pi)
P'I!# 1rac(Pi)
P'I!# 1ix(,Pi)
P'I!# 1rac(,Pi)
!D
/
9.=@=C>BFC/C>
,/
9.=@=C>BFC/C>
%nt
+nt((umber returns the mathematica& integer part o/ a number, i#e#, the greater
integer sma&&er than (umber#
(al-e 6 Int ( !-mber )
=ere are some e6amp&es 'ou can tr' on the conso&eC
P'I!# Int(Pi)
/
P'I!# Int(,Pi)
,@
22?
&og
Log is an intrinsic /unction that computes the natura& &ogarithm o/ e# >he &ogarithm
having base e. >he constant e is appro6imate&' ;#J"*;*; ,here e is a uni5ue number ,ith the
propert' that the area o/ the region bounded b' the h'perbo&a y E 8A, the 64a6is, and the
vertica& &ines E8 and Ee is "# >he notation ln is used in ph'sics and engineering to denote
the natura& &ogarithm, ,hi&e mathematicians common&' use the notation log # >he (umber
argument can be an' va&id numeric e6pression greater than $# 2tandard ca&&ing convention isC
val-e 6 Lo5 ( !-mber )
=ere is an e6amp&eC
PUBLIC SUB Main()
P'I!# Lo5(B.X=?B?)
P'I!# Lo5(=)
!D
9.>>>>>>/BX/@X
9
Kou can create a derived /unction to ca&cu&ate base4n &ogarithms /or an' number 6 b'
dividing the natura& &ogarithm o/ 6 b' the natura& &ogarithm o/ n as /o&&o,sC
Logn(6 W Log(6 M Log(n
=ere is an e6amp&e to tr'C
PUBLIC SUB Main()
DIM n $S 1loat
DIM x $S 1loat
DIM lo5n $S 1loat

n 6 B
x 6 =9
lo5n 6 Lo5(x) M Lo5(n)
P'I!# lo5n S ; is the res-lt o* Lo5n(; S x S ;);
!D
22%
/./B=>B?9>@??X is the res-lt o* Lo5n(=9)
&og;<
Log"$ is a derived /unction that computes the decima& &ogarithm o/ a number# Log"$(6
W Log(6 M Log("$# Ca&&ing convention isC
val-e 6 Lo5=9 ( !-mber )
E6amp&e C
P'I!# Lo5=9(=9)
=
2a and 2in
1a6 returns the greater e6pression o/ the &ist# E6pressions must be numbers or
dateMtime va&ues# 1in returns the sma&&er e6pression o/ the &ist# E6pressions must be numbers
or dateMtime va&ues#
val-e 6 Max ( xpression " 0 xpression ... % )
val-e 6 Min ( xpression " 0 xpression ... % )
E6amp&es
PUBLIC SUB Main()
P'I!# Max(F0 @0 X0 =0 /)
P'I!# Max(!oA0 CDate(;9=M9=M=>99;)0 C)ate(;9=M9=MB=99;))
P'I!# Min(F0 @0 X0 =0 /)
P'I!#
P'I!# Min(!oA0 CDate(;9=M9=M=>99;)0 CDate(;9=M9=MB=99;))
!D
X
9=M9=MB=99
=
9=M9=M=>99
22+
Pi
Pi returns ` O (umber# +/ (umber is not speci/ied, it is assumed to be one# 2tandard
ca&&ing convention isC
'es-lt 6 Pi ( " !-mber % )
E6amp&esC
P'I!# Pi
/.=@=C>BFC/C>
P'I!# Pi(9.C)
=.CX9X>F/BFX>C
(andomi=e and (nd
Randomi0e +nitia&i0es the pseudo4random number generator ,ith a methodo&og' that
uses the current date and time# >he ca&&ing convention isC
'an)omiRe (!-mber)
,here the number argument can be an' va&id numeric e6pression# Randomi0e uses (umber
to initia&i0e the Rnd /unction's random4number generator, giving it a ne, seed va&ue# +/ 'ou
omit number, the va&ue returned b' the s'stem timer is used as the ne, seed va&ue# +/
Randomi0e is not used, the Rnd /unction (,ith no arguments uses the same number as a seed
the /irst time it is ca&&ed, and therea/ter uses the &ast generated number as a seed va&ue# +n
other ,ords, /or an' given initia& seed, the same number se5uence is generated because each
successive ca&& to the Rnd /unction uses the previous number as a seed /or the ne6t number in
the se5uence#
+n order to repeat se5uences o/ random numbers, ca&& Rnd ,ith a negative argument
immediate&' be/ore using Randomi0e ,ith a numeric argument# Be/ore ca&&ing Rnd, use the
Randomi0e statement ,ithout an argument to initia&i0e the random4number generator ,ith a
seed based on the s'stem timer# @sing Randomi0e ,ith the same va&ue /or number does not
repeat the previous se5uence#
Rnd computes a pseudo4random /&oating point number, using the Lehmer a&gorithm#
+/ no parameters are speci/ied, Rnd returns a pseudo4random number in the interva& Z$ , "[# +/
on&' one parameter is speci/ied, Rnd returns a pseudo4random number in the interva& Z$,
1in[# +/ both parameters are speci/ied, Rnd returns a pseudo4random number in the interva&
Z1in, 1a6[# 2tandard ca&&ing convention /or Rnd isC
'n) ( " Min " 0 Max % )
230
>he number argument can be an' va&id numeric e6pression# >he Rnd /unction returns
a va&ue &ess than " but greater than or e5ua& to $# >he va&ue o/ number determines ho, Rnd
generates a random number# =ere is a tab&e that he&ps e6p&ain itC
Random Function Determination Table
*f nu"/er is +nd genertes
Less than 0ero >he same number ever' time, using number as the seed#
Greater than 0ero >he ne6t random number in the se5uence#
E5ua& to 0ero >he most recent&' generated number#
:ot supp&ied >he ne6t random number in the se5uence#
>o produce random integers that /a&& ,ithin an' given range, use this /ormu&aC
Int((-pperbo-n) , loAerbo-n) H =) L 'n) H loAerbo-n))
=ere, upperbound is the highest number in the range, and &o,erbound is the &o,est number
in the range# =ere is an e6amp&e program to tr' on the conso&eC
PUBLIC SUB Main()
DIM Dice $S Inte5er
P'I!# ;BetAeen 9 an) =O ;G
P'I!# 'n)
P'I!# ;BetAeen 9 an) BO ;G
P'I!# 'n)(B)
P'I!# ;BetAeen Pi an) PiLBO ;G
P'I!# 'n)(Pi0 Pi(B))
'an)omiRe
D2 +:IL Dice UK =
Dice 6 Int('n)(=0X))
T#hroAs the )ice betAeen = an) F
P'I!# ;Wo- threA a ; S )ice
L22P
!D
BetAeen 9 an) =O X.?BF/F>BCCX?=,F
BetAeen 9 an) BO 9.BF/9XCCXF=F@
BetAeen Pi an) PiLBO C.C=C/>FX?=X9F
Wo- threA a F
231
Wo- threA a @
Wo- threA a =
(ound
Round rounds a number to its nearest integer i/ .igits is not speci/ied# +/ .igits is
speci/ied, rounds to "$ ^ .igits #
(al-e 6 'o-n) ( !-mber " 0 Di5its % )
E6amp&eC
PUBLIC SUB Main()
P'I!# 'o-n)(Pi0 ,B)
P'I!# 'o-n)(=>XB0 B)
!D
/.=@
B999
,gn
2gn returns an integer indicating the sign o/ a number# +/ the number is 0ero, it returns
0ero# +/ the number is strict&' positive, it returns the integer number F"# +/ the number is
strict&' negative, it returns the integer number 4"# Ca&&ing convention isC
Si5n 6 S5n ( !-mber )
E6amp&eC
PUBLIC SUB Main()
P'I!# S5n(Pi)
P'I!# S5n(,Pi)
P'I!# S5n(9)
!D
=
232
,=
9
,in
2in is an intrinsic /unction that computes the sine o/ an ang&e# >he ang&e is speci/ied in
radians# >he sine /unction sin is one o/ the basic /unctions encountered in trigonometr' (the
others being the cosecant, cosine, cotangent, secant, and tangent# Let be an ang&e
measured counterc&oc-,ise /rom the 64a6is a&ong an arc o/ the unit circ&e# >hen sin is the
vertica& coordinate o/ the arc endpoint#
As a resu&t o/ this de/inition, the sine /unction is periodic ,ith period ;# B' the
P'thagorean theorem, sin a&so obe's the identit' sin
;
+ cos
2
N 1. The standard ca&&ing
convention /or 2in isC
(al-e 6 Sin ( $n5le )
E6amp&eC
PUBLIC SUB Main()
P'I!# Sin(PiMB)
!D
=
,inh
2inh is a derived /unction that computes the h'perbo&ic sine o/ a number# 2tandard
ca&&ing convention /or 2inh isC
(al-e 6 Sinh ( !-mber )
>he /o&&o,ing e6amp&e uses the E6p /unction to ca&cu&ate h'perbo&ic sine o/ an ang&eC
PUBLIC SUB Main()
DIM My:Sin $S 1loat T De*ine an5le in ra)ians
My$n5le 6 =./ T Calc-late hyperbolic sine.
My:Sin 6 (xp(My$n5le) , xp(,= L My$n5le)) M B
P'I!# My:Sin
!D
233
=.F>?/?B@/XB>/
,>r
25r is an intrinsic /unction that returns the s5uare root o/ a number# >he number
argument can be an' va&id numeric e6pression greater than or e5ua& to $ (non4negative# >he
ca&&ing convention isC
(al-e 6 SIr ( !-mber )
=ere is an e6amp&eC
P'I!# SIr(B)
=.@=@B=/CFB/X/
>he /o&&o,ing e6amp&e uses the 25r /unction to ca&cu&ate the s5uare root o/ a numberC
PUBLIC SUB Main()
DIM MySIr $S 1loat
MySIr 6 SIr(@) T 'et-rns B.
P'I!# MySIr S ; is the res-lt o* SIr(@);
MySIr 6 SIr(B/) T 'et-rns @.X>C?/=CB//=BXB.
P'I!# MySIr S ; is the res-lt o* SIr(B/);
MySIr 6 SIr(9) T 'et-rns 9.
P'I!# MySIr S ; is the res-lt o* SIr(9);
TMySIr 6 SIr(,@) T .enerates a r-n,time error.
TP'I!# MySIr S ; is the res-lt o* SIr(,@);
!D
Tan
>an is an intrinsic /unction that computes the tangent o/ an ang&e# >he ang&e argument
can be an' va&id numeric e6pression that e6presses an ang&e in radians# >an ta-es an ang&e
and returns the ratio o/ t,o sides o/ a right triang&e# >he ratio is the &ength o/ the side opposite
the ang&e divided b' the &ength o/ the side ad9acent to the ang&e# >o convert degrees to
radians, mu&tip&' degrees b' pi M"*$# >o convert radians to degrees, mu&tip&' radians b'
"*$Mpi# 2tandard ca&&ing convention isC
(al-e 6 #an ( an5le )
>he /o&&o,ing e6amp&e uses the >an /unction to return the tangent o/ an ang&eC
234
PUBLIC SUB Main()
DIM MyCotan5ent $S 1loat
My$n5le 6 =./ T De*ine an5le in ra)ians.
MyCotan5ent 6 = M #an(My$n5le) T Calc-late cotan5ent.
P'I!# MyCotan5ent
P'I!# #an(PiM@)
!D
9.BXXF=CF@FC@=
=
Tanh
>anh is a derived /unction that computes the h'perbo&ic tangent o/ a number# >he
standard ca&&ing convention /or >anh isC
(al-e 6 #anh ( !-mber )
E6amp&eC
PUBLIC SUB Main()
P'I!# #anh(=)
!D
9.XF=C>@=CC>CF
>he /o&&o,ing non4intrinsic math /unctions are provided in Gambas as bui&t4in intrinsic math
/unctionsC
Gambas Derived Mat Functions
!unction #erived e=uivlents
+nverse 2ine A2in(Q W Atn(Q M 25r(4Q O Q F "
+nverse Cosine ACos(Q W Atn(4Q M 25r(4Q O Q F " F ; O Atn("
='perbo&ic 2ine 2inh(Q W (E6p(Q 4 E6p(4Q M ;
='perbo&ic Cosine Cosh(Q W (E6p(Q F E6p(4Q M ;
='perbo&ic >angent >anh(Q W (E6p(Q 4 E6p(4Q M (E6p(Q F E6p(4Q
23#
+nverse ='perbo&ic 2ine A2inh(Q W Log(Q F 25r(Q O Q F "
+nverse ='perbo&ic Cosine ACosh(Q W Log(Q F 25r(Q O Q 4 "
+nverse ='perbo&ic >angent A>anh(Q W Log((" F Q M (" 4 Q M ;
Logarithm to base "$ Log"$(Q W Log(Q M Log(:
Oter Derived Mat Functions
2ecant 2ec(Q W " M Cos(Q
Cosecant Cosec(Q W " M 2in(Q
Cotangent Cotan(Q W " M >an(Q
+nverse 2ecant Arcsec(Q W Atn(Q M 25r(Q O Q 4 " F 2gn((Q 4" O (; O Atn("
+nverse Cosecant Arccosec(Q W Atn(Q M 25r(Q O Q 4 " F (2gn(Q 4 " O (; O Atn("
+nverse Cotangent Arccotan(Q W Atn(Q F ; O Atn("
='perbo&ic 2ecant =2ec(Q W ; M (E6p(Q F E6p(4Q
='perbo&ic Cosecant =Cosec(Q W ; M (E6p(Q 4 E6p(4Q
='perbo&ic Cotangent =Cotan(Q W (E6p(Q F E6p(4Q M (E6p(Q 4 E6p(4Q
+nverse ='perbo&ic 2ecant =Arcsec(Q W Log((25r(4Q O Q F " F " M Q
+nverse ='perbo&ic
Cosecant
=Arccosec(Q W Log((2gn(Q O 25r(Q O Q F " F" M Q
+nverse ='perbo&ic
Cotangent
=Arccotan(Q W Log((Q F " M (Q 4 " M ;
Logarithm to base : Log:(Q W Log(Q M Log(:
2ince Gambas does not direct&' provide /unctions /or these speci/ic derived /unctions,
,e are going to bui&d a modu&e that ,i&& e6tend Gambas capabi&ities b' providing a&& o/ the
/unctions &isted in the tab&e above as a /ina& e6ercise in this chapter# Our modu&e ,i&& be
named .erived and 'ou ,i&& be ab&e to access a&& o/ the /unctions in 'our code b' using the
/ormat .erived#function=name ,here function=name ,i&& be one o/ the /unctions ,e bui&d in
the ne6t section#
2tart Gambas and create a termina& app&ication# 11ain is 'our de/au&t startup c&ass#
:o, create a ne, modu&e and name it .erived# <hen the ne, code ,indo, opens /or the
.erived modu&e, go bac- to 11ain and enter the /o&&o,ingC
T .ambas class *ile
PUBLIC SUB Main()
DIM my(al $S 1loat

my(al 6 C=.C
+:IL my(al UK 9.9
P'I!# ;nter a n-mber K = or enter 9 to I-itO ;G
LI! I!PU# my(al
238
I1 my(al 6 9.9 #:! B'$Q
I1 my(al U6 =.9 #:!
P'I!#;!-mber Aas U6 =.9;
C2!#I!U
!DI1
P'I!# Derive).Sec(my(al) S ; is secant;
P'I!# Derive).CoSec(my(al) S ; is cosecant;
P'I!# Derive).Co#an(my(al) S ; is cotan5ent;
P'I!#
P'I!# Derive).$rcSec(my(al) S ; is arcsecant;
P'I!# Derive).$rccosec(my(al) S ; is arccosecant;
P'I!# Derive).$rccotan(my(al) S ; is arccotan5ent;
P'I!#
P'I!# Derive).:Sec(my(al) S ; is hyperbolic secant;
P'I!# Derive).:CoSec(my(al) S ; is hyperbolic cosecant;
P'I!# Derive).:Co#an(my(al) S ; is hyperbolic cotan5ent;
P'I!#
P'I!# Derive).:$rcSec(my(al) S ; is hyperbolic arcsecant;
P'I!# Derive).:$rcCoSec(my(al) S ; is hyperbolic arccosecant;
P'I!# Derive).:$rcCo#an(my(al) S ; is hyperbolic arccotan5ent;
P'I!#
P'I!# Derive).Lo5!(my(al0 B) S ; is Lo5! o*O ; S my(al S ; to base B;
P'I!# ;o* my(alO ; S my(al
+!D
!D
:o,, here is the code /or the .erived#modu&e /i&eC
T .ambas Derive).mo)-le *ile
PUBLIC 1U!C#I2! Sec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 =.9 M Cos(x)
'#U'! res-lt
!D
PUBLIC 1U!C#I2! CoSec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 =.9 M Sin(x)
'#U'! res-lt
!D
23?
PUBLIC 1U!C#I2! Co#an(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 =.9 M #an(x)
'#U'! res-lt
!D
PUBLIC 1U!C#I2! $rcSec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 $tn(xMSIr(xLx,=))H(S5n(x),=)L(BL$tn(=))
'#U'! res-lt
!D
PUBLIC 1U!C#I2! $rccosec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 $tn(xMSIr(xLx,=))H(S5n(x),=)L(BL$tn(=))
'#U'! res-lt
!D
PUBLIC 1U!C#I2! $rccotan(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 $tn(x)H(BL$tn(=))
'#U'! res-lt
!D
PUBLIC 1U!C#I2! :Sec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 B.9 M (xp(x) H xp(,x))
'#U'! res-lt
!D
PUBLIC 1U!C#I2! :CoSec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 B.9 M (xp(x) , xp(,x))
'#U'! res-lt
!D
PUBLIC 1U!C#I2! :Co#an(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 (xp(x) H xp(,x))M(xp(x) , xp(,x) )
'#U'! res-lt
!D
23%
Tthis ro-tine c-rrently pro)-ces an error in .ambas
Ti* yo- try to -se the *orm-la res-lt 6 Lo5((SIr(,xL(xH=))H=)Mx)
Tso this is a Aork,aro-n) to 5et the same res-lts
PUBLIC 1U!C#I2! :$rcsec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
DIM #emp= $S 1loat
DIM #empB $S 1loat
DIM #emp/ $S 1loat

#emp= 6 ((x L ,=)L( x H =))H=
#empB 6 SIr($bs(#emp=))
#emp/ 6 Lo5(#empB)
res-lt 6 #emp/ L ,=

Tthis call Aill 5enerate an error beca-se the
TSIr *-nction Aill not Aork Aith ne5ative val-es
Tres-lt 6 Lo5((SIr(,xL(xH=))H=)Mx)
'#U'! res-lt
!D
PUBLIC 1U!C#I2! :$rccosec(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 Lo5((S5n(x)LSIr(xLxH=)H=)Mx)
'#U'! res-lt
!D
PUBLIC 1U!C#I2! :$rccotan(x $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 Lo5((xH=)M(x,=))MB
'#U'! res-lt
!D
PUBLIC 1U!C#I2! Lo5!(x $S 1loat0 n $S 1loat) $S 1loat
DIM res-lt $S 1loat
res-lt 6 Lo5(x)MLo5(n)
'#U'! res-lt
!D
<hen 'ou run the program, 'ou ,i&& a prompt to enter a number Y " or $ to 5uit# Enter ( and
'ou shou&d see the /o&&o,ing resu&tsC
23+
nter a n-mber K = or enter 9 to I-itO @
,=.CB>??CFCF@FF is secant
,=./B=/@?X9??== is cosecant
9.?F/F>==C@@C= is cotan5ent
9.?CX9X=>@X?C is arcsecant
9.?9=CB>>>@B/B is arccosecant
B.?>FF=/>>9@F/ is arccotan5ent
9.9/FF=?>>/@X@ is hyperbolic secant
9.9/FF@/CX9/BF is hyperbolic cosecant
=.999FX==C9@9B is hyperbolic cotan5ent
,=.@XBB=>@?>C?/ is hyperbolic arcsecant
9.B@X@FF@F=C@X is hyperbolic arccosecant
9.BCC@=B?==??/ is hyperbolic arccotan5ent
B is Lo5! o*O @ to base B
o* my(alO @
nter a n-mber K = or enter 9 to I-itO
240
The gb_reserved_temp.h source >ile where operator precedence is de>ined in Gambas.
MM 2perator #ype (al-e :ierarchy ByteCo)e
``;6;0 'S182PBS0 2P8YU$L0 @0 C8Y a0
` ;66;0 'S182PBS0 2P8!$'0 @0 C8!$' a0
` ;(;0 'S182PP0 2P8LB'$0 =B0 a0
` ;);0 'S182PP0 2P8'B'$0 =B0 a0
` ;.;0 'S182PB0 2P8P#0 B9 a0
` ;V;0 'S182PB0 2P87CL0 B9 a0
` ;H;0 'S182PB0 2P8PLUS0 C0 C8$DD a0
` ;,;0 'S182PB0 2P8MI!US0 C0 C8SUB a0
` ;L;0 'S182PB0 2P8S#$'0 F0 C8MUL a0
` ;M;0 'S182PB0 2P8SL$S:0 F0 C8DI( a0
` ;P;0 'S182PBS0 2P81L70 X0 C8P2+ a0
` ;S;0 'S182P!0 2P8$MP0 ?0 C8C$# a0
` ;K;0 'S182PBS0 2P8.#0 @0 C8.# a0
` ;U;0 'S182PBS0 2P8L#0 @0 C8L# a0
` ;K6;0 'S182PBS0 2P8.0 @0 C8. a0
` ;U6;0 'S182PBS0 2P8L0 @0 C8L a0
` ;UK;0 'S182PBS0 2P8!0 @0 C8! a0
` ;";0 'S182PP0 2P8LSY'0 =B0 a0
` ;%;0 'S18!2!0 2P8'SY' =B0 a0
` ;$!D;0 'S182PBSM0 2P8$!D0 B0 C8$!D a0
` ;2';0 'S182PBSM0 2P82'0 B0 C82' a0
` ;!2#;0 'S182P=0 2P8!2#0 =90 C8!2# a0
` ;72';0 'S182PBSM0 2P872'0 B0 C872' a0
` ;NN;0 'S182PBS0 2P8DI(0 F0 C8YU2 a0
` ;DI(;0 'S182PBS0 2P8DI(0 F0 C8YU2 a0
` ;M2D;0 'S182PBS0 2P8M2D0 F0 C8'M a0
` ;LIQ;0 'S182PBS0 2P8LIQ0 @0 C8LIQ a0
` ;SM;0 'S182P!0 2P81IL0 >0 C81IL aa
241
Chapter 11 5b6ect-5riented Concepts
+n the /ie&d o/ computer science, ob9ect4oriented programming (OOP is considered a
computer programming paradigm# >he genera& idea is that a computer program is composed
o/ a co&&ection o/ individua& units (ca&&ed ob9ects, each o/ ,hich is capab&e o/ receiving
messages, processing data, and sending messages to other units or ob9ects# >his di//ers /rom
the traditiona& vie, o/ programming ,here a program is seen as a &ist o/ instructions that are
e6ecuted in a se5uentia& order b' the computer#
Proponents o/ ob9ect4oriented programming have c&aimed the approach gives
programmers more /&e6ibi&it' and /aci&itates ma-ing changes to programs ,hen needed# >he
paradigm is ver' popu&ar in companies and government entities that conduct so/t,are
engineering and deve&opment as a matter o/ course# 7urthermore, man' peop&e be&ieve OOP
to be easier to &earn /or novice programmers ,hen compared ,ith other &anguages such as
%ava, CFF, etc# OOP, the' c&aim, is simp&er to deve&op and maintain and that it &ends itse&/ to
a better understanding o/ comp&e6 situations and procedures than other programming
methods#
>here are an a&most as man' critics o/ the OO paradigm as there are proponents# 2ome
o/ the most common arguments critics raise are that OO4based &anguages &i-e 2ma&&ta&-, Lisp,
and others have had their progress sta&&ed ,ith the advent o/ ne,er &anguages &i-e CFF, C],
and %ava# 2ma&&, interpreted &anguages &i-e >c&, Per&, and P'thon have deve&oped a /air&' &arge
/o&&o,ing but the' are not ma-ing an' progress in the deve&opment o/ a true OO paradigm#
Critics a&so have said the ob9ect4oriented approach does not ade5uate&' address /uture
computing re5uirements# >he' /ee& ob9ect4oriented &anguages have sacri/iced simp&icit'the
ver' thing that ma-es programming approachab&e to a ,ider audience# %ava, /or e6amp&e, is
an e6treme&' comp&e6 imp&ementation o/ OO concepts# Others contend concepts &i-e
encapsu&ation and inheritance, ,hich ,ere origina&&' intended to !save# programmers /rom
themse&ves ,hi&e deve&oping so/t,are, have /ai&ed because the' imp&ement g&oba& properties#
1odu&arit' is another ,a' o/ -eeping things &oca& in scope so peop&e can understand code
better# >hat ,as ,hat encapsu&ation ,as supposed to accomp&ish# >oda', open source
so/t,are seems to have evo&ved a ,or-ab&e approach to the prob&em o/ code maintenance,
a&though it is not ,ithout its o,n issues#
Ob9ects promised reuse, and the programming communit' has not seen much success
,ith that# >he abi&it' to maintain a program once it has been ,ritten and to do &oca&i0ed
debugging and to do much &arger deve&opment e//orts are a&so reasons cited as signi/icant
advantages gained ,ith the use o/ OOPLs# +n the "))$s, over4optimism regarding the bene/its
o/ OO programming &ed businesses to e6pect mirac&es# <hen so/t,are deve&opers cou&d not
de&iver on the outrageous business p&ans based on those promises, ;$$" sa, businesses /a&&
&i-e dominos, &eaving the entire tech industr' in a recession# .e/unct companies &ittered
2i&icon !a&&e' &i-e &i-e so man' b&eached bones in a desert#
7ortunate&', Gambas ta-es a ver' pragmatic approach to the imp&ementation o/ OO
242
concepts, &everaging ,hat ,or-s and, un&i-e CFF, avoiding that ,hich ,i&& not ever ,or- ,e&&#
>he GB imp&ementation is an e&egant compromise bet,een true OO theor' and the business
rea&ities programmers have to contend ,ith toda'#

OOP is o/ten ca&&ed a paradigm rather than a st'&e or t'pe o/ programming to
emphasi0e the point that OOP can change the ,a' so/t,are is deve&oped b' changing the ,a'
that programmers and so/t,are engineers thin- about so/t,are# 1uch o/ the evo&ution o/ an'
&anguage depends on the O2 that supports that &anguage# <ith the advent o/ Linu6 and the
huge ground s,e&& o/ support /or open source so/t,are, the /uture &oo-s ver' bright /or
Gambas# :o,, &et's ta-e a &oo- at some o/ the basic OO concepts that GB supports#
-undamenta*s of Ob?ect Oriented Programming
Ob9ect4oriented programming is based upon severa& -e' conceptsC ob9ects, data
abstraction, encapsu&ation, po&'morphism, and inheritance# One distinguishing /eature o/
OOP is the methods used /or hand&ing data t'pes# /bject2type data is genera&&' re5uired to
satis/' programmer4de/ined constraints# A data4t'pe restricted to a speci/ic ob9ect is
considered to be a pri#ate data4t'pe# >his t'pe o/ &anguage4imposed constraint restricting
data t'pes to speci/ic ob9ects /orces programmers (b' design to code ,ithout re&'ing on
creating a &aundr' &ist o/ variab&es visib&e to ever' ob9ect in the program (g&oba& variab&es#
!ariab&es can be used and disposed o/ ,ithin the ob9ect or c&ass in ,hich the' are needed and
the' do not a//ect other parts o/ a program# >he actions ta-en b' the program ,here such
variab&es are used are re/erred to as methods# +n more traditiona& &anguages, methods e5uate
to /unctions or subroutines# +n OOP, these constraints a&so ma' e6tend to the use o/ methods
and are not e6c&usive to variab&es#
Ob9ect4oriented &anguages provide interna& mechanisms /or ensuring that variab&es and
methods are on&' visib&e and avai&ab&e ,ithin the scope o/ the c&ass or method in ,hich the'
are dec&ared# A&beit, some variab&es and methods are designed to be visib&e to a&& other
methods or c&asses o/ a pro9ect# +n those instances, the' are re/erred to as public variab&es
and methods# +n Gambas, variab&es and methods that are pub&ic are g&oba& in scope to the
class in ,hich the' are dec&ared# !ariab&es meant to be visib&e on&' to the methods in ,hich
the' are dec&ared as pri#ate ,ithin a given c&ass are created ,ith the .+1 -e',ord in
Gambas#
Ob6ects
O/jects are comprised o/ a&& the data and /unctiona&it' that e6ist ,ithin distinct units
in a running (e6ecuting computer program# Ob9ects are the /oundation o/ modu&arit' and
structure in an OOPL# >he' have t,o basic attributesC the' are se&/4contained and the' are
uni5ue&' identi/iab&e# =aving these t,o attributes a&&o,s a&& o/ the various program
components to corre&ate variab&es in a program ,ith various rea&4,or&d aspects o/ a prob&em
/or ,hich a program is intended to so&ve#
243
Data Abstraction
#t ,/strction 4 .ata abstraction is a methodo&og' used in OOPLs that enab&es a
programmer to speci/' ho, a data ob9ect is used# Abstraction a&&o,s a programmer to iso&ate
data ob9ects /rom the under&'ing detai&s o/ ho, the data is created (usua&&' b' using even
more primitive data ob9ects# +n other ,ords, the use o/ a data ob9ect, comprised o/ one or
more primitive data ob9ects, a&&o,s a programmer to structure his or her code to use data
ob9ects that operate on abstract data#
.ata ob9ects that are comprised o/ one or more primitive data ob9ects are ca&&ed
compound data ob9ects# <ith abstraction, the program can use data ,ithout ma-ing an'
assumptions about it (i#e#, the under&'ing detai&s o/ ho, or ,here that data came /rom that
isn't necessar' /or per/orming a given tas-# A concrete data representation is de/ined
independent o/ an' programs that use the data# >he inter/ace bet,een the concrete and
abstract data is a set o/ procedures, ca&&ed constructors, that imp&ement abstract data in terms
o/ the concrete representation# 1ethods (subroutines and /unctions ma' a&so be so
abstracted in the OOP paradigm#
Encaps-lation
Encpsultion 4 Ensures that users o/ an ob9ect cannot change the interna& state o/
the ob9ect in une6pected ,a's\ on&' the ob9ect's interna&&' de/ined methods are a&&o,ed to
access its state (or attributes# Each ob9ect e6poses an inter/ace that speci/ies ho, other
ob9ects ma' interact ,ith it# Other ob9ects ,i&& not -no, o/ this ob9ect's interna& methods and
must there/ore re&' upon this ob9ect's inter/ace in order to interact ,ith it#
%ol1morphism
Poly"orphis" means the abi&it' to ta-e more than one /orm# +n OOPLs, it re/ers to a
programming &anguage's abi&it' to process ob9ects di//erent&' depending on the data t'pe or
c&ass# 1ore speci/ica&&', po&'morphism is the abi&it' to rede/ine methods /or derived c&asses#
An operation ma' e6hibit di//erent behaviors in di//erent circumstances# >he behavior is
dependent upon the data t'pe used in the operation# 7or e6amp&e, given a base c&ass named
shape, po&'morphism enab&es the programmer to de/ine di//erent methods o/ area ca&cu&ation
/or an' number o/ derived c&asses, such as circ&es, rectang&es and triang&es# :o matter ,hat
shape an ob9ect is, app&'ing the area method to it ,i&& return the correct resu&ts#
Po&'morphism is used e6tensive&' in OOPLs ,hen imp&ementing inheritance and is
considered to be a re5uirement o/ an' true OOPL#
Inheritance
*nheritnce is the process b' ,hich ob9ects can ac5uire the properties o/ ob9ects that
e6ist in another c&ass# +n Gambas, a&& o/ the contro&s o/ the >oo&bo6 inherit the properties o/
the c&ass named Contro&# +n OOP, inheritance provides reusabi&it' and e6tensibi&it' (adding
additiona& /eatures to an e6isting c&ass ,ithout the need to modi/' it# >his is achieved b'
244
deriving a ne, c&ass /rom an e6isting c&ass and ma-ing changes to the ne, instance o/ that
c&ass# >he ne, c&ass ,i&& have combined the /eatures o/ both c&asses# +nheritance a&&o,s
ob9ects to be de/ined and created that are specia&i0ed imp&ementations o/ a&read'4e6isting
ob9ects# >he' can share (and e6tend the e6isting ob9ect's behavior ,ithout having to re4
imp&ement it#
The Gambas Approach to OOP
An OO program is genera&&' designed b' identi/'ing a&& o/ the ob9ects that ,i&& e6ist in a
s'stem# >he code ,hich actua&&' does the ,or- is irre&evant to the ob9ect due to
encapsu&ation# >he biggest cha&&enge in OOP is o/ designing an ob9ect s'stem that is
understandab&e and maintainab&e# +t shou&d be noted that there are distinct para&&e&s bet,een
the ob9ect4oriented paradigm and traditiona& s'stems theor'# <hi&e OOP /ocuses on ob9ects
as units in a s'stem, s'stems theor' /ocuses on the s'stem itse&/# 2ome,here in bet,een, one
ma' /ind so/t,are design patterns or other techni5ues that use c&asses and ob9ects as bui&ding
b&oc-s /or &arger components# 2uch components can be seen as an intermediate step /rom the
ob9ect4oriented paradigm to,ards the more pragmatica&&' oriented mode&s o/ s'stems theor'#
2uch appears to be the Gambas approach to OOP# +t is an e&egant, pragmatic so&ution that
ta-es the best o/ both approaches and ma-es programming eas' and simp&e#
Gambas has tried to -eep simp&icit' at the /ore/ront o/ an approach that &everages OO
concepts and compromises ,ith s'stems theor' ,here it ma-es good sense# +n that regard,
Gambas has ta-en a class2based approach to OOP# >he c&ass4based OOP approach is an OOP
paradigm ,here the concept o/ a c&ass is centra&# +n this approach encapsu&ation prevents
users /rom brea-ing invariants o/ the c&ass# C&ass invariants are estab&ished during
construction and are constant&' maintained bet,een ca&&s to pub&ic methods# >emporari&'
brea-ing c&ass invariance bet,een private method ca&&s is possib&e, a&though it is not
encouraged# 2ometimes, it is use/u& because it a&&o,s the imp&ementation o/ a c&ass o/ ob9ects
to be changed /or aspects not visib&e to or e6posed inside the c&ass inter/ace ,ithout having an
impact on user code that ma' have imp&emented /eatures o/ that c&ass#
>he de/inition o/ encapsu&ation in a c&ass4based OOP paradigm /ocuses on grouping
and pac-aging o/ re&ated in/ormation (cohesion rather than on program securit' issues# OOP
&anguages do not norma&&' o//er /orma& securit' restrictions to the interna& ob9ect state# @sing
a method o/ access is a matter o/ convention /or the inter/ace design# +nheritance is t'pica&&'
done b' grouping ob9ects into c&asses and de/ining c&asses as e6tensions o/ e6isting c&asses#
>his grouping o/ c&asses is sometimes organi0ed into tree or &attice structures, re/&ecting
behaviora& commona&it'#
Gambas Classes
+n Gambas, 'ou can de/ine 'our o,n c&asses# Remember that a c&ass is mere&' temp&ate
that is used b' the program at runtime# >he c&ass itse&/ is not used direct&'# >o use a c&ass,
'ou must ma-e a variab&e dec&aration o/ the c&ass data4t'pe, create a cop' o/ the c&ass /or the
24#
program to use, then instantiate the cop'# >he instantiated cop' is ca&&ed an ob9ect# 2ince a
c&ass is a rea& data4t'pe, the dec&aration o/ the ob9ect &oo-s &i-e an' other norma& variab&e
dec&arationC
ob3ect8name $S Class8name
+nstantiating an ob9ect means to create a ne, instance o/ the temp&ate and assign that
instance the name on the &e/t side o/ the e5ua& sign# +n GB, this is accomp&ished using the
NE- -e',ordL
ob3ect8name 6 !+ Class8name
<hen object=name is instantiated as a ne, cop' o/ the temp&ate de/ined b'
Class=name, the programming &anguage a&&o,s object=name to inherit a&& o/ the methods and
attributes o/ Class=name. <hen the ne, ob9ect is created, it automatica&&' invo-es a
constructor to initia&i0e itse&/ ,ith de/au&t variab&es#
,amp*e program: Contacts
>o i&&ustrate the use o/ a c&ass in Gambas, ,e are going to create a samp&e program that
imp&ements a contacts boo-# +t is going to be /air&' simp&e but ,i&& be use/u& to maintain
contacts# >o begin, create a ne, pro9ect named C&asses and ,hen 'ou get to the +.E, create a
c&ass (not a startup c&ass named Contact# >his is ,here ,e ,i&& start ,ith our program,
bui&ding a c&ass de/inition /or a Contact#
The Contact class
T .ambas Contact.class *ile
PUBLIC 1irst!ame $S Strin5
PUBLIC Last!ame $S Strin5
PUBLIC Initial $S Strin5
PUBLIC S-**ix $S Strin5
PUBLIC Street= $S Strin5
PUBLIC StreetB $S Strin5
PUBLIC City $S Strin5
PUBLIC State $S Strin5
PUBLIC \ipC $S Strin5
PUBLIC \ip@ $S Strin5
PUBLIC $reaco)e $S Strin5
PUBLIC Pre*ix $S Strin5
PUBLIC Last@ $S Strin5
PUBLIC 'ecor)ID $S Inte5er
248
<e ,ant our c&ass to provide t,o methods, one to retrieve our contact data /rom the
/i&e it is stored in and one to put data into that /i&e# Appropriate&', the t,o methods ,i&& be
named Contact.5et-ata and Contact.3ut-ata#
Contact7GetData .etho
Let's start ,ith the Get.ata method, ,hich is dec&eared as a /unction because it ,i&&
ta-e a co&&ection variab&e as a parameter and return a co&&ection filled ,ith data /rom the
contacts.data /i&e i/ that data e6ists# <e ,i&& dec&are &oca& variab&es ,ithin our methods b'
using the .+1 -e',ord# :ote that ,e cou&d dec&are these variab&es as PR+!A>E outside o/
the method de/initions and it ,ou&d render them visib&e on&' to the methods ,ithin the
contact c&ass# =o,ever, dec&arations &oca& to the method themse&ves /urther restricts the
scope and ma-es the entire c&ass /i&e c&eaner in appearance /rom a user perspective# >he' ,i&&
see a&& the pub&ic methods and variab&es and nothing more#
>he co&&ection variab&e is passed in as a parameter /rom the constructor ca&& in
71ain#c&ass so it is not necessar' to dec&are it separate&'# >he /unction ,i&& return a co&&ection
variab&e so ,e add ,$ Collection to the end o/ the /unction dec&aration# <e ,i&& sho, ho,
the co&&ection variab&e cThe-ata is passed to this /unction ,hen it is ca&&ed /rom the
71ain#c&ass /i&e#
PUBLIC 1U!C#I2! .etData (c#heData $S Collection) $S Collection
Tthis strin5 var Aill hol) each line o* )ata rea) *rom the *ile

TAe nee) a *ile han)le an) tAo strin5 vars *or b-il)in5 *ilenames
DIM h1ileIn $S 1ile
DIM *ilename $S Strin5
DIM *-llpath $S Strin5
Tthis class variable is -se) to convert the strin5 )ata Ae rea) in
T*rom *ile into a contact recor). +e )eclare the variable here an)
TAill instantiate it beloA
DIM MyContact'ecor) $S Contact
Ta local inte5er var to keep track o* hoA many recor)s Ae a))e)
DIM 'ecor)!-m $S Inte5er
Tthis variable Aill take the strin5 rea) in an) convert all the *iel)s
Tthat are comma,)elimite) into an array -sin5 the split statement
DIM arsInp-t1iel)s $S Strin5"%
Tthis co-nter is -se) to loop thro-5h the array an) assi5n val-es
Tto the contact recor)s
24?
*ilename 6 ;contacts.)ata; Thar)co)e) beca-se it Aill not chan5e
TAe Aill -se the c-rrent )ir Ahere the app is to b-il) *-ll pathname
*-llpath 6 $pplication.Path SM *ilename
TnoA0 see i* the *ile alrea)y exists0 i* so open it *or '$D.
I1 xist(*-llpath) #:!
2P! *-llpath 12' '$D $S <h1ileIn
Tstart Aith recor) =
'ecor)!-m 6 =
TAe Aill loop thro-5h every line o* )ata -ntil Ae reach n) o* *ile
Tevery contact a))e) to the collection m-st be instantiate)
Teach time a recor) is a))e) to the collection. Wo- C$!
Tre-se the same class var *or each re,instantiation tho-5h.
MyContact'ecor) 6 !+ Contact There is Ahere it reneAs itsel*
Trea) the line in *rom *ile an) store in strin5 var sInp-tLine
T-se) *or console )eb-55in5
P'I!# ;'ea)in5O ; S sInp-tLine
TnoA0 *ill o-r array o* strin5s -sin5 Split to convert the line
To* strin5 )ata rea) in to *iel)s in an array
arsInp-t1iel)s 6 Split(sInp-tLine0 ;0;)
T*or )eb-5 only to shoA that all *iel)s convert correctly
12' co-nter 6 9 #2 =@
P'I!# ;Loa)in5O ; S arsInp-t1iel)s"co-nter%
!7#
TnoA0 Ae p-t the *iel) )ata into o-r local contact class var
Tan) Aill a)) that contact recor) to the collection o* contacts
MyContact'ecor).1irst!ame 6 arsInp-t1iel)s"9%
MyContact'ecor).Initial 6 arsInp-t1iel)s"=%
MyContact'ecor).Last!ame 6 arsInp-t1iel)s"B%
MyContact'ecor).S-**ix 6 arsInp-t1iel)s"/%
MyContact'ecor).Street= 6 arsInp-t1iel)s"@%
24%
MyContact'ecor).StreetB 6 arsInp-t1iel)s"C%
MyContact'ecor).City 6 arsInp-t1iel)s"F%
MyContact'ecor).State 6 arsInp-t1iel)s"X%
MyContact'ecor).\ipC 6 arsInp-t1iel)s"?%
MyContact'ecor).\ip@ 6 arsInp-t1iel)s">%
MyContact'ecor).$reaco)e 6 arsInp-t1iel)s"=9%
MyContact'ecor).Pre*ix 6 arsInp-t1iel)s"==%
MyContact'ecor).Last@ 6 arsInp-t1iel)s"=B%
MyContact'ecor).'ecor)ID 6 CInt(arsInp-t1iel)s"=/%)
MyContact'ecor).Delete) 6 CBool(arsInp-t1iel)s"=@%)
T*or )eb-5 o-tp-t to the console
P'I!# ;$))in5 )ata *or recor)O ; S 'ecor)!-m S ; ;G
P'I!# MyContact'ecor).1irst!ame S ; ; S MyContact'ecor).Last!ame
Tall recor) *iel)s are assi5ne) )ata0 so Ae a)) to collection
c#heData.$))(MyContact'ecor)0 CStr('ecor)!-m))
T*or )eb-5 o-tp-t to the console
P'I!# c#heData"CStr('ecor)!-m)%.Last!ame S ; store).;
Tincrement o-r recor) co-nter an) clear the sInp-tLine variable
I!C 'ecor)!-m
sInp-tLine 6 ;;
+!D Tloop *or more recor)s
Tclose the *ile Ahen no more recor)s exist in the *ile
CL2S < h1ileIn
LS Tno *ile *o-n)0 p-t -p a messa5e to the -ser
Messa5e.In*o(;!o contacts.)ata *ile present.;0;2Q;)
!DI1

T*or )eb-5 only0 Ae Aill list all the recor)s in the collection
P'I!# ;:ere is Ahat is store) in c#heDataO;
12' $C: MyContact'ecor) I! c#heData
!7#
'#U'! c#heData Tret-rn the collection (noA *ille)) Aith )ata
!D To* .etData
Contact7%-tData .etho
>he reciproca& routine to Get.ata is Put.ata, ,here ,e ,i&& store the co&&ection o/ data
that is considered most current# <hatever edits or changes have been made ,i&& be re/&ected
24+
in this save operation# <e ,i&& save the date to a /i&e, storing the record as a comma4de&imited
string# Each &ine o/ output ,i&& represent one contact record#
>he Put.ata method is dec&ared as a subroutine since it does not return a variab&e# +t
ta-es a sing&e parameter, the co&&ection ob9ect ,e ,ish to store# +n this case, c>he.ata is the
co&&ection passed into this subroutine#
PUBLIC SUB P-tData (c#heData $S Collection)
Tthis strin5 var Aill hol) each line o* )ata rea) *rom the *ile

TAe nee) a *ile han)le an) tAo strin5 vars *or b-il)in5 *ilenames
DIM h1ile2-t $S 1ile
DIM *ilename $S Strin5
DIM *-llpath $S Strin5
Tthis class variable is -se) to convert the strin5 )ata into
Ta contact recor). +e )eclare the variable here an)
TAill instantiate it beloA
Ta local inte5er var to keep track o* hoA many recor)s Ae a))e)
DIM 'ecor)!-m $S Inte5er
Tinstantiate a neA recor) that is blank. !ote that since Ae are not
Ta))in5 this recor) to a collection0 it is not necessary to reneA
Tit by re,instantiatin5 it each time.
MyContact'ecor) 6 !+ Contact

Tstart at recor) =
'ecor)!-m 6 =
TAe have a har),co)e) *ile name so Ae only nee) the path to the pro5ram
Tbeca-se Ae Aill store the )ata Ahere the pro5ram resi)es.
*ilename 6 ;contacts.)ata;
*-llpath 6 $pplication.Path SM *ilename
TAe have to speci*y +'I# C'$# Ahen Ae open the *ile. I* the *ile
Texists0 it Aill be opene) *or +'I#. I* it )oes not exist0 then Ae
TAill create a neA *ile an) Arite to that.
2#0
2P! *-llpath 12' +'I# C'$# $S <h1ile2-t
TnoA0 Ae loop thro-5h each recor) in the collection. !ote that Ae
T-se the 12' $C: constr-ct to )o this.
12' $C: MyContact'ecor) I! c#heData
TAe concatenate each *iel) to the last0 insertin5 commas
Tto be -se) as *iel) )elimiters *or the rea) operation
sInp-tLine 6 sInp-tLine S MyContact'ecor).1irst!ame S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).Initial S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).Last!ame S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).S-**ix S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).Street= S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).StreetB S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).City S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).State S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).\ipC S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).\ip@ S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).$reaco)e S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).Pre*ix S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).Last@ S ;0;
sInp-tLine 6 sInp-tLine S MyContact'ecor).'ecor)ID S ;0;
sInp-tLine 6 sInp-tLine S CStr(MyContact'ecor).Delete)) S ;0;
T*or )eb-5 only0 to shoA Ahat is bein5 store)
P'I!# ;Storin5O ; S sInp-tLine
Tthis call is act-ally Ahat p-ts the )ata into the *ile
P'I!# <h1ile2-t0 sInp-tLine
Tclear o-t o-r strin5 var to be re-se) in the next iteration
sInp-tLine 6 ;;
!7# Titeration o* the loop to en-merate ob3ects
T5ot them all Aritten noA0 so close the *ile
CL2S < h1ile2-t
'#U'! TAitho-t passin5 a variable back0 hence s-bro-tine
!D
Our program ,i&& a&&o, a user to add, change or de&ete a contact and store that data to a
data /i&e# Contact data is managed in our program as a co&&ection o/ ob9ects that are o/ t'pe
Contact, ,hich ,e de/ined in the Contact#c&ass /i&e above# <e ,i&& a&&o, the user to move to
the ver' /irst item in the co&&ection, scro&& to ne6t or previous items, go to the &ast item, update
data on the current /orm, save the current data to /i&e, and e6it#
2#1
A&& in a&&, it does most o/ the basics necessar' /or contact management# <e ,i&& a&so
add a search /eature (using a modu&e that ,i&& /ind the /irst instance o/ a contact b' searching
/or a &ast name# Ama0ing&', to accomp&ish a&& o/ this ta-es ver' &itt&e code in GambasS
&.ain7class 0ile
2ave the Contact#c&ass /i&e and c&ose it# Our contact c&ass de/inition is comp&ete so no,
,e ,i&& need to create a /orm named 71ain# 71ain ,i&& serve as the main inter/ace bet,een
the user and the program and it's data# =ere is ,hat our /inished /orm ,i&& &oo- &i-eC
:o,, &et's &oo- at the program that ,i&& use the contact c&ass# >he program ,i&& re5uire
/our pub&ic variab&es, as sho,n be&o,# Our constructor routine ,i&& automatica&&' &oo- /or and
&oad the de/au&t contact /i&e, ,hich ,e named contacts#data# +t is not necessar' /or the user to
-no, or use this /i&ename so it is hard4coded into the methods ,here it is used# +/ the
constructor routine Mnew() cannot &oad a /i&e, it ,i&& create one dumm' record so the user
never sees a b&an- startup screen#
T .ambas 1Main class *ile
TContacts Aill represent the collection o* recor)s *or the a))r book
PUBLIC Contacts $S Collection
Trepresents a sin5le contact recor) -se) by all s-bro-tines
PUBLIC Contact'ecor) $S Contact
Tin)ex that points to the c-rrent recor)
PUBLIC 'ecor)Pointer $S Inte5er
2#2
Figure /2: Finishe" ontacts program.
TAe Aill nee) a strin5 var to -se Ahen the -ser searches by last name
PUBLIC SearchQey $S Strin5
&.ain Constr-ctor
Tthe constr-ctor ro-tine calle) Ahen 1Main8open() is calle)
PUBLIC SUB 8neA()
Tinstantiate the collection that Aill hol) o-r a))ress recor)s
Contacts 6 !+ Collection
Tinstantiate a neA contact (recor)) that is blank
Contact'ecor) 6 !+ Contact
T*or )eb-5 only
P'I!# ;Callin5 .etData...;
Tcall the .etData metho) )e*ine) in the contact class )e*inition
Contact'ecor)..etData(Contacts)
Tset the recor) pointer to the last recor) *o-n) in the )ataset
'ecor)Pointer 6 Contacts.Co-nt
T*or )eb-5 only
P'I!# ;In 8neA()0 rtn *m .etData AithO ; S 'ecor)Pointer S ; recor)s.;
Tthe )e*a-lt constr-ctor Aill ens-re at least one recor) exists
Ti* the Contacts collectionTs co-nt property shoAs U = recor).
I1 'ecor)Pointer U = #:!
Ta)) o-r )-mmy )ata
Contact'ecor).1irst!ame 6 ;4ohn;
Contact'ecor).Initial 6 ;Y;
Contact'ecor).Last!ame 6 ;P-blic;
Contact'ecor).S-**ix 6 ;II;
Contact'ecor).Street= 6 ;=B/@C .ambas Drive;
Contact'ecor).StreetB 6 ;$pt =9=;
Contact'ecor).City 6 ;Dancer;
Contact'ecor).State 6 ;#7;
Contact'ecor).\ipC 6 ;XX>B>;
Contact'ecor).\ip@ 6 ;9=9=;
Contact'ecor).$reaco)e 6 ;???;
2#3
Contact'ecor).Pre*ix 6 ;FFF;
Contact'ecor).Last@ 6 ;@@@@;
Contact'ecor).'ecor)ID 6 =
Contact'ecor).Delete) 6 1$LS
'ecor)Pointer 6 Contact'ecor).'ecor)ID
Contacts.$)) (Contact'ecor)0 CStr(Contact'ecor).'ecor)ID) )
!DI1
Tcheck o-r collection to make s-re recor)s exist
I1 Contacts.xist(CStr('ecor)Pointer)) #:!
T*or )eb-5 only
P'I!# ;'ecor) )ata exists *or ; S CStr('ecor)Pointer) S ; recor)s.;
Tthis *or loop is *or )eb-5 only
12' $C: Contact'ecor) I! Contacts
P'I!# Contact'ecor).1irst!ame S ; ; S Contact'ecor).Last!ame
!7#
LS
Ti* no recor)s0 p-t -p a messa5e box to in*orm -ser
Messa5e.In*o(;'ecor)s )o not existV;0;2k;)
!DI1
!D
&orm8Open S-bro-tine
Our program ,i&& automatica&&' open the /orm using the 7ormLOpen( subroutine
be&o,# 2ince 71ain#/orm is de/ined as a startup /orm, it is not necessar' to ca&& the
7@ain#2ho, method# A&& ,e are going to do here is set the caption to disp&a' at the top o/ the
,indo, ,hen the program runs and get the record pointed to b' the current record pointer#
+n this case, the pointer shou&d point to the &ast record &oaded /rom the contacts /i&e a/ter
program /&o, returns /rom the constructor#
Tset the pro5ram caption
1Main.Caption 6 ; Contacts Mana5er ;
Tstart Aith the recor) pointe) to a*ter the constr-ctor call
TAhich sho-l) be the last recor) in the collection
Contact'ecor) 6 Contacts"CStr('ecor)Pointer)%
Tthis s-bro-tine Aill re*resh all *iel)s Aith c-rrent recor) )ata
Up)ate1orm
!D
2#4
Aing Controls to &.ain7&orm
+t is time to put a&& o/ the contro&s on the /orm and give them names# <e ,i&& be using
nine >oo&Buttons, one regu&ar Button, "( &abe&s and "D >e6tBo6es# <e ,i&& a&so need to use
nine icons, ,hich ,e can obtain /rom the usrMshareMiconsMde/au&t4-deMD;6D; /o&der ((/TE*
your system may be different so browse around to find where the icons are stored if needed#
>he icons used /or this program are as /o&&o,sC
.he .oo(Buttons
>he nine >oo&Buttons that use these icons in their Picture propert' are namedC
1irst'ecor)Btn Prev'ecor)Btn !ext'ecor)Btn
Last'ecor)Btn ClearBtn Up)ate
$))Btn Delete'ecor)Btn Save$llBtn
Create nine >oo&Buttons and arrange them on the /orm as sho,n at the beginning o/
this chapter# Assign the names sho,n above to the >oo&Buttons and set the respective button
Picture properties to the names o/ the icons 'ou chose /or 'our program, based on ,hat 'our
s'stem distribution provides# <orst case scenario is that 'ou can use the bui&t4in icon editor
in Gambas to create 'our o,n icons#
.he Cuit Button
Once 'ou have comp&eted the >oo&Buttons, ,e ,i&& add the regu&ar button as our AHuitB
button# 2e&ect a Button /rom the >oo&Bo6 and p&ace it on the /orm in the &o,er right corner, as
c&ose as 'ou can to the 7igure above# 2et the >e6t propert' /or this button to AHuitB# As &ong
as ,e are here, ,e can code the program's e6it routine, ,hich ,i&& be ca&&ed ,hen this button
is c&ic-ed# .oub&e4c&icon the Huit button and 'ou ,i&& be p&aced in the code editor# Add this
codeC
Tprompt to save )ata be*ore Ae I-it
SLC# Messa5e.Y-estion(;Save be*ore exitJ;0;Wes;0 ;!o;0 ;Cancel;)
2##
Figure /3: Toolbar icons use" in our sample
program.
C$S =
Ti* the -ser says yes0 Ae save
Save$llBtn8Click
C$S B TAe )onTt save0 3-st close
C$S / Tthey cancele)0 so Ae ret-rn to the pro5ram
'#U'!
C$S LS TAe )o nothin5 b-t close
!D SLC#
M.Close There Ae close the Ain)oA
!D Tpro5ram stops
Adding 1abe( and .e;tbo; 0ontro(s
Probab&' the most tedious part o/ deve&oping this program is ne6t, adding the Labe&
and >e6tBo6 contro&s to the /orm# >r' to arrange them as sho,n be&o,# 7or the Labe&
contro&s, 'ou can ta-e the de/au&t variab&e names provided b' Gambas /or a&& o/ the &abe&s
e6cept the one at the bottom o/ the /orm ,here ,e ,i&& disp&a' our 0ecord n of n data# >hat
&abe& shou&d be named 2tatusLabe&# >he >e6tbo6 /ie&ds, as sho,n /rom top &e/t to bottom right
on the /orm, shou&d be named as /o&&o,sC
1irst!ame
MI
Last!ame
S-**ix
Street=
StreetB
City
State
\ipC
\ip@
$reaCo)e
DialPre*ix
DialLast@
=ope/u&&', the names shou&d be se&/4e6p&anator' (i.e., self2documenting code and 'ou
have no prob&ems creating the /orm# Be care/u& to use the correct case and t'pe the names
e6act&' as sho,n above, other,ise 'ou ,i&& be trac-ing do,n un4dec&eared variab&es ,hen 'ou
tr' to run the program# At this point, 'our /orm, in design mode, shou&d &oo- &i-e thisC
2#8
Upate&orm9: S-bro-tine
>he @pdate7orm( routine ,i&& be ca&&ed ever' time data on the /orm has changed and
needs to be re/reshed so the user ,i&& see the updates as the' occur# >his routine posts each
/ie&d on the /orm ,ith the current data /ound in the co&&ection based on the current record
pointer# A&so, the &abe& 2tatusLabe& is updated ,ith the current record number o/ n records in
the co&&ection /rom here# Let's ,a&- through the codeC
PUBLIC SUB Up)ate1orm()
Tcheck to ens-re there are recor)s be*ore Ae )o anythin5
TAe *o-n) recor)s so noA Ae move to the recor) at c-rrent pointer
T*or )eb-5 only
P'I!# ;In Up)ate1orm Aith 'ecor)Pointer o*O ; S 'ecor)Pointer
Tassi5n #extbox.#ext val-es Ahatever is store) in the contact recor)
1irst!ame.#ext 6 Contact'ecor).1irst!ame
MI.#ext 6 Contact'ecor).Initial
Last!ame.#ext 6 Contact'ecor).Last!ame
S-**ix.#ext 6 Contact'ecor).S-**ix
Street=.#ext 6 Contact'ecor).Street=
StreetB.#ext 6 Contact'ecor).StreetB
City.#ext 6 Contact'ecor).City
State.#ext 6 Contact'ecor).State
2#?
Figure /#: F2ain as seen in "esign mo"e.
\ipC.#ext 6 Contact'ecor).\ipC
\ip@.#ext 6 Contact'ecor).\ip@
$reaCo)e.#ext 6 Contact'ecor).$reaco)e
DialPre*ix.#ext 6 Contact'ecor).Pre*ix
DialLast@.#ext 6 Contact'ecor).Last@
T-p)ate the c-rrent recor) stat-s *iel) Aith c-rrent )ata
Stat-sLabel.#ext 6 ;'ecor)O ; S CStr('ecor)Pointer)
Stat-sLabel.#ext 6 Stat-sLabel.#ext S ; o* ; S CStr(Contacts.Co-nt)
Tcall the 'e*resh metho) to repaint the *orm contents
1Main.'e*resh
Tselect the contents o* the 1irst!ame *iel)
1irst!ame.Select
Tset the c-rsor *oc-s to the 1irst!ame *iel)
1irst!ame.Set1oc-s
LS Tno recor)s existV
T*or )eb-5 only
P'I!# ;In Up)ate1orm0 'ecor)O ; S 'ecor)Pointer S ; not *o-n).;
!DI1
T*or )eb-5 only
P'I!# ;Leavin5 Up)ate1orm...;
!D
0oding .oo(buttons3 2irst' *re)' 6e;t' and 1ast
>he /irst >oo&Button ,e ,i&& code is the one that ,i&& move us to the beginning o/ the
data# .oub&e4c&icon the /irst >oo&Button and 'ou shou&d be ta-en to the code ,indo, ,here
the 7irstRecordBtnLC&ic-( routine a,aits# Add this codeC
PUBLIC SUB 1irst'ecor)Btn8Click()
Tmove to the *irst recor)
'ecor)Pointer 6 =
Tretrieve that recor) *rom the collection
T-p)ate the *orm )isplay Aith the neA )ata
Up)ate1orm
!D
2#%
As 'ou can see, moving to the /irst record ,as prett' simp&e# :o,, ,e ,i&& code the
Prev and :e6t buttons# .oub&e4c&icon the second >oo&Button (E and 'ou ,i&& be ta-en to
the PrevRecordBtnLC&ic-( subroutine# Add this codeC
PUBLIC SUB Prev'ecor)Btn8Click()
T*or )eb-5 only
P'I!# ;in PrevO c-rrent pointer isO ; S 'ecor)Pointer
TAe are movin5 to a loAer recor) so Ae )ecrement the recor) pointer
DC 'ecor)Pointer
Ti* Ae move) past recor) = then reset to recor) =
I1 'ecor)Pointer 6 9 #:!
'ecor)Pointer 6 =
!DI1
T-p)ate o-r contact varaible Aith the neA (prev) recor) )ata
Ti* Ae are alrea)y at the be5innin5 o* the )ata noti*y the -ser
I1 'ecor)Pointer 6 = #:!
T*or )eb-5 only
P'I!# ;$t *irst contact alrea)yV;
LS
T*or )eb-5 only
P'I!# ;in Prev , noA c-rrent pointer isO ; S 'ecor)Pointer
!DI1
T-p)ate o-r *orm Aith the neA )ata
Up)ate1orm
!D
:o,, ,e ,i&& code the :e6t button# .oub&e4c&icon the third >oo&Button (F and 'ou
,i&& be ta-en to the :e6tRecordBtnLC&ic-( subroutine# Add this codeC
PUBLIC SUB !ext'ecor)Btn8Click()
T*or )eb-5 only
P'I!# ;in !extO c-rrent pointer isO ; S 'ecor)Pointer
TAe move *orAar) thro-5h the collection so Ae increment the pointer
I!C 'ecor)Pointer
2#+
Ti* Ae move) past the last recor)0 reset to the last recor)
I1 'ecor)Pointer K Contacts.Co-nt #:!
!DI1
T-p)ate the contact recor) Aith the neA )ata
Ti* Ae are alrea)y at the last recor)0 tell the -ser
I1 'ecor)Pointer 6 Contacts.Co-nt #:!
T*or )eb-5 only
P'I!# ;$t Last contact alrea)yV;
LS
T*or )eb-5 only
P'I!# ;in !ext0 the c-rrent pointer isO ; S 'ecor)Pointer
!DI1
T-p)ate o-r *orm a5ain Aith the neA )ata
Up)ate1orm
!D Tnext recor) move
>he &ast >oo&Button ,e need to code /or moving around in the data is /or the
LastRecordBtnLC&ic-( subroutine# >his subroutine ,i&& p&ace us at the end o/ the data
co&&ection, at the &ast record# .oub&e4c&icon the /ourth >oo&Button and add this codeC
PUBLIC SUB Last'ecor)Btn8Click()
Tset recor) pointer to last recor) -sin5 collection.co-nt property.
T-p)ate o-r recor) var Aith the neA )ata *or the last recor)
T-p)ate the *orm Aith the neA )ata
Up)ate1orm
!D
0oding .oo(Buttons3 Adding a record
:o,, &et's go through ho, to add a ne, contact to the co&&ection# .oub&e4c&icon the
/i/th >oo&Button, the &itt&e person icon, and 'ou ,i&& be put in the code ,indo, at the
AddBtnLC&ic-( subroutine# Let's go through the codeC
PUBLIC SUB $))Btn8Click()
T)eclare a local contact varaible 3-st *or -se in this s-bro-tine
280
Tinstantiate the contact recor) so Ae can -se it
Ti* there is no *irst name0 Ae Aill not a)) a recor)
I1 1irst!ame.#ext UK ;; #:!
T*or )eb-5 only
P'I!# ;$))in5 ; S 1irst!ame.#ext S ; to collection.;
TAe are here so Ae *o-n) a *irst name. $ssi5n the #extbox )ata
Tto the *iel)s store) in the recor)O
MyContact'ecor).1irst!ame 6 1irst!ame.#ext
MyContact'ecor).Last!ame 6 Last!ame.#ext
MyContact'ecor).Initial 6 MI.#ext
MyContact'ecor).S-**ix 6 S-**ix.#ext
MyContact'ecor).Street= 6 Street=.#ext
MyContact'ecor).StreetB 6 StreetB.#ext
MyContact'ecor).City 6 City.#ext
MyContact'ecor).State 6 State.#ext
MyContact'ecor).\ipC 6 \ipC.#ext
MyContact'ecor).\ip@ 6 \ip@.#ext
MyContact'ecor).$reaco)e 6 $reaCo)e.#ext
MyContact'ecor).Pre*ix 6 DialPre*ix.#ext
MyContact'ecor).Last@ 6 DialLast@.#ext
Tincrement the recor) key so each key is -niI-e Ahen a))e) to
Tthe collection. .ambas reI-ires that this be converte) to a
Tstrin5 variable Ahen Ae act-ally a)) it beloA.
MyContact'ecor).'ecor)ID 6 Contacts.Co-nt H =
Ti* Ae a))in5 a recor) it is not ta55e) as )elete)
MyContact'ecor).Delete) 6 1$LS
Tset 5lobal recor) pointer to the val-e o* the incremente) key
'ecor)Pointer 6 MyContact'ecor).'ecor)ID
TnoA0 call the Collection.$)) metho) to a)) the recor)
Contacts.$)) (MyContact'ecor)0 CStr('ecor)Pointer) )
Tthis is *or )eb-5 only to shoA Ahat has been a))e)
T*or )eb-5 only
281
P'I!# ;'ecor) ; S CStr('ecor)Pointer) S ; a))e)V;
LS
T*or )eb-5 only
P'I!# ;'ecor) )oes not existV;
!DI1
LS Tcannot a)) a contact Aitho-t a *irst name0 tell -ser
Messa5e.In*o(;Cannot a)) Aitho-t a *irst name;0 ;2k;)
!DI1
Up)ate1orm
Tthis is *or )eb-5 p-rposes0 shoA all recor)s in the collection
12' $C: MyContact'ecor) I! Contacts
P'I!# ;'ecor) ; S CStr('ecor)Pointer) S ;O ;G
!7#
!D Ta)) ro-tine
0oding .oo(Buttons3 0(earing data
>he si6th >oo&Button is used to c&ear the data on the /orm to a&&o, users to start ,ith a
/resh, b&an- /orm to enter data# +t simp&' b&an-s out each >e6tbo6 /ie&d# .oub&e4c&icon the
C&earBtn and enter this codeC
PUBLIC SUB ClearBtn8Click()
1irst!ame.#ext 6 ;;
MI.#ext 6 ;;
Last!ame.#ext 6 ;;
S-**ix.#ext 6 ;;
Street=.#ext 6 ;;
StreetB.#ext 6 ;;
City.#ext 6 ;;
State.#ext 6 ;;
\ipC.#ext 6 ;;
\ip@.#ext 6 ;;
$reaCo)e.#ext 6 ;;
DialPre*ix.#ext 6 ;;
DialLast@.#ext 6 ;;
!D
282
Valiating User Inp-t
<hen the user enters data in the +nitia& /ie&d, and a&so in the 2u//i6, 2tate, VipG, Vip(,
AreaCode, .ia&Pre/i6 and .ia&Last( /ie&ds, ,e ,ant to ensure that the data /its and the'
cannot enter e6traneous &etters or characters# Each o/ the routines be&o, are activated on a
change event# +n other,ords, i/ the te6t in the >e6tBo6#>e6t /ie&d changes, it ,i&& go to the
respective LChange( routine be&o,# Each routine ,or-s a&most identica&&' to &imit the
number o/ characters the user can t'pe# +/ the' t'pe more, the e6tra characters are truncated
at the &ength speci/ied b' the program# 7or e6amp&e, an area code can be no more than three
digits# <e cou&d a&so add code to ensure on&' digits are entered in numeric /ie&ds, etc#, but
that is not ,h' ,e are bui&ding this program# <+ ,i&& &eave that to 'ou to add as an e6ercise at
the end o/ this chapter# 7or each chec- be&o,, ,e ,i&& need a temporar' string var, s>emp# +/
the &ength o/ the >e6tBo6#>e6t data e6ceeds the &ength ,e a&&o,, ,e use 1+.U to cop' the /irst
n &etters to s>emp and then cop' that va&ue bac- into the >e6tBo6#>e6t propert'#
PUBLIC SUB MI8Chan5e()
DIM s#emp $S Strin5
I1 Len(MI.#ext) K = #:!
s#emp 6 Mi)[( MI.#ext0 =0 =)
MI.#ext 6 s#emp
!DI1
!D
PUBLIC SUB S-**ix8Chan5e()
DIM s#emp $S Strin5
I1 Len(S-**ix.#ext) K / #:!
s#emp 6 Mi)[( S-**ix.#ext0 =0 /)
S-**ix.#ext 6 s#emp
!DI1
!D
PUBLIC SUB State8Chan5e()
DIM s#emp $S Strin5
I1 Len(State.#ext) K B #:!
s#emp 6 Mi)[( MI.#ext0 =0 B)
State.#ext 6 s#emp
!DI1
!D
PUBLIC SUB \ipC8Chan5e()
283
DIM s#emp $S Strin5
I1 Len(\ipC.#ext) K C #:!
s#emp 6 Mi)[( MI.#ext0 =0 C)
\ipC.#ext 6 s#emp
!DI1
!D
PUBLIC SUB \ip@8Chan5e()
DIM s#emp $S Strin5
I1 Len(\ip@.#ext) K @ #:!
s#emp 6 Mi)[( MI.#ext0 =0 @)
\ip@.#ext 6 s#emp
!DI1
!D
PUBLIC SUB $reaCo)e8Chan5e()
DIM s#emp $S Strin5
I1 Len($reaCo)e.#ext) K / #:!
s#emp 6 Mi)[( $reaCo)e.#ext0 =0 /)
$reaCo)e.#ext 6 s#emp
!DI1
!D
PUBLIC SUB DialPre*ix8Chan5e()
DIM s#emp $S Strin5
I1 Len(DialPre*ix.#ext) K / #:!
s#emp 6 Mi)[( DialPre*ix.#ext0 =0 /)
DialPre*ix.#ext 6 s#emp
!DI1
!D
PUBLIC SUB DialLast@8Chan5e()
DIM s#emp $S Strin5
I1 Len(DialLast@.#ext) K @ #:!
s#emp 6 Mi)[( DialLast@.#ext0 =0 @)
DialLast@.#ext 6 s#emp
!DI1
!D
284
As 'ou can see, &ots o/ repetitive but necessar' code# Kou can go bac- &ater and
!bulletproof# the input o/ this program b' adding additiona& va&idation chec-s /or ever'
possib&e thing 'ou can thin- o/ but + ,i&& sho, 'ou &ater in this boo- a better ,a', bui&ding a
customi0ed +nputBo6 that ,i&& per/orm the va&idation process automatica&&'#
Aing a Search &eat-re
<e ,ant the user to be ab&e to /ind a contact b' searching /or a &ast name# >here are so
man' contro&s on our /orm no, that adding another one ,ou&d detract /rom the overa&&
aesthetics and ma-e it appear &ess than e&egant# A better so&ution is to use a mouse c&ic-
an',here on the /orm itse&/# +t generates an event and ,i&& a&&o, us to capture that event and
initiate a search process# <hen this happens, ,e are going to pop up a customi0ed search
/orm and prompt the user to enter the &ast name to search /or# =ere is the code /or the mouse
do,n eventC
PUBLIC SUB 1orm8Mo-seDoAn()
Search1orm.ShoAMo)al
Messa5e.In*o(;Back to main *orm AithO ; S SearchQey0 ;2k;)
Do1in)
!D
:ote that ,e sho, the /orm using the 2ho,1oda& method instead o/ 9ust ca&&ing 2ho,#
>his is because ,e ,ant the user to enter something and c&ic- the 2earch button# =ere is ,hat
the /orm itse&/ &oo-s &i-e in design modeC
Prett' basic, 9ust a &abe&, a >e6tbo6, and a button# 7rom the +.E create a ne, /orm,
named 2earch7orm and add the &abe& and button as sho,n be&o,# :ame the button
2earchBtn and the >e6tBo6 shou&d be named 2earch+nput# =ere is a&& the code that is needed
/or the 2earch7ormC
T .ambas Search1orm class *ile
PUBLIC SUB SearchBtn8Click()
28#
Figure /%: ,esigning the search (orm.
Tthis is a call to o-r c-stom mo)-le0 search0 Ahich has
Ta sin5le metho)0 Search2n0 that is explaine) beloA
Search.Search2n( SearchInp-t.#ext)
T*or )eb-5 only
P'I!# ;ret-rnin5O ; S SearchInp-t.#ext
Tassi5n the search key to the 5lobal var Ae name) in 1Main
1Main.SearchQey 6 SearchInp-t.#ext
TnoA close o-r search *orm
Search1orm.Close
!D
Tset the caption *or the search Ain)oA
Search1orm.Caption 6 ; 1in) by last name ;
Thi5hli5ht an) select the SearchInp-t #extbox
Tsince there is only one inp-t *iel)0 it has *oc-s alrea)y
SearchInp-t.Select
!D
At this point, 'ou might be ,ondering ,hat is going on# Basica&&', in Gambas, pub&ic
variab&es are pub&ic to a class file# <hen ,e ,ant to pass parameters between c&asses, ,e can
use the method o/ passing parameters ,ith /unctions &i-e ,e did ,hen ,e started the program
and passed an empt' co&&ection variab&e to the Get.ata method# Another ,a' to accomp&ish
this is b' using modu&es# >he -e' point to remember is that pub&ic variab&es in modu&es are
pub&ic to ll c&asses# Essentia&&', a&& ,e have done is create a conduit to pass our search -e'
/rom the search /orm bac- to the main program via the modu&e# :ote that the on&' code
needed in the modu&e is a statement that ta-es the parameter passed /rom the search /orm
and returns it to the main program# As soon as it comes bac- /rom the modu&e, it is assigned
to the 71ain c&ass pub&ic variab&e 2earchEe'# :ote that ,e /u&&' 5ua&i/ied the variab&e name,
speci/'ing 71ain#2earchEe' to ensure it reso&ves correct&'# >his is necessar' because the
2earchButtonLC&ic-( subroutine that invo-ed the modu&e is in a di//erent c&ass /i&e than the
71ain c&ass /i&e that ca&&ed it#
TPUBLIC SearchQey $S Strin5
PUBLIC 1U!C#I2! Search2n(sQey $S Strin5) $S Strin5
'#U'! sQey
!D
288
.he 8o2ind 7ubroutine
At this point, ,e have popped up the /orm, obtained the user input o/ a &ast name to
search /or, and have passed that variab&e bac- to our program using the modu&e conduit
method described above# :o,, ,e are read' to actua&&' search the co&&ection and /ind the
entr'# =ere is the code to do thatC
PUBLIC SUB Do1in)()
T)eclare a contact ob3ect *or local -se
Tinstantiate it
Tset the recor) pointer to the *irst recor) in the collection
'ecor)Pointer 6 =
T*or )eb-5 only
P'I!# ;In Do1in) AithO ; S SearchQey
T-se 12' $C: to iterate thro-5h each ob3ect in the collection
12' $C: MyContact'ecor) I! Contacts
Tassi5n each temp recor) to o-r 5lobal contact ob3ect
Ti* the last name matches search key0 -p)ate the *orm an) leave
I1 Contact'ecor).Last!ame 6 SearchQey #:!
T*or )eb-5 only
P'I!# ;1o-n)O ; S MyContact'ecor).Last!ame
TnoA -p)ate the *orm
Up)ate1orm
B'$Q T*orce ret-rn Aith this statement
!DI1
Tno match so Ae increment the recor) pointer an) move to the next
I!C 'ecor)Pointer
!7#
!D
Upating an E+isting #ecor
+/ the user happens to edit data on an e6isting record ,hen it is disp&a'ed, ,e ,ant the
28?
data to be saved to the same record# >o accomp&ish this using a co&&ection ob9ect is
comp&icated b' the /act that each ob9ect in the co&&ection must have a uni5ue -e'# >o get
around this, ,e ,i&& de&ete the ob9ect ,ith the current -e' using the bui&t4in method Remove,
and re4add the ob9ect using the same -e' but ,ith updated data# 2ort o/ snea-', but it gets the
9ob done ,ithout much e//ort# =ere is ho, it ,or-sC
PUBLIC SUB Up)ate8Click()
T)eclare a local contact ob3ect *or -s to Aork Aith
Tinstantiate it
TnoA remove the existin5 recor) in the collection
Contacts.'emove(CStr('ecor)Pointer))
Tthen Ae pop-late o-r Aork recor) Aith the *orm )ata
MyContact'ecor).1irst!ame 6 1irst!ame.#ext
Ta)) the Aork copy to the collection Aith the same
Tkey that belon5e) to the recor) Ae )elete) above
T*or )eb-5 only
P'I!# ;'ecor) ; S CStr('ecor)Pointer) S ; -p)ate)V;
LS
P'I!# ;'ecor) not -p)ate)V; TAe Aant this o-tp-t i* i* *aile)
!DI1
Up)ate1orm
!D
Deleting a Contact #ecor
28%
+/ the user ,ants to de&ete a record in a co&&ection ,e a&so have to thin- about ho, to
hand&e that# 1anaging ,hich -e's are avai&ab&e and ,hich are not cou&d be a programmer's
nightmare so an easier approach is to simp&' mar- the record as de&eted and b&an- it# >hat
,a', it is avai&ab&e /or reuse ,ith the same -e'# +t b&an-s out the data and, ,hen the save
occurs, does not store the o&d data, e//ective&' de&eting it# On&' di//erence is, ,e can reuse the
-e' b' having the user simp&' enter data in an empt' record and c&ic- the update button#
=ere is ho, this is accomp&ishedC
PUBLIC SUB Delete'ecor)Btn8Click()
T)eclare o-r local contact ob3ect
Tinstantiate it
Tremove the c-rrent recor) -sin5 the b-ilt,in 'emove metho)
Contacts.'emove(CStr('ecor)Pointer))
Tclear all the *iel)s on the *orm
ClearBtn8Click
Tset the *irst *iel) Aith an in)icator that the recor) is )elete)
MyContact'ecor).1irst!ame 6 ;UDelete) 'ecor)K;
Tleave the rest blank by simply assi5nin5 them a*ter clearin5
T mark recor) as )elete)
Mycontact'ecor).Delete) 6 #'U
Ta)) the blanke)0 )elete) recor) as it exists to the collection
T*or )eb-55in5 only
P'I!# ;'ecor) ; S CStr('ecor)Pointer) S ; marke) )elete)V;
LS
Ti* it *ails0 Ae Aant a messa5e
Messa5e.In*o(;'ecor) not marke) )elete)V;0;2k;)
!DI1
28+
T-p)ate the *orm
Up)ate1orm
!D
Sa/ing Data
>he &ast thing ,e need to code is the save button# >his is rea&&' simp&e because ,e have
a&read' bui&t a method in our Contact c&ass /i&e to do that# =ere, a&& ,e do is ca&& the Put.ata
methodC
PUBLIC SUB Save$llBtn8Click()
Tinvoke the P-tData metho)
Contact'ecor).P-tData(Contacts)
T*or )eb-5 only
P'I!# ;Contacts save) to contact.)ata *ile.;
!D
>hat is a&& ,e have &e/t to do# Run the program and enter some data# Be sure to tr' a&&
the options and create a /e, records# 2ave 'our data to /i&e and re&oad it# <hen 'ou are
satis/ied that it ,or-s as ,e p&anned, it is o- to go bac- and comment out a&& the conso&e
output (the PR+:> statements so the' ,i&& not disp&a' at runtime# 7or a&& the other programs
,e have created, ,e have been content to simp&' e6ecute them /rom ,ithin the +.E# 2ince
this program can be a use/u& addition to 'our des-top, ,e ,i&& no, sho, 'ou ho, to create a
stand4a&one e6ecutab&e and a&&o, it to run independent o/ the Gambas programming
environment#
Creating a ,tand3a*one Eecutab*e
+t is ver' eas' to create the e6ecutab&e# 2imp&' ma-e sure 'our program is read' /or
re&ease (test it /irstS and then go to the Pro9ect menu and choose 1a-e E6ecutab&e# >he
Gambas +.E ,i&& create an e6ecution script that ,i&& invo-e the Gambas interpreter and a&&o,
'ou to e6ecute 'our code# + created a des-top &in- to the program and used this /or the
app&ication path on m' s'stemC
TMrootMMy Doc-mentsM.ambas *or Be5innersMClassesMClassesT
O/ course, your system will be different8 Kou ,i&& need to point the des-top &in-
to the app&ication to ,here ever 'ou had the +.E save the e6ecutab&e /i&e# On the Linu6
distribution + origina&&' used /or this program (Linspire G#$, it ,ou&d not ,or- unti& +
enc&osed the /u&& path ,ith tic- mar-s, sho,n above# Because the Gambas interpreter is
invo-ed as a s'stem ca&&, the tic-s are needed to -eep the s'stem /rom thin-ing it is passing
parameters to 9root9My (,here the /irst space character occurs# =ere is the /ina& resu&t, our
program e6ecuting in stand4a&one mode on the des-topC
2?0
2?1
Figure /): Aur (inishe" program running on the >inu8 2int "es3top.
Chapter 12 Learning to +raw
.ra, is the c&ass used in Gambas /or dra,ing on an ob9ect# >he ob9ect ma' be o/ t'pe
Picture, <indo,, Printer, .ra,ing, or .ra,ingArea ob9ect# >his c&ass is static# +t is
important to remember that be/ore starting to dra, an'thing, 'ou must ca&& the %egin
method b' passing it a hand&e to the ob9ect t'pe 'ou ,ant to dra,# Once 'ou do that, 'ou can
ca&& an' o/ the dra,ing methods GB provides to dra, points, &ines, te6ts, pictures, etc#
=o,ever, it is not clearly documented that 'ou "ust lso set the .ra,ingArea's ,ached
propert' to >rue i/ 'ou ,ant to see 'our dra,ing appear on the /orm# <hen 'our dra,ing is
/inished, 'ou must ca&& the End method#
!raw Properties
Each item 'ou ,ish to dra, in Gambas is supported ,ith severa& common attributes,
such as bac-ground co&or and /oreground co&or, a /i&& co&or, /i&& st'&e, etc# 2ome properties in
Gambas, such as C&ip, are read4on&' and simp&' return data to 'ou /or use in 'our code#
(ac;gro-n an &oregro-n
As ,e e6p&ained in Chapter (, man' o/ the properties /or contro&s are common among
a&& contro&s, so ,e ,i&& ta-e the time to e6p&ain a&& o/ the button properties here, and &ater in
the boo- ,e ,i&& on&' e6p&ain the properties that are uni5ue to a given contro&#
Background is de/ined as P'2P'#W Back5ro-n) $S Inte5er
.oreground is de/ined as P'2P'#W 1ore5ro-n) $S Inte5er
>his integer va&ue represents the co&or used /or the current dra,ing bac-ground or
/oreground co&or# +t is s'non'mous ,ith the Bac-Co&orM7oreCo&or properties, ,hich ,i&& be
obso&ete in GambasD# :ote that P+OPE+&3 is a prede/ined data4t'pe used interna&&' in
Gambas# Kou can use the GB prede/ined constants /or co&or to set co&or va&ueC
Black Bl-e Cyan DarkBl-e
DarkCyan Dark.ray Dark.reen DarkMa5enta
Dark'e) DarkWelloA De*a-lt .ray
.reen Li5ht.ray Ma5enta 2ran5e
Pink 'e) #ransparent (iolet
+hite WelloA
>o set the Bac-ground propert' to red, 'ou ,ou&d use this codeC
DraA.Back5ro-n) 6 Color.'e)
A&ternative&', i/ 'ou -no, the RGB or =2! va&ues /or a speci/ic co&or, GB provides a
2?2
means to convert those va&ues to an integer va&ue that can be passed to the Bac-ground (or
other color2related propert'# >he c&ass Co&or provides t,o methods, RGB and =2! that 'ou
can use# =ere is ho, those /unctions are de/inedC
S#$#IC 1U!C#I2! '.B (' $S Inte5er0 . $S Inte5er0 B $S Inte5er "0 $lpha $S Inte5er % ) $S Inte5er
>he +F% /unction returns a co&or va&ue /rom its red, green and b&ue components# 7or
the =2! /unction, use thisC
S#$#IC 1U!C#I2! :S( ( :-e $S Inte5er0 Sat-ration $S Inte5er0 (al-e $S Inte5er ) $S Inte5er
6$' returns a co&or va&ue /rom its hue, saturation and va&ue components# >o use one o/
these /unctions to set the button's bac-ground co&or, here is ,hat 'ou cou&d codeC
DraA.Back5ro-n) 6 Color.'.B(BCC0BCC0BCC)
>his ,ou&d set the button's bac-ground co&or to ,hite# >his is most use/u& ,hen 'ou are
tr'ing to set co&ors ,hose va&ues /a&& outside the de/au&t constants va&ues provided in GB#
Clip
>his c&ass is static# C&ip is a read4on&' propert' that returns a virtua& ob9ect (.-rawClip
that is used /or managing the c&ipping area o/ a dra,ing# .-rawClip is a virtua& c&ass used /or
de/ining the c&ipping area o/ a dra,ing# >he Gambas dra,ing methods never dra, outside the
boundaries o/ the de/ined c&ipping area# Kou cannot use this virtua& c&ass as a data4t'pe# >he
standard ca&&ing convention isC

S#$#IC P'2P'#W '$D Clip $S .DraAClip
>his c&ass can be used as a /unction# >o invo-e the /unction to de/ine a c&ipping area, use this
ca&&ing conventionC
S#$#IC SUB .DraAClip (7 $S Inte5er0 W $S Inte5er0 + $S Inte5er0 : $S Inte5er )
Properties returned b' this /unction inc&ude Enab&ed, =, =eight, <, <idth, Q and K#
&illColor" &illSt1le" &ill)" &ill<
7i&&Co&or returns or sets the co&or used b' /i&&ing dra,ing methods# >his c&ass is static#
7i&&2t'&e returns or sets the st'&e used b' /i&&ing dra,ing methods# >he 7i&& c&ass supports
severa& 7i&&2t'&e prede/ined constants used to represent /i&& patterns /or dra,ingC
2?3
BackDia5onal Cross CrossDia5onal Dense=B
DenseBX DenseC9 DenseF Dense??
Dense>@ Dia5onal :oriRontal !one
Soli) (ertical
Ca&&ing convention /or 7i&&Co&or and 7i&&2t'&e is as /o&&o,sC
S#$#IC P'2P'#W 1illColor $S Inte5er
S#$#IC P'2P'#W 1illStyle $S Inte5er
7i&&Q and 7i&&K are used to return or set the hori0onta&Mvertica& origin o/ the brushes used b'
/i&&ing dra,ing methods# Ca&&ing convention /or 7i&&Q and 7i&&K isC
S#$#IC P'2P'#W 1ill7 $S Inte5er
S#$#IC P'2P'#W 1illW $S Inte5er
&ont
7ont returns or sets the /ont used /or rendering te6t on the dra,ing sur/ace# Ca&&ing
convention isC
S#$#IC P'2P'#W 1ont $S 1ont
>o set contro& /ont attributes, this code can be usedC
DraA.1ont.!ame 6 ;L-ci)a;
DraA.1ont.Bol) 6 #'U
DraA.1ont.Italic 6 1$LS
DraA.1ont.SiRe 6 ;=9;
DraA.1ont.Strike2-t 6 1$LS
DraA.1ont.Un)erline 6 1$LS
In/ert
+nvert is used to stipu&ate that a&& dra,ing primitives ,i&& combine their pi6e& co&ors
,ith the pi6e& co&ors o/ the destination using an QOR operation# Ca&&ing convention isC
S#$#IC P'2P'#W Invert $S Boolean
LineSt1le'LineWith
Line2t'&e returns or sets the st'&e used /or dra,ing &ines# Line<idth returns or sets the
,idth used /or dra,ing &ines# >he Line c&ass is static and de/ines the constants used b' the
.ra,#Line2t'&e propert'# >hese constants inc&udeC
2?4
Dash Dot DashDot
DashDotDot !one Soli)
S#$#IC P'2P'#W LineStyle $S Inte5er
S#$#IC P'2P'#W Line+i)th $S Inte5er
Transparent
>ransparent indicates that some dra,ing methods &i-e .ra,#>e6t are transparent, i#e#,
it means the' do not /i&& their bac-ground# Ca&&ing convention isC
S#$#IC P'2P'#W #ransparent $S Boolean
!raw 2ethods
One o/ the best ,a's to &earn ho, to use Gambas dra,ing methods is to ,rite code that
demonstrates the use o/ each method# +n this manner, 'ou can see ho, to program the
method and get immediate grati/ication b' seeing the resu&ts# <e are going to bui&d a demo
app&ication that ,i&& sho, 'ou ho, to use near&' a&& o/ the methods that are supported b' the
.ra, c&ass# <e ,i&& start b' creating a ne, H> graphica& user inter/ace app&ication# :ame the
pro9ect g/6.emo and ,hen the +.E appears, create a /orm, 71ain# 1a-e sure 'ou speci/' it
as a startup c&ass and ensure the contro&s are pub&ic# =ere is ,hat the 5@ain &a'out ,i&& &oo-
&i-e at runtimeC
2et the /orm ,idth to GD$ and the height to ()$# >he de/au&t settings /or a&& other
properties shou&d be /ine /or our purposes# Create eight buttons and &abe& them as sho,n in
2?#
Figure /*: g(8,emo FMain la$out.
the picture above# >he button names are >e6tBtn, +nvRectBtn, E&&ipseBtn, 7i&&RectBtn,
Po&'gonBtn, Po&'LineBtn, >i&eBtn, and HuitBtn# Each button shou&d have a ,idth o/ I$ and a
height o/ ;G# P&ace them as &o, on the /orm as 'ou can ,ithout cutting o// the bottom o/ the
button# 7or each button 'ou have created, ,e ,i&& need to create a c&ic- event b' doub&e4
c&ic-ing on the button#
As ,e go through the e6p&anations o/ each o/ the /o&&o,ing methods, ,e ,i&& be adding
code ,here appropriate# Be/ore ,e get to the methods themse&ves, there are a coup&e o/
things ,e need to do ,ith our program# 7irst, ,e need to add a dra,ing area contro&, named
da to the /orm# >he .ra,ing Area too& can be /ound on the Container tab o/ the Gambas
>oo&bo6# P&ace it at the top &e/t corner o/ 71ain and ma-e it about " inch b' " inch# <e ,i&&
d'namica&&' resi0e it in our program# :e6t, ,e ,i&& use a constructor to start the dra,ing
process, invo-ing the #rw1%egin method and setting the parameters that ,i&& be used /or
our program# =ere is the constructor subroutine 'ou need to addC
PUBLIC SUB 8neA()
Testablish Ai)th o* the )raAin5 area 5 .+ is synonymo-s Aith .+i)th
)a.+ 6 -2ain.+ , =9
Testablish hei5ht o* the )raAin5 area 5 .: is synonymo-s Aith .:ei5ht
)a.: 6 -2ain.: , @C
Tmake the man)atory call to start )raA operations
DraA.Be5in()a)
Tset a )e*a-lt line Ai)th o* B pixels
DraA.Line+i)th 6 B
T*or the .Clear metho) to Aork0 the property DraAin5$rea.Cache) m-st be set to #'U.
)a.Cache) 6 #'U
!D
<hen the /orm opens at program start, it ,i&& /irst ca&& the constructor above, then
e6ecute the code in the 7ormLOpen subroutine# A&& ,e are going to do /or this subroutine is
set the caption at the top o/ the /ormC
1Main.#ext 6 ; DraAin5 xamples ;
!D
>he /ina& routine ,e ,i&& create be/ore e6p&oring the .ra, methods is the code needed to stop
our program# .oub&e4c&icon the Huit button and add this codeC
DraA.n) Tclose )raAin5 operations
M.Close Tclose -2ain
!D
2?8
:o,, ,e are read' to begin adding code to e6p&ore our various dra,ing too&s, the methods o/
the .ra, c&ass#
Te+t'Te+tHeight'Te+tWith
<e ,i&& begin ,ith .ra,#>e6t and the t,o read4on&' te6t properties, >e6t=eight and
>e6t<idth# >e6t=eight returns the height o/ a te6t dra,ing ,hi&e >e6t<idth returns the ,idth
o/ a te6t dra,ing# 2tandard ca&&ing convention isC
1U!C#I2! #ext:ei5ht ( #ext $S Strin5 ) $S Inte5er
1U!C#I2! #ext+i)th ( #ext $S Strin5 ) $S Inte5er
.oub&e4c&icon the >e6t button and add this codeC
PUBLIC SUB #extB-tton8Click()
Tthis var Aill be -se) *or o-r loop co-nter

Tclear the c-rrent )raAin5 area
)a.Clear
Tset *ore5ro-n) color to black
DraA.1ore5ro-n) 6 color.Black
Tset c-rrent *ont to $rial
)raA.1ont.!ame 6 ;$rial;
Tt-rn on bol)*ace
)raA.1ont.Bol) 6 #'U
Tt-rn o** italic
)raA.1ont.Italic 6 1$LS
Tt-rn o** -n)erline
)raA.1ont.Un)erline 6 1$LS
Tset text siRe to =F points
)raA.1ont.SiRe 6 ;=F;

Tstart a loop an) contin-e -ntil Ae iterate =9 times
12' co-nter 6 9 #2 >
To-tp-t text an) increment the y position by @9 L co-nter
2??
Tthe optional Ai)th0 hei5ht parameters are 5iven as =990 F9
)raA.#ext(;Sample #ext;0 =90 =9 H @9Lco-nter0 =990F9)
!7# Titeration o* the loop
TnoA set *ont to B@ points
)raA.1ont.SiRe 6 ;B@;
DraA.1ore5ro-n) 6 color.Bl-e Tan) chan5e color to bl-e
12' co-nter 6 9 #2 > Tloop another =9 times
Tall Ae chan5e is x position to move the text ri5ht B99 pixels
)raA.#ext(;More Sample #ext;0 B990 =9 H @9Lco-nter0 =990F9)
!7# Titeration
!D T Ae are )one Aith text st-**V
Once 'ou have added the code above, save 'our ,or- and c&ic- the R@: button# >he pro9ect
,i&& compi&e and, ,hen comp&eted, here is ,hat 'ou shou&d seeC
Dra4 %rimiti/es= %oint'#ect'Ellipse'Line
>he .ra,#Point method dra,s a sing&e pi6e& ,hi&e .ra,#Rect dra,s a rectang&e#
Ca&&ing convention /or these t,o methods isC
S#$#IC SUB Point (7 $S Inte5er0 W $S Inte5er )
2?%
Figure //: Besults o( clic3ing the Te8t
=utton.
S#$#IC SUB 'ect (7 $S Inte5er0W $S Inte5er0+i)th $S Inte5er0:ei5ht $S Inte5er )
<e are going to use the +nvRect button to i&&ustrate ho, these methods are used# .oub&e4c&ic-
on the +nvRect button and enter the /o&&o,ing codeC
PUBLIC SUB Inv'ectBtn8Click()
T-se this var *or o-r loop co-nter
Tclear the )raAin5 area
)a.Clear
Tmake s-re *ill style is set to !one
)raA.1illStyle 6 *ill.!one
Tset color to cyan
)raA.1ore5ro-n) 6 color.cyan
Tthis Aill make the cyan rectan5le appear re)
)raA.Invert 6 #'U
12' co-nter 6 9 #2 =C Tloop =F times
T)raA a rect0 inc the startx0y an) en) x0y positions CL co-nter val
DraA.'ect(CHCLco-nter0 CHCLco-nter0 )a.+MBHCLco-nter0 )a.:MB H CLco-nter)
Ti* Ae hit an even n-mber0 invoke to55le Invert property onMo**
I1 co-nter M2D B 6 9 #:!
)raA.Invert 6 1$LS
LS
)raA.Invert 6 #'U
!DI1
Tens-re invert is set to o**
)raA.Invert 6 1$LS
Tset c-rrent *5) color to black
)raA.1orecolor 6 color.Black
Tset a point mi)screen
)raA.Point()a.+MB0 )a.:MB)
TnoA Ae Aill make a tiny crosshair *rom the *irst point by movin5 one pixel -p0 )oAn0 le*t an) ri5ht o* the center
T)ot Ae set Aith the *irst )raA.point call
)raA.Point()a.+MB,=0 )a.:MB)
)raA.Point()a.+MBH=0 )a.:MB)
)raA.Point()a.+MB0 )a.:MB,=)
)raA.Point()a.+MB0 )a.:MBH=)
!D To* the rectMpoint )emo co)e
2ave 'our ,or- and run the program# <hen 'ou c&ic- the +nvRect button, 'ou shou&d
see something simi&ar to thisC
2?+
>he .ra,#Line method dra,s a &ine# >he 6", '" points represent the start verte6 o/ the
&ine, 6;, '; represent the end verte6 o/ the &ine# >he &ine method uses properties /rom the
Line c&ass to estab&ish &ine st'&e and thic-ness# >he constants used b' the .ra,#Line2t'&e
propert' are -ash, -ash-ot, -ash-ot-ot, -ot, (one, and Solid# Line thic-ness is set using
the .ra,#Line<idth propert' and ,idth is set in pi6e&s# >he ca&&ing convention /or this
method isC
S#$#IC SUB Line(7= $S Inte5er0W= $S Inte5er07B $S Inte5er0WB $S Inte5er)
.ra,#Circ&e ,i&& dra, a circ&e# >he ca&&ing convention /or .ra,#Circ&e isC
S#$#IC SUB Circle ( 7 $S Inte5er0 W $S Inte5er0 'a)i-s $S Inte5er " 0 Start $S 1loat0 n) $S 1loat %)
Q and K represent the center point o/ the circ&e# +/ 'ou speci/' the optiona& parameters
o/ start and &ength, these represent starting ang&es (in radians ,here the dra,ing ,i&& start
and stop#
.ra,#E&&ipse ,i&& dra, an e&&ipse or circ&e# Remember, a circ&e is an e&&ipse ,ith e5ua&
,idth and height parameters# >he ca&&ing convention /or .ra,#E&&ipse isC
S#$#IC SUB llipse (7 $S Inte5er0 W $S Inte5er0 +i)th $S Inte5er0 :ei5ht $S Inte5er "0 Start $S 1loat0 Len5th $S 1loat% )
Q and K represent the center point o/ the circ&e or e&&ipse# <idth can be thought o/ as
the diameter a&ong the hori0onta& p&ane, height is the diameter a&ong the vertica& p&ane# <e
,i&& i&&ustrate this in our e6amp&e be&o, using the E&&ipses button# .oub&e4c&icon the
E&&ipses button and enter this codeC
2%0
Figure /0: Besults o( +n'Bect button clic3. 7ote the
tin$ blac3 crosshair center screen.
PUBLIC SUB llipseBtn8Click()
T)eclare some variables to Aork Aith
DIM x= $S Inte5er
DIM xB $S Inte5er
TAe Aill nee) a co-nter variable
DIM i $S Inte5er
Tan) a var to hol) the val-e o* line Ai)th as Ae chan5e it
DIM lAi)th $S Inte5er
DIM i'a)i-s $S Inte5er
DIM i+i)th $S Inte5er
DIM i:ei5ht $S Inte5er

T+e Aill nee) to convert the )e5ree val-es o* i an) i H /9 to 'a)ians
DIM s$n5le= $S 1loat
DIM s$n5leB $S 1loat

Tclear o-r )isplay be*ore Ae be5in
)a.Clear
Tset initial vectors
i'a)i-s 6 C9
i+i)th 6 =99
i:ei5ht 6 =99

Tchan5e the color to )ark bl-e
DraA.1ore5ro-n) 6 color.DarkBl-e
Tset -p *or a soli) *ill. $ny *illable container that is calle) a*ter
Tthis call Aill be *ille) Aith the pattern speci*ie) beloA
)raA.1illStyle 6 *ill.Soli)

Tset -p a loop that Aill create =B increments
12' i 6 9 #2 /F9 S#P /9
Ti* Ae *all on a >9 )e5ree increment0 sAitch colors
I1 i M2D @C 6 9 #:!
)raA.1illColor 6 color.WelloA
LS
)raA.1illColor 6 color.'e)
!DI1
2%1
s$n5le= 6 'a)(i)
s$n5leB 6 'a)(i H /9)
T)raA a *ille) circle o* =B se5ments0 startin5 at each val-e o* I an) sAeepin5 *or /9 )e5rees0 as speci*ie) in the optional
params
DraA.Circle(F90 F90 i'a)i-s0 s$n5le=0 s$n5leB)
TLocate the center at pixels x 6 F90 y 6 F9.
T#he next line0 -ses the .llipse metho) to make a circle0 Aith
Tthe Ai)th an) hei5ht bein5 eI-al. Beca-se the Ai)th an) hei5ht
To* =99 pixels has the same e**ect as a ra)i-s o* C90 .llipse
Tpro)-ces the same res-lt as the .Circle metho).
DraA.llipse(>90 >90 i+i)th0 i:ei5ht0 s$n5le=0 s$n5leB)
TLocate the center at pixels x 6 >90 y 6 >9.
!7#
TnoA0 t-rn o** the *ill style
Tset o-r *5) color to black
)raA.1ore5ro-n) 6 color.Black
Tstart Aith a line Ai)th o* a sin5le pixel
lAi)th 6 =
Tloop ? times0 movin5 )oAn alon5 the y axis in BC pix increments
12' i 6 =9 #2 B99 S#P BC
T)raA a line
)raA.Line()a.+MB0 i0 )a.+MB H =C90 i)
Tincrease line thickness variable
I!C lAi)th
Tset the neA Ai)th
)raA.Line+i)th 6 lAi)th
To-t o* the loop0 reset to a )e*a-lt o* B pix Ai)e
)raA.Line+i)th 6 B
T*or the ellipses beloA0 set x at mi)screen horiR axis , BC pixels
x= 6 )a.+MB,BC
2%2
Tset o-r y at mi)screen on the vertical axis
y= 6 )a.:MB

TnoA0 lets start another loop an) )raA some ellipses
12' i 6 = #2 @9 S#P / Tlets make =/ o* them
Tmovin5 this one le*t alon5 the horiR axis
DraA.llipse(x=,iLC0 y=0 XC0 B99)
Tan) movin5 this one ri5ht alon5 the horiR axis
DraA.llipse(x=HiLC0 y=0 XC0 B99)
Ti* Ae hit an even n-mber in o-r loop chan5e colors
I1 i M2D B 6 9 #:!
)raA.1ore5ro-n) 6 color.'e)
LS
)raA.1ore5ro-n) 6 color.Black
!DI1
!D Ten) o* the ellipses an) lines )emo co)e
2ave 'our ,or- and run the program# <hen 'ou c&ic- the E&&ipses button, 'ou shou&d
2%3
Figure 01: 5sing the -llipses button to
"emonstrate "ra.ing lines an" ellipses.
Our ne6t code segment ,i&& use the 7i&&Rect button# <e are re4visiting the .ra,#Rect
method to sho, 'ou ho, to use the .ra,#7i&&2t'&e to create /i&&ed ob9ects# Create a c&ic-4event
and enter the /o&&o,ing codeC
PUBLIC SUB 1ill'ectBtn8Click()
Tcreate some local vars to Aork Aith
DIM x= $S Inte5er
DIM xB $S Inte5er
DIM y= $S Inte5er
DIM yB $S Inte5er
)a.Clear
Tset the rect top le*t corner
x= 6 B9
y= 6 ?9
Tset the rect bot ri5ht corner
xB 6 x=HC9
yB 6 y=HC9
Tset *5) color to re)
)raA.1illColor 6 color.'e)
Tspeci*y a horiR style *ill pattern
)raA.1illStyle 6 *ill.:oriRontal
T)raA a rect0 i* a *ill pattern is speci*ie)0 it is a-to*ille)
DraA.'ect(x=0y=0xB0 yB)
Tset the rect top le*t corner
x= 6 BB9
y= 6 =?9
Tset the rect bot ri5ht corner
xB 6 x=HC9
yB 6 y=HC9
Tset *5) color to bl-e
)raA.1illColor 6 color.Bl-e
Tspeci*y a cross style *ill pattern
)raA.1illStyle 6 *ill.Cross
2%4
T)raA a rect0 i* a *ill pattern is speci*ie)0 it is a-to*ille)
DraA.'ect(x=0y=0xB0 yB)
Tt-rn o** the *ill
!D
2ave 'our ,or- and run the program# <hen 'ou c&ic- the 7i&&Rect button, 'ou shou&d see
something simi&ar to thisC
NoteL In or"er to graphicall$ "ispla$ "ata in a program9 $ou;'e seen ho. $ou coul" create a circle
an" (ill it in or"er to generate pie charts. +( $ou .ante" to "ispla$ a rectangle .ith gri"&lines (or a
line chart9 bar chart9 etc.9 $ou coul" "ra. a rectangle an" use a FAB...7-JT loop to "ra. the
in"i'i"ual lines o( the gri" insi"e the rectangle9 using FT-P to control the spaces bet.een lines
accor"ing to $our nee"s.
Dra4 %rimiti/es= %ol1gon an %ol1line
>he .ra,#Po&'gon method dra,s a po&'gon ,ith n vertices# >he vertices are speci/ied
in an +nteger arra' using this ca&&ing conventionC
S#$#IC SUB Poly5on ( Points $S Inte5er"% )
>he Points parameter is an arra' o/ +nteger containing the coordinates o/ the po&'gon
2%#
Figure 01: Autput a(ter clic3ing the FillBect button.
verte6es# >he coordinates are assumed to be in 6,' /ormat so there must be t,o integers in
the arra' /or each verte6 o/ the po&'gon#
>he .ra,#Po&'&ine ,or-s near&' the same as the Po&'gon routine e6cept that ,ith a
po&'&ine the /igure being dra,n does not need to be c&osed# >his is sometimes re/erred to as a
void po&'gon# A po&'&ine is a series o/ vertices 9oined /rom one to the ne6t b' a &ine# >he &ine
,i&& dra, /rom the &ast verte6 to the ne6t verte6 speci/ied in the arra'# >he ca&&ing convention
/or Po&'&ine isC
S#$#IC SUB Polyline ( Points $S Inte5er"% )
>he Points parameter is an arra' o/ +nteger containing the coordinates o/ the po&'gon
verte6es# 2o there must be t,o integers in the arra' /or each verte6# <e ,i&& use the 7i&&Po&'
button on our 5@ain to demonstrate the use o/ the .ra,#Po&'gon method# .oub&e4c&icon
the 7i&&Po&' button to create a c&ic- event and ,hen the code ,indo, appears, enter this codeC
PUBLIC SUB Poly5onBtn8Click()
T)eclare some Aork variables to create a poly5on
DIM x= $S Inte5er
DIM y= $S Inte5er
DIM xB $S Inte5er
DIM yB $S Inte5er
DIM x/ $S Inte5er
DIM y/ $S Inte5er
TAe are 5oin5 to create a trian5le *or o-r poly5on
Tan) store the vertices in the inte5er array trian5le
DIM trian5le $S Inte5er"%

Tclear the )isplay area
)a.Clear

Tset the vertices *or each le5 o* the trian5le
Tstartin5 Aith the top part o* an eI-ilateral trian5le
x= 6 )a.AMB T set the horiR axis to mi),screen
y= 6 =9 Tset vertical axis to top H =9 pixels

TnoA0 Ae Aill )o the le*t le5 o* the trian5le
Tstartin5 on the extreme le*t e)5e pl-s =9 pixels
xB 6 )a.Le*t H =9
Tan) settin5 o-r y position to )raAin5area hei5ht , B99 pixels
yB 6 )a.: , B99
Tthe ri5ht le5 sets horiR position *ar ri5ht , B9 pixels in
x/ 6 )a.+ , B9
2%8
Tan) the vert axis Aill be same as the secon) le5
y/ 6 yB

Tall vertices )e*ine)0 loa) the inte5er arrays Aith the trian5le
trian5le.$))(x=0 9)
trian5le.$))(y=0 =)
trian5le.$))(xB0 B)
trian5le.$))(yB0 /)
trian5le.$))(x/0 @)
trian5le.$))(y/0 C)
Tset a *ill style
)raA.1illStyle 6 *ill.DenseF/
Tan) a *ill color
)raA.1illColor 6 color.DarkMa5enta
Tan) )raA the poly5on -sin5 the trian5le array )ata
)raA.Poly5on(trian5le)
Tremember to set *ill style to !one
Tcall re*resh to see o-r Aork
)a.'e*resh
!D T an) Ae are )one Aith the poly5on ro-tine
2ave 'our ,or- and run the program# <hen 'ou c&ic- the 7i&&Po&' button, 'ou shou&d
2%?
Figure 02: 5sing ,ra..Pol$gon to "ra. a
triangle.
:o,, &et's see ho, the .ra,#Po&'&ine method ,or-s# .oub&e4c&icon the Po&'&ine
button and create a c&ic- event# <hen the code ,indo, appears, enter this codeC
PUBLIC SUB PolyLineBtn8Click()
T)eclare some variables to create o-r vertices
DIM x= $S Inte5er
DIM y= $S Inte5er
DIM xB $S Inte5er
DIM yB $S Inte5er
DIM x/ $S Inte5er
DIM y/ $S Inte5er
DIM x@ $S Inte5er
DIM y@ $S Inte5er
T)eclare an inte5er array to hol) the polyline )ata
DIM lines $S !+ Inte5er"%
Tclear the )raAin5area
)a.Clear
Tstart o-r *irst point mi)screen abo-t =9 pixels *rom the top
x= 6 )a.AMB
y= 6 =9
Tthe next point Aill be =9 pixels in *rom *ar le*t0 )oAn B99 pixels
xB 6 )a.Le*t H =9
yB 6 )a.: Z B99
To-r /r) vertex Aill be )ea),center o* the )raAin5 area on horiR axis
Tan) very bottom o* the )raAin5 area *or vert axis
x/ 6 )a.+ , B9
y/ 6 )a.: , B9
Tan) the @th vertex Aill be )ea),center x an) y o* the )raAin5 area
x@ 6 )a.+MB
y@ 6 )a.:MB
Tloa) the vertices into the arrayG i* Ae Aante) to close the poly5on0 all Ae nee) to )o is a)) the
Tx=0y= vertices to the en) o* the array. 4-st -ncomment the last tAo array assi5nments to try it an) see
lines.$))(x=0 9)
lines.$))(y=0 =)
lines.$))(xB0 B)
lines.$))(yB0 /)
lines.$))(x/0 @)
lines.$))(y/0 C)
lines.$))(x@0 F)
lines.$))(y@0 X)
Tlines.$))(x=0 ?)
Tlines.$))(y=0 >)
Tens-re any *ill styles are t-rne) o**
2%%
Tset the color to )ark 5reen
)raA.1ore5ro-n) 6 color.Dark.reen
T)raA the lines
)raA.Polyline(lines)
!D To* the polyline )emo ro-tine
2ave 'our ,or- and run the program# <hen 'ou c&ic- the Po&'&ine button, 'ou shou&d
Image'%ict-re'Tile
>he +mage c&ass dra,s an +mage, or part o/ it# >he image contents are stored in the
process memor', not in the disp&a' server &i-e a Picture# >his c&ass is creatab&e# +/ <idth and
=eight are not speci/ied, then the ne, image is void# Ca&&ing convention isC
S#$#IC SUB Ima5e ( Ima5e $S Ima5e0 7 $S Inte5er0 W $S Inte5er " 0 Src7 $S Inte5er0 SrcW $S Inte5er0 Src+i)th $S Inte5er0 Src:ei5ht $S Inte5er % )
>he /o&&o,ing code ,ou&d create a ne, imageC
DIM hIma5e $S Ima5e
hIma5e 6 !+ Ima5e ( " +i)th $S Inte5er0 :ei5ht $S Inte5er % )
>his c&ass acts &i-e an arra' o/ pi6e&s# >hin- o/ Q as ro,s and K as co&umns o/ image pi6e&s#
=ere is ho, the code to get or set a pi6e& o/ an image ,ou&d ,or-C

DIM hIma5e $S Ima5e
DIM anInte5er $S Inte5er
2%+
Figure 03: 5sing ,ra..Pol$line to "ra.
lines.
anInte5er 6 hIma5e " 7 $S Inte5er0 W $S Inte5er %
>he code above ,i&& return the co&or o/ an image pi6e& at Q, K ,hi&e the /o&&o,ing code ,i&& set
the co&or o/ an image pi6e& to the va&ue o/ an+ntegerC
hIma5e " 7 $S Inte5er0 W $S Inte5er % 6 anInte5er
+mage a&&o,s 'ou to use the /o&&o,ing propertiesC .epth, =eight, Picture, and <idth#
#epth returns or sets the depth o/ the image# <hen setting depth va&ues, 'ou must on&' use
the /o&&o,ing va&uesC ;, *, "I, and ;(# +t is dec&ared asC
P'2P'#W Depth $S Inte5er
6eight is a read4on&' attribute that returns the height o/ the image as an integer# +t is
dec&ared asC
P'2P'#W '$D :ei5ht $S Inte5er
-idth is a read4on&' attribute that returns the ,idth in pi6e&s o/ the image# +t is dec&ared asC
P'2P'#W '$D +i)th $S Inte5er
Picture (read4on&' converts the image into a picture, and returns it# +t is dec&ared asC
P'2P'#W '$D Pict-re $S Pict-re
>he +mage c&ass supports severa& methods# >hese inc&udeC C&ear, Cop', 7i&&, 7&ip, Load,
1irror, Rep&ace, Resi0e, Rotate, 2ave, and 2tretch#
Cler ,i&& c&ear the image, setting a&& pi6e& va&ues to 0ero#
Copy returns a cop' o/ the image, or a cop' o/ a part o/ it# >he cop' method is dec&ared as a
/unction, as sho,n be&o,C
1U!C#I2! Copy ( " 7 $S Inte5er0 W $S Inte5er0 +i)th $S Inte5er0 :ei5ht $S Inte5er % ) $S Ima5e
!ill /i&&s the image ,ith a speci/ied co&or# Ca&&ing convention isC
SUB 1ill ( Color $S Inte5er )
!lip returns a mirrored cop' o/ the image# >he mirrored cop' is created using the hori0onta&
a6is o/ the image#
1U!C#I2! 1lip ( ) $S Ima5e
2+0
)od nd $ve &oad or saves an image /rom a /i&e or to a /i&e respective&'# >he /i&e e6tension
o/ 3ath ,i&& speci/' the graphics /i&e /ormat used ,ith the saved image# Current&' supported
/i&e /ormats are %PEG, P:G, B1P, G+7 and QP1# Ca&&ing convention isC
SUB Loa) ( Path $S Strin5 )
SUB Save ( Path $S Strin5 )
Mirror returns a mirrored cop' o/ the image# >he mirrored cop' is created using the vertica&
a6is o/ the image#
1U!C#I2! Mirror ( ) $S Ima5e
+eplce s,aps an e6isting /ldColor va&ue ,ith the co&or speci/ied b' (ewColor, as sho,n
be&o,C
SUB 'eplace ( 2l)Color $S Inte5er0 !eAColor $S Inte5er )
+esi<e Resi0es the image to the si0e speci/ied b' the ,idth and height parameter givenC
SUB 'esiRe ( +i)th $S Inte5er0 :ei5ht $S Inte5er )
+otte returns a rotated cop' o/ the image# Ca&&ing convention is as /o&&o,sC
1U!C#I2! 'otate ( $n5le $S 1loat ) $S Ima5e
>he /unction ,i&& rotate the image n radians# >he ang&e is speci/ied in radians, so i/ 'ou ,ant
to use degrees /or the va&ue o/ Ang&e, state the argument as (Rad(Ang&e A2 7&oat#
$tretch returns a stretched cop' o/ the image# +/ the optiona& parameter 2mooth is speci/ied
as >rue, a smoothing a&gorithm is app&ied to the returned resu&t# >he ca&&ing convention isC
1U!C#I2! Stretch ( +i)th $S Inte5er0 :ei5ht $S Inte5er " 0 Smooth $S Boolean % ) $S Ima5e
>he Picture c&ass dra,s a picture, or part o/ a picture# >he picture contents are stored
in the disp&a' server, not in the process memor' &i-e an +mage# Each picture can have a
transparenc' mas-# >his /eature can be set e6p&icit&' at picture instantiation, or imp&icit&'
,hen &oading an image /i&e that has transparenc' &i-e P:G# <hen dra,ing on a picture
having a mas-, the picture and the mas& are modi/ied according&'# Ca&&ing convention isC
S#$#IC SUB Pict-re ( Pict-re $S Pict-re0 7 $S Inte5er0 W $S Inte5er " 0 Src7 $S Inte5er0 SrcW $S Inte5er0 Src+i)th $S Inte5er0 Src:ei5ht $S Inte5er % )
>his c&ass is creatab&e# >he /o&&o,ing code sho,s 'ou ho, to create a PictureC
2+1
hPict-re 6 !+ Pict-re ( " +i)th $S Inte5er0 :ei5ht $S Inte5er0 #ransparent $S Boolean % )
+/ the optiona& <idth and =eight parameters are not speci/ied, the ne, picture is void# Kou
can speci/' i/ the picture has a mas- ,ith the >ransparent parameter# >his c&ass acts &i-e an
arra'#
hPict-re 6 Pict-re " Path $S Strin5 %
>he code above ,i&& return a picture ob9ect /rom the interna& picture cache# +/ the
picture is not present in the cache, it is automatica&&' &oaded /rom the speci/ied /i&e# +n order
to insert a picture in the interna& picture cache, use this codeC
Pict-re " Path $S Strin5 % 6 hPict-re
#epth returns or sets the depth o/ the picture# <hen setting depth va&ues, 'ou must on&' use
the /o&&o,ing va&uesC ;, *, "I, and ;(# +t is dec&ared asC
P'2P'#W Depth $S Inte5er
6eight is a read4on&' attribute that returns the height o/ the picture as an integer# +t is
dec&ared asC
P'2P'#W '$D :ei5ht $S Inte5er
-idth is a read4on&' attribute that returns the ,idth in pi6e&s o/ the picture# +t is dec&ared asC
P'2P'#W '$D +i)th $S Inte5er
*"ge is a read4on&' propert' that converts the picture into an image and returns it# +t is
dec&ared asC
P'2P'#W '$D Ima5e $S Ima5e
<e ,i&& use an e6amp&e /rom the Gambas <i-i to sho, 'ou ho, this ,or-s# <e ,i&&
sho, 'ou ho, to ta-e a screenshot ,ith code and save the image# >he image o/ the des-top is
ta-en as a picture ob9ect ,hen the button on the /orm is c&ic-ed# >his picture ob9ect is
subse5uent&' converted into an image ob9ect and disp&a'ed as an image in a dra,ingarea#
2tart Gambas and create a ne, H> graphica& user inter/ace pro9ect, named g/6.emo;#
+n AOptionsB, c&icon A+nternationa&i0ationB#<hen the +.E appears, create a startup c&ass
2+2
/orm named 5@ain# 7rom the properties ,indo, /or 5@ain, set the AutoResi0e propert' to
>rue so 'ou can stretch the /orm to see the image ,hen it is added# Add a button named
Button" and a .ra,ingArea named .ra,ingArea"# P&ace the .ra,ingArea at the top &e/t
corner o/ the /orm and ma-e it about one inch ,ide and one inch high# :o,, put the button at
the bottom right corner o/ the /orm# Add the caption ASnapshot# to the button# .oub&e4c&ic-
on the button to create a c&ic- event and add this codeC
T .ambas class *ile
T)eclare a var *or o-r pict-re
p $S !+ Pict-re
Tan) one *or o-r ima5e
i $S !+ Ima5e
T:i)e the c-rrent control so it is not seen in the screenshot
M.(isible 6 1$LS TM ret-rns a re*erence to the c-rrent ob3ect.
T .ive the c-rrent *orm a chance to hi)e
+$I# 9.C
T.et the pict-re ob3ect *rom the )esktop -sin5 ..rab metho).
p 6 Desktop..rab()
T'estore visibility o* the control.
M.(isible 6 #'U
Tassi5n the pict-re -sin5 the ima5e property to
Tconvert screenshot to an ima5e
i 6 p.ima5e

Tspeci*y that the contents o* the )raAin5 area are cache) in memory
DraAin5area=.Cache) 6 #'U

TresiRe )raAin5 area to siRe o* the ima5e converte) *rom pict-re
DraAin5$rea=.'esiRe(i.+i)th0i.:ei5ht)
DraAin5$rea=.Clear()

Tcall the DraA.Be5in (man)atory) metho) to start to )raA
DraA.Be5in(DraAin5$rea=)
Tp-t the ima5e in the )raAin5 area startin5 at ori5in 909
DraA.Ima5e(i0 90 9)
2+3
Tcall the (man)atory) DraA.n) metho) to I-it )raAin5
DraA.n)
Tmake the ima5e visible
DraAin5$rea=.(isible 6 #'U
Tre*resh the )raAin5 area to see Ahat Aas )one
DraAin5$rea=.'e*resh
T!2#O Usin5 the Pict-re.Save metho)0 yo- co-l) Arite co)e to save the
Tscreenshot to )isk.
!D
2ave 'our ,or- and run the program# C&ic- the button and a screenshot o/ 'our des-top ,i&&
be p&aced on the dra,ing area o/ the /orm# Prett' eas' using the Gambas methods, isn't itN
NoteL +n Gambas 29 the ,es3top class has the static metho" .Grab9 (rom the :t3 librar$. The
screenshot area can be change" b$ "ragging the bor"ers9 but the origin o( the screenshot .ill al.a$s
be pi8el 191 I the upper le(t&han" corner o( the screen. Gambas 3 uses the up"ate" :t# librar$9
an" .Grab has been replace" .ith the metho" .Fcreenshot. The calling con'ention (or .Fcreenshot is:
S#$#IC 1U!C#I2! Screenshot ( " 7 $S Inte5er0 W $S Inte5er0 +i)th $S Inte5er0 :ei5ht $S Inte5er % ) $S Pict-re
>i3e .Grab9 .Fcreenshot returns a screenshot o( the "es3top as a Picture object. +( the J9 K9 Wi"th9
?eight arguments are speci(ie"9 the$ "e(ine the part o( the screen that .ill be returne". +( the$ are
not "e(ine"9 the area o( the "es3top co'ere" b$ the program .in"o. is returne" (again9 starting at
191). +n Gambas 39 the line p L ,es3top.Grab() can be replace" .ith something much more
sophisticate": p L ,es3top.Fcreenshot(89 $9 .i"th9 height). With this s$nta89 $ou can .rite co"e to
interacti'el$ let the user "e(ine the Grab area in pi8els9 so $ou no longer are limite" to the origin o(
the screenshot at pi8el 191.
&rnsprent is a Boo&ean /&ag that can be read or set# +t indicates ,hether or not the picture
has a mas-# Ca&&ing convention isC
P'2P'#W #ransparent $S Boolean
1ethods supported b' Picture inc&ude C&ear, Cop', 7i&&, 7&ush, Load, Resi0e, and 2ave#
Cler ,i&& c&ear the picture, setting a&& pi6e& va&ues to 0ero#
Copy returns a cop' o/ the picture, or a cop' o/ a part o/ it# >he cop' method is dec&ared as a
/unction, as sho,n be&o,C
2+4
1U!C#I2! Copy ( " 7 $S Inte5er0 W $S Inte5er0 +i)th $S Inte5er0 :ei5ht $S Inte5er % ) $S Ima5e
!ill /i&&s the picture ,ith a speci/ied co&or# Ca&&ing convention isC
SUB 1ill ( Color $S Inte5er )
!lush 7&ushes the interna& picture cache# >he method ta-es no parameters and is ca&&ed
using this conventionC
S#$#IC SUB 1l-sh ( )
)od nd $ve &oads or saves a picture /rom a /i&e or to a /i&e respective&'# >he /i&e e6tension
o/ 3ath ,i&& speci/' the graphics /i&e /ormat used ,ith the saved picture# Current&' supported
/i&e /ormats are %PEG, P:G, B1P, G+7 and QP1# Ca&&ing convention isC
SUB Loa) ( Path $S Strin5 )
SUB Save ( Path $S Strin5 )
+esi<e resi0es the image to the si0e speci/ied b' the ,idth and height parameter givenC
SUB 'esiRe ( +i)th $S Inte5er0 :ei5ht $S Inte5er )
>he >i&e method dra,s a ti&ed picture in the .ra,ingArea# Ca&&ing convention is as
/o&&o,sC
S#$#IC SUB #ile ( Pict-re $S Pict-re0 7 $S Inte5er0 W $S Inte5er0 +i)th $S Inte5er0 :ei5ht $S Inte5er )
Let's no, go bac- to our origina& g/6.emo program and /inish coding the &ast button# 2tart
Gambas and &oad the g/6.emo pro9ect# Open 5@ain and doub&e4c&icon the >i&e+mg button#
<hen the code ,indo, appears, add this codeC
PUBLIC SUB #ileBtn8Click()
T)eclare o-r local vars here
TAe Aill nee) a pict-re var to hol) the pict-re Ae loa)
DIM mypic $S Pict-re
TAe nee) a co-nter var *or o-r loop Aork
TAe are also 5oin5 to nee) some inte5er vars
DIM i $S Inte5er
DIM 3 $S Inte5er
Tset i an) 3 to Rero to start
2+#
i 6 9
3 6 9
Tinstantiate pict-re variable
mypic 6 !+ Pict-re
)a.Clear
TnoA loa) the pict-re -sin5 the loa) metho)
mypic 6 mypic.Loa)(;5ambas/.pn5;)
TAe Aill tile the pict-re i col-mns across per 3 roAs )oAn
Tin o-r case Ae Aill have @ roAs o* / ima5es per roA
Tso Ae Aill nee) to loop =B times
12' co-nter 6 9 #2 ==
T)raA the tile
)raA.#ile(mypic0 (iL=XC)HB90 30 =X90=9C) D$))in5 B9 to the x val-e
T3-st improves le*t,to,ri5ht centerin5 *or this speci*ic ima5e.
Tincrement o-r col-mn co-nter
I!C i
Tcheck to see i* Ae have three across
I1 i M2D / 6 9 #:!
Ti* so0 move val-e o* 3 (o-r y axis) ima5e.hei5ht H C pixels )oAn
3 6 3 H ==9
Treset col-mn co-nter to Rero
i 6 9
!DI1 To-r check to see i* / across
!D To* the #ileIm5 b-tton co)e
2+8
>he &ast thing ,e need to do is get an image to use /or our program# 7or our progarm, +
have chosen the Gambas mascot, ,hich ,e used /rom an ear&ier pro9ect# Kou can cop' this
image /rom our 7irstPro9ect# 7rom the pro9ect ,indo,, on the >ree!ie, .ata /o&der, se&ect
:e, +mage#
<hen the ,indo, appears, 'ou can se&ect the E6isting tab and bro,se to the /o&der
7irstPro9ect (assuming 'ou named 'our pro9ects as ,e speci/ied in the boo- and choose the
AgambasD#pngB image, or ,hatever the /i&ename is that Gambas is current&' using#
2ave it to the g/6.emo pro9ect as !5ambas shrimp.png# and that is a&& there is to it# +/, /or
some reason, 'ou cannot /ind the image on 'our s'stem, simp&' go to the Gambas ,eb site and
use the right mouse button over the mascot image to save a cop' to our g/6.emo pro9ect
/o&der#
Chec- the ,idth and height o/ 'our image in the /i&e properties, so that 'ou can use that
in/ormation in the dra,#>i&e arguments# :o,, save 'our ,or- and run the program# C&ic- the
>i&e+mg button and 'ou shou&d see something simi&ar to thisC
Dra4ing 4ith a Dra4ing ob6ect
+n Gambas, a dra,ing ob9ect is based on the use o/ 2ca&ab&e !ector Graphics, or 2!G#
2+?
Figure 0#: 5sing tile" images as a bac3groun" on a (orm.
According to the 2!G speci/ication
"G
, !S<5 is a language for describing two2dimensional
graphics in DB7. S<5 allows for three types of graphic objects* vector graphic shapes (e.g.,
paths consisting of straight lines and curves), images and tet. 5raphical objects can be
grouped, styled, transformed and composited into previously rendered objects. The feature
set includes nested transformations, clipping paths, alpha mas&s, filter effects and template
objects. S<5 drawings can be interactive and dynamic. )nimations can be defined and
triggered either declaratively (i.e., by embedding S<5 animation elements in S<5 content)
or via scripting.#
+n-scape
"I
is a popu&ar program used in the Linu6 communit' /or creating 2!G images
and is ,hat this author has chosen to use ,ith this boo- since it is /ree&' avai&ab&e on the
+nternet# +n-scape is an open source vector graphics editor, ,ith capabi&ities simi&ar to
+&&ustrator, 7reehand, Core&.ra,, or Qara Q using the <DC standard 2ca&ab&e !ector Graphics
(2!G /i&e /ormat#
NO&EL As o( this .riting9 Gambas2 "oes not properl$ han"le F4G "ra.ings9 "espite some ('er$
limite") "ocumentation that $ou ma$ (in" on the Web. ?o.e'er9 the authors ha'e e'aluate" some
basic graphics (unctions in the Gambas3 Alpha 'ersion an" Gambas3 "oes seem to han"le F4G
correctl$9 as .ell as intro"ucing a number o( sophisticate" graphics (unctions not pre'iousl$
a'ailable. +n Gambas39 using the F'g+mage class9 $ou can loa"9 paint9 sa'e9 or clear an F4G image.
The properties that $ou ha'e a'ailable to $ou are the most basic9 namel$ .i"th an" height.
On the .!. that accompanies this boo-, 'ou ,i&& /ind a pro9ect named
AChapterL";L2!GLinLGambasDB# Kou can on&' open it in GambasD & i/ 'ou ,ant to &oo- at
the code in a te6t editor, 'ou must set that /o&der's !ie, to A2ho, =idden 7i&esB, go into the
A#srcB /o&der, and open the te6t /i&e A71ain#c&assB# >his program not on&' e6p&ores ho, to
hand&e 2!G, but a&so demonstrates ho, to hand&e interna& Gambas dra,ings and bitmap
graphics in GambasD# >here are a coup&e o/ di//erences /rom the methods in Gambas;,
a&though that ma' change in /uture GambasD re&eases# 2evera& graphics are inc&uded,
inc&uding one 2!G image o/ a sucrose mo&ecu&e that is a /ree&' avai&ab&e pub&ic domain
&icensed image, do,n&oaded /rom the +nternet atC
httpCMMopenc&ipart#org#
Because GambasD ma' e6perience a /e, more changes, ,e ,i&& on&' &oo- at the part o/ the
inc&uded program that is the subroutine dea&ing ,ith 2!G graphics#
P-blic S-b DraAS(.8Click() TPaint an S(. 5raphic to establish the correct syntax.
Dim )a)r $s DraAin5$rea
Dim )ra $s Sv5Ima5e
)a)r 6 !eA DraAin5$rea(1Main)
)ra 6 !eA Sv5Ima5e
1# /ee ,6' httpG99www.w3.org9T69/(G9intro.html >or more details on /(G.
18 /ee ,6' httpG99www.inkscape.org9 >or more details on Inkscape.
2+%
)a)r.Cache) 6 #r-e T#he Cache) property m-st be set to #r-e. I*
Tthis is not )one0 the pict-re Aill not )isplay.
)a)r.Bor)er 6 = T#he Bor)er property m-st be set to =0 B0 /0 or
T@. I* Bor)er is set to 9 (no bor)er)0 the pict-re Aill not )isplay.
)a)r.Painte) 6 #r-e T#he Painte) property m-st be set to #r-e. I*
Tthis is not )one0 the pict-re Aill not )isplay.
TnoA loa) it -sin5 the Loa) metho)
)ra 6 )ra.Loa)(;s-crose.sv5;)
)a)r.Move(B9C0 X0 )ra.+i)th0 )ra.:ei5ht)
Paint.Be5in()a)r) TS(. 5raphics are )raAn Aith Paint0 not DraA.
)ra.Paint
Paint.n) T$s Aith DraA0 Paint reI-ires a Be5in an) an n) metho).
n)
+e"e"/er4 this only works in F"/sP1
>his /igure is sho,n as imp&emented in the pro9ect AChapterL";L2!GLinLGambasDB
on the inc&uded .!.# >he picture o/ a sucrose mo&ecu&e is an 2!G graphic# <e hope 'ou
have en9o'ed our short &itt&e !tour de force# o/ Gambas dra,ing capabi&ities# >his chapter has
attempted to present 'ou ,ith most o/ the basics needed to use Gambas /or a&most an'
graphica& app&ication needs# +n the ne6t chapter, ,e ,i&& ta&- about error hand&ing ,ith
Gambas#
2++
Figure 0%: >oa"ing an" "ispla$ing graphics in Gambas3.
Chapter 13 7rror )anagement
Error management is a -e' area /or deve&opers doing an' -ind o/ app&ication
deve&opment# Error management is a ver' po,er/u& concept and can ma-e deve&opment ,or-
much easier i/ it is used e//icient&'# As a Gambas deve&oper, it is high&' recommended that 'ou
adopt an appropriate strateg' /or error management that ,i&& enab&e 'ou to bui&d high 5ua&it'
and robust app&ications# +mproper hand&ing o/ errors can and ,i&& degrade the per/ormance
o/ 'our app&ication, it's perception b' 'our user communit', and u&timate&', its overa&&
acceptance# +n order to understand error management, it is important to -no, the t'pes o/
errors that can occur in a program# <e ,i&& brie/&' e6p&ain the most common error categories
in the /o&&o,ing sections and tr' to point out some things 'ou shou&d ,atch /or as 'ou ,rite
'our code#
General Concepts o0 Error .anagement
Errors can have man' causes# .epending on the cause, the error might be recoverab&e#
A recoverab&e error is one /or ,hich 'our app&ication can identi/' the error cause and ta-e
some action to reso&ve or mitigate the prob&em# 2ome errors might be recoverab&e can be
hand&ed ,ithout the need to indicate to the user that an error ,as even encountered# 7or
e6amp&e, an error generated ,hen a re5uested /i&e does not e6ist is recoverab&e# >he
app&ication can be programmed to disp&a' an error message in such an event# Errors such as
va&idation errors, /or ,hich the app&ication cannot continue processing but can provide error4
speci/ic /eedbac- can a&so be considered recoverab&e i/ hand&ed proper&'# 7or e6amp&e, an
error that occurs ,hen a user enters te6t ,here a number is re5uired can be considered
recoverab&e because the app&ication can recogni0e the error and redisp&a' the data /ie&d a&ong
,ith a message that provides in/ormation about the cause o/ the error, a&&o,ing the user to
reenter data using correct input#
Error Hanling
>here are three -e' /actors to consider ,hen programming to avoid errorsC prevention,
detection, and recover'# >a-ing ade5uate steps to prevent errors ,i&& certain&' he&p to ensure
'ou have a happ' user communit'# =o,ever, ho, do 'ou prevent errors i/ the' cannot be
detected b' the program be/ore the user ,i&& su//er the conse5uencesN =ave 'ou and 'our
team ta-en the time to investigate and account /or ever' possib&e -e'stro-e, input, and data
t'pe that a user cou&d enterN Rea&&' thin- about this ,hi&e 'ou are sti&& in the design phase
and again during the initia& deve&opment o/ the test p&ans because it can come bac- to haunt
'ou /or man', man' bui&d and retest iterations# 7ina&&', i/ the error does occur, ,hat can be
done to get the program bac- to the state o/ usabi&it' it ,as in before the error occurredN
1ost errors are the resu&t o/ inade5uate design, poor programming practices, and poor
testing# Poor programming practices inc&ude coding on&' the method o/ achieving the desired
resu&ts ,ithout accounting /or user error, mista-es in input, va&idation errors, etc# A&&
programmers -no, ho, to deve&op data va&idation chec-s and usua&&' tr' to put them o// unti&
300
the' get the code ,or-ing# 1a-ing data va&idation a re5uirement bumps the priorit' o/ doing
this ,or- up a notch on the &ist o/ things the programmer has to do# Poor testing is
epitomi0ed b' test teams /ai&ing to account /or these t'pes o/ /actors in the design and
construction o/ the product test p&ans and test cases#
(o-nar13#elate Errors
<hen a program e6ecutes, the program cursor moves /rom one part o/ the program to
the ne6t e6ecuting the coded instructions se5uentia&&'# >he transition /rom one area to the
ne6t in the program is de/ined b' the e6it o/ one boundar' condition and the entr' to the ne6t#
>his transitiona& state, or boundar', can inc&ude numeric, te6t, and operator boundaries# +/
the user is as-ed to enter a number /rom $ to )) in a program, ,hat happens i/ the user enters
the &etter aBb or t'pes in ";D insteadN <hat i/ the user enters the number *( and the s'stem
te&&s 'ou the number is too &arge, prompting the user to tr' entering a number /rom $ 4 ))
once againN .oes the program /ai& to va&idate input and attempt to process bad inputN =ave
a&& possib&e boundar' conditions been accounted /or in design and testN Rea&&'N
Calc-lation Errors
>here are an in/inite number o/ conditions that can cause ca&cu&ation errors# >he
programmer &ogic ma' have been in error or his or her /ormu&a /or the ca&cu&ation ma' be
coded incorrect&'# Rounding or truncation errors can signi/icant&' a&ter desired resu&ts# A
good design process shou&d incorporate pseudo4code /or an' and a&& ca&cu&ated resu&ts to sho,
ho, these /ormu&as are intended to be imp&emented or used in production# Code revie,s
,ou&d chec- to see that the' are indeed imp&emented as designed# >est cases ,ou&d e6ecute
a&& boundar' conditions against the code and veri/' the imp&ementation is as roc-4so&id as it
can be be/ore turning it over to production /or genera& use#
Initial an Later States
<hen a program e6ecutes subroutines and uses variab&es, these variab&es o/ten must be
initia&i0ed ,ith de/au&t va&ues# +n Gambas, such de/au&ts genera&&' ta-e the /orm o/ a 0ero
va&ue or a :@LL va&ue# +/ initia&i0ation is not done speci/ica&&' b' a deve&oper, it is an'onebs
guess as to ,hat the va&ue o/ that variab&e ,i&& be ,hen /irst ca&&ed un&ess the variab&e is one o/
the data4t'pes that Gambas initia&i0es automatica&&'# Remember, these types of errors re
result of progr""ers not doing the jo/ correctly# As an e6amp&e, &et us assume
that in the previous e6amp&e above no variab&e initia&i0ation is ,hat has happened ,hen a
routine ca&&s /or a variab&e to increment# >he program processed G$ records, incrementing the
va&ue o/ the variab&e each time the routine is e6ecuted# <hen the va&ue is output at the end o/
processing, it shou&d be e5ua& to G$# =o,ever, the un4initia&i0ed variab&e had a va&ue o/ ";;
(or some other random number and the output sho,n to the user ,as "J;# >his describes
,hat constitutes an initia& state error#
>o demonstrate &ater state errors, consider the same situation as above, but instead o/
passing the e6pected va&ue o/ G$ to another modu&e to use /or processing, the va&ue o/ "J; is
301
passed a&ong# >hese errors are a bit harder to detect because the output /rom the ca&&ed
modu&e is ,here the user thin-s the error occurred# Programmers assigned to debug this
prob&em have to trace through the e6ecution path and /o&&o, the changing state o/ the variab&e
unti& it is discovered to be a prob&em in the ca&&ing modu&e, not the ca&&ed one# >he resu&t o/
this is a great dea& o/ time and e//ort ,ent into discovering a prob&em that ,as avoidab&e# +/
the user reported this /rom a production s'stem, pro9ect team credibi&it' again ta-es a hit# As
a program manager, 'ou must ensure these t'pes o/ situations are prevented b' /aci&itating
ade5uate, in4depth discussion in the design phase#
Control &lo4 Errors
Previous&', ,e stated that ,hen a program e6ecutes, the program cursor moves /rom
one part o/ the program to the ne6t, e6ecuting the coded instructions se5uentia&&'# 2ome
e6ecution instructions /orce the program to 9ump /rom one routine to another# >his
movement in e6ecution is re/erred to as program or contro& /&o,# <hen a program does
something ,rong in contro& /&o,, it is genera&&' a prob&em ,ith the program &ogic or a
programmer error in coding the design# 2uch &ogic errors are o/ten uncovered during code
revie,s in the imp&ementation phase# 2ometimes, in testing the' are discovered b' bui&ding
test cases to va&idate program /&o, based on the design speci/ications bui&t in the design phase
and the test p&ans bui&t in the imp&ementation phase# An' o/ these t'pes o/ errors discovered
b' a user ,hen a s'stem is in production re/&ects a /ai&ure o/ the test team to ade5uate&' test
the product# As a pro9ect &eader, 'ou are u&timate&' responsib&e /or preventing this situation
/rom occurring# >RK to ,or- ,ith the design team and test case deve&opers as ear&' in the
process as possib&e to set proper e6pectations /or the t'pe o/ testing and the &eve& o/
thoroughness 'ou e6pect#
Errors in Hanling or Interpreting Data
>here are man' ,a's data can become choc- /u&& o/ errors in a deve&opment process#
=o,ever, a&most a&& o/ these m'riad ,a's data can go a,r' are attributed to human error#
>hese t'pes o/ errors can be a resu&t o/ misca&cu&ation, errors in &ogic, parameter passing
errors, use o/ incorrect data t'pes, etc# A&most an'thing that a programmer can do to ma-e a
mista-e can cause an error in data# >he best means o/ preventing such errors is a continua&
chec- o/ &ogic, revie, o/ e6pected and actua& va&ues, revie, o/ input and output data, etc# >his
is an ongoing process and it invo&ves both user and deve&oper#
7rom the user perspective, the data shou&d be benchmar-ed against current means o/
producing the data# >he user shou&d continua&&' revie, the resu&ts o/ output to ensure
something has not run a/ou& and caused data to become bad# 7rom the deve&oper perspective,
basic coding discip&ine shou&d be en/orced\ range and boundar' conditions need to be
chec-ed, parametric va&ues need va&idation, data t'pe va&idation must occur, and use o/ test
data must be va&idated to be o/ the right /ormat, current and in s'nc ,ith production data, and
usab&e /or production output# +t is a&,a's good /or team &eads to rein/orce these concepts ,ith
deve&opers and ensure periodic code revie,s ta-e p&ace# +t is essentia& to team success#
302
#ace an Loa Conitions
A race condition is best de/ined as one event preceding another# >he tric- is ma-ing
sure the /irst condition shou&d be /irst or the &ast condition is supposed to be &ast# 7e,
programmers thin- about or even chec- /or race conditions# >hese conditions are sometimes
identi/ied on&' a/ter great manpo,er has been e6pended in doing traces into e6ecutab&e code,
step b' step, to see ,hat is happening# <hen 'ou hear the ,ords irreproducib&e as testers are
ta&-ing about this t'pe o/ bug, interpret it to mean a possib&e race condition and as- someone
i/ the' have chec-ed /or it#
Load conditions are common and are the resu&t o/ putting more ,or- on the computer
than it can bear to hand&e# A simp&e point o/ i&&ustration is having a computer process mi&&ions
o/ records# +t is the per/ect 9ob /or a computer but, ,hen the time to process each record is
more than a /e, mi&&iseconds, the mi&&ion records to be processed can ta-e a great dea& o/
time# 7or e6amp&e, &ets assume an idea& situation ,here 'our app&ication does some comp&e6
va&idation, necessar' to proper&' process a record, and that it ta-es "$ mi&&iseconds to process
each o/ these records in a per/ect&' managed test environment# >his trans&ates to a processing
rate o/ "$$ records a second# :ot bad, but ,hen 'ou divide "$$ into ",$$$,$$$ records, 'ou
5uic-&' /ind out that this 9ob ,i&& ta-e "$,$$$ seconds or ;#J hours to run to comp&etion#
Again, acceptab&e in most cases, e6cept that 'ou must remember the machine is comp&ete&'
tied up ,ith processing# :o reports can be produced, no 5ueries can be run, etc# +n toda'bs
modern computing environment, this is not acceptab&e#
Lets ta-e another vie, ,here rea&4,or&d conditions are app&ied# +n a test environment,
,here the "$ mi&&iseconds are idea& computing conditions, ,e ,i&& compound the prob&em
,ith user interaction and s'stem overhead# Lets &oo- at record retrieva& times and /actor that
into the e5uation# Kour "$ mi&&iseconds are no, "(#G mi&&iseconds per record# @ser 5ueries
and other user interactions interaction cou&d easi&' add another "$ or so mi&&iseconds per
activit' and no, ,e are at ;G mi&&iseconds o/ processing time /or 9ust a sing&e record# <e are
no, &oo-ing at I#JG hours to run the same 9ob that ran in ;#J hours in the test &ab# >he point
here is that testing shou&d account /or such &oad conditions be/ore re&ease into production# +/
a user -no,s be/ore -ic-ing o// a production 9ob that it ,i&& ta-e J hours to run, the' can go o//
and do other things or run the 9ob at night# =o,ever, i/ the EQPEC>A>+O: is a ;#G hour 9ob,
the' ,i&& a&,a's be dissatis/ied ,ith per/ormance because it is not ,hat the' e6pected#
%lat0orm an Har4are Iss-es
=ard,are issues are among the most /rustrating a user can encounter# An e6amp&e
,ou&d be having a user se&ect to print a report and ,atch it scro&& b' on the screen, at a mi&&ion
,ords a second# >he printer device ,as not speci/ied correct&' or not speci/ied at a&&# >he user
assumed a printer ,ou&d print the report but device errors or &ac- o/ device hand&ing caused
the situation above# >here are man' t'pes o/ devices ,hich a programmer must account /or
and the testing process needs to account /or user interaction on a&& o/ them# Aside /rom the
condition cited above, programs can send the ,rong codes to the right device, overrun the
device ,ith data, etc# Programmers and testers are responsib&e /or ensuring these conditions
303
are accounted /or and tested be/ore 'our user communit' are e6posed to them# A&& these t'pes
o/ errors can do is give 'ou a bad mar- in credibi&it' as 'our users rate 'our per/ormance#
So-rce" Version" an ID Control Errors
>hese t'pes o/ errors are genera&&' due to poor con/iguration management and an
interna& &ac- o/ en/orcement o/ e6isting con/iguration management po&icies and procedures#
An e6amp&e o/ this is having a ne, programmer insert a beta version o/ code into a production
stab&e re&ease /or a norma& bug /i6 and then not te&&ing an'one a change has been made in that
modu&e# :orma& testing o/ the maintenance re&ease ,i&& &i-e&' not catch the prob&em and it
ma' go unnoticed /or severa& subse5uent re&eases#
As another e6amp&e, this situation cou&d be something as insidious as a data error that
on&' sho,s up on&' ,hen 5uarter&' /inancia&s are produced# <hen there is no reason to be
/ound as to ,h' the compan' ba&ance sheet is o// b' severa& hundred thousand do&&ars, much
e//ort is e6pended in having senior deve&opers per/orm code traces to /ind a prob&em#
2omeone ,i&& eventua&&' discover that there is some beta code in a production modu&e that has
errant&' rounded ever'thing to the nearest do&&ar or some other simi&ar stupid mista-e# Good
intentions aside, the best cure /or these t'pes o/ prob&ems is good programmer discip&ine /or
con/iguration management and to have strong po&ic' en/orcement ingrained into an
organi0ations corporate cu&ture#
Testing Errors
Even testers ma-e mista-es# >he' can interpret the &ogic o/ a test case improper&', the'
can misinterpret test resu&ts, /ai& to report g&itches, etc# >esters ma' /orget to e6ecute test
cases or report bugs that rea&&' donbt e6ist# >hese /o&-s are human too# >hat means their
resu&ts are a&so sub9ect to 5uestioning# <hen 'our teams have ,or-ed hard to deve&op
something and the test resu&ts come bac- s-e,ed bad&' one ,a' or another, 5uestion the test
process#
Test %lan #e/ie4s
7or a&& but the most simp&e t'pes o/ pro9ects, a /orma& revie, process is genera&&'
re5uired# >his a&so re5uires participation /rom the users, the deve&opers, the s'stems
ana&'sts, data ana&'sts, and testers# +t is best /or a&& concerned i/ the /orma& test revie,
inc&ude the most e6perienced users and deve&opers present in an organi0ation# 2ome users
ma' not have the proper e6perience ,ith a s'stem to proper&' identi/' prob&ems be/ore the'
occur and this added e6perience can on&' bene/it a revie, process# Ensure participation in a
/orma& test p&an revie, is based &ess on the avai&abi&it' o/ user and deve&oper personne& and
more on the contributions the best 5ua&i/ied deve&opers and users can bring to the tab&e# :o,
that ,e have a good understanding o/ the ho, and ,h' o/ errors, &ets ta&- about ho, ,e can
manage such errors in Gambas#
304
Gambas Error management
Gambas provides bui&t4in mechanisms to assist the programmer in error management#
2uch mechanisms are too&s at a programmer's disposa& that are o/ten over&oo-ed and, in man'
instances, not used at a&&# Gambas ,as designed ,ith the concepts o/ simp&icit' and avoidance
o/ errant &ogic in mind# Gambas programs 'ou ,rite shou&d tr' to adhere to these concepts b'
using a&& o/ the means avai&ab&e to prevent errors# >his means ta-ing the time to ,rite
va&idation routines, ,or-ing 'our code to trac- /&o, and provide output &ogs, etc# +t is rea&&'
not that much more ,or- and ,i&& ma-e a huge di//erence in the &ong run# Gambas can on&'
provide an environment in ,hich to deve&op, but, in the end, it is 'ou, the coder, that is
responsib&e /or 'our product# Let's ta-e some time no, to &earn ho, to use the Gambas
/eatures /or error management#
T#< statement777 I& E##O#
>he >RK command provides a programmer ,ith the means to per/orm an error chec-
an',here he or she suspects an error ma' occur# +t is, in e//ect, a ,a' to test the ,ater be/ore
9umping in# Kou can tr' to e6ecute the statement and, i/ an error occurs, it ,i&& be recorded b'
the Error c&ass# >his is done b' setting propert' va&ues that 'ou can chec-# >hese propert'
va&ues inc&udeC
Error#C&ass
Error#Code
Error#>e6t
Error#<here
>he Error#C&ass propert' ,i&& return to 'ou the name o/ the c&ass ,here the error
occurred and the Error#Code propert' ,i&& te&& 'ou ,hat the speci/ic error code ,as# >he te6t
associated ,ith the Error#Code is stored in the Error#>e6t propert' and the Error#<here
propert' ,i&& te&& 'ou the o//ending &ine o/ source code (i/ possib&e# >he error c&ass a&so
provides t,o methods, Error#C&ear and Error#Raise that 'ou can use to he&p trac- do,n
prob&ems# <e ,i&& discuss the use o/ these t,o methods a &itt&e bit &ater in this chapter# >he
>RK statement is used to test /or speci/ic errors ,hereas the CA>C= statement (described
be&o, is more o/ a genera& purpose error catching mechanism# >he genera& &ogic used /or
>RK is sho,n in the pseudo4code be&o,C
#'W aStatement
i* ''2' #:!
Messa5e.rror(error.text)
en)i*
Ten) o* try
Let's create a 5uic- e6amp&e to demonstrate ho, to use tr'# Open the Gambas +.E and create
a ne, graphica& user inter/ace pro9ect# Create a startup c&ass /orm (71ain and put an E6it
30#
button on the /orm, named E6itBtn# .oub&e4c&icon the button and add this codeC
PUBLIC SUB xitBtn8Click()
DIM a $S Inte5er
DIM b $S Inte5er

a 6 B
b 6 9

#'W P'I!# aMb
I1 ''2' #:!
Messa5e.rror(;CL$SSO ; S Str(rror.class) S ;0 C2DO ; S error.co)e S ;0 6 ; S error.text S ; $#O ; S error.Ahere0
;2Q;)
!DI1
!D

2ave 'our ,or- and e6ecute the program# C&ic- the E6it button and 'ou shou&d see something
simi&ar to thisC
Catch an &inall1 Statements
Ctch is a genera& purpose error trap# +t is e6ecuted ,hen an error is raised an',here
bet,een ,here a /unction starts to e6ecute and ,here it ends# Catch provides a means to dea&
,ith errors that ma' occur in a given /unction and sti&& a&&o, the user to -eep using the
program# An error can be raised b' the /unction itse&/, or b' an' other /unction it ma' ca&&
during e6ecution# +/ the ca&&ed /unction has a Catch b&oc-, the more nested the Catch b&oc- is,
the more priorit' it has# +n other ,ords, i/ an' error occurred in the nested section o/ code,
the Catch in that section ,ou&d be e6ecuted, not the Catch /rom the ca&&ing /unction# +/ an
error is raised ,hi&e the program is e6ecuting ,ithin the catch b&oc- itse&/, the error ,i&&
norma&&' be propagated outside the catch b&oc- because catch has no means o/ protecting
itse&/# +/ there is a !inlly part in the /unction, it must precede the catch part# Let's create a
simp&e program to demonstrate this /eature# Create a ne, pro9ect named Chap8F as a G@+
based pro9ect and ,hen the +.E appears, create a startup c&ass /orm named 71ain# Add t,o
buttons, Error and Huit, named ErrBtn and HuitBtn# P&ace the buttons on the bottom right
corner o/ the /orm# Create a >e6tLabe& and name it >e6tLabe&"# Put it at the top &e/t corner o/
the /orm and stretch it a&& the ,a' across and ma-e it about one inch in height# .oub&e4c&ic-
308
Figure 0): -rror results caught .ith TBK.
on the /orm and enter this codeC
T .ambas class *ile
PUBLIC SUB 8neA()
#extLabel=.#ext 6 ;UcenterKUstron5K!o errors present.;
!D
S#$#IC PUBLIC 1U!C#I2! '-n() $S Boolean
DIM h1orm $S 1orm
h1orm 6 !+ 1orm=
'#U'! h1orm.ShoAMo)al()
!D
M.Close(#'U)
!D
PUBLIC SUB rrBtn8Click()
DIM a $S Inte5er
DIM b $S Inte5er

a 6 B
b 6 9
P'I!# aMb TAill 5enerate a )ivi)e by Rero error
1I!$LLW
#extLabel=.#ext 6 ;CL$SSO ; S Str(rror.class) S ;0 C2DO ; S error.co)e S ;0 6 ; S error.text S ; $#O ; S error.Ahere
#extLabel=.'e*resh
C$#C:
I1 ''2' #:!
Messa5e.rror(;CL$SSO ; S Str(rror.class) S ;0 C2DO ; S error.co)e S ;0 6 ; S error.text S ; $#O ; S error.Ahere0
;2Q;)
!DI1
Messa5e.In*o(;Cleare) the rror;0 ;2Q;)
#extLabel=.#ext 6 ;UcenterKUstron5Krror has been cleare).;
!D
<hen 'ou run the program, 'ou shou&d see this as the opening screenC
30?
:o,, c&ic- the error button to generate our error and 'ou shou&d see thisC
Kou shou&d a&so notice that the main screen >e6tLabe& has changed to thisC
Once 'ou c&ic- the O- button /or the Error 1essage dia&og, 'ou ,i&& see thisC
30%
Figure 111: +n(o message that the error is cleare".
Figure 00: The Te8t>abel up"ate" .ith error in(o.
Figure 0/: ,i' b$ 6ero error caught b$ AT?.
Figure 0*: AT? test program opening screen.
:o,, c&ic- the OE button on the +n/o message and the >e6tArea is updated &i-e thisC
>his shou&d give 'ou a prett' good idea o/ ho, to use the Gambas error management
/eatures to he&p manage errors ,hen the' occur in 'our code (and the' inevitab&' ,i&& occur#
:ot hand&ing errors &i-e the div b' 0ero ,e used in our e6amp&e ,i&& be a Asho,4stopperB in
most circumstances# As a 5uic- e6amp&e, go bac- to our code, in the ErrBtnLC&ic- subroutine
and comment out these &ines as sho,n be&o,C
T 1I!$LLW
T #extLabel=.#ext 6 ;CL$SSO ; S Str(rror.class) S ;0 C2DO ; S error.co)e S ;0 6 ; S error.text S ; $#O ; S error.Ahere
T #extLabel=.'e*resh
TC$#C:
T I1 ''2' #:!
T Messa5e.rror(;CL$SSO ; S Str(rror.class) S ;0 C2DO ; S error.co)e S ;0 6 ; S error.text S ; $#O ; S error.Ahere0
;2Q;)
T !DI1
TMessa5e.In*o(;Cleare) the rror;0 ;2Q;)
:o,, run the program again and c&ic- the Error button# =ere is ,hat 'ou getC
Kou can tr' to continue, but there is no guarantee that 'our program ,i&& ,or- correct&'
or that it ,i&& even continue# >his is de/inite&' not ,hat 'ou ,ou&d ,ant 'our users to see# +t
9ust ma-es good sense to use the too&s avai&ab&e in Gambas to prevent this ,hen 'ou can#
30+
Figure 112: ,e(ault Gambas error
"ialog.
Figure 111: 2ain screen a(ter error has been cleare".
:o,, &ets move on to see ho, ,e can use events to he&p ,rite better code#
Gambas Event management
Gambas is bui&t around an event4driven programming paradigm# >raditiona& computer
programming &anguages ,ere designed to /o&&o, their o,n contro& /&o, changing /&o,
direction (course at branch points# +n an event4driven paradigm, the contro& /&o, is &arge&'
driven b' e6terna& events such as mouse movements, button c&ic-s, etc# Genera&&', an event4
driven s'stem is preprogrammed using an event &oop ,hich s'stematica&&' po&&s the s'tem to
&oo- /or in/ormation to process (which could be any type of event, even the passage of time#
+/ an event is detected, it triggers a /&ag that can be chec-ed in the event &oop# >his a&&o,s
programmers to chec- /or and respond to events b' ,riting subroutines or /unction to process
them#
=o, in/ormation on events is ac5uired b' the s'stem is not rea&&' important to the
programmer# Common t'pes o/ event input data can be po&&ed in the event &oop# Comp&e6 or
proprietar' events ma' re5uire the use o/ interrupt hand&ers that react to hard,are events,
such as signa& data traversing a :et,or- +nter/ace Card (:+C# 1ost event4driven s'stems use
both techni5ues# A&gorithms ,ritten b' the programmer to respond to events ensure that
,hen a given event is triggered, code to hand&e the event in a manner acceptab&e to the user is
provided# >his creates a &a'er o/ so/t,are abstraction that emu&ates an interrupt driven
environment# Event4driven programs t'pica&&' consist o/ a number o/ sma&& programs ca&&ed
event hand&ers# Event hand&ers are ca&&ed in response to events# A dispatcher is used to ca&&
the event hand&er# 1ost o/ten, the dispatcher is imp&emented b' using an event 5ueue to ho&d
unprocessed events#
2ometimes, event hand&ers can trigger events themse&ves# >his can possib&' &ead to an
event cascade (not good# Gambas, &i-e most common graphica& user inter/ace programs, is
programmed in an event4driven st'&e# +n Gambas, 'ou have the capabi&it' o/ creating events
/or use in 'our programs# Kou can dec&are an event &i-e thisC
(!# I)enti*ier("Parameter <= "0 Parameter <B ...%) "$S Boolean%
>his dec&aration ,i&& dec&are a class event# A c&ass event is raised b' a /unction ca&&#
Additiona&&', 'ou can speci/' ,hether or not the event hand&er ,i&& return a (Boo&ean va&ue#
+/ a return va&ue is speci/ied, a >R@E return resu&t ,ou&d indicate that the event ,as cance&ed#
+n Gambas, the standard ca&&ing convention /or an event hand&er ,ou&d be
.nstance(ame=Event(ame to invo-e the method to be ca&&ed b' the event &istener ,hen such
an event is raised# Let's add to our previous e6amp&e to demonstrate the use o/ events# Add
another button to the /orm /or our previous e6amp&e, named EventBtn# .oub&e4c&ic- and add
this code to the programC
(!# Myvent(Ms5 $S Strin5) $S Boolean
310
PUBLIC SUB vent=Btn8Click()
DIM b'es-lt $S Boolean
b'es-lt 6 '$IS Myvent(;'aise an event;)
I1 b'es-lt #:!
#extLabel=.#ext 6 ;Cancelle) the event;
LS
#extLabel=.#ext 6 ;'aise) the event;
b'es-lt 6 !2# b'es-lt
S#2P (!#
!DI1
!D
2ave 'our ,or- and run the program# C&ic- the Event button and 'our disp&a' shou&d &oo-
&i-e thisC
>his chapter has e6p&ained the basic concepts o/ error hand&ing in programming
environments, Gambas in particu&ar# >he -no,&edge presented here ,i&& transcend the
speci/ic &anguage 'ou use to program and ,i&& be o/ great assistance in 'our programming
endeavors over time# <e hope this has he&ped 'ou to understand ho, to better program 'our
code and ma-e 'our app&ication more re&iab&e and use/u& to the communit' o/ users 'ou ,i&&
support#
311
Figure 113: Aur e'ent .as raise".
Chapter 1! )ouse* Keyboard and #it
5perations
>he mouse ,as designed to be a rep&acement /or gathering -e'board input /rom users#
<hi&e G@+ design has advanced signi/icant&' since the ear&' da's o/ ,indo,ed inter/aces, the
evo&ution o/ the mouse has not# Probab&' the biggest change /or the mouse ,as going optica&
and cord&ess# =o,ever, the basic /unctiona&it' remains virtua&&' the same# Provide an Q,K
position, c&ic- a &e/t, right, or midd&e button and detect it's state as up or do,n, and chec- the
movement o/ the mouse ,hee& or change the de&ta va&ue ,hen the ,hee& moves# Gambas, o/
course, supports a&& o/ these basic /eatures ,ith an eas' to code, &ogica& approach# +n the ne6t
/e, pages, ,e ,i&& sho, 'ou ho, to master mouse and -e'board input# 7ina&&', as a &ast
e6ercise, ,e ,i&& create a program to sho, 'ou ho, to use bit operators# Let's start ,ith the
mouse#
2ouse Operations
+n Gambas, ,e can use the 1ouse c&ass to obtain in/ormation about a mouse event#
>his c&ass de/ines the constants used ,ith the mouse properties# >he c&ass is static and the
properties supported areC
$lt B-tton Control Delta
Le*t Meta Mi))le !ormal
2rientation 'i5ht Screen7 ScreenW
Shi*t Start7 StartW 7
W
1ost o/ these properties are se&/4e6p&ained b' their name, but a /e, need /urther
e6p&anation# >he ,lt, Control, Met and $hift properties a&& return a >R@E va&ue i/ those
respective -e's are pressed# Nor"l can be chec-ed (tested to see i/ an' other specia& -e'
,as pressed# %utton can be used to see i/ an' button is pressed but 'ou can use )eft4 +ight,
and Middle to determine i/ an' speci/ic mouse button has been pressed# A&& o/ these
properties return >R@E i/ a button is pressed# #elt returns the (o//set va&ue o/ the mouse
,hee& ,hi&e Orienttion can be used to chec- the direction (/or,ard, bac-,ards o/ the
,hee&'s turn# $creenH and $creen3 return the abso&ute va&ue o/ the cursor based on the
des-top# 2tartQ and 2tartK return the va&ues o/ 1ouse#Q and 1ouse#K at the beginning o/ the
event, ,hi&e H and 3 return the current position, re&ative to the ,indo,#
>here is on&' one method /or the 1ouse c&ass, 1ove# >he Move "ethod simp&'
repositions the mouse cursor to the Q,K coordinates speci/ied# 1ouse events 'ou can monitor
in 'our program are 1ousemove, 1ouse.o,n, 1ouseup, and 1ouse,hee&# An' change in
the current state o/ those events a&&o, 'ou to create a coded response /or that event# ?hen
coding mouse (or &eyboard) operations, it is very important to always use the predefined
312
constants. @sing an' other method o/ getting or setting properties is not guaranteed to be
up,ard compatib&e /rom one Gambas version to the ne6t# >he 1ouse c&ass uses the /o&&o,ing
constants to speci/' the shape o/ the mouse cursorC
$rroA Blank Cross C-stom De*a-lt
:oriRontal Pointin5 SiRe$ll SiRe SiRe:
SiRe! SiRe! SiRe!S+ SiRe!+ SiRe!+S
SiReS SiReS SiReS+ SiRe( SiRe+
Split: Split( #ext (ertical +ait
Let's create a short Gambas program to demonstrate ho, to use the mouse no,# 7rom
the Gambas +.E, create a ne, pro9ect named 1ouseOps and ma-e it a graphica& user
inter/ace pro9ect, trans&atab&e ,ith pub&ic contro&s# Create a ne, /orm, 71ain, a startup c&ass
/orm# :e6t, add a dra,ing area named da to the top &e/t corner o/ the 71ain#/orm ,indo,#
Resi0e it to be about one inch s5uare# :o,, &et's add some code# 7irst o/ a&&, ,hen the
program runs and the ,indo, opens, ,e ,ant to set a caption that te&&s the user ho, to c&ear
or e6it the ,indo,# <e a&so need to resi0e the dra,ing area to /it the /orm /u&&' and set the
cached bu//er propert' to >R@E so our dra,ing can be seen b' the user# =ere is ho, to do
thisC
T .ambas class *ile
TAhen *orm opens at r-ntime0 set a caption an) resiRe the )raAin5 area
M.Caption 6 ;Press space to clear0 mo-seAheel exits...;
)a.+ 6 M.+,C
)a.: 6 M.:,C
)a.1oreColor 6 color.Black Tset the *ore5ro-n) color to black
Tset cache) property to tr-e so Ae can store the )raAin5 b-**er
)a.Cache) 6 #'U
)raA.Be5in()a) Tstart to )raA
TAe Aill )raA a horiR an) vert line to section *o-r I-a)rants
)raA.Line(=0)a.hMB0)a.+,=0)a.hMB)
)raA.Line()a.+MB0 =0 )a.+MB0 )a.: , =)
)raA.n)
!D
+/ the mouse moves, ,e ,ant to change the cursor shape, depending on ,hich 5uadrant
o/ the dra,ing area the mouse is in# <e ,i&& use the 1ousemove event and code thisC
Ti* the mo-se moves0 Ae Aill -p)ate the c-rsor shape )epen)in5 on the
TI-a)rant the mo-se is locate) at
PUBLIC SUB )a8Mo-seMove()
Tcheck the top le*t I-a)rant
I1 mo-se.7 U6 )a.+MB $!D mo-se.W U6 )a.:MB #:!
)a.Mo-se 6 mo-se.Pointin5
313
Telse Ae check the bottom le*t I-a)rant
LS I1
mo-se.7 U6 )a.+MB $!D mo-se.W K6 )a.:MB #:!
)a.Mo-se 6 mo-se.Cross
Telse Ae check the top ri5ht I-a)rant
LS I1
mo-se.7 K6 )a.+MB $!D mo-se.W U6 )a.:MB #:!
)a.Mo-se 6 mo-se.SiRe!+S
TotherAise0 it m-st be in the bottom ri5ht I-a)rant
LS I1
mo-se.7 K6 )a.+MB $!D mo-se.W K6 )a.:MB #:!
)a.Mo-se 6 mo-se.SiRe!S+
Ti* it is anyAhere else0 make it the )e*a-lt
LS
)a.Mo-se 6 mo-se.De*a-lt
!DI1
:o, that ,e have set the cursor shape, ,e ,i&& chec- to see i/ the user is pressing a mouse
button to dra,# +/ the &e/t button is pressed, ,e ,i&& dra, points# +/ it is the right button, ,e
,i&& dra, tin' bo6es#
Tcheck mo-se b-tton is presse) to see Ahich one is presse) an)
T)raA points *or le*t btn0 boxes *or the ri5ht
I1 Mo-se.Le*t #:!
Tstart to )raA
DraA.Be5in()a)
Tlittle tiny )ots
DraA.Point(Mo-se.70 Mo-se.W)
DraA.n)
LS Ti* it is ri5ht b-tton
DraA.Be5in()a)
DraA.'ect(Mo-se.70 Mo-se.W0 /0 /)
DraA.n)
!DI1
!D
<henever the user moves the mouse ,hee&, ,e ,i&& terminate the app&ication#
Ti* the -ser moves the mo-se Aheel0 Ae Aill terminate the application
PUBLIC SUB )a8Mo-se+heel()
M.Close
!D
314
+/ the user has pressed and re&eased a mouse button, ,e ,i&& reset the mouse cursor to the
norma& state#
TAhenever a mo-se b-tton is release)0 reset mo-se c-rsor to normal
PUBLIC SUB )a8Mo-seUp()
)a.Mo-se 6 mo-se.De*a-lt
!D
7ina&&', i/ the user presses an' -e', ,e ,i&& reset the dra,ing area b' c&earing it and redra, the
5uadrant b' ca&&ing the same routine used to open the /ormC
Tcheck kb) events to clear the )raAin5 area an) re)raA the I-a)rants
PUBLIC SUB 1orm8QeyPress()
)a.Clear
1orm82pen()
!D
>hat's it# <hen 'ou run the program, 'ou shou&d see something &i-e thisC
As 'ou move the mouse /rom 5uadrant to 5uadrant, notice ho, the cursor changes#
>r' both the &e/t and right mouse buttons and press the spacebar to c&ear the dra,ing and
restart# <hen 'ou are satis/ied ever'thing ,or-s, move the mouse ,hee& and the program ,i&&
31#
Figure 11#: 2ouseAps program running.
terminate# :o,, &et's &earn about -e'board operations#
9eyboard Operations
>his c&ass is used /or getting in/ormation about a -e'board event# +t contains a&& o/ the
prede/ined constants Gambas uses to represent the -e's /ound on 'our -e'board# As ,e
pointed out previous&', 'ou shou&d never use the integer -e' va&ues direct&'# Kou shou&d
a&,a's use the Gambas prede/ined constants# >his c&ass is static and it acts &i-e a read4on&'
arra'# Kou can dec&are an integer variab&e and obtain the va&ue o/ a -e' constant using this
ca&&ing conventionC
DIM MyInte5er $S Inte5er
MyInte5er 6 Qey " Qey $S Strin5 %
Properties that are supported /or the Ee' c&ass inc&ude ,lt4 Code4 Control4 Met4
Nor"l4 $hift4 $tte and &ext1 2tate can be used to test ,hether or not a specia& -e' is
pressed and >e6t ,i&& return the sing&e character representation /or a given -e'# A&& the other
properties ,or- &i-e those used ,ith the 1ouse c&ass ,e described in the previous section#
>he Ee' c&ass supports the /o&&o,ing prede/ined constantsC
7or cursor -e'sC )p6 !own6 &eft6 and (ight
7or /unction -e'sC -; -@ -A -B -C -D -E -F -G -;< -;; -;@
7or shi/ted 74-e'sC -;A -;B -;C -;D -;E -;F -;G -@< -@; -@@ -@A -@B
7or a&& other -e'sC
+ack,pace +ackTab Caps&ock !e*ete End Enter Escape
$e*p $ome %nsert 2enu Num&ock Page!own Page)p
Pause Print (eturn ,cro**&ock ,pace ,ys(e> Tab
Let's create another short Gambas program to demonstrate ho, to use the -e'board#
7rom the Gambas +.E, create a ne, pro9ect named EbdOps and ma-e it a graphica& user
inter/ace pro9ect, trans&atab&e ,ith pub&ic contro&s#
Create a ne, /orm, 71ain, a startup c&ass /orm# <e ,i&& on&' need to use t,o &abe&s in
this program, a >e6tLabe& and a Labe&# 7irst, create a >e6tLabe& named >e6tLabe&" and ma-e
it about "M;B high and stretch it across the ,idth o/ the /orm# 2et the >e6tLabe&"#A&ignment
propert' to center#
:o,, create a Labe& named Labe&" and p&ace it be&o, the >e6tLabe&" contro&# 1a-e it
about t,o inches ,ide and "M;B ta&&# 2et the Labe&#>e6t propert' to APress an' -e'###B and set
the contro& /ont si0e to "( point and ma-e it bo&d# .oub&e4c&icon the /orm and the code
,indo, appears# =ere is the code ,e ,i&& add to our programC
318
T .ambas class *ile
TAe Aill check the key release event to see Ahat to )o
PUBLIC SUB 1orm8Qey'elease()
TAhenever a key is release)0 check the co)e
SLC# key.co)e
C$S key.#ab Ti* it is a tab key
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 #$B.;
C$S key.BackSpace Tor backspace
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 Backspace.;
C$S key.CapsLock Tor caps lock
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 CapsLock.;
C$S key.1= Tor a 1,key
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1= key.;
C$S key.1B
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1B key.;
C$S key.1/
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1/ key.;
C$S key.1@
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1@ key.;
C$S key.1C
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1C key.;
C$S key.1F
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1F key.;
C$S key.1X
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1X key.;
C$S key.1?
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 1? key.;
Ti* none o* the above0 is it printableJ I* so0 shoA co)e an) val-e
C$S LS
I1 key.Co)e K /B $!D key.Co)e U =B? #:!
textlabel=.#ext 6 ;key co)e isO ; S key.Co)e S ;0 ; S Chr(key.Co)e)
LS TotherAise 3-st the co)e
textlabel=.#ext 6 ;key co)e isO ; S key.Co)e
!DI1
!D SLC#
!D
Tcheck key )oAn event to *ilter o-t shi*t0 control0 alt0 etc.
PUBLIC SUB 1orm8QeyPress()
I1 key.Shi*t #:!
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 S:I1#;
LS I1 key.$lt #:!
31?
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 $L#;
LS I1 key.Control #:!
textlabel=.#ext 6 ;Qey co)e isO ; S key.Co)e S ;0 C#'L;
LS I1 key.Co)e K /B $!D key.Co)e U =B? #:!
textlabel=.#ext 6 ;key co)e isO ; S key.Co)e S ;0 ; S Chr(key.Co)e)
LS I1 key.sc #:! Ti* an SC key is presse)
textlabel=.#ext 6 ;key co)e isO ; S key.Co)e S ;0 SC;
LS
textlabel=.#ext 6 ;key co)e isO ; S key.Co)e
!DI1
!D
M.Caption 6 ; Qeyboar) 2perations ;
!D
As 'ou can see, the code above is prett' straight4/or,ard and simp&e# <hen 'ou run the
program, 'ou shou&d see something &i-e thisC
+it Operations
9its are the sma&&est e&ements used in computer operations# >he' are indivisib&e atoms
o/ memor' c&ustered in groups ca&&ed b'tes# A byte is composed o/ n number o/ bits, ,hich is
dependent upon the machine word si6e# 7or e6amp&e, in an eight4bit s'stem, one b'te is
composed o/ eight bits#
7or modern computing s'stems used toda', the operating s'stem is bui&t using D; or I(
bit ,ord si0es# >he ,ord si0e increases in order to accommodate a &arger addressab&e memor'
space# +n an o&der eight4bit s'stem /or e6amp&e, the s'stem can on&' address memor' that can
31%
Figure 11%: The Ce$boar" Aperations program
running.
be e6pressed in binar' /orm as """"""""# +n other ,ords, the memor' space is &imited to a si0e
that can be e6pressed ,ith those eight bits# 7or an eight4bit s'stems memor' ranges e6tend
/rom the sing&e4b'te decima& representation o/ 4IGGDJ to FIGGD*# +n a modern D;4bit s'stem,
it ta-es the binar' /orm o/ """""""""""""""""""""""""""""""" ,hich can be e6pressed in decima&
notation as 4;,"(J,(*D,I(* to F;,"(J,(*D,I(J# As 'ou can see, the addressab&e range o/
memor' ,ith D;4bit s'stems is hugeS
+n app&ications &eve& programming, there is genera&&' not much occasion to operate at
the bit4&eve& ,hen but occasiona&&' the need does arise# Gambas provides a&& o/ the too&s 'ou
need to test a bit, c&ear it, change (invert it, or set it# Additiona&&', bit,ise operations 'ou can
per/orm inc&ude rotating a bit right or &e/t and shi/ting a bit right or &e/t# >he tab&e be&o,
summari0es the bit operations 'ou can per/orm in GambasC
Gambas !it Operations
Operator Syntax Action taken
(Tst (oolean > (Tst9!-mber " (it: Test to see i0 a bit is set in operand1 -sing operand2
(Clr Val-e > (Clr9!-mber " (it: Clear a speci0ic bit in operand1 -sing operand2
(Set Val-e > (Set9!-mber " (it: #et-rn T#UE i0 the the bit speci0ie in operand2 o0 operand1 is set7
(Chg Val-e > (Chg9!-mber " (it: #et-rns operand1 4ith the bit speci0ie in operand2 in/erte7
Shl Val-e > Shl9!-mber " (it: #et-rns operand1 4ith the bit speci0ie in operand2 shi0te le0t one bit position7
Shr Val-e > Shr9!-mber " (it: #et-rns operand1 4ith the bit speci0ie in operand2 shi0te right one bit position7
#ol Val-e > #ol9!-mber " (it: #et-rns operand1 rotate le0t operand2 bit positions7
#or Val-e > #or9!-mber " (it: #et-rns operand1 rotate right operand2 bit positions7
:o,, ,e ,i&& create 'et another short Gambas program to demonstrate ho, to use the
bit /unctions# 7rom the Gambas +.E, create a ne, pro9ect named BitOps# 1a-e it a graphica&
user inter/ace pro9ect, trans&atab&e ,ith pub&ic contro&s# Create a ne, /orm, 71ain, 'our
de/au&t startup c&ass /orm#
Our program ,i&& ta-e an integer number /rom $ ;GG and disp&a' the
he6adecima& and binar' va&ues /or that number# +t ,i&& a&&o, 'ou to se&ect an' one o/ the eight
bits used to represent the integer number and per/orm ,hatever operation the button 'ou
c&ic- represents# >he binar' va&ue o/ that integer ,i&& be disp&a'ed so 'ou can compare that
binar' va&ue to the va&ue o/ the integer as origina&&' speci/ied#
7or this program, ,e ,i&& need seven >e6tLabe&s, named >e6tLabe&" through
>e6t&abe&J# +n our e6amp&e, /or >e6tLabe&G and >e6tLabe&J, ,e have set /ont st'&e in the
Properties tab to ABo&dB# <e ,i&& need t,o >e6tBo6es, >e6tBo6" and >e6tBo6;# 7ina&&', ,e
,i&& add nine buttons named +ol%tn4 +or%tn4 $hl%tn4 $hr%tn4 Cler%tn4 $et%tn4
31+
&est%tn4 Chnge%tn4 and the Euit%tn# La'out the contro&s above on the /orm, as sho,n
in the /igure be&o,C
Once 'ou have /inished &a'ing out the contro&s as sho,n in the /igure above, doub&e4
c&ic- some,here on the /orm and the code ,indo, ,i&& appear# Add the /o&&o,ing code /or the
7ormLOpen subroutineC
T .ambas class *ile
M.Caption 6 ; bit2pns ;
!D
:o,, the program ,i&& disp&a' the caption A bitOpns B ,hen it is e6ecuted# Let's code
an e6it procedure so the user can terminate the app&ication ne6t# .oub&e4c&icon the Huit
button and add thisC
M.Close Tclose the Ain)oA
!D
+/ the user enters an' va&ue in the >e6tBo6; /ie&d to change a bit, ,e need to update the
/orm and re/&ect the changed va&ues# <e ,i&& ,orr' about ,hat to do ,ith the ne, va&ue a
&itt&e &ater on in the code# 7or no,, it is a simp&e ca&& to the Re/resh method ,e needC
PUBLIC SUB #extBoxB8Chan5e()
1Main.'e*resh Tre*resh o-r )isplay anytime the bit val-e chan5es
!D
<hen the user speci/ies an integer va&ue in the >e6tBo6" /ie&d, ,e ,i&& on&' react to the
entr' ,hen the >AB -e' is pressed# >hat causes a Lost7ocus event, ,hich is ,hat ,e ,i&& code
/or# =ere is ,hat ,e need to do ne6tC
320
Figure 11): The =itAps program in "esign mo"e.
PUBLIC SUB #extBox=8Lost1oc-s()
TAe nee) a local int var to Aork Aith
DIM myInt $S Inte5er
Tconvert o-r strin5 text val-e to an int
myInt 6 CInt(#extBox=.text)
Tcheck to see i* it is in ?,bit ran5e
I1 Int(myInt K6 9) $!D (myInt U BCF) #:!
#extLabelB.#ext 6 ;:exO ; S :ex(myInt) Tconvert hex val-e
#extlabel/.#ext 6 ;BinO ; S Bin(myInt) Tconvert bin val-e
#extlabelX.#ext 6 Str[(myInt) T-p)ate o-r text *iel)s
1Main.'e*resh Tre*resh the *orm
!DI1
!D
<hen the user presses the c&ear button, ,e ,ant to c&ear the bit speci/ied /or the integer
represented b' the /irst parameter#
PUBLIC SUB ClearBtn8Click()
DIM i $S Inte5er
DIM res-lt $S Inte5er
myInt 6 CInt(#extBox=.#ext)
Ti* the inte5er is betAeen 9 an) BCC process0 otherAise i5nore
Tconvert strin5 val-e to an int
res-lt 6 CInt(#extBoxB.#ext)
Tclear the bit
i 6 BClr(myInt0 res-lt)
T-p)ate the label )isplays
#exLtabelC.#ext 6 ;BclrO ; S Bin(i)
#extLabelX.#ext 6 Str[(i)
!DI1
!D
<hen the user presses the 2et button, ,e ,ant to set the bit speci/ied /or the integer
represented b' the /irst parameter# >his is essentia&&' the opposite o/ c&ear discussed above#
PUBLIC SUB SetBtn8Click()
DIM i $S Inte5er
321
Ti* the inte5er is betAeen 9 an) BCC process0 otherAise i5nore
Tconvert strin5 val-e to an int
Tset the bit
i 6 BSet(myInt0 res-lt)
T-p)ate the labels
#extLabelC.#ext 6 ;BsetO ; S Bin(i)
!DI1
!D
>he Bchg /unction is rea&&' 9ust an invert operation# <hen our user c&ic-s the Change button,
,e ,i&& e6ecute this codeC
PUBLIC SUB Chan5eBtn8Click()
DIM i $S Inte5er
i 6 BCh5(myInt0 res-lt)
#extLabelC.#ext 6 ;Bch5O ; S Bin(i)
!DI1
!D
>he 2h& /unction ,i&& shi/t the va&ue o/ 1'+nt n bits &e/t ,here n is speci/ied b' the
second parameter# <hen our user c&ic-s the 2h& button, ,e ,i&& e6ecute this codeC
PUBLIC SUB S:LBtn8Click()
DIM i $S Inte5er
i 6 Shl(myInt0 res-lt)
#extLabelC.#ext 6 ;S:LO ; S Bin(i)
322
!DI1
!D
>he 2hr /unction is ,i&& shi/t the va&ue o/ 1'+nt n bits right ,here n is speci/ied b' the
second parameter# <hen our user c&ic-s the 2hr button, this subroutine ,i&& be e6ecutedC
PUBLIC SUB S:'Btn8Click()
DIM i $S Inte5er
i 6 Shr(myInt0 res-lt)
#extLabelC.#ext 6 ;S:'O ; S Bin(i)
!DI1
!D
+n o&der *4bit s'stems, it ,as impossib&e to process numbers &arger than ;GG un&ess
the' ,ere sp&it up into *4bit chun-s# Operations ,ere then per/ormed on each piece o/ a
number# A/ter the operations ,ere comp&eted, it ,as necessar' to reassemb&e each number
bac- together to recreate the ,ho&e number# A&& o/ this ,as accomp&ished b' using one tin'
bit, the carr' bit# >he Gambas /unctions ROL (rotate &e/t and ROR (rotate right are used to
shi/t bits in binar' numbers# >hese /unctions ,or- conceptua&&' &i-e thisC
.he &/1 4nstruction
.he &/& 4nstruction
ROL and ROR ,or- such that the carr' bit is shi/ted into the end bit that is &e/t empt'
b' the rotation process instead o/ inserting a 0ero va&ue# ROL shi/ts the contents o/ a b'te one
p&ace to the &e/t# ROL does not p&ace a 0ero into bit $# +nstead, it moves the carr' bit /rom bit
323
8 ? # 4 3 2 1 0
C
8 ? # 4 3 2 1 0
C
position J into bit position $ o/ the number being shi/ted# >he $ bit position ,as vacated b'
the shi/t rotation and the ROL instruction p&aces bit J into the carr' bit position# ROR ,or-s
9ust &i-e ROL, but in the opposite direction# +t moves each bit o/ a b'te right one position,
p&acing the carr' bit into bit J and bit $ into the carr' bit#
Trotate le*t
PUBLIC SUB '2LBtn8Click()
DIM i $S Inte5er
i 6 'ol(myInt0 res-lt)
#extLabelC.#ext 6 ;'2LO ; S Bin(i)
!DI1
!D
Trotate ri5ht
PUBLIC SUB '2'Btn8Click()
DIM i $S Inte5er
i 6 'or(myInt0 res-lt)
#extLabelC.#ext 6 ;'2'O ; S Bin(i)
!DI1
!D
+/ 'ou ,ant to chec- to see i/ a bit has been set, 'ou can ca&& Btst# >his /unction ,i&& return
>R@E i/ the bit speci/ied in operand@ o/ operand8 is >R@E#
PUBLIC SUB #estBtn8Click()
DIM i $S Boolean
324
i 6 B#st(myInt0 res-lt)
#extLabelC.#ext 6 ;BtstO ; S i
!DI1
!D
>hat is a&& ,e have to do /or our bit4/idd&ing program# 2ave 'our ,or- and e6ecute the
program# Kour resu&ts shou&d be simi&ar to thisC
<hen 'ou are satis/ied that the program ,or-s as ,e p&anned, save 'our ,or-# +t
,ou&d be a good e6ercise at this time to go bac- and modi/' the code to ensure on&' integer
va&ues are input into the t,o >e6tbo6 /ie&ds# A&so, 'ou cou&d a&&o, negative numbers to be
entered to see ,hat resu&ts ,ou&d be produced# + ,i&& &eave that e6ercise to those among 'ou
eager and ambitious enough to tr' it is rea&&' not ver' di//icu&t and ,e have a&read' sho,n
'ou ho, to do va&idation routines (remember, bac- in the co&&ections chapterN# +n the ne6t
chapter, ,e ,i&& cover database operations ,ith Gambas# >he abi&it' to ,or- ,ith data in 'our
programs is essentia& and ,e cannot over&oo- this vita& aspect o/ programming in our 9ourne'
through Gambas#
32#
Figure 11*: Aur bitAps program running.
Chapter 1% )y-8L and Gambas
>his chapter describes in detai& the process o/ using the 1'2HL database /rom ,ithin
the Gambas programming environment# 7or our purposes, ,e ,i&& assume that 1'2HL is
a&read' insta&&ed on 'our machine (or a machine accessib&e to 'ou /rom 'our machine and
that a 1'2HL server is avai&ab&e /or 'ou to connect to /rom ,ithin 'our Gambas program# +/
this is not the case, then 'ou ,i&& have to re/er to the 1'2HL manua& and /igure out ho, to
insta&& the 1'2HL database distribution on 'our particu&ar s'stem# Kou shou&d a&so be a,are
o/ the /act that Gambas ,i&& a&so ,or- ,ith Postgre2HL and 2HLite# 2HLite is not a true
c&ientMserver architecture &i-e 1'2HL and Postgre2HL# +t is a /&at4/i&e database s'stem and
does not use the c&ientMserver database mode&# 7or our purposes in this chapter, ,e ,i&& stic-
to 1'2HL since it is probab&' the most ,ide&' used o/ the three database products#
>he 1'2HL database pac-age consists o/ the 1'2HL server and man' c&ient programs#
>he 1'2HL server is a program that stores and manages a&& o/ 'our databases ,ithin the
1'2HL environment# >he c&ient programs that are inc&uded ,ith 1'2HL are too numerous to
&ist here but it is important /or 'ou to understand that each c&ient app&ication serves a speci/ic
purpose re&ated to the management andMor administration o/ data or metadata stored on the
1'2HL server# >he c&ient program ,e ,i&& be dea&ing ,ith in this chapter is ca&&ed m's5&
(note it is spelled in lowercase letters# >his c&ient program provides a command &ine
inter/ace (CL+ 'ou can use to issue 2HL statements interactive&' to the 1'2HL server and see
the resu&ts disp&a'ed immediate&'# >he main di//erence bet,een My$E) and mys"l is that
My$E) is used to re/er to the entire My$E) distribution pac-age or to re/er to the My$E)
server ,hi&e mys"l re/ers to the c&ient CL+ program#
<hat purpose does it serve to have both a c&ient and a server instead o/ a sing&e
programN >he server and c&ient programs are divided into di//erent entities so 'ou can use the
c&ient program(s on 'our s'stem to access data on a 1'2HL server that cou&d be running on
another computer# B' separating the pac-age into a server and n c&ients, it serves to separate
data /rom the data retrieva& inter/ace# Be/ore 'ou begin ,or-ing on this chapter, it is high&'
recommended that 'ou /ami&iari0e 'ourse&/ ,ith 1'2HL b' do,n&oading the &atest manua&
/rom the o//icia& 1'2HL ,eb site
"J
# At a minimum, comp&ete the tutoria& in Chapter D o/ the
1'2HL @ser 1anua& be/ore proceeding ,ith this chapter# Once 'ou are /ami&iar ,ith ho,
basic 2HL operations ,or- ,ithin the 1'2HL environment, 'ou are read' to continue ,ith
this chapter, ,hich /ocuses more on ho, to accomp&ish the same t'pes o/ things the 1'2HL
tutoria& demonstrated, but /rom ,ithin a Gambas program#
+n order to access databases ,ithin the Gambas environment, 'ou need to ensure 'our
pro9ect uses the gb#db component# <hen 'ou create a ne, pro9ect, 'ou need to go to the
pro9ect properties dia&og and 'ou ,i&& /ind a tab /or components# 7rom ,ithin this tabbed
dia&og, 'ou can se&ect the components 'ou need /or 'our program# +n the case o/ databases,
'ou ,i&& need to chec- gb8db be/ore 'ou can use an' o/ the c&asses de/ined b' this component#
As ,e stated previous&', the gb#db component a&&o,s 'ou to access the /o&&o,ing database
1? /ee ,6' httpG99www.m*sEl.com9 .
328
management s'stemsC Postgre2HL, 1'2HL, 2HLite;, 2HLiteD, 7irebird, and O.BC# Because
Postgre2HL and 1'25& are c&ientMserver databases, it means 'our program ,i&& need to ma-e
a connection to a database server# 2HLite is a /&at/i&e4based database so there is no server
process /or 'our program to connect ,ith# =o,ever, this a&so means that 'our program ma'
need to use /u&&' 5ua&i/ied pathnames /or an' database /i&e it uses i/ the de/au&t path (i.e., the
application path is not used#
>he gb#db component has been designed to create an intermediate (abstracted &a'er
bet,een the database server and 'our program# >his a&&o,s 'ou to use the same code
regardless of the database backend 'ou decide to use# >here are a coup&e o/ caveats, o/
course# >his abstracted approach on&' ,or-s i/ 'ou have created 'our database b' using the
database manager or b' using the gb#db component# 7urtherrmore, 'ou must use the 7ind,
Create and Edit methods provided ,ith the gb#db component# Kou cannot put 2HL va&ues
direct&' in a re5uest 'ou must use the substitution /eature o/ the a/orementioned methods to
accomp&ish that# 7ina&&', 'ou cannot use the E6ec method to send 2HL re5uests direct&' to the
server to access server4speci/ic /eatures# <hi&e this sounds /air&' restrictive, in rea&it' it is not
a hindrance to 'our program# Given these /e, caveats, 'ou can accomp&ish a&most an'
database operation needed /rom ,ithin the Gambas environment# >he c&asses that are
supported in the gb#db component are 9lob, Connection, -9, -atabase, -atabase:ser, +ield,
.nde, 0esult, 0esult+ield, Table# :oteC Gambas D introduces a ne, c&ass ca&&ed Connections#
+*ob C*ass
>he B&ob c&ass is an ob9ect returned b' a B&ob /ie&d, ,hich is a datat'pe used in 2HLiteD
to contain data o/ indeterminate /ormat, &i-e the !ariant datat'pe in Gambas# >his a&&o,s us
to read or ,rite data ,hen the datat'pe that the variab&e ,i&& receive is not -no,n# B&ob has
t,o propertiesC -ata, ,hich sets or returns the b&ob contents\ and 7ength, ,hich returns the
&ength o/ the B&ob contents in b'tes#
Connection C*ass
>he Connection c&ass estab&ishes 'our connection to the database# +n order to
success/u&&' connect to a database, 'ou must /irst create a connection ob9ect and set the
necessar' properties that ,i&& be used b' the database# :e6t 'ou must ca&& the Open method#
+/ 'ou are connecting to a 2HLite database and the :ame propert' is nu&&, a database is
opened in memor'# +/ the :ame speci/ied is an abso&ute path, the pathname is used# +/ the
:ame speci/ied is a re&ative path and the =ost propert' is nu&&, the database is &ocated in the
app&ication temporar' director' AtmpAgambas.>:.-As"lite# Other,ise, =ost ,i&& contain the
database director' name and the database /i&e path is the resu&t o/ concatenating the =ost and
:ame propert' va&ues# >his c&ass is creatab&e and the ca&&ing convention isC
DIM hConnection $S Connection
hConnection 6 !+ Connection()
32?
Connection %roperties
<hen the hConnection ob9ect is instantiated, it creates a ne, void connection ob9ect#
Kou ,i&& then need to set properties /or this ob9ect# >he properties that 'ou can use ,ith a
connection ob9ect inc&udeC
0harset
Charset is a read4on&' propert' that returns the charset used b' the database# +t is
possib&e /or 'ou to store 'our strings in the database direct&' in @>74* /ormat# =o,ever, 'ou
can a&so can use this propert' combined ,ith the ConvU( subroutine to convert /rom @>74*
/ormat to the database charset /ormat# @sing the database charset comes at a cost in
per/ormance ho,ever# >his is because 'ou must use the ConvU( subroutine each and ever'
time 'ou read or ,rite string data to the database /ie&ds# 7or no,, this is the on&' ,a' 'ou can
do this i/ 'ou ,ant to use the string4based 2HL /unctions and bui&t4in sort routines o/ the
under&'ing database management s'stem (1'2HL, Postgre2HL, or 2HLite# 7uture versions
o/ Gambas may automatica&&' ma-e the conversion bet,een Gambas strings and the
database charset#
8atabases
>he .atabases propert' can be chec-ed to obtain a co&&ection ob9ect that ,i&& contain
names o/ a&& databases that are managed b' the database server# 2'nta6 isC
P'2P'#W Databases $S .ConnectionDatabases
>he resu&ting co&&ection o/ data (,hich is enumerab&e using the 7OR EAC= statement ,ou&d
be the same as i/ 'ou t'ped 2=O< .A>ABA2E2 /rom the m's5& c&ient CL+#
5rror
>his propert' returns the code o/ the &ast error raised b' the database driver#
,ost
Kou can use the =ost propert' to set or get the host name o/ ,here the database server
is &ocated# >he host name can be either a machine name or an +P address# >he de/au&t host is
named &oca&host# +n 2HLite, host name is not re&evant since 2HLite is not a c&ientMserver
database s'tstem# =o,ever, /rom version $#)G /or,ard, it is possib&e /or 'ou to set the home
path /or the 2HLite database b' using this propert'# 2'nta6 /or using the =ost propert' isC
P'2P'#W :ost $S Strin5
1ogin
>he Login propert' is used to set or get the user &ogin data that is used /or estab&ishing
32%
the connection to the database# Once again, this app&ies to 1'2HL and Postgre2HL, not
2HLite# 2ince 2HLite has no concept o/ users, access to a 2HLite database is contro&&ed b' the
/i&e permission settings o/ the database /i&e itse&/# >his means that the Login propert' is
a&,a's going to be set to the user id o/ the user that is e6ecuting the Gambas program that
uses the 2HLite database# 2'nta6 isC
P'2P'#W Lo5in $S Strin5
6ame
>he :ame propert' sets or gets the name o/ the database 'ou ,ant to connect to# +/ 'ou
do not speci/' a name, a de/au&t s'stem database is used# 7or Postgre2HL the de/au&t
database is named template8 and /or m'2HL it is named mys"l# 7or 2HLite, the de/au&t name
is AtmpAs"lite.db# 7or an' database access, ho,ever, the user needs to have at &east read and
connect access privi&eges to use these databases# 25&ite ,i&& &ocate the database /irst b' tr'ing
to use the /u&& pathname i/ it has been given# +/ not, it ,i&& chec- to see i/ the =ost variab&e has
been set# +/ that is the case, 2HLite ,i&& &oo- at the path name that ,as set in the variab&e# +/
the environment variab&e F,M%,$M$E)*&EM#%6OME has been set, then 2HLite ,i&&
use that as the current ,or-ing director'# +t is a&so possib&e to create and use a database in
memor' b' setting the :ame propert' to AL"e"oryLJ rather than Am's5&B or Apostgres5&B or
As5&iteB# 2'nta6 isC
P'2P'#W !ame $S Strin5
/pened
>his Boo&ean propert' returns >R@E i/ the connection is opened# 2'nta6 isC
P'2P'#W '$D 2pene) $S Boolean
*assword
>he Pass,ord propert' ,i&& return or set the pass,ord used /or estab&ishing a
connection to the database# Ca&&ing convention isC
P'2P'#W PassAor) $S Strin5
*ort
>he Port propert' is used to get or set the >CPM+P port used /or estab&ishing the
connection to a database# >he de/au&t port depends on the connection >'pe# 2'nta6 isC
P'2P'#W Port $S Strin5
.ab(es
32+
>he >ab&es propert' is used to obtain a virtua& co&&ection that can be used /or managing
a&& o/ the tab&es o/ a database# 2'nta6 isC
P'2P'#W #ables $S .Connection#ables
.ype
>he >'pe propert' represents the t'pe o/ the database server 'ou ,ant to connect to#
+n Gambas, the current&' supported databaset'pe areC 3postgres5&3, 3m's5&3, and 3s5&ite3# >he
t'pe propert' uses this s'nta6C
P'2P'#W #ype $S Strin5
>sers
>his is a s'non'm /or the Login propert'# 2'nta6 isC
P'2P'#W User $S Strin5
>he @sers propert' returns a co&&ection o/ a&& users registered in the database server#
Li-e an' other co&&ection ob9ect, it can be enumerated ,ith 7OR EAC=# 2'nta6 isC
P'2P'#W Users $S .ConnectionUsers
Version
>he !ersion propert' is a read4on&' va&ue that returns the version o/ the database that
the driver has connected ,ith# 2'nta6 isC
P'2P'#W '$D (ersion $S Inte5er
The Concept o0 a Transaction
>here are times ,hen the order in ,hich database actions (or 5ueries are e6ecuted is
important# 2ometimes, a program must ensure a&& 5ueries in a group are run success/u&&' and
in order or process none o/ them at a&&# A c&assic e6amp&e is ta-en /rom the ban-ing
environment# +/ a given amount o/ mone' (/or e6amp&e, "$$ do&&ars is ta-en /rom one
account and posted to another account, ,e ,ou&d e6pect the /o&&o,ing actions to occurC
UPD$# acco-nt= S# balance 6 balance , =99G
UPD$# acco-ntB S# balance 6 balance H =99G
Both 5ueries must e6ecute success/u&&' or neither must e6ecute# 1one' cannot be
trans/erred out o/ one account and /ai& to be posted to the other account# Both o/ these
5ueries /orm a sing&e transaction that is composed o/ t,o separate actions (debit 8GG from
330
account8 and credit 8GG to account@# A transaction is simp&' one or more individua&
database 5ueries grouped together bet,een %EF*N and COMM*& statements# <ithout a
CO11+> statement, the transaction is not permanent and can be reversed ,ith the
+O))%,CK statement#
1'2HL automatica&&' commits statements that are not part o/ a transaction process#
>he resu&ts o/ an' 2HL @P.A>E or +:2ER> statement that is not preceded ,ith BEG+: ,i&&
immediate&' be visib&e to a&& connections to the database because the commit is automatica&&'
per/ormed# 1ost databases that are ab&e to accomp&ish this are said to be ,C*#.co"plint1
>he AC+. mode& is one o/ the o&dest and most important concepts o/ database theor'# >he
/our goa&s that must be met /or an' database to be considered re&iab&e are ,tomicit',
Consistenc', *so&ation and #urabi&it' (AC+.# Letbs e6amine each o/ these /our characteristics
in detai&#
,to"icity means database modi/ications must /o&&o, an Aa&& or nothingB ru&e# Ever'
transaction is considered an AatomicB unit# +/ an' part o/ the transaction /ai&s, the entire
transaction /ai&s# +t is critica& the .B12 maintain the atomic nature o/ transactions in an'
circumstance#
Consistency states on&' va&id data ,i&& be ,ritten to a database# +/ a transaction is
e6ecuted that vio&ates database consistenc' ru&es, the entire transaction ,i&& be ro&&ed bac-
and the database ,i&& be restored to a state consistent ,ith those ru&es# Converse&', i/ a
transaction e6ecutes success/u&&', it ,i&& maintain a state o/ consistenc'#
*soltion re5uires mu&tip&e transactions that occur simu&taneous&' not impact each
other# 7or e6amp&e, i/ @ser A issues a transaction against a database at the same time @ser B
issues a transaction, both transactions shou&d operate on the database in iso&ated b&iss# >he
database shou&d per/orm one transaction be/ore the other# >his prevents a transaction /rom
reading intermediate data produced as a side e//ect o/ another transaction# +so&ation does not
ensure either transaction ,i&& e6ecute /irst, 9ust that the' ,i&& not inter/ere ,ith each other#
#ur/ility ensures an' transaction committed to the database ,i&& not be &ost# >his is
accomp&ished via database bac-ups and transaction &ogs that /aci&itate restoration o/
committed transactions despite an' subse5uent /ai&ures# :o,, &et's ta-e a &oo- at Gambas
Connection c&ass methods avai&ab&e to 'ou in 'our programs#
Connection Class .ethos
>he connection c&ass provides most o/ the methods 'ou ,i&& need to estab&ish a
connection to a database and e6ecute one or more transactions to /ind, add, change, or de&ete
data#

/pen-0(ose
>he Open method is used to open a connection to the database# Prior to ma-ing the
331
ca&& to Open, 'ou shou&d set the connection properties ,ith the data necessar' to use the
database# Genera&&', at a minimum 'ou ,i&& need to speci/' the t'pe o/ database, the host, a
&ogin +. and pass,ord, and the name o/ the database 'ou ,ish to use# >he s'nta6 /or open isC
1U!C#I2! 2pen ( ) $S Boolean
>he code e6amp&e be&o, sho,s ho, to use the Open method to connect user jrittinghouse to a
1'2HL database named A5ambas9ugsB that is stored on =ost localhostC
DIM [hConn $s !+ Connection
+I#: [hConn
.#ype 6 ;mysIl;
.:ost 6 ;localhost;
.Lo5in 6 ;3rittin5ho-se;
.PassAor) 6 ;ab/Be@@;
.!ame 6 ;.ambasB-5s;
!D +I#:
#'W [hConn.2pen
I1 rror #:! P'I!# ;Database cannot be opene). rror 6 ;G rror.#ext
>o c&ose the connection, simp&' invo-e the C&ose method# +n our e6amp&e above, 'ou cou&d
use this codeC
[hConn.Close
and the connection ,ou&d be c&osed# +n order to subse5uent&' use an' data stored in the
database, 'ou ,ou&d need to re4open the database using the Open method#
Begin-0ommit-&o((back
As ,e stated previous&', a transaction is one or more individua& database 5ueries that
are grouped together bet,een BEG+: and CO11+> statements# <ithout a CO11+>
statement, the transaction is not permanent and can be reversed ,ith a ROLLBACE
statement# Remember that 1'2HL automatica&&' commits statements that are not part o/ a
transaction process (de/ined b' BEG+: and CO11+># +n Gambas, it is recommended that
'ou use the 7ind, Create, and Edit methods to ma-e changes to the database# >his he&ps to
maintain code independence and it a&&o,s 'ou to ,rite a sing&e piece o/ code that ,i&& ,or-
,ith an' database supported b' Gambas# Gambas uses a result ob:ect to return the resu&ts
o/ a 2HL 5uer'#
332
2ind
>he 7ind method returns a read4on&' 1esult ob:ect used /or 5uer'ing records in the
speci/ied tab&e# >he ca&&ing convention /or 7ind isC
1U!C#I2! 1in) (#able $S Strin5 "0 'eI-est $S Strin50 $r5-ments $S 0 ... % ) $S 'es-lt
0e"uest represents a 2HL <=ERE statement that is used /or 5uer'ing the tab&e#
)rguments are 5uoted as necessar' (dictated b' 2HL s'nta6, and substituted inside the
Re5uest string# +t ,or-s &i-e the 2ubst( /unction in this case# @sing the 7ind method a&&o,s
'ou to ,rite re5uests that are independent o/ the under&'ing database, meaning it ,i&& ,or-
,ith Postgre2HL or 1'2HL ,ithout an' code change re5uired#
0reate
>he Create method is used to bui&d a readM,rite Resu&t ob9ect ,hich can used to create
records in a tab&e# 2tandard ca&&ing convention isC
1U!C#I2! Create ( #able $S Strin5 ) $S 'es-lt
5dit
>he Edit method returns a readM,rite Resu&t ob9ect used /or editing records in the
speci/ied tab&e# 0e"uest is a 2HL <=ERE c&ause used /or /i&tering the tab&e, and the
)rguments are 5uoted as needed b' the 2HL s'nta6 and substituted in the Re5uest string as
,e e6p&ained previous&'# 2tandard ca&&ing convention isC
1U!C#I2! )it ( #able $S Strin5 " 0 'eI-est $S Strin50 $r5-ments $S 0 ... % ) $S 'es-lt
=ere is a code samp&e to sho, ho, Edit( ,or-sC
DIM My'es-lt $S 'es-lt
DIM sY-ery $S Strin5
DIM iParm $S Inte5er
sY-ery 6 ;Select L *rom tblD1$UL# Ahere i) 6 ;
T Ae Aill insert a parameter val-e (=B) at the en) o* the I-ery strin5
iParm 6 =B
[hConn.Be5in
My'es-lt6[hConn.)it(;tblD1$UL#;0 sY-ery0 iParm)
My'es-ltV!ame 6 ;Mr 'ittin5ho-se; T Set a *iel) val-e
[hConn.Up)ate T Up)ate Aith the neA val-e
[hConn.Commit T make the chan5es permanent
[hConn.Close T close the )atabase connection
333
5;ec
>he E6ec method e6ecutes a 2HL re5uest and returns a read4on&' Resu&t ob9ect
containing the resu&t o/ the re5uest# 2tandard ca&&ing convention isC
1U!C#I2! xec ( 'eI-est $S Strin50 $r5-ments $S 0 ... ) $S 'es-lt
0e"uest is a 2HL <=ERE c&ause and )rguments shou&d be 5uoted as re5uired b' 2HL
s'nta6#
1imit
>his method &imits the number o/ records returned b' the ne6t 5uer'#
A/ter the 5uer' is e6ecuted, the number o/ returned records is reset to un&imited# >his
method returns the connection it app&ies to, so that 'ou can ,rite something &i-e thatC
DB.Limit(7).xec(...)
Cuote
>he Huote method returns a 5uoted identi/ier 'ou can use to insert in a 2HL 5uer'#
>his identi/ier can be a tab&e or /ie&d name# 2'nta6 isC
1U!C#I2! Y-ote ( !ame $S Strin5 ) $S Strin5
>he 5uoting mechanism is dependent upon the particu&ar database server driver ,hich
ma-es this method necessar' i/ 'ou need to ,rite database4independent code# =ere is an
e6amp&e o/ ho, to use HuoteC
T 'et-rns n-mber o* recor)s in a I-erys DB#able
T is the name o* the table. Since the name can incl-)e reserve)
Tcharacters it nee)s to be s-rro-n)e) by I-ote marks
r'es-lt 6 [hConn.xec(;SLC# C2U!#(L) $S i!-m'ecs 1'2M ; S DB.Y-ote(sDB#able))
P'I!# r'es-ltVi!-m'ecs
7ubst
>he 2ubst method creates a 2HL sentence b' substituting its arguments in a /ormat
string# 2'nta6 isC
1U!C#I2! S-bst ( 1ormat $S Strin50 $r5-ments $S0 ... ) $S Strin5
!or"t is the 2HL sentence, and ,rgu"ents are the arguments to substitute# >he &1,
334
&2### patterns inside the 7ormat string are rep&aced b' respective&' the 2HL representation o/
the "st, ;nd### Arguments# >hese arguments are 5uoted according to the under&'ing database
2HL s'nta6# >he arguments are used in the same manner that the' are used in the 2ubstU
/unction, discussed in Chapter J#
7or e6amp&eC
P'I!# DB.S-bst(D+:' !ame 6 S= $!D Date 6 SBE0 DBenoitE0 !oA)
returns this outputC
+:' !ame 6 TBenoitT $!D Date 6 TB9==,9B,=C ==OC=O//.9@/T
#es-lt Ob6ects
>he resu&t ob9ect is a c&ass that is used to return the resu&t o/ a 2HL re5uest# >his c&ass
is not creatab&e and it acts 9ust &i-e a read4on&' arra'# +t is enumerab&e using the 7OR EAC=
statement# .ec&are and iterate a resu&t ob9ect as /o&&o,sC

DIM h'es-lt $S 'es-lt
12' $C: h'es-lt
T)o somethin5 Aith the )ata
!7#
>he code snippet be&o, sho,s ho, 'ou can get the va&ue o/ a /ie&d in the current record o/ a
Resu&t ob9ectC
DIM My(ariant $S (ariant
My(ariant 6 My'es-lt "1iel) $S Strin5%
>he Resu&t7ie&d c&ass represents one o/ the /ie&ds o/ a Resu&t ob9ect# Kou can use the
7ind method to se&ect a particu&ar /ie&d be/ore using it# >he properties this c&ass supports are
Length, :ame, Resu&t and >'pe# +t is a&so possib&e to enumerate the Resu&t7ie&d data ,ith the
7OR EAC= -e',ord# >his c&ass is not creatab&e# >he code be&o, sho,s 'ou ho, to modi/'
the va&ue o/ a /ie&d in the current record o/ a Resu&t ob9ectC
DIM My(ariant $S (ariant
My'es-lt "1iel) $S Strin5% 6 My(ariant
Properties that 'ou can use ,ith a resu&t ob9ect inc&ude Avai&ab&e, Connection, Count,
33#
7ie&ds, +nde6, Length and 1a6# Avai&ab&e ,i&& return a >R@E va&ue i/ the resu&t points to an
e6isting database record# Connection returns the parent connection ob9ect# Count te&&s 'ou
the number o/ records (ro,s returned ,ith the resu&t ob9ect# 7ie&ds returns a co&&ection o/ the
/ie&ds in the database tab&e returned ,ith the resu&t ob9ect# +nde6 returns the inde6 (current
ro, pointer or cursor o/ the current record, starting at 0ero# Length is the same as count and
is used interchangeab&'# 1a6 returns Resu&t#Count4"#
1ethods supported b' the resu&t ob9ect c&ass inc&ude .e&ete, 1ove7irst, 1oveLast,
1ove:e6t, 1ovePrevious, 1ove>o, and @pdate# 1ost o/ these are se&/4e6p&anator', but the
@pdate method is used to re,rite the current record to the database ,ith an' data changes
that are speci/ied# +/ 'ou use 1ove>o and speci/' an inde6 that is void or inva&id, it ,i&& return
a >R@E va&ue indicating an error# :o, that ,e have a basic understanding o/ ,hat a resu&t
ob9ect is and ho, to use it, &et's see ho, Gambas a&&o,s 'ou to /ind data in a database ,ith the
7ind method#
!+ C*ass
>his c&ass represents the current database connection# >his c&ass is static and a&& o/ its
members are a&so static# 1ost o/ the properties o/ this c&ass are the same as those o/ the
Connection c&ass so ,e ,i&& on&' cover those that are di//erent, name&' Current, .atabases,
and .ebug# Current returns or sets the current connection# .atabases returns a co&&ection o/
a&& o/ the databases that are managed b' the database server# .ebug sets or returns >R@E i/
the database component is in debugging mode# <hen the debug /&ag is set, each 5uer' sent to
an' database driver is printed on the standard error output (genera&&', the conso&e# >he
methods used in the .B c&ass are the same as those used in the Connection c&ass (Begin,
C&ose, Commit, Create, .e&ete, Edit, E6ec, 7ind, Limit, Open, Huote# Ro&&bac- and 2ubst so
,e ,on't repeat that in/ormation here#
!atabase
>he .atabase c&ass is used to represent in/ormation pertaining to a database# >his
c&ass is not creatab&e# >he properties that 'ou can use ,ith this c&ass inc&ude Connection,
:ame, and 2'stem# Connection can be used to obtain the parent connection ob9ect# :ame
,i&& return the name o/ the database and 2'stem ,i&& return a >R@E va&ue i/ the database is a
s'stem database# >he database c&ass on&' has one method, .e&ete, ,hich ,i&& de&ete a
database#
!atabase)ser
>he .atabase@ser c&ass is used to represent users o/ a database# >his c&ass is not
creatab&e# >he properties @ser c&ass supports are Administrator, Connection, :ame and
Pass,ord# Administrator is a read4on&' propert' that returns >R@E i/ a user is a database
administrator# Connection returns the parent connection ob9ect o/ the user# :ame ,i&& return
338
the name o/ the user and Pass,ord ,i&& get or set the pass,ord associated ,ith a user# <hen
'ou read the propert', 'ou shou&d get the pass,ord in an encr'pted /orm# >he .atabase@ser
c&ass has a sing&e method, .e&ete ,hich is used to de&ete a user /rom the database#
-ie*d
>he 7ie&d c&ass is used to represent data /or a tab&e /ie&d# >his c&ass is not creatab&e#
Properties that this c&ass supports are .e/au&t, Length, :ame, >ab&e, and >'pe# .e/au&t
returns the de/au&t va&ue o/ a /ie&d# Lentgh ,i&& return the ma6imum &ength o/ a te6t /ie&d# +/
the te6t /ie&d being chec-ed has no &imit speci/ied, a 0ero va&ue is returned# :ame ,i&& return
the /ie&d name and >ab&e returns the tab&e ob9ect in ,hich the /ie&d ,as created# >'pe returns
the datat'pe that the /ie&d represents# Gambas ,i&& return one o/ the /o&&o,ing constantsC
5b.Boolean0 5b.Inte5er0 5b.1loat0 5b.Date or 5b.Strin5
%nde
>he +nde6 c&ass represents a tab&e inde6# >his c&ass is not creatab&e# >he properties
this c&ass supports are 7ie&ds, :ame, Primar', >ab&e, and @ni5ue# 7ie&ds returns a comma4
separated &ist o/ strings representing the /ie&ds that ma-e up the inde6# :ame returns the
inde6 name ,hi&e Primar' ,i&& return a >R@E va&ue i/ an inde6 is the primar' inde6 o/ the
tab&e# >ab&e ,i&& return the tab&e ob9ect that o,ns this inde6# @ni5ue returns >R@E i/ the
inde6 is uni5ue#
Tab*e
>he >ab&e c&ass represents the de/inition o/ a database tab&e# >his c&ass is not creatab&e#
>he properties that are supported b' the >ab&e c&ass inc&ude Connection, 7ie&ds, +nde6es,
:ame, Primar'Ee', 2'stem and >'pe# Connection can be used to obtain the parent
connection ob9ect# 7ie&ds ,i&& return a co&&ection o/ the /ie&ds o/ the tab&e ,hi&e +nde6es ,i&&
return a co&&ection o/ the inde6es o/ the tab&e# :ame ,i&& return the name o/ the tab&e#
Primar'Ee' ,i&& return or set the primar' -e' o/ the tab&e# >he primar' -e' is a string arra'
containing the name o/ each primar' -e' /ie&d# 2'stem ,i&& return a >R@E va&ue i/ the
database is a s'stem database# >'pe returns or sets the t'pe o/ a tab&e# >his propert' is
uni5ue to 1'2HL and is on&' used ,ith 1'2HL databases# >his c&ass on&' has one method,
@pdate, ,hich is ca&&ed to actua&&' create the tab&e in the current&' connected database#
The !atabase Eamp*e Program
>he previous sections o/ this chapter have e6p&ained about the Gambas database
component and the /eatures provided therein# =o,ever, nothing substitutes ,or-ing ,ith
rea& code in a rea& app&ication# Gambas ships ,ith an e6amp&e database program ,ritten b'
Gambas /ounder Benoit 1inisini, and this program is an e6ce&&ent e6amp&e o/ ho, to code
33?
'our program to use database ,ithin the Gambas environment#
<e're going to ,or- ,ith a modi/ied version o/ this program named A.atabase"B, /ound
on the .!. that accompanies this boo-# >o begin, start Gambas and choose the .atabase"
program /rom the .!.# <hen the +.E appears, 'ou ,i&& see that the program contains t,o
/orms, 71ain and 7Re5uest# 71ain shou&d &oo- &i-e thisC
>his program ,i&& a&&o, 'ou to choose ,hat database p&at/orm to use (i#e#, Postgre2HL,
1'2HL, or 2HLite and speci/' the host name, database name, user +. and pass,ord# An
option to automatica&&' create a database e6ists and is activated ,henever the chec-bo6 is
chec-ed# Once 'ou have success/u&&' connected to the database, 'ou have the option o/
creating a tab&e, de&eting it, or /i&&ing it ,ith some test data# >he 2HL re5uest bo6 at the
bottom o/ the /orm ,i&& a&&o, 'ou to per/orm 2HL 5ueries against the database# A&& in a&&, this
program demonstrates a&most ever'thing 'ou need to -no, to connect to an' database using
Gambas# >he 7Re5uest /orm is much simp&er to bui&d# +t is sho,n in the /igure be&o,C
33%
Figure 11/: The F2ain (orm in "esign mo"e.
>he 7Re5uest /orm contains a sing&e contro&, ,hich ,e have not previous&' introduced, the
>ab&e!ie, contro&# >his contro& is /ound in the H> too&set ,e discussed previous&'# <e ,i&&
sho, 'ou ho, to use this contro& ,hen ,e discuss the 7Re5uest /orm code be&o,#
7or no,, &et's 9ump into the code /or the 71ain /orm and see ho, things ,or-#
T .ambas class *ile
;h,onn is dec&ared as a private variab&e and ,i&& be used b' a&& subroutines in this c&ass /i&e#
:ote that the variab&e is pre/i6ed ,ith a 7 s'mbo& to indicate it is a private c&ass variab&e#
<hi&e not re5uired, it is a good programming convention to /o&&o,#
P'I($# [hConn $S Connection
<henever the user has /i&&ed out the data at the top o/ the /orm ,ith their user name, host,
pass,ord, etc#, and c&ic-s the connect button, the program ,i&& come to this subroutine and
tr' to use that data to estab&ish a connection to the database#
PUBLIC SUB btnConnect8Click()
TAe nee) to have a strin5 to Aork Aith so )eclare s!ame as local
DIM s!ame $S Strin5
TnoA Ae 5et a little tricky. i* a )atabase Aas previo-sly opene)
Tan) is still open0 this next line Ao-l) close it. Usin5 #'W
TAo-l) alloA any error to be ca-5ht (see C$#C: beloA).
TI* there is not an open )atabase to close0 no harm Aas )one
Tan) the co)e exec-tion procee)s.
33+
Figure 110: FBe<uest Form in "esign mo"e.
#'W [hConn.Close
TAe assi5n the )ata in the #extbox txt!ame to o-r strin5 var s!ame
Tan) set the )atabase connection properties to the val-es provi)e)
Tby the -ser by -sin5 the +I#:M!D +I#: constr-ct.
s!ame 6 txt!ame.#ext
+I#: [hConn
.#ype 6 cmb#ype.#ext Tthe type o* )atabase plat*orm to -se
.:ost 6 txt:ost.#ext Thost name o* the )atabase
.Lo5in 6 txtUser.#ext TUS' ID
.PassAor) 6 txtPassAor).#ext TUS' passAor)
!D +I#:
Tat this point0 all the connection properties are set b-t
TAe have not opene) the connection yet. #he *olloAin5 co)e
Tse5ment Aill see i* a )atabase Aith the name speci*ie) by
Ts!ame exists an)0 i* not0 it Aill create it i* the checkbox to
Tcreate )atabase is checke).
I1 chkCreate.(al-e #:!
[hConn.2pen Topen the connection
Tsee i* a )atabase s!ame exists an) i* not0 a)) it to the server
I1 !2# [hConn.Databases.xist(s!ame) #:!
[hConn.Databases.$))(s!ame)
!DI1
TnoA close the connection
[hConn.Close
!DI1
TnoA0 Ae are rea)y to open the )atabase. ither it alrea)y existe)
Tan) Ae open that )atabase or Ae Aill open the neA one Ae create)
Ti* the checkbox Aas checke). 1irst0 set the !ame property *or the
Tconnection to s!ame an) then call the 2pen metho)O
[hConn.!ame 6 s!ame
[hConn.2pen
TAe set the enable) properties *or both pro5ram *orms to #'U
Tan) place some )e*a-lt text in the SYL reI-est box at the
Tbottom o* the 1Main *ormO
*rmDatabase.nable) 6 #'U
*rm'eI-est.nable) 6 #'U
340
txt'eI-est.#ext 6 ;S:2+ #$BLS;
Ti* o-r #'W *aile) or i* any error occ-rre) )-rin5 this s-bro-tine0
Tthe C$#C: statement Ao-l) )isplay an ''2' )ialo5 Aith the text o*
Tthe error messa5e. DConv Aill convert the system charset to U#1,?.
C$#C:
Messa5e.rror(DConvrror.#ext))
!D To* connectBtn8Click s-bro-tine
+/, a/ter the database connection is estab&ished, the user ,ou&d c&ic- the Create tab&e
AtestB button, this subroutine ,ou&d be e6ecuted#
PUBLIC SUB btnCreate8Click()
T)eclare a local #able variable
DIM h#able $S #able
Ta)) the table to the )atabase -sin5 the $)) metho)
h#able 6 [hConn.#ables.$))(txt!ame.text)
TnoA a)) the *iel)s o* the table to the table Ae 3-st a))e)
Tnote that Ae speci*y the *iel) name an) )ata type *or each
To* the *iel)s Ae insert into the table. 1or strin5 )ata0
TAe also speci*y the maxim-m len5th o* the strin5 *iel).
h#able.1iel)s.$))(;i);0 5b.Inte5er)
h#able.1iel)s.$))(;*irstname;0 5b.Strin50 =F)
h#able.1iel)s.$))(;name;0 5b.Strin50 /B)
h#able.1iel)s.$))(;birth;0 5b.Date)
h#able.1iel)s.$))(;active;0 5b.Boolean)
h#able.1iel)s.$))(;salary;0 5b.1loat)
TAe can speci*y a primary key *or the )atabase table. In this
Tcase0 the i) *iel) is -se) as Ae can create -niI-e inte5er in)ex
T)ata
h#able.PrimaryQey 6 ";i);%
Tthe call to the Up)ate metho) commits the chan5es to the )atabase
Tan) makes them permanent.
h#able.Up)ate
341
TnoA Ae p-t -p a simple )ialo5 to in*orm the -ser Ae have
Ts-ccess*-lly complete) the creation task.
Messa5e.In*o(;#able ; S txt!ame.#ext S ; has been create).;)
Tthis co)e enables or )isables the
Tb-ttons )epen)in5 on the state o* the )atabase. 1or example0
Ti* there is )ata alrea)y in the )atabase table0 it )oes not make
Tsense to *ill that table a5ain0 so that b-tton Ao-l) be )isable).
ThoAever0 the )elete b-tton Ao-l) be enable) so the )ata co-l) be
Tremove). I* the )atabase table is )elete)0 then it Ao-l) be
Tre,enable) an) i* the table is create) an) no )ata exists0
Tthe *ill b-tton Ao-l) a5ain be enable)0 etc. #his prevents errors
T*rom clickin5 on a b-tton Ahere an action co-l) not be per*orme)
Ts-ccess*-lly.
btn1ill.nable) 6 #'U
btnDelete.nable) 6 #'U
btnCreate.nable) 6 1$LS
Tnext0 Ae a)) some )e*a-lt text to the SYL I-ery box
txt'eI-est.#ext 6 ;ShoA #$BLS;
Tthe C$#C: statement Ao-l) )isplay an ''2' )ialo5 Aith the text o*
Tthe error messa5e i* any error occ-rs in this s-bro-tine.
C$#C:
Messa5e.rror(DConv(rror.#ext))
!D To* the create b-tton s-bro-tine
+/, a/ter the database connection is estab&ished, the user ,ou&d c&ic- the
.e&ete tab&e AtestB button, this subroutine ,ou&d be e6ecuted#
PUBLIC SUB btnDelete8Click()
Tremove the table

#'W [hConn.#ables.'emove(txt!ame.#ext)
Tp-t -p a messa5e to in*orm the -ser the table is 5one
Messa5e.In*o(;#able ;S txt!ame.#ext S ; has been remove);)
Tenable or )isable the b-ttons to make sense. I* the table
342
Thas been remove)0 it cannot be )elete) a5ain an) it cannot
Tbe *ille) since it )oes not exist. $ll that is le*t is to
Trecreate it an) that b-tton is enable).
btnDelete.nable) 6 1$LS
btn1ill.nable) 6 1$LS
btnCreate.nable) 6 #'U
Tno table exists to I-ery so blank o-t the SYL I-ery text.
txt'eI-est.#ext 6 ;;
Ti* an error occ-rs in the s-bro-tine catch it here an) shoA a )ialo5
Tmessa5e to the -ser.
C$#C:
!D Tthe )elete b-tton s-bro-tine
+/ the database connection has been estab&ished and the user has created the tab&e,
there needs to be some data added to ma-e it use/u&# >his subroutine is e6ecuted and ,i&& add
semi4arbitrar' data to the tab&e# +t ,i&& random&' se&ect a /irst name /rom the arra' o/ /ive
names provided and concatenate the counter number to the string A:ame ]B to serve as the
&ast name# >he birth date is created random&' b' pic-ing a va&ue that adds a random number
/rom "4"$,$$$ to the base date o/ %anuar' "
st
, ")J$# >he record has an active /&ag, random&'
set as ,e&&# 2a&ar' /igures are random&' se&ected ,ithin the range o/ ",$$$ to "$,$$$# 7ina&&',
the @pdate method ,i&& put a&& the data in the tab&e and ma-e the CO11+> to the database#
Let's &oo- at each &ine o/ code to see ho, eas' this is accomp&ished in GambasC
PUBLIC SUB btn1ill8Click()
TAe nee) an inte5er co-nter iIn) to be o-r in)ex an) Ae
Tnee) a 'es-lt ob3ect to store o-r res-lts
DIM iIn) $S Inte5er
DIM r#est $S 'es-lt
Tset the B-sy *la5 to prevent interr-ptions to o-r process
TAe are 5oin5 to start the )atabase transaction process Aith B.I!
[hConn.Be5in
Tcreate the )atabase table *irst
Tr#est 6 [hConn.Create(;test;)
r#est 6 [hConn.Create(txt!ame.#ext)

343
TnoA0 set -p a loop to create =99 recor)s
12' iIn) 6 = #2 =99
Tmake the recor) i) be the co-nter variable val-e
r#estVi) 6 iIn)
Tran)omly set the *irst name to be one o* the *ive in the array
r#estV*irstname 6 ";Pa-l;0;Pierre;0;4acI-es;0;$ntoine;0;Mathie-;%"Int('n)(C))%
Tmake the last name a catenate) val-e Aith the inte5er in)ex val-e
r#estVname 6 ;!ame <; S iIn)
Tran)omly choose a )ate by a))in5 a val-e *rom = Z =90999 to the
Tbase )ate o* 4an =0 =>X9
r#estVbirth 6 CDate(;9=M9=M=>X9;) H Int('n)(=9999))
Tset the active *la5 to either 9 or = (#'U or 1$LS)
r#estVactive 6 Int('n)(B))
Tran)omly choose a salary *i5-re *rom =0999 to =90999
r#estVsalary 6 Int('n)(=9990 =9999))
T-p)ate this recor) Aith the )ata semi,arbitrary )ata val-es
r#est.Up)ate
Tcommit all a))e) recor)s to the )atabase
[hConn.Commit
Tlast thin5 to exec-te be*ore leavin5 the s-bro-tine
1I!$LLW
T)ecrement the b-sy *la5
DC $pplication.B-sy
Tpop -p a messa5e to in*orm the -ser Ahat Ae )i)
Messa5e.In*o(txt!ame.#ext S ; has been *ille).;)
Tp-t a )e*a-lt SYL I-ery in the SYL Y-ery textbox
txt'eI-est.#ext 6 ;select L *rom ; S txt!ame.#ext
T*ix o-r b-ttons to make sense
btn1ill.nable) 6 1$LS
btnDelete.nable) 6 #'U
btnCreate.nable) 6 1$LS
344
Ti* somethin5 5oes Aron50 abort all chan5es Aith the 'ollback an)
TshoA the error messa5e to the -ser
C$#C:
[hConn.'ollback
!D To* the *ill )ata s-bro-tine
+/ the user enters an arbitrar' 2HL re5uest in the 2HL 5uer' bo6 at the bottom o/ the
/orm, ,e ,i&& use the E6ec method to per/orm the 5uer' and disp&a' the resu&ts o/ the re5uest
using the 7Re5uest /orm# =ere is ho, that is doneC
PUBLIC SUB btn'-n8Click()
T)eclare a res-lt ob3ect to hol) the res-lts o* the I-ery
DIM rData $S 'es-lt
T)eclare a *orm variable so Ae can shoA the 1'eI-est *orm
DIM h1orm $S 1'eI-est
Texec-te the I-ery -sin5 the xec metho) an) assi5n the res-lts to
Tthe res-lt ob3ect rData
rData 6 [hConn.xec(txt'eI-est.#ext)
Tpass the )atabase connection han)le an) the res-lt )ata to the
T1'eI-est *orm Ahen it is instantiate)
h1orm 6 !+ 1'eI-est([hConn0 rData)
TnoA )isplay the *orm to the -ser Aith the res-lt )ata
h1orm.ShoA
Tcome here i* there is a problem in the s-bro-tine an) )isplay a ms5
C$#C:
!D To* sIl I-ery s-bro-tine
<henever our program runs and the 71ain /orm opens, ,e need to instantiate our
connection variab&e UhConn# <henever the /orm is c&osed, ,e ,i&& c&ose the connection#
[hConn 6 !+ Connection
!D
PUBLIC SUB 1orm8Close()
34#
[hConn.Close
!D
:e6t, ,e need to ta-e a &oo- at the 7Re5uest /orm and see ho, that code disp&a's the resu&t
ob9ect data ,hen it is invo-ed# =ere is the code /or thatC
T .ambas class *ile
T *'eI-est.class )eclares tAo private variables to -se in this class
T one *or the connection0 one *or the res-lt )ata.
P'I($# [hConn $S Connection
P'I($# [rData $S 'es-lt
Ta constr-ctor ro-tine Aill be -se) to receive the connection han)le Tan) the res-lts o* a I-ery as parameters Ahen
1'eI-est is calle) by
Tthe 1Main *orm.
PUBLIC SUB 8neA(hConn $S Connection0 rData $S 'es-lt)
Tassi5n the hConn parameter to o-r private [hConn variable
[hConn 6 hConn
Tassi5n the rData parameter to o-r [rData private variable
Tthese assi5nments are ma)e so the [ pre*ixe) variables are
Tvisible to the entire class0 not 3-st the constr-ctor ro-tine.
[rData 6 rData
Tcall o-r little s-bro-tine to )isplay the title in the *orm Ain)oA
'e*resh#itle
Tthe 'ea)Data s-bro-tine is -se) to pop-late o-r #able(ieA control
'ea)Data
TresiRe the Ain)oA to center on the )esktop
M.Move(Int('n)(Desktop.+ , M.+))0 Int('n)((Desktop.: , M.:))))
!D To* the constr-ctor
Tthis s-bro-tine simply -p)ates the Ain)oA caption
P'I($# SUB 'e*resh#itle()
TAe nee) a local strin5 variable
DIM s#itle $S Strin5
TAe Aill concatenate the connection name to the text *or the caption
s#itle 6 (;SYL Y-ery 'es-lts ;) S ; , ; S [hConn.!ame
348
Tan) set the title property to be the strin5 variable val-e
M.#itle 6 s#itle
!D
>he Read.ata( subroutine is used to de/ine the structure o/ the data passed in /rom
the resu&ts ob9ect to the >ab&e!ie, contro&# +t determines the number o/ /ie&ds /rom the
resu&ts ob9ect and sets up the co&umns in the tab&e, assigning the proper co&umn (/ie&d name
and data t'pe# >he data t'pe is determined b' ca&&ing another subroutine, <idth7rom>'pe(
to get that in/ormation#
>he Ht &ibrar'4based >ab&e!ie, contro& is obso&ete in the Ht &ibrar', having been
rep&aced ,ith the H>ab&e contro&# =o,ever, Gambas has added its o,n >ab&e!ie, contro&, so
it is sti&& usab&e and ,e ,i&& sho, 'ou ho, it is done#
P'I($# SUB 'ea)Data()
Tthis variable is )eclare) b-t never -se)0 yo- can comment it o-t
DIM h#able $S #able
DIM h1iel) $S 'es-lt1iel)
DIM iIn) $S Inte5er
Tset the application b-sy *la5 to avoi) interr-ptions
Treset roA co-nt o* the #able(ieA control to Rero
tbvData.'oAs.Co-nt 6 9
Tset the n-mber o* col-mns to be the same n-mber
T as the n-mber o* *iel)s in the res-lt ob3ect
tbvData.Col-mns.Co-nt 6 [rData.1iel)s.Co-nt
TnoA Ae Aill iterate thro-5h each *iel) o* the res-lt ob3ect an)
T5et the name o* the *iel) an) the )ata type an) set the #able(ieA
Tcol-mn hea)in5s an) *iel) typeMsiRe as appropriate
12' $C: h1iel) I! [rData.1iel)s
+I#: h1iel)
Tthis is a )eb-5 line that Aas commente) o-t
TP'I!# .!ameG ;O ;G .#ypeG ; ;G .Len5th
Tthis next line sets the col-mn name to be the *iel) name
tbvData.Col-mns"iIn)%.#ext 6 .!ame
34?
There0 the call to +i)th1rom#ype is -se) to )etermine Ahat )ata
Ttype the *iel) is an) Ahat the appropriate Ai)th sho-l) be
tbvData.Col-mns"iIn)%.+i)th 6 +i)th1rom#ype(tbvData0 .#ype0 .Len5th0 .!ame)
!D +I#:
Tincrement o-r in)ex co-nter
I!C iIn)
!7# Titeration o* res-lt )ata
Tset the n-mber o* #able(ieA roAs to be the same as the n-mber
To* roAs o* )ata in the res-lt ob3ect
tbvData.'oAs.Co-nt 6 [rData.Co-nt
Tlast thin5 Ae )o in this s-bro-tine is )ecrement the b-sy *la5
1I!$LLW
DC $pplication.B-sy
Ti* there Aere any errors in this s-bro-tine Ae Ao-l) shoA a messa5e
C$#C:
Messa5e.rror(;Cannot exec reI-est.; S ;NnNn; S rror.#ext)
!D To* 'ea)Data s-bro-tine
>he ne6t bit o/ code is activated ,henever data is present# >he -ata event o/ the
>ab&e!ie, contro& is used as the driver /or activation o/ this subroutine# +t inserts a ro, o/
data /rom the resu&ts ob9ect into the current ro, and co&umn o/ the >ab&e!ie, contro&# Bear
in mind that 'ou don't ever ca&& the data event direct&'# >here is ver' &itt&e documentation
avai&ab&e /or the >ab&e!ie, contro& so nothing stated herein shou&d be considered as the
de/initive ans,er /or using it# =o,ever, the genera& approach to using the >ab&e!ie, contro&
is to /irst &oad a&& data that is to be disp&a'ed into an arra' and prepare the >ab&e!ie, contro&
,ith ro,s and co&umns as ,as done in the Read.ata subroutine above#
>he ver' process o/ /i&&ing the arra' and de/ining the co&umns in this manner /orces the
,idget that is used in the >ab&e!ie, contro& to ma-e an interna& ca&& to the -ata event that
actua&&' does /i&& the ce&&s ,ith data /rom 'our arra'# It is up to you to code the assignment
statement(s that move data /rom the resu&ts ob9ect to the >ab&e!ie, ro, and co&umn ,here
'ou ,ant the data disp&a'ed# >he -e' thing to remember is that 'ou must have an event
hand&er, tbvControl=-ata( ... ) some,here in 'our c&ass /i&e to do this# +n a >ab&e!ie,
contro&, the data that is re/reshed is on&' ,hat is visib&e in the contro&# >he contro& can disp&a'
a huge amount o/ data ,ithout ho&ding an' o/ the data va&ues direct&' in storage itse&/# >hat is
,hat 'our program arra' is used /or# <hi&e it sounds a bit a,-,ard, it is a pragmatic so&ution
that a&&o,s Gambas to disp&a' data /rom a database in a prett' e//icient manner#

PUBLIC SUB tbvData8Data('oA $S Inte5er0 Col-mn $S Inte5er)
Tthis 5ets to the correct roA
[rData.Move#o('oA)
34%
Tthis act-ally assi5ns )ata *rom the res-lts ob3ect to the tablevieA
tbvData.Data.#ext 6 Str([rData"tbvData.Col-mns"Col-mn%.#ext%)
!D
+/ the /orm is resi0ed b' the user, ,e need to resi0e the contro&# >his subroutine ,i&& do the
tric-#
PUBLIC SUB 1orm8'esiRe()
tbvData.'esiRe(M.Client+0 M.Client:)
!D
<hen data is being read /rom the resu&ts ob9ect, this subroutine is ca&&ed to determine
,hat the data t'pe is /or each /ie&d o/ a ro,# >he properties /rom the 7ie&d c&ass are passed as
parameters to this /unction and used in the se&ect statement# >his ensures the data p&aced in
the individua& ce&&s o/ the >ab&e!ie, contro& is not truncated and ,i&& disp&a' proper&',
regard&ess o/ the /ont propert' setting estab&ished b' the >ab&e!ie, contro& itse&/#
P'I($# 1U!C#I2! +i)th1rom#ype(hCtrl $S control0 i#ype $S Inte5er0 iLen5th $S Inte5er0 s#itle $S Strin5) $S Inte5er
DIM i+i)th $S Inte5er
SLC# C$S i#ype
C$S 5b.Boolean
i+i)th 6 hCtrl.1ont.+i)th(Str(1$LS)) H /B
C$S 5b.Inte5er
i+i)th 6 hCtrl.1ont.+i)th(;=B/@CFX?>9;) H =F
C$S 5b.1loat
i+i)th 6 hCtrl.1ont.+i)th(CStr(Pi) S ;H>>>;) H =F
C$S 5b.Date
i+i)th 6 hCtrl.1ont.+i)th(Str(!oA)) H =F
C$S 5b.Strin5
I1 iLen5th 6 9 #:! iLen5th 6 BCC
iLen5th 6 Min(/B0 iLen5th)
i+i)th 6 hCtrl.1ont.+i)th(;7;) L iLen5th H =F
!D SLC#
i+i)th 6 Max(i+i)th0 hCtrl.1ont.+i)th(s#itle) H ?)
'#U'! i+i)th
!D
34+
7ina&&', i/ the user c&ic-s on the A6B at the top right corner o/ the ,indo, to c&ose the program,
,e come to this routine and c&ose things do,n#
PUBLIC SUB 1orm8Close()
M.Close
!D
<hen 'ou e6ecute the e6amp&e .atabase program, it re5uires that 'ou have a database
s'stem &i-e Postgre2HL or 1'2HL insta&&ed on 'our s'stem# Kou must have a user account
and pass,ord to use the database s'stems# Given those caveats, run the program and &og into
the database# Kou can p&a' around, create and /i&& the test tab&e, and ma-e 5ueries ,ith the
program# At this point, 'ou have &earned a&& the basics /or connecting to and using a database
in Gambas# +n the ne6t chapter, ,e ,i&& cover the essentia&s o/ ma-ing 'our program avai&ab&e
to users g&oba&&', a process ca&&ed internationa&i0ation (+"*:#
3#0
Chapter 16 Global Gambas
Gambas has been designed /rom the ver' beginning to support an internationa&
communit'# Being an open source product, peop&e /rom ever',here on the p&anet participate
in the ongoing care and deve&opment o/ the Gambas product# >he abi&it' Gambas provides to
deve&opers to create a sing&e code4base that ,i&& satis/' users /rom ever' countr' is a
signi/icant step in the recognition o/ a g&oba& communit'# Gambas a&&o,s deve&opers to ,rite
programs that are easi&' trans&ated to near&' an' &anguage, ,ithout having to re,rite code and
,ithout having to hire an e6pensive outsource /irm to do the 9ob# >he processes o/
.nternationali6ation and 7ocali6ation are signi/icant&' enhanced b' the Gambas approach#
>he /o&&o,ing sections ,i&& provide an overvie, that ever' Gambas deve&oper shou&d be a,are
o/ in order to product g&oba&&'4acceptab&e code# <e are, o/ course, a&& /rom one p&anet and
shou&d a&,a's consider the imp&ications o/ ,hat ,e p&ace in an open4source communit'#
%nternationa*i=ation
*nterntionli<tion is the process o/ designing an app&ication so that it can be
adapted to various &anguages and regions ,ithout engineering changes# 2ometimes the term
internationa&i0ation is abbreviated as i"*n, because there are "* &etters bet,een the /irst 3i3
and the &ast 3n#3 An internationa&i0ed program, ,ith the addition o/ &oca&i0ed data, can use the
same e6ecutab&e ,or&d,ide# >e6tua& e&ements, such as status messages and the G@+
component &abe&s, are not hard4coded in the program# +nstead the' are stored outside the
source code and retrieved d'namica&&'# 2upport /or ne, &anguages does not re5uire
recompi&ation# Cu&tura&&'4dependent data, such as dates and currencies, appear in /ormats
that con/orm to the end user's region and &anguage# +t can be locali6ed 5uic-&'#
&oca*i=ation
)ocli<tion is the process o/ adapting so/t,are /or a speci/ic region or &anguage b'
adding &oca&e4speci/ic components and trans&ating te6t# >he term &oca&i0ation is o/ten
abbreviated as &"$n, because there are "$ &etters bet,een the 3&3 and the 3n#3 @sua&&', the most
time4consuming portion o/ the &oca&i0ation phase is the trans&ation o/ te6t# Other t'pes o/
data, such as sounds and images, ma' re5uire &oca&i0ation i/ the' are cu&tura&&' sensitive#
Loca&i0ers a&so veri/' that the /ormatting o/ dates, numbers, and currencies con/orms to &oca&
re5uirements#

)niversa* Character ,et /)C,0
+2OM+EC "$I(I de/ines a ver' &arge character set ca&&ed the @niversa& Character 2et
(@C2, ,hich encompasses most o/ the ,or&d's ,riting s'stems# >he same set o/ characters is
a&so de/ined b' the @nicode standard# >o date, changes in @nicode and amendments and
additions to +2OM+EC "$I(I have been made in unison so that the character repertoires and
3#1
code point assignments have sta'ed s'nchroni0ed# >he re&evant standardi0ation committees
have committed to maintain this ver' approach#
Both (C$ and (nicode are code tab&es that assign an integer va&ue to a character#
>here are severa& a&ternatives /or ho, a string o/ such characters (or their integer va&ues can
be represented as a b'te se5uence# >he t,o most obvious encoding /orms store @nicode te6t
as se5uences o/ either ; or ( b'tes# >hese encoding schemes are designated as @C24; and
@C24(# +n both o/ these schemes, the most signi/icant b'te comes /irst (Big Endian /ormat#
>he @nicode characters are identi/ied b' number or Acode pointB, usua&&' given in
he6adecima&, so /or e6amp&e the =ebre, &etter AheB is G.(, usua&&' ,ritten @F$G.(#
@nicode current&' de/ines 9ust under "$$,$$$ characters, but has space /or ",""(,"";
code points# >he code points are organi0ed into "J Ap&anesB o/ ;"I (IG,GDI characters,
numbered $ through "I# P&ane $ is ca&&ed the ABasic 1u&ti&ingua& P&aneB or B1P and contains
s'mbo&s /ound to be use/u&# Genera&&' spea-ing, it contains ever' character avai&ab&e to a
programmer be/ore @nicode came a&ong#
>he characters in the B1P are distributed in a A<est to EastB /ashion, ,ith the A2C++
characters having their /ami&iar A2C++ va&ues /rom $ to ";J, the +2O4Latin4" characters
retaining their va&ues /rom ";* to ;GG# >hen, the character sets move east,ard across Europe
(Gree-, C'ri&&ic, on to the 1idd&e East (Arabic, =ebre,, across +ndia and on to 2outheast
Asia, ending up ,ith the character sets /rom China, %apan, and Eorea (C%E# Be'ond this
B1P e6ists p&anes " through "I# >he' are sometimes re/erred to as the Aastral planesB
because the' are t'pica&&' used /or e6otic, rare, and historica&&' important characters#
A2C++ /i&es can be converted into a @C24; /i&e b' inserting $6$$ in /ront o/ ever' A2C++
b'te# >o ma-e a @C24( /ormatted /i&e, 'ou must insert three $6$$ b'tes be/ore ever' A2C++
b'te# @sing either @C24; or @C24( on @ni6 p&at/orms can &ead to some ver' signi/icant
prob&ems# 2trings used ,ith these encoding schemes can contain parts o/ man' ,ide character
b'tes &i-e AT$B or AMB that have specia& meaning in /i&enames and other C &ibrar' /unctions#
>he vast ma9orit' o/ @:+Q too&s e6pect to operate ,ith A2C++4based /i&es and simp&' cannot
read "I4bit ,ords as characters# 2imp&' put, @C24;M@C24( are not suitab&e /or @ni6 ,hen
used ,ith /i&enames, te6t /i&es, environment variab&es, code &ibraries, etc#
>here are severa& other encoding /orms common to both @C2 and @nicode, name&'
@>74*, @>74"I, and @>74D;# +n each o/ these encoding /ormats, each character is
represented as one or more encoding units# A&& standard @C2 encoding /orms e6cept @>74*
have an encoding unit &arger than one octet#
7or man' app&ications and protoco&s, an assumption o/ an *4bit or J4bit character set
ma-es the use o/ an'thing other than @>74* near&' impossib&e# 2ince @>74* has a one4octet
encoding unit, it uses a&& bits o/ an octet but can sti&& contain the /u&& range o/ @24A2C++
characters, a&& o/ ,hich happen to be encoded in a sing&e octet# An' octet ,ith such a va&ue
can on&' represent a @24A2C++ character#
3#2
)T-3F
@>74* ,as invented b' Een >hompson
"*
# According to the stor' b' Rob Pi-e ,ho ,as
,ith Een at the time, it ,as deve&oped during the evening hours o/ 2eptember ;
nd
in ")); at a
:e, %erse' diner# Een designed it in the presence o/ Rob Pi-e on a p&acemat (see Rob Pi-ebs
@>74* histor'
")
# >he ne, design rep&aced an ear&ier attempt to design a 7i&e 2'stem 2a/e
@C2 >rans/ormation 7ormat (722M@>7 that ,as circu&ated in an QMOpen ,or-ing document
in August o/ the same 'ear b' Gar' 1i&&er (+B1, Greger Lei9onhu/vud and %ohn Entenmann
(21+ as a rep&acement /or the division4heav' @>74" encoding presented in +2O "$I(I4"
;$
#
<ithin a ,ee-'s time in 2eptember "));, Pi-e and >hompson made A>P> Be&& Labbs P&an )
the /irst operating s'stem in the ,or&d to use @>74* encoding# >he' reported this at the
@2E:+Q <inter "))D >echnica& Con/erence
;"
# 722M@>7 ,as brie/&' a&so re/erred to as @>74;
and &ater renamed @>74* and pushed through the standards process b' the QMOpen %oint
+nternationa&i0ation Group QO%+G#
@>74* encodes @C2 characters as a var'ing number o/ octets# >he number o/ octets
and the va&ue o/ each depend on the integer va&ue assigned to the character in +2OM+EC "$I(I
(the character number, a.&.a., it$s code position, code point or :nicode scalar value# >his
encoding /orm has the /o&&o,ing characteristics
;;
(va&ues in he6adecima&C
Character numbers /rom @F$$$$ to @F$$J7 (@24A2C++ set correspond to octets $$
to J7 (J bit @24A2C++ va&ues# A direct conse5uence is that a p&ain A2C++ string is a&so a
va&id @>74* string#
@24A2C++ octet va&ues do not appear other,ise in a @>74* encoded character stream#
>his provides compatibi&it' ,ith /i&e s'stems or other so/t,are (e#g#, the print/(
/unction in C &ibraries that parse based on @24A2C++ va&ues but are transparent to
other va&ues#
Round4trip conversion is eas' bet,een @>74* and other encoding /orms#
>he /irst octet o/ a mu&ti4octet se5uence indicates the number o/ octets in the se5uence#
>he octet va&ues C$, C", 7G to 77 never appear#
Character boundaries are easi&' /ound /rom an',here in an octet stream#
>he b'te4va&ue &e6icographic sorting order o/ @>74* strings is the same as i/ ordered b'
character numbers# O/ course this is o/ &imited interest since a sort order based on
character numbers is a&most never cu&tura&&' va&id#
>he Bo'er41oore /ast search a&gorithm can be used ,ith @>74* data#
@>74* strings can be /air&' re&iab&' recogni0ed as such b' a simp&e a&gorithm, i#e#, the
probabi&it' that a string o/ characters in an' other encoding appears as va&id @>74* is
&o,, diminishing ,ith increasing string &ength#
1% httpG99www.cs.bell-labs.com9who9ken9
1+ httpG99www.cl.cam.ac.uk9Smgk2#9ucs9ut>-%-histor*.t2t
20 httpG9984.233.18?.1049searchT
ENcacheG,4D(?dcaE0!UGwww.>aEs.org9>tp9r>c9pd>9r>c22?+.t2t.pd>MGregerM'eiFonhu>"udVhlNen
21 ,/!7I; Technical Con>erence held in /an $iego) CA) Uanuar* 2#-2+) 1++3) published in the Con>erence roceedings)
pp. 43-#0.
22 /ee ,6' httpG99www.>aEs.org9r>cs9r>c22?+.html.
3#3
>he (&!.S encoding is /orma&&' de/ined in +2O "$I(I4"C;$$$ Anne6 .# +t is a&so
described in R7C DI;) as ,e&& as section D#) o/ the @nicode (#$ standard# +n order to use
@nicode under @ni64st'&e operating s'stems, @>74* is the best encoding scheme to use# >his
is because @C2 characters @F$$$$ to @F$$J7 (A2C++ are encoded as b'tes $6$$ to $6J7
(/or A2C++ compatibi&it'#
>his means /i&es and strings that contain on&' J4bit A2C++ characters ,i&& have the same
encoding under both A2C++ and @>74*# A&& @C2 characters that /a&& in the range greater than
@F$$J7 are encoded as a mu&ti4b'te se5uence, each o/ ,hich has the most signi/icant bit set#
>here/ore, no A2C++ b'te ($6$$4$6J7 can appear as part o/ an' other character#
>he /irst b'te o/ a mu&ti4b'te se5uence that represents a non4A2C++ character ,i&&
a&,a's /a&& in the range o/ $6C$ to $67. and it indicates ho, man' b'tes ,i&& /o&&o, /or this
character# An' /urther b'tes in a mu&ti4b'te se5uence ,i&& be in the range /rom $6*$ to $6B7#
>his a&&o,s eas' res'nchroni0ation and ma-es encoding state&ess and robust against missing
b'tes# A&& possib&e ;D" @C2 codes can be encoded#
@>74* encoded characters ma' theoretica&&' be up to si6 b'tes &ong# >he sorting order
o/ Big Endian @C24( b'te strings is preserved# >he b'tes $67E and $677 are never used in
the @>74* encoding# >he /o&&o,ing b'te se5uences are used to represent a character# >he
se5uence to be used depends on the @nicode number o/ the characterC
U-00000000 U-0000007F: 0xxxxxxx
U-00000080 U-000007FF: 110xxxxx 10xxxxxx
U-00000800 U-0000FFFF: 1110xxxx 10xxxxxx 10xxxxxx
U-00010000 U-001FFFFF: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
U-00200000 U-03FFFFFF: 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
U-04000000 U-7FFFFFFF: 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
>he 666 bit positions are /i&&ed ,ith the bits o/ the character code number in binar'
representation# >he rightmost 6 bit is the &east4signi/icant bit# On&' the shortest possib&e
mu&ti4b'te se5uence ,hich can represent the code number o/ the character can be used#
Note that in multi-byte sequences, the number of leading 1 bits in the first byte is identical to the number of
bytes in the entire sequence.
$ow to trans*ate in Gambas
>o trans&ate Gambas into 'our o,n &anguage, open the Gambas pro9ect in the +.E, and
c&icon >rans&ate### in the Pro9ect menu, as sho,n in the /igure be&o,C
3#4
:e6t, 'ou must se&ect the target trans&ation &anguage in the combo4bo6 o/ the trans&ate
dia&og bo6, as sho,n be&o,# C&icon A:e,B and choose Esperanto (An',hereSC
2e&ect a string /rom the &ist o/ untrans&ated strings and enter its trans&ation in the te6t
/ie&d sho,n at the bottom o/ the dia&og# Kou need to repeat this process unti& ever' string in
'our app&ication has been trans&ated# <hen 'ou have /inished, c&icon the C&ose button# +t is
not necessar' to comp&ete a&& o/ the strings at one sitting# Kou can trans&ate the pro9ect in
3##
Figure 111: The Translate ,ialog in Gambas.
Figure 111: hoosing the Translate option
in Gambas.
severa& attempts# >he too&bar icons 'ou see at the top o/ the >rans&ate dia&og a&&o, 'ou toC
2ave the current trans&ation#
Re&oad the current trans&ation (:oteC an' changes are &ost ,hen 'ou re&oad#
.e&ete the current trans&ation#
.up&icate an e6isting trans&ation#
E6port the current trans&ation to a .po /i&e#
1erge a trans&ation /i&e#
!eri/' a trans&ation b' chec-ing to see i/ ever' s'mbo& character is preserved#
>here are certain occasions ,here 'ou ma' not ,ant to ever trans&ate a string# +n
Gambas, 'ou can indicate a string shou&d not be trans&ated b' entering a minus sign character
as the trans&ated string# Kour trans&ation is stored in a H.po /i&e in the .lang director' o/ the
pro9ect# >he name o/ the .po /i&e depends on the &anguage trans&ated# 7or e6amp&e, the
7rench trans&ation /i&e is named /r#po#

<henever the &atest Gambas version changes, an' un4trans&ated strings in 'our
program cou&d change# =o,ever, an' strings 'ou have trans&ated ,i&& be preserved# +/ an un4
trans&ated string disappears comp&ete&', the trans&ation ,i&& a&so disappear and i/ a ne, un4
trans&ated string is added, it gets an empt' or nu&& trans&ation string assigned to it# A&& other
un4trans&ated strings ,i&& -eep their corresponding trans&ation strings# <hi&e the string
trans&ation /eature o/ Gambas a&&o,s 'ou to easi&' maintain string conversions, other &oca&e
speci/ic things such as dates, number /ormats, etc# are &e/t to 'ou to manage# +t is hoped that
Gambas; ,i&& address these /eatures ,hen it is re&eased# @nti& that time arrives, here is a
short, genera&i0ed chec-&ist /or he&ping 'ou &oca&i0e 'our app&icationC
Ensure a&& messages, icons, and human readab&e content are stored in e6terna&
resource /i&es and can be easi&' trans&ated#
>he trans&ated message or resource /i&es shou&d be d'namica&&' &oaded b' the
app&ication, depending on the current &anguage and &oca&e settings /or the session#
.ateMtime, sort order, numeric and monetar' /ormatting etc# are in the target &anguage#
>he sort order shou&d be con/igurab&e, depending on the &anguage o/ the user#
>arget &anguage characters can be correct&' entered and disp&a'ed b' the user and the'
can be read /rom and ,ritten to the native /i&e s'stem o/ the target p&at/orm#
According to =uang et# a&#,
;D
'ou shou&d consider creating an +"*: testing chec-&ist /or
'our app&ication# 2ome o/ the 5uestions the' recommend 'ou consider inc&ude the /o&&o,ingC
.oes the program design account /or internationa& considerationsN
Can users enter te6t, acce&eratorsMshortcut4-e' combinations on an internationa&
-e'boardN
Can a user enter dates, times, currencies, and numbers using internationa& /ormatsN
23 .uang) !.) .a>t) 6. and .su) U. O$e"eloping a 6oadmap >or /o>tware InternationaliDationP) -hitepaper dated 1ctober
2000) retrie"ed >rom,6' www.s*mbio-group.com9doc9$e"eloping a 6oadmap >or /o>tware InternationaliDation.pd> on
# 1ct 0#.
3#8
Can a user success/u&&' cutMpaste te6t ,ith accented (or doub&e4b'te charactersN
Can the app&ication ,or- correct&' on di//erent t'pes o/ hard,are so&d in the target
mar-etN
.oes the app&ication ,or- correct&' on &oca&i0ed operations s'stemsN
Can users t'pe European accented (or doub&e4b'te characters in documentsMdia&og
bo6esN
Can documents created in a target &anguage be opened in other &anguages and vice4
versaN
Can users saveMprint /i&es ,ith accented (or doub&e4b'te charactersN
<hi&e there is no sing&e chec-&ist that can account /or the ,ide degree o/ variation /rom
app&ication to app&ication, consideration o/ these basic issues ,i&& &i-e&' go /ar in he&ping 'ou
to reach a g&oba& audience# >he +nternet has made the ,or&d a much sma&&er p&ace and the
audience /or app&ications have become much &arger# Kou cannot simp&' assume ever'one
using 'our app&ication is Eng&ish4spea-ing and uses the same -e'board or ,i&& understand
'our icons# .i//erent pictograms mean di//erent things depending on the &oca&e in ,hich 'our
user resides# 1ost important o/ a&&, ma-e the e//ort to accommodate the broadest audience
possib&e and 'our users ,i&& most &i-e&' a&&o, /or a /e, mista-es here and there# :ot ma-ing
such an e//ort ,i&& genera&&' &eave them ,ith the impression that 'ou cou&d care &ess and the'
,i&& probab&' /ee& the same ,a' about using 'our program#
3#?
Alphabetical Index
Add method..........................................................%?
A7$ operator.......................................................38
arithmetic operators..............................................30
assignment statement...........................................30
:ackground propert*......................................81) 88
:oolean data-t*pes...............................................2#
:order propert*....................................................82
buil.......................................................................2+
:*te data-t*pe......................................................28
Cancel button.......................................................#+
Cancel propert*....................................................82
Caption propert*............................................82) ?+
CA/! !'/! block...............................................4+
CA/! statement...................................4%) 102) 113
CATC. statement..............................................30#
Check:o2 class....................................................+1
Check:o2 control.............................................+0p.
Checked propert*.................................................+%
ChrI+J..............................................................13#p.
class e"ent..........................................................310
class hierarch*......................................................22
Click e"ent...........................................................?4
Collections...........................................................##
Combo:o2 arra*s................................................%?
Combo:o2 control............................................%4p.
Combo:o2 items.................................................%?
comparison operators...........................................30
conditionals..........................................................4#
Conditionals.........................................................4#
Constant...............................................................2%
Container class.....................................................80
Control class.........................................................#+
Control Groups.....................................................+?
controls.................................................................#?
cop*right notice......................................................2
Cop*right 7otice................................................1p.
Cursor propert*....................................................83
date data-t*pe.......................................................2?
$ate data-t*pe......................................................2?
$blclick e"ent.....................................................?8
$!C operator.......................................................3%
$e>ault button......................................................#+
$e>ault propert*...................................................84
$elete method......................................................8%
$esign propert*....................................................84
$esktop.Charset.................................................141
$ialog class........................................................101
$ialog Title propert*..........................................102
di"ision b* Dero.................................................34p.
$i"ision b* Kero..................................................38
$1 <-.I'!= '11............................................#0
dot notation..........................................................30
double-click e"ent................................................?8
$rag method.........................................................8%
$rop propert*.......................................................84
!nabled propert*..................................................8#
!7$ ke*word......................................................33
!7$ -IT. instruction........................................30
!nter e"ent...........................................................?2
!rror management..............................................300
!rror.Class propert*...........................................30#
!rror.Clear..........................................................30#
!rror.Code propert* ..........................................30#
!rror.6aise.........................................................30#
!rror.Te2t propert*............................................30#
!rror.-here propert*.........................................30#
e"ent dri"en language..........................................4#
e"ent handler........................................................?8
e"ent-dri"en programming.................................310
e"ent-dri"en s*stem...........................................310
!2pand propert*...................................................8#
5inall*................................................................308
>loat data-t*pe......................................................28
5loat data-t*pe......................................................28
>ocus control.........................................................8+
5ont class......................................................10?pp.
5ont propert*........................................................8#
516 !AC...........................................................#0
516 !AC. construct .........................................##
516 statement.............................................4+p.) ##
5oreground propert*............................................8#
5rame class...........................................................%+
3#%
Gambas component librar*..................................%%
Gambas constants.................................................2%
Gambas Constants................................................2+
Gambas data-t*pes.........................................24) 2%
Gambas $e"elopment !n"ironment....................84
Gambas I$!.........................................................#?
Gambas Interpreter...............................................14
GA@:A/ interpreter.........................................141
Gambas ke*words................................................4#
Gambas Tool:o2.................................................#?
Gambas -iki........................................................14
G1T1 instruction................................................4+
Grab method.........................................................8%
Graphical ,ser Inter>ace classes..........................#?
GT4M...................................................................1#
GT4M#.................................................................14
. propert*............................................................88
.andle propert*....................................................88
handles.................................................................80
.eight propert* ...................................................88
.ide method.........................................................8%
./( >unction.......................................................81
html......................................................................8%
.T@'.......................................................1+) ?%pp.
.ungarian 7otation..............................................28
I5 statement....................................................48) +%
I5 /tatement.........................................................48
I5 T.!7 !'/!..................................................10+
I7C operator........................................................3%
in>inite loop..........................................................#1
Integer data-t*pe..................................................28
Ua"a.......................................................................#3
Ua"a-like arra*s....................................................#3
'A:!'.................................................................4+
'ea"e e"ent..........................................................?2
'e>t propert*........................................................88
'I4!..............................................................3+) 43
'inu2..................................................................141
'ist:o2 control.................................................%?p.
'oad conditions..................................................303
localiDation....................................13%pp.) 142) 14#
looping structures.................................................4+
'ower method......................................................8%
@enu !ditor......................................................+8p.
@enuItems........................................................+8p.
@essage class.....................................................111
@essage:o2 control...........................................111
@I@! TC!........................................................8%
@1$ >unction......................................................3#
@1$ operator......................................................38
@ouse propert*....................................................88
@o"e method.......................................................8+
7ati"e arra*..........................................................#3
7!- ke*word......................................................2#
7ew roFect -iDard.......................................31) ?0
7e2t propert*.......................................................88
7!;T statement...................................................#0
7!;T /tatement..................................................4+
71T operator.......................................................42
obFect data-t*pe....................................................2?
1bFect data-t*pe...................................................2?
1penContent 'icense..........................................1p.
1pen5ile $ialog.........................................102) 118
16 operator..........................................................3?
anel class............................................................+2
anel control........................................................+2
arent propert*.....................................................8?
icture class..........................................................8?
icture control......................................................?8
picture obFect........................................................??
icture obFect........................................................84
icture propert*....................................................8?
7G >ile...............................................................??
ointer datat*pe....................................................2%
ower operator.....................................................38
prede>ined constants.......................81) 8#) 102) 14%
re"ious propert*.................................................8?
6I7T statement......................................34) 4#) #0
6I7T /tatement.................................................4#
6I(AT! ke*word..............................................2#
rogress:ar control..............................................?1
roFect !2plorer........................................1%pp.) 31
,:'IC ke*word..........................................2#) 2%
Et..........................................................................#?
At.........................................................14p.) #?) 141
At8........................................................................14
A,IT command...................................................33
race condition.....................................................303
6adio:utton class................................................+3
6adio:utton control..........................................+2p.
3#+
6aise method........................................................8%
reco"erable error................................................300
6e>resh method....................................................8+
6!!AT and ,7TI'...........................................#2
6esiDe method......................................................8+
6!T,67 command.............................................33
6G: >unction.......................................................81
/a"e5ile $ialog..........................................102) 11?
/creen; propert*.................................................8?
/creenC propert*................................................8?
/!'!CT statement...............................4%) 104) 113
/electColor $ialog.....................................102) 104
/elect$irector* $ialog...............................102) 11%
/elect5ont $ialog..........................................10?pp.
/et5ocus method..................................................8+
/et5ocusIJ method...............................................8?
/hort data-t*pe.....................................................28
/how method.......................................................8%
/TATIC ke*word.................................................2#
/tatus :ar.............................................................1+
/T! ke*word.....................................................4+
/tring constants....................................................2+
string data-t*pe.......................................2+) ##) 124
/tring data-t*pe....................................................2?
string >unctions...................................................124
string operators.....................................................30
sub@enus.............................................................+?
/*stem class......................................................%%p.
t-in constants........................................................2+
Tag propert*.........................................................8?
terminal application......................................31) 124
Te2t propert*..................................................82) 8?
Te2tbo2 control....................................................%2
Te2t:o2 control.............................................?+) %2
Toggle:utton control...........................................+0
Tool:ar................................................................22
Toolbo2................................................................19
Tool:o2 pane.......................................................22
ToolTip................................................................22
ToolTip propert*..................................................8?
Top propert*.........................................................8?
Tree"iew.............................................................103
Tree(iew..................................................1%) 31) 82
T6C....................................................................30#
T6C statement...................................................30#
,T5-% charset............................................13#) 141
(alue propert*......................................................8?
"ariant data-t*pe...................................................2?
(ariant data-t*pe............................................2?) ##
(:..................................................................28) 33
(isible propert*....................................................8?
- propert*...........................................................88
-AIT...................................................................8+
-arning messages..............................................114
-.I'! ... -!7$................................................#2
-idth propert*.....................................................88
-indow propert*.................................................8%
-IT....................................................................30
-IT. ke*word....................................................30
; propert*............................................................88
;--indows..........................................................??
;16 operator.......................................................3%
C propert*............................................................88
380
Appendix A
Gambas online resources:
1. Gambas project homepage (the starting point)
http://gambas.sourceforge.net/en/main.html
2. Gambas Wiki Encclope!ia
http://gambas!oc.org/help"en
#. $anguage references %ote that these same resources (belo&' in this section) are a(ailable
offline' for our current (ersion of Gambas !istribution' if ou click the )"* item on our
Gambas +,E menu. +f ou !o that' a bro&ser &in!o& &ill open' gi(ing access to the
!ocumentation' &ithout nee!ing to ha(e a Web connection.
http://&&&.gambas!oc.org/help/comp
-his is the gate&a to !ocumentation of all Gambas2 components an! classes !atatpes'
controls' properties' metho!s' etc.
http://&&&.gambas!oc.org/help/comp"(#
-his is the same as the abo(e' but for Gambas#.
http://gambas!oc.org/help/lang
-his is the $anguage +n!e. for Gambas2. +t inclu!es an /(er(ie& section an! an +n!e. 0 %ame
for ke&or!s an! functions.
http://gambas!oc.org/help/lang"(#
1. 2onte.t help
+f ou are &riting co!e in the Gambas +,E' ou can highlight a &or! an! click on the
magnifing glass/3uestion mark icon ( ) an! the +,E &ill open a help bro&ser &ith that specific
Gambas language &or! !efine!.
4. 5pecial purpose !ocuments
http://gambas!oc.org/help/!oc
-his contains !ocuments !iscussing ho& to !o a (ariet of special6purpose jobs connecte! &ith
Gambas.
http://gambas!oc.org/help/!oc"(#
7. Gambas6relate! sites an! forums:
http://gambaslinu..eg2.fr/in!e..php"lng8en
-his &ebsite is bilingual in 9rench an! English. 5ome of the co!e samples are !ocumente! in
9rench' others in English. -here are man useful co!e samples' some complete programs' an!
links to other forums an! blogs. %ote the chat function' ):ini -chat*' &here ou can ask
3uestions.
http://&&&.gambasforum.com/in!e..php"
;<;5E55+,8fcc!c7e=e>1?!1a!=424?aa4?ac?4=47@boar!82.>
-his is a (er &ell6organiAe! Gambas forum' &ith a lot of participation. Great for fin!ing
a!(ice.
http://gambasra!.org/Aforum/in!e.Bhtml
<ere is another forum' &ith thousan!s of topics an! co!e e.amples' an! man participants.
http://en.&ikibooks.org/&iki/Gambas
-his is a &iki that nee!s more submissions' but it !oes contain useful information.
http://pigasoft&are.a.&iki6site.com/in!e..php/GambasBE.amples
-his is a &iki that !iscusses techni3ues an! co!e e.amples' &ith a special focus on games.
http://beginnersgui!etogambas.com/
-his is a Wor!;ress blog' inten!e! to support this book b allo&ing comments or 3uestions
relate! to the book contents. 2ontents of the ,C, reference! herein ma be !o&nloa!e! from
here.
Appendix B
Managing the Gambas experience:
1. Dea!6onl Gambas E.amples +n Gambas 2...' the E.ample projects !emonstrate a lot of
(aluable programming techni3ues: net&orking' barco!es' charts' games an! me!ia' an! much
more. -hese can pro(i!e the basis for our o&n great programs' but the E.amples inclu!e!
&ith the installation are )rea!6onl*' so ou canEt (ie& the GF+ properties for the forms an!
other controls. 5olution: the )rea!6onl* propert can be remo(e! b simpl coping a project
fol!er an! pasting it as a ne& fol!er in another location. /r' ou can cop an! paste &ith a
ne& name in the current location. Gt an rate' the complete set of Gambas2 E.ample projects'
&ithout the )rea!6onl* propert' has been inclu!e! in the ,C, that accompanies this book.
5ee the fol!er name! )Gambas2 e.amples %/- rea!6onl*.
+n the Gambas# Glpha (ersion' these projects are not' at this time of &riting' )rea!6onl*' an!
&e !onEt kno& &hether or not that &ill be true in the release (ersion of Gambas#. <o&e(er' if
ou encounter a problem' the cop6paste proce!ure mentione! abo(e &ill probabl sol(e it.
2. ,ifferences bet&een Gambas 2... an! Gambas #... -he release !ate for Gambas #... has
not been set et. -here are a number of changes' compare! to Gambas 2.... +f ou tr to use
Gambas# to open a program &ritten in Gambas2' Gambas &ill notif ou about this !iscrepanc'
an! &ill ask ou if ou &ant to con(ert the project to Gambas# format. +f ou repl positi(el'
Gambas &ill make the con(ersion. -his makes the project incompatible &ith Gambas2.
-herefore' make a backup cop of our Gambas2 project before ou make the con(ersion to
Gambas#.
+n mo(ing from Gambas2 to Gambas#' some of the changes inclu!e simplifie! snta.' fe&er
snonms for ke&or!s an! properties' impro(e! consistenc' better G-HI performance' an!
Jt1 compatibilit. -here is a major structural change in the project fol!ers' as sho&n in the
follo&ing figures:
Figure 1- TreeView1, original project structure
under Gambas2
Figure 2- TreeView1 project structure, converted to
run under Gambas3
%ote that the filenames &ith til!e characters (K) are backup files that appear after ou ha(e
e!ite! the original program. 5et our file bro&ser to )Cie& hi!!en files* &hen ou look insi!e
a Gambas project' because most of these files an! fol!ers are hi!!en. Glso' these tree(ie&s of
-reeCie&s &ere generate! using the -reeCie& of 2hapter L. DecursionM
+f ou con(ert a project from Gambas2 to Gambas#' there is no guarantee that it &ill run
correctl. Gambas just con(erts the project structure' as sho&n abo(e it !oes not attempt to
change our co!e to insure compatibilit' an! the programmer must troubleshoot an nee!e!
changes. %ote the &ebpage:
http://gambas!oc.org/help/!oc/gb2togb#"(#
-he page title is );orting from Gambas 2 to Gambas #*' an! the table on that page tries to take
an in(entor of all incompatible changes bet&een the t&o (ersions.
#. 2hanging the project properties after creation When ou start a ne& Gambas project' ou
respon! to a number of prompts until the project is create!. 9or e.ample' ou ha(e an
opportunit to inclu!e the components for +nternationaliAation' ,atabase access' %et&ork
programming' etc. -he configuration that ou chose at creation is not fi.e! fore(er' therefore
!onEt &orr if ou fin! later that ou nee! to a!! something' or that a component &as
unnecessar. -he );roject* menu gi(es ou a );roperties* !ialog that allo&s ou to assign a
project title (if ou !i!nEt !o that before)' change a (ariet of options (inclu!ing translatabilit)
an! check or uncheck components that &ill be use! in the project. Nou can e(en s&itch from
the Jt toolkit to G-HI' an! (ice (ersa. +tEs a goo! i!ea to spen! some time e.ploring the top
menu bar to see all of the tools that are a(ailable to ou.
1. Dan!om notes on project management from the +,E
E(er time ou e.ecute a program from the +,E' the current state of our project &ill be
temporaril sa(e! before e.ecution' an! ou &ill be able to un!o our changes b
clicking on the )back* icon.
E(er time ou )5a(e* our project' our class/form/mo!ule files &ill be up!ate! to the
current state' an! our pre(ious (ersion is sa(e! into the backup files &ith names that
inclu!e til!es (K)' as sho&n in item 2 abo(e. Gfter sa(ing' if ou run into a serious
problem' ou canEt use the )back* icon anmore' but ou can !elete (or rename) our
current class/form/mo!ule files' then rename the backup files b remo(ing the til!es.
-his restores our project con!ition prior to the last )5a(e*.
When ou e.ecute our program from the +,E' our e!iting toolbar or ;roperties tab
&ill !isappear' an! the !ebugging toolbar &ill be acti(e. +f the interpreter encounters an
error that causes the program to freeAe' ou must terminate the program before ou
can resume e!iting. -he s3uare )5top* icon on the !ebugging toolbar is the best &a to
terminate the program an! return to e!iting.
RV779

1.BGGV3 Book

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

1.BGGV3 Book

Uploaded by

Copyright:

Available Formats

A Beginner's Guide to Gambas Revised Edition

Copyright Notice for the printed version of this work:

You might also like