Programming Visual Basic for the Palm OS

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Over the past five years, the Palm PDA has zoomed to prominence as the handheld device of choice for the consumer and the enterprise. In that time, the Visual Basic developer has been relegated to the sidelines—the Palm doesn't run the Microsoft Windows operating system, and its processor isn't based on a design from Intel. The available development tools mostly favored the C/C++ developer, or they required an individual or corporate investment in a proprietary scripting language.

All that changed when AppForge introduced its flagship product, a VB compiler for the Palm. AppForge calls its product a "family of visual software tools that enables virtually anyone to write engaging GUI software for non-PC computer devices." (In this chapter and throughout this book, when we mention AppForge, we mean the add-in for VB for Palm OS.)

AppForge is an add-in for Microsoft's Visual Basic. With AppForge, developers build applications that execute on the Palm PDA from within the native VB integrated development environment (IDE). Instead of compiling code into a Windows executable, AppForge generates a Palm Resource (PRC) file—roughly speaking, a program file.

From a practical perspective, this means that it is very easy to come up to speed with the AppForge tool. Developers can focus right away on forms and controls, events and procedures, without learning a new development environment.

In this chapter, we take a quick look at what it means to develop software for the Palm handheld device, which is very different from the Windows desktop. We provide an overview of the AppForge product—what it is and how it works. We cover installing AppForge onto a development system, and we explain how it integrates into the VB IDE.

After all that, we'll walk through getting a simple project up and running. Along the way, we'll touch on some things that are different from desktop VB development, such as cross-platform emulation tools and the user interface controls for the Palm.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

If you are reading this book, the chances are high that you are new to Palm software development or to the AppForge product, or very likely both. Writing software for embedded devices—such as the Palm, the Pocket PC, or pagers like the RIM Blackberry—was once the exclusive territory of the professional C developer. Every bit was counted, and every screen pixel hoarded.

This approach is still important—you simply cannot write software for the handheld market as if it were the Windows desktop. Microsoft has been trying that for years with dismal results. Consumers and corporate users do not buy handheld devices for the quality of the Web browser; instead, they want focused tools that enhance personal productivity or enable key business processes, and they want applications that run quickly.

Look in a typical PDA, and you will see organizer software, notepad programs, diet and exercise planners, newsreaders, games and entertainment software, stock applications, and so on. In fact, one of the major reasons for the success of the Palm device is its thousands and thousands of quality software products.

All these successful applications share at least one common factor: they are focused on providing exactly what the user wants, and little else. They do not provide a feature list bloated with nice-to-have features; they do provide timely access to information that really matters—a telephone number, a stock quote, a photograph, or directions to the shopping center.

This book cannot tell you which features are critical to your users and your market—only you can do that. This book will, however, show you when and how to use the available Palm features to structure a program that works well on the handheld device.

If you are completely new to the Palm, you should stop right now and get a book on using the Palm handheld device. This will give you a better foundation for developing software that fits the Palm device. There are many important differences between desktop and Palm development that will force you to rethink the way software is engineered and used.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Before we get down to installing AppForge, let's review the versions of the product. First of all, AppForge supports multiple handheld platforms: the Palm Computing Platform and the Microsoft Pocket PC. In this book, we are only going to cover AppForge for the Palm OS. AppForge for the Palm comes in two flavors: Personal and Professional. We'll look at what comes with each edition, and how each is different.

Both editions ship with the AppForge Visual Basic add-in, which is the compiler. Like Microsoft VB, compiled AppForge programs on the Palm require a runtime component to function—the Booster. This is the equivalent of Msvbvm60.dll, the Microsoft VB Runtime. The Booster for Palm OS is freely available for download and redistribution from the AppForge Web site.

There are costs and benefits associated with the use of the AppForge Booster:

Execution speed: Calling into another layer of code can impact performance. The performance penalty on a Windows machine is trivial, but it can be significant on the low-powered Palm PDA.
Code size: The Booster is large—more than 350 KB of memory. Even though 8 MB of memory is more common now, this is still a big amount.
Shared code: If more than one AppForge application is installed on the Palm PDA, then there is an advantage to using the Booster, because library and common code is not duplicated between applications.
Maintenance: Bug fixes to the common functions in the Booster need only be distributed once to patch all AppForge applications on a Palm PDA.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There are a few prerequisites for installing and using the AppForge compiler. Most importantly, AppForge will only work with Microsoft Visual Basic 6. Fortunately, it will work with just about any flavor of VB—Learning/Working Edition, Professional Edition, or Enterprise Edition.

AppForge requires that Visual Studio Service Pack 4 be applied prior to installation. The service pack is freely downloadable from the Microsoft Visual Studio web site; this is a large download of more than 50 megabytes. AppForge includes the service pack on some of its CD-ROM distributions.

Most Palm users have a version of the Palm Desktop software installed on their computers. From the developer's perspective, the most important components of the Palm Desktop are the installation application and the HotSync manager, which install programs and databases on the Palm PDA. This is usually accomplished using the Palm cradle and a serial connection. The Palm Desktop is not required for development, although having it can simplify the compile-debug-test cycle. The latest version of the Palm Desktop software can be freely downloaded from the Palm web site: http://www.palm.com/software/desktop/.

If you don't have a Palm PDA, don't worry—we cover how to use the Palm Operating System Emulator (POSE) to run your Palm programs later in this chapter. The Emulator is a Windows application that simulates the Palm PDA's hardware and software down to the last detail—even including the Palm VII radio.

Installing AppForge itself is straightforward. There is a license screen that requires a registration key, which you should have obtained with your version of AppForge. If you downloaded an evaluation copy, you can install the software immediately, but you cannot run it until you receive a key from AppForge (usually via email). If you later purchase AppForge, you can apply the new license information from within the product; you do not need to reinstall.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Now that the software is installed, let's look at how to build a Palm PRC program from within VB. Start by launching the VB IDE. Notice that there is now an AppForge project type available from the New Project dialog, as shown in Figure 1-5.

Figure 1-5: New AppForge Project

You might have to scroll the dialog a little to see the AppForge project icon, especially if you have a lot of other project types and wizards installed. Once you select AppForge, you will get another dialog asking you to select a runtime target—Palm OS or Pocket PC. Since this is a book about Palm software development, choose Palm OS.

Alternatively, you can use the Start AppForge menu option that is accessible from the AppForge program group. This starts the VB IDE and brings up a history of recent Palm OS projects, as shown in Figure 1-6. Choose the New Project button, and once again select Palm OS as the runtime target.

Figure 1-6: AppForge project manager

The first thing you will see after creating a new AppForge project is a very small form. Get used to it—that's all there is on the Palm PDA. We'll look into the user interface issues imposed by the Palm's stark 160 x 160 pixel screen in Chapter 2.

We're going to build the simplest possible application, so add the following code to the usual Form1:

Option Explicit

Private Sub Form_Load(  )

    MsgBox "Hello, Hand-held World!"

End Sub

Push F5 to run the program, and note that the form and message box come up. AppForge projects—ingots, database libraries, and all—run almost as well on Windows as on the Palm. With judicious use of conditional compilation, this capability is a great debugging technique. Many of the AppForge tutorial projects use this idea, although we don't stress it in this book.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

In addition to the online documentation, the AppForge installation includes example projects, each of which highlights a specific AppForge feature or function:

Extensibility library: Illustrates how to call another Palm application in AppForge to obtain system-specific information; professional edition only
Palm DB samples: Illustrates how to read and write the native Palm application databases, such as the Address and To-do databases
PDB library: Illustrates how to use most of the AppForge database library calls, including database and record manipulation and sorting
Recipes to go: Illustrates how to build a large, multiform application that supports several databases with categories
Slide: Illustrates simple graphical programming, using the traditional 15-piece puzzle
Unit converter: Illustrates a data-driven application, using the AppForge Database Converter

Even after months of using AppForge, we still find ourselves coming back to the samples to review code snippets. In addition, there is a comprehensive tutorial that is nicely organized into lessons that cover almost all aspects of AppForge development.

The AppForge Developers Sector is an online resource that contains documentation, the knowledge base, and a code library. The knowledge base contains bug reports, fixes, and other technical articles. Of course, it is searchable. The code library contains example applications and techniques posted by both AppForge and members of the development community. See

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Creating Palm applications requires you to consider many different design aspects, as discussed in Chapter 1. The success of your applications, however, will ultimately ride on their usability by the end users, so it is important to understand both the style of a typical Palm application and how to achieve that using Visual Basic and AppForge.

This chapter will explain how to design and develop Palm applications that provide most or all the features common to other Palm applications. The emphasis is on using AppForge ingots to create your user interface and leveraging the libraries provided by AppForge, which give you access to many native Palm functions within Visual Basic. The chapter offers a building block approach, in which we will present several topics and then incorporate them into an application. Where appropriate, we will build on previous examples. However, the goal is to teach you specific concepts and not focus on building a large monolithic application by chapter's end. It is intended that the source code be generic enough that you can cut and paste code into your applications as you see fit. The source code and compiled versions of all examples presented in this chapter are available for download at http://www.oreilly.com/catalog/vbpropalm/.

User interface design is one of the most challenging aspects of Palm programming. Creating a usable interface is the key to user acceptance; if an interface is too hard to work with, people won't use it.

There are many styles of Palm interfaces, especially for custom applications never intended for public distribution. However, style guidelines do exist for the Palm OS, just as they do for Windows programming. Palm has a programming design and style guide posted on their web site that covers some of the topics in this chapter.

Your applications should be designed to provide quick execution and data retrieval, to minimize data entry and provide selection lists where appropriate, to reduce the number of taps to navigate to key screens, and to find data quickly via sorts and filters.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

User interface design is one of the most challenging aspects of Palm programming. Creating a usable interface is the key to user acceptance; if an interface is too hard to work with, people won't use it.

There are many styles of Palm interfaces, especially for custom applications never intended for public distribution. However, style guidelines do exist for the Palm OS, just as they do for Windows programming. Palm has a programming design and style guide posted on their web site that covers some of the topics in this chapter.

Your applications should be designed to provide quick execution and data retrieval, to minimize data entry and provide selection lists where appropriate, to reduce the number of taps to navigate to key screens, and to find data quickly via sorts and filters.

Time is critical to Palm users, since they often need to keep up with external activities such as conversations while they look up an address, enter a new phone number, or jot down a quick note.

You also want your interface to operate in a similar fashion to other Palm applications, thus providing the user with a common look, feel, and operation. Let's review some of the basic user interface (UI) elements and how they can be used to achieve these goals.

Your basic application layout will usually have a title bar, an application workspace, and operation buttons along the bottom. This screen is sometimes referred to as the base screen. The following list provides more information about the elements in the base screen.

Title/information bar: You should put either the application name or some other pertinent information based on the application context in the upper left of the screen. Figure 2-1 shows the Palm scheduler application with the title set to the current day being viewed. This title changes based on the currently selected view format. This area could also be used for quick navigation controls (in this case, day and week navigation push buttons). This is also where an application menu bar will reside. Menus on the Palm are normally hidden to save space and are usually displayed by tapping the title bar tab or the silkscreen menu button. The typical height of the menu bar is 15 pixels.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Our first application's purpose will be to set up a typical base window with a title bar and a command button. Our goals for this application are to:

Introduce the Shape, Label, and Command button ingots
Compile and run in Visual Basic
Generate a PRC file and run it on a Palm device

Start by opening an AppForge project in Visual Basic. Your first form, like regular Visual Basic applications, will be autogenerated. What you will see is a form that's 160 x 160 pixels in size, with a blank title bar. Of course, Windows-style title bars do not exist in the Palm OS. This title bar is there to provide you with a means to drag the window around your desktop and close the form if you are test-running it in the Visual Basic IDE. This size and color of the title bar provide a common foundation for developing forms for the typical Palm or Pocket PC device that match the actual screen size of those devices. Change the name to frmBase.

The next step is to add a title bar that is common to almost all Palm applications. There are two methods to produce a title bar, custom or automatic. First, let's look at creating a custom title bar. There are only a few reasons why you may want to create your own custom title bar, and you'll most likely find that letting AppForge create it automatically will meet your needs. But it's worth a quick review just in case you do want to create your own. (Automatic title bar creation was introduced in AppForge version 2.0.) We are going to create our title bar by using a label and two Shape ingot controls. You may be wondering why you need to use so many controls, but remember, you are responsible for painting everything you see on the screen. As we stated previously, the standard height for a title bar is 15 pixels, so we can create our title bar using the following method. Other methods are possible, such as using a graphic ingot, but the method we'll use produces an exact replica of a title bar that has no overlapping controls (an issue discussed in the next section) and that takes up less memory that a graphic ingot and its associated external graphic.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The Palm OS is considerably different from the Windows OS in many aspects. Its underlying structure, memory model, and data storage are radically different and require an "application abstraction layer" to provide easier access to the underlying OS. This abstraction layer is provided to the VB programmer via the AppForge libraries. These libraries provide access to native Palm OS functions, including complete support for creating and maintaining Palm databases.

There is considerable support for the VB language constructs. However, there also has been a conscious effort to increase application efficiency by limiting or eliminating (i.e., ignoring) certain aspects of VB by the AppForge compiler. There are many reasons for this, but they are related to the sheer fact that mobile handheld devices are limited by available power. Applications that require the device to perform resource-intensive processes, such as continually accessing RAM, will draw more power than usual. Another power-limiting factor is the use of slower processors to conserve energy. Consequently, some Windows features were either optimized to provide satisfactory response times or were eliminated altogether.

In this section, we will cover the Visual Basic functionality that is not supported by the AppForge compiler.

Section 2.3.1.1: Object support

AppForge does allow the creation of user-defined classes (i.e., class modules), using the New keyword in the Dim statement. You can also create object references to the libraries and ingots provided by AppForge, but you cannot create new ingots. No external references can be made to other objects and, as you may have guessed, the CreateObject method is not available (since it attempts to create an ActiveX object, which is obviously not supported by the Palm OS).

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

Palm programs, like other programs, typically use some form of persistent data storage. In Chapter 2, we examined how to access the application preferences database to store and retrieve state information, but this form of storage is best suited for small amounts of data. The Palm database manager is the tool of choice for an application's working data.

In this chapter, we first explain what the Palm OS database manager is and how it works. We'll look at the different types of databases the Palm supports, and explain the physical layout and characteristics of the most common database—the Palm data file (PDB).

Then we show you how to access the Palm database features via the AppForge PDB library, which provides all the functionality needed to create and manipulate databases and records. We introduce many of the database features with snippets of code showing how the library is used. We also explain the AppForge database schema extensions, which free you from many bookkeeping chores normally associated with Palm database programming.

Next, we cover a very useful AppForge database tool: the Database Converter. This Windows program converts Microsoft Access databases into Palm PDB files for use in your applications.

Finally, we provide an example application that reinforces the material introduced both in Chapter 2 and in this chapter. We have migrated parts of the North Wind Traders Inventory application—a standard example program distributed by Microsoft—to the Palm device to show how to support some business functions on the Palm device.

The North Wind application also introduces the AppForge Grid ingot, which is a powerful method for displaying record data.

There are two main types of databases in the Palm OS:

Palm Record Database (PDB): This is a record-oriented database that is used to store application data.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

There are two main types of databases in the Palm OS:

Palm Record Database (PDB): This is a record-oriented database that is used to store application data.
Palm Resource Database (PRC): This database is similar to the PDB, but stores application code and Palm OS resources. Palm applications themselves are PRC files.

This chapter focuses on the Palm Record databases, which are the main data repositories on the Palm device. It is important to recognize that Palm databases have different physical implementations, depending if they are on the desktop or on the Palm device. The PDB is stored on the desktop as a normal disk file, with a well-defined format. Once uploaded to the Palm device, the PDB has a proprietary in-memory format, since the Palm OS does not support a filesystem. Instead, the database is organized as blocks of memory under the control of the Palm database and resource manager, which prevents direct programmer access to these structures. Most databases are slightly larger than their file size when stored on the Palm device due to the addition of control information by the memory manager.

Let's look at the logical structure of the Palm database (see Figure 3-1). The database consists of a fixed header block, a variable-length list of record location entries, and optional application and sort information blocks, followed by the physical data pages. The structure is essentially an Indexed Sequential Access Method (ISAM) database, where the record entry section contains indexes (pointers) to the actual record data blocks. The SortInfo block can also contain a pointer to the records to maintain a logical sorting, distinct from the physical record order.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The Palm database provides a straightforward and efficient mechanism to store application data. In fact, it is the only way to store large amounts of data on the device because the Palm OS lacks a true filesystem.

AppForge provides the PDB library to encapsulate and extend the Palm database manager. Because the PDB library is implemented as a Microsoft COM component, you use it by adding a reference to afPDBLib.dll to your VB project. The PDB library is simple to use. Its methods can be broken into the following groups, which we will explain in turn:

Database management: Performs functions such as creating new databases dynamically, with or without schemas, opening and closing existing databases, and deleting databases
Record management: Handles most record operations, such as creating, editing, and deleting, as well as record categories
Navigation: Covers moving between records in the database, as well as finding and sorting functions
Other functions: Handles reporting or changing the state of a database or record via specified attributes, as well as record counts and database error information

It is easy to create a database, either programmatically, with code, or by converting from an existing database into a Palm database, with the following techniques:

Use the AppForge PDB library in a Palm VB application to create an empty database directly on the Palm device

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

In this chapter, we've looked at how to create and manipulate a database programmatically, but we've ignored the issue of content—how do you get desktop data into the PDB? Typically, you accomplish this by using the HotSync process, with a custom conduit for your database, or with a conversion program developed specifically for your application.

There is an easier way: the AppForge Database Converter. This is a simple tool that moves existing data from the Windows desktop into Palm databases. This tool will create the PDB, populate its records, and generate VB source code that contains the Creator ID and Type ID, the record schema, and functions to read and write records.

The Database Converter requires its input to be in Microsoft Access format; it translates the internal tables into individual Palm PDB files. This is not as restrictive as it sounds, for it is possible to convert almost any data source into an Access MDB file or link table.

The conversion is an excellent time to think about what information really needs to be transferred. If your Windows desktop database has information that will not be relevant to the user, filter it out before it gets to the Palm device. The more data on the handheld, the slower the handheld will run.

Once the information is in a Microsoft Access database, you must ensure that the tables to be converted to the Palm have supported data types. Table 3-9 shows how each MS Access data type is converted.

Table 3-9: Supported MS Access data type conversions
MS Access types	PDB field type	Manual alternate
Text

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The primary resource is the AppForge PDB library reference, which is part of the product. The reference is also available on the AppForge web site at http://www.appforge.com/dev/usersguide.html. The Palm File Format Specification, which describes the layout of databases in great detail, is available from Palm at http://www.palmos.com/dev/tech/docs/.

AppForge also provides sample applications that read and write the main Palm native application databases, such as Address Book and To-Do. These are distributed with the product.

There are also some excellent third-party tools that are invaluable for debugging; these provide the ability to explore and modify the attributes and contents of databases and records on the Palm device. Popular examples are Z'Catalog and Insider. Both are shareware products that are readily available on the Internet.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·Buy PDF of this chapter|Buy reprint rights for this chapter

The original concept of the Palm was of a device tethered to data on the desktop. The PDA is an extension of the desktop, not its replacement. 3Com (the Palm PDA manufacturer) has expanded this design concept; it now calls the Palm device the "connected organizer." Palm wants you to build applications that function in today's mobile and connected world.

In this chapter, we look at building conduits using Microsoft Visual Basic (VB). Conceptually, a conduit is the tether that moves data back and forth, connecting your Palm application and its data store. A conduit is a piece of software that runs on the desktop when the PDA is synchronizing, under the control of the Palm HotSync manager. In this book, we are going to build conduits using VB and ActiveX.

By design, a conduit is dedicated to a single Palm application, which will have one or more associated Palm databases. Keep in mind that, even though the conduit is a piece of desktop software, the application data may be located anywhere—on the desktop, in a relational database, or even on the Internet. Once you have decided where your application's data resides, it is then your responsibility to build a conduit capable of delivering that data to the Palm device. The Palm Conduit Development Kit provides a framework for ActiveX conduit development, which we'll explain in detail later in this chapter.

Note that conduits developed in VB can be used with any application and database on the PDA, not only those created with AppForge. The high-level HotSync architecture is shown in Figure 4-1.

Figure 4-1: Overview of HotSync COM architecture

The Palm HotSync manager is in control of the synchronization process. It maintains a list of configured conduits in the system registry, and it handles the interface with the Palm PDA. The HotSync manager uses a set of COM objects—the Sync Suite API—to communicate with ActiveX conduits. The conduit manages application-specific data and supplies a userinterface if appropriate.

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Content preview·|Buy reprint rights for this chapter

Before we get to the mechanics of conduit development, let's review the concept of data synchronization as it applies to Palm applications and databases. If the handheld is an extension of the desktop, then it is natural to ask: How should the data flow between the handheld and the desktop? This is going to depend in great deal on the design and purpose of your application and its databases.

Entertainment or utility programs rarely have a conduit—they don't have data worth moving to the desktop. These applications usually save any data in the system Preferences database, which is automatically backed up and restored by the HotSync manager. We covered application preferences in Chapter 3.

More typical is the unidirectional conduit, in which the data flows from the Palm device to the desktop, or the other way around. This type of conduit is useful in applications like questionnaires, where the Palm is used primarily as a remote data collection tool.

The Palm PDA's native applications, like Address and To-Do, use a mirror-image conduit, where changes on the desktop and the device are replicated in both directions. This type of synchronization is so important that Palm has documented exactly how a mirror-image conduit should behave. We will cover mirror-image synchronization in detail later in this chapter.

A transactional conduit processes data to produce intermediate results, which are written back to the Palm device. The data flow in a transactional conduit can be in one or both directions. You could implement this sort of conduit for an application that uploads orders to a SQL database for fulfillment processing and then downloads invoices to the Palm. We discuss this type of conduit in Chapter 5.

Finally, there are system functions such as installation and backup that use special- purpose conduits to perform their functions. The default backup conduit synchronizes databases whose applications don't have a custom conduit, or databases that have a conduit but whose type is not

Additional content appearing in this section has been removed.
Purchase this book now or read it online at Safari to get the whole thing!

Table of Contents

Section 2.3.1.1: Object support