*General Topics*

Back to the start


Subs
Variables
Array Variables
Controls
Operators
External Files
Debug
Menu Editor
Visual Designer
Compiling Applications
Screen Size
Unicode
Database
External Libraries and Objects
Code Files
Data Types



Subs Top

All program code (including global variables definitions) is written inside Subs. Subs syntax starts with "Sub SubName (Parameters)" and ends with "End Sub".
If there are no parameters for the sub, then write "Sub SubName" without the parentheses. There are no Functions in Basic4ppc but instead every sub can return a value with the keyword "Return"

There are two special subs:
1. Globals - Inside this sub you can declare global variables. Any other variable you will declare elsewhere will be local. (Global means that the variable can be used anywhere, unlike local that of which can be used only in the same sub.)
2. App_Start - This is the first sub that executes when the program loads. If no form is shown at the end of this sub execution then the program will end.


To connect an event to a sub you have three options:
1. Use the event menu in the Designer, and the correct sub will be added automatically.
2. Write a sub whose name is the control's name (the control that will trigger the event) and the event name joined by an underscore.
If the event has parameters then add them too. (Their names are not important)
Example: Sub Button1_Click
Example: Sub Form1_MouseDown (px,py)
3. Use the AddEvent keyword.

To call a sub, write its name (and parameters if any. If there are no parameters then do not write any parentheses).

Example:

Sub Button1_Click
  Msgbox("The mean of 20 and 30 is " & crlf & Mean(20,30))
End Sub

Sub Mean (a,b)
  Return (a+b)/2
End Sub

Result: A Msgbox that displays 25 when the button is pressed.

Variables Top

In Basic4ppc all simple variables are variant variables. This means that any variable can store any type of number or a string. Variables can be global or local.
Local variables value can be used only while their parent sub is executing.
Global variables? values can be used everywhere.
Except for array variables, there is no need to declare a local variable before using it.
Global variables are variables that were declared (or used) in Sub Globals; all other variables are local.

Example:

Sub Globals
  a=20
End Sub

Sub App_Start
  b=10
  CalcVars
End Sub

Sub CalcVars
  Msgbox ("a = " & a)  
Msgbox ("b = " & b)
End Sub

Result:
First msgbox will show a = 20

Second msgbox will show b = b is null because it's local and wasn't assigned any value yet in this sub.

To pass data between subs you could use global variables, or better, you can pass the data as parameters.

Example:
Sub Globals
  a=20
End Sub

Sub App_Start
  c=10
  CalcVars (c)
End Sub

Sub CalcVars (b)
  Msgbox ("a = " & a)
  Msgbox ("b = " & b)
End Sub
Result: The second msgbox will show b = 10

Note: When using parameters the variable is not passed, but its value is copied.
In the above example, I used a variable named c instead of b. Remember that if you change a local variable?s value in one place (even if it had received its data from a parameter), then the change will not affect any other local or global variable outside the current sub.

Array Variables Top

Basic4ppc supports arrays of up to three dimensions. Array variables are always global and must be declared before used. Arrays can store items of a certain data type.
This is useful for working with external libraries which sometimes expect an array of a certain type.
Declare global variables with Dim keyword.
An array index starts from 0 and its last index is array dimensions - 1.
Example:
Sub Globals
 Dim Books (20)
  Dim Buffer (100) As Byte
End Sub

Result: Declares an array of 20 items starting from Books(0) and up to Books(19) and an array of bytes starting from Buffer(0) and up to Buffer(99)
When you need to reference an entire array (not one item in the array) write the array's name followed by ().

Example:
i = ArrayLen (buffer() )
BinaryFile.WriteBytes (buffer())

Arrays can be declared with 0 items like:
  Dim Buffer(0) As Byte
Buffer is an empty array that can be used later with an external library which returns an array.
Example:
  Buffer() = Serial.InputArray
Use ArrayLen to find the length of the array.

Controls Top

Controls in Basic4ppc are global objects, which means that each control has a unique name (even if controls are on different forms).
To reference a control you need to write its name followed with a period. A list of properties and methods will pop up (only for controls that were added using the Visual Designer).

Example:

[M] - Method.
If the method name is followed with () then the method syntax includes ().
Example: Form1.Line (20,20,60,60,cGreen,BF)

[I/O] - Input / Output property (named also get / set property).

Operators Top

The operators in Basic4ppc are:
  +,-,*,/     Basic math operators
  ^      Power sign
  mod    Modulus operator
  &    String concatenation
  '    Remarks (REM is not supported)


External Files Top

There are some occasions when your program may look for external file.
The external file path is relative to the source code path (or the compiled application path).
If you haven't saved your program even once then there is not any known path and Basic4ppc won't be able to find external files.

Example:
To play a wave file named music.wav that is located at the same folder of the source code (or compiled application) you need to write: Sound ("music.wav")


Debug Top

Debugging your applications can be done in several ways.
Using the Add BreakPoint / Remove BreakPoint you can choose in which line the program will stop. When the program is running you can use Pause to make it pause on the next statement. Stop button will quit the application.
Once the application is paused (Break Mode), you can see the value of the variables by making the cursor hover over them.
A tooltip will show the data.
Tooltips are limited to regular variables and one dimension arrays with a simple index.
For more complicated values (or expressions) use the watches at the bottom of the screen.
To return the cursor to the line where paused, press Pause again.
To continue running the application use Run or one of the step options.
Step will step to the next statement.
Step Over will not enter a nested Sub. (The application will enter the sub but it will not stop there.)
Step Out will exit the current sub. (Again, it will finish the current sub and then stop.)

Menu Editor Top

The menu editor allows you to add menu items to a form.
Reaching the menu editor is done through the Visual Designer - Controls - Menu Editor.
Each item added will show as a menu item when running the application.
To add an event push the "Create Click Event" button, and the event sub will show in the code. Menu items with child nodes will not raise click event. Top level menu items cannot be checked.

Visual Designer Top

The Visual Designer allows you to build your GUI with little effort. To open the Designer, choose Menu - Design - Create New Form (or one of the already created forms, if any). From the Designer, you can add controls to your form, change their properties and build their events.

To add controls to a form, choose Menu - Controls - The control you want to add. The control will show in the middle of the form. Now you can move and change the controls height and width with the mouse. Type with the keyboard to change its text. To change its properties, select it and choose Menu - Properties.

There are three ways to choose the color (font color and back color):
1. Write a R,G,B color (each number can be between 0 to 255).
2. Write one of the color constants. Example: cYellow
3. On the desktop only: Click on the button "Color" and choose the color.

Some of the properties change between different types of controls.
In the Image File property (relevant to Forms and Images controls), type the image file name.
As with all files in Basic4ppc the file path is relative to your source code path (or the compiled application path).
In order to use external files in Basic4ppc, source code must first be saved at least once so Basic4ppc will know its initial directory.

Compiling Applications Top

As of version 3.0 Basic4ppc supports compiling your application to an executable file with no runtime files needed.
Compiled files can target Windows EXE (desktop) and Device EXE (Pocket PC / Windows Mobile). Unlike previous versions of Basic4ppc, compiling is done from the desktop (full version). B4P files are no longer supported and Basic4ppc Runner is no longer needed.
The compiled application file will show the icon you chose.
Devices support icons with up to 256 colors. To choose an icon: Menu - Choose Icon.
To compile your application: Menu - Compile - Device EXE or Windows EXE.
Devices cache the icons. If you change an icon to an existing file (replacing a file with a new one with the same name), you will have to soft reset the device to see the new icon.

Screen Size Top

When working on a device the forms screen size is same as the physical screen size and you can't control the forms size.
On the desktop you can change the "screen" size. Changing the screen size will affect all forms. Changing is done through the Visual Designer - Tools - Screen Size.
For example, if you want to write a landscape application change the screen size to:
Height - 240
Width - 320
These settings won't change the screen orientation on the device automatically.
Using Form.Width / Form.Height you can get the size of the user available area (without the menu and tittle bar).

Unicode Top

Basic4ppc supports Unicode formatted as UTF-8. All keywords support this format except FileGet / FilePut which support only ASCII files. When working with a non-ASCII file make sure to save it as UTF-8. This can be done with Microsot NotePad: Choose Save As - Encoding - UTF-8.

Database Top
Database applications use the Table control.
The Table control stores data in rows (records).
If you do not want to show the table directly, then change its Visible property to false and use the table only to access the data.
Each row consists of several columns. Rows are accessed by their index (starting from 0) and columns are accessed by there names.
Each column can store either string data or numbers only.
To access a specific cell use Table.Cell (Column Name, Row Index)
To sort the data use TableSort.
To filter the data use the Filter method. Filtering does not delete any rows; but it hides all the rows that do not match the filter expression. ColName property returns the name of the column in the specified index and allows iterating through all columns in an easy way. Data can be saved to and loaded from files either as XML data or CSV (Comma Separated Values).
XML files store the columns types as well as the data. XML files are bigger than CSV files and take longer to load / save. CSV files store only the data.
CaseSensitve property determines if string comparison (filtering and sorting) is case sensitive or not. Default is not.

External Libraries and Objects Top

As of version 4.00 Basic4ppc supports working with external libraries. The external libraries are dll files which include all kinds of new functionality.

There are three stages for working with external libraries:

First Stage:
Open the Components dialog using Tools - Components...
The Components dialog shows the dll and code files that are used for the desktop and the device. Sometimes there are different files for the desktop and the device (like SerialDevice.dll and SerialDesktop.dll).
Add the required dll file.

Second Stage:
Using Tools - Add Object, choose the object type and create an object of this type.

If you prefer to add the objects at runtime you can use the AddObject keyword instead.

Third Stage:
Before using an object it must first be initialized with one if its New methods. Example:
Node1.New1

Important notes: Under the Help menu you will find the documentation of all the libraries (on the desktop only).
Like all other controls, when you write the object's name and add a period, a list of all available methods and properties will appear. All objects support the Dispose method which is used to delete the object and free the resources it uses. The Control keyword can be used with objects. When an external method expects a file, the absolute path should use.
You can use AppPath to get the path of the application. Example:
Bitmap1.New1 (AppPath & "\pic.jpg")

The dll files should be distributed together (in the same folder) with the compiled file.

Code Files Top

Basic4ppc supports separating the code into several files.
A project must include one main sbp file. The other files are regular text files. Breaking the code into several files can be handy when building large applications, or when there is a need to write different code for the desktop and the device.
Note that small differences (between desktop and device) can be handled using the cPPC constant. To add a code file to the application, choose Tools - Components... Now add the code files to the desktop, device or both.

Data Types Top

Some external libraries expect variables of a specific type.
If this is a regular variable (not array) Basic4ppc will automatically convert the variable to the right type. This is not the case when working with arrays. In order to avoid the performance loss of converting many items Basic4ppc will not convert arrays.
When you declare an array you can declare it as an array of a specific data type.
These are the available data types:

Name Description Range
* Byte  8-bit unsigned integer   0 - 255
* Int16  16-bit signed integer   -32768 - 32767
* Int32  32-bit signed integer  -2,147,483,648 - 2,147,483,647
* Int64  64-bit signer integer  -9e18 - 9e18
* Single  32-bit floating point   -3.4e38 - 3.4e38
* Double 64-bit floating point -1.79e308 - 1.79e308
* Boolean  8-bit boolean value   True, False
* Decimal  96-bit integer value  -79e27 - 79e27
* Char  A Unicode character
* String