Beginner's Guide

Last update : 2014.06.03

Copyright: 2011, 2012, 2013, 2014 Anywhere Software

Edition 2.9

Table of contents

Basic4Android Beginner's Guide

Getting started ......................................................................................................................... 8

1.1
Trial version .................................................................................................................... 9
1.2
Installing Basic4Android and Android SDK .................................................................. 10
1.2.1 Install and configure Basic4Android .......................................................................... 12
1.3
Installing Android Emulator........................................................................................... 13
2
My first program (MyFirstProgram.b4a)............................................................................... 19
3
Second program (SecondProgram.b4a) ................................................................................. 39
4
The IDE ................................................................................................................................ 53
4.1
Menu and Toolbar.......................................................................................................... 54
4.1.1 Toolbar ...................................................................................................................... 54
4.1.2 File menu................................................................................................................... 55
4.1.3 Edit menu .................................................................................................................. 55
4.1.4 Project menu .............................................................................................................. 56
4.1.4.1 Add a new module ............................................................................................. 56
4.1.5 Tools menu ................................................................................................................ 56
4.1.5.1 Word wrap ......................................................................................................... 57
4.1.5.2 Auto Save .......................................................................................................... 57
4.1.5.3 Show Tooltips During Typing ............................................................................ 57
4.1.5.4 Test Compile When Saving ................................................................................ 57
4.1.5.5 Take Screenshot ................................................................................................. 58
4.1.5.6 Clean Files Folder (unused files) ........................................................................ 58
4.1.5.7 Clean Project...................................................................................................... 58
4.2
Code area....................................................................................................................... 59
4.2.1 Code header Project Attributes / Activity Attributes................................................... 59
4.2.1.1 Project Attributes ............................................................................................... 59
4.2.1.2 Activity Attributes.............................................................................................. 59
4.2.2
4.2.3
4.2.4
4.2.5

Undo Redo
................................................................................................. 61
Collapse a subroutine ................................................................................................. 61
Collapse a Region ...................................................................................................... 62
Collapse the whole code............................................................................................. 63

4.2.6 Commenting and uncommenting code

......................................................... 64

4.2.7 Bookmarks

..................................................................................... 64

4.2.8 Indentation

................................................................................................... 65

4.2.9 Autocomplete
..................................................................................................... 67
4.2.10 Built in documentation ........................................................................................... 69
4.2.11 Jump to a subroutine .............................................................................................. 70
4.2.12 Highlighting occurrences of words......................................................................... 71
4.2.13 Debugging ............................................................................................................. 72
4.2.13.1
Debug (legacy) mode ..................................................................................... 72
4.2.13.2
Debug (rapid) mode........................................................................................ 74
4.2.13.3
Release and Release (obfuscated) modes ........................................................ 80
4.2.14 Breakpoints............................................................................................................ 81
4.2.15 Color Picker ........................................................................................................... 84
4.3
Tabs............................................................................................................................... 85
4.3.1 Module and subroutine lists
................................................................... 85
4.3.1.1 Find Sub Tool (Ctrl + E) .................................................................................... 86
4.3.1.2 Find All References (F7) .................................................................................... 87
4.3.2 Files

........................................................................................................... 88

4.3.3 Logs

.......................................................................................................... 89

Table of contents
4.3.3.1

Basic4Android Beginner's Guide

Test Compile / Warnings.................................................................................... 90

4.3.4 Libs
............................................................................................................ 97
Screen sizes and resolutions................................................................................................... 98
5.1
Special functions like 50%x, 50dip ............................................................................ 103
5.1.1 PerXToCurrent, PerYToCurrent - 50%x .................................................................. 103
5.1.2 DipToCurrent - 50dip............................................................................................... 103
5.2
Working with different screen sizes / number of layouts .............................................. 104
5.3
Screen orientations....................................................................................................... 110
5.4
Supporting multiple screens - tips and best practices .................................................... 111
5.4.1 Advices.................................................................................................................... 111
5.4.1.1 'dip' units.......................................................................................................... 111
5.4.1.2 Use only a few layout variants.......................................................................... 111
5.4.1.3 Understand the meaning of scale (dots per inch)............................................... 111
5.4.1.4 "Normalized" variants ...................................................................................... 111
5.4.1.5 Scaling strategy................................................................................................ 112
5.4.1.6 How to change the views size and text size? AutoScale .................................. 112
6
The Emulator....................................................................................................................... 113
6.1
Launch an Emulator..................................................................................................... 113
6.2
Create a new Emulator................................................................................................. 115
6.3
Emulator problems....................................................................................................... 118
6.3.1 Process timeout........................................................................................................ 119
6.4
Exchanging files with the PC ....................................................................................... 120
7
Connecting a real device USB / B4A Bridge.................................................................... 123
7.1
USB............................................................................................................................. 123
7.2
B4A Bridge ................................................................................................................. 124
7.2.1 First you need to install B4A-Bridge on your device. ............................................... 124
7.2.2 Run B4A-Bridge on your device. ............................................................................. 125
7.2.3 Connect the IDE to the device.................................................................................. 125
7.2.3.1 Wireless connections........................................................................................ 125
7.2.3.2 Bluetooth connections ...................................................................................... 126
7.2.3.3 Bluetooth tips ................................................................................................... 128
8
The Designer ....................................................................................................................... 129
8.1
The menu..................................................................................................................... 130
8.1.1 File menu................................................................................................................. 130
8.1.2 Edit menu ................................................................................................................ 130
8.1.3 AddView menu........................................................................................................ 131
8.1.4 The Tools menu ....................................................................................................... 132
8.2
Tools ........................................................................................................................... 133
8.2.1 Generate Members ................................................................................................... 133
8.2.2 BringTo Front .......................................................................................................... 134
8.2.3 Send To Back........................................................................................................... 134
8.2.4 Duplicate Selected View .......................................................................................... 134
8.2.5 Remove Selected View ............................................................................................ 135
8.2.6 Change grid ............................................................................................................. 135
8.2.7 Connect device or emulator...................................................................................... 136
8.3
General settings ........................................................................................................... 137
8.4
Image files ................................................................................................................... 139
8.5
Properties list ............................................................................................................... 140
8.6
Layout variants ............................................................................................................ 142
8.7
The Abstract Designer ................................................................................................. 147
8.7.1 The menu................................................................................................................. 148
8.7.2 Context menus ......................................................................................................... 149
8.7.3 Select views ............................................................................................................. 150
5

Table of contents

Basic4Android Beginner's Guide

8.7.4 Example................................................................................................................... 151

8.8
Adding views by code.................................................................................................. 154
8.9
Designer Scripts........................................................................................................... 157
8.10 Anchors ....................................................................................................................... 164
8.10.1 First example ....................................................................................................... 167
8.10.2 Second example ................................................................................................... 175
8.11 AutoScale .................................................................................................................... 178
8.11.1 Simple AutoScale example with only one layout variant ...................................... 179
8.11.2 Same AutoScale example with portrait and landscape layout variants................... 184
8.11.3 AutoScale more advanced examples..................................................................... 187
8.12 UI Cloud...................................................................................................................... 191
9
Process and Activity life cycle............................................................................................. 193
9.1
How do we handle it ? ................................................................................................. 194
9.2
Process global variables ............................................................................................... 195
9.3
Activity variables......................................................................................................... 195
9.4
Sub Activity_Create (FirstTime As Boolean) ............................................................... 195
9.5
Globals versus FirstTime ............................................................................................. 196
9.6
Sub Activity_Resume Sub Activity_Pause (UserClosed As Boolean) .......................... 196
9.7
Activity.Finish / ExitApplication ............................................................................... 197
10 Variables and objects........................................................................................................... 198
10.1 Variable Types............................................................................................................. 198
10.2 Names of variables ...................................................................................................... 200
10.3 Declaring variables ...................................................................................................... 200
10.3.1 Simple variables................................................................................................... 200
10.3.2 Array variables..................................................................................................... 201
10.3.3 Array of views (objects) ....................................................................................... 203
10.3.4 Type variables...................................................................................................... 204
10.4 Casting ........................................................................................................................ 205
10.5 Scope........................................................................................................................... 206
10.5.1 Process variables.................................................................................................. 206
10.5.2 Activity variables ................................................................................................. 207
10.5.3 Local variables..................................................................................................... 207
10.6 Tips ............................................................................................................................. 207
11 Modules .............................................................................................................................. 208
11.1 Activity modules.......................................................................................................... 209
11.2 Class modules.............................................................................................................. 210
11.3 Code modules .............................................................................................................. 211
11.4 Service modules........................................................................................................... 212
11.5 Shared modules ........................................................................................................... 215
12 Tools ................................................................................................................................... 216
12.1 Search function in the forum........................................................................................ 216
12.2 The B4A Documentation Wiki..................................................................................... 217
12.3 B4AHelp ..................................................................................................................... 218
12.4 Help documentation - B4A Object Browser ................................................................. 221
12.5 Usefull links ................................................................................................................ 222
12.6 Books .......................................................................................................................... 223
13 Example programs............................................................................................................... 224
13.1 User interfaces ............................................................................................................. 224
13.1.1 Menu example (UserInterfaceMenu.b4a)............................................................. 225
13.1.2 TabHost example (UserInterfaceTabHost.b4a) ................................................... 226
13.1.3 Button toolbox example (UserInterfaceButtonToolbox.b4a)................................ 227
13.2 Program with 3 Activities (ThreeActivityExample.b4a) .............................................. 228
13.3 ScrollView examples ................................................................................................... 235

Table of contents

Basic4Android Beginner's Guide

13.3.1 ScrollView example program............................................................................... 236

14 Basic language .................................................................................................................... 247
14.1 Program flow ............................................................................................................... 247
14.1.1 Process_Globals routine ....................................................................................... 247
14.1.2 Globals routine..................................................................................................... 248
14.1.3 Activity_Create (FirstTime As Boolean) routine .................................................. 248
14.1.4 Activity_Resume routine...................................................................................... 248
14.1.5 Activity_Pause (UserClosed As Boolean) routine................................................. 248
14.2 Expressions.................................................................................................................. 251
14.2.1 Mathematical expressions .................................................................................... 251
14.2.2 Relational expressions.......................................................................................... 252
14.2.3 Boolean expressions............................................................................................. 252
14.3 Conditional statements................................................................................................. 253
14.3.1 If Then End If................................................................................................. 253
14.3.2 Select Case........................................................................................................ 255
14.4 Loop structures ............................................................................................................ 257
14.4.1 For Next............................................................................................................ 257
14.4.2 For - Each ............................................................................................................ 258
14.4.3 Do - Loop ............................................................................................................ 259
14.5 Subs............................................................................................................................. 261
14.5.1 Declaring ............................................................................................................. 261
14.5.2 Calling a Sub........................................................................................................ 261
14.5.3 Calling a Sub from another module ...................................................................... 261
14.5.4 Naming ................................................................................................................ 262
14.5.5 Parameters ........................................................................................................... 262
14.5.6 Returned value ..................................................................................................... 262
14.6 Events.......................................................................................................................... 263
14.7 Libraries ...................................................................................................................... 266
14.7.1 Standard libraries ................................................................................................. 266
14.7.2 Additional libraries folder .................................................................................... 266
14.7.3 Load and update a Library.................................................................................... 267
14.7.4 Error message "Are you missing a library reference?" .......................................... 268
14.8 String manipulation ..................................................................................................... 269
14.9 Timers ......................................................................................................................... 270
14.10
Files......................................................................................................................... 271
14.10.1 File object ............................................................................................................ 271
14.10.2 Filenames............................................................................................................. 273
14.10.3 Subfolders............................................................................................................ 273
14.10.4 TextWriter ........................................................................................................... 274
14.10.5 TextReader........................................................................................................... 275
14.10.6 Text encoding ...................................................................................................... 276
14.11
Lists......................................................................................................................... 278
14.12
Maps........................................................................................................................ 280
15 Graphics / Drawing.............................................................................................................. 282
15.1 Overview ..................................................................................................................... 282
15.2 Drawing test programs ................................................................................................. 284
15.2.1 First steps............................................................................................................. 284
15.2.1.1
Start Dim and Initialisation.......................................................................... 285
15.2.1.2
Draw a line................................................................................................... 285
15.2.1.3
Draw a rectangle........................................................................................... 286
15.2.1.4
Draw a circle ................................................................................................ 287
15.2.1.5
Draw a text................................................................................................... 288
15.2.2 Drawing rotating bitmaps / RotatingNeedle.......................................................... 289

Table of contents

Basic4Android Beginner's Guide

15.2.3 Simple draw functions.......................................................................................... 294

16 VB6 versus B4A.................................................................................................................. 303
17 FAQ .................................................................................................................................... 308
17.1 "Please save project first" message............................................................................. 308
17.2 "Are you missing a library reference" message........................................................... 308
17.3 How loading / updating a library.................................................................................. 309
17.4 When do we need to 'Initialize' and when not............................................................. 309
17.5 Split a long line into two or more lines......................................................................... 310
17.6 Avoid closing an application / capture keycodes like Back / Menu............................... 310
17.7 Unwanted events like Click, Touch or others ............................................................... 311
17.8 Adding a Menu item .................................................................................................... 311
17.9 How do I remove a View with the Designer................................................................. 312
17.10
"Process has timeout" message............................................................................... 312
17.11
Getting a picture from the gallery............................................................................. 313
17.12
How to delete x.bal files or other files from a project ............................................. 314
17.13
Block a screen orientation ........................................................................................ 315
17.14
Close second Activity .............................................................................................. 316
17.15
Taking a screenshot programaticaly ......................................................................... 316
17.16
After compiling, where are the files ......................................................................... 316
17.17
Run an application from another one........................................................................ 317
17.18
How to pass an Array to a Sub ................................................................................. 317
17.19
Getting language and country from device ............................................................... 318
17.20
Where is the apk file ................................................................................................ 318
17.21
Why is my apk filename result.apk .......................................................................... 318
17.22
Why is my apk filename xxx_DEBUG.apk .............................................................. 319
17.23
Select True / Case trick ............................................................................................ 319
17.24
Fill an array with random numbers without repetition .............................................. 319
17.25
Detect screen orientation.......................................................................................... 320
17.26
Some functions don't work in Activity_Pause........................................................... 320
17.27
Calling the internal Calculator.................................................................................. 321
17.28
Get the Alpha / Red / Green / Blue ........................................................................... 322
17.29
Get device type ........................................................................................................ 322
17.30
Generate a Click event ............................................................................................. 322
17.31
"Out of memory" Error / Bitmaps............................................................................. 323
17.32
Remove the scrollbar from a ScrollView.................................................................. 323
17.33
Check if directory exists........................................................................................... 323
17.34
Set Full Screen in code............................................................................................. 323
17.35
Change EditText input modes .................................................................................. 324
17.36
Sorting a file list according to last modified time...................................................... 326
17.37
Get the dpi values of the device (dots per inch) ........................................................ 326
17.38
Finding java program lines....................................................................................... 327
18 Glossary .............................................................................................................................. 328
Main contributors :
Erel Uziel
(Erel)
Klaus Christl (klaus)
nfordbscndrd
To search for a given word or sentence use the Search function in the Edit menu.
All the source code and files needed (layouts, images etc) of the example projects in this guide are
included in the SourceCode folder.

Table of contents

Updated for Basic4Android version 3.5 .

A more advanced guide can be downloaded User's Guide.

Basic4Android Beginner's Guide

1 Getting started

Basic4Android Beginner's Guide

Getting started

Basic4android is a simple yet powerful development environment that targets Android devices.
Basic4android language is similar to Visual Basic language with additional support for objects.
Basic4android compiled applications are native Android applications; there are no extra runtimes or
dependencies.
Unlike other IDEs, Basic4android is 100% focused on Android development.
Basic4android includes a powerful GUI designer with built-in support for multiple screens and
orientations. No XML writing is required.
You can develop and debug with the Android emulator or with a real device
(USB-connected or over the local network).
Basic4android has a rich set of libraries that make it easy to develop advanced applications.
This includes: SQL databases, GPS, Serial ports (Bluetooth), Camera, XML parsing, Web services
(HTTP), Services (background tasks), JSON, Animations, Network (TCP and UDP), Text To Speech
(TTS), Voice Recognition, WebView, AdMob (ads), Charts, OpenGL, Graphics and more.

Android 1.6 and above are supported (including tablets).

1 Getting started

1.1

Basic4Android Beginner's Guide

Trial version

The trial version has a new compilation mode called Remote Compilation Mode to avoid the
installation of the two components Java JDK and Android SDK.
This remote compilation mode is only available in the trial version.
Requirements:
You need to install the program B4A-Bridge on your device.
- You can download it here: http://www.basic4ppc.com/android/files/b4a_bridge.apk.
- B4A-Bridge is also available in Android market. Search for: B4A Bridge.
Look at chapter 7 B4A Bridge in this guide.

Download the B4A trial version.

- Install it and run it

1 Getting started

1.2

10

Basic4Android Beginner's Guide

Installing Basic4Android and Android SDK

Basic4android depends on two additional (free) components:

- Java JDK
- Android SDK
Installation instructions:
The first step should be to install the Java JDK, as Android SDK requires it as well.
Note that there is no problem with having several versions of Java installed on the same computer.
- Open the Java 7 JDK download link.
- Check the Accept License Agreement radio button.
- Select "Windows x86" in the platforms list (for 64 bit machines as well).
Android SDK doesn't work with Java 64bit JDK.
You should install the regular JDK for 64-bit computers as well.
- Download the file and install it.
The next step is to install the Android SDK and a platform:
- Install the SDK . The SDK doesn't always behave properly when it is installed in a path with
embedded spaces (like Program Files). It is recommended to install it to a custom folder
similar to C:\Android.
- You should now install the platform tools and at least one platform image. Use the latest one or at
least API 8.
You can also install Google USB Driver if you need to connect a physical device with USB. A list
of other drivers is available here.
Note that Basic4android allows you to connect to any device over the local network with B4ABridge tool.

A screen similar to this will be shown.

Select the API version you want to download.
In the example, I choose API 17.

1 Getting started

11

Basic4Android Beginner's Guide

You can select several APIs and install them

in parallel.
In this example, API 8 is also selected.

Note that you can install more packages later.

- Press on Install Selected and install both packages.
If you want to connect a device with USB you might also download the Google USB driver.

1 Getting started

12

Basic4Android Beginner's Guide

1.2.1 Install and configure Basic4Android

- Download and install Basic4Android.
- Open Basic4android.
- Choose Tools menu - Configure Paths.

- Use the browse buttons to locate "javac.exe" and "android.jar"

javac is located under <java folder>\bin.
android.jar is located under <android-sdk-windows>\platforms\android-17
The folder depends on where you installed the Android SDK,
It should be : C:\Android\platforms\android-17\android.jar
or C:\Android\platforms\android-8\android.jar.
The number depends on the Android version you loaded.
On older versions it could be under:
C:\Android\android-sdk-windows\platforms\android-8\android.jar.
On Windows 64 bit, Java will probably be installed under C:\Program Files (x86).
It is recommended to create a specific folder for Additional libraries.
Basic4Android utilizes two types of libraries:
Standard libraries, which come with Basic4Android and are located in the
Libraries folder of B4A.
These libraries are automatically updated when you install a new version of B4A.
Additional libraries, which are not part of B4A, and are mostly written by members. These
libraries should be saved in a specific folder different from the standard libraries folder.
More details in Chapter 14.7.2 Additional libraries folder.
Shared modules : Module files can be shared between different projects and must therefore be saved
in a specific folder. More details in 11.5 Shared modules.
Common errors
- Windows XP - "Basic4Android.exe Application could not be initialised correctly error
0xc0000135" on start-up. Basic4android requires .Net Framework 2.0 or above.
Windows XP users who didn't install it before should first install the framework.

1.3 Installing Android Emulator

1.3

13

Basic4Android Beginner's Guide

Installing Android Emulator

Please follow the installation (and configuration) instructions if you have not done it yet:
http://www.basic4ppc.com/forum/basic...droid-sdk.html.
In this chapter we will create a new AVD (Android Virtual Device) which is an emulator;
software on the PC that 'emulates' a device. It's a virtual device and not a real device.
Then we will create a simple program that displays a simple message box and writes a message to
the log.
You can also connect a real device to the IDE and run the program on your actual device instead of
running it on the virtual device:
Connecting your device with ADB
Connecting your device with B4A-Bridge Chapter 7
Create new AVD
- Run Basic4android.
- Choose Tools Menu - Run AVD Manager.
Wait a few seconds.
- The AVD Manager should appear:

- Click on

and refer to the following image to fill in the fields with similar values.

1.3 Installing Android Emulator

14

Basic4Android Beginner's Guide

Enter a name.
Select a device, in the example the
'standard' screen 320 x 480 pixels.
Select the Android target version.

- Click on

- Note that you can create more

than one AVD. Each can have a
different resolution or can target a
different API version (you will
need to install additional platforms
first).
Add a memory size for SD Card
support :
Example : 16Mb
Simulates an external SD card.

1.3 Installing Android Emulator

15

Basic4Android Beginner's Guide

- Select the Emulator in the list.

- Now click on

in order to start the emulator.

- You will see a screen similar to this one.

- Click on

to start the emulator.

- You will see several windows popping up and disappearing. This is normal.

1.3 Installing Android Emulator

16

Basic4Android Beginner's Guide

- The emulator should boot up:

Wait. The first time it can take several minutes before the emulator is ready.

1.3 Installing Android Emulator

17

Basic4Android Beginner's Guide

The emulator is ready when it gets to this screen or

one similar to it.
The actual screen will differ based on which API
you selected earlier.
If it looks like a phone or a tablet screen, thats it !
Note that there is no need to restart the emulator
each time you deploy a program. The emulator can
be kept running all the time.
If you are not familiar with Android you can play
with the emulator. Press on the button with the
small squares to get to the application page.

Click on

1.3 Installing Android Emulator

18

Basic4Android Beginner's Guide

You may see screens like below depending on the Android target Version.

If you see a screen similar to this one, it's a lock screen,

drag the lock icon to the right to unlock the device.

2 My first program

19

Basic4Android Beginner's Guide

My first program (MyFirstProgram.b4a)

Let us write our first program. The suggested program is a math trainer for kids.
The project is available in the SourceCode folder :
SourceCode\MyFirstProgram\ MyFirstProgram.b4a
The look of the screen is different depending on the Android version, even with Emulators.
Emulator Android version 4.2

Emulator Android version 2.2

On the screen, we will have:

- 2 Labels displaying randomly generated numbers (between 1 and 9)
- 1 Label with the math sign (+)
- 1 EditText view where the user must enter the result
- 1 Button, used to either confirm when the user has finished entering the result or generate a new
calculation.
- 1 Label with a comment about the result.
In Android :
- Label
is an object to show text.
- EditText
is an object allowing the user to enter text.
- Button
is an object allowing user actions.
We will design the layout of the user interface with the Designer on an Emulator and go step by
step through the whole process.

2 My first program

20

Basic4Android Beginner's Guide

Run the IDE

Save the project.
You must save the project before you can run the Designer.

Create a new folder MyFirstProgram

and save the project with the name
MyFirstProgram.

Set the Package Name.

Each program needs a package name.
In the menu Project click on Package Name .

This window appears :

2 My first program

21

Basic4Android Beginner's Guide

The default name is b4a.example. We will change it to b4a.myfirstprogram.

Package names must be lower case !

Set the Application Label.

The Application label is the name of the program that will be shown on the device or in the
Emulator.
On top of the code screen you see these two lines showing two 'regions'.

Regions are code parts which can be collapsed or

extended.
Clicking on will expand the Region.
Clicking on will collapse the Region.
Regions are explained in Chapter 4.2.3 Collapse a
Region.
#Region Project Attributes
#ApplicationLabel: B4A Example
#VersionCode: 1
#VersionName:
'SupportedOrientations possible values: unspecified, landscape or portrait.
#SupportedOrientations: unspecified
#CanInstallToExternalStorage: False
#End Region
#Region Activity Attributes
#FullScreen: False
#IncludeTitle: True
#End Region

The default name is B4A Example, but we will change it to MyFirstProgram for naming
consistency.
Change this line:
#ApplicationLabel: B4A Example

to
#ApplicationLabel: MyFirstProgram

The other lines are explained in Chapter 4.2.1 Code header Project Attributes / Activity Attributes.

2 My first program

22

Basic4Android Beginner's Guide

In the IDE run the Emulator.

IDE menu Tools

Run AVD Manager

Select the Emulator.

Click on

2 My first program

23

Basic4Android Beginner's Guide

Click on

Wait until the Emulator is

ready. This will take quite
some time.
The Emulator images may
change according to the
Android target version you
selected for the Emulator.
In the example we target
Android version 4.2.

In the IDE run the Designer .

Wait until the Designer is ready.

2 My first program

24

Basic4Android Beginner's Guide

You should see

something like this.
Note that near the top
left of the Designer
window you will see :

Connect the Designer to the Emulator.

Wait until the Designer and the Emulator
are connected. This can take some time, so
be patient.
You will see the state of the Designer here
in the top left corner:

The top of the Emulator will have a look similar to this :

2 My first program

25

Basic4Android Beginner's Guide

Now we will add the 2 Labels for the numbers.

In the Designer, add a Label.

The label appears in the Emulator, and its default properties are listed in the Designer.
Resize and move the Label with the red
squares like this.

The new properties Left, Top, Width and

Height are directly updated in the
Designer.
You can also modify the Left, Top,
Width and Height properties directly in
the Designer.
Let us change the properties of this first Label
according to our requirements.
By default, the name is Label with a number, here
Label1, let us change its name to lblNumber1.
The three letters 'lbl' at the beginning mean 'Label',
and 'Number1' means the first number.
It is recommended to use significant names for
views so we know directly what kind of view it is
and its purpose.

2 My first program

26

Basic4Android Beginner's Guide

Pressing the 'Return' key or clicking

elsewhere will also change the Event Name
property.

We have now:

Main :
main module.
Name :
name of the view.
Type :
type of the view. In this case, Label, which is not editable.
Event Name : generic name of the routines that handle the events of the Label.
Parent :
parent view the Label belongs to.

Let us check and change the other properties:

Left, Top, Width and Height are OK.

Enabled, Visible are OK

Tag, we leave empty.

Text, we set a default number, say 5

Typeface, Style are OK

Horizontal Alignment, we set to CENTER_HORIZONTAL
Vertical Alignment, we leave CENTER_VERTICAL.
Size, we set to 36

We leave all the other properties as they are.

2 My first program

27

Basic4Android Beginner's Guide

The new properties.

We need a second Label similar to the first one. Instead of adding a new one, we copy the first one
with the same properties. Only the Name and Left properties will change.

The
new
label
covers
the
previo
us one.

In the left part you see a tree with

the different views.
The new label Label1 is added.

2 My first program

28

Basic4Android Beginner's Guide

Let us position the new Label and change its name to lblNumber2.

The name in the list has

changed.

Let us now add a 3rd Label for the math sign. We copy once again lblNumber1.
Click on lblNumber1 in the Emulator, and in the Designer click in the 'Tools' menu on 'Duplicate
Selected View'.

The new label covers lblNumber1.

Position it between the first two Labels and change its name to lblMathSign and its
Text property to '+'.

2 My first program

29

Basic4Android Beginner's Guide

Now let us add an EditText view.

In the Designer Add View menu
click on Edit Text .

Position it below the three Labels and change its name to edtResult. 'edt' means EditText and
'Result' for its purpose.

Let us change these properties.

Name
to edtResult

Horizontal Alignment
Text Size
to 30

Input Type
Hint Text

to CENTER_HORIZONTAL

to NUMBERS
to Enter result

Setting Input Type to NUMBERS lets the user enter only numbers.
Hint Text represents the text shown in the EditText view if no text is entered.

After making these changes, you should see something like

this.

2 My first program

30

Basic4Android Beginner's Guide

Now, let's add the Button which, when pressed, will either check the result the user supplied as an
answer, or will generate a new math problem, depending on the user's input.

Position it below the EditText view. Resize it and change following properties:
Name

to btnAction

Text

to O K (with a space between O and K)

Text Size to 24

2 My first program

31

Basic4Android Beginner's Guide

Let us add the last Label for the comments. Position it below the Button and resize it.

Change the following properties:

Name to lblComments

Horizontal Alignment CENTER_HORIZONTAL

Text Color
to Black
Color
to White
Alpha
to 255

We set the Text Color property to Black.

By default, the Label background color is
black and transparent. We set it to white and
opaque Alpha = 255.

The result will look like below depending on the Android version.

Android 4.2 Emulator

Android 2.2 Emulator

2 My first program

32

Basic4Android Beginner's Guide

Let us save the layout in a file.

Click on

and save it with the name 'Main'.

Click on

To write the routines for the project, we need to reference the Views in the code.
This can be done with the Generate Members tool in the Designer.

2 My first program

33

Basic4Android Beginner's Guide

The Generate Members tool automatically generates references and subroutine frames.

Click on

to open the generator.

Here we find all the views added to the current layout.

We check all views and check the Click event for the btnAction Button.
Checking a view
generates its reference in the Globals Sub routine in the code.
This is needed to make the view recognized by the system and allow the autocomplete function.
Dim
Dim
Dim
Dim
Dim
Dim

btnAction As Button
edtResult As EditText
lblComments As Label
lblMathSign As Label
lblNumber1 As Label
lblNumber2 As Label

Clicking on an event of a view

generates the Sub frame for this event.

Sub btnAction_Click
End Sub

Click on

to generate the references and Sub frames, then

2 My first program

34

Basic4Android Beginner's Guide

Now we go back to the IDE to enter the code.

First, we need our Activity to load our layout file. Within the Activity_Create sub, do the
following. You can remove the lines in green.
- Enter 'Activity'

- Enter a dot

- The autocomplete function shows all the possible properties of the view.
- Enter 'L' , and the autocomplete function shows the properties beginning with 'L'

- Press the down arrow key, and LoadLayout will be highlighted with the online help for the given
property or method.

2 My first program

35

Basic4Android Beginner's Guide

- Press 'Return' to add LoadLayout.

- Press '(' to display the online help showing the needed properties for the method.

- Enter "Main"
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Main")
End Sub

We want to generate a new problem as soon as the program starts. Therefore, we add a call to the
New subroutine.
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Main")
New
End Sub

Generating a new problem means generating two new random values between 1 and 9 (inclusive)
for Number1 and Number2, then showing the values using the lblNumber1 and lblNumber2 Text
properties.
To do this we enter following code:
In Sub Globals we add two variables for the two numbers.
Dim Number1, Number2 As Int
End Sub

And the 'New' Subroutine:

Sub New
Number1 = Rnd(1, 10)
' Generates a random number between 1 and 9
Number2 = Rnd(1, 10)
' Generates a random number between 1 and 9
lblNumber1.Text = Number1
' Displays Number1 in label lblNumber1
lblNumber2.Text = Number2
' Displays Number2 in label lblNumber2
lblComments.Text = "Enter the result" & CRLF & "and click on OK"
edtResult.Text = ""
' Sets edtResult.Text to empty
End Sub

The following line of code generates a random number from '1' (inclusive) to '10' (exclusive) :
Rnd(1, 10)

The following line displays the comment in the lblComment view :

lblComments.Text = "Enter the result" & CRLF & "and click on OK"
CRLF is the LineFeed character.

2 My first program

36

Basic4Android Beginner's Guide

Now we add the code for the Button click event.

We have two cases:
- When the Button text is equal to "O K", it means that a new problem is displayed, and the program
is waiting for the user to enter a result and press the Button.
- When the Button text is equal to "NEW", it means that the user has entered a correct answer and
when the user clicks on the Button a new problem will be generated.
Sub btnAction_Click
If btnAction.Text = "O K" Then
If edtResult.Text="" Then
Msgbox("No result entered","E R R O R")
Else
CheckResult
End If
Else
New
btnAction.Text = "O K"
End If
End Sub
If btnAction.Text = "O K" Then checks if the Button text equals "O K"

If yes then we check if the EditText is empty.

If yes, we display a MessageBox telling the user that there is no result in the EditText view.
If no, we check if the result is correct or if it is false.
If no then we generate a new problem, set the Button text to "O K" and clear the EditText view.

The last routine checks the result.

Sub CheckResult
If edtResult.Text =
lblComments.Text
btnAction.Text =
Else
lblComments.Text
End If
End Sub

Number1 + Number2 Then

= "G O O D result" & CRLF & "Click on NEW"
"N E W"
= "W R O N G

result" & CRLF & "Enter a new result" & CRLF & "and click OK"

With If edtResult.Text = Number1 + Number2 Then we check if the entered result is correct.
If yes, we display in the lblComments label the text below:
'G O O D result'
'Click on NEW'
and we change the Button text to "N E W ".
If no, we display in the lblComments label the text below:
W R O N G result
Enter a new result
and click OK

2 My first program

37

Basic4Android Beginner's Guide

Let us now compile the program and transfer it to the Emulator.

In the IDE on top click on

The program is going to be compiled.

When you see 'Completed successfully.' as in above message box, the compiling and transfer
is finished.
Looking at the emulator, you should see something similar to the image below, with different
numbers.

Of course, we could make aesthetic improvements in the

layout, but this was not the main issue for the first program.

2 My first program

38

Basic4Android Beginner's Guide

On the Emulator, you can use the keyboard of the computer

or the virtual keyboard.

On a real device, you need to use the virtual keyboard.

One disadvantage of the current layout is the comment
label being covered by the virtual keyboard.
This will be improved in the next chapter,
'Second program', when we create our own keyboard.

3 Second program

39

Basic4Android Beginner's Guide

Second program (SecondProgram.b4a)

The project is available in the SourceCode folder :

SourceCode\SecondProgram\SecondProgram.b4a
Improvements to My first program.
Create a new folder called SecondProgram. Copy all the files and folders from MyFirstProgram
to the new SecondProgram folder and rename the program file MyFirstProgram.b4a to
SecondProgram.b4a .
Load this new program in the IDE.
Run the Designer and connect it to the Emulator.
Let us add a numeric keyboard to the layout to avoid the
use of the virtual keyboard.
We need to change the Package Name.
In the IDE Project menu.
Click on Package Name

Change the Package name to b4a.secondprogram, ATTENTION lower case !

Click on

3 Second program

40

Basic4Android Beginner's Guide

Then we must change the ApplicationLabel on the very top of the code.
#Region Project Attributes
#ApplicationLabel: SecondProgram

We want to replace the edtResult EditText view by a new Label.

In the Emulator and the Designer, click on the edtResult view.

Click on

Click on lblNumber1 to select it.

Duplicate it

The new label covers lblNumber1.

3 Second program

41

Basic4Android Beginner's Guide

Move it between the upper labels and the button

and resize it.

Modify the following properties:

Name

to lblResult

Text

to " " blank character

Text Color

to Black

Corner Radius
Color
Alpha

to 5
to White
to 255

3 Second program

42

Basic4Android Beginner's Guide

Let us add a Panel for the keyboard buttons.

Position and resize it as in the image.

Change its Name to pnlKeyboard

"pnl" for Panel, the view type.

Change
Corner radius to 0
Color
to ControlDarkDark

3 Second program

43

Basic4Android Beginner's Guide

We will move the O K button from the Activity to the

pnlKeyboard Panel.
Click on the O K button (btnAction)
and in the Parent list click on

The button now belongs to the Panel.

Now we rearrange the views to get some more space for the
keyboard.
Set the Height property of the 4 Labels to 50 instead of 60.
Set the Top property of label lblResult to 60.
Set the Top property of label lblComments to 120.
Set the Top property of panel pnlKeyboard to 210.
Set the Height property of panel pnlKeyboard to 180.

3 Second program

44

Basic4Android Beginner's Guide

Click on the pnlKeyboard panel to select it.

Click on
to add a new button.

The new button is added.

Change the following properties :

Name
Event name

to btn0
to btnEvent

Left
Top
Width
Height

to 0
to 120
to 55
to 55

Tag
Text

to 0
to 0

Size
TextColor

to 24
to Black

3 Second program

45

Basic4Android Beginner's Guide

Now we want to change the button colors.

Click on StatelistDrawable.

Click on GradientDrawable

Change the following properties :

Orientation
to
First Color
Second Color

TOP_BOTTOM

Pressed Drawable

to GradientDrawable

Orientation
to
First Color
Second Color

TOP_BOTTOM

The button looks now like this.

Let us duplicate btn0 and position the new one beside

button btn0.
Select the Button btn0.

Click on Duplicate Selected Views.

3 Second program

46

Basic4Android Beginner's Guide

Move the new Button next to the previous one.

Change the following properties :

Name

to btn1

Tag
Text

to 1
to 1

And the result.

Let us add 8 more Buttons and position them like in the

image.
Change following properties:
Name btn2, btn3, btn4 etc.
Tag
2 , 3 , 4 etc.
Text
2 , 3 , 4 etc.

3 Second program

47

Basic4Android Beginner's Guide

To create the BackSpace button, duplicate one of the

number buttons, and position it like in the image.
Resize and position btnAction.
Change the pnlKeyboard Color to Black.
Change their Name, Tag, Text and Color properties as below.
btnBS

<

Set the Color property of panel pnlKeyboard to Black.

btnAction

OK

3 Second program

48

Basic4Android Beginner's Guide

The finished new layout.

Now we will update the code.

First, we must replace the edtResult by lblResult because we replaced the EditText view by a Label.

Click on edtResult to select it.

Click on Find(F3)

3 Second program

49

Basic4Android Beginner's Guide

Click on

Click on

and

We also need to change its view type form EditText to Label.

Dim lblResult As Label

Now we write the routine that handles the Click events of the Buttons.
The Event Name for all buttons, except btnAction, is "btnEvent".
The routine name for the associated click event will be btnEvent_Click.
Enter the following code:
Sub btnEvent_Click
End Sub

We need to know what button raised the event. For this, we use the Sender object which is a special
object that holds the object reference of the view that generated the event in the event routine.
Sub btnEvent_Click
Dim btnSender As Button
btnSender = Sender
Select btnSender.Tag
Case "BS"
Case Else
End Select
End Sub
Select btnSender.Tag
Case "BS"
Case Else

To have access to the properties of the view that raised the

event we declare a local variable
Dim btnSender As Button.
And set btnSender = Sender.
Then, to differentiate between the backspace button and
the numeric buttons we use a Select / Case / End Select
structure and use the Tag property of the buttons.
Remember, when we added the different buttons we
set their Tag property to BS, 0, 1, 2 etc.
sets the variable to test.
checks if it is the button with the "BS" tag value.
handles all the other buttons.

3 Second program

50

Basic4Android Beginner's Guide

Now we add the code for the numeric buttons.

We want to add the value of the button to the text in the lblResult Label.
Select btnSender.Tag
Case "BS"
Case Else
lblResult.Text = lblResult.Text & btnSender.Text
End Select
End Sub

This is done in this line

lblResult.Text = lblResult.Text & btnSender.Text

The "&" character means concatenation, so we just append to the already existing text the value of
the Text property of the button that raised the event.
Now we add the code for the BackSpace button.
Select btnSender.Tag
Case "BS"
If lblResult.Text.Length >0 Then
lblResult.Text = lblResult.Text.SubString2(0, lblResult.Text.Length - 1)
End If
Case Else
lblResult.Text = lblResult.Text & btnSender.Text
End Select
End Sub

When clicking on the BS button we must remove the last character from the existing text in
lblResult.
However, this is only valid if the length of the text is bigger than 0. This is checked with:
If lblResult.Text.Length >0 Then

To remove the last character we use the SubString2 function.

lblResult.Text = lblResult.Text.SubString2(0,lblResult.Text.Length - 1)

SubString2(BeginIndex, EndIndex) extracts a new string beginning at BeginIndex (inclusive) until

EndIndex (exclusive).
Now the whole routine is finished.
Sub btnEvent_Click
Dim btnSender As Button
btnSender = Sender
Select btnSender.Tag
Case "BS"
If lblResult.Text.Length >0 Then
lblResult.Text = lblResult.Text.SubString2(0,lblResult.Text.Length - 1)
End If
Case Else
lblResult.Text = lblResult.Text & btnSender.Text
End Select
End Sub

3 Second program

51

Basic4Android Beginner's Guide

We can try to improve the user interface of the program by adding some colors to the lblComments
Label.
Let us set:
- Yellow
for a new problem
- Light Green for a GOOD answer
- Light Red for a WRONG answer.
Let us first modify the New routine, where we add the line lblResult.Text = ""...
Sub New
Number1 = Rnd(1, 10)
' Generates a random number between 1 and 9
Number2 = Rnd(1, 10)
' Generates a random number between 1 and 9
lblNumber1.Text = Number1 ' Displays Number1 in label lblNumber1
lblNumber2.Text = Number2 ' Displays Number2 in label lblNumber2
lblComments.Text = "Enter the result" & CRLF & "and click on OK"
lblComments.Color = Colors.RGB(255,235,128) ' yellow color
lblResult.Text = ""
' Sets lblResult.Text to empty
End Sub

And in the CheckResult routine we add lines 76 and 80.

Sub CheckResult
If lblResult.Text = Number1 + Number2 Then
lblComments.Text = "G O O D result" & CRLF &
lblComments.Color = Colors.RGB(128,255,128)
btnAction.Text = "N E W"
Else
lblComments.Text = "W R O N G result" & CRLF
lblComments.Color = Colors.RGB(255,128,128)
End If
End Sub

"Click on NEW"
' light green color

& "Enter a new result" & CRLF & "and click OK"
' light red color

3 Second program

52

Basic4Android Beginner's Guide

Another improvement would be to hide the '0' button to avoid entering a leading '0'.
For this, we hide the button in the New subroutine in line btn0.Visible = False.
Sub New
Number1 = Rnd(1, 10)
' Generates a random number between 1 and 9
Number2 = Rnd(1, 10)
' Generates a random number between 1 and 9
lblNumber1.Text = Number1 ' Displays Number1 in label lblNumber1
lblNumber2.Text = Number2 ' Displays Number2 in label lblNumber2
lblComments.Text = "Enter the result" & CRLF & "and click on OK"
lblComments.Color = Colors.RGB(255,235,128) ' yellow color
lblResult.Text = ""
' Sets lblResult.Text to empty
btn0.Visible = False
End Sub

In addition, in the btnEvent_Click subroutine, we hide the button if the length of the text in
lblResult is equal to zero and show it if the length is greater than zero, lines 98 to 102.
Sub btnEvent_Click
Dim btnSender As Button
btnSender = Sender
Select btnSender.Tag
Case "BS"
If lblResult.Text.Length >0 Then
lblResult.Text = lblResult.Text.SubString2(0,lblResult.Text.Length - 1)
End If
Case Else
lblResult.Text = lblResult.Text & Send.Tag
End Select
If lblResult.Text.Length = 0 Then
btn0.Visible = False
Else
btn0.Visible = True
End If
End Sub

As we are accessing btn0 in the code we need to declare it in the Globals routine.
Modify line 25 like below:
Dim btnAction, btn0 As Button

4 The IDE

53

Basic4Android Beginner's Guide

The IDE

The Integrated Development Environment.

When you run the IDE you will get a form like the image below:
Example: SecondProgram.b4a.

You see 4 main areas :

Code area

The code editor

Module list
List containing all module names.
Clicking on one of the names jumps directly to the selected module.

Subroutine list
List of the subroutines in the current module.
Clicking on one of the names jumps directly to the selected routine.

Tabs

Tabs for different settings.

4 The IDE

4.1

54

Basic4Android Beginner's Guide

Menu and Toolbar

4.1.1 Toolbar
Generates a new empty project.
Loads a project.
Saves the current project.
Copies the selected text to the clipboard.
Cuts the selected text and copies it to the clipboard.
Pastes the text in the clipboard at the cursor position.
Undoes the last operation.
Redoes the previous operation.
Activates the Find and Replace function.
Sets the selected lines as comments.
Uncomments the selected lines.
Navigate backwards
Navigate forwards
Adds a bookmark.
Removes a bookmark.
Go back to the previous bookmark.
Go forward to the next bookmark.
Autocomplete function Ctrl + space.
Decrease the indentation of the selected lines.
Increase the indentation of the selected lines.
Runs the compiler.
Compiler options list and Debugging
Routine list

4 The IDE

55

Basic4Android Beginner's Guide

4.1.2 File menu

New
Generates a new empty
project.
Open Source Loads a project.
Save
Saves the current project.
Export As Zip Exports the whole project
in a zip file.
Page Setup
Setup pages for printing
Print Preview Shows a print preview.
Print
Prints the code.
Exit
Leaves the IDE.
List of last loaded programs.

4.1.3 Edit menu

Cut
clipboard.
Cut Line
Copy
Paste
position.

Cuts the selected text and copies it to the

Undo
Redo
Find

Undoes the last operation.

Redoes the previous operation.
Activates the Find and Replace function.

Cuts the line at the cursor position.

Copies the selected text to the clipboard.
Pastes the text in the clipboard at the cursor

Block Comment
Sets the selected lines as comments.
Block Uncomment Uncomments the selected lines.
Remove All Bookmarks
Remove All Breakpoints
Outlining

Bookmarks.
Breakpoints.

Collapse the whole code.

4 The IDE

56

Basic4Android Beginner's Guide

4.1.4 Project menu

Adds a new module

Adds an existing module
Changes the module name
Removes the current module
Hides the current module

Chooses an icon for the program.

Changes the package name.
Runs the Manifest Editor.
Don't overwrite Manifest File.

Test Compilation, new feature since B4A v 2.70

Look at Warnings.
Different compiling modes.

4.1.4.1 Add a new module

Activity module
Class module
Code module
Service module

4.1.5 Tools menu

IDE Options

see below

B4A Bridge, connection with Bluetooth or Wifi

Clean Files Folder (unused files)
see next page
Clean Project
see next page
Run AVD Manager
Configure Paths

Take Screenshot

see next page

4 The IDE

57

Basic4Android Beginner's Guide

Change Tab size.

Change Font, not recommended.
Word wrap, see below.
Auto Save, see below.
Show Tooltips, see below.
Configure Process Timeout
Test Compile When Saving
For debugging.

4.1.5.1 Word wrap

Without word wrap.

The end of the line is hidden.

With word wrap.

The end of the line is wrapped to the next line.

4.1.5.2 Auto Save

Saves the program when you run it.
4.1.5.3 Show Tooltips During Typing

Show Tooltips checked.

Show Tooltips unchecked.

4.1.5.4 Test Compile When Saving

Executes a compile test when saving the program, see details in Test Compile / Warnings.

4 The IDE

58

Basic4Android Beginner's Guide

4.1.5.5 Take Screenshot

The

function can be called from the:

Tools menu when the IDE is in edit mode
Debug menu when the IDE is in debug mode

Clicking on
shows this window.

Click on
to take the
screenshot picture from the device or the
emulator.
You can resize the image.

You can save the image with

as a PNG file.
And you can change the
orientation
of the picture.

Right click on the image to copy the

image to the clipboard.

4.1.5.6 Clean Files Folder (unused files)

Deletes files that are located under the Files folder but are not used by the project (it will not delete
any file referenced by any of the project layouts). A list of unused files will be displayed before
deletion (and you may cancel the operation).
4.1.5.7 Clean Project
Deletes all files that are generated during compilation.

4 The IDE / 4.2 Code area

4.2

59

Basic4Android Beginner's Guide

Code area

The code of the selected module is displayed in this area and can be edited.
The examples below are based on the code of the SecondProgram.

4.2.1 Code header Project Attributes / Activity Attributes

Since Basic4Android version 2.5 a code header is added with general settings.
These settings were in the Project menu in the previous Basic4Android versions:
4.2.1.1 Project Attributes
Attributes that are valid for the whole project. Displayed only in the Main module.
#Region Project Attributes
#ApplicationLabel: B4A Example
#VersionCode: 1
#VersionName:
'SupportedOrientations possible values: unspecified, landscape or portrait.
#SupportedOrientations: unspecified
#CanInstallToExternalStorage: False
#End Region

4.2.1.2 Activity Attributes

Valid for the current activity.
#Region Activity Attributes
#FullScreen: False
#IncludeTitle: True
#End Region

When you load a project saved with a version of B4A older than 2.5 then the header will look like
this:
#Region Module Attributes
#FullScreen: False
#IncludeTitle: True
#ApplicationLabel: MyFirstProgram
#VersionCode: 1
#VersionName:
#SupportedOrientations: unspecified
#CanInstallToExternalStorage: False
#End Region

When you add a new Activity you'll find the Activity Attributes region on top.
#Region Activity Attributes
#FullScreen: False
#IncludeTitle: True
#End Region

When you add a new Service you'll find the Service Attributes header.
#Region Service Attributes
#StartAtBoot: False
#End Region

4 The IDE / 4.2 Code area

60

Basic4Android Beginner's Guide

When you want to add a new Attribute you can just write # and the inline help shows all
possibilities.

4 The IDE / 4.2 Code area

61

Basic4Android Beginner's Guide

4.2.2 Undo Redo

In the IDE it is possible to undo the previous operations and redo undone operations.
Click on

to undo and on

to redo.

4.2.3 Collapse a subroutine

In the IDE a subroutine can be collapsed to minimize the number of lines displayed.
The btnAction_Click routine expanded.
Click on to collapse the
subroutine.

The btnAction_Click routine collapsed.

Hovering with the mouse over the collapsed routine name shows its content.

4 The IDE / 4.2 Code area

62

Basic4Android Beginner's Guide

4.2.4 Collapse a Region

You can define Regions in the code, which can be collapsed.
Example:
#Region GPS sets the beginning of a region and
#End Region the end

Then you can add the subroutines between the two limits:

Then clicking on

collapses the whole region.

Hovering over GPS

shows the beginning of the code, not all the routines in the region.

4 The IDE / 4.2 Code area

63

Basic4Android Beginner's Guide

4.2.5 Collapse the whole code

In the Edit menu there are three

functions:
- Toggle All
Expands the collapsed
routines and collapses the
extended routines and regions.
- Expands All
Expands the whole code
- Collapse All
Collapses the whole code.

Clicking on Collapse All .

The whole code collapsed.

Hovering with the mouse over a

subroutine still shows the
beginning of its content.

4 The IDE / 4.2 Code area

64

Basic4Android Beginner's Guide

4.2.6 Commenting and uncommenting code

A selected part of the code can be set to comment lines or set to normal.

Original code

Select the code.

Click on

Lines set as comments.

To set the lines to normal,
select the lines and click on

4.2.7 Bookmarks
You can set 'bookmarks' anywhere in the code and jump forward and backwards between these
bookmarks.
To set a bookmark, position the cursor on the
desired line, 12 in this example.
Click on

The bookmark sign is displayed in the left

margin.
To remove a bookmark, position the cursor
on the line and click on
Click on

to jump forward to the next bookmark.

Click on

to jump backward to the previous bookmark.

In the

menu you can remove all bookmarks

4 The IDE / 4.2 Code area

65

Basic4Android Beginner's Guide

4.2.8 Indentation
A good practice is to use the indentation of code parts.
For example for subroutines, loops, structures etc.

This code is difficult to read because the

structure of the code is not obvious.

This code is much easier to read,

the structure of the code is in
evidence.
A tabulation value of 2 for the
indentation is a good value.

Example with an
indentation of 4
Personally,
I prefer a value of 2.

4 The IDE / 4.2 Code area

66

Basic4Android Beginner's Guide

Whole blocks of code can be indented forth and back at once.

Original code

Select the code block.

Click on

The whole block has moved one tabulation to the

right.
To move a block to the left.
Select the code and click on

The indentation value can be changed in the Tools menu.

Enter the value and click on

4 The IDE / 4.2 Code area

67

Basic4Android Beginner's Guide

4.2.9 Autocomplete
A very useful tool is the autocomplete function.
Example:
Let us write lblN
Press on Ctrl + Space or click on

All variables, views and property names

beginning with the letters already written are
shown in a popup menu with the online help
for the highlighted variable, view or
property name.
To choose lblNumber1 press Return.
To choose lblNumber2 press the down
arrow and press Return.

The selected name is completed.

After pressing "." all properties and methods are

displayed in a popup menu.

When selecting an item, the

internal help is displayed
Pressing on the up / down
arrows selects the previous
or next item with its help.
Pressing a character updates
the list and shows the
parameter beginning with
that character.
The best way to learn it is to 'play' with it.

4 The IDE / 4.2 Code area

68

Basic4Android Beginner's Guide

A second Autocomplete function allows you to create event subroutines.

Enter the Sub word plus a blank character.

Press Tab.

Select the type, Button in our example.

Select the type, Click in our example.

The subroutine frame is generated.

Modify 'EventName' to the EventName of the button, 'btnOK' in our case.

The routine is ready.

4 The IDE / 4.2 Code area

69

Basic4Android Beginner's Guide

4.2.10 Built in documentation

Since Basic4android V2.00 a new built-in documentation feature is available.
Comments above subs, such as:

Will automatically appear in the pop-up window:

If you want to add a code example you can use <code> tags:
Code:
'Parses a raw mail message and returns a Message object
'Mail - The mail raw text
'AttachmentsDir - Attachments will be saved in this folder
'
'Example: <code>
'Dim m As Message
'm = MailParser.ParseMail("Content-Type: text/plain; charset=" & QUOTE & "utf8" & QUOTE, File.DirRootExternal)
'Log(m)</code>

The code will be syntax highlighted:

4 The IDE / 4.2 Code area

70

Basic4Android Beginner's Guide

4.2.11 Jump to a subroutine

Sometimes it is useful to jump from a subroutine call to the subroutine definition.
This can easily be done :

Right click on the selected text.

Click on Goto Sub Declaration

Select the text of the subroutine call.

And you are there.

4 The IDE / 4.2 Code area

71

Basic4Android Beginner's Guide

4.2.12 Highlighting occurrences of words

When you select a single word, it is highlighted in dark blue and all the other occurrences in the
code are highlighted in light blue and in the scroll view on the right side.
With the slider you can move up or down the code to go to the other occurrences.

The same happens with Breakpoints.

4 The IDE / 4.2 Code area

72

Basic4Android Beginner's Guide

4.2.13 Debugging
To allow debugging you must activate one of the two debugging modes Debug (legacy) or
Debug (rapid) on top of the IDE.

4.2.13.1

Debug (legacy) mode

Let's first select Debug(legacy) : When this option is selected then the
compiled code will contain debugging code.
The debugging code allows the IDE to connect to the program and inspect
it while it runs.
When the program starts, it will wait for up to 10 seconds for the IDE to
connect. Usually the IDE will connect immediately. However if you run your program manually
from the phone you will see it waiting.
The name of the compiled APK file will end with _DEBUG.apk. You should not distribute this apk
file as it contains the debugging code which adds a significant overhead.
To distribute files you must select the Release or the Release (obfuscated) option.
When we run the program with the Debug (legacy) option, the IDE will open the debugger module
at the bottom of the screen:

Notes about the debugger:

Breakpoints in the following subs will be ignored: Globals, Process_Globals and
Activity_Pause.
Services - Breakpoints that appear after a call to StartService will be ignored. Breakpoints
set in Service_Create and Service_Start will pause the program for up to a specific time
(about 12 seconds). This is to prevent the OS from killing the Service.
Events that fire when the program is paused will be executed. Breakpoints in the event code
will be ignored (only when the program is already paused).
The data sent from the device to the IDE is limited in size. Long strings may be truncated.
When the debugger is running in legacy mode, the IDE is read-only. The user cannot change
any of the program text.
When the debugger is running in rapid mode, you can change the code and run the changes.

4 The IDE / 4.2 Code area

73

Basic4Android Beginner's Guide

The two major utilities for debugging are:

Breakpoints - You can mark lines of codes as breakpoints. This is done by pressing on the grey area
left of the line.
The program will pause when it reaches a breakpoint and will allow you to inspect the current state.
Logging - The Logs tab at the right pane is very useful. It shows messages related to the
components life cycle and it can also show messages that are printed with the Log keyword. You
should press on the Connect button to connect to the device logs. Note that there is a Filter
checkbox. When it is checked you will only see messages related to your program. When it is
unchecked you will see all the messages running in the system. If you are encountering an error and
do not see any relevant message in the log, it is worth unchecking the filter option and looking for
an error message.
Note that the log is maintained by the device. When you connect to a device you will also see
previous messages.

4 The IDE / 4.2 Code area

4.2.13.2

74

Basic4Android Beginner's Guide

Debug (rapid) mode

Since B4A version 3.0 a new Debug mode is available.

Improved since version 3.5, much more rapid and new features.
The rapid debugger is a very sophisticated debugger with features not
available in any other native Android development tool.
The rapid debugger is an important addition to Basic4android. It will increase your productivity as
it makes the "write code -> test result" cycle much quicker.
Using this deployment mode is similar to using the standard debugger ("legacy" debugger).
Rapid Debugger advantages

Very quick compilation and installation. Usually in less than one or two seconds.
In most cases (after the first installation) there is no need to reinstall the APK. This means
that the deployment is much quicker. With B4A-Bridge there is no need to approve the
installation.
Hot code swapping (edit and continue). You can modify the code while the app runs, hit
Save and the code will be updated.
Watch Expressions feature.
Powerful variables browser:

4 The IDE / 4.2 Code area

75

Basic4Android Beginner's Guide

Limitations:

The runtime execution in this mode is almost as rapid like non debugging. The rapid
debugger is not suitable for debugging "real-time" games or CPU intensive tasks. This is
why the legacy debugger is kept.
Hot code swapping is very powerful. You can even add subs or modify existing subs.
However you cannot add or remove global variables.
Unlike the legacy debugger, the app cannot run when the IDE is not connected. It will wait
for 10 seconds for the IDE to connect and then exit.

So how does the rapid debugger work?

I will start with an explanation about the legacy debugger. When you compile in Debug (legacy) the
B4A compiler creates a regular Android APK. However in addition to the program code the
compiler generates instrumented code. This means that for each line it adds a runtime check to test
whether there is a breakpoint on that line. If there is a breakpoint the program pauses by showing a
modal dialog and the variables data is sent to the IDE over the connection.
The rapid debugger works differently. When you compile your code it creates two applications. A
device application (shell) and a standard Java application (debugger engine).
Your code resides in the debugger engine. The debugger engine runs on the desktop. The shell
application is like a mini-virtual machine. The debugger engine connects to the shell app and sends
the instructions to the shell app. The interesting part of this is that your code is not executed on the
device. It is executed on the desktop.
In most cases the shell app can be reused. If for example you add a new file or edit the manifest file
with the manifest editor then the compiler will create a new shell app and will reinstall it
automatically during compilation.
The standard JVM is more powerful than the Android Dalvik machine. For example, it allows
classes to be loaded at runtime. This is how code swapping is supported.

4 The IDE / 4.2 Code area

76

Basic4Android Beginner's Guide

Small example, the code DebugRapid.b4a is in the DebugRapid folder in the source code folder :

If you click on the Draw

button the red line is drawn.

In the code change

line y1 = 150dip to y1 = 250dip

and hit Ctrl + s

or click on

In the Debug rapid mode a new button has been added.

It allows the program to be restarted.
Click on the Draw button, a new line with the new coordinate is
drawn without rerunning the program.

4 The IDE / 4.2 Code area

77

Basic4Android Beginner's Guide

Changing the layout in the code:

In the code change

the line btnDraw.Left = 100dip

and hit Ctrl + s

to btnDraw.Left = 10dip

and click on

The Button has moved without stopping and rerunning the

program.

If you set a breakpoint in the code and run it, you will find a window in the lower part of the screen
showing all objects with their properties and all variables with their current values.

You can open and close objects or variables by clicking on

Right click on an item to copy its value to the clipboard.

or

4 The IDE / 4.2 Code area

78

Basic4Android Beginner's Guide

You can click on a variable in the code to show its value in the variable browser.

Clicking on the variable y1 in the

code shows the variable with its value
in the variable browser.

Other example:
Clicking on the variable col .

Clicking on an object in the code, btnDraw in the example, shows all properties of this object in the
variable browser.

4 The IDE / 4.2 Code area

79

Basic4Android Beginner's Guide

Watch Expressions feature

At the right side of the debugger buttons we find a TextBox Add Watch :

To watch the Right coordinate of btnDraw we enter

100%x (btnDraw.Left + btnDraw.Width) and click on

This adds a new watch expression in the list with its value.

Clicking on

removes all watch expressions.

Now we wnt to know the length of the line in pixels:

We add Sqrt(Power((x2 - x1), 2) + Power((x2 - x1), 2))
And click on

4 The IDE / 4.2 Code area

4.2.13.3

80

Basic4Android Beginner's Guide

Release and Release (obfuscated) modes

To distribute your project you must compile it with:

Release
The debugger code will not be added to the apk file.
Release (obfuscated)
The debugger code will not be added to the apk file,
but the program file will be modified. See below.
Basic4Android v1.8 includes a new code obfuscation feature.
During compilation Basic4android generates Java code which is then compiled with the Java
compiler and converted to Dalvik (Android byte code format).
There are tools that allow decompilation of Dalvik byte code into Java code.
The purpose of obfuscation is to make the decompiled code less readable, harder to understand and
make it more difficult to extract strings like developer account keys.
It is important to understand how the obfuscator works.
The obfuscator does two things:
Strings obfuscation
Any string written in Process_Globals sub (and only in this sub) will be obfuscated, making it much
harder to extract important keys. The strings are deobfuscated at runtime.
Note that several keys are used during obfuscation including the package name, version name and
version code. Modifying these values with the manifest editor will break the deobfuscation process.
Variables renaming
The names of global variables and subs are converted to meaningless strings. Local variables are
not affected as their names are lost anyway during the compilation.
The following identifiers are not renamed:
- Identifiers that contain an underscore (required for the events handlers).
- Subs that appear in CallSub statements. When a sub name appears as a static string, the identifier
be kept as it is.
- Designer views names.
Tip: If, for some reason, you wish to prevent obfuscation of an identifier, include an underscore
character in the name.
A file named ObfuscatorMap.txt will be created under the Objects folder. This file maps the
original identifiers names to the obfuscated names. This mapping can be helpful in analysing crash
reports.
Activating the obfuscator
Basic4android version 1.8 makes it simpler to choose the compilation mode.

4 The IDE / 4.2 Code area

81

Basic4Android Beginner's Guide

4.2.14 Breakpoints
Clicking on a line in the left margin adds a breakpoint. When the program is running it stops at the
first breakpoint. Breakpoints, in Globals, Process_Globals and Activity_Pause are ignored.
The IDE behaves differently depending on the debug mode. The examples below are for the
legacy debug mode. For the rapid debug mode look in the Debug (rapid) mode chapter.

Run the program, the program stops at the breakpoint and the IDE looks like below. The breakpoint
line is highlighted in yellow.

At the bottom of the IDE you find other information.

Debugger is connected.
Double click to detach the Debugger.
Name of the routine where the program stopped.
New routine at line 52.
Caller of New routine : Activity_Create routine in line 24.
Clicking on these links jumps the cursor to the given line.

4 The IDE / 4.2 Code area

82

Basic4Android Beginner's Guide

Continue code execution (F5).

Continues the execution until the end or the next breakpoint.
Step to the next line (F8).
Continues execution of the code to the next line. Very useful during debugging to see
the program flow and monitor variable values.
Pause the code as soon as possible.
Stop the current program (F11).
Also stops the program in the Emulator.
Stopping the program in the Emulator doesn't stop it in the IDE !

Global variables.
List of the global
objects and variables
used by the program
with their values and
properties.

Examples:
btnAction: Type = Button Left = 190 Top = 0 Width = 115 Height = 55 Tag = empty Text = OK
Number1 = 6

Local variables.
None in this example.

Hovering with the mouse over a variable shows

its value.

Hovering with the mouse over a view shows its properties like in the list.

4 The IDE / 4.2 Code area

83

Basic4Android Beginner's Guide

Let us run the program step by step:

Set a breakpoint at line 50.
Click on

to run the program or press F5.

The program will stop at line 50.

Values of the two numbers in the

Global variables window,
it has been reduced to just show the two numbers.

Click on F8.
The program executes the next code line.

The value of Number1 has changed !

Click on F8.
The program executes the next code line.

The value of Number2 has changed !

4 The IDE / 4.2 Code area

84

Basic4Android Beginner's Guide

4.2.15 Color Picker

A new feature since Basic4Android version 3 is the Color Picker.
In the code, right click to show the menu below and click on Show Color Picker.

The Color Picker will be displayed.

Select a color, and its value will be copied to the Clipboard. You may then paste the value into your
code.

4 The IDE / 4.3 Tabs

4.3

85

Basic4Android Beginner's Guide

Tabs

There are 4 tabs at the bottom right corner of the IDE that
display the following information.

4.3.1 Module and subroutine lists

All the modules of the project and all subroutines of the selected module are listed in two lists at the
right of the IDE. The picture below has been reduced in height.
Module list
Clicking on a module shows its code in the code area.
Find Sub Tool (Ctrl + E)
Find All References (F7)

see below
see below

Subroutine list of the selected module.

Clicking on a subroutine shows its code in the middle of
the code area.

In the IDE, in the bottom right corner.

4 The IDE / 4.3 Tabs

86

Basic4Android Beginner's Guide

4.3.1.1 Find Sub Tool (Ctrl + E)

This is a search engine to find subroutines with a given name or with a given part of the name.
If you click on
or press Ctrl + E, you get the screen below showing a list of
subroutines according to the text entered in the TextBox.
If no text is entered, the first 10 routines of the selected module are shown.
Example with the code of MyFirstProgram.

Clicking on one item shows the

code of the selected routine.

Even if it's in another module.

Enter Act into TextBox.

All routines in all modules
containing 'act' in their name will be
displayed.

4 The IDE / 4.3 Tabs

87

Basic4Android Beginner's Guide

4.3.1.2 Find All References (F7)

This is a search engine to find all references for a given object (view, variable).
If you click on
or press F7 you get the screen below showing a list of all code
lines with the selected reference or the first object in the current line.
Example with the code of MyFirstProgram.
Select in the code in line 49 Number1.

Click on
object.

you get the list below with all code lines containing the selected

Clicking on a line in the list shows that line in the middle of the IDE code area.

4 The IDE / 4.3 Tabs

88

Basic4Android Beginner's Guide

4.3.2 Files
This window lists all the files that have been added to the project.
These files are saved in the Files subfolder under your main project folder.
These can be any kind of files: layouts, images, texts, etc.

Click on
to add files to the list.
The files in that subfolder can be accessed from your
program by using the reference File.DirAssets.

In the IDE, in the bottom right corner.

Checking one or more files enables the

button.

Clicking on this button removes the selected files from the

list and from the Files folder of the project.

You are asked if you want to

delete the files from the 'Files'
folder.
Oui
= Yes
Non
= No
Annuler = Cancel

Make sure to have a copy of the files you remove, because they are removed from the Files
folder, but not transferred to the Recycle Bin, which means that they are definitely lost if you
don't make a copy.

See chapter Files for file handling.

4 The IDE / 4.3 Tabs

89

Basic4Android Beginner's Guide

4.3.3 Logs
Display of Log comments generated by the program when it is running.
We add the two lines 51 and 53 in the program 'SecondProgram' in the 'New' routine.
The number of the lines may be different from yours.

Run the program.

Click on

to connect the logger.

In the window we see the flow of the
program.
Activity (main) Create, isFirst = true
First log message
Second log message
Activity (main) Resume

In the IDE, in the bottom right corner.

When Filter is checked you will only see messages related to your program. When it
is unchecked you will see all the messages running in the system. If you are encountering an error
and do not see any relevant message in the log, it is worth unchecking the filter option and looking
for an error message
Click

to clear the Logs window.

If the debugger is still running, do one of the following to edit the code :
- Select Debug > Stop from the IDE menu.
- Press F11 shortcut key.
-

Or click on

4 The IDE / 4.3 Tabs

90

Basic4Android Beginner's Guide

4.3.3.1 Test Compile / Warnings

Starting from v2.70, Basic4android includes a warning engine. The purpose of the warning engine
is to find potential programming mistakes as soon as possible.
The warning engine runs :
- whenever you compile the project
- when you click on
- when you save the project.

in the

menu, or

The compile-time warnings appear above the logs and in the code itself when hovering with the
cursor above the code line.
The code lines which caused the warning are underlined like
this .

Clicking on the warning in the list will take you to the relevant code.
Ignoring warnings
You, as the developer, can choose to ignore any warning. Adding an "ignore" comment will disable
all the warnings for that specific line:
Sub UnusedSub(a As Int) 'ignore

You can also disable warnings from a specific type in the module by adding the #IgnoreWarning
attribute in the Project Attributes or Module Attributes regions.
For example, to disable warnings #10 and #12:
#Region Project Attributes
#ApplicationLabel: Warnings
#VersionCode: 1
#VersionName:
'SupportedOrientations possible values: unspecified, landscape or portrait.
#SupportedOrientations: unspecified
#CanInstallToExternalStorage: False
#IgnoreWarnings: 10, 12
#End Region

4 The IDE / 4.3 Tabs

91

Basic4Android Beginner's Guide

Runtime warnings
Some of the warnings are only checked at runtime. These warnings will appear in the regular logs.
Runtime warnings are only checked in Debug mode.
List of warnings
1: Unreachable code detected.
2: Not all code paths return a value.
3: Return type (in Sub signature) should be set explicitly.
4: Return value is missing. Default value will be used instead.
5: Variable declaration type is missing. String type will be used.
6: The following value misses screen units ('dip' or %x / %y): {1}.
7: Object converted to String. This is probably a programming mistake.
8: Undeclared variable '{1}'.
9: Unused variable '{1}'.
10: Variable '{1}' is never assigned any value.
11: Variable '{1}' was not initialized.
12: Sub '{1}' is not used.
13: Variable '{1}' should be declared in Sub Process_Globals.
14: File '{1}' in Files folder was not added to the Files tab.\nYou should either delete it or add it to
the project.\nYou can choose Tools - Clean unused files.
15: File '{1}' is not used.
16: Layout file '{1}' is not used. Are you missing a call to Activity.LoadLayout?
17: File '{1}' is missing from the Files tab.
18: TextSize value should not be scaled as it is scaled internally.
19: Empty Catch block. You should at least add Log(LastException.Message).
20: View '{1}' was added with the designer. You should not initialize it.
21: Cannot access view's dimension before it is added to its parent.
22: Types do not match.
23: Modal dialogs are not allowed in Sub Activity_Pause. It will be ignored.
24: Accessing fields from other modules in Sub Process_Globals can be dangerous as the
initialization order is not deterministic.
'Runtime warnings
1001: Panel.LoadLayout should only be called after the panel was added to its parent.
1002: The same object was added to the list. You should call Dim again to create a new object.
1003: Object was already initialized.
1004: FullScreen or IncludeTitle properties in layout file do not match the activity attributes
settings.

1: Unreachable code detected.

There is some code which will never be executed.
This can happen if you have some code in a Sub after a Return statement.

4 The IDE / 4.3 Tabs

92

Basic4Android Beginner's Guide

2: Not all code paths return a value.

Sub Calc(Val1 As Double, Val2 As Double, Operation As String) As Double
Select Operation
Case "Add"
Return (Val1 + Val2)
Case "Sub"
Return (Val1 - Val2)
Case "Mult"
Return (Val1 * Val2)
Case "Div"
End Select
End Sub

In the Case "Div" path no value is returned !

Other example:
Wrong code
Sub Activity_KeyPress(KeyCode As Int) As Boolean
Dim Answ As Int
Dim Txt As String
If KeyCode = KeyCodes.KEYCODE_BACK Then' Checks if the KeyCode is BackKey
Txt = "Do you really want to quit the program ?"
Answ = Msgbox2(Txt,"A T T E N T I O N","Yes","","No",Null) ' MessageBox
If Answ = DialogResponse.POSITIVE Then
' If return value is Yes then
Return False
' Return = False the Event will not be consumed
Else
' we leave the program
Return True
' Return = True
the Event will be consumed to avoid
End If
' leaving the program
End If
End Sub

Correct code
Sub Activity_KeyPress(KeyCode As Int) As Boolean
Dim Answ As Int
Dim Txt As String
If KeyCode = KeyCodes.KEYCODE_BACK Then' Checks if the KeyCode is BackKey
Txt = "Do you really want to quit the program ?"
Answ = Msgbox2(Txt,"A T T E N T I O N","Yes","","No",Null) ' MessageBox
If Answ = DialogResponse.POSITIVE Then
' If return value is Yes then
Return False
' Return = False the Event will not be consumed
Else
' we leave the program
Return True
' Return = True
the Event will be consumed to avoid
End If
' leaving the program
Else
Return True
' Return = True
the Event will be consumed to avoid
End If
' leaving the program
End Sub

3: Return type (in Sub signature) should be set explicitly.

Wrong code
Sub Calc(Val1 As Double, Val2 As Double, Operation As String)

Correct code
Sub Calc(Val1 As Double, Val2 As Double, Operation As String) As Double

The return type must be declared !

4 The IDE / 4.3 Tabs

93

Basic4Android Beginner's Guide

4: Return value is missing. Default value will be used instead.

Wrong code
Sub CalcSum(Val1 As Double, Val2 As Double) As Double
Dim Sum As Double
Sum = Val1 + Val2
Return
End Sub

Correct code
Sub CalcSum(Val1 As Double, Val2 As Double) As Double
Dim Sum As Double
Sum = Val1 + Val2
Return Sum
End Sub

5: Variable declaration type is missing. String type will be used.

Wrong code
Sub Calc(Val1, Val2 As Double, Operation As String) As Double

Correct code
Sub Calc(Val1 As Double, Val2 As Double, Operation As String) As Double

In sub declarations each variable needs its own type declaration.

But in Dim declarations it's allowed, in the line below both variables are Doubles:
Dim Val1, Val2 As Double

6: The following value misses screen units ('dip' or %x / %y): {1}.

Wrong code
Activity.AddView(lblTest, 10, 10, 150, 50)

Correct code
Activity.AddView(lblTest, 10dip, 10dip, 150dip, 50dip)

In the example above you will get four warnings, one for each value.
For view dimensions you should use dip, %x or %y values.
See chapter 5.1 Special functions like 50%x, 50dip
7: Object converted to String. This is probably a programming mistake.
8: Undeclared variable '{1}'.
Wrong code
Sub SetHeight
h = 10dip
End Sub

Correct code
Sub SetHeight
Dim h As Int
h = 10dip
End Sub

The variable h was not declared. You see it also with the red color.

4 The IDE / 4.3 Tabs

94

Basic4Android Beginner's Guide

9: Unused variable '{1}'.

Sub SetHeight
Dim h As Int
h = 10dip
End Sub

This warning tells that the variable h is not used.

It is declared and assigned a value, but it is not used !
This code gives no warning because variable h is used:
Sub SetHeight
Dim h As Int
h = 10dip
lblTest.Height = h
End Sub

10: Variable '{1}' is never assigned any value.

Sub Test
Dim h As Int
End Sub

This warning shows that the variable h is declared but not assigned any value.
Correct code see above.
11: Variable '{1}' was not initialized.
Wrong code
Dim lst As List
lst.Add("Test1")

Correct code
Dim lst As List
lst.Initialize
lst.Add("Test1")

Variables (objects) like List or Map must be initialized before they can be used.
Views added by code must also be initialized before they can be added to a parent view.
12: Sub '{1}' is not used.
This warning is displayed if a Sub routine is never used.
13: Variable '{1}' should be declared in Sub Process_Globals.
Wrong code :
Sub Globals
Dim Timer1 As Timer
Dim GPS1 As GPS

Correct code :
Sub Process_Globals
Dim Timer1 As Timer
Dim GPS1 As GPS

Certain objects like Timers and GPS should be declared in Process_Globals, not in Globals.

4 The IDE / 4.3 Tabs

95

Basic4Android Beginner's Guide

14: File '{1}' in Files folder was not added to the Files tab.
You are using a file which is in the Files folder, but was not added to the Files tab.
You should:
- Make a backup copy.
- Delete it from the Files subfolder.
- Add it to the project in the Files tab.
- Use Clean Files Folder (unused files) in the Tools menu.

15: File '{1}' is not used.

You have files in the Files folder that are not used.
You should remove them from the Files folder.
Or you can clean the Files folder from within the Tools menu (see above).
16: Layout file '{1}' is not used. Are you missing a call to Activity.LoadLayout?
You have a layout file in the Files folder that is not used.
You should add LoadLayout or you can remove the layout file from the Files folder.
Or you can clean the Files folder in the Tools menu.

17: File '{1}' is missing from the Files tab.

The given file is in the Files tab but is missing in the Files folder. You should add it.
See chapter 4.3.2 Files
18: TextSize value should not be scaled as it is scaled internally.
Wrong code
lblTest.TextSize = 16dip

Correct code
lblTest.TextSize = 16

TextSize values are pixel and density independent. Their unit is the typographic point, a
typographic unit, and must be given absolute values and not dip values.

4 The IDE / 4.3 Tabs

96

Basic4Android Beginner's Guide

19: Empty Catch block. You should at least add Log(LastException.Message).

Wrong code
Try
imvImage.Bitmap = LoadBitmap(File.DirRootExternal, "image.jpg")
Catch
End Try

Correct code
Try
imvImage.Bitmap = LoadBitmap(File.DirRootExternal, "image.jpg")
Catch
Log(LastException.Message)
End Try

It is recommended to add at least Log(LastException.Message) in the Catch block instead of

leaving it empty.
20: View '{1}' was added with the designer. You should not initialize it.
A View defined with the Designer in a layout file must not be initialized !
Only views added by code need to be initialized.
21: Cannot access view's dimension before it is added to its parent.
You must add a view to a parent view before you can access its dimensions.
When you add a view by code its dimensions are defined when you add it with AddView.
22: Types do not match.
23: Modal dialogs are not allowed in Sub Activity_Pause. It will be ignored.
Modal dialogs like MessageBox should not be used in the Activity_Pause routine.
24: Accessing fields from other modules in Sub Process_Globals can be dangerous as the
initialization order is not deterministic.

4 The IDE / 4.3 Tabs

97

Basic4Android Beginner's Guide

4.3.4 Libs
The Libs tab contains a list of the available libraries that can be used in the project.
Check the libraries you need for your project.
Make sure that you have the latest version of the libraries.

In the IDE, in the bottom right corner.

On the top of the tab you find a field to filter the libraries.

Enter AH in the fiesl and you gat all libraries beginning with AH.

The list of all additional libraries can be found here : Additional Libraries.
The documentation for libraries can be found here :
Basic4android - Android programming with Gui designer

Look also at chapter Libraries.

5 Screen sizes and resolutions

98

Basic4Android Beginner's Guide

Screen sizes and resolutions

There exist many different screen sizes with different resolutions and pixel densities.
We must explain the difference between the following parameters.
- Physical screen size
Ex: 3.6 '' diagonal
- Resolution in pixels
Ex: 320 / 480
- Density pixels per inch
Ex: 160
The standard screen is 320 / 480 pixels, density 160 pixels/inch.
There exist other screens with almost the same physical size but with a higher resolution (for
example 480 / 640 pixels with a density of 240 pixels/inch).
Tablets have bigger physical sizes but can have a density similar to the standard screen.
Example: 7.2 '' screen diagonal, 640 / 960 pixels and a density of 160 pixels/inch.
A non-exhaustive list of screens:
Diagonal
3.5
3.5
3.9
3.5
5
7
7
10
10
10

Resolution
320 / 480
480 / 720
480 / 800
240 / 320
1080 / 1920
640 / 960
800 / 1280
768 / 1024
800 / 1280
1200 / 1920

Let us compare the following resolutions:

1)
320 / 480 / 160
screen ~3.5''
2)
480 / 800 / 240
screen ~3.5''
3)
640 / 960 / 320
screen ~3.5''
4)
640 / 960 / 160
~7'' screen

Density
160
240
240
120
480
160
160
160
160
240

Scale
1
1.5
1.5
0.75
3
1
1
1
1
1.5

W / H Ratio
3/2
3/2
5/3
4/3
4/3
3/2
16 / 9
4/3
16 / 10
16 / 10

standard density 160

density 240
density 320
standard density 160

In cases 1) 2) and 3) the physical sizes of the screens are the same but the density of the pixels is
different.
In cases 1) and 4) the densities are the same, but the physical dimensions of the screen in case 4)
are double the dimensions of screen 1), yielding 4 times the area, and 4 times total number of
pixels.
Let us look at the physical size of a button with 80 / 80 dip.
dips
pixels
inch
1)
80
80
0.5
2)
80
120
0.5
2)
-80
0.375
dimension given in pixels not in dips
3)
80
160
0.5
3)
-80
0.25
dimension given in pixels not in dips
4)
80
80
0.5
dip = density independent pixel
It is possible to generate special Emulators with special sizes, resolutions and densities.

5 Screen sizes and resolutions

99

Basic4Android Beginner's Guide

A same layout can fit into different screen resolutions, but with some restrictions.
We will use the TestLayouts program to test the same layout with different screen resolutions.
The source code is in the <Guide>\SourceCode\TestLayouts directory.
The different resolutions are:
Screen
resolution
240 / 320
320 / 480
480 / 800

Density

H / W ratio

120
160
240

4/3
3/2
5/3

Equivalent
height pixels
360
480
720

Pixel diff.
- 40
0
+ 80

The reference resolution is 320 / 480 with a density of 160.

If we calculate, for the two other resolutions, the equivalent height using the same H/W ratio we get
the equivalent height in pixels and the difference in pixels.
This means that with the same layout file for all three resolutions there will be 40 pixels missing
with the 240/320 resolution and 80 extra pixels with the 480/800 resolution.

The original layout in the standard 320/480 pixels density 160

Emulator is the following.
To make the tests we need three emulators:
- 320 / 480 density 160
- 240 / 320 density 120
- 480 / 800 density 240
If you do not have these emulators, you must create them in the AVD
Manager. Look here to generate an Emulator.

And the code is:

Sub Globals
' These global variables will be redeclared each time the activity Is created.
' These variables can only be accessed from this module.
Dim ListView1 As ListView
Dim pnlToolBox As Panel
End Sub
Sub Activity_Create(FirstTime As Boolean)
Dim i As Int
Activity.LoadLayout("MainLayout")
For i=0 To 10
ListView1.AddSingleLine("Test "&i)
Next
If Activity.Height>Activity.Width Then
'
pnlToolBox.Top=Activity.Height-pnlToolBox.Height
'
ListView1.Height=pnlToolBox.Top-ListView1.Top-10dip
Else
'
pnlToolBox.Left=Activity.Width-pnlToolBox.Width
'
ListView1.Width=pnlToolBox.Left-ListView1.Left-10dip
End If
End Sub

1.3 Installing Android Emulator

100

Basic4Android Beginner's Guide

Note that lines 38 and 39 are commented out (lines 41 and 42 too for landscape)!
Tests with the three Emulators with different resolutions and different densities.

480 / 800 240

320 / 480 160

240 / 320 120

The image sizes are reduced by a factor of 0.5 for easier comparison.
What we see:
- with the standard resolution, the image in the emulator is equal to the original layout.
- with the 240/320 resolution we see that there are the 'expected' 40 pixels missing.
- with the 480/800 resolution, we see that there are the 'expected' 80 extra pixel.
The numbers of items in the ListView are the same for all three resolutions.

5 Screen sizes and resolutions

101

Basic4Android Beginner's Guide

Second test with lines 38 and 39 activated (and 41 and 42 for landscape).
If Activity.Height>Activity.Width Then
pnlToolBox.Top=Activity.Height-pnlToolBox.Height
ListView1.Height=pnlToolBox.Top-ListView1.Top-10dip
Else
pnlToolBox.Left=Activity.Width-pnlToolBox.Width
ListView1.Width=pnlToolBox.Left-ListView1.Left-10dip
End If

In line 38 we calculate the top of the pnlToolBox panel according to the screen height.
In line 39 we calculate the ListView height according to the top of the pnlToolBox.

What we see:
- with the standard resolution, the image in the emulator is still equal to the original layout.
- with the 240/320 resolution we see that the buttons are at the bottom of the screen but the
ListView height is shortened.
- with the 480/800 resolution we see that the buttons are at the bottom and the ListView is
higher.
The numbers of items in the ListView is different in the three layouts because the ListView height
has been adapted to the different relative screen heights.
In the first test, the number of items in the ListView were the same !
These examples show that it is not easy to have one layout for different screen resolutions.
In the example above it was relatively easy because the view in the middle is easily adjustable.

5 Screen sizes and resolutions

102

Basic4Android Beginner's Guide

Even when we load the layout file in the three emulators with resolutions 480 / 800, 320 / 480 and
240 / 320 pixels the layout is stretched or compressed according to the screen size, but of course we
also see extra or missing pixels depending on the different relative screen heights.
The Android OS autoscale system adjusts the Left, Top, Width, Height, FontSize and other
properties with the scale factor but does NOT resize the vertical positions nor the heights of the
views proportional to the screen height. The same is valid for the width in landscape mode.

5 Screen sizes and resolutions

5.1

103

Basic4Android Beginner's Guide

Special functions like 50%x, 50dip

There are special functions to accommodate different screen sizes and resolution.

5.1.1 PerXToCurrent, PerYToCurrent - 50%x

PerXToCurrent(Percentage As Float)

or

50%x

PerXToCurrent(50) means 50% of the Activity width.

It can be written as a shortcut: 50%x.

50%x is equal to Activity.Width * 0.5
PerYToCurrent(30) means 30% of the Activity height.

It can be written as a shortcut: 30%y.

30%y is equal to Activity.Height * 0.3
In the Designer Scripts 100%x and 100%y refer to the dimensions of the view where the layout file
is loaded.
If the layout file is loaded :
onto the Activity then 100%x = Activity.Width and 100%y = Activity.Height
onto a Panel then 100%x = Panel.Width and 100%y = Panel.Height

5.1.2 DipToCurrent - 50dip

DipToCurrent(Length As Int)

or

50dip

DipToCurrent calculates a dimension with the given Length according to the scale of the current
device.
DipToCurrent(50) is equal to 50 * DeviceScale
It can be written as a shortcut: 50dip density independent pixel
The 'standard' resolution is 160 dpi (dots per inch) and scale 1.
No spaces between the number and dip!
If we have a Button with a dimension of 50 * 50 pixels standard scale, to define its dimensions we
should set Button1.Width = 50dip and Button1.Height = 50dip.
Depending on the scale, the Button dimension will be:
Scale
Pixels
1
50 * 50
1.5
75 * 75
Example:
Dim Button1 As Button
Button1.Initialize("Button1")
Activity.AddView(Button1, 20%x, 30%y, 100dip, 50dip)

The values for the Left, Top, Width and Height properties in the Designer are considered as
dip values.

5 Screen sizes and resolutions

5.2

104

Basic4Android Beginner's Guide

Working with different screen sizes / number of layouts

With the big number of devices, screen sizes, and resolutions on the market, it becomes more and
more complicated to design a project that looks nice on all available devices.
There is no universal method to manage this problem. The method you choose depends on :
What kind of project you are designing.
What devices and screen sizes you are targeting.
What you want to show on the different screens.
The same layout but stretched according to the screen sizes, or
Different layout variants for the different sizes. On a big screen more views can be
displayed at the same time.
Summary of the different physical screen sizes, where each size can have different resolutions,
densities scales and aspect ratios.
resolution density scale aspect ratio
~ 3.0'' - 4.0 ''
320 / 240
120 0.75 4 / 3
1.333
480 / 320
160 1
3/2
1.5
640 / 480
240 1.5
4/3
1.333
800 / 480
240 1.5
5/3
1.667
854 / 480
240 1.5
16 / 9 1.78
960 / 540
240 1.5
16 / 9 1.78
960 / 640
240 1.5
3/2
1.5
1280 / 720
320 2
16 / 9 1.78
~ 5.5 ''
1280 / 800
240 1.5
16 / 10 1.6
~ 7 ''
1024 / 600
160 1
1.71
1280 / 800
160 1
16 / 10 1.6
~ 10 ''
1024 / 600
160 1
1.71
1024 / 768
160 1
4/3
1.333
1280 / 800
160 1
16 / 10 1.6
1920 / 1200 240 1.5
16 / 10 1.6

Depending on what you want to display on the different screens you can either :
Design different layout variants.
Two layout variants (portrait and landscape) for each dimension.
The views are automatically resized for the different densities.
However, you may need to take into account different width/height ratios (aspect ratios).
These adjustment could be done in the code or would need two more layout variants.
Calculate all view dimensions and positions in the code using %x , %y and dip dimensions.
For comparison :
A 5.5'' screen has a surface about 2.5 times bigger than a 3.5'' screen.
A 7'' screen has a surface about 4 times bigger than a 3.5'' screen.
A 10'' screen has a surface about 9 times bigger than a 3.5'' screen.

5 Screen sizes and resolutions

105

Basic4Android Beginner's Guide

The examples below show the same layout stretched in the code to fit the different screen sizes.
The source code is OneLayoutStretched, the images are Emulator screenshots.

~3.5'' 240 / 320

~3.5'' 320 / 480

7 '' 800 / 1280 / 160

~3.5'' 480 / 800

~5.5'' 800 / 1280 / 240

10 '' 800 / 1280 / 160

It's probably not the best solution to have the same layout stretched for all screen sizes.
It could be more interesting to show more views on bigger screens.

5 Screen sizes and resolutions

106

Code to check the device type :

Sub CheckDeviceType
' check device type, used to define text sizes
' should be completed if necessary
lv = GetDeviceLayoutValues
Select lv.Scale
Case 2
DeviceType = "Smartphone 5"
TextSizeRatio = 1.5
Case 1.5
If lv.Width > 1100 Then
DeviceType = "Tablet 7"
TextSizeRatio = 2
Else
DeviceType = "Smartphone 3.5"
TextSizeRatio = 1
End If
Case 1
If lv.Width > 1100 Then
DeviceType = "Tablet 10"
TextSizeRatio = 3
Else If lv.Width < 600 Then
DeviceType = "Smartphone 3.5"
Else
DeviceType = "Tablet 7"
TextSizeRatio = 2
End If
End Select
End Sub

Part of the code for setting the view dimensions.

Sub InitLayout
Dim wb As Int
If Activity.Width > Activity.Height Then
wb = 100%y / 4
pnlToolbox.Left = 100%x - wb
pnlToolbox.Width = wb
pnlToolbox.Height = 100%y
pnlToolbox.Top = 0
btnTest1.Left = 0
btnTest1.Width = wb
btnTest1.Top = 0
btnTest1.Height = wb
.
lblTitle.Left = 10%x
lblTitle.Width = 80%x - wb
lblTitle.Top = 0
lblTitle.Height = 100%y / 8
lstTest.Left = 5%x
lstTest.Width = 90%x - wb
lstTest.Top = lblTitle.Height
lstTest.Height = 100%y - lstTest.Top
lstTest.TwoLinesLayout.Label.Height = 12%y
lstTest.TwoLinesLayout.Label.Top = 0
lstTest.TwoLinesLayout.SecondLabel.Height = 10%y

Basic4Android Beginner's Guide

5 Screen sizes and resolutions

107

Basic4Android Beginner's Guide

lstTest.TwoLinesLayout.SecondLabel.Top = 12%x
lstTest.TwoLinesLayout.ItemHeight = 24%y
Else
wb = 100%x / 4
pnlToolbox.Left = 0
pnlToolbox.Width = 100%x
pnlToolbox.Height = wb
pnlToolbox.Top = 100%y - wb
btnTest1.Left = 0
btnTest1.Width = wb
btnTest1.Top = 0
btnTest1.Height = wb
.
lblTitle.Left = 10%x
lblTitle.Width = 80%x
lblTitle.Top = 0
lblTitle.Height = 100%x / 8
lstTest.Left = 5%x
lstTest.Width = 90%x
lstTest.Top = lblTitle.Height
lstTest.Height = pnlToolbox.Top - lstTest.Top
lstTest.TwoLinesLayout.Label.Height = 12%x
lstTest.TwoLinesLayout.Label.Top = 0
lstTest.TwoLinesLayout.SecondLabel.Height = 10%x
lstTest.TwoLinesLayout.SecondLabel.Top = 12%x
lstTest.TwoLinesLayout.ItemHeight = 22%x
End If
btnTest1.Text = "Test 1"
btnTest1.TextSize = 16 * TextSizeRatio
btnTest2.Text = "Test 2"
btnTest2.TextSize = 16 * TextSizeRatio
btnTest3.Text = "Test 3"
btnTest3.TextSize = 16 * TextSizeRatio
btnTest4.Text = "Test 4"
btnTest4.TextSize = 16 * TextSizeRatio
lblTitle.Text = "Test layout"
lblTitle.TextSize = 20 * TextSizeRatio
lstTest.TwoLinesLayout.Label.TextSize = 20 * TextSizeRatio
lstTest.TwoLinesLayout.Label.Gravity = Gravity.CENTER_VERTICAL
lstTest.TwoLinesLayout.Label.Color = Colors.Blue
lstTest.TwoLinesLayout.SecondLabel.TextSize = 16 * TextSizeRatio
lstTest.TwoLinesLayout.SecondLabel.Gravity = Gravity.CENTER_VERTICAL
lstTest.TwoLinesLayout.SecondLabel.Color = Colors.Green
End Sub

5 Screen sizes and resolutions

108

Basic4Android Beginner's Guide

In the examples below we see the display of a grid with buttons. The physical button dimensions are
almost the same. The source code is CodeLayout.

3.5''

5.5''

10''

The source code :

Dim i, j, k, nx, ny, x0, x1, x2 As Int
x0 = 4dip
x1 = 60dip
x2 = x0 + x1
nx = Floor(Activity.Width / x2) - 1
ny = Floor(Activity.Height / x2) - 1
k = 0
For j = 0 To ny
For i = 0 To nx
k = k + 1
Dim btn As Button
btn.Initialize("btn")
btn.Color = Colors.Red
Activity.AddView(btn, x0 + i * x2, x0 + j * x2, x1, x1)
btn.Text = k
btn.TextSize = 20
Next
Next

5 Screen sizes and resolutions

109

Basic4Android Beginner's Guide

If you want to display more views on bigger screens you must define two layout variants (one for
portrait and one for landscape) for each screen size and resolution. This can become quite
cumbersome.
A compromise could be made by defining the layouts partly in the layout files and partly in the
code.
The adaptation of different aspect ratios could be done in the code rather than in separate layout
variants.
As already mentioned, there is no universal rule, the solution depends on different factors.
As a developer, you must define your needs and requirements as a function of :
What kind of project you are designing.
What kind of data you are treating, displaying, editing, etc.
What devices and screen sizes you are targeting.
What you want to show on the different screens.
The same layout, but stretched according to the screen size, or
Different layout variants for different sizes. On a big screen more views can be displayed
at the same time.

5 Screen sizes and resolutions

5.3

110

Basic4Android Beginner's Guide

Screen orientations

Three different screen orientation values can be defined:

Portrait only
Landscape only
Both
These orientations can be defined either:
In the code on top in the Project Attributes region.
#Region Project Attributes
#ApplicationLabel: MyFirstProgram
#VersionCode: 1
#VersionName:
#SupportedOrientations: unspecified
#CanInstallToExternalStorage: False
#End Region

In this line:
#SupportedOrientations: unspecified

The possible orientation values are :

#SupportedOrientations: unspecified
#SupportedOrientations: portrait
#SupportedOrientations: landscape

In the code with the Phone library

Landscape
Phone1.SetScreenOrientation(0)

Portrait
Phone1.SetScreenOrientation(1)

Both
Phone1.SetScreenOrientation(-1)

Both

5 Screen sizes and resolutions

5.4

111

Basic4Android Beginner's Guide

Supporting multiple screens - tips and best practices

There are several features in Basic4android (and Designer4android) that help you target Android
phones and tablets with different screen sizes and resolutions. The purpose of this page is to collect
tips and best practices that will help you create flexible layouts.
If you are not familiar with the designer script feature then please read this chapter
Designer Scripts

5.4.1 Advices
Below a few advices.
5.4.1.1 'dip' units
It is very simple. You should always use 'dip' units when specifying the size or position of a view
(control). This way the view's physical position and size will be the same on any device.
This is correct for both regular code and designer script.
Button1.Width = 100
'WRONG!
Button1.Width = 100dip 'Good job!

Note that text size is measured in physical units. So you should not use 'dip' units with text size
values.
5.4.1.2 Use only a few layout variants
It is easy to create many variants. However it is very difficult to maintain a layout made of many
variants. You should use the designer script feature to adjust (or fine tune) your layout instead of
creating many variants.
5.4.1.3 Understand the meaning of scale (dots per inch)
There are many questions starting with "I have a device with 480x800 screen...". There is no
meaning to these dimensions without the scale value.
A scale of 1.0 means that there are 160 dots (pixels) per inch.
The scale values can be one of the following values: 0.75, 1.0, 1.5, 2 and 3.
Most phones today have a scale of 1.5 (160 * 1.5 = 240 dots per inch).
Most tablets have a scale of 1.0, and some have a scale of 1.5.
5.4.1.4 "Normalized" variants
Normalized variants are variants with a scale of 1.0.
The layout you create with the designer is scaled (not stretched or resized) automatically. This
means that the layout will look exactly the same on two phones with the same physical size. The
scale doesn't matter.
It is highly recommended to work and design your layout with normalized variants only.
For example a variant of 480x800, scale=1.5 matches the normalized variant: 320x533, scale=1.0
(divide each value by the scale value). Now it is easy to see that this device is slightly longer than
the "standard" variant: 320x480, scale=1.0.

5 Screen sizes and resolutions

112

Basic4Android Beginner's Guide

5.4.1.5 Scaling strategy

A useful example is available here: http://www.basic4ppc.com/forum/desig...mpate-1-a.html
You should decide what will happen with your layout when it runs on a larger device.
Usually some views will be docked to the edges. This can be done easily with the designer script.
For example, to dock a button to the right side:
Button1.Right = 100%x

Some views should fill the available area.

This is done with SetTopAndButton and SetLeftAndRight methods.
'Make an EditText fill the available height between two buttons:
EditText1.SetTopAndBottom(Button1.Bottom, Button2.Top)
'Make a Button fill the entire PARENT panel:
Button1.SetLeftAndRight(0, Parent1.Width)
Button1.SetTopAndBottom(0, Parent1.Height)

5.4.1.6 How to change the views size and text size? AutoScale
Larger devices offer a lot more available space. The result is that even if the physical size of a view
is the same, it just "feels" smaller.
Some developers use %x and %y to specify the views size. However the result is far from being
perfect. The layout will just be stretched.
The solution is to combine the "dock and fill" strategy with a smart algorithm that increases the
views size and text size based on the running devices physical size.
We treat the standard variant (320 x 480, scale = 1.0) as the base variant. We then use this script
code to calculate the scale factor:
delta = ((100%x + 100%y) / (320dip + 430dip) - 1)
rate = 0.3 'value between 0 to 1.
scale = 1 + rate * delta

You can play with the value of 'rate'. The rate determines the change amount in relation to the
device physical size.
Value of 0 means no change at all. Value of 1 is similar to using %x and %y: If the physical size is
twice the size of the standard phone then the size will be twice the original size.
Values between 0.2 to 0.5 seem to give good results.
The abstract designer is useful to quickly test the effect of this value.
The scale will not be applied automatically.
You will need to manually do it (for the views that need to adjust their size):
Label1.TextSize = Label1.TextSize * scale
Button1.Width = Button1.Width * scale
'For a button that is docked to the right side:
Button2.Width = Button2.Width * scale
Button2.Right = 100%x
'Or:
Button2.SetLeftAndRight(100%x - Button2.Width * scale, 100%x)

If done properly this saves the need to create many variants.

Your layout will look good on all devices.
The above principle can easily be implemented with the AutoScale function since
Basic4Android version 2.20.

6 The Emulator

113

Basic4Android Beginner's Guide

The Emulator

The Emulator or Virtual Device is a program that simulates devices on the PC.

6.1

Launch an Emulator
To launch an Emulator click in the IDE in the Tools menu
on Run AVD Manager.

Select the desired emulator.

The portrait Emulator in this case. Click on

Click on

6 The Emulator

114

Basic4Android Beginner's Guide

Wait until the Emulator is ready, this will take quite some time.

The physical size of the Emulator on the screen can be changed in the Launch Option window.

In the example the size is set to 5 inches.

6 The Emulator

6.2

115

Basic4Android Beginner's Guide

Create a new Emulator

Let us add a new Emulator with a resolution of 480 / 800 pixels, density 240.
In the AVD Manager

Click

Name: Enter the name Emulator 480_800

Target: Select Android 2.2 API Level 8

SD Card:
Enter 16.
Skin: select WVGA800.
HVGA
QVGA
WQVGA400
WQVGA432
WVGA800
WVGA854

Click

320 / 480
240 / 320
240 / 400
240 / 432
480 / 800
480 / 854

6 The Emulator

116

Basic4Android Beginner's Guide

Select

Click

Change 240 to 160, click on

And select 160.

Click

Click

6 The Emulator
The new Emulator is added.

117

Basic4Android Beginner's Guide

6 The Emulator

6.3

118

Basic4Android Beginner's Guide

Emulator problems

Unfortunately, the Emulator is quite slow and sometimes a pain.

When you either run the program or connect to the Emulator from the Designer, sometimes you will
see the message below.

You have two options:

- Yes (Oui) to cancel the process.
- No (Non) Continue the process.

Most times when clicking

However, even after having clicked

, the process will succeed.

, sometimes you will see following message.

In most cases, if you run the program once more, the connection to the Emulator will be established
and it will work properly.
This often happens when the Emulator is still running a program or if the Emulator is still
connected to another project. In this case press the back button until you reach the Emulator's home
screen and try again.
If this happens for a second time, close the current Emulator and run it again from the AVD
Manager.
If the first message above appears too often you can increase the process timeout value.

6 The Emulator

119

6.3.1 Process timeout

In the IDE Tools menu.

Set the ProcessesTimeoutSeconds parameter to a higher value.

I set it to 45 seconds.

Basic4Android Beginner's Guide

6 The Emulator

6.4

120

Basic4Android Beginner's Guide

Exchanging files with the PC

To get access to files in the Emulator you can use the Dalvik Debug Monitor.
The name is ddms.bat and it is located in the folder where you copied the Android SDK.
Example : C:\Android\android-sdk-windows\tools.
Make sure that Emulator is running.
Run the ddms.bat file:

A window like this one will appear.

Wait a moment.

The Dalvik Debug Monitor will be displayed.

6 The Emulator

121

Basic4Android Beginner's Guide

In the upper left corner you should see a

reference to the Emulator.
Select it.

Then in the menu Device

select File Explorer...

The Device File Explorer will be displayed :

You see several

folders.
In data\app you'll
find applications.

mnt\sdcard
is the
DirRootExternal
folder.
In the example the
file persons.db is a
database copied in a
B4A program from
DirAssets to
DirRootExternal.

6 The Emulator

122

Basic4Android Beginner's Guide

In the upper left corner you see three icons :

Pull file from device, copies the file to the PC

Push file onto device, copies a file to the device
Deletes the file
Clicking on either
or
shows the standard Windows file explorer to select the destination or
source folder for the selected file.

If the Dalvik Debug Monitor doesn't run you need to add the path where the ddms.bat file is located
to the environment variables.
From the desktop, right-click My Computer and click Properties.
In the System Properties window, click on the Advanced tab.
In the Advanced section, click the Environment Variables button.
Finally, in the Environment Variables window (as shown below), highlight the Path variable in
the Systems Variable section and click the Edit (Modifier) button. Add or modify the path lines
with the paths you wish the computer to access. Each different directory is separated with a
semicolon as shown below.

7.1 Connecting a real device USB

123

Basic4Android Beginner's Guide

Connecting a real device USB / B4A Bridge

There are different means to connect a real device :

USB
Needs that the device supports ADB debugging.
Need to activate USB Debugging on the device.
B4A Bridge
o via WiFi
o via Bluetooth

7.1

USB

You should download Google USB Driver in the Android SDK Manager.
If this driver doesn't work you must search for a specific driver for your device.
To be able to connect a device with USB you must activate USB Debugging.
This is also need if you use an Emulator.
In this state on most devices you will not be able to access the SD card from the PC.
If you want to access the SD card you must uncheck USB Debugging.

Launch Settings

Select Applications

Check Unknown sources

Select Development

Check USB Debugging

7.2 Connecting a real device B4A Bridge

7.2

124

Basic4Android Beginner's Guide

B4A Bridge

Up until now there were two methods for testing your application during development.
You can either work with the Android emulator or if your device supports ADB debugging, you are
able to connect to your real device.
The Android emulator is very slow compared to a real device (especially with applications
installation).
Therefore in most cases it is more convenient to work with a real device.
Personally, I'm only using the emulator when working with the visual designer.
However not all devices support ADB debugging. This is exactly the reason for the new B4ABridge tool.
B4A-Bridge is made of two components. One component runs on the device and allows the second
component which is part of the IDE to connect and communicate with the device.
The connection is done over a network (B4A-Bridge cannot work if there is no network available).
Once connected, B4A-Bridge supports all of the IDE features which include: installing applications,
viewing LogCat and the visual designer.
Android doesn't allow applications to quietly install other applications, therefore when you run your
application using B4A-Bridge you will see a dialog asking for your approval.
Getting started with B4A-Bridge

7.2.1 First you need to install B4A-Bridge on your device.

B4A-Bridge can be downloaded here: http://www.basic4ppc.com/android/files/b4a_bridge.apk.
B4A-Bridge is also available on Play Store. Search for: B4A Bridge.
Note that you need to allow install of applications from "Unknown sources". This is done by
choosing Settings from the Home screen - Manage Applications.
B4A-Bridge requires writable storage card. It is not possible to install applications without it.

7.2 Connecting a real device B4A Bridge

125

Basic4Android Beginner's Guide

7.2.2 Run B4A-Bridge on your device.

It will display a screen similar to:

Status will be: Waiting for connections.

You should now choose either Start - Wireless or Start - Bluetooth depending on the working mode.
The Make Discoverable checkbox will make your device Bluetooth discoverable for 5 minutes.
This is only needed if the device and computer weren't paired before.

7.2.3 Connect the IDE to the device.

Go to Tools - B4A-Bridge and choose Connect Wireless or Connect Bluetooth.
7.2.3.1 Wireless connections
You will be asked to enter the device IP address. The IP is displayed on the device. In some cases
the address displayed may be the mobile network address. In that case you can find the local
wireless address in the wireless advanced settings page.

7.2 Connecting a real device B4A Bridge

126

Basic4Android Beginner's Guide

7.2.3.2 Bluetooth connections

In Bluetooth mode you should first click on Find Devices. All paired devices and new devices in
discoverable mode will be listed.
You should choose the correct one and press on Connect.
Assuming that the connection succeeded the dialog will be closed.
The status bar at the bottom of the screen shows the current status:

or

That's it.
When B4A-Bridge gets connected it first checks if the designer application needs to be updated. In
that case it will first install the designer application.
B4A-Bridge keeps running as a service until you press on the Stop button.
You can always reach it by opening the notifications screen:

7.2 Connecting a real device B4A Bridge

127

Basic4Android Beginner's Guide

Pressing on the notification will open the main screen.

As mentioned above, when you run an application you are required to approve the installation. You
will usually see the following screens:

Note that the Bluetooth permission and Internet permission are automatically added in debug mode.

7.2 Connecting a real device B4A Bridge

128

Basic4Android Beginner's Guide

In the above dialog you should choose Open to start the application.
If you try to install an existing application signed with a different key, the install will fail
(without any meaningful message). You should first uninstall the existing application. Go to
the home screen - Settings - Applications - Manage applications - choose the application Uninstall.
Once you finished developing you should press on the Stop button in order to save battery.
7.2.3.3 Bluetooth tips
- Unfortunately many devices, especially older devices running Android 2.1 or 2.2 have all kinds of
issues with Bluetooth connections and especially with multiple connections. All kinds of
workarounds were implemented because of these issues. Still however there are devices (HTC
desire for example) that do not work reliably enough.
- The Reset Bluetooth button disables and then enables the Bluetooth adapters. You should try it if
there are connections problems.
- If your connection is not stable then you should avoid using the debugger or designer. Both the
debugger and the designer create an additional connection.
Note that B4A-Bridge was written with Basic4android.

8 The Designer

129

Basic4Android Beginner's Guide

The Designer

The Designer allows generating layouts with either the Emulator or a real device.

8 The Designer / 8.1 The menu

8.1

130

Basic4Android Beginner's Guide

The menu

8.1.1 File menu

New
Open

Opens a new empty layout.

Opens an existing layout.

Save
Save As

Saves the current layout.

Saves the current layout with a new name.

Remove Layout
Removes the layout from the Files directory.
Main
Layout file list, in this case only one file, 'Main'.

8.1.2 Edit menu

The standard edit functions. You can
Cut
Copy
Paste
Undo
Redo
views between different layout files.
These functions are available only in the DesignerScipts screen.

8 The Designer / 8.1 The menu

131

Basic4Android Beginner's Guide

8.1.3 AddView menu

This menu allows you to select the view you want to add to the current layout on the device or the
Emulator.

AutoCompleteEditText
adds an AutoCompleteEditText
Button
adds a Button
CheckBox
adds a CheckBox
CustomView
adds a CustomView
EditText
adds an EditText
ImageView
adds an ImageView
HorizontalScrollViewadds a HorizontalScrollView
Label
adds a Label
ListView
adds a ListView
Panel
adds a Panel
ProgressBar
adds a ProgressBar
RadioButton
adds a RadioButton
ScrollView
adds a Scrollview
SeekBar
adds a SeekBar
Spinner
adds a Spinner
TabHost
adds a TabHost
ToggleButton
adds a ToggleButton
WebView
adds a WebView

8 The Designer / 8.1 The menu

132

Basic4Android Beginner's Guide

8.1.4 The Tools menu

Generate Members
Bring to Front

Members generator
Brings the selected View to front

Send To Back
Sends the selected View to back
Duplicate Selected View Duplicates the selected View
Remove Selected View Removes the selected View
Change Grid

Allows to change the grid size

Connect to Device Connects the Emulator or the device

Disconnect From Device / Emulator
Show Abstract Designer
Run Script Runs the script code in the Designer Scripts
Send To UI Cloud.

8 The Designer / 8.2 Tools

8.2

133

Basic4Android Beginner's Guide

Tools

8.2.1 Generate Members

Allows generating Dim statements and frames for subroutines.
The Generate Members tool allows to automatically generate references and subroutine frames.
The example is based on the MyFirstProgram project.

Click on to open the generator.

Here we find all the views added to the current layout.

We check all views and check the Click event for the btnAction Button.
Checking a view
generates its reference in the Globals Sub in the code. This is
needed to make the view recognized and allow the autocomplete function.
Dim
Dim
Dim
Dim
Dim
Dim

btnAction, btn0 As Button

lblResult As Label
lblComments As Label
lblMathSign As Label
lblNumber1 As Label
lblNumber2 As Label

Clicking on an event

of a view generates the Sub frame for this event.

Sub btnAction_Click
End Sub

Click on

to generate the references and sub frame and

8 The Designer / 8.2 Tools

134

Basic4Android Beginner's Guide

8.2.2 BringTo Front

When views are overlapping, the hidden or
partial hidden view can be brought to front.
Click on the view to bring to front to select it.
Click on
to bring the selected view to front.

This is especially interesting with big Panels.

8.2.3 Send To Back

is
the opposite of Bring To Front.

8.2.4 Duplicate Selected View

Click on the view you want to duplicate to

select it.
Click on
to duplicate the view.

The view is duplicated.

The view covers the source view !

8 The Designer / 8.2 Tools

135

Basic4Android Beginner's Guide

8.2.5 Remove Selected View

Click on the view to remove to select it.
Click on
to remove it.
This function is the same as the Cut function
in the Edit menu.

The view has been removed.

Note: Be careful, you will not be asked if you
really want to remove the view.
If you remove a view by mistake you can
recover it with Undo in the Edit menu.

8.2.6 Change grid

The grid is an invisible grid with a given size. The default grid size is 10 pixels. That means that all
positions and dimensions of a view will be set to values in steps corresponding to the grid size.
Moving a view will be done in steps equal to the grid size.

Click on
You can change the grid size
to the value you want.

The value is saved in the layout file, you will get the same value when you reload this layout.
The default value when you start a new project is 10.

8 The Designer / 8.3 General settings

136

Basic4Android Beginner's Guide

8.2.7 Connect device or emulator

Click on
Emulator.

in the Tools menu to connect to a device or an

If different devices or Emulators are connected, you will be asked which device or Emulator you
want to connect to.

Select the emulator or the device in the

list.

Click on

To disconnect it click on

to confirm.

In the Tools menu.

8 The Designer / 8.3 General settings

8.3

137

Basic4Android Beginner's Guide

General settings

Shows the Designer state. You can add views, remove views and edit their properties.
In the left pane all views are displayed in a tree.
In the middle pane the properties of the selected view are displayed and can be edited.
On the right part of the screen several settings can be set.
A parent view like the Activity or a Panel can be expanded or not.

1.3 Installing Android Emulator

138

Basic4Android Beginner's Guide

The window can be set to stay always on TOP.

8 The Designer / 8.4 Image files

8.4

139

Basic4Android Beginner's Guide

Image files
You can add image files to the layout.
Click on

to select the files(s) to add.

These files will be listed in the Image Files list.

These files are saved to the Files folder of the project.
To remove files, check the files to remove
and click on

8 The Designer / 8.5 Properties list

8.5

140

Basic4Android Beginner's Guide

Properties list

Select for example lblNumber1 in the list.

All the properties of lblNumber1 are displayed.
These are organized in groups.
All properties can be modified directly in the list.
All properties in the Main group and some of the
properties in the other groups are common to all view
types.

Explanation of some general properties for all types of Views:

Main :
Name
Name of the view. It is good practice to give meaningful names. Common
usage is to give a 3 character prefix and add the purpose of the view. In the example, the view is of
type Label and its purpose is to enter a result. So we give it the name "lblResult", "lbl" for
Label and "Result" for the purpose. This does not take much time during the design of the layout
but saves a lot time during coding and maintenance of the program.
Type
Type of the view, not editable. It is not possible to change the type of a view.
If you need to, you must remove the view and add a new one.
Event Name
Generic name for the subroutines that manages the view's events. By default,
the Event Name is the same as the view's name like in the example. The Events of several Views
can be redirected to a same subroutine. In that case you must enter the name of that routine.
Look at the SecondProgram example for the Click event management for the buttons of the
keyboard, the btnEvent_Click routine.
Parent
Name of the parent view. Activity, in the example. The parent view can be
changed in selecting the new one in the list.

8 The Designer / 8.5 Properties list

141

Basic4Android Beginner's Guide

Common properties :
HorizontalAnchor Horizontal Anchor function. Possible values LEFT, RIGHT or BOTH
VerticalAnchor

Vertical Anchor function. Possible values TOP, BOTTOM or BOTH

Left
X coordinate of the left edge of the View from the left edge of its parent
View, in pixels (the pixels are in reality dips, density independent pixels).
Top
Y coordinate of the upper edge of the View from the upper edge of its parent
View, in pixels (the pixels are in reality dips, density independent pixels).
Width
Width of the View in pixels (the pixels are in reality dips, density
independent pixels).
Height
Height of the View in pixels (the pixels are in reality dips, density
independent pixels).
Enabled

Enables or disables the use of the View Ex: Enabled = True

Visible

Determines if the View is visible to the user or not.

Tag
This is a place holder which can used to store additional data. Tag can simply
be text but can also be any other kind of object.
Tag is used in the SecondProgram example for the numeric buttons click events management in the
btnEvent_Click routine.

8 The Designer / 8.6 Layout variants

8.6

142

Basic4Android Beginner's Guide

Layout variants
Different layout variants can be managed in a same layout file.

Let us make an example based on the TestLayouts project

(which can be found under the Guide\SourceCode\TestLayouts directory):
- Copy the whole TestLayouts folder.
- Rename it to TestLayoutVariants.
- Rename the TestLayout.b4a file to TestLayoutVariants.b4a.
- Run the IDE.
- Run the Emulator (320 * 480 - 160)
- Run the Designer.
- Connect the Designer to the Emulator or the device.
The emulator should look like this.

8 The Designer / 8.6 Layout variants

143

Basic4Android Beginner's Guide

In the Designer, click on

Select:
480 x 320
scale = 1

Click on

The new variant is added.

Go to the Emulator, press Ctrl + F11, to change it to landscape mode.

It should look like this.

8 The Designer / 8.6 Layout variants

144

Basic4Android Beginner's Guide

The toolbox is not visible, to get it we select it in the Designer.

And set its Top value to 10.

The Toolbox is now visible.

We need to write code to automatically
rearrange the views when landscape mode
is used.

Button height 65
ListView1:
Width = 380
Height = 220

8 The Designer / 8.6 Layout variants

145

In the code we change the Activity_Create routine from

to

Run the program.

The Emulator should look like this:

Click on Ctrl + F11 to change to portrait >>>

We now have two layout variants in the same layout file.

Basic4Android Beginner's Guide

8 The Designer / 8.6 Layout variants

146

Basic4Android Beginner's Guide

With the 320*240_120 emulator.

We can achieve a similar effect in the Designer when a different Layout Variant is selected and we
switch to Landscape mode (Ctrl-F11).

8 The Designer / 8.7 Abstract Designer

8.7

147

Basic4Android Beginner's Guide

The Abstract Designer

The Abstract Designer is a tool that shows the layout in a separate window and is part of the
Designer. It is much faster than the Emulator.
Its main purpose is to create different layout variants.
The different views are not shown with their exact shape but only as coloured rectangles.
Clicking on a view shows its properties in the Designer.

Emulator

Abstract Designer

8 The Designer / 8.7 Abstract Designer

148

Basic4Android Beginner's Guide

8.7.1 The menu

Layout

Matches :
The chosen variant in the
Designer.
The connected device.

Choice of the most

current screen sizes and
resolutions.
Select a resolution and
position the different
views according to the
new dimensions and
scale.

Zoom

Two possibilities:
50%
100%

Tools
Resize form to fit the layout.
Adds the current layout as a new layout variant in the
Designer.

8 The Designer / 8.7 Abstract Designer

149

Basic4Android Beginner's Guide

8.7.2 Context menus

Clicking on a view shows a context menu.

Add View
Cut
Copy
Paste
Duplicate Selected Views
Horizontal Anchor
Vertical Anchor
Bring To Front
Send To Back
Generate

Generate : Generates the Dim statement or an event routine for the select View
Dim btnTest As Button
Generates the Dim statement
Dim btnTest1 As Button

Down
Generates the Down event
Sub btnTest1_Down
End Sub

Up
Generates the Up event
Sub btnTest1_Up
End Sub

Sub
btnTest1_Click
End Sub

LongClick
Generates the LongClick event
Sub btnTest1_LongClick
End Sub

8 The Designer / 8.7 Abstract Designer

150

Basic4Android Beginner's Guide

8.7.3 Select views

Select a single view:

Click on the view

Select several views :

Click on the first view.
Press the Ctrl key,
Select the following views.
The selected views have a yellow border.

After the selection you can :

Move the selected views with the arrow keys of the keyboard in the four directions.

Display the Generate Members Dialog.

Bring To Front.

Send To Back.

Duplicate the selected views (see Context menus).

Remove the selected views.

In the Designer you can change these

properties.

8 The Designer / 8.7 Abstract Designer

151

Basic4Android Beginner's Guide

8.7.4 Example
Let us take a simple example with a layout in portrait mode, like the image below.

Now we would like to make a landscape variant.

Click on Phone (landscape) in the Layout menu

The Designer looks like this:

Click in the Tools menu on

Add Current Layout As New Variant
to add the landscape mode as a new variant in the
layout file. Then click on :
Resize Form To Fit Layout

8 The Designer / 8.7 Abstract Designer

152

Basic4Android Beginner's Guide

Now we rearrange the views to fit

the new orientation.

In the Designer we see the new variant.

If you select in the Designer

the previous variant

you will see the screen on the left.

8 The Designer / 8.7 Abstract Designer

Click, in the Tools menu, on

to resizes the window to fit the layout.

153

Basic4Android Beginner's Guide

.

8 The Designer / 8.9 Designer Scripts

8.8

154

Basic4Android Beginner's Guide

Adding views by code

It is also possible to add views by code instead of using the Designer with a device, the Emulator or
the Abstract Designer.
Advantage : you have full control of the view.
Disadvantage : you have to define almost everything.
The source code is in the source code directory: AddViewsByCode
For the positions and dimensions of the views on the screen two special options are available:
dip
density independent pixels.
100dip = DipToCurrent(100)
DipToCurrent is a Keyword
dip is the Shortcut
100dip = 100 / 160 * device density
The default density is 160 dpi dots per inch (pixels per inch)
Densities in Android:
o 120 scale 0.75
o 160 scale 1 default
o 240 scale 1.5
o 320 scale 2

%x and %y represent distances proportional to the active screen width and height.
20%x = 0.2 * Activity.Width
90%y = 0.9 * Activity.Height
20%x = PerXToCurrent(20)
PerXToCurrent is a Keyword %x is the Shortcut
90%y = PerYToCurrent(90)

Example:
Let us put a Label on top of the screen and a Panel below it with a Label and a Button on it:
Sub Globals
Dim lblTitle, lblPanelTitle As Label
Dim pnlTest As Panel
Dim btnTest As Button
End Sub

8 The Designer / 8.9 Designer Scripts

155

Basic4Android Beginner's Guide

Sub Activity_Create(FirstTime As Boolean)

lblTitle.Initialize("")
lblTitle.Color = Colors.Red
lblTitle.TextSize = 20
lblTitle.TextColor = Colors.Blue
lblTitle.Gravity = Gravity.CENTER_HORIZONTAL + Gravity.CENTER_VERTICAL
lblTitle.Text = "Title"
Activity.AddView(lblTitle, 20%x, 10dip, 60%x, 30dip)
pnlTest.Initialize("")
pnlTest.Color = Colors.Blue
btnTest.Initialize("btnTest")
btnTest.Text = "Test"
lblPanelTitle.Initialize("")
lblPanelTitle.Color = Colors.Red
lblPanelTitle.TextSize = 16
lblPanelTitle.TextColor = Colors.Blue
lblPanelTitle.Gravity = Gravity.CENTER_HORIZONTAL + Gravity.CENTER_VERTICAL
lblPanelTitle.Text = "Panel test"
Activity.AddView(pnlTest, 0, lblTitle.Top+lblTitle.Height+10dip, 100%x, 50%y)
pnlTest.AddView(lblPanelTitle, 20dip, 10dip, 100dip, 30dip)
pnlTest.AddView(btnTest, 50dip, 50dip, 100dip, 60dip)
End Sub

'Diming' the views.

Dim lblTitle, lblPanelTitle As Label
Dim pnlTest As Panel
Dim btnTest As Button

Initializing the title label:

lblTitle.Initialize("")
Initializes the Label, no EventName required.
lblTitle.Color = Colors.Red
Sets the Background color to red.
lblTitle.TextSize = 20
Sets the text size to 20.
lblTitle.TextColor = Colors.Blue
Sets the text color to blue.
lblTitle.Gravity = Gravity.CENTER_HORIZONTAL + Gravity.CENTER_VERTICAL

Sets the label gravity.

lblTitle.Text = "Title"
Sets the label text to 'Title'.
Activity.AddView(lblTitle, 20%x, 10dip, 60%x, 30dip) Adds the view to the activity.
If the Label had been added in the Designer, all the above code wouldn't have been necessary
because the properties would already have been defined in the Designer.
In the Activity.AddView line we see that:
the Left property is set to 20%x, 20% of Activity.Width.
the Top property is set to 10dip, 10 density independent pixels.
the Width property is set to 60%x, 60% of Activity.Width
the Height property is set to 30dip, 30 density independent pixels.
pnlTest.Initialize("")
pnlTest.Color = Colors.Blue

Initializes the Panel, no EventName required.

Sets the Background color to blue.

btnTest.Initialize("btnTest")
btnTest.Text = "Test"
lblPanelTitle.Initialize("")

Initializes the Button, EventName = btnTest.

Sets the button text to "Test"

8 The Designer / 8.11 AutoScale

156

Basic4Android Beginner's Guide

lblPanelTitle.Color = Colors.Red
lblPanelTitle.TextSize = 16
lblPanelTitle.TextColor = Colors.Blue
lblPanelTitle.Gravity = Gravity.CENTER_HORIZONTAL + Gravity.CENTER_VERTICAL
lblPanelTitle.Text = "Panel test"

Similar to the title Label.

Activity.AddView(pnlTest,0,lblTitle.Top + lblTitle.Height + 10dip, 100%x, 50%y)

Adds the Panel pnlTest to the Activity.

the Left property is set to 0
the Top property is set to 10dips below the title Label
the Width property is set to 100%x, the total Activity.Width
the Height property is set to 50%y, half the Activity.Height
pnlTest.AddView(lblPanelTitle, 20dip, 10dip, 100dip, 30dip)

Adds the Label lblPanelTitle to the Panel pnlTest at the given position and with the given
dimensions in dips.
pnlTest.AddView(btnTest, 50dip, 50dip, 100dip, 60dip)

Adds the Button btnTest to the Panel pnlTest at the given position and with the given dimensions in
dips.
And the result:

8 The Designer / 8.9 Designer Scripts

8.9

157

Basic4Android Beginner's Guide

Designer Scripts

One of the most common issues that Android developers face is the need to adapt the user interface
to devices with different screen sizes.
As described in the visual designer tutorial, you can create multiple layout variants to match
different screens.
However it is not feasible nor recommended to create many layout variants.
Basic4android v1.9 introduces a new tool named "Designer Scripts" that will help you fine tune
your layout and easily adjust it to different screens and resolutions.
The idea is to combine the usefulness of the visual designer with the flexibility and power of
programming code.
You can write a simple script to adjust the layout based on the dimensions of the current device and
immediately see the results. No need to compile and install the full program each time.
You can also immediately see the results on the abstract designer. This allows you to test your
layout on many different screen sizes.

8 The Designer / 8.9 Designer Scripts

158

Basic4Android Beginner's Guide

How to
Every layout file can include script code. The script is written inside the visual designer under the
new Designer Scripts tab:

There are two types of scripts: the general script that will be applied to all variants, and a script
specific to the current variant.
Once you press on the Run Script button (or F5), the script is executed and the connected device /
emulator and abstract designer will show the updated layout.
The same thing happens when you run your compiled program. The (now compiled) script is
executed after the layout is loaded.
The general script is first executed followed by the variant specific script.
The script language is very simple and is optimized for managing the layout.
Lets start with an example.

8 The Designer / 8.9 Designer Scripts

159

Basic4Android Beginner's Guide

Example
In this example we will build the following layout:
The source code is in the DesignerScripts folder.

btnLeft and btnRight should be located in the top corners.

btnDown should be located at the bottom and fill the entire width.
ListView1 should fill the entire available area.
ToggleButton1 should be located exactly in the centre.
The first step is to add the views and position them with the visual designer (you do not need to be
100% accurate).
Now we will select the designer scripts tab and add the code.
Note that the views are locked when the designer scripts tab is selected.
The same can be done with Anchors, a new feature sine Basic4Android version 3.20.

8 The Designer / 8.9 Designer Scripts

160

The code in this case is:

'All variants script
btnRight.Right = 100%x
btnDown.Bottom = 100%y
btnDown.Width = 100%x
EditText1.Width = 100%x
EditText1.Bottom = btnDown.Top - 5dip
ListView1.Width = 100%x
ListView1.SetTopAndBottom(,.Bottom, EditText1.Top)
ToggleButton1.HorizontalCenter = 50%x
ToggleButton1.VerticalCenter = 50%y

The result:

Basic4Android Beginner's Guide

8 The Designer / 8.9 Designer Scripts

10 '' tablet

161

Basic4Android Beginner's Guide

8 The Designer / 8.9 Designer Scripts

162

Basic4Android Beginner's Guide

Reference
The following properties are supported:
- Left / Right / Top / Bottom / HorizontalCenter / VerticalCenter
Gets or sets the view's position. The view's width or height will not be changed.
- Width / Height - Gets or Sets the view's width or height.
- TextSize - Gets or sets the text size.
You should not use 'dip' units with this value as it is already measured in physical units.
- Text - Gets or sets the view's text. TextSize and Text properties are only available to views that
show text.
- Image - Sets the image file (write-only). Only supported by ImageView.
- Visible - Gets or sets the view's visible property.

Methods
- SetLeftAndRight (Left, Right) - Sets the view's left and right properties. This method changes
the width of the view based on the two values.
- SetTopAndBottom (Top, Bottom) - Sets the view's top and bottom properties. This method
changes the height of the view based on the two values.

Keywords
- Min / Max - Same as the standard Min / Max keywords.
- AutoScale - Autoscales a view based on the device physical size. Example : AutoScale(Button1)
- AutoScaleAll - Autoscales all layout views.
- AutoScaleRate - Sets the scaling rate, a value between 0 to 1. The default value is 0.3
Example : AutoScaleRate(0.5)
- ActivitySize - Returns the approximate activity size measured in inches.
- If .. Then condition blocks - Both single line and multiline statements are supported. The
syntax is the same as the regular If blocks.

8 The Designer / 8.9 Designer Scripts

163

Basic4Android Beginner's Guide

If you write the beginning of a keyword of a view name and press Ctrs + Space you get the list of
available functions and views :
Example : Auto Ctrl + Space

Notes and tips

- %x and %y values are relative to the view that loads the layout.
Usually it will be the activity. However it you use Panel.LoadLayout then it will be relative to this
panel.
- Use 'dip' units for all specified sizes (except of TextSize). By using 'dip' units the values will be
scaled correctly on devices with higher or lower resolution.
- In most cases it is not recommended to create variants with scales other than 1.0. When you add
such a variant you will be given an option to add a normalized variant instead with a scale of 1.0.
- Variables - You can use variables in the script. You do not need to declare the variables before
using them (there is no Dim keyword in the script).
- Activity.RerunDesignerScript (LayoutFile As String, Width As Int, Height As Int) - In some cases
it is desirable to run the script code again during the program. For example you may want to update
the layout when the soft keyboard becomes visible. Activity.RerunDesignerScript method allows
you to run the script again and specify the width and height that will represent 100%x and 100%y.
In order for this method to work all the views referenced in the script must be declared in Sub
Globals.
Note that this method should not be used to handle screen orientation changes. In that case the
activity will be recreated and the script will run during the Activity.LoadLayout call.

8 The Designer / 8.10 Anchors

164

Basic4Android Beginner's Guide

8.10 Anchors
Two anchor properties, Horizontal Anchor and Vertical Anchor were added to
Basic4Androd version 3.20.
Horizontal Anchor

The horizontal anchor property can take three values :

LEFT
This is the default value.
The left edge is anchored to the left
edge of the parent view with the
distance given in the Left property.

RIGHT

The right edge is anchored to the right edge of the

parent view with the distance given in the Right Edge
Distance property.
The Left property is no more available because it is
defined by the width and the right anchor !

BOTH
Both edges are anchored.
The Width property is no more
available because it is defined by the
anchors !

Setting the Horizontal Anchor property to BOTH is similar to the SetLeftAndRight function in the
Designer Scripts.

8 The Designer / 8.10 Anchors

165

Basic4Android Beginner's Guide

Vertical Anchor

The vertical anchor property can take three values :

TOP
This is the default value.
The top edge is anchored to the top
edge of the parent view with the
distance given in the Top property.

BOTTOM
The bottom edge is anchored to the bottom edge of
the parent view with the distance given in the Bottom
Edge Distance property.
The Top property is no more available because it is
defined by the Height and the bottom anchor !

BOTH
Both edges are anchored.
The Height property is no more
available because it is defined by the
anchors !

Setting the Vertical Anchor property to BOTH is similar to the SetTopAndBottom function in the
Designer Scripts.

8 The Designer / 8.10 Anchors

166

Basic4Android Beginner's Guide

What happens when we set the horizontal anchor of the two views below to BOTH and change the
parent view width?
The left views right edge is anchored to the right edge of the parent view with the Right Edge
Distance.
The right views left edge is anchored to the left edge of the parent view with the Left distance.

If we increase the width of the parent view we get the layout below.

The left views right edge is still at the Right Edge Distance from the parent views right edge.
The right views left edge is still at the Left distance from the parent views left edge.
The result is an overlapping of both views.
In this case you must adjust the views in the Designer Scripts with the SetLeftAndRight method!
For example:
LeftView.SetLeftAndRight(0, 67%x)
RightView.SetLeftAndRight(33%x, 100%x)

8 The Designer / 8.10 Anchors

167

Basic4Android Beginner's Guide

8.10.1 First example

The examples shown in this chapter are based on the DesignerAnchor project.
First we add a label on top of the screen which should cover the whole width and stay on top.
In the AbstractDesigner right-click somewhere on the screen, the menu below will be displayed:

Click on Add View.

On the left side appears the list of the

views you can add to the layout.

Click on Label.

Move the labels upper left corner to the upper

left corner of the screen and stretch it to fill
the whole width of the screen.

8 The Designer / 8.10 Anchors

168

Basic4Android Beginner's Guide

Click somewhere else on the screen to
remove the red anchors.
Anchor arrows are displayed on the
left edge
the label.

and the top edge

of

We see these properties:

Left = 0
Top = 0
Width = 320
Height = 40

full layout width

Now we change le Horizontal Anchor property :

Click on BOTH

We see that the properties changed :

Left, Top and Height are still the same.
But Width has disappeared and is replaced by
Right Edge Distance = 0

Its value = 0 because the right edge is on the right

edge of the screen.

Set the other properties like in the picture.

Now we see a new anchor arrow on the right

edge.

8 The Designer / 8.10 Anchors

169

Basic4Android Beginner's Guide

Now, let us add a Panel at the bottom of the

screen covering also the whole screen width.

The properties look like in the picture.

We set the Horizontal Anchor to BOTH.

Same as for Label1.

We set the Vertical Anchor to BOTTOM.

The Top property is replaced by the :

Bottom Edge Distance = 0 property.
Its value = 0 because we anchor the bottom
edge of Panel1 to the screens bottom edge.

And set the other properties like this.

8 The Designer / 8.10 Anchors

170

Basic4Android Beginner's Guide

Now we add a second label onto Panel1.

Click on Panel1 to select it.

Add the label.

Move and size the label like in the picture

with the Left, Top, Width and Height properties
like in the list below.

In the left pane we

see that Label2 is
shifted to the right
because its parent
view is Panel1 and
not the Activity like
for Label1 and
Panel1!

The properties
Left = 10 and
Top = 10 remain the same.
Right Edge Distance = 10 and
Bottom Edge Distance = 10

The two values are equal to 10 because we want a

frame around Label2.

Set the other properties like in the picture.

8 The Designer / 8.10 Anchors

171

Basic4Android Beginner's Guide

And the result looks like the pictures below in portrait and landscape screen orientations.

To demonstrate the anchor feature we move, in the Abstract Designer, the top edge of Panel1
upwards.

We see that the bottom edge of Label2

remains at its place !

8 The Designer / 8.10 Anchors

172

Now, we add a ListView onto the left half of the

screen and vertically positioned between
Label1 and Panel1 leaving a small space.

Basic4Android Beginner's Guide

We set the vertical anchor to BOTH.

And set the other properties like in the picture.

Now, we add a ScrollView on the right

We set the horizontal anchor to RIGHT.
half of the screen also positioned between We set the vertical anchor to BOTH.
Label1 and Panel1 leaving a small space.
And set the other properties like in the picture.

8 The Designer / 8.10 Anchors

173

Basic4Android Beginner's Guide

In the code we :
- Load the layout.
- Fill the ListView and the ScrollView.
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Main")
FillListView
FillScroolView
End Sub

The two filling routines.

Sub FillListView
Dim i As Int
For i = 0 To 20
ListView1.AddSingleLine("Test " & i)
Next
End Sub
Sub FillScroolView
Dim i As Int
Dim lblHeight = 30dip As Int
For i = 0 To 20
Dim lbl As Label
lbl.Initialize("lbl")
ScrollView1.Panel.AddView(lbl, 0, i*lblHeight, 100%x-20dip, lblHeight-1dip)
lbl.Color = Colors.Blue
lbl.TextColor = Colors.White
lbl.Text = "Test " & i
lbl.Tag = i
Next
ScrollView1.Panel.Height = i * lblHeight
End Sub

And the result :

In portrait and landscape screen orientations.

We see that the anchors work fine.

But, we see that there is a big gap between the
ListView and the ScrollView.

8 The Designer / 8.10 Anchors

174

Basic4Android Beginner's Guide

Why do we have this gap ?

Because we set the Horizontal Anchor of the ListView to LEFT
and the Horizontal Anchor of the ScrollView to RIGHT.
But the Width property remains the same and thats why we get the gap between the two views
when the screen width is wider than the layout screen width.
To adjust the width we add two lines in the DesignerScripts.
Click on

to show the DesignerScripts window.

Here we comment AutoScaleAll and add the following two lines :

'AutoScaleAll
ListView1.Width = 50%x - 20dip
ScrollView1.SetLeftAndRight(50%x + 10dip, 100%x - 10dip)

The anchors are valid in the AbstractDesigner but not in Designer Scripts.
For ListView1 its enough to set its Width property.
But for ScrollView1 we need to define both properties Left and Right which is done with
SetLeftAndRight because the RIGHT anchor is lost.

8 The Designer / 8.10 Anchors

175

Basic4Android Beginner's Guide

8.10.2 Second example

We do the same exercise as in chapter 8.9

Designer Scripts but with the new Anchor
functions added to Basic4Android version 3.20.

This is the layout file from the DesignerScripts

example.

Click on btnRight.

And set the

Horizontal Anchor

property
to RIGHT.

The RIGHT anchor arrow is displayed instead of

the LEFT anchor arrow.

8 The Designer / 8.10 Anchors

176

Basic4Android Beginner's Guide

Click on btnDown.

Set the
Horizontal Anchor

property
to BOTH.
Set the
Vertical Anchor property
to BOTTOM.

Click on EditText1.

Set the anchors to BOTH and BOTTOM.

Click on ListView1
Move the right edge to the right edge of the screen

and set both anchors to BOTH.

8 The Designer / 8.10 Anchors

177

Basic4Android Beginner's Guide

Remains ToggleButton1.
For this view we need the DesignerScript we cannot adjust it with anchors.

And the result in portrait and landscape.

8 The Designer / 8.11 AutoScale

178

Basic4Android Beginner's Guide

8.11 AutoScale
Since B4A version 2.2 three new functions have been added :
AutoScaleRate(rate)
AutoScale
AutoScaleAll
Larger devices offer a lot more available space. The result is that even if the physical size of a view
is the same, it just "feel" smaller.
Some developers use %x and %y to specify the views size. However the result is far from being
perfect. The layout will just be stretched.
The solution is to combine the "dock and fill" strategy with a smart algorithm that increases the
views size and text size based on the running device physical size.
The AutoScale function is based on the standard variant (320 x 480, scale = 1.0).
Since Basic4Android version 3.2 AutoScale takes into account the dimensions of the variant
defined in the layout.
For other screen sizes and resolutions AutoScale calculates a scaling factor based on the equations
below.
delta = ((100%x + 100%y) / (320dip + 430dip) - 1)
rate = 0.3 'value between 0 to 1.
scale = 1 + rate * delta

AutoScale multiplies the Left / Top / Width and Height properties by the scale value.
If the view has a Text property this one is also multiplied by the scale value.
You can play with the 'rate' value. The rate determines the change amount in relation to the device
physical size.
Value of 0 means no change at all. Value of 1 is almost similar to using %x and %y: If the physical
size is twice the size of the standard phone then the size will be twice the original size.
Values between 0.2 to 0.5 seem to give good results. The default value is 0.3.
Be careful when you downsize a layout defined for a big screen to a small screen. The views may
become very small.
Note: The size of the CheckBox and RadioButton images is the same for all screen sizes.
The abstract designer is useful to quickly test the effect of this value.
Functions :
AutoScaleRate(rate) Sets the rate value for above equations.
Example : AutoScaleRate(0.5) Sets the rate value to 0.5.

AutoScale(View)
Scales the given view.
Example : AutoScale(btnTest1)
This is quivalent to :
btnTest1.Left = btnTest1.Left * scale
btnTest1.Top = btnTest1.Top * scale
btnTest1.Width = btnTest1.Width * scale
btnTest1.Height = btnTest1.Height * scale
btnTest1.TextSize = btnTest1.TextSize * scale

AutoScaleAll

Scales all the views in the selected layout

8 The Designer / 8.11 AutoScale

179

Basic4Android Beginner's Guide

8.11.1 Simple AutoScale example with only one layout variant

We will autoscale a simple example with the layout below, source code AutoScaleExample1 :

We have :
2 Labels on the top of the screen :
o lblTitle
o lblSubTitle

1 ScrollView in the middle of the screen :

o scvTest containing
one Panel pnlSetup with
10 Labels lblTest1 to lblTest10
10 EditTexts edtTest1 to edtTest10

1 Panel at the bottom of the screen :

o pnlToolBox
o Containing 3 Buttons
btnTest1
btnTest2
btnTest3

We have two layout files Main for the main screen and Panel for the ScrollView content with only
one layout variant 320 x 480 scale = 1 (160dip) for each.

8 The Designer / 8.11 AutoScale

180

Basic4Android Beginner's Guide

Main layout file:

We want to have the:
Two Labels on the top of the screen and
centred horizontally on the screen.
ToolBox Panel on the bottom of the screen and
centred horizontally.
ScrollView filling the space between the
SubTitle Label and the ToolBox Panel.
Note: Look at the anchors especially for the ToolBox
and the ScrollView.
First we set the AutoScaleRate to 0.5 with :
AutoScaleRate(0.5)

and AutoScale all views with :

AutoScaleAll

The two Labels are already on top and there are no

changes on the different screen sizes so need to set the
Top property again.
But we need to centre them on the screen with :
lblTitle.HorizontalCenter = 50%x
lblSubTitle.HorizontalCenter = 50%x

Then we centre the ToolBox with :

pnlToolBox.HorizontalCenter = 50%x

and we set the Vertical Anchor property of the ToolBox to BOTTOM to anchor it to the bottom of
the screen with :
This is needed because not all screens have the same width / height ratio and in landscape
orientation it would even not be visible.
Then we set the Vertical Anchor property of the ScrollView to BOTH because we want it to fill the
space between lblSubTitle and pnlToolBox.
We set the Bottom Edge Distance property to 60 to leave a small space of 10dip between the
ScrollView and the ToolBox.
Code in the Designer Scripts of the Main layout in the area for All variants script :
'All variants script
'Set the rate value to 0.5
AutoScaleRate(1)
'Scale all the views in the layout
AutoScaleAll
'Center the Labels horizonally to the middle of the screen
lblTitle.HorizontalCenter = 50%x
lblSubTitle.HorizontalCenter = 50%x
'Center the ToolBox Panel horizonally to the middle of the screen
pnlToolBox.HorizontalCenter = 50%x
'Center the ScrollView horizonally to the middle of the screen
scvTest.HorizontalCenter = 50%x

8 The Designer / 8.11 AutoScale

181

Basic4Android Beginner's Guide

Panel layout file :

All the Label and EditText views are on a Panel.

This is needed because they occupy more space than
the screen size.
This layout file is load into the ScrollView.Panel.
For this layout file we set also the AutoScaleRate
value to 0.5 with :
AutoScaleRate(0.5)

and AutoScale all views with :

AutoScaleAll

There is no need to modify any view after

autoscaling.

Code in the Designer Scripts of the Panel layout in the area for All variants script :
The whole code is very simply :
'All variants script
AutoScaleRate(0.5)
AutoScaleAll

In the program the code is the following :

Sub Activity_Create(FirstTime As Boolean)
' load the Main layout file
Activity.LoadLayout("Main")
' load the ScrollView.Panel layout file
scvTest.Panel.LoadLayout("Panel")
' set the ScrollView.Panel.Height to the pnlSetup Panel height
scvTest.Panel.Height = pnlSetup.Height
End Sub

We load the Main layout file into the Activity with Activity.LoadLayout("Main").
We load the Panel layout file into the ScrollView with scvTest.Panel.LoadLayout("Panel").
We set the ScrollView.Panel.Height to the height of the Panel in the layout file with :
scvTest.Panel.Height = pnlSetup.Height

8 The Designer / 8.11 AutoScale

182

Basic4Android Beginner's Guide

Screenshots of a 800/1280 10'' screen Emulator with different Rate values:

All the images have been downsized.

Rate = 0

Rate = 0.5

Rate = 0.1

Rate = 0.7

Rate = 0.3

Rate = 1.0

8 The Designer / 8.11 AutoScale

183

Basic4Android Beginner's Guide

Screenshots of a 480/800 7'' screen Emulator with different Rate values:

Rate = 0

Rate = 0.1

Rate = 0.3

Rate = 0.5

Rate = 0.7

Rate = 1

Screenshots of a 320/480 3.5'' screen Emulator. The Rate value has no influence.

8 The Designer / 8.11 AutoScale

184

Basic4Android Beginner's Guide

8.11.2 Same AutoScale example with portrait and landscape layout variants
Source code AutoScaleExample2 :

The previous example doesn't look

good on smartphone screens with
landscape orientation.

So we make a new layout variant for

landscape where we move the
ToolBox with the Buttons to the right
side of the screen.

The layout variant in the Main layout

file.
Note: Look at the anchors especially
for the ToolBox and the ScrollView.

8 The Designer / 8.11 AutoScale

185

Basic4Android Beginner's Guide

The code in the Designer Script must be changed :

For the portrait variant in the Main layout file we keep in the All variants script area only the
code below :
'All variants script
AutoScaleRate(0.5)
AutoScaleAll

Setting the rate value and autoscaling all the views.

All the other code is moved to the Variant specific script: 320x480,scale=1 area :
'Variant specific script: 320x480,scale=1
'Center the Labels horizonally to the middle of the screen
lblTitle.HorizontalCenter = 50%x
lblSubTitle.HorizontalCenter = 50%x
'Center the ToolBox Panel horizonally to the middle of the screen
pnlToolBox.HorizontalCenter = 50%x
'Center the ScrollView horizonally to the middle of the screen
scvTest.HorizontalCenter = 50%x

For the landscape variant we have in the All variants script area the same code as for the
portrait variant :
'All variants script
AutoScaleRate(0.5)
AutoScaleAll

And in the 'Variant specific script: 480x320,scale=1 area :

We centre the Title and SubTitle Labels to the middle of the space between the left screen border
and the left ToolBox boarder with :
lblTitle.HorizontalCenter = pnlToolBox.Left / 2
lblSubTitle.HorizontalCenter = pnlToolBox.Left / 2

We center the ToolBox vertically to the middle of the screen height with :
pnlToolBox.VerticalCenter = 50%y

We set the right border of the ToolBox to right border of the screen with :
pnlToolBox.Right= 100%x

We set the Vertical Anchor property of the ScrollView to BOTH to fill the space between the
bottom SubTitle Label boarder and the bottom screen boarder with.

8 The Designer / 8.11 AutoScale

186

Basic4Android Beginner's Guide

And the whole code :

'Variant specific script: 480x320,scale=1
'Center the ToolBox Panel vertically
pnlToolBox.VerticalCenter = 50%y
'Center the Labels horizonally to the middle
'of the space between the left screen border
'and the left boarder of the ToolBox Panel
lblTitle.HorizontalCenter = pnlToolBox.Left / 2
lblSubTitle.HorizontalCenter = pnlToolBox.Left / 2
'Center the ScrollView horizonally to the middle
'of the space between the left screen border
'and the left ToolBox Panel border
scvTest.HorizontalCenter = pnlToolBox.Left / 2

For the Panel layout file :

The code for the portrait variant remains the same.
We add the same code for the landscape variant :
'All variants script
AutoScaleRate(0.5)
AutoScaleAll

Here too, no code in the 'Variant specific script: 480x320,scale=1 area.

8 The Designer / 8.11 AutoScale

187

Basic4Android Beginner's Guide

8.11.3 AutoScale more advanced examples

This chapter is dedicated for more advanced users, the code is not explained here.
Source code AutoScaleExample4.
The AutoScale function in the Designer Scripts scales only views added in the Designer but not
views added in the code.
To overcome this drawback I wrote the Scale Code module included in the example code.
There are two other drawbacks :
the internal Labels of ListViews are not scaled.
with the Designer Scripts AutoScale function for some smartphone screen sizes especially
the 480 x 800 scale 1.5 screen the scaling is not optimal (at least for me).
With AutoScale on a screen with a resolution of 480 x 800 scale 1.5 (the standard screen is
320 x 480 scale 1) the views are stretched too much horizontally and not enough vertically
because of the different width/height ratio.
I added in the Scale Module a new set of equations with two scale factors one for X and one for Y.
For smartphone screens (< 6'') the views are scaled according to the screen width and the screen
height without the rate factor. For bigger screens the scale factors are modified with the rate factor.
For the big screens a rate value of 0 means no scaling and a value of 1 is equivalent to a scaling
with %x and %y.
The AutoScale function in the code module scales also the internal views in ScrollViews, ListViews
and scales the TextSize property of Spinners.
The Scale code module contains following functions:
Initialize
Calculates the scale factors
SetRate(Rate)
Sets a new Rate value and calculates the scale factors
ScaleView(View)
Scales the given view with its child views
with the new equations.
ScaleViewDS(View)
Scales the given view with its child views
with the Designer Scripts equations
ScaleAll(Activity, True)
Scales all views of the given Activity or Panel
with the new equations.
ScaleAllDS(Activity, True) Scales all views of the given Activity or Panel
with the Designer Scripts equations
GetDivicePhysicalSize
Gets the approximate physical size of the device
GetScaleDS
Returns the Disigner Scripts scale factor
GetScaleX
Returns the X scale factor
GetScaleX_L
Returns the X scale landscape factor
independant of the current orientation
GetScaleX_P
Returns the X scale portrait factor
independant of the current orientation
GetScaleY
Returns the Y scale factor
GetScaleY_L
Returns the Y scale landscape factor
independant of the current orientation
GetScaleY_P
Returns the Y scale portrait factor
independant of the current orientation
Bottom(View)
Returns the Bottom coordinate of the View

8 The Designer / 8.11 AutoScale

188

Basic4Android Beginner's Guide

Right(View)
Returns the Right coordinate of the View
HorizonzalCenter(View, x1, x2)
Centres the View horizontally the view between two
coordinates
HorizonzalCenter2(V1, V2, V3)
Centres the View V1 horizontally between two views
V2 and V3
VerticalCenter(View, x1, x2)
Centres the View horizontally the view between two
coordinates
VerticalCenter2(V1, V2, V3)
Centres the View V1 horizontally between two views
V2 and V3
IsActivity(View)
Returns True if the View is an activity
IsPanel(View)
Returns True if the View is a Panel
SetRight(View, xRight)
Sets the Left propety of the view according to the given right
coordinate xRight and the views Width property.
SetBottom(View, yBottom) Sets the Top propety of the view according to the given bottom
coordinate yBottom and the views Height property.
SetLeftAndRight(View, xLeft, xRight)
Sets the Left and Width properties of view View
according to the xLeft and xRight coordinates.
SetLeftAndRight2(V1, VL, dxL, VR, dxR) Sets the Left and Width properties of view V1
between the views VL and VR with the given spaces dxL and dxR.
SetTopAndBottom(View, yTop, yBottom) Sets the Top and Height properties of view
View according to the yTop and yBottom coordinates.
SetTopAndBottom2(V1, VT, dyT, VB, dyB)
Sets the Top and Height properties of
view V1 between the views VT and VB with the given spaces dyT and dyB.

The module is part of the attached AutoScaleExample4 project.

The project contains following activities showing different examples of the use of either Designer
Scripts AutoScale or scaling with the Code Module.
Activities:
Main
Main screen with an image and buttons.
Setup
The setup screen from the GPSExample program.
About
An about screen example.
DBWebView A database table in a WebView with a modified DBUtils version
scaling the table text size.
DBScrollView A database table in a ScrollView.
Keyboard
A keyboard with views added in the code.
ListView
A ListView with the internal Labels and Bitmap scaled.
Calculator
A calculator layout from the RPNCalc project without the functions
scaled with the new equations.
Calculator1 Same as Calculator but scaled with the Designer Scripts equations.
Positionning Example with the different positioning routines.
Code modules:
Scale
DBUtils

The scaling module

The modified DBUtils module

If you run Calculator and Calculator1 on a 480 x 800 scale 1.5 device you'll see the difference
between Designer Scripts scaling and the scaling with the new equations.
If you don't need all routines in the Scale module you can remove those not needed.
The Scale module scales also ScrollView2D views, if you don't use such a view you must comment
the corresponding lines or remove them.

8 The Designer / 8.11 AutoScale

189

Basic4Android Beginner's Guide

On the following pages you'll see some screenshots of following Emulators with Rate = 0.5 :
1280 x 800 10'' tablet

480 x 320 3.5'' smartphone

For some examples the smartphone screen is limited to portrait orientation only depending on the
screen sizes and layouts.

Main :

Setup :

About :

8 The Designer / 8.11 AutoScale

190

Basic4Android Beginner's Guide

DBWebView :

DBScrollView :

Keyboard :

8 The Designer / 8.12 UI Cloud

191

Basic4Android Beginner's Guide

8.12 UI Cloud
Since Basic4Android version 2.30 a new feature allowing to see how layouts look on different
devices.

When you have defined a layout in the Designer Scripts

you can send it to the UI Cloud in the tools menu.
The layout file is be sent to the Basic4Android site and
you get a page showing your layout on different devices
with different screen resolutions and densities.
It's a very convenient tool to check the layout look
without needing to have physical devices.

Example of a UI Cloud screen :

8 The Designer / 8.12 UI Cloud

192

Some other devices :

You can click on an image to show it in real size :

Basic4Android Beginner's Guide

9 Process and Activity life cycle

193

Basic4Android Beginner's Guide

Process and Activity life cycle

Let's start simple:

Each Basic4android program runs in its own process.
A process has one main thread which is also named the UI thread which lives as long as the process
lives. A process can also have more threads which are useful for background tasks.
A process starts when the user launches your application, assuming that it is not running already in
the background.
The process end is less determinant. It will happen sometime after the user or system has closed all
the activities.
If for example you have one activity and the user pressed on the back key, the activity gets closed.
Later when the phone gets low on memory (and eventually it will happen) the process will quit.
If the user launches your program again and the process was not killed then the same process will
be reused.
A Basic4android application is made of one or more activities. Android supports several other
"main" components. These will be added to Basic4android in the future.
Activities are somewhat similar to Windows Forms.
One major difference is that, while an activity is not in the foreground it can be killed in order to
preserve memory. Usually you will want to save the state of the activity before it gets lost. Either in
a persistent storage or in memory that is associated with the process.
Later this activity will be recreated when needed.
Another delicate point happens when there is a major configuration change in the device. The most
common is an orientation change (the user rotates the device). When such a change occurs the
current activities are destroyed and then recreated. Now it is possible to create the activity according
to the new configuration (for example, we now know the new screen dimensions).

9 Process and Activity life cycle

9.1

194

Basic4Android Beginner's Guide

How do we handle it ?

When you create a new activity you will start with the following code template:
'Activity module
Sub Process_Globals
'These global variables will be declared once when the application starts.
'These variables can be accessed from all modules.
End Sub
Sub Globals
'These global variables will be redeclared each time the activity is created.
'These variables can only be accessed from this module.
End Sub
Sub Activity_Create(FirstTime As Boolean)
End Sub
Sub Activity_Resume
End Sub
Sub Activity_Pause (UserClosed As Boolean)
End Sub

Variables can be either global or local. Local variables are variables that are declared inside a sub
other than Process_Globals or Globals.
Local variables are local to the containing sub. Once the sub ends, these variables no longer exist.
Global variables can be accessed from all subs.
There are two types of global variables.
Process variables and activity variables.

9 Process and Activity life cycle

9.2

195

Basic4Android Beginner's Guide

Process global variables

These variables live as long as the process lives.

You should declare these variables inside sub Process_Globals.
This sub is called once when the process starts (this is true for all activities, not just the first
activity).
These variables are the only "public" variables. Which means that they can be accessed from other
modules as well.
However, not all types of objects can be declared as process variables.
All of the views for example cannot be declared as process variables.
The reason is that we do not want to hold a reference to objects that should be destroyed together
with the activity.
In other words, when the activity is destroyed, all of the views that are contained in the activity are
destroyed as well. If we didn't do this, and kept a reference to a view after the Activity was
destroyed, the garbage collector would not be able to free the resource and we would have a
memory leak. If we hold a reference to a view, the garbage collector would not be able to free the
resource and we will have a memory leak.
The compiler enforces this requirement.

9.3

Activity variables

These variables are owned by the activity.

You should declare these variables inside Sub Globals.
These variables are "private" and can only be accessed from the current activity module.
All object types can be declared as activity variables.
Every time the activity is created, Sub Globals is called (before Activity_Create).
These variables exist as long as the activity exists.

9.4

Sub Activity_Create (FirstTime As Boolean)

This sub is called when the activity is created.

The activity is created
when the user first launches the application
the device configuration has changed (user rotated the device) and the activity was
destroyed
when the activity was in the background and the OS decided to destroy it in order to free
memory.
The primary purpose of this sub is to load or create the layout.(among other uses).
The FirstTime parameter tells us if this is the first time that this activity is created. First time relates
to the current process.
You can use FirstTime to run all kinds of initializations related to the process variables.
For example if you have a file with a list of values that you need to read, you can read it if
FirstTime is True and store the list as a process variable by declaring the list in Sub
Process_Globals
Now we know that this list will be available as long as the process lives and there is no need to
reload it even when the activity is recreated.
To summarize, you can test whether FirstTime is True and then initialize the process variables that
are declared in Sub Process_Globals.

8 The Designer / 8.11 AutoScale

9.5

196

Basic4Android Beginner's Guide

Globals versus FirstTime

Process_Globals and Globals should be used to declare variables.

You can also set the values of "simple" variables (numeric, strings and booleans).
You should not put any other code there.
You should instead put the code in Activity_Create.

9.6

Sub Activity_Resume
Sub Activity_Pause (UserClosed As Boolean)

Each time the activity moves from the foreground to the background Activity_Pause is called.
Activity_Pause is also called when the activity is in the foreground and a configuration change
occurs (which leads to the activity getting paused and then destroyed).
Activity_Pause is the last place to save important information.
Generally there are two types of mechanisms that allow you to save the activity state.
Information that is only relevant to the current application instance can be stored in one or more
process variables.
Other information should be stored in a persistent storage (file or database).
For example, if the user changed some settings you should save the changes to a persistent storage
at this point. Otherwise the changes may be lost.
Activity_Resume is called right after Activity_Create finishes or after resuming a paused activity
(activity moved to the background and now it returns to the foreground).
Note that when you open a different activity (by calling StartActivity), the current activity is first
paused and then the other activity will be created if needed and (always) resumed.
As discussed above Activity_Pause is called every time the activity moves from the foreground to
the background. This can happen because:
1. A different activity was started.
2. The Home button was pressed.
3. A configuration changed event was raised (orientation changed for example).
4. The Back button was pressed.
In scenarios 1 and 2, the activity will be paused and for now kept in memory as it is expected to be
reused later.
In scenario 3 the activity will be paused, destroyed and then created (and resumed) again.
In scenario 4 the activity will be paused and destroyed. Pressing on the Back button is similar to
closing the activity. In this case you do not need to save any instance specific information (the
position of pacman in a PacMan game for example).
The UserClosed parameter will be true in this scenario and false in all other. Note that it will also be
true when you call Activity.Finish. This method pauses and destroys the current activity, similar to
the Back button.
You can use UserClosed parameter to decide which data to save and also whether to reset any
related process variables to their initial state (move pacman position to the center if the position is a
process variable).

9 Process and Activity life cycle

9.7

197

Basic4Android Beginner's Guide

Activity.Finish / ExitApplication

Some explanations on how and when to use Activity.Finish and ExitApplication.

An interesting article about the functioning of Android can be found here : Multitasking the
Android way.
Most applications should not use ExitApplication but prefer Activity.Finish which lets the OS
decide when the process is killed.
You should use it only if you really need to fully kill the process.
When should we use Activity.Finish and when not ?
Let us consider following example without any Activity.Finish :
Main activity
o StartAcivity(SecondActivity)
SecondActivity activity
o StartAcivity(ThirdActivity)
ThirdActivity activity
o Click on Back button
o The OS goes back to previous activity, SecondActivity
SecondActivity activity
o Click on Back button
o The OS goes back to previous activity, Main
Main activity
o Click on Back button
o The OS leaves the program
Let us now consider following example with Activity.Finish before each StartActivity :
Main activity
o Activity.Finish
o StartAcivity(SecondActivity)
SecondActivity activity
o Activity.Finish
o StartAcivity(ThirdActivity)
ThirdActivity activity
o Click on Back button
o The OS leaves the program
We should use Activity.Finish before starting another activity only if we don't want to go back to
this activity with the Back button.

10 Variables and objects

198

Basic4Android Beginner's Guide

10 Variables and objects

A variable is a symbolic name given to some known or unknown quantity or information, for the
purpose of allowing the name to be used independently of the information it represents. A variable
name in computer source code usually associated with a data storage location and thus also its
contents, and these may change during the course of program execution. (source Wikipedia)
Basic4android type system is derived directly from Java type system.
There are two types of variables: primitives and non-primitives types.
Primitives include the numeric types: Byte, Short, Int, Long, Float and Double.
Primitives also include: Boolean and Char.

10.1 Variable Types

List of types with their ranges:
B4A
Boolean

Type
boolean

Byte

integer 8 bits

Short

integer 16 bits

Int

integer 32 bits

Long

long integer 64 bits

Float

floating point number

32 bits

Double

double precision
number
64 bits

Char
String

character
array of characters

min value
False
- 27
-128
- 2 15
- 32768
- 2 31
-2147483648
- 2 63

max value
True
27 - 1
127
2 15 -1
32767
2 31 -1
2147483647
2 63 -1

-9223372036854775808

9223372036854775807

-149

-2
1.4E-45
- 2 -1074

(2 -2 -23) * 2 127
3.4028235 E 38
(2 -2 -52) * 2 1023

2.2250738585072014 E 308

1.7976931348623157 E
308

Primitive types are always passed by value to other subs or when assigned to other variables.
For example:
Sub S1
Dim A As Int
A = 12
S2(A)
Log(A) ' Prints 12
End Sub
Sub S2(B As Int)
B = 45
End Sub

The variable A = 12
It's passed by value to routine S2
Variable A still equals 12, even though B was changed in routine S2.
Variable B = 12
Its value is changed to B = 45

10 Variables and objects

199

Basic4Android Beginner's Guide

All other types, including arrays of primitives types and strings are categorized as non-primitive
types.
When you pass a non-primitive to a sub or when you assign it to a different variable, a copy of the
reference is passed.
This means that the data itself isn't duplicated.
It is slightly different than passing by reference as you cannot change the reference of the original
variable.
All types can be treated as Objects.
Collections like lists and maps work with Objects and therefore can store any value.
Here is an example of a common mistake, where the developer tries to add several arrays to a list :
Dim arr(3) As Int
Dim List1 As List
List1.Initialize
For i = 1 To 5
arr(0) = i * 2
arr(1) = i * 2
arr(2) = i * 2
List1.Add(arr) 'Add the whole array as a single item
Next
arr = List1.Get(0) 'get the first item from the list
Log(arr(0))
'What will be printed here???

You may expect it to print 2. However it will print 10.

We have created a single array and added 5 references of this array to the list.
The values in the single array are the values set in the last iteration.
To fix this we need to create a new array each iteration.
This is done by calling Dim each iteration:
Dim arr(3) As Int 'This call is redundant in this case.
Dim List1 As List
List1.Initialize
For i = 1 To 5
Dim arr(3) As Int
arr(0) = i * 2
arr(1) = i * 2
arr(2) = i * 2
List1.Add(arr) 'Add the whole array as a single item
Next
arr = List1.Get(0) 'get the first item from the list
Log(arr(0)) 'Will print 2

Tip: You can use agraham's CollectionsExtra library to copy an array.

10 Variables and objects

200

Basic4Android Beginner's Guide

10.2 Names of variables

It is up to you to give any name to a variable, except reserved words.
A variable name must begin with a letter and must be composed by the following characters A-Z, az, 0-9, and underscore "_", no spaces, no brackets etc.
Variable names are case insensitive, that means that Index and index refer to the same variable.
But it is good practice to give them meaningful names.
Example:
Interest = Capital * Rate / 100
is meaningful
n1 = n2 * n3 / 100
not meaningful
For Views it is useful to add to the name a three character prefix that defines its type.
Examples:
lblCapital lbl > Label
Capital > purpose
edtInterest edt > EditText
Interest > purpose
btnNext
btn > Button
Next > purpose

10.3

Declaring variables

10.3.1 Simple variables

Variables are declared with the Dim keyword followed by the variable name and the As keyword
and followed by the variable type. Examples:
Dim Capital As Double
Dim Interest As Double
Dim Rate As Double

Declares three variables as Double,

double precision numbers.

Dim i As Int
Dim j As Int
Dim k As Int

Declares three variables as Int, integer numbers.

Dim edtCapital As EditText

Dim edtInterest As EditText
Dim edtRate As EditText
Dim btnNext As Button
Dim btnPrev As Button

Declares three variables as EditText views.

Declares two variables as Button views.

The same variables can also be declared in a short way.

Dim
Dim
Dim
Dim

Capital, Interest, Rate As Double

i, j, k As Int
edtCapital, edtInterest, edtRate As EditText
btnNext, btnPrev As Button

The names of the variables separated by commas and followed by the type declaration.

10 Variables and objects

201

Basic4Android Beginner's Guide

Since version2.2 of Basic4Android following variable declarations are valid:

Dim i = 0, j = 2, k = 5 As Int
Dim txt = "test" As String, value = 1.05 As Double, flag = False As Boolean

View names must be declared when we want to use them in the code.
For example, if we wan to change the text in an EditText view in the code, like
edtCapital.Text = "1200",
we need to reference this EditText view by its name edtCapital, this is done with the Dim
declaration.
If we never make any reference to this EditText view anywhere in the code no declaration is
needed.
Using an event routine for that view doesn't need a declaration either.
To allocate a value to a variable write its name followed by the equal sign and followed by the
value, like:
Capital = 1200
LastName = "SMITH"

Note that for Capital we wrote just 1200 because Capital is a number.
But for LastName we wrote "SMITH" because LastName is a string.
Strings must always be written between double quotes.

10.3.2 Array variables

Arrays are collections of data or objects that can be selected by indices. Arrays can have multiple
dimensions.
The declaration contains the Dim keyword followed by the variable name LastName, the number of
items between brackets (50), the keyword As and the variable type String.
Examples:
Dim LastName(50) As String

One dimension array of strings, total number of items 50.

Dim Matrix(3, 3) As Double

Two dimensions array of Doubles, total number of items 9.

Dim Data(3, 5, 10) As Int

Three dimensions array of integers, total number of items 150.

The first index of each dimension in an array is 0.

LastName(0), Matrix(0,0), Data(0,0,0)

The last index is equal to the number of items in each dimension minus 1.
LastName(49), Matrix(2,2), Data(2,4,9)
Dim
Dim
Dim
Dim

LastName(10) As String
FirstName(10) As String
Address(10) As String
City(10) As String

or
Dim LastName(10), FirstName(10), Address(10), City(10) As String

10 Variables and objects

202

Basic4Android Beginner's Guide

This example shows how to access all items in a three dimensional array.
For i = 0 To 2
For i = 0 To 2
For i = 0 To 2
Data(i, j, k) = ...
Next
Next
Next

A more versatile way to declare arrays is to use variables.

Dim
Dim
Dim
Dim
Dim

NbPers As Int
: NbPers = 10
LastName(NbPers) As String
FirstName(NbPers) As String
Address(NbPers) As String
City(NbPers) As String

We declare the variable Dim NbPers As Int and set its value to 10, NbPers = 10 .
The semi-colon ":" is a separator for two statement on the same line.
Then we declare the arrays with this variable instead of the number 10 as before.
The big advantage is if at some point we need to change the number of items, we change only ONE
value.
For the Data array we could use the following code.
Dim
Dim
Dim
Dim

NbX As Int
: NbX
NbY As Int
: NbY
NbZ As Int
: NbZ
Data(NbX, NbY, NbZ) As

= 2
= 5
= 10
Int

And the access routine.

For i = 0 To NbX - 1
For j = 0 To NbY For k = 0 To NbZ - 1
Data(i, j, k) = ...
Next
Next
Next

Filling an array with the Array keyword :

Dim Name() As String
Name = Array As String("Miller", "Smith", "Johnson", "Jordan")

10 Variables and objects

203

Basic4Android Beginner's Guide

10.3.3 Array of views (objects)

Views or objects can also be in an Array. The following code shows an example:
The individual names (b1, b2 etc) must also be 'Dimed'.
In the example below the Buttons are added to the Activity by code.
Sub Globals
Dim b1, b2, b3, b4, b5, b6, b7 As Button
Dim Buttons() As Button
End Sub
Sub Activity_Create(FirstTime As Boolean)
Dim i As Int
Buttons = Array As Button(b1, b2, b3, b4, b5, b6, b7)
For i = 0 To 6
Buttons(i).Initialize("Buttons")
Activity.AddView(Buttons(i), 10dip, 10dip + i * 60dip, 150dip, 50dip)
Buttons(i).Tag = i + 1
Buttons(i).Text = "Test " & (i + 1)
Next
End Sub
Sub Buttons_Click
Dim btn As Button
btn = Sender
Activity.Title = "Button " & btn.Tag & " clicked"
End Sub

The Buttons could also have been added in a layout file, in that case they must neither be initialized,
nor added to the Activity and the Text and Tag properties should also be set in the Designer.
In that case the code would look like this:
Sub Globals
Dim b1, b2, b3, b4, b5, b6, b7 As Button
Dim Buttons() As Button
End Sub
Sub Activity_Create(FirstTime As Boolean)
Dim i As Int
Buttons = Array As Button(b1, b2, b3, b4, b5, b6, b7)
End Sub
Sub Buttons_Click
Dim btn As Button
btn = Sender
Activity.Title = "Button " & btn.Tag & " clicked"
End Sub

10 Variables and objects

204

Basic4Android Beginner's Guide

10.3.4 Type variables

A Type cannot be private. Once declared it is available everywhere (similar to Class modules).
The best place to declare them is in the Process_Globalsroutine in the Main module.
Let us reuse the example with the data of a person.
Instead of declaring each parameter separately, we can define a personal type variable with the
Type keyword:
Dim NbUsers As Int
: NbUsers = 10
Type Person(LastName As String, FirstName As String. Address As String, City As String)
Dim User(NbUsers) As Person
Dim CurrentUser As Person

The new personal type is Person , then we declare either single variables or arrays of this personal
type.
To access a particular item use following code.
CurrentUser.FirstName
CurrentUser.LastName
User(1).LastName
User(1).FirstName

The variable name, followed by a dot and the desired parameter.

If the variable is an array then the name is followed by the desired index between brackets.
It is possible to assign a typed variable to another variable of the same type, as shown below.
CurrentUser = User(1)

10 Variables and objects

10.4

205

Basic4Android Beginner's Guide

Casting

Basic4android casts types automatically as needed. It also converts numbers to strings and vice
versa automatically.
In many cases you need to explicitly cast an Object to a specific type.
This can be done by assigning the Object to a variable of the required type.
For example, Sender keyword references an Object which is the object that raised the event.
The following code changes the color of the pressed button.
Note that there are multiple buttons that share the same event sub.
Sub Globals
Dim Btn1, Btn2, Btn3 As Button
End Sub
Sub Activity_Create(FirstTime As Boolean)
Btn1.Initialize("Btn")
Btn2.Initialize("Btn")
Btn3.Initialize("Btn")
Activity.AddView(Btn1, 10dip, 10dip, 200dip, 50dip)
Activity.AddView(Btn2, 10dip, 70dip, 200dip, 50dip)
Activity.AddView(Btn3, 10dip, 130dip, 200dip, 50dip)
End Sub
Sub Btn_Click
Dim btn As Button
btn = Sender
' Cast the Object to Button
btn.Color = Colors.RGB(Rnd(0, 255), Rnd(0, 255), Rnd(0, 255))
End Sub

The above code could also be written more elegantly:

Sub Globals
End Sub
Sub Activity_Create(FirstTime As Boolean)
Dim i As Int
For i = 0 To 9 ' create 10 Buttons
Dim Btn As Button
Btn.Initialize("Btn")
Activity.AddView(Btn, 10dip, 10dip + 60dip * i, 200dip, 50dip)
Next
End Sub
Sub Btn_Click
Dim btn As Button
btn = Sender
' Cast the Object to Button
btn.Color = Colors.RGB(Rnd(0, 255), Rnd(0, 255), Rnd(0, 255))
End Sub

10 Variables and objects

10.5

206

Basic4Android Beginner's Guide

Scope

10.5.1 Process variables

These variables live as long as the process lives.
You should declare these variables inside Sub Process_Globals.
This sub is called once when the process starts (this is true for all activities, not just the first
activity).
These variables are the only "public" variables. Which means that they can be accessed from other
modules as well.
However, not all types of objects can be declared as process variables.
All of the views for example cannot be declared as process variables.
The reason is that we do not want to hold a reference to objects that should be destroyed together
with the activity.
In other words, once the activity is being destroyed, all of the views which are contained in the
activity are being destroyed as well.
If we hold a reference to a view, the garbage collector would not be able to free the resource and we
will have a memory leak. The compiler enforces this requirement.
To access process global variables in other modules than the module where they were declared their
names must have the module name they were declared as a prefix.
Example:
Variable defined in a modle with the name : MyModule
Sub Process_Globals
Public MyVar As String
End Sub

Accessing the variable in MyModule module:

MyVar = "Text"

Accessing the variable in any other module:

MyModule.MyVar = "Text"

Variables can be declared with:

Dim MyVar As String

In this cas the variable is public same as Public.

It is good practice to declare the variables like this:
Public MyVar As String

This valiable is public.

It is possible to declare private variables in Sub Porcess_Globals like this:
Private MyVar As String

The variable is private to the activity or the module where it is declared.

For Activities it is better to declare them in Sub Globals.
For variables declared in Class module in Sub Class_Globals the same rules as above are valid.
Public MyVarPublic As String
Private MyVarPublic As String
Dim MyVar As String

' public
' private
' public like Public

Using Dim in Sub Class_Globals is not recommended !

10 Variables and objects

207

Basic4Android Beginner's Guide

10.5.2 Activity variables

These variables are contained by the activity.
You should declare these variables inside Sub Globals.
These variables are "private" and can only be accessed from the current activity module.
All object types can be declared as activity variables.
Every time the activity is created, Sub Globals is called (before Activity_Create).
These variables exist as long as the activity exists.

10.5.3 Local variables

Variables declared in a subroutine are local to this subroutine.
They are "private" and can only be accessed from within the subroutine where they were declared.
All objects types can be declared as local variables.
At each call of the subroutine the local variables are initialized to their default value or to any other
value you have defined in the code and are 'destroyed' when the subroutine is left.

10.6

Tips

A view can be assigned to a variable so you can easily change the common properties of the view.
For example, the following code disables all views that are direct children of the activity:
For i = 0 To Activity.NumberOfViews - 1
Dim v As View
v = Activity.GetView(i)
v.Enabled = False
Next

If we only want to disable buttons:

For i = 0 To Activity.NumberOfViews - 1
Dim v As View
v = Activity.GetView(i)
If v Is Button Then ' check whether it is a Button
v.Enabled = False
End If
Next

11 Modules

208

Basic4Android Beginner's Guide

11 Modules
At least one module exists, the main one.
Its name is always Main and cannot be changed.

There do exist four different types of modules:

Activity modules
Class modules
Code modules
Service modules
To add a new module click on either Activity, Class, Code or Service Module in the
IDE menu Project / Add New Module.

To add an existing module click on Add Existing Module in the IDE menu Project.

11 Modules

11.1

209

Basic4Android Beginner's Guide

Activity modules

Each Activity has its own module. For a better knowledge of Activity life cycle have a look at the
Process and Activity life cycle chapter.
You can add either an existing module or a new module.
To add a new Activity module click on:

The example is explained in detail in the chapter: Program with 3 Activities.

To access any object or variable in a module other than the module where they were declared you
must add the module name as a prefix to the object or variable name separated by a dot.
Examples from the ThreeActivityExample program:
Variables Value1 and Value2 are declared in Main module in Sub Process_Globals.
Sub Process_Globals
Dim Value1, Value2, Value3 As String
End Sub

To access these variables from another module the name is Main.Value1 or Main.Value2.
Sub Activity_Pause (UserClosed As Boolean)
Main.Value2 = edtValue2_P2.Text ' Sets edtValue_P2.Text to the
End Sub
' Process Global variable Value2

It is NOT possible to access any view from another activity module, because when a new activity is
started the current activity is paused and its no more accessible !

11 Modules

210

Basic4Android Beginner's Guide

11.2 Class modules

Class modules have been added to Basic4Android since version 2.0.
Class modules are explained in detail in the User's Guide.

11 Modules

11.3

211

Basic4Android Beginner's Guide

Code modules

Code modules contain code only. No activity is allowed in Code modules.

The purpose and advantage of code modules is sharing same code in different programs, mainly for
calculations or other general management.
Some code modules, called utilities, are already published by Erel in the forum:
DBUtils, Android databases are now simple. Database management utilities.
The DBUtils module is explained in the User's Guide.
HttpUtils, Android web services are now simple.
StateManager, helps managing Android application settings and state.

11 Modules

11.4

212

Basic4Android Beginner's Guide

Service modules

Service modules play an important role in the application and process life cycle.
Start with this tutorial if you haven't read it before: Android Process and activities life cycle
Code written in an activity module is paused once the activity is not visible.
So by only using activities it is not possible to run any code while your application is not visible.
Services life cycle is (almost) not affected by the current visible activity. This allows you to run
tasks in the background.
Services usually use the status bar notifications to interact with the user. Services do not have any
other visible elements. Services also cannot show any dialog (except of toast messages).
Note that when an error occurs in a service code you will not see the "Do you want to continue?"
dialog. Android's regular "Process has crashed" message will appear instead.
Before delving into the details I would like to say that using services is simpler than it may first
sound. In fact for many tasks it is easier to work with a service instead of an activity as a
service is not paused and resumed all the time and services are not recreated when the user rotates
the screen. There is nothing special with code written in service.
Code in a service module runs in the same process and the same thread as all other code.
It is important to understand how Android chooses which process to kill when it is low on memory
(a new process will later be created as needed).
A process can be in one of the three following states:
- Foreground - The user currently sees one of the process activities.
- Background - None of the activities of the process are visible, however there is a started service.
- Paused - There are no visible activities and no started services.
Paused processes are the first to be killed when needed. If there is still not enough memory,
background processes will be killed.
Foreground processes will usually not be killed.
As you will soon see a service can also bring a process to the foreground.
Adding a service module is done by choosing Project - Add New Module - Service Module.

11 Modules

213

Basic4Android Beginner's Guide

The template for new services is:

Sub Process_Globals
End Sub
Sub Service_Create
End Sub
Sub Service_Start (StartingIntent As Intent)
End Sub
Sub Service_Destroy
End Sub

Sub Process_Globals is the place to declare the service global variables. There is no other Globals
sub like in Activity as Service doesn't support Activity objects.
Sub process globals should only be used to declare variables. It should not run any other code as it
might fail. This is true for other modules as well.
Note that Process_Global variables are kept as long as the process runs and are accessible from
other modules.
Sub Service_Create is called when the service is first started. This is the place to initialize and set
the process global variables. Once a service is started it stays alive until you call StopService or
until the whole process is destroyed.
Sub Service_Start is called each time you call StartService (or StartServiceAt). When this subs
runs the process is moved to the foreground state. Which means that the OS will not kill your
process until this sub finishes running. If you want to run some code every couple of minutes /
hours you should schedule the next task with StartServiceAt inside this sub.
Sub Service_Destroy is called when you call StopService. The service will not be running after this
sub until you call StartService again (which will run Sub Service_Create followed by Sub
Service_Start).
Service use cases
As I see it there are four main use cases for services.
- Separating UI code with "business" or logic code. Writing the non-UI code in a service is easier
than implementing it inside an Activity module as the service is not paused and resumed and it is
usually will not be recreated (like an Activity).
You can call StartService during Activity_Create and from now on work with the service module.
A good design is to make the activity fetch the required data from the service in Sub
Activity_Resume. The activity can fetch data stored in a process global variable or it can call a
service Sub with CallSub method.
- Running a long operation. For example downloading a large file from the internet. In this case you
can call Service.StartForeground (from the service module). This will move your activity to the
foreground state and will make sure that the OS doesn't kill it. Make sure to eventually call
Service.StopForeground.

11 Modules

214

Basic4Android Beginner's Guide

- Scheduling a repeating task. By calling StartServiceAt you can schedule your service to run at a
specific time. You can call StartServiceAt in Sub Service_Start to schedule the next time and create
a repeating task (for example a task that checks for updates every couple of minutes).
- Run a service after boot. By checking Project - Service properties - Run At Boot your service will
run after boot is completed.
Notifications
Status bar notifications can be displayed by activities and services.
Usually services use notifications to interact with the user. The notification displays an icon in the
status bar. When the user pulls the status bar they see the notification message.

Example of a notification (using the default

icon):

The user can press on the message, which will

open an activity as configured by the
Notification object.

The notification icon is an image file which you should manually put in the following folder:
<project folder>\Object\res\drawable.
Accessing other modules
Process global objects are public and can be accessed from other modules.
Using CallSub method you can also call a sub in a different module.
It is however limited to non-paused modules. This means that one activity can never access a sub of
a different activity as there could only be one running activity.
However an activity can access a running service and a service can access a running activity.
Note that if the target component is paused then an empty string returns.
No exception is thrown.
You can use IsPause to check if the target module is paused.
For example if a service has downloaded some new information it can call:
If the Main activity is running it will fetch the data from the service process global variables and
will update the display.
It is also possible to pass the new information to the activity sub. However it is better to keep the
information as a process global variable. This allows the activity to call RefreshData whenever it
want and fetch the information (as the activity might be paused when the new information arrived).
Note that it is not possible to use CallSub to access subs of a Code module.
Examples:
Downloading a file using a service module
Periodically checking Twitter feeds

11 Modules

215

Basic4Android Beginner's Guide

11.5 Shared modules

Since Baseic4Android version 3.80 it is possible to share modules between different applications.
These module files must be stored in a specific Shared Modules folder wich must be defined in
the IDE menu Tools - Configure Paths.

You can see that a module was loaded from the shared folder in the list of modules:

Adding a shared module to a project is done in the same way as adding a non-shared module.
You choose Project -> Add Existing Module. If the module folder is the shared folder then the
module will be loaded as a shared module and will not be copied to the project folder.
If you want to convert a non-shared module to a shared module then you need to manually move the
module file to the shared modules folder and reload the project

12 Tools

216

Basic4Android Beginner's Guide

12 Tools
To find answers to many questions about Basic4Android the following tools are very useful.

12.1 Search function in the forum

In the upper right corner you find the

searchbox for the forum.
Enter a question or any keywords and
press 'Return'.
The function shows you the posts that
match your request.
Example: Enter the keyword ScrollView :
And the result :

Click on the title to show the selected post.

12 Tools

217

Basic4Android Beginner's Guide

12.2 The B4A Documentation Wiki

In the upper left corner of the forum page

you find the menu for the Documentation
Wiki.

You can browse throug it to find answers to your questions.

12 Tools

218

Basic4Android Beginner's Guide

12.3 B4AHelp
B4AHelp is a stand alone program written by Andrew Graham (agraham) showing the help files for
the diffferent libraries. It can be downloaded here.

On top we find :

In the upper left corner a drop down

list shows the different objects
included in the selected library.

Besides the objects list you find

another drop down list with the
methods(M)
events(E)
properties(P)
fields(F) constants
for the selected object.

12 Tools

219

Basic4Android Beginner's Guide

Select the standard library to display.

Select the additional library to display.
Search engine to find the object for a given keyword.
Closes B4AHelp
Launches the forum 'Online Community'.
Launches the Android Developpers site.

Standard libraries

Select the library to display and click on

(Open).

Here
you can select the directory where the
standard libraries are saved.
Once selected the directory is saved for the next start of the program.

12 Tools

220

Basic4Android Beginner's Guide

Additional libraries.
The same also for the additional libraries.

Here
additional libraries.

you can select the directory for the

Search engine for the selected library.

Exemple:
Selected library :
Enter DrawRect

Core

And the result :

We get the object Canvas and two methods.

12 Tools

221

Basic4Android Beginner's Guide

12.4 Help documentation - B4A Object Browser

This is also a standalone Windows program showing the help files of libraries.
It has been written by Vader and can be downloaded here.
A pdf documentation on how to use the program is part of the download.

12 Tools

222

Basic4Android Beginner's Guide

12.5 Usefull links

A usefull link for layout graphics. Android cheatsheet for graphic designers
Android Developpers. Getting started

Design

Android Developpers searching for any request.

In the upper right corner you find the search field.

Enter View in the field :

Click on the link View | Android Developers.

And you get all the information about Views.

Developp

Distribute

12 Tools

223

12.6 Books
Basic4Android book
Written by Philip Brown under the pseudo Wyken Seagrave.

http://basic4android.info/

MagBook Build your own Android App.

Written by Nigel Whitfield.

http://www.magbooks.com/mag-books/

Basic4Android Beginner's Guide

13 Example programs

224

Basic4Android Beginner's Guide

13 Example programs
13.1

User interfaces

Let us make three different user interfaces to select three different screens.
The three user interfaces are:
Menu

TabHost view

Button toolbox

For each test program there is a Main layout.

For each of the three pages there are separate layout files Page1, Page2 and Page3.
Each layout file is loaded to a Panel or a TabHost panel.
These layouts can contain whatever views you need.

13 Example programs

225

Basic4Android Beginner's Guide

13.1.1 Menu example (UserInterfaceMenu.b4a)

The test program is: UserInterfaceMenu.b4a.
1.
2.
3.
4.
5.

The code is self explanatory.

Each page is on a Panel, pnlPage1, pnlPage2 and pnlPage3.

The Panels are added by code.
The page layout files are loaded to the Panels.
The Menu items are added to the Activity.
One Click event routine for each Menu item.
It could also be done in one routine (like in UserInterfaceButtonToolbox.b4a).

Sub Globals
Dim pnlPage1, pnlPage2, pnlPage3 As Panel
End Sub
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Main")

' Declares the three panels

' Loads "Main" layout file

pnlPage1.Initialize("")
pnlPage1.LoadLayout("Page1")
Activity.AddView(pnlPage1,0,0,100%x,100%y)
pnlPage1.Visible=True

'
'
'
'

Initializes pnlPage1
Loads "Page1" layout file
Adds pnlPage1 to Activity
Sets pnlPage1 to Visible

pnlPage2.Initialize("")
pnlPage2.LoadLayout("Page2")
Activity.AddView(pnlPage2,0,0,100%x,100%y)
pnlPage2.Visible=False

'
'
'
'

Initializes pnlPage2
Loads "Page2" layout file
Adds pnlPage1 to Activity
Sets pnlPage1 to Visible

pnlPage3.Initialize("")
pnlPage3.LoadLayout("Page3")
Activity.AddView(pnlPage3,0,0,100%x,100%y)
pnlPage3.Visible=False

'
'
'
'

Initializes pnlPage3
Loads "Page3" layout file
Adds pnlPage1 to Activity
Sets pnlPage1 to Visible

Activity.AddMenuItem("Page 1","mnuPage1")
Activity.AddMenuItem("Page 2","mnuPage2")
Activity.AddMenuItem("Page 3","mnuPage3")
End Sub

' Adds menu item mnuPage1

' Adds menu item mnuPage2
' Adds menu item mnuPage3

Sub mnuPage1_Click
pnlPage2.Visible = False
pnlPage3.Visible = False
pnlPage1.Visible = True
End Sub

' Hides pnlPage2

' Hides pnlPage3
' Sets pnlPage1 to Visible

Sub mnuPage2_Click
pnlPage1.Visible = False
pnlPage3.Visible = False
pnlPage2.Visible = True
End Sub

' Hides pnlPage1

' Hides pnlPage3
' Sets pnlPage2 to Visible

Sub mnuPage3_Click
pnlPage1.Visible = False
pnlPage2.Visible = False
pnlPage3.Visible = True
End Sub

' Hides pnlPage1

' Hides pnlPage2
' Sets pnlPage3 to Visible

13 Example programs

226

Basic4Android Beginner's Guide

13.1.2 TabHost example (UserInterfaceTabHost.b4a)

The test program is: UserInterfaceTabHost.b4a

The code is self explanatory.

1. Each page is on a TabHost panel.

2. The TabHost view is in the Main layout.
3. The TabHost panels are added with the Page layout files.
Sub Globals
Dim pnlPage1, pnlPage2, pnlPage3 As Panel
Dim tbhPages As TabHost
End Sub
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Main")
tbhPages.AddTab("Page 1","Page1")
tbhPages.AddTab("Page 2","Page2")
tbhPages.AddTab("Page 3","Page3")
End Sub

' Declares the three panels

' Devlares the TabHost view

' Loads "Main" layout file

' Adds Page1 on the first Tab
' Adds Page2 on the second Tab
' Adds Page3 on the third Tab

13 Example programs

227

Basic4Android Beginner's Guide

13.1.3 Button toolbox example (UserInterfaceButtonToolbox.b4a)

The test program is: UserInterfaceButtonToolbox.b4a
1.
2.
3.
4.
5.

The code is self explanatory.

Each page is on a Panel, pnlPage1, pnlPage2 and pnlPage3.

The Panels are added by code.
The page layout files are loaded to the Panels.
The Buttons are in the Main layout on the pnlToolBox panel.
One Click event routine for all Buttons.

Sub Globals
Dim pnlPage1, pnlPage2, pnlPage3 As Panel
Dim pnlToolbox As Panel
End Sub

' Declares the three panels

Sub Activity_Create(FirstTime As Boolean)

Dim PanelHeight As Float
Activity.LoadLayout("Main")

' Loads "Main" layout file

' Calculates the top of the Toolbox
pnlToolbox.Top = Activity.Height - pnlToolbox.Height
PanelHeight = pnlToolbox.Top - 5dip
' Calculates the Panel height
pnlPage1.Initialize("")
' Initializes pnlPage1
pnlPage1.LoadLayout("Page1")
' Loads "Page1" layout file
Activity.AddView(pnlPage1,0,0,100%x,PanelHeight)
' Adds pnlPage1
pnlPage1.Visible=True
' Sets pnlPage1 to Visible
pnlPage2.Initialize("")
' Initializes pnlPage2
pnlPage2.LoadLayout("Page2")
' Loads "Page2" layout file
Activity.AddView(pnlPage2,0,0,100%x,PanelHeight)
' Adds pnlPage2
pnlPage2.Visible=False
' Sets pnlPage1 to Visible
pnlPage3.Initialize("")
' Initializes pnlPage3
pnlPage3.LoadLayout("Page3")
' Loads "Page3" layout file
Activity.AddView(pnlPage3,0,0,100%x,PanelHeight)
' Adds pnlPage3
pnlPage3.Visible=False
' Sets pnlPage1 to Visible
End Sub
Sub btnPage_Click
Dim Send As Button

' Declares Send as a Button

Send = Sender
pnlPage1.Visible=False
pnlPage2.Visible=False
pnlPage3.Visible=False
Select Send.Tag
Case "1"
pnlPage1.Visible=True
Case "2"
pnlPage2.Visible=True
Case "3"
pnlPage3.Visible=True
End Select
End Sub

'
'
'
'

' Sets Sender to Send

Sender is the view that raised the event
Hides pnlPage1
Hides pnlPage2
Hides pnlPage3

'
'
'
'
'
'
'

Selects the buttons tag

If Tag = 1, btnPage1
Sets pnlPage1 visible
If Tag = 2, btnPage1
Sets pnlPage2 visible
If Tag = 3, btnPage1
Sets pnlPage3 visible

13.2 Three Activity example program

228

Basic4Android Beginner's Guide

13.2 Program with 3 Activities (ThreeActivityExample.b4a)

The test program is: ThreeActivityExample.b4a
The goal of the program is:
- to show how to manage several Activities.
- working with Process Global variables across different Activities. The variables can be
changed in different activities, but are available over the whole project.
- change layout properties, in moving a small red panel over the screen.
- save and load the layout properties of the small red panel with a Map object so the square
will keep the same position after changing a page or restarting the program.
The program looks like below:

We have:
- 3 pages, each one in its own Activity.
- 3 process global variables, Value1, Value2 and Value3
- on each page 1 EditText view to modify the Value variable with page index.
- 2 Labels to display the two other variables.
- on Page1 a small red square Panel to move around.
We can:
- Change Value1 in Page1.
- Change Value2 in Page2.
- Change Value3 in Page3.
- Move the small red square over the screen.
- Select either Page2 or Page3 on Page1.

13.2 Three Activity example program

229

Basic4Android Beginner's Guide

Let us take the example with the Button toolbox (UserInterfaceButtonToolbox.b4a).

Instead of having our three pages on three panels we will use 3 activities.
Main, Page2 and Page 3.
For this we must create two new Activity Modules: Page2 and Page3.

In the IDE click on.

Enter the name Page2

and click on

A new module is added to the project.

13.2 Three Activity example program

230

Basic4Android Beginner's Guide

Modify the code of Page2 module as below:

'Activity module
Sub Process_Globals
End Sub
Sub Globals
Dim lblValue1_P2, lblValue3_P2 As Label
Dim edtValue2_P2 As EditText
End Sub
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Page2")
' Loads "Page2" layout file
End Sub
Sub Activity_Resume
lblValue1_P2.Text = Main.Value1
edtValue2_P2.Text = Main.Value2
lblValue3_P2.Text = Main.Value3
End Sub

' Sets Main.Value1 to lblValue1_P2.Text

' Sets Main.Value2 to edtValue2_P2.Text
' Sets Main.Value3 to lblValue3_P2.Text

Sub Activity_Pause (UserClosed As Boolean)

Main.Value2 = edtValue2_P2.Text ' Sets edtValue2_P2.Text to the
End Sub
' Process_Global variable Value2

Add now a new module "Page3" the same way as Page2 and modify the code like below:
'Activity module
Sub Process_Globals
End Sub
Sub Globals
Dim lblValue1_P3, lblValue2_P3 As Label
Dim edtValue3_P3 As EditText
End Sub
Sub Activity_Create(FirstTime As Boolean)
Activity.LoadLayout("Page3")
' Loads "Page3" layout file
End Sub
Sub Activity_Resume
lblValue1_P3.Text = Main.Value1
lblValue2_P3.Text = Main.Value2
edtValue3_P3.Text = Main.Value3
End Sub

' Sets Main.Value1 to lblValue1_P3.Text

' Sets Main.Value2 to lblValue2_P3.Text
' Sets Main.Value3 to edtValue3_P3.Text

Sub Activity_Pause (UserClosed As Boolean)

Main.Value3 = edtValue3_P3.Text ' Sets edtValue3_P2.Text to the
End Sub
' Process_Global variable Value3

These codes are self explanatory.

13.2 Three Activity example program

231

Basic4Android Beginner's Guide

Let us modify the code of the Main module:

In Sub Process-Globals we add following variables.
Value1, Value2 and Value3 to save some values.
mapMoveTopLeft as a Map object to save the Left and Top parameter of the small red square.
Sub Process_Globals
Dim Value1, Value2, Value3 As String

' Declares the Value variables

' as Process_Global variables
' Declares the Map as Process_Global

Dim mapMoveTopLeft As Map

End Sub

In Globals we have the variables below:

lblValue2_P1 is the Label to display Value2 on page1.
lblValue3_P1 is the Label to display Value3 on page1.
edtValue1_P1 is the EditText to enter Value1 on page1.
pnlPage1 is the container for the Page1 layout.
pnlMove is the small red square.
X0, Y0, X1 and Y1 are used to memorize initial coordinates when moving the red square.
Sub Globals
Dim lblValue2_P1, lblValue3_P1 As Label
Dim edtValue1_P1 As EditText
Dim pnlPage1 As Panel
Dim pnlToolbox, pnlMove As Panel
Dim X0, Y0, X1, Y1 As Float
End Sub

' Declares the Views

' Coordinate variables

Sub Activity_Create is modified like below:

When the routine is called for the first time, we initialize the three Value variables.
Sub Activity_Create(FirstTime As Boolean)
Dim PanelHeight As Float
Activity.LoadLayout("Main")
' Loads "Main" layout file
' Calculates the top of the
Toolbox
pnlToolbox.Top = Activity.Height - pnlToolbox.Height
PanelHeight = pnlToolbox.Top - 5dip
' Calculates the Panel height
pnlPage1.Initialize("")
' Initializes pnlPage1
pnlPage1.LoadLayout("Page1")
' Loads "Page1" layout file
Activity.AddView(pnlPage1,0,0,100%x,PanelHeight)
' Adds pnlPage1
If FirstTime = True Then
Value1 = 1000
Value2 = 2000
Value3 = 3000
End If
End Sub

' If Activity_Create is called the first time

' we initialize the three Values

13.2 Three Activity example program

232

Basic4Android Beginner's Guide

In Sub Activity_Resume we initialize the properties of the views of Activity Main.

Init.txt is the file with the Left and Top properties of the small red square pnlMove.
If the file exists we read it and set the Left and Top properties of pnlMove.
If the file doesn't exist we initialize the Map object and set the two first properties to the Left and
Top properties of pnlMove..
Sub Activity_Resume
edtValue1_P1.Text = Value1
' Attribues Value1 to edtValue1_P1.Text
lblValue2_P1.Text = Value2
lblValue3_P1.Text = Value3
' If the file does exsit, we read it
If File.Exists(File.DirInternal,"Init.txt") Then
mapMoveTopLeft = File.ReadMap(File.DirInternal,"Init.txt")
pnlMove.Left = mapMoveTopLeft.Get("Left") ' set pnlMove.Left parameter
pnlMove.Top = mapMoveTopLeft.Get("Top")
' set pnlMove.Top parameter
Else
' If the file doesn't exsit
mapMoveTopLeft.Initialize
' We initialize the Map
mapMoveTopLeft.Put("Left",pnlMove.Left)
' Setting the Left parameter
mapMoveTopLeft.Put("Top",pnlMove.Top)
' Setting the Top parameter
End If
End Sub

When the "Main" Activity is paused, due to either a page change or the program close, we:
- set variable Value1 to the edtValue1.Text content.
- save the Map to file Init.txt.
Sub Activity_Pause (UserClosed As Boolean)
Value1 = edtValue1_P1.Text
' get Value1 from edtValue1_P1.Text
File.WriteMap(File.DirInternal,"Init.txt",mapMoveTopLeft) ' Saves the Map
End Sub

To go back to Page1 from either Page2 or Page3, the user must press the Back key. To avoid that
the program stops when the user clicks, by inadvertence, one time too much, we check in Sub
Activity_KeyPress what key was pressed. And if it's the Back key we display a message in a
MessageBox asking the user if he really wants to quit the program. If Yes, then we set the Return
value to False that means that the event is sent back to the OS to close the program. If the answer is
No, we set the Return value to True, that means that we 'consume' the event and the OS will not
stop the program.
Sub Activity_KeyPress(KeyCode As Int) As Boolean
Dim Answ As Int
Dim Txt As String
If KeyCode = KeyCodes.KEYCODE_BACK Then' Checks if the KeyCode is BackKey
Txt = "Do you really want to quit the program ?"
Answ = Msgbox2(Txt,"A T T E N T I O N","Yes","","No",Null) ' MessageBox
If Answ = DialogResponse.POSITIVE Then
' If return value is Yes then
Return False
' Return = False the Event will not be consumed
Else
'
we leave the program
Return True
' Return = True
the Event will be consumed to avoid
End If
'
leaving the program
End If
End Sub

13.2 Three Activity example program

233

Basic4Android Beginner's Guide

To show how to manage layout properties we have the small red square, pnlMove, that can be
moved on the screen. The position of pnlMove is handled in Sub Activity_Touch where we get
three parameters:
- Action
holding the value of the action the user made.
ACTION_DOWN
the user touches the screen.
ACTION_MOVE
the user moves on the screen
ACTION_UP
the user leaves the screen
- X
the X coordinate of the finger on the screen.
- Y
the Y coordinate of the finger on the screen.
To be able to move pnlMove we do the following:
- when Action is equal to ACTION_DOWN, the user touches the screen
we memorize the coordinates of the finger and the coordinates of the upper left corner of
pnlMove (lines 76 to 79).
-

when Action is equal to ACTION_MOVE the user moves his finger on the screen,
we calculate the relative displacement, dX and dY, in both directions and set the new Left
and Top properties of pnlMove (lines 82 to 85).

when Action is equal to ACTION_UP, the user leaves the screen and
we update the two properties in the Map object (lines 88 and 89=.

Sub Activity_Touch (Action As Int, X As Float, Y As Float)

Dim dX, dY As Float
Select Action
Case Activity.ACTION_DOWN
X0 = X
Y0 = Y
X1 = pnlMove.Left
Y1 = pnlMove.Top

'
'
'
'
'
'

Selects the Action parameter

Checks if ACTION_DOWN
Memorizes the X coordinate
Memorizes the Y coordinate
Memorizes the Left coordinate
Memorizes the Top coordinate

Case Activity.ACTION_MOVE
dX = X - X0
dY = Y - Y0
pnlMove.Left = X1 + dX
pnlMove.Top = Y1 + dY

'
'
'
'
'

Checks if ACTION_MOVE
Calculates the X distance moved
Calculates the X distance moved
Sets the new Left coordinate
Sets the new Top coordinate

Case Activity.ACTION_UP
' Checks if ACTION_UP
mapMoveTopLeft.Put("Left",pnlMove.Left) ' Memorizes Left in the Map
mapMoveTopLeft.Put("Top",pnlMove.Top)
' Memorizes Top in the Map
End Select
End Sub

13.2 Three Activity example program

234

Basic4Android Beginner's Guide

In Sub btnPage_Click we start the Page Activity according to what button was pressed.
- We declare a new Button object, Send.
- We attribute Sender to Send .
Sender is the button view that raised the event.
- Depending on the Tag value of the sender object we start the correct Activity.
Sub btnPage_Click
Dim Send As Button
Send = Sender
Select Send.Tag
Case "2"
StartActivity("Page2")
Case "3"
StartActivity("Page3")
End Select
End Sub

' Declares Send as a Button

'
'
'
'
'
'
'

Sets Sender to Send

Sender is the view that raised the event
Selects the buttons tag
If Tag = 2, btnPage2
Calls Page2 Activity
If Tag = 3, btnPage3
Calls Page3 Activity

We still need to modify the four layout files:

Main:
We remove btnPage1, as it is no longer needed.
Enlarge the two remaining buttons and reposition them

Page 1:
We add the views like in the image at the left.

Similar for Page 2 and Page 3.

The layout files are in the project.

13.3 Scrollview example program

13.3

235

Basic4Android Beginner's Guide

ScrollView examples

ScrollView is a very versatile view to display lists of objects holding data or user interface views.
ListViews are, currently, limited to two lines of text and an image per data set.
ScrollViews have an internal Panel, bigger than the screen, that can be scrolled vertically and holds
any type of views either as one layout or as lists of view sets.
Some screenshots of examples: ( a summary of ScrollView examples)
Gridline in TableView Scrollview

Another ScrollView example

SQLLiteDB

Add imageview

ScrollView, layouts

HelpScrollView

13.3 Scrollview example program

236

Basic4Android Beginner's Guide

13.3.1 ScrollView example program

Let us make a ScrollView example with following functions:
The source code is in the ScrollViewExample folder.

Read a csv file and display it in a table based on a ScrollView.

The ScrollView can be scrolled vertically with the standard scrolling function of the
ScrollView.
The ScrollView can also be scrolled horizontally with a Seekbar or dynamically with the
finger on the lower blue rectangle ( SeekBar visible or not).
Clicking on a cell highlights the row and the cell, this routine allows adding other functions
related to a row or a cell.
Clicking on a header, displays the column, this routine allows adding functions related to a
column.

13.3 Scrollview example program

237

Basic4Android Beginner's Guide

We define the following variables and assign their default values:

StringUtils1
Used to read the csv file.
NumberOfColumns
Number of columns.
RowHeight
Height of a row in the ScrollView.
RowLineWidth
Width of the lines between the rows.
RowHeight_1
Internal height of a row
RowHeight_1 = RowHeight - RowLineWidth
ColLineWidth
Width of the lines between the columns.
ColumnWidth()
Width of the different columns as an array
ColumnWidth_1()
Internal width of the different columns.
TotalColumnWidth()
Coordinates of the left border of a column as an array.
HeaderColor
Headers background color.
HeaderFontColor
Headers font color.
HeaderLineColor
Headers line color.
LineColor
Cell line color.
CellColor
Cell background line color.
FontColor
Cell font line color.
Alignment
Text alignment of the text in the headers and cells.
SelectedRow
Index of the selected row.
SelectedRowColor
Color of the selected row.
SelectedCellColor
Color of the selected cell.
Type RowCol (Row As Int, Col As Int)
MoveLeft0
MoveX0
MoveX1
DeltaScroll
DeltaX
Time0

Define a custom variable that contains a row and a column index.

Used for the horizontal scrolling.
Used for the horizontal scrolling.
Used for the horizontal scrolling.
Used for the horizontal scrolling.
Used for the horizontal scrolling.
Used for the horizontal scrolling.

Personally, I prefer working with variables rather than with values. The maintenance and
modification of a program is much easier with variables than with numerical values.

13.3 Scrollview example program

238

Basic4Android Beginner's Guide

Sub Process_Globals
Dim StringUtils1 As StringUtils
Dim NumberOfColumns As Int
: NumberOfColumns = 5
Dim NumberOfRows As Int
Dim RowHeight As Int
: RowHeight = 30dip
Dim RowLineWidth As Int
: RowLineWidth = 1dip
Dim RowHeight_1 As Int
: RowHeight_1 = RowHeight - RowLineWidth
Dim ColLineWidth As Int
: ColLineWidth = 1dip
Dim ColumnWidth(NumberOfColumns) As Int
ColumnWidth(0) = 50dip
ColumnWidth(1) = 100dip
ColumnWidth(2) = 100dip
ColumnWidth(3) = 150dip
ColumnWidth(4) = 100dip
Dim ColumnWidth_1(NumberOfColumns) As Int
Dim TotalColumnWidth(NumberOfColumns + 1) As Int
Dim HeaderColor As Int
: HeaderColor = Colors.Blue
Dim HeaderFontColor As Int
: HeaderFontColor = Colors.Yellow
Dim HeaderLineColor As Int
: HeaderLineColor = Colors.Yellow
Dim LineColor As Int
: LineColor = Colors.Black
Dim CellColor As Int
: CellColor = Colors.RGB(255,255,220)
Dim FontColor As Int
: FontColor = Colors.Black
Dim FontSize As Float
: FontSize = 14
Dim Alignment As Int
: Alignment = Gravity.CENTER
Dim SelectedRow As Int
: SelectedRow = -1
Dim SelectedRowColor As Int
: SelectedRowColor=Colors.RGB(255,196,255)
Dim SelectedCellColor As Int
: SelectedCellColor=Colors.RGB(255,150,255)
Type RowCol (Row As Int, Col As Int)
Dim MoveLeft0, MoveX0, MoveX1, DeltaScroll, DeltaX As Float
Dim Time0 As Long
End Sub

Now we define the Views for the program:

scvPersons
ScrollView to display the data.
pnlHeader
Panel to display the headers.
skbScroll
Seekbar to scroll the ScrollView and Header.
pnlScroll
Panel for the 'dynamic' horizontal scrolling.
Timer1
Timer used the 'dynamic' horizontal scrolling.
Sub Globals
Dim scvPersons As ScrollView
Dim pnlHeader As Panel
Dim skbScroll As SeekBar
Dim pnlScroll As Panel
Dim Timer1 As Timer
End Sub

13.3 Scrollview example program

239

Basic4Android Beginner's Guide

Now we initialize the different Views and variables, we:

Initialize the panel for the horizontal scrolling.
Initialize the SeekBar for the horizontal scrolling.
Initialize the ScrollView
Initialize the internal column width and the left coordinates for each column and the total
width of all columns.
Initialize the ScrollView width.
Set the Max parameter for the Seekbar
Set the index of the selected row to -1, no row selected.
Load the csv file, set the headers and fill the ScrollView.
Initialize the Timer for the horizontal scrolling.
Sub Activity_Create(FirstTime As Boolean)
Dim i As Int
pnlScroll.Initialize("pnlScroll")
' initialize the scroll panel
Activity.AddView(pnlScroll, 0, Activity.Height - 40dip, 100%x, 40dip)
pnlScroll.Color = Colors.Blue
skbScroll.Initialize("skbScroll")
' initilaize the Seekbar
Activity.AddView(skbScroll, 0, Activity.Height - 40dip, 100%x, 40dip)
skbScroll.Visible = True
scvPersons.Initialize(0)
' initialize the ScrollView
scvPersons.Panel.Color = LineColor
Activity.AddView(scvPersons,0,RowHeight,100%x,pnlScroll.Top-RowHeight)
' initialze the internal column width and left coordinates
TotalColumnWidth(0) = ColLineWidth
For i = 0 To NumberOfColumns - 1
ColumnWidth_1(i) = ColumnWidth(i) - ColLineWidth
TotalColumnWidth(i + 1) = TotalColumnWidth(i) + ColumnWidth(i)
Next
' initializes the ScrollView width
scvPersons.Width = TotalColumnWidth(NumberOfColumns)
' initializes the Seekbar max value
skbScroll.Max = scvPersons.Width - Activity.Width
SelectedRow = -1

' sets the selected row index to -1

' loads the csv file

LoadTableFromCSV(File.DirAssets, "persons.csv", True)
' SaveTableToCSV(File.DirRootExternal, "persons.csv")
Timer1.Initialize("Timer1",100)
End Sub

13.3 Scrollview example program

240

Basic4Android Beginner's Guide

Then we read the csv file, fill the headers and the table (ScrollView).
First, if the headers exist, we read the csv file with the headers.
Or, if the headers do not exist, we read the csv file without the headers and set the default
header names to Col1, Col2 etc.
Get the number of columns.
Display the headers SetHeader(h).
Display the table, by adding the different rows to the ScrollView AddRow(row).
Sub LoadTableFromCSV(Dir As String,Filename As String,HeadersExist As Boolean)
ClearAll 'Clears the previous table and loads the CSV file to the table
Dim List1 As List
Dim h() As String
If HeadersExist Then
' Reads the csv file
Dim headers As List
List1 = StringUtils1.LoadCSV2(Dir, Filename, ",", headers)
' Sets the header names of the columns
Dim h(headers.Size) As String
For i = 0 To headers.Size - 1
h(i) = headers.Get(i)
Next
Else
' Reads the csv file
List1 = StringUtils1.LoadCSV(Dir, Filename, ",")
' Sets default header names
Dim firstRow() As String
firstRow = List1.Get(0)
Dim h(firstRow.Length)
For i = 0 To firstRow.Length - 1
h(i) = "Col" & (i + 1)
Next
End If
NumberOfColumns = h.Length ' Gets the number of columns
SetHeader(h)
' Sets the headers
NumberOfRows = 0
For i = 0 To List1.Size - 1
' Fills the table
Dim row() As String
row = List1.Get(i)
AddRow(row)
Next
End Sub

13.3 Scrollview example program

241

Basic4Android Beginner's Guide

To display the headers we:

Initialize the header panel.
Set the header panel color to the header line color.
Initialize a Label for each column name.
Set the different properties for the labels.
Add the Labels onto the header panel.
Add the header panel to the Activity
Sub SetHeader(Values() As String)
'Set the headers values
If pnlHeader.IsInitialized Then Return 'should only be called once
pnlHeader.Initialize("")
pnlHeader.Color = HeaderLineColor
For i = 0 To NumberOfColumns - 1
Dim l As Label
l.Initialize("Header")
l.Text = Values(i)
l.Gravity = Gravity.CENTER
l.TextSize = FontSize
l.Color = HeaderColor
l.TextColor = HeaderFontColor
l.Tag = i
pnlHeader.AddView(l,TotalColumnWidth(i),0,ColumnWidth_1(i),RowHeight_1)
Next
Activity.AddView(pnlHeader,scvPersons.Left,0,scvPersons.Width,RowHeight)
End Sub

13.3 Scrollview example program

242

Basic4Android Beginner's Guide

Filling a row of the ScrollView with the AddRow routine:

First we check if the number of cells is equal to the number of columns.
Initialize a Label for each cell in the row.
Set the different properties of the cell.
Initialize a RowCol variable, rc, for the label tag.
Set rc.Row to the row index and rc.Col to the column index.
Set the label tag to rc.
Add each label to the ScrollView.
Set the height of the internal panel of the ScrollView.
Sub AddRow(Values() As String)
'Adds a row to the table
If Values.Length <> NumberOfColumns Then
Log("Wrong number of values.")
Return
End If
For i = 0 To NumberOfColumns - 1
Dim l As Label
l.Initialize("cell")
l.Text = Values(i)
l.Gravity = Alignment
l.TextSize = FontSize
l.TextColor = FontColor
l.Color=CellColor
Dim rc As RowCol
rc.Initialize
rc.Col = i
rc.Row = NumberOfRows
l.Tag = rc
scvPersons.Panel.AddView(l,TotalColumnWidth(i), RowHeight * NumberOfRows, _
ColumnWidth_1(i), RowHeight_1)
Next
NumberOfRows = NumberOfRows + 1
scvPersons.Panel.Height = NumberOfRows * RowHeight
End Sub

Note: an underscore character at the end of a line means 'continue same instruction next line'.

13.3 Scrollview example program

243

Basic4Android Beginner's Guide

Other functions:
Cell_Click
Click event of one of the cells in the table.
o Dim rc as a RowCol variable and Dim l as a Label
o Set l equal to the Sender, the View that raised the event
o Set rc equal to the Sender Tag parameter
o Call the SelectRow routine
o Display in the Activities title the row and column indexes and the cell content.
Sub Cell_Click
Dim rc As RowCol
Dim l As Label
l = Sender
rc = l.Tag
SelectRow(rc)
Activity.Title = "Cell: ("&rc.Row&", "& rc.Col&") "&GetCell(rc.Row, rc.Col)
End Sub

Header_Click
Click event of one of the header cells in the table.
o Dim l as a Label and Dim col as an integer
o Set I equal to the Sender
o Set col equal to the Sender Tag parameter, which is the column index.
o Display the selected column in the Activity title.

Sub Header_Click
Dim l As Label
Dim col As Int
l = Sender
col = l.Tag
Activity.Title = "Header clicked: " & col
End Sub

13.3 Scrollview example program

244

Basic4Android Beginner's Guide

SelectRow
This routine manages the colors of the selected row and cell.
It is called from the Cell_Click routine
o Dim col as an integer.
o If there is a row selected, set the normal cell color.
o Set the SelectedRow variable to the new selected row index.
o Set the selected row and selected cell colors.

Sub SelectRow(rc As RowCol)

Dim col As Int
'Removes the color of previously selected row
If SelectedRow > -1 Then
For col = 0 To NumberOfColumns - 1
GetView(SelectedRow, col).Color = CellColor
Next
End If
SelectedRow = rc.Row
'Sets the color of the selected row and selected cell
For col = 0 To NumberOfColumns - 1
If col = rc.col Then
GetView(rc.Row, col).Color = SelectedCellColor
Else
GetView(rc.Row, col).Color = SelectedRowColor
End If
Next
End Sub

13.3 Scrollview example program

245

Basic4Android Beginner's Guide

GetView
Gets the Label object for the given row and column.
o Dim l as a Label.
o Gets the View in the given row and column, the view index in the ScrollView panel
is equal to Row * NumberOfColumns + Col.
o Returns the Label.

Sub GetView(Row As Int, Col As Int) As Label

'Returns the label in the specific cell
Dim l As Label
l = scvPersons.Panel.GetView(Row * NumberOfColumns + Col)
Return l
End Sub

GetCell
Gets the text of the Label for the given row and column.
o Gets the View in the given row and column.
o Return the Views Text parameter.

Sub GetCell(Row As Int, Col As Int) As String

'Gets the value of the given cell
Return GetView(Row, Col).Text
End Sub

SetCell
(not used in the program)
Sets the text of the Label for the given row and column.
o Gets the View in the given row and column
o Sets the Views Text parameter to the given value

Sub SetCell(Row As Int, Col As Int, Value As String)

'Sets the value of the given cell
GetView(Row, Col).Text = Value
End Sub

ClearAll
o Removes all Views (Labels) from the ScrollView Panel
o Sets the ScrollView Panel Height to 0
o Sets the selected row index to -1, no row selected

Sub ClearAll
'Clears the table
For i = scvPersons.Panel.NumberOfViews -1 To 0 Step -1
scvPersons.Panel.RemoveViewAt(i)
Next
scvPersons.Panel.Height = 0
SelectedRow = -1
End Sub

13.3 Scrollview example program

246

Basic4Android Beginner's Guide

Horizontal moving with the SeekBar

o Sets the Left parameter of the Header panel and the ScrollView.
o The SeekBar Max value was set to
skbScroll.Max = scvPersons.Width - Activity.Width.

Sub skbScroll_ValueChanged (Value As Int, UserChanged As Boolean)

'Moves the ScrollView horizontally
pnlHeader.Left = - Value
scvPersons.Left = - Value
End Sub

Horizontal scrolling with the scroll panel.

o pnlScroll_Touch and Timer1_Tick.
o I leave it up to you to find how these work.
The basic principle is to calculate the speed between ACTION_DOWN and
ACTION_UP and in the Timer routine to move dynamically the header and the
Scrollview and reducing the speed.

14 Basic language

247

Basic4Android Beginner's Guide

14 Basic language
In computer programming, BASIC (an acronym which stands for Beginner's All-purpose Symbolic
Instruction Code) is a family of high-level programming languages designed to be easy to use.
The original Dartmouth BASIC was designed in 1964 by John George Kemeny and Thomas
Eugene Kurtz at Dartmouth College in New Hampshire, USA to provide computer access to nonscience students. At the time, nearly all use of computers required writing custom software, which
was something only scientists and mathematicians tended to do. The language and its variants
became widespread on microcomputers in the late 1970s and 1980s.
BASIC remains popular to this day in a handful of highly modified dialects and new languages
influenced by BASIC such as Microsoft Visual Basic. (source Wikipedia).

14.1

Program flow

This is a summary of the more detailed explanations in Process and Activity life cycle.
'Activity module
Sub Process_Globals
'These global variables will be declared once when the application starts.
'These variables can be accessed from all modules.
End Sub
Sub Globals
'These global variables will be redeclared each time the activity is created.
'These variables can only be accessed from this module.
End Sub
Sub Activity_Create(FirstTime As Boolean)
End Sub
Sub Activity_Resume
End Sub
Sub Activity_Pause (UserClosed As Boolean)
End Sub

The program goes through following routines when starting from top to down:

14.1.1 Process_Globals routine

Dedicated to the declaration of process global variables. Variables that are valid during the whole
life time of the process and accessible from everywhere in the program.

14 Basic language

248

Basic4Android Beginner's Guide

14.1.2 Globals routine

Dedicated to the declaration of activity global variables. Variables that are valid only during the life
time of the activity and accessible only insides the activity. As soon as the activity is paused, these
variables are no more available.

14.1.3 Activity_Create (FirstTime As Boolean) routine

Area to initialize activity variables.
If variables or objects must be initialized only once, the first time at the launch of the application,
you can use the FirstTime parameter to check it.
Sub Activity_Create(FirstTime As Boolean)
If FirstTime = True Then
Initialize
End If
End Sub

14.1.4 Activity_Resume routine

This routine is called every time an activity is launched or resumed, re-activated, Here you can set
any setup parameters for the new current activity.

14.1.5 Activity_Pause (UserClosed As Boolean) routine

When the activity is going to be paused, this routine Activity_Pause is called.
Here you need to save activity parameters you want to get back when the activity is resumed (reactivated)
One of the most frequent reasons why an activity is paused, is an orientation change.
In that case the current activity is 'paused', and re-activated with the new orientation and goes at
least through the Activity_Resume routine, but normally through Globals, Activity_Create and
Activity_Resume.
The variable UserClosed can be used to differentiate if the Activity has been paused by the
Operating System (ex: orientation change) or by the user (ex: back button click).

14 Basic language

249

Basic4Android Beginner's Guide

Program flow: Example: MyFirstProgram.

1. The program calls

Process_Globals.
In the example there is no
code.
2. Then the program calls
Globals.
Declares the variables.

3. Then the program calls

Activity_Create.
Loads the "Main" layout.
Calls the New subroutine.

4. The code in Sub New is

executed.
When reaching End Sub, the
program goes back to the line
following New.
In this case line 25.

5. Activity_Resume is called.
No code.

6. The program waits for an

event.

7. If the user clicks on the

Button btnAction
The Sub btnAction_Click
routine is called and the
code inside the Sub is
executed.
8. The program waits for

14 GPS
another event.

250

Basic4Android Beginner's Guide

14 Basic language

251

Basic4Android Beginner's Guide

14.2 Expressions
An expression in a programming language is a combination of explicit values, constants, variables,
operators, and functions that are interpreted according to the particular rules of precedence and of
association for a particular programming language, which computes and then produces (returns)
another value. This process, like for mathematical expressions, is called evaluation. The value can
be of various types, such as numerical, string, and logical (source Wikipedia).
For example, 2 + 3 is an arithmetic and programming expression which evaluates to 5. A variable is
an expression because it is a pointer to a value in memory, so y + 6 is an expression. An example of
a relational expression is 4 = 4 which evaluates to True (source Wikipedia).

14.2.1 Mathematical expressions

Operator

Example

x + y

Addition

x - y

Subtraction

x * y

Multiplication

x / y

Division

Modulo

Power of

Mod
Power

Precedence level Operation

x Mod y
Power(x,y) x

Precedence level: In an expression, operations with level 1 are evaluated before operations with
level 2, which are evaluated before operations with level 3.
Examples:
4 + 5 * 3 + 2 = 21

> 4 + 15 + 2

(4 + 5) * (3 + 2) = 45

> 9*5

(4 + 5)2 * (3 + 2) = 405
Power(4+5,2)*(3+2)

> 92 * 5

11 Mod 4 = 3

> Mod is the remainder of 10 / 4

233

> 23 at the power of 3

Power(23,3)

- 22 = - 4
(-2)2 = 4

> 81 * 5

14 Basic language

252

Basic4Android Beginner's Guide

14.2.2 Relational expressions

In computer science in relational expressions an operator tests some kind of relation between two
entities. These include numerical equality (e.g., 5 = 5) and inequalities (e.g., 4 >= 3).
In B4A these operators return True or False, depending on whether the conditional relationship
between the two operands holds or not (source Wikipedia).

Operator

Example

Used to test

x=y

the equivalence of two values

<>

x <> y

the negated equivalence of two values

>

x>y

if the value of the left expression is greater than that of the right

<

x<y

if the value of the left expression is less than that of the right

>=

x >= y

if the value of the left expression is greater than or equal to that of the right

<=

x <= y

if the value of the left expression is less than or equal to that of the right

14.2.3 Boolean expressions

In computer science, a Boolean expression is an expression that produces a Boolean value when
evaluated, i.e. one of True or False. A Boolean expression may be composed of a combination of
the Boolean constants True or False, Boolean-typed variables, Boolean-valued operators, and
Boolean-valued functions (source Wikipedia).
Boolean operators are used in conditional statements such as IF-Then and Select-Case.
Operator
Or

Comment
Boolean Or

Z = X Or Y

Z = True if X or Y is equal to True or both are True

And

Boolean And

Z = X And Y Z = True if X and Y are both equal to True

Not ( )

Boolean Not

X = True Y = Not(X) > Y = False

Or

And

False

False

False

False

True

False

True

False

False

True

True

False

True

True

True

True

14 Basic language

14.3

253

Basic4Android Beginner's Guide

Conditional statements

Different conditional statements are available in Basic.

14.3.1 If Then End If

The If-Then-Else structure allows to operate conditional tests and execute different code sections
according to the test result.
General case:
If test1 Then
' code1
Else If test2 Then
' code2
Else
' code3
End If

The If-Then-Else structure works as follows:

1. When reaching the line with the If keyword, test1 is executed.
2. If the test result is True, then code1 is executed until the line with the Else If keyword.
And jumps to the line following the End If keyword and continues.
3. If the result is False, then test2 is executed.
4. If the test result is True, then code2 is executed until the line with the Else keyword.
And jumps to the line following the End If keyword and continues.
5. If the result is False, then code3 is executed and continues at the line following the End
If keyword.
The tests can be any kind of conditional test with two possibilities True or False.
Some examples:
If b = 0 Then
a = 0
End If

The simplest If-Then structure.

If b = 0 Then a = 0

The same but in one line.

If b = 0 Then
a = 0
Else
a = 1
End If

The simplest If-Then-Else structure.

If b = 0 Then a = 0 Else a = 1

The same but in one line.

Personally, I prefer the structure on several lines, better readable.

An old habit from HP Basic some decades ago, this Basic accepted only one instruction per line.

14 Basic language
Note. Difference between:
B4A
Else If

254

Basic4Android Beginner's Guide

VB
ElseIf

In B4A there is a blank character between Else and If.

Some users try to use this notation:
If b = 0 Then a = 0 : c = 1

There is a big difference between B4A and VB that gives errors :

The above statements is equivalent to :
B4A
VB
If b = 0 Then
a = 0
End If
c = 1

If b = 0 Then
a = 0
c = 1
End If

The semicolon character ' : ' in the line above is treated in B4A like a CarriageReturn CR character.

14 Basic language

255

Basic4Android Beginner's Guide

14.3.2 Select Case

The Select - Case structure allows to compare a TestExpression with other Expressions and
to execute different code sections according to the matches between the TestExpression and
Expressions.
General case:
TestExpression is the expression to test.

Select TestExpression
Case ExpressionList1
' code1
Case ExpressionList2
' code2
Case Else
' code3
End Select

ExpressionList1 is a list of expressions to compare

to TestExpression
ExpressionList2 is another list of expressions to compare
to TestExpression

The Select - Case structure works as follows:

1. The TestExpression is evaluated.
2. If one element in the ExpressionList1 matches TestExpression then executes
code1 and continues at the line following the End Select keyword.
3. If one element in the ExpressionList2 matches TestExpression then executes
code2 and continues at the line following the End Select keyword.
4. For no expression matches TestExpression executes code3
and continues at the line following the End Select keyword.
TestExpression can be any expression or value.
ExpressionList1 is a list of any expressions or values.

Examples:
Select Value
Case 1, 2, 3, 4

The Value variable is a numeric value.

Select a + b
Case 12, 24

The TestExpression is the sum of a + b

Select Txt.CharAt
Case "A", "B", "C"

The TestExpression is a character at

Sub Activity_Touch (Action As Int, X As Float, Y As Float)

Select Action
Case Activity.ACTION_DOWN
Case Activity.ACTION_MOVE
Case Activity.ACTION_UP
End Select
End Sub

14 Basic language
Note. Differences between:
B4A
Select Value
Case 1,2,3,4,8,9,10

256

VB
Select Case Value
Case 1 To 4 , 8 To 9

In VB the keyword Case is added after the Select keyword.

VB accepts Case 1 To 4 , this is not implemented in B4A.

Basic4Android Beginner's Guide

14 Basic language

14.4

257

Basic4Android Beginner's Guide

Loop structures

Different loop structures are available in Basic.

14.4.1 For Next

In a ForNext loop a same code will be executed a certain number of times.
Example:
For i = n1 To n2 Step n3
' Specific code

i
n1
n2
n3

incremental variable
initial value
final value
step

Next

The ForNext loop works as below:

1. At the beginning, the incremental variable i is equal to the initial value n1.
i = n1
2. The specific code between the For and Next keywords is executed.
3. When reaching Next, the incremental variable i is incremented by the step value n3.
i = i + n3.
4. The program jumps back to For, compares if the incremental variable i is lower or equal to
the final value n2.
test if i <= n2
5. If Yes, the program continues at step 2, the line following the For keyword.
6. If No, the program continues at the line following the Next keyword.
If the step value is equal to '+1' the step keyword is not needed.
For i = 0 To 10

For i = 0 To 10 Step 1

is the same as
Next

Next

The step variable can be negative.

For i = n3 To 0 Step -1
Next

It is possible to exit a For Next loop with the Exit keyword.

For i = 0 To 10
' code
If A = 0 Then Exit
' code
Next

In this example, if the variable a equals 0

Then exit the loop.

14 Basic language
Note : Differences between
B4A
Next
Exit

258

Basic4Android Beginner's Guide

VB
Next i
Exit For

In VB :
The increment variable is added after the Next Keyword.
The loop type is specified after the Exit keyword.

14.4.2 For - Each

This loop was introduced in Basic4Android version 2.2.
It is a variant of the For - Next loop.
Example:
For Each n As Type In Array
' Specific code

n
Type
Array

variable any type or object

type of variable n
Array of values or objects

Next

The ForEach loop works as below:

1. At the beginning, n gets the value of the first element in the Array.
n = Array(0)
2. The specific code between the For and Next keywords is executed.
3. When reaching Next, the program checks if n is the last element in the array.
4. If No, the variable n gets the next value in the Array and continues at step 2, the line
following the For keyword.
n = Array(next)
5. If Yes, the program continues at the line following the Next keyword.
Example For - Each :
Dim Numbers() As Int
Dim Sum As Int
Numbers = Array As Int(1, 3, 5 , 2, 9)
Sum = 0
For Each n As Int In Numbers
Sum = Sum + n
Next

Same example but with a For - Next loop :

Dim Numbers() As Int
Dim Sum As Int
Dim i As Int
Numbers = Array As Int(1, 3, 5 , 2, 9)
Sum = 0
For i = 0 To Numbers.Length - 1
Sum = Sum + Numbers(i)
Next

14 Basic language

259

Basic4Android Beginner's Guide

This example shows the power of the For - Each loop :

For Each lbl As Label In Activity
lbl.TextSize = 20
Next

Same example with a For - Next loop :

For i = 0 To Activity.NumberOfViews - 1
Dim v As View
v = Activity.GetView(i)
If v Is Label Then
Dim lbl As Label
lbl = v
lbl.TextSize = 20
End If
Next

14.4.3 Do - Loop
Several configurations exist:
Do While test
' code
Loop

test is any expression

Executes the code while test is True

Do Until test
' code
Loop

test is any expression

Executes the code until test is True

The Do While -Loop loop works as below :

1. At the beginning, test is evaluated.
2. If True, then executes code
3. If False continues at the line following the Loop keyword.
The Do Until -Loop loop works as below :
1. At the beginning, test is evaluated.
2. If False, then executes code
3. If True continues at the line following the Loop keyword.
It is possible to exit a Do-Loop structure with the Exit keyword.
Do While test
' code
If a = 0 Then Exit
' code
Loop

If a = 0 then exit the loop

14 Basic language

260

Basic4Android Beginner's Guide

Examples :
Do Until Loop :
Dim i, n As Int
i = 0
Do Until i = 10
' code
i = i + 1
Loop

Do While Loop :
Dim i, n As Int
i = 0
Do While i < 10
' code
i = i + 1
Loop

Read a text file and fill a List :

Dim lstText As List
Dim line As String
Dim tr As TextReader
tr.Initialize(File.OpenInput(File.DirInternal, "test.txt"))
lstText.Initialize
line = tr.ReadLine
Do While line <> Null
lstText.Add(line)
line = tr.ReadLine
Loop
tr.Close

Note : Difference between:

B4A
Exit

VB
Exit Loop

In VB the loop type is specified after the Exit keyword.

VB accepts also the following loops, which are not supported in B4A.
Do
' code
Loop While test

Do
' code
Loop Until test

14 Basic language

261

Basic4Android Beginner's Guide

14.5 Subs
A Subroutine (Sub) is a piece of code. It can be any length, and it has a distinctive name
and a defined scope (in the means of variables scope discussed earlier). In Basci4Android code, a
subroutine is called Sub, and is equivalent to procedures, functions, methods and
subs in other programming languages. The lines of code inside a Sub are executed from
first to last, as described in the program flow chapter.
It is not recommended to have too long Subs, they get less readable.

14.5.1 Declaring
A Sub is declared in the following way:
Sub CalcInterest(Capital As Double, Rate As Double) As Double
Return Capital * Rate / 100
End Sub

It starts with the keyword Sub, followed by the Subs name, followed by a parameter list, followed
by the return type and ends with the keywords End Sub.
Subs are always declared at the top level of the module, you cannot nest two Subs
one inside the other.

14.5.2 Calling a Sub

When you want to execute the lines of code in a Sub, you simply write the Subs name.
For example:
Interest = CalcInterest(1234, 5.2)

Interest
CalcInterest
1235
5.25

Value returned by the Sub.

Sub name.
Capital value transmitted to the Sub.
Rate value transmitted to the Sub.

14.5.3 Calling a Sub from another module

A subroutine declared in a code module can be accessed from any other module but the name of the
routine must have the name of the nodule where it was declared as a prefix.
Example: If the CalcInterest routine were declared in the moduel MyModule then calling the routine
must be :
Interest = MyModule.CalcInterest(1234, 5.2)

instead of:
Interest = CalcInterest(1234, 5.2)

14 Basic language

262

Basic4Android Beginner's Guide

14.5.4 Naming
Basically, you can name a Sub any name thats legal for a variable. It is recommended to
name the Sub with a significant name, like CalcInterest in the example, so you can tell what it
does from reading the code.
There is no limit on the number of Subs you can add to your program, but it is not
allowed to have two Subs with the same name in the same module.
Sub CalcInterest(Capital As Double, Rate As Double) As Double
Return Capital * Rate / 100
End Sub

14.5.5 Parameters
Parameters can be transmitted to the Sub. The list follows the sub name. The parameter list is put in
brackets.
The parameter types should be declared directly in the list.
Sub CalcInterest(Capital As Double, Rate As Double) As Double
Return Capital * Rate / 100
End Sub

In B4A, the parameters are transmitted by value and not by reference.

14.5.6 Returned value

A sub can return a value, this can be any object.
Returning a value is done with the Return keyword.
The type of the return value is added after the parameter list.
Sub CalcInterest(Capital As Double, Rate As Double) As Double
Return Capital * Rate / 100
End Sub

14 Basic language

263

Basic4Android Beginner's Guide

14.6 Events
In Object-oriented programming we have objects which can react on different user actions called
events.
The number and the type of events an object can raise depend on the type of the object.
User interface objects are called 'Views' in Android.
Summary of the events for different views :

Button
CheckBox
EditText
HorizontalScrollView
ImageView
Label
ListView
Panel
RadioButton
ScrollView
SeekBar
Spinner
TabHost
ToggleButton
WebView

PageFinished

OverrideUrl

TabChanged

ValueChanged

ScrollChanged

TextChanged

FocusChanged

EnterPressed

ItemLongClick

ItemClick

KeyUp

KeyPress

Up

Down

Touch

CheckedChange

Views
Activity

LongClick

Click

Events

14 Basic language

264

Basic4Android Beginner's Guide

The most common events are:

Click
Example:

Event raised when the user clicks on the view.

Sub Button1_Click
' Your code
End Sub

LongClick
Example:

Event raised when the user clicks on the view and holds it pressed for a while.

Sub Button1_LongClick
' Your code
End Sub

Touch (Action As Int, X As Float, Y As Float)

Event raised when the user touches the screen.
Three different actions are handled:
- Activity.Action_DOWN, the user touches the screen.
- Activity.Action_MOVE, the user moves the finger without leaving the screen.
- Activity.Action_UP,
the user leaves the screen.
The X an Y coordinates of the finger position are given.
Example:
Sub Activity_Touch (Action As Int, X As Float, Y As Float)
Select Action
Case Activity.ACTION_DOWN
' Your code for DOWN action
Case Activity.ACTION_MOVE
' Your code for MOVE action
Case Activity.ACTION_UP
' Your code for UP action
End Select
End Sub

CheckChanged (Checked As Boolean)

Event raised when the user clicks on a CheckBox or a RadioButton
Checked is equal to True if the view is checked or False if not checked.
Example:
Sub CheckBox1_CheckedChange(Checked As Boolean)
If Checked = True Then
' Your code if checked
Else
' Your code if not checked
End If
End Sub

14 Basic language

265

Basic4Android Beginner's Guide

KeyPress (KeyCode As Int) As Boolean

Event raised when the user presses a physical or virtual key.
KeyCode is the code of the pressed key, you can get them with the KeyCodes keyword.

The event can return either:

- True, the event is 'consumed', considered by the operating system as already executed and
no further action is taken.
- False, the event is not consumed and transmitted to the system for further actions.
Example:
Sub Activity_KeyPress(KeyCode As Int) As Boolean
Dim Answ As Int
Dim Txt As String
If KeyCode = KeyCodes.KEYCODE_BACK Then ' Checks if KeyCode is BackKey
Txt = "Do you really want to quit the program ?"
Answ = Msgbox2(Txt,"A T T E N T I O N","Yes","","No",Null)' MessageBox
If Answ = DialogResponse.POSITIVE Then ' If return value is Yes then
Return False
' Return = False the Event will not be consumed
Else
'
we leave the program
Return True
' Return = True
the Event will be consumed to avoid
End If
'
leaving the program
End If
End Sub

14 Basic language

14.7

266

Basic4Android Beginner's Guide

Libraries

Libraries add more objects and functionalities to B4A.

Some of these libraries are shipped with B4A and are part of the standard development system.
Other, often developed by users like Andrew Graham (agraham), can be downloaded (by registered
users only) to add supplementary functionalities to the B4A development environment.
When you need a library, you have to:
- Check in the Lib Tab, if you already have the library.
- For additional libraries, check if it's the latest version.
- If yes, then check the library in the list to select it.

If no, download the library, unzip it and copy the

<LibraryName>.jar and <LibraryName>.xml files to the additional libraries folder.
Restart the IDE and check the library in the Lib Tab list to select it.

14.7.1 Standard libraries

The standard B4A libraries are saved in the Libraries folder in the B4A program folder.
Normally in: C:\Program Files\Anywhere Software\Basic4android\Libraries

14.7.2 Additional libraries folder

For the additional libraries it is useful to setup a special folder to save them somewhere else.
For example: D:\Basic4Android\AddLibraries
When you install a new version of B4A, all standard libraries are automatically updated, but the
additional libraries are not included. The advantage of the special folder is that you don't need to
care about them because this folder is not affected when you install the new version of B4A.
The additional libraries are not systematically updated with new version of B4A.
When the IDE starts, it looks first for the available libraries in the Libraries folder of B4A and then
in the folder for the additional libraries.

14 Basic language

267

Basic4Android Beginner's Guide

If you setup a special additional libraries folder you must specify it in the IDE.
In the menu Tools / Configure Paths:

Enter the folder name and click on

14.7.3 Load and update a Library

A list of the official and additional libraries with links to the relevant forum threads is shown in the
B4A Wiki here: List of Libraries
To load or update a library follow the steps below:
Download the library zip file somewhere.
Unzip it.
Copy the xxx.jar and xxx.xml files to the
o B4A Library folder for a standard B4A library
o Additional libraries folder for an additional library.
Restart the IDE and check the library in the Lib Tab list to select it.

14 Basic language

268

Basic4Android Beginner's Guide

14.7.4 Error message "Are you missing a library reference?"

If you get this message, means that you forgot to check the specified library in the Lib Tab list !

14 Basic language

269

Basic4Android Beginner's Guide

14.8 String manipulation

Basic4Android allows string manipulations like other Basic languages but with some differences.
These manipulations can be done directly on a string.
Example:
txt = "123,234,45,23"
txt = txt.Replace(",", ";")

Result: 123;234;45;23
The different functions are:
CharAt(Index)
Returns the character at the given index.
CompareTo(Other)
Lexicographically compares the string with the Other string.
Contains(SearchFor)
Tests whether the string contains the given SearchFor string.
EndsWith(Suffix)
Returns True if the string ends with the given Suffix substring.
EqualsIgnoreCase(Other) Returns True if both strings are equal ignoring their case.
GetBytes(Charset)
Encodes the Charset string into a new array of bytes.
IndexOf(SearchFor)
Returns the index of the first occurrence of SearchFor in the
string.
IndexOf2(SearchFor, Index)
Returns the index of the first occurrence of SearchFor
in the string. Starts searching from the given index.
LastIndexOf(SearchFor) Returns the index of the first occurrence of SearchFor in the
string. Starts searching from the end of the string.
Length
Returns the length, number of characters, of the string.
Replace(Target, Replacement)
Returns a new string resulting from the replacement of
all the occurrences of Target with Replacement.
StartsWith(Prefix)
Returns True if this string starts with the given Prefix.
Substring(BeginIndex)
Returns a new string which is a substring of the original string.
The new string will include the character at BeginIndex and will extend to the end of the
string.
Substring2(BeginIndex,EndIndex)
Returns a new string which is a substring of the
original string. The new string will include the character at BeginIndex and will extend to
the character at EndIndex, not including the last character.
ToLowerCase
Returns a new string which is the result of lower casing this string.
ToUpperCase
Returns a new string which is the result of upper casing this string.
Trim
Returns a copy of the original string without any leading or trailing
white spaces.
Number formatting, display numbers as strings with different formats, there are two keywords:
NumberFormat(Number As Double, MinimumIntegers As Int, MaximumFractions As Int)
NumberFormat(12345.6789, 0, 2) = 12,345.68
NumberFormat(1, 3 ,0)
= 001
NumberFormat(Value, 3 ,0)
variables can be used.
NumberFormat(Value + 10, 3 ,0) arithmetic operations can be used.
NumberFormat((lblscore.Text + 10), 0, 0) if one variable is a string add parentheses.

NumberFormat2(Number As Double, MinimumIntegers As Int, MaximumFractions As

Int, MinimumFractions As Int, GroupingUsed As Boolean)
NumberFormat2(12345.67, 0, 3, 3, True)
= 12,345.670

14 Basic language

14.9

270

Basic4Android Beginner's Guide

Timers

A Timer object generates ticks events at specified intervals. Using a timer is a good alternative to a
long loop, as it allows the UI thread to handle other events and messages.
Note that the timer events will not fire while the UI thread is busy running other code (unless you
call DoEvents keyword).
Timer events will not fire when the activity is paused, or if a blocking dialog (like Msgbox) is
visible.
It is also important to disable the timer when the activity is pausing and then enable it when it
resumes. This will save CPU and battery.
A timer has:
Three parameters.
o Initialize
Initializes the timer with two parameters, the EventName and the
interval.
Timer1.Initialize(EventName As String, Interval As Long)
Ex: Timer1.Initialize("Timer1", 1000)
o Interval
Sets the timer interval in milli-seconds.
Timer1. Interval = Interval
Ex: Timer1.Interval = 1000, 1 second
o Enabled
Enables or disables the timer. It is False by default.
Ex: Timer1.Enabled = True

One Event
o Tick
The Tick routine is called every time interval.
Ex: Sub Timer1_Tick

The Timer must be declared in a Process_Global routine.

Sub Process_Globals
Dim Timer1 As Timer

But it must be initialized in the Activity_Create routine in the module where the timer tick
event routine is used.
Sub Activity_Create(FirstTime As Boolean)
If FirstTime = True Then
Timer1.Initialize("Timer1", 1000)
End If

And the Timer Tick event routine.

This routine will be called every second (1000 milli-seconds) by the operating system.
Sub Timer1_Tick
' Do something
End Sub

You find an example in the RotatingNeedle example program.

14 Basic language

271

Basic4Android Beginner's Guide

14.10 Files
Many applications require access to a persistent storage. The two most common storage types are
files and databases.

14.10.1

File object

The predefined object File has a number of functions for working with files.
Files locations - There are several important locations where you can read or write files.
File.DirAssets
The assets folder includes the files that were added with the file manager in the IDE.
It's the Files folder in the project folder.
These files are read-only.
You can not create new files in this folder (which is actually located inside the apk file).
If you have a database file in the Dir.Assets folder you need to copy it to another folder before you
can use it.
File.DirInternal / File.DirInternalCache
These two folders are stored in the main memory of the device and are private to your application.
Other applications cannot access these files.
The cache folder may get deleted by the OS if it needs more space.
File.DirRootExternal
The storage card root folder.
File.DirDefaultExternal
The default folder for your application in the SD card.
The folder is: <storage card>/Android/data/<package>/files/
It will be created if required.
Note that calling any of the two above properties will add the EXTERNAL_STORAGE permission
to your application.
Tip: You can check if there is a storage card and whether it is available with
File.ExternalReadable and File.ExternalWritable.
To check if a file already exists use:
File.Exists ( Dir As String, FileName As String)
Returns True if the file exists and False if not.
The File object includes several methods for writing to files and reading from files.
To be able to write to a file or to read from a file, it must be opened.

14 Basic language

272

Basic4Android Beginner's Guide

File.OpenOutput (Dir As String, FileName As String, Append As Boolean)

- Opens the given file for output, the Append parameter tells whether the text will be added at the
end of the existing file or not. If the file doesn't exist it will be created.
File.OpenInput (Dir As String, FileName As String)
- Opens the file for reading.
File.WriteString (Dir As String, FileName As String, Text As String)
- Writes the given text to a new file.
File.ReadString (Dir As String, FileName As String) As String
- Reads a file and returns its content as a string.
File.WriteList (Dir As String, FileName As String, List As List)
- Writes all values stored in a list to a file. All values are converted to string type if required. Each
value will be stored in a separare line.
Note that if a value contains the new line character it will saved over more than one line and when
you read it, it will be read as multiple items.
File.ReadList (Dir As String, FileName As String) As List
- Reads a file and stores each line as an item in a list.
File.WriteMap (Dir As String, FileName As String, Map As Map)
- Takes a map object which holds pairs of key and value elements and stores it in a text file. The file
format is known as Java Properties file: .properties - Wikipedia, the free encyclopedia
The file format is not too important unless the file is supposed to be edited manually. This format
makes it easy to edit it manually.
One common usage of File.WriteMap is to save a map of "settings" to a file.
File.ReadMap (Dir As String, FileName As String) As Map
- Reads a properties file and returns its key/value pairs as a Map object. Note that the order of
entries returned might be different than the original order.
Some other useful functions:
File.Copy (DirSource As String, FileSource As String, DirTarget As String, FileTarget As String)
- Copies the source file from the source directory to the target file in the target directory.
Note that it is not possible to copy files to the Assets folder.
File.Delete (Dir As String, FileName As String)
- Deletes the given file from the given directory.
File.ListFiles (Dir As String) As List
- Lists the files and subdirectories in the diven directory.
Example:
Dim List1 As List

List1 = File.ListFiles(File.DirRootExternal)

List1 can be 'dimed' in Sub Globals

File.Size (Dir As String, FileName As String)
- Returns the size in bytes of the specified file.
This method does not support files in the assets folder.

14 Basic language

14.10.2

273

Basic4Android Beginner's Guide

Filenames

Android file names allow following characters :

a to z, A to Z, 0 to 9 dot . underscore _ and even following characters + - % &
Spaces and following characters * ? are not allowed.
Example : MyFile.txt
Note that Android file names are case sensitive !
MyFile.txt is different from myfile.txt

14.10.3

Subfolders

You can define subfolders in Android with.

File.MakeDir(File.DirInternal, "Pictures")

To access the subfolder you should add the subfoldername to the foldername with "/" inbetween.
ImageView1.Bitmap = LoadBitmap(File.DirInternal & "/Pictures", "test1.png")

Or add the subfoldername before the filename with "/" inbetween.

ImageView1.Bitmap = LoadBitmap(File.DirInternal, "Pictures/test1.png")

Both possibilities work.

14 Basic language

14.10.4

274

Basic4Android Beginner's Guide

TextWriter

There are two other useful functions for text files: TextWriter and TextReader:
TextWriter.Initialize (OutputStream As OutputStream)
- Initializes a TextWriter object as an output stream.
Example:
Dim Writer As TextWriter
Writer.Initialize(File.OpenOutput(File.DirRootExternal, "Test.txt" , False))

Writer could be 'dimed' in Sub Globals.

TextWriter.Initialize2 (OutputStream As OutputStream , Encoding As String)
- Initializes a TextWriter object as as output stream.
- Encoding indicates the CodePage (also called CharacterSet), the text encoding (see next chapter).
Example:
Dim Writer As TextWriter
Writer.Initialize2(File.OpenOutput(File.DirRootExternal,"Test.txt" ,False)," ISO-8859-1")

Writer could be 'dimed' in Sub Globals.

See : Text encoding
TextWriter.Write (Text As String)
- Writes the given Text to the stream.
TextWriter.WriteLine (Text As String)
- Writes the given Text to the stream followed by a new line character LF Chr(10).
TextWriter.WriteList (List As List)
- Writes each item in the list as a single line.
Note that a value containing CRLF will be saved as two lines (which will return two items when
reading with ReadList).
All values will be converted to strings.
TextWriter.Close
- Closes the stream.
Example:
Dim Writer As TextWriter
Writer.Initialize(File.OpenOutput(File.DirDefaultExternal, "Text.txt", False))
Writer.WriteLine("This is the first line")
Writer.WriteLine("This is the second line")
Writer.Close

14 Basic language

14.10.5

275

Basic4Android Beginner's Guide

TextReader

There are two other useful functions for text files: TextWriter and TextReader:
TextReader.Initialize (InputStream As InputStream)
- Initializes a TextReader as an input stream.
Example:
Dim Reader TextReader
Reader.Initialize(File.InputOutput(File.DirRootExternal, "Test.txt"))

Reader could be 'dimed' in Sub Globals.

TextReader.Initialize2 (InputStream As InputStream, Encoding As String)
- Initializes a TextReader as an input stream.
- Encoding indicates the CodePage (also called CharacterSet), the text encoding.
Example:
Dim Reader

TextReader

Reader.Initialize(File.OpenInput(File.DirRootExternal, "Test.txt"),"ISO-8859-1")

Reader could be 'dimed' in Sub Globals.

See : Text encoding
TextReader.ReadAll As String
- Reads all of the remaining text and closes the stream.
Example:
txt = Reader.ReadAll

TextReader.ReadLine As String
- Reads the next line from the stream.
The new line characters are not returned.
Returns Null if there are no more characters to read.
Example:
Dim Reader As TextReader
Reader.Initialize(File.OpenInput(File.DirDefaultExternal, "Text.txt")
Dim line As String
line = Reader.ReadLine
Do While line <> Null
Log(line)
line = Reader.ReadLine
Loop
Reader.Close

TextReader.ReadList As List
- Reads the remaining text and returns a List object filled with the lines.
Closes the stream when done.
Example:
List1 = Reader.ReadList

14 Basic language

14.10.6

276

Basic4Android Beginner's Guide

Text encoding

Text encoding or character encoding consists of a code that pairs each character from a given
repertoire with something else. Other terms like character set (charset), and sometimes character
map or code page are used almost interchangeably (source Wikipedia).
The default character set in Android is Unicode UTF-8.
In Windows the most common character sets are ASCII and ANSI.
ASCII includes definitions for 128 characters, 33 are non-printing control characters (now
mostly obsolete) that affect how text and space is processed.
ANSI, Windows-1252 or CP-1252 is a character encoding of the Latin alphabet, used by
default in the legacy components of Microsoft Windows in English and some other Western
languages with 256 definitions (one byte). The first 128 characters are the same as in the
ASCII encoding.
Many files generated by Windows programs are encoded with the ANSI character-set in western
countries. For example: Excel csv files, Notepad files by default.
But with Notepad, files can be saved with UTF-8 encoding.
Android can use following character sets:
UTF-8
default character-set
UTF -16
UTF - 16 BE
UTF - LE
US-ASCII
ASCII character set
ISO-8859-1
almost equivalent to the ANSI character-set
Windows-1251
cyrillic characters
Windows-1252
latin alphabet
To read Windows files encoded with ANSI you should use the Windows-1252 character-set.
If you need to write files for use with Windows you should also use the Windows-1252 characterset.
Another difference between Windows and Android is the end of line character:
Android, only the LF (Line Feed) character Chr(10) is added at the end of a line.
Windows, two characters CR (Carriage Return Chr(13)) and LF Chr(10) are added at the
end of a line. If you need to write files for Windows you must add CR yourself.
The symbol for the end of line is :
Basic4Android
CRLF
Basic4PPC
CRLF

Chr(10)
Chr(13) & Chr(10)

To read or write files with a different encoding you must use the TextReader or TextWriter objects
with the Initialize2 methods. Even for reading csv files.

14 Basic language

277

Basic4Android Beginner's Guide

Tip for reading Excel csv files:

You can either:
On the desktop, load the csv file in a text editor like NotePad or Notepad++
Save the file with UTF-8 encoding
With Notepad++ use Encode in UTF-8 without BOM, see below.
Or

Read the whole file with TextReader.Initialize2 and "Windows-1252" encoding.

Save it back with TextWriter.Initialize with the standard Android encoding.
Read the file with LoadCSV or LoadCSV2 from the StringUtils library.

Dim txt As String

Dim tr As TextReader
tr.Initialize2(File.OpenInput(File.DirAssets, "TestCSV1_W.csv"), "Windows-1252")
txt = tr.ReadAll
tr.Close
Dim tw As TextWriter
tw.Initialize(File.OpenOutput(File.DirInternal, "TestCSV1_W.csv", False))
tw.Write(txt)
tw.Close
lstTest = StrUtil.LoadCSV2(File.DirInternal, "TestCSV1_W.csv", ";", lstHead)

When you save a file with NotePad three additional bytes are added .
These bytes are called BOM characters (Byte Order Mark).
In UTF-8 they are represented by this byte sequence : 0xEF,0xBB,0xBF.
A text editor or web browser interpreting the text as Windows-1252 will display the characters
.
To avoid this you can use Notepad++ instead of NotePad and use Encode in UTF-8 without BOM.

Another possibility to change a text from Windows-1252 to UTF-8 is to use the code below.
Dim var, result As String
var = "Gesti"
Dim arrByte() As Byte
arrByte = var.GetBytes("Windows-1252")
result = BytesToString(arrByte, 0, arrByte.Length, "UTF8")

14 Basic language

278

Basic4Android Beginner's Guide

14.11 Lists
Lists are similar to dynamic arrays, detailed descriptions of all functions are in chapter List.
Lists are often used and many examples can be found in code examples:
StringUtils
LoadCSV, SaveCSV
DBUtils module
InsertMaps, UpdateRecord, ExecuteMemoryTable, ExecuteSpinner,
ExecuteListView, ExecuteHtml, ExecuteJSON
Charts module
to hold different variables.
A list must be initialized before it can be used.
Initialize
Initializes an empty List.
Dim List1 As List
List1.Initialize
List1.AddAll(Array As Int(1, 2, 3, 4, 5))

Initialize2 (SomeArray)
Initializes a list with the given values. This method should be used to convert arrays to lists.
Note that if you pass a list to this method then both objects will share the same list, and if
you pass an array the list will be of a fixed size.
Meaning that you cannot later add or remove items.
Example 1:
Dim List1 As List
List1.Initialize2(Array As Int(1, 2, 3, 4, 5))

Example 2:
Dim List1 As List
Dim SomeArray(10) As String
' Fill the array
List1.Initialize2(SomeArray)

You can add and remove items from a list and it will change its size accordingly.
With either:
Add (item As Object)
Adds a value at the end of the list.
List1.Add(Value)

AddAll (Array As String("value1", "value2"))

Adds all elements of an array at the end of the list.
List1.AddAll(List2)
List1.AddAll(Array As Int(1, 2, 3, 4, 5))

AddAllAt (Index As Int, List As List)

Inserts all elements of an array in the list starting at the given position.
List1.AddAll(12, List2)
List1.AddAllAt(12, Array As Int(1, 2, 3, 4, 5))

InsertAt (Index As Int, Item As Object)

Inserts the specified element in the specified index.
As a result all items with index larger then the specified index are shifted.
List1.InsertAt(12, Value)

RemoveAt (Index As Int)

Removes the specified element at the given position from the list.
List1.RemoveAt(12)

14 Basic language

279

Basic4Android Beginner's Guide

A list can hold any type of object. However if a list is declared as a process global object it cannot
hold activity objects (like views).
Basic4android automatically converts regular arrays to lists. So when a List parameter is expected
you can pass an array instead.
Get the size of a List :
List1.Size
Use the Get method to get an item from the list with :
Get(Index As Int)
number = List1.Get(i)

You can use a For loop to iterate over all the values:
For i = 0 To List1.Size - 1
Dim number As Int
number = List1.Get(i)
...
Next

Lists can be saved and loaded from files with:

File.WriteList(Dir As String, FileName As String, List As List)
File.WriteList(File.DirRootExternal, "Test.txt", List1)

File.ReadList (Dir As String, FileName As String)

List1 = File.ReadList(File.DirRootExternal, "Test.txt")

A sinngle item can be changed with :

List1. Set(Index As Int, Item As Object)
List1.Set(12, Value)

A List can be sorted (the items must all be numbers or strings) with :
Sort(Ascending As Boolean)
List1.Sort(True)
sort ascending
List1.Sort(False)
sort descending
SortCaseInsensitive(Ascending As Boolean)
Clear a List with :
List1.Clear

14 Basic language

280

Basic4Android Beginner's Guide

14.12 Maps
A Map is a collection that holds pairs of keys and values, detailed descriptions of all functions are
in chapter Map.
The keys are unique. Which means that if you add a key/value pair (entry) and the collection
already holds an entry with the same key, the previous entry will be removed from the map.
The key should be a string or a number. The value can be any type of object.
Similar to a list, a map can hold any object, however if it is a process global variable then it cannot
hold activity objects (like views).
Maps are very useful for storing applications settings.
Maps are used in these example codes:
DBUtils module
used for database entries, keys are the column names and values the values.
StateManager module
used for settings
A list must be initialized before it can be used.
Initialize
Initializes an empty Map.
Dim Map1 As Map
Map1.Initialize

Add a new entry :

Put(Key As Object, Value As Object)
Map1.Put("Language", "English")

Get an entry :
Get(Key As Object)
Language = Map1.Get("Language")

Get a key or a value at a given index :

Returns the value of the item at the given index.
GetKeyAt and GetValueAt should be used to iterate over all the items.
These methods are optimized for iterating over the items in ascending order.
GetKeyAt(Index As Int)
Key = Map1.GetKeyAt(12)

Get a value at a given index :

GetValueAt(Index As Int)
Value = Map1.GetValueAt(12)

Check if a Map contains en entry, tests whether there is an entry with the given key :
ContainsKey(Key As Object)
If Map1.ContainsKey("Language") Then
Msgbox("There is already an entry with this key !", "ATTENTION")
Return
End If

14 Basic language

281

Basic4Android Beginner's Guide

Remove an entry :
Remove(Key As Object)
Map1.Remove("Language")

Clear an entry, clears all items from the map :

Clear
Map1.Clear

Maps can be saved and loaded with :

File.WriteMap(Dir As String, FileName As String, Map As Map)
File.WriteMap(File.DirInternal, "settings.txt", mapSettings)

ReadMap(Dir As String, FileName As String)

Reads the file and parses each line as a key-value pair (of strings).
Note that the order of items in the map may not be the same as the order in the file.
mapSettings = File.ReadMap(File.DirInternal, "settings.txt")

File. ReadMap2(Dir As String, FileName As String, Map As Map)

Similar to ReadMap. ReadMap2 adds the items to the given Map.
By using ReadMap2 with a populated map you can force the items order as needed.
mapSettings = File.ReadMap2(File.DirInternal, "settings1.txt", mapSettings)

15 Graphics / Drawing

282

Basic4Android Beginner's Guide

15 Graphics / Drawing
15.1 Overview
To draw graphics we need to use a Canvas object.
Explanations from the help file.
A Canvas is an object that draws on other views or (mutable) bitmaps.
When the canvas is initialized and set to draw on a view, a new mutable bitmap is created for that
view background, the current view's background is copied to the new bitmap and the canvas is set
to draw on the new bitmap.
The canvas drawings are not immediately updated on the screen. You should call the target view
Invalidate method to make it refresh the view.
This is useful as it allows you to make several drawings and only then refresh the display.
The canvas can be temporary limited to a specific region (and thus only affect this region). This is
done by calling ClipPath. Removing the clipping is done by calling RemoveClip.
You can get the bitmap that the canvas draws on with the Bitmap property.
This is an 'Activity Object', it cannot be declared under Sub Process_Globals.
It is possible to draw onto the following views:
Activity
ImageView
Panel
Bitmap (mutable)
In the following functions you will find a number of common parameters.
Bitmap1 as Bitmap
an Android bitmap
x, y. x1, y1, x2, y2 As Float
are coordinates, Float variables.
Color as Int
are color variables. Int variables
SrcRect, DestRact, Rect1 As Rect are rectangles, Rect objects
Filled As Boolean
flag if the surface is filled (True) or not (False)
The most common drawing functions are:
DrawBitmap (Bitmap1 As Bitmap, SrcRect As Rect, DestRect As Rect)
Draws the given bitmap or only a part of it..
SrcRect = source rectangle, can be only a part of the original bitmap.
DestRect = destination rectangle, can be any size.
Do draw with the same size both rectangles must have same width and same height.
If DestRect is different than SrcRect the destination drawing is stretched or shrinked
depending on the size ratios between the two rectangles.

Draw BitmapRotated (Bitmap1 As Bitmap, SrcRect As Rect, DestRect As Rect, Degrees

As Float)
Same function as DrawBitmap, but with a rotation of the given Degrees angle around the
centre of the bitmap.

DrawCircle (x As Float, y As Float, Radius As Float, Color as Int, Filled As Boolean,

StrokeWidth As Float)
Draws a circle.
x an y are the centre coordinates of the circle and Radius the circles radius.

15 Graphics / Drawing

283

Basic4Android Beginner's Guide

DrawColor (Color As Int)

Fills the whole view with the given color.
The color can be Colors.Transparent making the whole view transparent.

DrawLine (x1 As Float, y1 As Float, x2 As Float, y2 As Float, Color as Int, StrokeWidth

As Float)
Draws a straight line.

DrawRect (Rect1 As Rect, Color As Int, Filled As Boolean, StrokeWidth as Float)

Draws a rectangle with given size, color, filled or not and line width.

DrawRectRotated (Rect1 As Rect, Color As Int, Filled As Boolean, StrokeWidth As Float,

Degrees As Float)
Same as DrawRect but rotated by the given angle

DrawText (Text As String, x As Float, y As Float, Typeface1 As TypeFace, TestSize As

Float, Color As Int Align1 As Align)

DrawTextRotated (Text As String, x As Float, y As Float, Typeface1 As TypeFace,

TestSize As Float, Color As Int Align1 As Align, Degrees As Float)

15 Graphics / Drawing

284

Basic4Android Beginner's Guide

15.2 Drawing test programs

15.2.1 First steps
The project is in : SourceCode\Graphics\GraphicsFirstSteps.b4a
To draw something we need a Canvas object which is simply a drawing tool.
The Canvas draws onto a Bitmap. This Bitmap can be the background bitmap of views.
The most common views to draw on are : Activity, Panel, ImageView or a Bitmap.
The Canvas must be 'connected' to a bitmap or a view background image in the Initialize method.
Initialize(Target View)
Initialize2(Target Bitmap)
If we want to draw on different views at the same time we need one Canvas for each view.
In the example program we'll use several drawing functions and draw onto the Activity and onto a
Panel pnlGraph defined in the 'main' layout file. Here we need two canvases.

15 Graphics / Drawing
15.2.1.1

285

Basic4Android Beginner's Guide

Start Dim and Initialisation

First we must dim the different views and objects :

We have :
the Panel pnlGraph
the Canvas cvsActivity for the Activity
the Canvas cvsPanel for the Panel
Sub Globals
Dim pnlGraph As Panel
Dim cvsActivity, cvsGraph As Canvas
End Sub

Then we must load the layout file and initialize the two Canvases:
Sub Activity_Create(FirstTime As Boolean)
' load the layout file
Activity.LoadLayout("main")
' initialize the Canvas for the activity
cvsActivity.Initialize(Activity)
' initialize the Canvas for the pnlGraph panel
cvsGraph.Initialize(pnlGraph)
End Sub

15.2.1.2

Draw a line

Then in Activity_Resume we draw a horizonzal line onto the Activity :

The function is :
DrawLine (x1 As Float, y1 As Float, x2 As Float, y2 As Float, Color as Int, StrokeWidth As Float)
Where :
x1, y1 are the coordinates of the start point in pixels
x2, y2 are the coordinates of the end point in pixels
Color is the line color
StrokeWidth the line thickness in pixels
And the code :
' draw a horizontal line onto the Activity
cvsActivity.DrawLine(20dip, 20dip, 160dip, 20dip, Colors.Red, 3dip

Then we draw a horizonzal line onto pnlGraph with the same coordinates :
The coordinates are relative to the upper left corner of the view we draw on, the Panel pnlGraph in
this case.
' draw a horizontal line onto pnlGraph
cvsGraph.DrawLine(20dip, 20dip, 160dip, 20dip, Colors.Red, 3dip)

15 Graphics / Drawing
15.2.1.3

286

Basic4Android Beginner's Guide

Draw a rectangle

Then we draw an empty rectangle onto the Activity :

The function is :
DrawRect (Rect1 As Rect, Color As Int, Filled As Boolean, StrokeWidth as Float)
Where :
Rect1 is a rectangle object
Color is the border or rectangle color
Filled: False = only the border is drawn True = the rectangle is filled
StrokeWidth is the line thickness of the border, not relevant when Filled = True
To draw a rectangle we need a Rect object.
We :
Define it with the name rect1.
Initialize it with the coordinates of the upper left corner and the coordinates of the lower
right corner.
Draw it
' draw an empty rectangle onto the Activity
Dim rect1 As Rect
rect1.Initialize(20dip, 40dip, 150dip, 100dip)
cvsActivity.DrawRect(rect1, Colors.Blue, False, 3dip)

Then we draw a filled rectangle onto pnlGraph with the same coordinates :
We don't need to define nor initialize a new rectangle because the coordinates are the same so we
use the same Rect object.
' draw a filled rectangle onto pnlGraph
cvsGraph.DrawRect(rect1, Colors.Blue, True, 3dip)

15 Graphics / Drawing
15.2.1.4

287

Basic4Android Beginner's Guide

Draw a circle

Then we draw an empty circle onto the Activity :

The function is :
DrawCircle (x As Float, y As Float, Radius As Float, Color as Int, Filled As Boolean, StrokeWidth
As Float)
Where :
x, y are the coordinates of the center in pixels.
Radius is the radius in pixels.
Color is the border or circle color
Filled: False = only the border is drawn True = the circle is filled
StrokeWidth is the line thickness of the border, not relevant when Filled = True
And the code:
' draw an empty circle onto the Activity
cvsActivity.DrawCircle(220dip, 70dip, 30dip, Colors.Green, False, 3dip)

Then we draw a filled circle with a border with a different color on the panel.
There is no direct function to draw a filled circle with a border with a different colors.
So we first draw the filled circle and then the circle border in two steps.
Instead of using fixed values like 220dip we can also use variables like in the code below.
When a same value is used several times it's better to use variables because if you need to change
the value you change it only once the value of the variable all the rest is changed automatically by
the variable.
' draw a filled circle with a boarder onto pnlGraph
Dim centerX, centerY, radius As Float
centerX = 220dip
centerY = 70dip
radius = 30dip
cvsGraph.DrawCircle(centerX, centerY, radius, Colors.Green, True, 3dip)
cvsGraph.DrawCircle(centerX, centerY, radius, Colors.Red, False, 3dip)

15 Graphics / Drawing
15.2.1.5

288

Basic4Android Beginner's Guide

Draw a text

Then we draw a text onto the Activity.

The function is :
DrawText (Text As String, x As Float, y As Float, Typeface1 As TypeFace, TestSize As Float,
Color As Int Align1 As Align)
Where:
Text is the text to draw
x, y are the coordinates of the reference point (depending on the Align1 value) in pixels.
The reference point is on the texts baseline.
TypeFace1 is the text style
TextSize is the text size in a typogrphic unit called 'point'.
The text size is independant of the screen density !
Don't use dip values !
Color is the text color
Align1 is the alignement of the text according to the refence point.
Possible values : "LEFT", "CENTER", "RIGHT".
And the code :
' draw a text onto the Activity
cvsActivity.DrawText("Test text", 20dip, 150dip, Typeface.DEFAULT, 20, _
Colors.Yellow, "LEFT")

Then we draw a rotated text onto pnlGraph.

And we draw a cross on the reference point to show where it is and how the align does work.
The function is DrawTextRotated, it's the same as DrawText but with an additional parameter
Degrees, the rotation angle.
Instead of using fiexd dip values in the routine we define three variables:
refX and refY
the coordinates of the reference point
hl
the half of the cross line length
Dim refX, refY, hl As Float
refX = 150dip
refY = 180dip
hl = 5dip
' draw a rotated text onto pnlGraph
cvsGraph.DrawTextRotated("Test text", refX, refY, Typeface.DEFAULT, _
20, Colors.Black, "RIGHT", 45)
' draw a cross on the reference point
cvsGraph.DrawLine(refX - hl, refY, refX + hl, refY, Colors.Red, 1dip)
cvsGraph.DrawLine(refX, refY - hl, refX, refY + hl, Colors.Red, 1dip)

15 Graphics / Drawing

289

Basic4Android Beginner's Guide

15.2.2 Drawing rotating bitmaps / RotatingNeedle

The project is in : SourceCode\Graphics\RotatingNeedle\RotatingNeedle.b4a
In the first test program we will demonstrate the DrawBitmapRotated function.
The program has two modes:
A rotating needle with a static compass
A rotating compass with a static needle

We have in the layout:

3 buttons

o
starts rotating

o
step by step moving

o
we can let turn either the needle
or the compass.

2 bitmap files
o compass.png
o needle.png

In the DrawBitmapRotated function the bitmap rotates around the bitmaps centre.
If we had a needle image like this one, we would need to do some calculations to make sure that
it turns around the needle centre.

To avoid these calculations, the needle bitmap looks like this one. We added the lower part so
that the needle centre is at the bitmap's centre.
The blue pixels are, in reality, transparent pixels.

15 Graphics / Drawing

290

Basic4Android Beginner's Guide

Let us have a look at the code.

Sub Process_Globals
Dim AngleStep As Float
Dim Angle As Float
Dim Mode As Boolean
Dim Timer1 As Timer
End Sub

: AngleStep = 6
: Angle = -AngleStep
: Mode = True

Here we define three global variables with their values.

AngleStep step in degrees for the angle variations from one step to the next.
Angle
current angle of the needle
Mode
program mode
True = needle turns
False = compass turns
Sub Globals
Dim btnGoStop, btnStep, btnMode As Button
Dim csvCompass, csvNeedle As Canvas
Dim bmpCompass, bmpNeedle As Bitmap
Dim imvCompass, imvNeedle As ImageView
Dim RectCompass, SRectNeedle, DRectNeedle As Rect
End Sub

Then we define the different objects used by the program.

The three buttons from the layout file.
Two Canvas views, one for the compass and one for the needle.
Two Bitmaps, one for the compass and one for the needle.
Two ImageViews, one for the compass and one for the needle.
Three rectangles, one for the compass, two for the needle source and destination.
One Timer, it is used to move dynamically the needle or the compass.
In the Activity_Create routine we:
Sub Activity_Create(FirstTime As Boolean)
Dim x, y As Float
Activity.LoadLayout("rotatingneedle")

Define two variables used for calculations

Load the layout file to the Activity

bmpCompass.Initialize(File.DirAssets,"compass.png")
bmpNeedle.Initialize(File.DirAssets,"needle.png")

Initialize the compass bitmap

Initialize the needle bitmap

15 Graphics / Drawing

291

Basic4Android Beginner's Guide

imvCompass.Initialize("")
imvCompass.Bitmap = bmpCompass
imvNeedle.Initialize("")
imvNeedle.Color=Colors.Transparent

Initialize the compass ImageView.

Set the compass bitmap to the compass ImageView bitmap.
Initialize the needle ImageView.
Set the needle ImageView color to transparent.

x = (100%x - bmpCompass.Width) / 2
y = (100%y - bmpCompass.Height) / 2
Activity.AddView(imvCompass, x, y, bmpCompass.Width, bmpCompass.Height)
Activity.AddView(imvNeedle, x, y, bmpCompass.Width, bmpCompass.Height)
csvCompass.Initialize(imvCompass)
RectCompass.Initialize(0, 0, bmpCompass.Width, bmpCompass.Height)

Calculate the Left and Top coordinates of the compass ImageView.

Add the compass ImageView to the Activity.
Add the needle ImageView to the Activity
with the same dimensions as the compass ImageView.
Initialize the compass Canvas and connect it to the compass ImageView.
Initialize the compass rectangle.

csvNeedle.Initialize(imvNeedle)
x = (bmpCompass.Width - bmpNeedle.Width)/2
y = (bmpCompass.Height - bmpNeedle.Height)/2
SRectNeedle.Initialize(0, 0, bmpNeedle.Width, bmpNeedle.Height)
DRectNeedle.Initialize(x, y, x + bmpNeedle.Width, y + bmpNeedle.Height)

Initialize the needle Canvas and connect it to the needle ImageView.

Calculate the Left and Top coordinates of the needle ImageView.
Initialize the needle source and destination rectangles.

Timer1.Initialize("Timer1",200)
Timer1_Tick
End Sub

Initialize the timer, set the Interval to 200 ms.

Call the Timer1_Tick routine to draw the needle

15 Graphics / Drawing

292

Basic4Android Beginner's Guide

In the Timer1_Tick routine we:

Sub Timer1_Tick
Dim Angle1 As Float
Angle1 = Angle
Angle = (Angle+AngleStep) Mod 360
If Mode = True Then
csvNeedle.DrawRectRotated(DRectNeedle,Colors.Transparent,True,1,Angle1)
csvNeedle.DrawBitmapRotated(bmpNeedle,SRectNeedle,DRectNeedle,Angle)
imvNeedle.Invalidate2(RectCompass)
Else
csvCompass.DrawBitmapRotated(bmpCompass,RectCompass,RectCompass,-Angle)
imvCompass.Invalidate2(RectCompass)
End If
End Sub

Define a local variable representing the current Angle

Calculate the new Angle using the Mod operator
If Mode = True, rotating needle mode we:
o Draw a rotated transparent rectangle to erase the current needle.
o Draw the needle with the new angle.
o Invalidate the needle ImageView to update it.
If Mode = False, rotating compass mode we:
o Draw the compass with the new angle, in our case the source and destination
rectangle are the same.
o Invalidate the compass ImageView to update it.

In the btnStep_Click routine we:

Sub btnStep_Click
Timer1_Tick
End Sub

Call the Timer1_Tick routine to draw a new step.

15 Graphics / Drawing

293

Basic4Android Beginner's Guide

In the btnGoStop_Click routine we:

Sub btnGoStop_Click
If Timer1.Enabled = True Then
Timer1.Enabled = False
btnGoStop.Text = "Go"
btnStep.Visible = True
Else
Timer1.Enabled = True
btnGoStop.TExt = "Stop"
btnStep.Visible = False
End If
End Sub

If Timer1 = True, the timer is running.

o We set the Timer1.Enabled property to False to stop it.
o Set the btnGoStop button text to "Go".
o Set the btnStep button to visible.
If Timer1 = False, the timer is stopped
o We set the Timer1.Enabled property to True to let it run.
o Set the btnGoStop button text to "Stop".
o Hide the btnStep button.

In the btnMode_Click routine we:

Sub btnMode_Click
Mode = Not(Mode)
If Mode = True Then
btnMode.Text = "Needle turns"
csvNeedle.DrawRect(DRectNeedle, Colors.Transparent, True, 1)
csvNeedle.DrawBitmapRotated(bmpNeedle,SRectNeedle,DRectNeedle,Angle)
csvCompass.DrawBitmap(bmpCompass, RectCompass, RectCompass)
Else
btnMode.Text = "Compass turns"
csvNeedle.DrawRectRotated(DRectNeedle,Colors.Transparent,True,1,Angle)
csvNeedle.DrawBitmap(bmpNeedle, SRectNeedle, DRectNeedle)
End If
Angle = Angle - AngleStep
Timer1_Tick
End Sub

We change the Mode variable from True to False or from False to True with the Not
keyword.
If Mode = True, rotating needle, we:
o Set the button text to "Needle turns".
o Draw a transparent rectangle to erase the current needle.
o Draw the needle at the new position.
o Draw the default compass.
If Mode = False, rotating compass, we:
o Set the button text to "Compass turns".
o Erase the current needle
o Draw the new needle.

15 Graphics / Drawing

294

Basic4Android Beginner's Guide

15.2.3 Simple draw functions

The project is in : SourceCode\Graphics\SimpleDrawFunctions\SimpleDrawFunctions.b4a
In the second drawing program, SimpleDrawFunctions, we use the other common drawing
functions.
The program has no other purpose than show what can be done with drawings.
The program has three Panels which we use as layers and three ToggleButtons buttons allowing us
to show or hide each layer.
Layer(0) has a grey background and the two other layers have a transparent background.

You can play with the buttons to observe the different combinations of visible and hidden layers.

15 Graphics / Drawing

295

Basic4Android Beginner's Guide

In this screenshot we solely see the background image of

the activity.
We use the ToggleButtons to either show or hide the
different layers.

Here we show layer(0).

The panel has a dark gray background with:
a blue circle.
a transparent circle, the activity's background is
inside this circle.
a blue, semi-transparent rectangle
a transparent rectangle, the activity's background
is inside this circle.
Touching the screen and moving the finger moves the
blue and transparent circles on layer(0).

15 Graphics / Drawing

296

Basic4Android Beginner's Guide

Here we show layer(1).

The panel has a transparent background with:
a green circle.
a small copy of the activity's background image.
a green, rotated semi-transparent rectangle.
We see that the rectangle covers the activity's
background because layer 1 is in front of layer 0.

Here we show layer(2).

The panel has a transparent background with:
4 lines on top.
3 horizontal texts with the three different
alignments.
3 rotated texts with the three different alignments.
a point for each text showing the position of the
reference point.

You can play with the buttons to show the different combinations of visible and hidden layers.

15 Graphics / Drawing

297

Basic4Android Beginner's Guide

Touching the screen with the finger and moving it,

moves the blue and transparent circles.

On each move, the backgound image of the activity

appears.

15 Graphics / Drawing

298

Basic4Android Beginner's Guide

Analysis of the code:

There is no layout file, all views are added by code.
In the Sub Globals routine we declare the different views and variables:
Sub Globals
Dim pnlLayer(3) As Panel
Dim cvsLayer(3) As Canvas
Dim btnLayer(3) As ToggleButton
Dim rect1 As Rect
Dim bmpBackground As Bitmap
Dim bdwBackground As BitmapDrawable
Dim xc, yc, x1, y1, x2, y2, r1, r2, h, w As Float
End Sub

We have:
3 Panels
3 Canvases
3 ToggleButtons
1 Rect, rectangle used to draw rectangles
1 Bitmap, holding the activity's background image
1 BitmapDrawable, holds the activity's background
different variables used for the drawing.
Note that we use arrays of views for the three panels, canvases and togglebuttons.
Dim pnlLayer(3) As Panel instead of Dim pnlLayer0, pnlLayer1, pnlLayer2 As Panel.

In the Sub Activity_Create routine we initialize the different views and add them to the activity:
Sub Activity_Create(FirstTime As Boolean)
Dim i As Int
If FirstTime Then
bmpBackground.Initialize(File.DirAssets,"Rose2.jpg")
bdwBackground.Initialize(bmpBackground)
Activity.Background = bdwBackground

We:

initialize the views only if FirstTime = True.

load the Rose2.jpg image file into the bitmap.
initialize the background image of the activity.
set the activity's background image
x1 = 2%x
w = 30%x
y1 = 100%y - 55dip
h = 50dip

15 Graphics / Drawing

299

Basic4Android Beginner's Guide

initialize some variables.

For i = 0 To 2
pnlLayer(i).Initialize("pnlLayer" & i)
Activity.AddView(pnlLayer(i), 0, 0, 100%x, 85%y)
cvsLayer(i).Initialize(pnlLayer(i))
pnlLayer(i).Tag = i

btnLayer(i).Initialize("btnLayer")
x2 = x1 + i * 33%x
Activity.AddView(btnLayer(i), x2, y1, w, h)
btnLayer(i).TextOn = "Layer" & i & " ON"
btnLayer(i).TextOff = "Layer" & i & " OFF"
btnLayer(i).Checked = True
btnLayer(i).Tag = i
Next
End If
End Sub

In a loop we:
initialize the layer Panels.
we define an individual EventName for each of the three Panels
we use only an event on layout(0).
add the panels to the activity.
initialize the layer Canvases.
set the Panels Tag property to the index.

initialize the layer ToggleButtons.

we define a single EventName for all three ToggleButtons.
we manage the showing and hiding of the Panels in one single event routine.
calculate the left coordinate for each ToggleButton.
set the texts for the two states.
set the Checked property to True.
set the Tag property to the index.

In the Sub Activity_Resume routine we call the Drawing routine.

Sub Activity_Resume
Drawing
End Sub

15 Graphics / Drawing

300

Basic4Android Beginner's Guide

In the Sub Drawing routine we:

Sub Drawing
cvsLayer(0).DrawColor(Colors.DarkGray)
cvsLayer(1).DrawColor(Colors.Transparent)
cvsLayer(2).DrawColor(Colors.Transparent)

draw the layout(0) background dark gray.

draw the layout(1) and layout(2) background transparent.

x1 = 10dip
y1 = 10dip
x2 = 150dip
y2 = 20dip
cvsLayer(2).DrawLine(x1,
y1 = 30dip
y2 = 30dip
cvsLayer(2).DrawLine(x1,
y1 = 35dip
y2 = 45dip
cvsLayer(2).DrawLine(x1,
y1 = 45dip
y2 = 55dip
cvsLayer(2).DrawLine(x1,

y1, x2, y2, Colors.Red, 0)

y1, x2, y2, Colors.Green, 0.99dip)

y1, x2, y2, Colors.Yellow, 0.99dip)

y1, x2, y2, Colors.Blue, 5dip)

draw four lines onto layer(2)

cvsLayer(2).DrawLine(x1, y1, x2, y2, Colors.Red, 0)

the last StrokeWidth parameter is '0', this means hairline mode, the width is one pixel.
cvsLayer(2).DrawLine(x1, y1, x2, y2, Colors.Green, 0.99dip)

here we use 0.99dip instead of 1dip because in some cases no line or only parts of it are
drawn. This is a known bug in Android with a StrokeWidth of '1'.
xc = 90dip
yc = 130dip
r1 = 70dip
cvsLayer(1).DrawCircle(xc, yc, r1, Colors.Green, False, 2dip)
r1 = 60dip
cvsLayer(0).DrawCircle(xc, yc, r1, Colors.Blue, True, 3dip)
r2 = 50dip
cvsLayer(0).DrawCircle(xc, yc, r2, Colors.Transparent, True, 1dip)

draw a green circle line on layer(1).

draw a filled blue circle on layer(0).
draw a filled transparent circle on layer(0).

15 Graphics / Drawing

301

Basic4Android Beginner's Guide

rect1.Initialize(10dip, 210dip, 300dip, 350dip)

cvsLayer(1).DrawRect(rect1, Colors.Red, False, 2dip)
rect1.Initialize(40dip, 230dip, 270dip, 320dip)
cvsLayer(0).DrawRect(rect1, Colors.ARGB(128, 0, 0, 255), True, 2dip)
cvsLayer(1).DrawRectRotated(rect1, Colors.ARGB(128, 0, 255, 0),True, 2dip,10)
rect1.Initialize(80dip, 240dip, 230dip, 360dip)
cvsLayer(0).DrawRect(rect1, Colors.Transparent, True, 2dip)

define the coordinates of a rectangle.

draw a red rectangle on layer(1).
define the coordinates of a rectangle.
draw a semi-transparent blue rectangle on layer(0).
draw a semi-transparent green rotated rectangle on layer(1).
define the coordinates of a rectangle.
draw a transparent rectangle on layer(0).
define the coordinates of a rectangle.
draw a red rectangle on layer(1).

rect1.Initialize(200dip, 90dip, 280dip, 195dip)

cvsLayer(1).DrawBitmap(bmpBackground,Null,rect1)

define the coordinates of a rectangle.

draw the activity's background image in a smaller rectangle on layer(1)

x1 = 200dip
y1 = 30dip
cvsLayer(2).DrawText("Rose", x1, y1, Typeface.DEFAULT,16,Colors.Red,"LEFT")
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)
y1 = 50dip
cvsLayer(2).DrawText("Rose", x1, y1, Typeface.DEFAULT,16,Colors.Red,"CENTER")
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)
y1 = 70dip
cvsLayer(2).DrawText("Rose", x1, y1, Typeface.DEFAULT,16,Colors.Red,"RIGHT")
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)

draw the text "Rose" with the three different possible alignments.
draw the reference point for each text.

x1 = 260dip
y1 = 30dip
cvsLayer(2).DrawTextRotated("Rose", x1,y1,Typeface.DEFAULT,16,Colors.Red,"LEFT",-10)
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)
y1 = 50dip
cvsLayer(2).DrawTextRotated("Rose", x1,y1,Typeface.DEFAULT,16,Colors.Red,"CENTER",-10)
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)
y1 = 70dip
cvsLayer(2).DrawTextRotated("Rose", x1,y1,Typeface.DEFAULT,16,Colors.Red,"RIGHT",-10)
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)
End Sub

same as above but rotated texts.

18 Collections

302

Basic4Android Beginner's Guide

Looking closer on the displayed texts we see the reference point for each text.
cvsLayer(2).DrawText("Rose", x1, y1, Typeface.DEFAULT,16,Colors.Red,"LEFT")
cvsLayer(2).DrawPoint(x1, y1, Colors.Red)

These are the x1 and y1 coordinates used to display the texts.

LEFT

alignment.

CENTER alignment.

RIGHT

alignment.

In the Sub btnLayer_Checked routine we:

Sub btnLayer_CheckedChange(Checked As Boolean)
Dim Send As Button
Send = Sender
pnlLayer(Send.Tag).Visible = Not(pnlLayer(Send.Tag).Visible)
End Sub

dim a local Button to get the view that raised the event.
set Send to the Sender view
change the Visible property from True to False or from False to True.

In the Sub pnlLayer0_Checked routine we:

Sub pnlLayer0_Touch (Action As Int, X As Float, Y As Float)
cvsLayer(0).DrawCircle(xc, yc, r1, Colors.DarkGray, True, 3dip)
xc = X
yc = Y
cvsLayer(0).DrawCircle(xc, yc, r1, Colors.Blue, True, 3dip)
cvsLayer(0).DrawCircle(xc, yc, r2, Colors.Transparent, True, 1dip)
pnlLayer(0).Invalidate
End Sub

draw a dark gray circle to erase the previous blue and transparent circle.
set and yc to the new coordinates of the circle centers.
draw a blue and transparent circle on layer(1).
invalidate pnlLayout(1) to force the update of the drawing.

16 VB6 versus B4A

303

Basic4Android Beginner's Guide

16 VB6 versus B4A

Written by : nfordbscndrd
http://www.basic4ppc.com/android/forum/threads/converting-vb6-to-b4a.9347/#content
VB6
B4A
===
===
controls
Views (button, edittext, label, etc.)
In the VB6 code window, the top left drop-down list contains all
the controls you have placed in the current form and the right list
contains all the events for each control. The equivalent in B4A can
be found by clicking on Designer - Tools - Generate Members. Once
you have created Subs in the program coding window, the tab "Modules"
on the right side will list each of the Subs.
In B4A, you start by typing "Sub [viewName]" followed by a space and
follow the prompts, pressing Enter after each selection until B4A
ends with "EventName" highlighted. This is where you would type in
the name of the Sub.
Dim/ReDim:
--------Dim Array(n)
Dim Array(n+1)
While "n" is the last index number in VB6, it indicates the number
of array elements when used in B4A. For example, to Dim an array
with 0-32 elements in VB6, you would say Dim A(32), while to convert
this to B4A, you need to change it to Dim A(33), yet index #33 is
never used (doing so would cause an out-of-range error).
ReDim Array()

Dim Array(n+1) -- to clear an array, just Dim it again.

[Dim a Int: Dim b as Boolean]

If Not b Then...
If Not(b) Then...
If b Then...
same
If b = True Then
same
If a Then...
If a > 0 Then...
B4A does not treat any non-zero value as True like VB6.
a = a + b
If b = True Then a = a - 1
Boolean's value cannot be used in a math function in B4A.
Global Const x=1

B4A does not have a Global Const function.

In Sub Globals, you can say
Dim x as Int: x = 1
but x is not a constant (its value can be changed).

Loops, If-Then, Select Case:

--------------------------Do [Until/While]
same
Loop [Until/While] Loop [Until/While not allowed.]
For - Next
same
For i... - Next i
The loop variable (i) is not allowed with Next.
Exit Do/For
Exit
If - Then - Else
same, except VB's ElseIf is "Else If" in B4A; ditto EndIf
--For i = 1 to 6
If i = 4 Then
...code...
End If
Next

Continue [Skips to Next in For-Next loop]

For i = 1 to 6
If i = 4 Then Continue
...code...
...
Next

Select Case [expr]

Select [value]

16 VB6 versus B4A

Colors:
-----L1.BackColor =
vbRed
L1.ForeColor =
vbBlack
Calling a sub:
------------SubName x, y

304

Basic4Android Beginner's Guide

L1.Color = Colors.Red
L1.TextColor = Colors.Black

SubName(x, y)

Sub SubName()

Sub SubName() As Int/String/etc.

Function FName()
As [var.type]

Sub FName() As [var.type]

In B4A, any Sub can be used like a Function by adding a
variable type such as
Sub CheckX(x As Int) As Boolean
...optional code...
If x = [desired value] Then Return True
...optional code...
End Sub
If no Return is given, then zero/False/"" is returned.
The calling code does not have to reference the returned
value, so that while "If CheckX(x) = True..." is valid,
so is just "CheckX(x)"
Return
Return [value]

Exit Sub
Exit Function
General:
------DoEvents

same, except that Erel says:

"Calling DoEvents in a loop consumes a lot of resources and
it doesn't allow the system to process all waiting messages
properly." This was in response to my pointing out that

while
in a Do Loop with DoEvents in it, WebView could not be
loaded
or if loaded, would not process a hyperlink click. And
Agraham
says: "Looping is bad practice on mobile devices. The CPU
will
be constantly executing code and using battery power as the
code will never get back to the OS idle loop where the
hardware
power saving measures are invoked."
Format()

NumberFormat & NumberFormat2 [see documentation]

InputBox($)

InputList(Items as List, Title, CheckedItem as Int) as Int

Shows list of choices with radio buttons. Returns index.
CheckedItem is the default.
InputMultiList(Items as List, Title) As List
Usere can select multiple items via checkboxes.
Returns list with the indexes of boxes checked.

MsgBox "text"
i=MsgBox()
Int

MsgBox("text", "title")
MsgBox2(Message, Title, Positive, Cancel, Negative, Icon) as

--Rnd is < 1

Displays three buttons with text to display for buttons

(Positive, Cancel, Negative)
Icon is displayed near the title and is specified like:
LoadBitmap(File.DirAssets, "[filename].gif")
ToastMessageShow(text, b) [where b=True for long duration]
Rnd(min, max) is integer >= min to < max

16 VB6 versus B4A

305

Basic4Android Beginner's Guide

Round(n)

same, or Round2(n, x) where x=number of decimal places

i = Val(string)

If IsNumber(string) Then i = string Else i = 0 -An attempt to use i=string "throws an exception" if the

string is
not numbers.
control.SetFocus

view.RequestFocus

n / 0 : error

n / 0 = 2147483647 -- B4A does not "throw an exception" for

division by 0, but it does return 2147483647 no matter
what the value of "n" is.

x = Shell("...")

See "Intent". This is not a complete replacement, but allows

code such as the following from the B4A forum (by Erel):
Dim pi As PhoneIntents
StartActivity
(pi.OpenBrowser("file:///sdcard/yourfile.html"))
t = Timer
1-70

t = DateTime.Now ' Ticks are number of milliseconds since 1-

TabIndex:
-------In VB6, TabIndex can be set to control the order in which controls get focus
when Tab is pressed. According to Erel, in B4A:
"Android handles the sequence according to their position. You can set
EditText.ForceDone = True in all your EditTexts. Then catch the
EditText_EnterPressed event and explicitly set the focus to the next
view (with EditText.RequestFocus)."
Setting Label Transparency:
-------------------------Properties - Back Style
Constants:
--------""
vbCr
vbCrLf

Designer - Drawable - Alpha

Quote = Chr$(34)
CRLF = Chr$(13)
none

String "Members":
---------------VB6 uses a character position pointer starting with 1.
B4A uses a character Index pointer starting with 0.
VB6
Mid$("abcde",
Mid$("abcde",
Mid$("abcde",
Mid$("abcde",
Mid$("abcde",
VB6
===
Mid$(text,
Mid$(text,
Mid$(text,
position]
Mid$(text,

1,
2,
3,
4,
5,

1)
1)
1)
1)
1)

=
=
=
=
=

"a"
"b"
"c"
"d"
"e"

=
=
=
=
=

letter
letter
letter
letter
letter

n, 1)
n)
n, x) [x=length wanted]
n, x) = text2

B4A
array
array
array
array
array

index
index
index
index
index

0 -- "a" = "abcde".CharAt(0)
1
2
3
4

B4A
===
text.CharAt(n-1)
text.SubString(n-1)
text.SubString2(n-1, n+x-1) [n+x-1=end
text = text.SubString2(0, n-2) & _
text2.SubString2(0, x-1) & _
text.SubString(n-1 + z) where...
z = Min(x, text2.length)

16 VB6 versus B4A

306

Left$(text, n) [n=num.of chars.]

Right$(text, n)
If a$ = b$...
If Right$(text, n) = text2...
If Left$(text, n) = text2...
If Lcase$(text) = Lcase$(text2)...
x = Len(text)
text = Replace(text, str, str2)
Lcase(text)
Ucase(text)
Trim(text)
(no LTrim or RTrim in B4A)
Instr(text, string)
Instr(int, text, string)

text.SubString2(0, n)
text.SubString(text.Length - n + 1)
If a.CompareTo(b)...
If text.EndsWith(text2)...
If text.StartsWith(text2)...
If text.EqualsIgnoreCase(text2)...
x = text.Length
text.Replace(str, str2)
text.ToLowerCase
text.ToUpperCase
text.Trim

If Lcase$(x) = Lcase$(y)...
text = Left$(text, n) & s &
Right$(Text, y)
Asc(s) [where s = a character]

Basic4Android Beginner's Guide

text.IndexOf(string)
text.IndexOf2(string, int)
Returns -1 if not found.
Returns char. index, not position.
Starts search at "int".
If x.EqualsIgnoreCase(y)...
text.Insert(n, s)
same

Error Trapping:
-------------VB6:
===
Sub SomeSub
On [Local] Error GoTo ErrorTrap
...some code...
On Error GoTo 0 [optional end to error trapping]
...optional additional code...
Exit Sub [to avoid executing ErrorTrap code]
ErrorTrap:
...optional code for error correction...
Resume [optional: "Resume Next" or "Resume [line label]".
End Sub
B4A:
===
Sub SomeSub
Try
...some code...
Catch [only executes if error above]
Log(LastException) [optional]
...optional code for error correction...
End Try
...optional additional code...
End Sub
WIth B4A, if you get an error caught in the middle of a large subroutine, you
can
NOT make a correction and resume within the code you were executing. Only the
code
in "Catch" gets executed. That would seem to make Try-Catch-End Try of use
mainly
during development.
Try-Catch in place of GoTo:
-------------------------Try-Catch can be used as a substitute for GoTo [line label] for forward, but not
backward, jumps. It cannot be used to replace GoSub, for which B4A has no
equivalent.
Start the code with "Try" and replace the [line label] with "Catch".

16 VB6 versus B4A

307

Basic4Android Beginner's Guide

Replace "GoTo [line label]" with code which will create an exception, which
causes
a jump to "Catch", such as OpenInput("bad path", "bad filename").
"Immediate Window" vs "Logs" Tab
-------------------------------Comments, variable values, etc., can be displayed in VB6's Immediate
Window by entering into the code "Debug.Print ...".
In the B4A environment, the Logs tab on the right side of the IDE is a
way to show the values of variables, etc., while the code is running.
Both VB6 and (now) B4A allow single-stepping through the code while it
is running and viewing the values of variables. VB6 also allows changing
the value of variables, changing the code, jumping to other lines from
the current line, etc. Because B4A runs on a PC while the app runs on
a separate device, B4A is currently unable to duplicate all of these
VB6 debug features.

17 FAQ

308

Beginner's Guide

17 FAQ
Some of the chapters below have been picked up from the forum.

17.1 "Please save project first" message

When I try to compile or open the Designer I see a message saying: "Please save source code first."
A new project doesn't have a containing folder until it is first saved.
Save your project and this error will go away.

17.2 "Are you missing a library reference" message

Compiler says: "Are you missing a library reference?".
Go to the Libraries tab in the right pane and check the
required libraries.
If you do not know which library a specific object type
belongs to, you can go to the documentation page or to
the list of additional libraries.

At the bottom of this page there is a long list with all the
objects types.

Pressing on any type will take you to the right library.

Note that the trial version doesn't support libraries. Only the full version.

17 FAQ

309

Beginner's Guide

17.3 How loading / updating a library

See the Libraries chapter in the guide.
A list of the official and additional libraries with links to the relevant forum threads is shown in the
B4A Wiki here: List of Libraries
To load or update a library follow the steps below:
Download the library zip file somewhere.
Unzip it.
Copy the xxx.jar and xxx.xml files to the
o B4A Library folder for a standard B4A library
o Additional libraries folder for an additional library.
Restart the IDE and check the library in the Lib Tab list to select it.

17.4 When do we need to 'Initialize' and when not

View.
For ALL Views:
To be able to have access to any View by its name you must Dim it in the Sub Globals
routine.
Views added
in the Designer in a layout file MUST NOT be initialized !
o Just Dim the View in the Sub Globals routine.
Sub Globals
Dim lblTitle As Label

and nothing else.

by code MUST be initilized.

o Dim the View in the Sub Globals routine.
Sub Globals
Dim lblTitle As Label

o Initialize it and add it to the Activity (or a Panel) in the Activity_Create routine.
Sub Activity_Create(FirstTime As Boolean)
If FirstTime Then
lblTitle.Initialize("")
Activity.AddView(lblTitle, 10dip, 10dip, 200dip, 50dip)
End If

List / Map.
List and Map objects must be Initialized before they can be used.

17 FAQ

310

Beginner's Guide

17.5 Split a long line into two or more lines

To split a long line into two or more lines put an underscore character, seperated by a blank
character, at the end of the line. Look at the example in the chapter below.
Answ = Msgbox2("Do you want to quit the program", "A T T E N T I O N", "Yes", "", "No", Null)

Becomes:
Answ = Msgbox2("Do you want to quit the program", _
"A T T E N T I O N", "Yes", "", "No", Null)

17.6 Avoid closing an application / capture keycodes like Back / Menu

This can be done by intercepting the Activity_KeyPress event.
Sub Activity_KeyPress (KeyCode As Int) As Boolean 'Return True to consume the
event
Dim Answ As Int
If KeyCode = KeyCodes.KEYCODE_BACK Then
Answ = Msgbox2("Do you want to quit the program ?", _
"A T T E N T I O N", "Yes", "", "No", Null)
If Answ = DialogResponse.NEGATIVE Then
Return True
End If
End If
Return False
End Sub

We check if the the KeyCode equals the Back key.

If yes, we ask the user if he really wants to quit the program.
o If 'No' we return True to consume the event.
o Otherwise we return False to transmit the event to the OS.

Just as a reminder, the underscore at the end in the 5th line

Answ = Msgbox2("Do you want to quit the program ?", _

means split the line and put the rest on the next line.
ATTENTION :
The Home key cannot be trapped in the Activity_KeyPress event routine !

17 FAQ

311

Beginner's Guide

17.7 Unwanted events like Click, Touch or others

Proposed by alfcen:
Suppose you have an Activity containing several buttons with Click events.
Now, you add a Panel onto the Activity, thus covering buttons. As you tap on the
panel you will see that a click event was fired on a button on the Activity.
This is NOT a B4A bug, on the contrary, it might be quite useful.
However, if this is not wanted, just add:
Sub Panel1_Click
' do nothing here or place code to be executed upon tapping on the panel
End Sub

17.8 Adding a Menu item

You should also have a look at Example programs / User interfaces.
This is done with the AddMenuItem or AddMenuItem2 methods.
Once a menu item is added you can neither modify it nor remove or disable it.
Activity.AddMenuItem("Title", "EventName")
Activity.AddMenuItem("Title", "EventName", image)

Examples:
Activity.AddMenuItem("Load", "mnuLoad")
Activity.AddMenuItem("Save", "mnuSave", image)

or
Activity.AddMenuItem("Load", "mnuLoad", LoadBitmap(File.DirAssets, "Load.png"))
Activity.AddMenuItem("Save", "mnuSave", LoadBitmap(File.DirAssets, "Save.png"))

17 FAQ

312

Beginner's Guide

17.9 How do I remove a View with the Designer

To remove a View with the Designer you must:
Select the View to remove either on the device, the Emulator or in the Designer.
Remove it, in the menu Tools click on Remove Selected View.

17.10 "Process has timeout" message

If you often get this message "Process has timeout" you can change its value:
In the IDE menu Tools / IDE Options click on Configure Process Timeout.

And change the value:

17 FAQ

313

Beginner's Guide

17.11 Getting a picture from the gallery

Following code allows you to load a picture from the gallery.
Sub Process_Globals
Dim chooser As ContentChooser
End Sub
Sub Globals
End Sub
Sub Activity_Create(FirstTime As Boolean)
If FirstTime Then
chooser.Initialize("chooser")
End If
chooser.Show("image/*", "Choose image")
End Sub
Sub chooser_Result(Success As Boolean, Dir As String, FileName As String)
If Success Then
Dim bmp As Bitmap
bmp.Initialize(Dir, FileName)
Activity.SetBackgroundImage(bmp)
Else
ToastMessageShow("No image selected", True)
End If
End Sub

17 FAQ

314

Beginner's Guide

17.12 How to delete x.bal files or other files from a project

To delete files from the project you must use the files Tab in the lower right corner of the IDE.

Select the files you want to delete.

Click on
and confirm to delete the files.
If you delete the files only in the folder, you will get a message for missing files the next
time you start the project.

You will be asked if you want to remove the files from the Files folder.
Oui > Yes
Non > No
Annuler > Cancel
o Yes
Removes the selected files from the Files folder, be sure that you have
backup files somewhere else if you need them afterwards.
o No
Removes the files from the project but leaves them in the Files folder.
o Cancel
Aborts the function.

17 FAQ

315

Beginner's Guide

17.13 Block a screen orientation

To block the orientation either to Portrait or to Landscape.
This valid for the whole project.
To define different screen orientations for different activities you must do in the code see below.

In the IDE, menu :

Project / Orientations supported:

Both
Portrait
Landscape

You can define screen orientations in the code with SetScreenOrientation from the Phone
library:

Landscape
Phone1.SetScreenOrientation(0)

Portrait
Phone1.SetScreenOrientation(1)

Both
Phone1.SetScreenOrientation(-1)

17 FAQ

316

Beginner's Guide

17.14 Close second Activity

From the forum:
Referring to the 'twoactivities' tutorial by Erel, I noticed that when back button was pressed from
the main Activity, Activity2 was then shown again.
In the code of Activity2 after StartActivity(Main) add Activity.Finish.
StartActivity(Main)
Activity.Finish

17.15 Taking a screenshot programaticaly

You can take a screenshot of the device or the Emulator with following code:
Needs the Reflection library.
Sub btnScrShot_LongClick
' Take a screenshot.
Dim Obj1, Obj2 As Reflector
Dim bmp As Bitmap
Dim c As Canvas
Dim now, i As Long
Dim dt As String
DateTime.DateFormat = "yyMMddHHmmss"
now = DateTime.now
dt = DateTime.Date(now) ' e.g.: "110812150355" is Aug.12, 2011, 3:03:55 p.m.
Obj1.Target = Obj1.GetActivityBA
Obj1.Target = Obj1.GetField("vg")
bmp.InitializeMutable(Activity.Width, Activity.Height)
c.Initialize2(bmp)
Dim args(1) As Object
Dim types(1) As String
Obj2.Target = c
Obj2.Target = Obj2.GetField("canvas")
args(0) = Obj2.Target
types(0) = "android.graphics.Canvas"
Obj1.RunMethod4("draw", args, types)
Dim Out As OutputStream
Out = File.OpenOutput(File.DirRootExternal, dt & ".png", False)
bmp.WriteToStream(Out, 100, "PNG")
Out.Close
End Sub

17.16 After compiling, where are the files

The compiler generates an *.apk file which is located in the 'Objects' folder. When the IDE is
connected to a device or to the Emulator the apk file is automaticaly uploaded to it.
The name of the apk file is the 'Application Label' you entered when you defined the project.
Example: GPSExample.apk
If you have checked 'Include Debug Information' and 'Attach Debugger' in the IDE you will get an
apk file with the _DEBUG suffix.
Example: GPSExample_DEBUG.apk
If you want to distribute your application you should uncheck these two options.

17 FAQ

317

Beginner's Guide

17.17 Run an application from another one

Erels' answer to the question:
You can start any application by sending the correct Intent.
The easiest way to see the required Intent is to look at the unfiltered logs while manually starting
the application.
The code below shows how to run an application from another one.
The PackageManager is an object in the Phone library.
The exact package name is needed !
Dim pm As PackageManager
Dim in As Intent
in.Initialize("", "")
in = pm.GetApplicationIntent
If in.IsInitialized Then
StartActivity(in)
End If

17.18 How to pass an Array to a Sub

It is possible to pass Arrays, also multidimensional Arrays, to a sub.
Code example.
Dim one(1), two(1,2), three(1,2,3) As String
Sub Test(a() As String, b(,) As String, c(,,) As String) As String(,)
...
End Sub
'
'
Test(one, two, three)

You need to specify the rank (number of dimensions) in the Sub definition with ',' .
If you want the Sub to return an array you must also speccify it.
Sub Test(a() As String, b(,) As String, c(,,) As String) As String

Returns a single string.

Sub Test(a() As String, b(,) As String, c(,,) As String) As String()

Returns a one rank string array.

Sub Test(a() As String, b(,) As String, c(,,) As String) As String(,)

Returns a two rank string array.

17 FAQ

318

Beginner's Guide

17.19 Getting language and country from device

You can get the current language and country from a device with the following code.
Sub Activity_Create(FirstTime As Boolean)
Log(GetDefaultLanguage)
End Sub
Sub GetDefaultLanguage
Dim r As Reflector
r.Target = r.RunStaticMethod("java.util.Locale", "getDefault", Null, Null)
Return r.RunMethod("getDisplayName")
End Sub
GetDefaultLanguage returns a string with the language and the country.

Needs the Reflection library (available only for users who bought Basic4Android) !
Examples:

English (United States)

Deutsch (sterreich)
franais (Suisse)

17.20 Where is the apk file

Where is the apk file:
The apk file is located in the Objects folder of your project.

17.21 Why is my apk filename result.apk

The filename is the same as the main project filename but instead of the .b4a suffix it has the .apk
suffix.
If you enter non authorized characters, like a space, the apk filename will be result.apk.
The apk name has no importance, the displayed name is the Label name you gave when you created
the project.

17 FAQ

319

Beginner's Guide

17.22 Why is my apk filename xxx_DEBUG.apk

To distribute a program you must select in the IDE, in the Drpodown list,
Release.

17.23 Select True / Case trick

The question : It would be nice to be able to use Select Case using the 'greater than' and 'less than'
operators <>. It makes for cleaner code than 'if' 'else' and 'end if' etc.
This trick does it:
i = 10
Select True
Case (i < 9)
Log("False")
Case (i = 10)
Log("True")
End Select

17.24 Fill an array with random numbers without repetition

This code snippet from Erel is based on the Fisher-Yates shuffle algorithm.
Sub Globals
Dim numbers(10) As Int
End Sub
Sub Activity_Create(FirstTime As Boolean)
'put numbers 1 - 10 in the array
For i = 0 To 9
numbers(i) = i + 1
Next
ShuffleArray(numbers)
For i = 0 To 9
Log(numbers(i)) 'print the numbers to the log
Next
End Sub
Sub ShuffleArray(arr() As Int)
Dim i As Int
For i = arr.Length - 1 To 0 Step -1
Dim j, k As Int
j = Rnd(0, i + 1)
k = arr(j)
arr(j) = arr(i)
arr(i) = k
Next
End Sub

17 FAQ

320

Beginner's Guide

17.25 Detect screen orientation

The code below detects the screen orientaion, comparing if the activity width is greater than the
activity height then the orientation is "landscape" otherwise it's "portrait".
Sub Globals
Dim Orientation As String
End Sub
Sub Activity_Create(FirstTime As Boolean)
If Activity.Width > Activity.Height Then
Orientation = "Landscape"
Else
Orientation = "Portait"
End If
End Sub

17.26 Some functions don't work in Activity_Pause

All functions stopping the program are not allowed in the Activity_Pause routine.
Like :
Message boxes
MsgBox
Modal dialogs
InputDialog, FileDialog etc.
Custom dialogs
Breakpoints
Log and ToasMessage work.

17 FAQ

321

17.27 Calling the internal Calculator

The subroutine below calls the internal calculator.
Sub Calculator
Dim i As Intent
i.Initialize("", "")
i.SetComponent("com.android.calculator2/.Calculator")
Try
StartActivity(i)
Catch
ToastMessageShow("Calculator app not found.", True)
End Try
End Sub

Some manufacturers change the name of the internal calculator.

The code below overcomes this problem.
Code provided by dxxxyyyzzz on the forum.
Needs the Phone Library.
Dim
Dim
Dim
Dim

Pm As PackageManager
Inte As Intent
Packages As List
st As String

Packages = Pm.GetInstalledPackages
For i = 0 To Packages.size - 1
st=Packages.Get(i)
If st.Contains("calc") =True Then
Inte=Pm.GetApplicationIntent(st)
If Inte.IsInitialized Then
StartActivity(Inte)
Exit
End If
End If
Next

Beginner's Guide

17 FAQ

322

Beginner's Guide

17.28 Get the Alpha / Red / Green / Blue

Sub Activity_Create(FirstTime As Boolean)
Dim argb() As Int
argb = GetARGB(Colors.Transparent)
Log("A = " & argb(0))
Log("R = " & argb(1))
Log("G = " & argb(2))
Log("B = " & argb(3))
End Sub
Sub GetARGB(Color As Int) As Int()
Dim res(4) As Int
res(0) = Bit.UnsignedShiftRight(Bit.And(Color, 0xff000000), 24)
res(1) = Bit.UnsignedShiftRight(Bit.And(Color, 0xff0000), 16)
res(2) = Bit.UnsignedShiftRight(Bit.And(Color, 0xff00), 8)
res(3) = Bit.And(Color, 0xff)
Return res
End Sub

In line Sub GetARGB(Color As Int) As Int() the () after Int are necessary because the return
value is an array.

17.29 Get device type

Sub Activity_Create(FirstTime As Boolean)
If GetDevicePhysicalSize > 6 Then
'7'' or 10'' tablet
Else
'phone
End If
End Sub
Sub GetDevicePhysicalSize As Float
Dim lv As LayoutValues
lv = GetDeviceLayoutValues
Return Sqrt(Power(lv.Height, 2) + Power(lv.Width, 2)) / lv.Scale / 160
End Sub

17.30 Generate a Click event

Sub Globals
Dim sp As Spinner
End Sub
Sub Activity_Create(FirstTime As Boolean)
sp.Initialize("sp")
sp.AddAll(Array As String("a", "b", "c", "d"))
Activity.AddView(sp, 10dip, 10dip, 200dip, 50dip)
End Sub
Sub Activity_Click
OpenSpinner(sp)
End Sub
Sub OpenSpinner(s As Spinner)
Dim r As Reflector
r.Target = s
r.RunMethod("performClick")
End Sub

17 FAQ

323

Beginner's Guide

17.31 "Out of memory" Error / Bitmaps

Under certain circumstances the program stops with "Out of memory" message.
This can happen when there are big bitmaps or many bitmaps.
The code below disposes the bitmap and frees the memory (code provided by agraham here)
Dim Obj1 As Reflector
Obj1.Target = bmp ' bmp is the unwanted Bitmap
Obj1.RunMethod("recycle")

For a bitmaps of a canvas:

Obj1.Target = canv
Obj1.Target = Obj1.GetField("bw")
Obj1.Target = Obj1.RunMethod("getObject")
Obj1.RunMethod("recycle")

17.32 Remove the scrollbar from a ScrollView

The code needs the Reflection library.
Dim r As Reflector
r.Target = ScrollView1
r.RunMethod2("setVerticalScrollBarEnabled", False, "java.lang.boolean")

17.33 Check if directory exists

Dim MyDirctory As String
MyDirctory = File.DirRootExternal & "/Images"
If File.Exists(MyDirctory, "") = False Then
File.MakeDir(File.DirRootExternal, "Images")
End If

17.34 Set Full Screen in code

Sub FullScreen(Active As Boolean, ActivityName As String)
Dim obj1 As Reflector
Dim i As Int
i = 1024 'FLAG_FULLSCREEN
obj1.Target = obj1.GetMostCurrent(ActivityName)
obj1.Target = obj1.RunMethod("getWindow")
If Active Then
obj1.RunMethod2("addFlags",i,"java.lang.int")
Else
obj1.RunMethod2("clearFlags",i,"java.lang.int")
End If
End Sub
Active = True sets full screen.
Active = False set back to show the status bar.

17 FAQ

324

Beginner's Guide

17.35 Change EditText input modes

The EditText view has several default input modes.
INPUT_TYPE_NONE
No input allowed.
INPUT_TYPE_NUMBERS
Allows only integer numbers.
INPUT_TYPE_DECIMAL_NUMBERS
Allows only decimal numbers.
INPUT_TYPE_TEXT
Allows any type of text.
INPUT_TYPE_PHONE
Allows phone numbers.
Example:
EditText1.InputType = EditText1.INPUT_TYPE_TEXT

Other flags are available:

A complete list can be found here.

INPUT_TYPE_TEXT flag combinations:

TYPE_TEXT_FLAG_CAP_CHARACTERS

Constant Value: 4096 (0x00001000)

Sets to upper case characters.

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 4096)

TYPE_TEXT_FLAG_CAP_SENTENCES

Constant Value: 16384 (0x00004000)

Sets the first character of a sentence to upper case.

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 16384)

TYPE_TEXT_FLAG_CAP_WORDS

Constant Value: 8192 (0x00002000)

Sets the first character of all words to upper case.

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 8192)

TYPE_TEXT_FLAG_NO_SUGGESTION

Constant Value: 524288 (0x00080000)

Sets to no suggestion.
EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 524288)

TYPE_TEXT_FLAG_AUTO_COMPLETE
Sets auto complete.

Constant Value: 65536 (0x00010000)

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 65536)

TYPE_TEXT_FLAG_AUTO_CORRECT
Sets auto correct.

Constant Value: 32768 (0x00008000)

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 32768)

TYPE_TEXT_VARIATION_EMAIL_ADDRESS

Constant Value: 32 (0x00000020)

Sets for e-mail address.

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 8192)

TYPE_TEXT_VARIATION_PASSWORD

Constant Value: 128 (0x00000080)

Sets password mode.

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_TEXT, 128)

17 FAQ

325

Beginner's Guide

INPUT_TYPE_NUMBERS flag combinations:

TYPE_NUMBER_SIGNED

Constant Value: 4096 (0x00001000)

Allows signed integer numbers

EditText1.InputType = Bit.Or(EditText1.INPUT_TYPE_NUMBERS, 4096)

17 FAQ

326

Beginner's Guide

17.36 Sorting a file list according to last modified time

Code supplied by Erel in the forum.
Sub Process_Globals
Type FileAndTime(Name As String, Time As Long)
End Sub
Sub Globals
End Sub
Sub Activity_Create(FirstTime As Boolean)
Dim files As List
files = ListFilesByDate(File.DirRootExternal)
For i = 0 To files.Size - 1
Dim fs As FileAndTime
fs = files.Get(i)
Log(fs.Name & ": " & DateTime.Date(fs.Time))
Next
End Sub
Sub ListFilesByDate(Folder As String) As List
Dim files As List
files = File.ListFiles(Folder)
Dim sortedFiles As List
sortedFiles.Initialize
For i = 0 To files.Size - 1
Dim fs As FileAndTime
fs.Name = files.Get(i)
fs.Time = File.LastModified(Folder, fs.Name)
sortedFiles.Add(fs)
Next
sortedFiles.SortType("Time", False)
Return sortedFiles
End Sub

17.37 Get the dpi values of the device (dots per inch)
Needs the Reflection library.
Dim Xdpi,Ydpi As Float
Dim r As Reflector
r.Target = r.GetContext
r.Target = r.RunMethod("getResources")
r.Target = r.RunMethod("getDisplayMetrics")
Xdpi = r.GetField("xdpi")
Ydpi = r.GetField("ydpi")

The different fields are :

density
The logical density of the display.
densityDpi
The screen density expressed as dots-per-inch.
heightPixels
The absolute height of the display in pixels.
widthPixels
The absolute width of the display in pixels.
scaledDisplay A scaling factor for fonts displayed on the display.
xdpi
The exact physical pixels per inch of the screen in the X dimension.
ydpt
The exact physical pixels per inch of the screen in the X dimension.

17 FAQ

327

Beginner's Guide

17.38 Finding java program lines

Sometimes a program raises java execution error messages with the subname and a java line
number.
To find the given line :
look at the Objects\src\packagename for the activity.java file.
open it in a text editor showing line numbers (like notepad++)
look at the given line number and you find the offending code.
Advice given by warwound (Martin Pearman).

18 Glossary

328

Basic4Android Beginner's Guide

18 Glossary
Android Android is a software stack for mobile devices that includes an operating system,
middleware and key applications. Google Inc. purchased, in 2005, Android Inc. the company that
initially developed the software.
Java
Java is a programming language originally developed by James Gosling at Sun
Microsystems (which is now a subsidiary of Oracle Corporation) and released in 1995 as a core
component of Sun Microsystems' Java platform. The language derives much of its syntax from C
and C++ but has a simpler object model and fewer low-level facilities.
Activity An activity is a single, focused thing that the user can do. Almost all activities interact
with the user, so the Activity class takes care of creating a window for you in which you can place
your UI.
View
Provides classes that expose basic user interface classes that handle screen layout and
interaction with the user. Examples: Label, Panel, Button, EditText etc.