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.

 
AAPL
$97.19
Apple Inc.
+2.47
MSFT
$44.87
Microsoft Corpora
+0.04
GOOG
$595.98
Google Inc.
+1.24

MacTech Search:
Community Search:

Software Updates via MacUpdate

Firefox 31.0 - Fast, safe Web browser. (...
Firefox for Mac offers a fast, safe Web browsing experience. Browse quickly, securely, and effortlessly. With its industry-leading features, Firefox is the choice of Web development professionals... Read more
Little Snitch 3.3.3 - Alerts you to outg...
Little Snitch gives you control over your private outgoing data. Track background activityAs soon as your computer connects to the Internet, applications often have permission to send any... Read more
Thunderbird 31.0 - Email client from Moz...
As of July 2012, Thunderbird has transitioned to a new governance model, with new features being developed by the broader free software and open source community, and security fixes and improvements... Read more
Together 3.2 - Store and organize all of...
Together helps you organize your Mac, giving you the ability to store, edit and preview your files in a single clean, uncluttered interface. Smart storage. With simple drag-and-drop functionality,... Read more
Cyberduck 4.5 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
iExplorer 3.4 - View and transfer all th...
iExplorer is an iPhone browser for Mac lets you view the files on your iOS device. By using a drag and drop interface, you can quickly copy files and folders between your Mac and your iPhone or... Read more
Airmail 1.4 - Powerful, minimal email cl...
Airmail is a powerful, minimal mail client.It was designed to retain the same experience with a single or multiple accounts and provide a quick, modern and easy-to-use user experience. Airmail... Read more
Macs Fan Control 1.1.12 - Monitor and co...
Macs Fan Control allows you to monitor and control almost any aspect of your computer's fans, with support for controlling fan speed, temperature sensors pane, menu-bar icon, and autostart with... Read more
A Better Finder Rename 9.37 - File, phot...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
MacBook Air EFI Firmware Update 2.9 - Fo...
MacBook Air EFI Firmware Update is recommended for MacBook Air (Mid 2011) models. This update addresses an issue where systems may take longer to wake from sleep than expected and fixes a rare issue... Read more

Latest Forum Discussions

See All

Together for iOS (Productivity)
Together for iOS 1.0 Device: iOS Universal Category: Productivity Price: $9.99, Version: 1.0 (iTunes) Description: Together is an app for keeping things in one place. Notes, documents, images, movies, sounds, web pages and bookmarks... | Read more »
Traps n' Gemstones (Games)
Traps n' Gemstones 1.00 Device: iOS Universal Category: Games Price: $2.99, Version: 1.00 (iTunes) Description: LAUNCH SALE! 40% off, JULY ONLY! TRAPS N' GEMSTONES is an adventurous platform game, among gamers typically known as the... | Read more »
Soccer Physics (Games)
Soccer Physics 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: One-button soccer game! So dumb it's fun. "Soccer Physics is probably the funniest football game you'll play on iOS" —... | Read more »
Ex-Angry Birds Developers Release Monsu...
Ex-Angry Birds Developers Release Monsu Teaser Trailer Posted by Jennifer Allen on July 23rd, 2014 [ permalink ] Finnish developer Boomlagoon has released a teaser trailer of their forthcoming side-scrolling action platformer, | Read more »
Lots of New Modes Have Been Added to Can...
Lots of New Modes Have Been Added to Canabalt Posted by Jennifer Allen on July 23rd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Stronghold 3: The Campaigns Review
Stronghold 3: The Campaigns Review By Jennifer Allen on July 23rd, 2014 Our Rating: :: DULL STRATEGIZINGiPad Only App - Designed for the iPad A cumbersome strategy game, Stronghold 3: The Campaigns has a few too many issues to... | Read more »
Table Tennis Touch on Sale for a Limited...
Table Tennis Touch on Sale for a Limited Time Posted by Jessica Fisher on July 23rd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Secret Files Tunguska Review
Secret Files Tunguska Review By Jennifer Allen on July 23rd, 2014 Our Rating: :: CONSPIRACY-LITTERED ADVENTURINGUniversal App - Designed for iPhone and iPad Offering traditional adventuring with no fear of in-app purchases, Secret... | Read more »
Celebrate Summer With a Cat in the Hat L...
Celebrate Summer With a Cat in the Hat Learning Library Sale Posted by Ellis Spice on July 22nd, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Dragon Raiders Review
Dragon Raiders Review By Nadia Oxford on July 22nd, 2014 Our Rating: :: RUN, DRAGON, RUNUniversal App - Designed for iPhone and iPad Dragon Raiders is rough and scaly in some parts, but overall it’s an enjoyable level-based running... | Read more »

Price Scanner via MacPrices.net

With The Apple/IBM Alliance, Is The iPad Now...
Almost since the iPad was rolled out in 2010, and especially after Apple made a 128 GB storage configuration available in 2012, there’s been debate over whether the iPad is a serious tool for... Read more
MacBook Airs on sale starting at $799, free s...
B&H Photo has the new 2014 MacBook Airs on sale for up to $100 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only. They also include free copies of Parallels... Read more
Apple 27″ Thunderbolt Display (refurbished) a...
The Apple Store has Apple Certified Refurbished 27″ Thunderbolt Displays available for $799 including free shipping. That’s $200 off the cost of new models. Read more
WaterField Designs Unveils Cycling Ride Pouch...
High end computer case and bag maker WaterField Designs of San Francisco now enters the cycling market with the introduction of the Cycling Ride Pouch – an upscale toolkit with a scratch-free iPhone... Read more
Kingston Digital Ships Large Capacity Near 1T...
Kingston Digital, Inc., the Flash memory affiliate of Kingston Technology Company, Inc.,has announced its latest addition to the SSDNow V300 series, the V310. The Kingston SSDNow V310 solid-state... Read more
Apple’s Fiscal Third Quarter Results; Record...
Apple has announced financial results for its fiscal 2014 third quarter ended June 28, 2014, racking up quarterly revenue of $37.4 billion and quarterly net profit of $7.7 billion, or $1.28 per... Read more
15-inch 2.0GHz MacBook Pro Retina on sale for...
B&H Photo has the 15″ 2.0GHz Retina MacBook Pro on sale for $1829 including free shipping plus NY sales tax only. Their price is $170 off MSRP. B&H will also include free copies of Parallels... Read more
Apple restocks refurbished Mac minis for up t...
The Apple Store has restocked Apple Certified Refurbished Mac minis for up to $150 off the cost of new models. Apple’s one-year warranty is included with each mini, and shipping is free: - 2.5GHz Mac... Read more
Twelve South HiRise For MacBook – Height-Adju...
If you use your MacBook as a workhorse desktop substitute, as many of us do, a laptop stand combined with an external keyboard and pointing device are pretty much obligatory if you want to avoid... Read more
Why The Mac Was Not Included In The Apple/IBM...
TUAW’s Yoni Heisler cites Fredrick Paul of Network World whoi blogged last week that the Mac’s conspicuous absence from Apple and IBM’s landmark partnership agreement represents a huge squandered... Read more

Jobs Board

Senior Interaction Designer, *Apple* Online...
**Job Summary** Apple is looking for a hands on Senior…will be a key player in designing for the Apple Online Store. The ideal designer will have a Read more
*Apple* Sales Chat Rep - Apple (United State...
…is looking for motivated, outgoing, and tech savvy individuals who want to offer Apple Customers an unparalleled customer experience over chat. At Apple , we believe Read more
Mac Expert - *Apple* Online Store Mexico -...
…MUST be fluent in English and Spanish to be considered for this position At Apple , we believe that hard work, a fun environment, creativity and innovation fuel the Read more
*Apple* Industrial Design CAD Sculptor - App...
**Job Summary** The Apple Industrial Design team is looking for a CAD sculptor/Digital 3D modeler to create high quality CAD models used in the industrial design process Read more
*Apple* Developer Support Advisor - Portugue...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.