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

Latest Forum Discussions

See All

Aether Gazer unveils Chapter 16 of its m...
After a bit of maintenance, Aether Gazer has released Chapter 16 of its main storyline, titled Night Parade of the Beasts. This big update brings a new character, a special outfit, some special limited-time events, and, of course, an engaging... | Read more »
Challenge those pesky wyverns to a dance...
After recently having you do battle against your foes by wildly flailing Hello Kitty and friends at them, GungHo Online has whipped out another surprising collaboration for Puzzle & Dragons. It is now time to beat your opponents by cha-cha... | Read more »
Pack a magnifying glass and practice you...
Somehow it has already been a year since Torchlight: Infinite launched, and XD Games is celebrating by blending in what sounds like a truly fantastic new update. Fans of Cthulhu rejoice, as Whispering Mist brings some horror elements, and tests... | Read more »
Summon your guild and prepare for war in...
Netmarble is making some pretty big moves with their latest update for Seven Knights Idle Adventure, with a bunch of interesting additions. Two new heroes enter the battle, there are events and bosses abound, and perhaps most interesting, a huge... | Read more »
Make the passage of time your plaything...
While some of us are still waiting for a chance to get our hands on Ash Prime - yes, don’t remind me I could currently buy him this month I’m barely hanging on - Digital Extremes has announced its next anticipated Prime Form for Warframe. Starting... | Read more »
If you can find it and fit through the d...
The holy trinity of amazing company names have come together, to release their equally amazing and adorable mobile game, Hamster Inn. Published by HyperBeard Games, and co-developed by Mum Not Proud and Little Sasquatch Studios, it's time to... | Read more »
Amikin Survival opens for pre-orders on...
Join me on the wonderful trip down the inspiration rabbit hole; much as Palworld seemingly “borrowed” many aspects from the hit Pokemon franchise, it is time for the heavily armed animal survival to also spawn some illegitimate children as Helio... | Read more »
PUBG Mobile teams up with global phenome...
Since launching in 2019, SpyxFamily has exploded to damn near catastrophic popularity, so it was only a matter of time before a mobile game snapped up a collaboration. Enter PUBG Mobile. Until May 12th, players will be able to collect a host of... | Read more »
Embark into the frozen tundra of certain...
Chucklefish, developers of hit action-adventure sandbox game Starbound and owner of one of the cutest logos in gaming, has released their roguelike deck-builder Wildfrost. Created alongside developers Gaziter and Deadpan Games, Wildfrost will... | Read more »
MoreFun Studios has announced Season 4,...
Tension has escalated in the ever-volatile world of Arena Breakout, as your old pal Randall Fisher and bosses Fred and Perrero continue to lob insults and explosives at each other, bringing us to a new phase of warfare. Season 4, Into The Fog of... | Read more »

Price Scanner via MacPrices.net

New today at Apple: Series 9 Watches availabl...
Apple is now offering Certified Refurbished Apple Watch Series 9 models on their online store for up to $80 off MSRP, starting at $339. Each Watch includes Apple’s standard one-year warranty, a new... Read more
The latest Apple iPhone deals from wireless c...
We’ve updated our iPhone Price Tracker with the latest carrier deals on Apple’s iPhone 15 family of smartphones as well as previous models including the iPhone 14, 13, 12, 11, and SE. Use our price... Read more
Boost Mobile will sell you an iPhone 11 for $...
Boost Mobile, an MVNO using AT&T and T-Mobile’s networks, is offering an iPhone 11 for $149.99 when purchased with their $40 Unlimited service plan (12GB of premium data). No trade-in is required... Read more
Free iPhone 15 plus Unlimited service for $60...
Boost Infinite, part of MVNO Boost Mobile using AT&T and T-Mobile’s networks, is offering a free 128GB iPhone 15 for $60 per month including their Unlimited service plan (30GB of premium data).... Read more
$300 off any new iPhone with service at Red P...
Red Pocket Mobile has new Apple iPhones on sale for $300 off MSRP when you switch and open up a new line of service. Red Pocket Mobile is a nationwide MVNO using all the major wireless carrier... Read more
Clearance 13-inch M1 MacBook Airs available a...
Apple has clearance 13″ M1 MacBook Airs, Certified Refurbished, available for $759 for 8-Core CPU/7-Core GPU/256GB models and $929 for 8-Core CPU/8-Core GPU/512GB models. Apple’s one-year warranty is... Read more
Updated Apple MacBook Price Trackers
Our Apple award-winning MacBook Price Trackers are continually updated with the latest information on prices, bundles, and availability for 16″ and 14″ MacBook Pros along with 13″ and 15″ MacBook... Read more
Every model of Apple’s 13-inch M3 MacBook Air...
Best Buy has Apple 13″ MacBook Airs with M3 CPUs in stock and on sale today for $100 off MSRP. Prices start at $999. Their prices are the lowest currently available for new 13″ M3 MacBook Airs among... Read more
Sunday Sale: Apple iPad Magic Keyboards for 1...
Walmart has Apple Magic Keyboards for 12.9″ iPad Pros, in Black, on sale for $150 off MSRP on their online store. Sale price for online orders only, in-store price may vary. Order online and choose... Read more
Apple Watch Ultra 2 now available at Apple fo...
Apple has, for the first time, begun offering Certified Refurbished Apple Watch Ultra 2 models in their online store for $679, or $120 off MSRP. Each Watch includes Apple’s standard one-year warranty... Read more

Jobs Board

DMR Technician - *Apple* /iOS Systems - Haml...
…relevant point-of-need technology self-help aids are available as appropriate. ** Apple Systems Administration** **:** Develops solutions for supporting, deploying, Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
IT Systems Engineer ( *Apple* Platforms) - S...
IT Systems Engineer ( Apple Platforms) at SpaceX Hawthorne, CA SpaceX was founded under the belief that a future where humanity is out exploring the stars is Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.