TweetFollow Us on Twitter

TicTacPalm 2

Volume Number: 19 (2003)
Issue Number: 1
Column Tag: Handheld Technologies

TicTacPalm 2

Saving Data in a Palm OS Application

by Danny Swarzman

Introduction

In a previous article ("TicTacPalm: Getting Started with Palm OS" in MacTech April, 2002), I presented a basic Palm OS application for a person to play Tic-Tac-Toe against the handheld computer. That article presented the structure of an application and the elements of the user interface. Here, we'll go one step further, adding the ability to save and restore documents.

On the Palm OS, each application can have one or more databases associated with it. Our sample application has only one database. Each record in the database is a game record. The user can review and modify saved games. This article shows how to save and restore game records. A future article will show how the game data can be transferred to a desktop computer.

The Application

TicTacPalm has three forms, a main game board form, a game list form, and game info form. The main form of the application is used both to enter new moves into a game and to review a game record. We use tape-recorder style buttons to review a game, moving forward or backwards. They are visible or hidden as needed. Figure 1 shows the board when reviewing a game.


Figure 1: The Game Board Form

The game list form has a scrolling list of names of games. The user selects a game to open or taps the New button to start a fresh game. (See Figure 2.) As you can see, there are buttons to open a game and to delete a game.


Figure 2: Game List Form

When the user deletes a game, the record doesn't completely disappear from the database. Instead, the record is marked for deletion. The record is eliminated when the next Hot Sync occurs. (We'll discuss this in greater detail in another article -- about conduits.)

In the game info form, the user enters the name that is to be associated with the game. The name doesn't need to be unique. The program distinguishes between games according to a record number.


Figure 3: Game Info Form

When the user taps OK in this form, control returns to the game board.

Figure 4 shows how the buttons can be used to navigate among the various forms. Menus could have been used instead of buttons. Menus require more effort to use, but they are needed when the application is more complex.


Figure 4: Links Among Forms

Databases

Creator and Type

A database on the Palm OS is a set of records associated with a creator and type. A creator is the 32-bit code corresponding to the application. An application can have several databases. The type is another 32-bit code that an application can use to distinguish among its databases.

Records

A record can be any size up to 64k bytes. Applications in which documents are larger must segment the documents. Palm OS does have a file system, which uses the Data Manager and is not particularly fast. Each record has flags that are maintained by the Data Manager and accessed through Data Manager functions.

  • The delete flag indicates that the user has deleted a record on the Palm OS device. When Hot Sync is performed, the file will be deleted on the desktop machine and finally be eliminated from the Palm OS device.

  • The dirty flag indicates that the record has been modified since the last Hot Sync.

  • The busy flag locks a record for writing.

  • The secret flag is cleared only when the user password has been entered.

Game Records

A program can open a record for reading. It can access it directly, as if it was just another chunk of memory. To write to a record, the application opens the record for writing. To do the actual writing, it calls a Data Manager routine to copy from another memory chunk to the record.

In this application, when a record is read, its data are copied into a CTicTacGame object. Data are written copying from a CTicTacGame object. When a game is opened, the board is displayed with the position as it was when the game was last closed.

CTicTacDatabase

This class handles the database access for the application. The declaration appears in Listing 1. It handles only one database.

Listing 1: Declaration of CTicTacDatabase

CTicTacDatabase
class   CTicTacDatabase
{
protected:
   class CTicTacGame *mGame;
   static DmOpenRef sOpenRef;
public:
      
   static Boolean Open();
   static void Close();
   static UInt16 Count();
   static void GetGame ( Int16 inRecordNumber,
            CTicTacGame *outGame);
   static void SetGame ( Int16 inRecordNumber,
            CTicTacGame *inGame);
   static Int16 Add ( CTicTacGame *inGame );
   static void Delete ( Int16 inRecordNumber );
   CTicTacDatabase ();
   virtual ~CTicTacDatabase ();
   
};

Listing 2 shows the functions to save and retrieve the current game.

Listing 2: Definition of ::GetGame and ::SetGame

CTicTacDatabase

void CTicTacDatabase :: GetGame ( Int16 inRecordNumber,
            CTicTacGame *outGame )
{
   // Open the database
   if ( Open() )
   {
      // Get the numbered record and lock it
      MemHandle dataHandle = DmGetRecord ( sOpenRef, 
            inRecordNumber );
      MemPtr dataPointer = MemHandleLock ( dataHandle );
      
      // Copy the data
      MemMove ( (void*)outGame, dataPointer, sizeof ( CTicTacGame ) );
      
      // Unlock release the record
      MemHandleUnlock ( dataHandle );
      DmReleaseRecord ( sOpenRef, inRecordNumber, false );
      // Close the database
      Close();
   }
   else
      outGame->Clear();
}
void CTicTacDatabase :: SetGame ( Int16 inRecordNumber,
   CTicTacGame *inGame )
{
   // Open the database
   if ( Open() )
   {
      // Get the numbered record and lock it
      MemHandle dataHandle = DmGetRecord ( sOpenRef, inRecordNumber );
      MemPtr dataPointer = MemHandleLock ( dataHandle );
      // Copy the data
      DmWrite ( dataPointer, 0, inGame, sizeof ( CTicTacGame ) );
      // Unlock release the record
      MemHandleUnlock ( dataHandle );
      DmReleaseRecord ( sOpenRef, inRecordNumber, true );
      Close();
   }
}

Preferences

The word preferences is a little misleading. This means that the data that is used to store information that the application needs to restore its state. Each time the user switches to a new application, the newly opened application needs to start where it left off the last time the user switched out of it.

For example, suppose the user switches out of the application while the Game Info form is displayed. The user may have been in the process of entering a new name. This partially entered new game name needs to reappear when the application is opened again. The case is similar for a selection made in the scrolling list in the Game List form. Let's see how this occurs.

CTicTacPreferences

The state of the current game is preserved in the application database when the application is switched out. This includes the state of the game. Listing 3 shows the declaration for the application task to deal with preferences.

Listing 3: Declaration of CTicTacPreferences

CTicTacPreferences
class   CTicTacPreferences 
{
protected:
   static CTicTacPreferences *sPreferences;
   struct PreferencesRecord
   {
      Int16 mCurrentRecord;
      Int16 mSelectedRecord;
      Int16 mLastFormID;
      GameNameType mUnconfirmedName;
   };
   PreferencesRecord mPreferencesRecord;
public:
   CTicTacPreferences();
   ~CTicTacPreferences();
   static Int16 GetCurrentRecord();
   static void SetCurrentRecord ( Int16 inRecord );
   static Int16 GetSelectedRecord();
   static void SetSelectedRecord ( Int16 inRecord );
   static Int16 GetLastForm();
   static void SetLastForm ( Int16 inFormID );
   static void GetUnconfirmedName ( GameNameType outGame );
   static void SetUnconfirmedName ( GameNameType inGame );   
};

Sequence of Events

When the user activates another application, the system sends an appStopEvent to the current application. The main event loop picks up the event and exits. Control goes back to TicTacPalmMain, which calls AppStop. AppStop closes the active forms. As each form is closed, a frmCloseEvent is sent to it.

AppStop is defined in Listing 4. The function first closes all forms and deletes the CTicTacPreferences object. Then it deletes the objects that handle user action. As each form is deleted, a frmCloseEvent is generated. The handler for the form saves the current state of the form in the preferences data. Then, when AppStop deletes the preferences, the preference data are written to disk.

Listing 4: Definition of AppStop

AppStop
static void AppStop(void)
{
   // Make sure the fields in each form are saved.
   FrmCloseAllForms ();
   
   if ( fPreferences )
   {
      delete fPreferences;
   }
   
   // Destroy the wrapper objects for forms.
   if ( fGameBoardForm )
   {
      delete fGameBoardForm;
      fGameBoardForm = NULL;
   }
   if ( fGameInfoForm )
   {
      delete fGameInfoForm;
      fGameInfoForm = NULL;
   }
   if ( fGameListForm )
   {
      delete fGameListForm;
      fGameListForm = NULL;
   }
}

CGameInfoForm::Close

When the system executes FrmCloseAllForms, the system sends a close event to each form. This event will be processed by the Close function for the Game Info form. That function, shown in Listing 5, saves the partially entered game name in the preferences.

Listing 5: Definition of ::Close

CGameInfoForm::Close
Boolean CGameInfoForm :: Close()
{
   GameNameType name;
   GetFieldText ( GameInfoNameFieldField, name );
   CTicTacPreferences :: SetUnconfirmedName ( name );
   // Return false to tell the OS to clean up the form
   // in the usual way after we have extracted the info.
   return false;
}

CTicTacPreferences Destructor

When the data in the CTicTacPreferences object are up-to-date, AppStop calls the destructor for the preferences object, which then stores its data, as shown in Listing 6.

Listing 5: Destructor for CTicTacPreferences

CTicTacPreferences::~CTicTacPreferences
CTicTacPreferences ::   ~CTicTacPreferences( )
{
   Boolean saved = true; // To be backed up at HotSync
   void *data = (void*)&mPreferencesRecord;
   UInt16 dataSize = sizeof ( PreferencesRecord );
   PrefSetAppPreferences (appFileCreator, appPrefID, 
            appPrefVersionNum, data, dataSize, saved );
   sPreferences = NULL;
}

Conclusion

Storing application data is relatively easy on the Palm OS, as long as the data takes less than 64k. Restoring the state of the application using Preferences data requires some thought. Both would be easier if there were an application framework to handle the messy details.

References and Credits

The Palm web site contains tons of information and links to related sites: http://www.palmos.com/dev/.

Thanks to Victoria Leonard for graphic resources. Thanks to Bob Ackerman, Mark Terry and Victoria Leonard for reviewing the text.


Danny Swarzman writes programs in JavaScript, Java, C++, and other languages. He also plays Go and grows potatoes. You can contact him with comments and job offers at dannys@stowlake.com, or you can visit his web site at http://www.stowlake.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

OmniOutliner Pro 4.2 - Pro version of th...
OmniOutliner Pro is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
VLC Media Player 2.2.1 - Popular multime...
VLC Media Player is a highly portable multimedia player for various audio and video formats (MPEG-1, MPEG-2, MPEG-4, DivX, MP3, OGG, ...) as well as DVDs, VCDs, and various streaming protocols. It... Read more
Nisus Writer Pro 2.1.1 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
Tinderbox 6.2.0 - Store and organize you...
Tinderbox is a personal content management assistant. It stores your notes, ideas, and plans. It can help you organize and understand them. And Tinderbox helps you share ideas through Web journals... Read more
OmniOutliner 4.2 - Organize your ideas,...
OmniOutliner is a flexible program for creating, collecting, and organizing information. Give your creativity a kick start by using an application that's actually designed to help you think. It's... Read more
Things 2.5.4 - Elegant personal task man...
Things is a task management solution that helps to organize your tasks in an elegant and intuitive way. Things combines powerful features with simplicity through the use of tags and its intelligent... Read more
NeoOffice 2014.10 - Mac-tailored, OpenOf...
NeoOffice is a complete office suite for OS X. With NeoOffice, users can view, edit, and save OpenOffice documents, PDF files, and most Microsoft Word, Excel, and PowerPoint documents. NeoOffice 3.x... Read more
iPhoto Library Manager 4.2 - Manage mult...
iPhoto Library Manager allows you to organize your photos among multiple iPhoto libraries, rather than having to store all of your photos in one giant library. You can browse the photos in all your... Read more
Web Snapper 3.3.8 - Capture entire Web p...
Web Snapper lets you capture Web pages exactly as they appear in your browser. You can send them to a file as images or vector-based, multi-page PDFs. It captures the whole Web page - eliminating the... Read more
TeamViewer 10.0.41404 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds, or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for... Read more

Chainsaw Warrior: Lords of the Night has...
It's time to put the Darkness back in its place now that Chainsaw Warrior: Lords of the Night has officially made it to iOS. | Read more »
A World of Ice and Fire Lets You Stalk 2...
George R. R. Martin’s A World of Ice and Fire, by Random House, is a mobile guide to the epic series. The new update gives you the Journeys map feture that will let you track the movements of 25 different characters. But don't worry, you can protect... | Read more »
Gameloft Announces Battle Odyssey, a New...
Battle Odyssey, Gameloft's newest puzzle RPG, is coming to the App Store next week. Set in the world of Pondera, you will need to control the power of the elements to defend the world from evil. You'll be able to entlist over 500 allies to aid you... | Read more »
Fusion - HDR Camera (Photography)
Fusion - HDR Camera 1.0.0 Device: iOS Universal Category: Photography Price: $1.99, Version: 1.0.0 (iTunes) Description: Fusion creates HDR (high dynamic range) photos by capturing different exposures and then combining them into one... | Read more »
Sago Mini Toolbox (Education)
Sago Mini Toolbox 1.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.1 (iTunes) Description: Come build with the Sago Mini friends! Use a wrench, try a saw, or hammer some nails. From sewing hand puppets to... | Read more »
You Should Probably Grab Hitman GO While...
Hitman GO is a surprisingly cool (yet also incredibly drastic) departure from the Hitman series. It's well worth playing for any puzzle game fans out there, and at the moment you can get your hands - or garrotte if you will - on it for a mere $0.99... | Read more »
IFTTT is Bringing Do Button and Do Note...
IFTTT has announced Do Button and Do Note for the Apple Watch. Do Button lets you make your own personalized button that can connect to things like your Google Drive, control the temperature in your home with Nest Thermostat, or turn the lights on... | Read more »
How Many Days, Hours, and Minutes Are Le...
Countdown, by Yves Tscherry, is now available on the App Store. The app keeps track of countdowns to your favorite things such as someones birthday or days till the New Year. You can display the time in seconds, minutes, hours, days, weeks, months,... | Read more »
The All-New Misfit 2.0 App is Available...
Misfit has just given their app a complete overhaul. Misfit 2.0 now has a brand new interface with a sleek design and is easier to navigate. You'll be able to sync your Misfit device and look up health and fitness information faster than ever before... | Read more »
Halo: Spartan Strike (Games)
Halo: Spartan Strike 1.0 Device: iOS Universal Category: Games Price: $5.99, Version: 1.0 (iTunes) Description: Delve into 30 challenging missions through cities and jungles using a devastating arsenal of weapons, abilities and... | Read more »

Price Scanner via MacPrices.net

TigerText Introduces First Secure Enterprise...
TigerText, a provider of secure, real-time messaging for the enterprise, has announced the launch of TigerText for the Apple Watch. TigerText for the Apple Watch enables users to securely send and... Read more
The Conservation Fund Partners with Apple To...
The Conservation Fund has announced that it will partner with Apple to help protect working forests in the United States. The Apple initiative will conserve more than 36,000 acres of working... Read more
Clearance 13-inch 2.6GHz Retina MacBook Pro a...
B&H Photo has clearance 2014 13″ 2.6GHz/128GB Retina MacBook Pros now available for $1099, or $200 off original MSRP. Shipping is free, and B&H charges NY sales tax only. Read more
Apple refurbished 2014 13-inch Retina MacBook...
The Apple Store has Apple Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and... Read more
iMacs on sale for up to $205 off MSRP, NY tax...
B&H Photo has 21″ and 27″ iMacs on sale for up to $205 off MSRP including free shipping plus NY sales tax only: - 21″ 1.4GHz iMac: $1019 $80 off - 21″ 2.7GHz iMac: $1189 $110 off - 21″ 2.9GHz... Read more
Sale! 16GB iPhone 5S for $1 with service
Best Buy is offering 16GB iPhone 5Ss for $1.00 with 2-year activation at a participating cellular provider. Choose free home shipping and activation, or buy online and activate during in-store pickup... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available starting at $679. An Apple one-year warranty is included with each MacBook, and shipping is free. These are currently the... Read more
27-inch 3.5GHz 5K iMac on sale for $2349, sav...
 Adorama has the 27″ 3.5GHz 5K iMac in stock today and on sale for $2349 including free shipping plus NY & NJ sales tax only. Their price is $150 off MSRP. For a limited time, Adorama will... Read more
Save up to $380 on an iMac with Apple refurbi...
The Apple Store has Apple Certified Refurbished iMacs available for up to $380 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $2119 $... Read more
iFixIt Teardown Awards 12-IInch Retina MacBoo...
iFixIt has posted its illustrated teardown of the new 12-inch MacBook Retina. They note that this new MacBook is less than half the thickness of the last Apple notebook called just “MacBook” back in... Read more

Jobs Board

*Apple* Watch SW Application Project Manager...
**Job Summary** The Apple Watch software team is looking for an Application Engineering Project Manager to work on new projects for Apple . The successful candidate Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Technical Project Manager - *Apple* Pay - A...
**Job Summary** Apple Pay is seeking an experienced technical PM to…manage the on boarding of new merchants for the Apple Pay platform in the US Within this role you Read more
Senior Identity Architect - *Apple* Pay - A...
**Job Summary** Apple , Inc. is looking for a highly motivated, innovative and hands-on senior identity architect to join the Apple Pay Engineering team. You will Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.