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

GraphicConverter 10.5.1 - $39.95
GraphicConverter is an all-purpose image-editing program that can import 200 different graphic-based formats, edit the image, and export it to any of 80 available file formats. The high-end editing... Read more
Delicious Library 3.7 - Import, browse a...
Delicious Library allows you to import, browse, and share all your books, movies, music, and video games with Delicious Library. Run your very own library from your home or office using our... Read more
Adobe Animate CC 2017 18.0.0.107 - Anima...
Animate CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Flash Professional customer). Animate CC 2018 (was Flash CC) lets you... Read more
Adobe After Effects CC 2018 15.0 - Creat...
After Effects CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous After Effects customer). The new, more connected After Effects CC... Read more
Adobe Premiere Pro CC 2018 12.0.0 - Digi...
Premiere Pro CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Premiere Pro customer). Adobe Premiere Pro CC 2018 lets you edit... Read more
Alarm Clock Pro 10.3 - $19.95
Alarm Clock Pro isn't just an ordinary alarm clock. Use it to wake you up in the morning, send and compose e-mails, remind you of appointments, randomize the iTunes selection, control an internet... Read more
Adobe Lightroom 20170919-1412-ccb76bd] -...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more
Adobe Illustrator CC 2018 22.0.0 - Profe...
Illustrator CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous Illustrator customer). Adobe Illustrator CC 2018 is the industry... Read more
Hopper Disassembler 4.3.0- - Binary disa...
Hopper Disassembler is a binary disassembler, decompiler, and debugger for 32- and 64-bit executables. It will let you disassemble any binary you want, and provide you all the information about its... Read more
Adobe InDesign CC 2018 13.0.0.125 - Prof...
InDesign CC 2018 is available as part of Adobe Creative Cloud for as little as $19.99/month (or $9.99/month if you're a previous InDesign customer). Adobe InDesign CC 2018 is part of Creative Cloud.... Read more

ICEY (Games)
ICEY 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: ICEY is a 2D side-scrolling action game. As you follow the narrator's omnipresent voice, you will see through ICEY's eyes and learn the... | Read more »
The best new games we played this week -...
We've made it, folks. Another weekend is upon us. It's time to sit back and relax with the best new releases of the week. Puzzles, strategy RPGs, and arcade games abound this week. There's a lot of quality stuff to unpack this week, so let's hop... | Read more »
Wheels of Aurelia (Games)
Wheels of Aurelia 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: | Read more »
Halcyon 6: Starbase Commander guide - ti...
Halcyon 6 is a well-loved indie RPG with stellar tactical combat and some pretty good writing, too. It's now landed on the App Store, so mobile fans, if you're itching for a good intergalactic adventure, here's your game. Being a strategy RPG, the... | Read more »
Game of Thrones: Conquest guide - how to...
Fans of base building games might be excited to know that yet another entry in the genre has materialized - Game of Thrones: Conquest. Yes, you can now join the many kingdoms of the famed book series, or create your own, as you try to conquer... | Read more »
Halcyon 6: Starbase Commander (Games)
Halcyon 6: Starbase Commander 1.4.2.0 Device: iOS Universal Category: Games Price: $6.99, Version: 1.4.2.0 (iTunes) Description: An epic space strategy RPG with base building, deep tactical combat, crew management, alien diplomacy,... | Read more »
Legacy of Discord celebrates its 1 year...
It’s been a thrilling first year for fans of Legacy of Discord, the stunning PvP dungeon-crawling ARPG from YOOZOO Games, and now it’s time to celebrate the game’s first anniversary. The developers are amping up the festivities with some exciting... | Read more »
3 reasons to play Thunder Armada - the n...
The bygone days of the Battleship board game might have past, but naval combat simulators still find an audience on mobile. Thunder Armada is Chinese developer Chyogames latest entry into the genre, drawing inspiration from the explosive exchanges... | Read more »
Experience a full 3D fantasy MMORPG, as...
Those hoping to sink their teeth into a meaty hack and slash RPG that encourages you to fight with others might want to check out EZFun’s new Eternity Guardians. Available to download for iOS and Android, Eternity Guardians is an MMORPG that lets... | Read more »
Warhammer Quest 2 (Games)
Warhammer Quest 2 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dungeon adventures in the Warhammer World are back! | Read more »

Price Scanner via MacPrices.net

9″ iPads on sale for $30 off, starting at $29...
MacMall has 9″ iPads on sale for $30 off including free shipping: – 9″ 32GB iPad: $299 – 9″ 128GB iPad: $399 Read more
Apple restocks full line of refurbished 13″ M...
Apple has restocked a full line of Apple Certified Refurbished 2017 13″ MacBook Pros for $200-$300 off MSRP. A standard Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
13″ 3.1GHz/256GB MacBook Pro on sale for $167...
Amazon has the 2017 13″ 3.1GHz/256GB Space Gray MacBook Pro on sale today for $121 off MSRP including free shipping: – 13″ 3.1GHz/256GB Space Gray MacBook Pro (MPXV2LL/A): $1678 $121 off MSRP Keep an... Read more
13″ MacBook Pros on sale for up to $120 off M...
B&H Photo has 2017 13″ MacBook Pros in stock today and on sale for up to $120 off MSRP, each including free shipping plus NY & NJ sales tax only: – 13-inch 2.3GHz/128GB Space Gray MacBook... Read more
15″ MacBook Pros on sale for up to $200 off M...
B&H Photo has 15″ MacBook Pros on sale for up to $200 off MSRP. Shipping is free, and B&H charges sales tax in NY & NJ only: – 15″ 2.8GHz MacBook Pro Space Gray (MPTR2LL/A): $2249, $150... Read more
Roundup of Apple Certified Refurbished iMacs,...
Apple has a full line of Certified Refurbished 2017 21″ and 27″ iMacs available starting at $1019 and ranging up to $350 off original MSRP. Apple’s one-year warranty is standard, and shipping is free... Read more
Sale! 27″ 3.8GHz 5K iMac for $2098, save $201...
Amazon has the 27″ 3.8GHz 5K iMac (MNED2LL/A) on sale today for $2098 including free shipping. Their price is $201 off MSRP, and it’s the lowest price available for this model (Apple’s $1949... Read more
Sale! 10″ Apple WiFi iPad Pros for up to $100...
B&H Photo has 10.5″ WiFi iPad Pros in stock today and on sale for $50-$100 off MSRP. Each iPad includes free shipping, and B&H charges sales tax in NY & NJ only: – 10.5″ 64GB iPad Pro: $... Read more
Apple iMacs on sale for up to $130 off MSRP w...
B&H Photo has 21-inch and 27-inch iMacs in stock and on sale for up to $130 off MSRP including free shipping. B&H charges sales tax in NY & NJ only: – 27″ 3.8GHz iMac (MNED2LL/A): $2179 $... Read more
2017 3.5GHz 6-Core Mac Pro on sale for $2799,...
B&H Photo has the 2017 3.5GHz 6-Core Mac Pro (MD878LL/A) on sale today for $2799 including free shipping plus NY & NJ sales tax only . Their price is $200 off MSRP. Read more

Jobs Board

*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Commerce Engineer, *Apple* Media Products -...
Commerce Engineer, Apple Media Products (New York City) Job Number: 113028813New York City, New York, United StatesPosted: Sep. 20, 2017Weekly Hours: 40.00 Job Read more
US- *Apple* Store Leader Program - Apple (Un...
US- Apple Store Leader Program Job Number: VariousUnited StatesPosted: Oct. 19, 2017Retail Store Job Summary Learn and grow as you explore the art of leadership at Read more
Product Manager - *Apple* Pay on the *Appl...
Job Summary Apple is looking for a talented product manager to drive the expansion of Apple Pay on the Apple Online Store. This position includes a unique Read more
*Apple* Retail - Multiple Positions - Farmin...
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
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.