Tutorial Hb++

HB++ ®

HANDHELD BASIC ®

Tutorial Básico

Guía Básica HB++®

2006 EVC Jr. 2

CONTENIDO

1. Introducción2. Software necesario3. Mi primera aplicación4. Controles GUI Personalizados.5. Bases de Datos Nativas de Palm OS6. Sitios Útiles7. Bibliografía


2006 EVC Jr. 3

INTRODUCCIÓN

Handheld Basic® es un lenguaje orientado al desarrollo de aplicaciones administrativas. Elmismo posee una sintaxis casi idéntica a MS Visual Basic®, como así también muchoscontroles GUI necesarios para el desarrollo de cualquier aplicación.Este tutorial es solo una guía básica que recopila algunos materiales de la página oficial deHandheld Basic®, por lo que toda la parte instructiva del tutorial está en inglés. El objetivo delmismo es dar a conocer algunas cuestiones de este nuevo lenguaje y animar a losprogramadores a utilizarlo y crear nuevas aplicaciones para los PDAs y Handhelds basadasen Palm OS®.

Por ser un lenguaje nuevo la comunidad de desarrolladores es muy reducida y ladocumentación existente es casi nula, la mayoría de la información y ejemplos disponible selimita a la página de HB++®. Es por ello que la intención de esta recopilación es invitar a losprogramadores a probar este Entorno de Desarrollo y ayudarnos mutuamente en elmaravilloso desafío de crear nuevas aplicaciones.


2006 EVC Jr. 4

SOFTWARE NECESARIO

Para comenzar a programar con HB++® necesitarás descargarte el Palm OS® Simulator de lapágina oficial del sistema operativo: www.palmsource.comPara descargarlo tenés que registrarte como desarrollador. Posteriormente en la secciónreservada para desarrolladores, deberás descargar la versión que simula al Palm OS® 5.4también llamado Palm OS® Garnet.Luego descargarte de la página oficial de HB++®: www.handheld-basic.com, la última versiónde Handheld Basic®.

Con este software ya estamos en condiciones de comenzar a crear nuestras primerasaplicaciones.

http://www.palmsource.com

http://www.handheld-basic.com


2006 EVC Jr. 5

MI PRIMERA APLICACIÓN

Your first application will be made of a text field and a button. Clicking on the button will causethe message "hello world" to appear in the text field.

An HB++ application is made up of one or more forms as well as a class describing how theapplication will handle different launch codes. Don't worry about these: the "Minimal Project"wizard will do everything for you.

Activate the frmMain default form which was automatically created for you:

Then, create a text field click using the appropriate tool in the toolbox:


2006 EVC Jr. 6

Create a button... It is now possible to modify the properties of the button and the text field.Select the button, then in the property window, change the "Text" property to: "Hello". Nowselect the form, and define the "Caption" property as: "My First Application".

The design of your form is now complete. It should look like this:

Writing codeNow, it is time to write the code handling the user events. Right clicking on a control displaysthe list of events it can raise. By right clicking on the button, you will see:


2006 EVC Jr. 7

By clicking on the "Click()" item, the text

appears in the code edit window.Enter the following code between the Sub and End Sub declarations:

Field1.Text = "hello, world"

That's all!Compiling and debugging

Click the Compile button or press F5 to compile your project. The output window displayserror messages and warnings.

In case your source code has no error, a .prc file is generated... You can install it on yourhandheld, or use the HB++ integrated debugger.In case you want to use the HB++ integrated debugger, click on the icon to launch theapplication either in the Palm OS® Emulator or on a device connected through a serial cable.At any time you can interrupt the execution by clicking on the button. Then, you enter in thedebug mode in which it is possible to view the call stack or error messages generated by yourapplication, add or remove a breakpoint by pressing the F9 key, inspect variables or resumethe execution, possibly line by line.


2006 EVC Jr. 8

CONTROLES GUI PERSONALIZADOS

First of all, we start by creating a minimal project and add in a user control.

Click on the File menu, then choose the New command, the following dialog box appears:

Choose Minimal Project, just as shown.

The following dialog box appears:


2006 EVC Jr. 9

You can leave all default values. Click the Next button. Do the same for step 2, just click theNext button. Finally to step 3 click the Finish button without changing anything. Now, we havea minimal project with a form. We have to add a UserControl. To do it, find the window calledProject right click on UserControls and choose Add User Control into the contextual menu asshown below:

UserControl1 is now added to your project. You can rename the user control by changing theproperty name UserControl1 for the following name: Enhanced_Label as shown below:

You can also change the frmMain caption property to Enhanced Label Demo.

At this point, the only thing we can expect from our enhanced custom control label is todisplay itself as a blank rectangle on a form.


2006 EVC Jr. 10

To continue, double-click on the Enhanced_Label project item you have just added. This itemis available in the project window:

Just add the following code for our control enhanced label:Private Sub UserControl_Paint() 'Draw the label border Rectangle 0, 0, Width-1, Height-1, hbRectBorderSolid+hbRectFillSolidEnd SubOur new enhanced label control is now created! To test it, draw an occurrence of theenhanced label control onto your main form:

Open the main form and click on the tool box to choose the enhanced label control:

Once the Enhanced Label is selected, draw it on the form and launch the emulator. You cankeep the default name which is Enhanced_Label1. You'll not see anything, except a blankrectangle:


2006 EVC Jr. 11

Our control is a little bit basic, isn't it? So what we are going to do now is to add the ability toset and display a text string into the control

Go back to the Enhanced Label project item (simply double click on it inside the ProjectWindow, User Controls, Enhanced_Label).

At the top of the user control code, we declare a private variable called m_strCaption:

Private m_strCaption As Stringm is for Member, str is for String. This convention is useful to know the type and scope of avariable simply from its name. This variable will contain our string shown into the label control.

We also add two properties procedures into the code:

Public Property Let Caption (ByRef Value as string)End PropertyPublic Property Get Caption () as stringEnd Property

The Let Caption procedure property sets the content of our label's caption. The Get Captionprocedure property allows us to get the current caption of the label. Now we are going toimplement these properties. Add this code into each procedure property:

Public Property Let Caption (ByRef Value as string) m_strCaption = Value RepaintEnd Property

Public Property Get Caption () As String Caption = m_strCaptionEnd Property


2006 EVC Jr. 12

Also, we add this code into the two events control Load and Paint:

Private Sub UserControl_Load() m_strCaption = "Enhanced Label"End SubPrivate Sub UserControl_Paint() 'Draw the label border Rectangle 0, 0, Width-1, Height-1, hbRectBorderSolid+hbRectFillSolid 'Show text in label centered horizontaly and vertically Textout Width/2, Height/2, m_strCaption, hbTextAlignCenter+hbTextAlignVCenterEnd Sub

This is very important here to understand the role of the Load and the Paint events. Load isan event raised when the control is loaded in memory while the Paint event occurs when thecontrol is painted on screen. We define the default value of the caption in the Load event. Thedefault caption will be set to the word Enhanced Label, and will be showed on screen from thePaint event, using the TextOut function. One parameter of the TextOut function is them_strCaption variable which contains our string.

Note that we raise automatically the Paint event by the reserved keyword Repaint called rightafter a change of the property in the Let Caption procedure.

Now we are going to show you how to modify the control's properties programmatically intoour project. Add a button to your application in the main form and set its name property toChange_Caption and its Text property to Change Caption. Edit the code for the click event inthe editor, and write in this code:

Enhanced_Label1.Caption = "Hello"

Now when you tap on the Change Caption button, the caption of the label changes to "Hello".In the emulator, you will get this result:


2006 EVC Jr. 13

If you tap on the button, you should have this result:

How does it works exactly ?

Actually, when you write this instruction:

Label_Enhanced1.Caption = "Hello!"You change the Enhanced_Label Caption property. In the control code you actually make acall to Property Let Caption:

Public Property Let Caption (ByRef Value as string) m_strCaption = Value RepaintEnd PropertyThe private variable m_strCaption is set to the Property Let parameter called Value. Value ispassed to set the new caption for our control and is equal to "Hello!" in this case. Note thatthe member is updated directly, you should always first affect the new value to a privatevariable declared and visible only from the control code (m_strCaption, for instance). Thisallows you to perform checks on the new value before changingthe actual property value.Once m_strCaption is set, we raise immediately the Repaint event from our control.

This event refreshes the control by repainting it on the screen. Since the user control isrepainted, the event UserControl_Paint() is raised, so the control caption will be redrawn withthe new value of m_strCaption

Private Sub UserControl_Paint() 'Show text in label centered horizontaly and vertically Textout Width/2, Height/2, m_strCaption, hbTextAlignCenter+hbTextAlignVCenterEnd Sub


2006 EVC Jr. 14

Additionnaly, suppose that you want to accept only 4 characters and no more for yourcaption, we could add into our Let Property a check before changing the value:

Public Property Let Caption (ByRef Value as string) If len(Value) > 4 then MsgBox "Please enter 4 characters only and no more" Exit Sub Else m_strCaption = Value End ifEnd PropertyAnd, finally, you can get the actual caption property of the control simply by adding thisstatement into your Change_Caption Button event:

MsgBox Enhanced_ Label1.CaptionActually, you call the Get Caption property of our Enhanced_Label:

Public Property Get Caption () As String Caption = m_strCaptionEnd Property>Get Caption simply returns the current caption property of the control which is stored in them_strCaption private variable.

That's all! Once you have assimilated the principle, it's pretty simple to continue our project.Now let's learn how to change the BackColor property of the Enhanced Label

3 - Changing the BackColor property

We will follow exactly the same approach.

Add a member variable called m_lngBackColor in our code control:

Private m_lngBackColor As LongThis variable will contain the Background Color of our enhanced label. Since a color is storedinto a long integer, we had to declare our variable as a long variable, of course.

Also, add this code into the Load event:

Private Sub UserControl_Load() m_strCaption = "Label" m_lngBackcolor = hbColorWhiteEnd SubThis line initializes the label background color to a default color, which is the "white" color inthis example.

Now, add this code to the Paint event:

Private Sub UserControl_Paint()


2006 EVC Jr. 15

Backcolor = m_lngBackcolor 'Draw the label border Rectangle 0, 0, Width-1, Height-1, hbRectBorderSolid+hbRectFillSolid 'Show text in label centered horizontaly and verticaly Textout Width/2, Height/2, m_strCaption, hbTextAlignCenter+hbTextAlignVCenterEnd SubThis statement will paint the control with the color stored into the m_lngBackcolor variable(The white color, for instance) when your control appears on your form. Since theUserControl_Paint event is raised when you draw your control, the m_lngBackcolor memberis initialized with the default background color.

But we also want to change programmatically the background color. So let's add twoproperties, just like we did before to set and get the caption control. However, we now want toset and get the background color of the control, so add those two properties:

Public Property Let BackColorLabel (Byval lngValue As Long) m_lngBackcolor = lngValue RepaintEnd Property

Public Property Get BackColorLabel() As Long BackColorLabel = m_lngBackcolorEnd Property

The Drawing color is defined when you call the BackColorLabel property. For example, drawa new button to your form and set its name to "Change_BackColor". Now open the code of itsClick event and enter exactly the following statement to set the background color of the labelto blue:

Enhanced_Label1.BackColorLabel = hbColorBlue(Note that you can use any color constant to set the background color of the label easily)

Now, when you start the program and click on the button, the following code is executed:

Enhanced_Label1.BackColorLabel = hbColorBlueActually, you call the Let BackColorLabel property, inside the control code and pass thehbColorBlue value to this property. The blue color is, at first, assigned to our member variablem_lngBackcolor:

Public Property Let BackColorLabel (Byval lngValue As Long) m_lngBackcolor = lngValue RepaintEnd PropertyNow, m_lngBackcolor has the value hbColorBlue, the blue color.

Then, since the Repaint statement is called, the Paint event is raised, allowing us toimmediately apply this change to our control by this statement:

Backcolor = m_lngBackcolor"


2006 EVC Jr. 16

the control is repainted on the form with its new blue background color.

Note that the BackColor reserved word is a property inherited from the display class.

Here is the result:

Click on the Change BackColor button, the background color of the label will become blue:

To get the new background color of the control, you can use this statement whenever youwant:

MsgBox Enhanced_Label1.BackColorLabel


2006 EVC Jr. 17

4 - Adding the TextColor property

Now you know how to add properties to our Enhanced Label control and how to change themprogrammatically. What we are going to do now is to add a TextColor property allowing us toget/set the text color of our control.

Open the Enhanced_Label project item and add the following code:

Private m_lngTextcolor As Long

Public Property Let TextColorLabel (Byval lngValue As Long) m_lngTextcolor = lngValue RepaintEnd Property

Public Property Get TextColorLabel () as long TextColorLabel = m_lngTextcolorEnd PropertyAlso, add this line into the Private Sub UserControl_Paint() event handler:

Private Sub UserControl_Paint() 'Change the background color Backcolor = m_lngBackcolor 'Change the text color TextColor = m_lngTextcolor 'Draw the label border Rectangle 0, 0, Width-1, Height-1, hbRectBorderSolid+hbRectFillSolid 'Show text in label centered horizontaly and vertically Textout Width/2, Height/2, m_strCaption, hbTextAlignCenter+hbTextAlignVCenterEnd SubNote that the TextColor reserved word is a property inherited from the Display class.

Now add this other line to the Private Sub UserControl_Load() event handler:

Private Sub UserControl_Load() m_strCaption = "Label" m_lngBackcolor = hbColorWhite m_lngTextcolor = hbColorBlackEnd SubNow you can change the color of the label using a color constant .

Here is an example, you can copy it and paste it in the Click event handler of a button namedChange Text Color to make the text color appear in red:

Enhanced_Label1.TextColorLabel = hbColorRed

When you launch the program you get this result:


2006 EVC Jr. 18

Tap on the Change Text Color button, you will get this result:

Now let's see how to add a new feature allowing us to modify the font used in ourEnhanced_Label control

5 - Adding the FontLabel property

We will add the "FontLabel" property allowing us to get/set the font used for the text inside ourenhanced label control.

Select the Enhanced_Label item in the project explorer, and add the following code:

Private m_lngFontLabel As HbFont


2006 EVC Jr. 19

Public Property Let FontLabel (Byval eFont As HbFont) m_lngFontLabel = eFont RepaintEnd Property

Public Property Get FontLabel () as HbFont FontLabel = m_lngFontLabelEnd PropertyThen, add this statement into the Private Sub UserControl_Paint() event handler:

Private Sub UserControl_Paint() 'Change the background color Backcolor = m_lngBackcolor 'Change the text color TextColor = m_lngTextcolor 'Change the font used for the label DrawFont = m_lngFontLabel 'Draw the label border Rectangle 0, 0, Width-1, Height-1, hbRectBorderSolid+hbRectFillSolid 'Show text in label centered horizontaly and vertically Textout Width/2, Height/2, m_strCaption, hbTextAlignCenter+hbTextAlignVCenterEnd SubNote that the DrawFont reserved word is a property inherited from the Display class.

Now, add this line to the Private Sub UserControl_Load() event handler:

Private Sub UserControl_Load() m_strCaption = "Label" m_lngBackcolor = hbColorWhite m_lngTextcolor = hbColorBlack m_lngFontLabel = hbFontStandardEnd SubNow you can change the font used in our Enhanced Label custom control by setting theFontLabel property using a font constant. Here is an example, you can copy it and paste itinto the Click event handler of a button called Change_Font, to set the font of the label to alarge font:

Enhanced_Label1. FontLabel = hbFontLarge


2006 EVC Jr. 20

When you launch the program, you get this result:

Tap on the Change_Font button, the font is modified and is now larger.

6 - List of the new properties added to the enhanced label control

Property DescriptionCaption Get / Set the text displayed in the labelBackColor Get / Set the background color of the labelTextColor Get / Set the text color of the labelFontLabel Get / Set the font used to draw the label7 - List of color constants


2006 EVC Jr. 21

Constant Value Red Green Blue

hbColorBlack &H00000000 0 0 0

hbColorBlue &H000000FF 0 0 255

hbColorCyan &H0000FFFF 0 255 255

hbColorDarkGray &H00404040 64 64 64

hbColorGray &H00808080 128 128 128

hbColorGreen &H0000FF00 0 255 0

hbColorLightGray &H00C0C0C0 192 192 192

hbColorMagenta &H00FF00FF 255 0 255

hbColorOrange &H00FFC080 255 192 128

hbColorPink &H00FFB0B0 255 176 176

hbColorRed &H00FF0000 255 0 0

hbColorYellow &H00FFFF00 255 255 0

hbColorWhite &H00FFFFFF 255 255 255

8 - List of font constants

hbFontStandard = 0

hbFontBold = 1

hbFontLarge = 2

hbFontLargeBold = 7

hbFontSymbol = 3

hbFontSymbol7 = 5

hbFontSymbol11 = 4


2006 EVC Jr. 22

hbFontLED = 6

9 - The complete source code for the Enhanced Label customcontrol

'============================================================'User control declaration section'============================================================Private m_strCaption As StringPrivate m_lngBackcolor As LongPrivate m_lngTextcolor As LongPrivate m_lngFontLabel As HbFont

'============================================================'Load event handler'============================================================Private Sub UserControl_Load() m_strCaption = "Enhanced Label" m_lngBackcolor = hbColorWhite m_lngTextcolor = hbColorBlack m_lngFontLabel = hbFontStandardEnd Sub

'============================================================'Paint event handler'============================================================Private Sub UserControl_Paint() 'Change the background color Backcolor = m_lngBackcolor 'Change the text color TextColor = m_lngTextcolor 'Change the font used for the label DrawFont = m_lngFontLabel 'Draw the label border Rectangle 0, 0, Width-1, Height-1, hbRectBorderSolid+hbRectFillSolid 'Show text in label center horizontaly and verticaly Textout Width/2, Height/2, m_strCaption, hbTextAlignCenter+hbTextAlignVCenterEnd Sub

'============================================================'Caption property'============================================================Public Property Let Caption(ByRef Value as string) m_strCaption = Value Repaint


2006 EVC Jr. 23

End PropertyPublic Property Get Caption() as String Caption = m_strCaptionEnd Property'============================================================'BackColorLabel property'============================================================Public Property Let BackColorLabel(Byval lngValue As Long) m_lngBackcolor = lngValue RepaintEnd PropertyPublic Property Get BackColorLabel() as long BackColorLabel = m_lngBackcolorEnd Property

'============================================================'TextColorLabel property'============================================================Public Property Let TextColorLabel(Byval lngValue As Long) m_lngTextcolor = lngValue RepaintEnd Property

Public Property Get TextColorLabel() as long TextColorLabel = m_lngTextcolorEnd Property

'============================================================'FontLabel property'============================================================Public Property Let FontLabel(ByVal eFont As HbFont) m_lngFontLabel = eFont RepaintEnd Property

Public Property Get FontLabel()as HbFont FontLabel = m_lngFontLabelEnd Property


2006 EVC Jr. 24

BASES DE DATOS NATIVAS DE PALM OS

How to use databases?Use Recordset objects to add a powerful and fast access to your databases. The Recordsetclass implements all the methods necessary to manipulate a table or a recordset resultingfrom a SQL query, and contains all the common properties and methods used to managedatabases.It works just like Visual Basic®!Private Sub cAddCustomer_Click() dim rsCustomer as new Customers rsCustomer.OpenTable hbModeOpenAlways+hbModeReadWrite rsCustomer.AddNew rsCustomer.Name = "Kevin Smith" rsCustomer.Address = Me.fldAddress.Text rsCustomer.Town = Me.fldTown.Text rsCustomer.ZIP = Me.fldZIP.Text rsCustomer.Country = Me.lstCountry.ItemData(lstCountry.ListIndex) rsCustomer.Update rsCustomer.CloseEnd SubPrivate Sub cSearchCustomerByName_Click() dim rsCustomer as new Customers rsCustomer.OpenRecordset "Name LIKE '" & fldSearch.Text & "*'",hbModeOpenExisting+hbModeReadOnly If rsCustomer.RecordCount > 0 then lstCustomers.Clear rsCustomer.MoveFirst While not rsCustomer.EOF lstCustomers.AddItem rsCustomer.Name, rsCustomer.Customer_ID rsCustomer.MoveNext Wend Else Msgbox "No customer found!",hbMsgBoxInformation End if rsCustomer.CloseEnd Sub

How to use infrared communications?HB++ features several classes enabling programmers to easily manage IR transmissionfunctions. The StreamExg class implements a stream allowing data transfers between twohandheld devices via the Palm OS® Exchange Manager.For example, if you want your application to beam itself to another device, the following linesof code are all you need.Private Sub cSendMe_Click() Dim sExg as new StreamExg sExg.Connect App.Info.Name & ".prc" Write sExg, App.Info sExg.Disconnect


2006 EVC Jr. 25

End Sub

How to manage expansion cards?The StreamFile class allows the manipulation of files stored on external media such as aSecure Digital or MultiMedia cards for example.

Dim v as New VFSVolumeDim s as New StreamFile

v.FindFirstVolumes.Open v.Reference, "/tmp.txt", hbModeWrite+hbModeCreateAlwaysWrite s, "Hello World !"s.Close

Use the StreamFile and the DatabaseInfo classes to copy databases from the handhelddevice memory to a memory card and vice versa. You can easily implement Backup andRestore functionality in a few lines:

Public Function CopyDatabaseToVFS(ByVal iVolRef as Integer, ByRef db as DatabaseInfo)as Integer Dim sf as New StreamFile On Error Goto ERR sf.Open iVolRef, "/" & db.Name & ".prc", hbModeCreateAlways+hbModeReadWrite Write sf, db sf.Close CopyDatabaseToVFS=0 Exit FunctionERR: CopyDatabaseToVFS=Err.NumberEnd Function

Public function RestoreDatabaseFromVFS(ByVal iVolRef as Integer, ByRef sName as String)as Integer Dim di as New DatabaseInfo Dim sf as New StreamFile On error goto ERR sf.Open iVolRef, sName, hbModeOpenExisting+hbModeReadOnly Read sf, di fd.Close Exit FunctionERR: RestoreDatabaseFromVFS=Err.NumberEnd Function

How to use graphics?HB++ provides advanced graphics functions. You will find these functions in the Display classand all the classes deriving from it.


2006 EVC Jr. 26

Using double buffering for fluid graphics and animation without flickering is possible :

Private Sub Form_Paint() me.CopyArea 0,20,160,140,myOffscreenBitmap,0,0End SubNetworkingThe StreamSocket class implements a standard TCP/IP client socket:

Dim objSock as New StreamSocket Dim cmd as String cmd = "GET /MiniBrowser.html HTTP/1.1" & chr(10) & "host: www.handheld-basic.com\n\n" objSock.Connect "www.handheld-basic.com", 80 objSock.Timeout=5000 'send the http query Write objSock, cmd[Len(cmd)] ...You can also use telephony functions to send SMS from a mobile phone connected to yourhandheld.Notifications and Launch codesYou can register various notifcations, in order to implement specific behaviour for yourapplication using the Application class: For example, the following lines tells the system thatyour app have to be launched with a specific Launch code each time a HotSync® operationends or when the device is started up:

RegisterNotify hbNotifySyncFinishEventRegisterNotify hbNotifyEarlyWakeupEventThen, each time the HotSync® operation ends or when the device is started up, the followingmethod will be called:

Private Sub Application_Notify(ByVal eNotify As HbNotify) If eNotify = hbNotifySyncFinishEvent then ' Manage databases operations for example ....

http://www.handheld-basic.com


2006 EVC Jr. 27

End ifEnd SubUsing alarm and reminders is also very easy - Add an alarm to your application just with thefollowing line of code:

App.Alarm=Now()+3600.0/86400.0 'in one hourCustom launch codes can also be used to enable communications between your app andother applications.


2006 EVC Jr. 28

SITIOS ÚTILES

• Manual de HB++ Online: www.handheld-basic.com/documentation/index.html• Descarga de HB++: www.handheld-basic.com/dl_try.php• Tutoriales Interactivos: www.skinnyfrogsoftware.com/tutorial.htm• Fuentes y ejemplos: www.handheld-basic.com/su_samples.php• Foro y comunidad: www.handheld-basic.com/forum• Palm Source: www.palmsource.com

http://www.handheld-basic.com/documentation/index.html

http://www.handheld-basic.com/dl_try.php

http://www.skinnyfrogsoftware.com/tutorial.htm

http://www.handheld-basic.com/su_samples.php

http://www.handheld-basic.com/forum

http://www.palmsource.com


2006 EVC Jr. 29

BIBLIOGRAFÍA

Todos los textos troncales de este tutorial han sido sacados de la página oficial de HB++®.Todos los copyrights y marcas registradas son propiedad de sus respectivos dueños.Este material es solo con fines educativos e informativos.

Documents

Tutorial Hb++