The following header file is created in the CodeWarrior for PalmPilot IDE. It describes how another app could call Flash! with a custom launch code to ask it to turn a certain piece of data into a flash card. One situation in which an application might do this would involve a foreign language dictionary application. On the screen which shows when you finish looking up a word, with the word in English and the foreign language displayed, you could put a button which only shows up when the Flash! app is detected. Pressing this button would import the word pair as a flash card into Flash!
typedef enum {
FlashLaunchMakeIntoCard = sysAppLaunchCmdCustomBase
} FlashCustomActionCodes;
typedef struct {
CharPtr Q;
/// Pointer to string for one side. Must be valid pointer.
char BreakChar;
/// The character that marks the end of side 1 and the beginning
/// of side 2 within the Side1 string, or 0.
CharPtr A;
/// Pointer to string for side 2. Should be null iff BreakChar != 0
Boolean dbIDIsNotFlashDeck : 1;
/// True if the dbID passed in LocalID does not refer to a Flash! deck.
Boolean NoDuplicates : 1;
/// True if Flash! should check through the entire deck and not import
/// this card if it is a duplicate of an existing card in that deck.
Boolean AlertDuplicates : 1;
/// If true, and if Flash! does not import the card because of duplication,
/// Flash! will return the value -1 instead of the dbID to which it tried
/// to import the card.
Boolean Reserved1 : 1;
Boolean Reserved2 : 1;
Boolean Reserved3 : 1;
Boolean UseDbIDName : 1;
/// See option 3, below. Meaningless unless dbIDIsNotFlashDeck is true.
/// DO NOT SET TRUE UNLESS YOU ALWAYS PASS A VALID LOCALID IN DBID.
Boolean ShowBoth : 1; ///At end for backward compatibility
/// True if this card can be tested from both sides, as in a foreign
/// vocabulary flashcard. In ambiguous cases, applications should pass
/// false.
LocalID dbID;
/// There are three possible types of things to pass here:
/// 1. 0 is always a legal value. If 0 is passed and there is no
/// default import deck, one is created with the name "Imported".
/// Then, the card is imported to this deck.
/// 2. If dbIDIsNotFlashDeck is false, then this must be the LocalID
/// of a Flash! deck (type = 'Deck', creator = 'Flsh').
/// You may have obtained this from the return value of a previous
/// FlashLaunchMakeIntoCard call. Flash! will add the card to this
/// deck. If this deck does not exist for any reason, a new deck
/// is created with the name "Imported dictionary words" and the card
/// imported to this deck.
/// 3. If dbIDIsNotFlashDeck is true, then this may be any valid LocalID.
/// A suggested value is the LocalID of the passing application or its
/// database. INVALID LOCALIDS COULD CAUSE PILOT CRASHES.
/// The first time a given value is passed, a deck is created.
/// If UseDbIDName is true, the name of the database corresponding to dbID
/// is checked and the new deck is given the same name (from a user POV;
/// PalmOS sees an extra character at the front). Otherwise, it is named
/// "Imported Dictionary Words".
/// Either way, a feature is created that records
/// the association between the value passed and the deck created. When
/// the same value is passed again, Flash! tries to use the same deck.
/// First, it checks for a feature to point it to the deck.
/// If the feature is gone due to a soft reset, and UseDbIDName is true,
/// Flash! checks for a deck with the correct name. If the deck has
/// been renamed prior to a soft reset or deleted, a new
/// one is created.
/// Technical details:
/// the feature has owner 'Flsh', number equal to (dbID ^ (dbID >> 16)),
/// and value equal to the LocalID of the created Flash! deck.
/// NOTE: since features do not persist through soft-resets of the device,
/// METHOD 3 CAN LEAD TO FRAGMENTED DECKS. If your application uses only
/// one database, you should keep the LocalID of the Flash! deck in your
/// preferences, and thus use method 2.
} CardPrototype;
/// this entire structure and its children are the responsibility
/// of the calling application.
/*
......the skeleton of your call to my app.
{
CardPrototype TheCard;
Err err;
UInt cardNo;
DWord result;
LocalID FlashID;
DmSearchStateType searchState;
#if EMULATION_LEVEL == EMULATION_NONE
// Get the card number and database id of the Flash
// application.
err = DmGetNextDatabaseByTypeCreator (true, &searchState,
sysFileTApplication, 'Flsh', true, &cardNo, &dbID);
if (! err)
{
TheCard.Q = QuestionText;
TheCard.A = AnswerText;/// Assuming you have separate strings for Q and A
TheCard.BreakChar = 0; /// Assuming you have separate strings for Q and A
TheCard.dbIDIsNotFlashDeck = false;
TheCard.NoDuplicates = false; /// Faster this way
TheCard.BothSides = false; ///Safest value, unless your app is a dictionary
TheCard.dbID = myPrefs.theFlashDeckIUse;
///Of course, all of the above must be tailored to your app
err = SysAppLaunch (cardNo, dbID, sysAppLaunchFlagSubCall,
FlashLaunchMakeIntoCard, (Ptr)&TheCard, &result);
if (result != 0)
myPrefs.theFlashDeckIUse = result; //The Flash! application returns
// the LocalID of the database into which it put the card
// in the Result variable. You can pass this value back to
// it (in the dbID field of the CardPrototype) next time you
// want a card added to the same database. If you pass an
// invalid ID, it will create a new database. Whenever a new
// database is created in this manner, that one will become
// the default database. Thus, in case there are more than one
// apps passing cards to Flash, it is recommended (but not
// necessary) that you save this value somewhere in your
// Preferences entry and refer to it on subsequent calls.
else
ErrFatalDisplayIf(debugging, "Flash had a problem importing... memory?");
ErrFatalDisplayIf(err, "PalmOS error sending card to Flash!");
}
else
{
/// Display error
}
#endif
}
....
then in the code executed on frmOpenEvent for the appropriate form
....
{
Err err;
UInt cardNo;
LocalID dbID;
DmSearchStateType searchState;
///blah blah blah ... specific to your app
case frmOpenEvent: // perhaps, unless you've packed this off to some init function
///Put this in whatever order, as long as it's befor the DrawForm call.
err = DmGetNextDatabaseByTypeCreator (true, &searchState,
sysFileTApplication, 'Flsh', true, &cardNo, &dbID);
CtlSetUsable(GetObjectPtr(SomeFormSendToFlashButton),!err);
}
*/