/* -*- mode: C++; tab-width: 4 -*- */ /* ===================================================================== *\ Copyright (c) 1999-2001 Palm, Inc. or its subsidiaries. All rights reserved. This file is part of the Palm OS Emulator. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. \* ===================================================================== */ #ifndef _PREFERENCEMGR_H_ #define _PREFERENCEMGR_H_ #include "EmFileRef.h" // EmFileRefList, EmFileRef #include "EmTransport.h" // EmTransportType #include "EmHAL.h" // EmUARTDeviceType #include "Skins.h" // SkinNameList #include "omnithread.h" // omni_mutex #include // FILE #include #include class EmTransport; /* This file contains the routines for loading, saving, and accessing a collection of preferences/settings. All settings are accessed via the Preference class. This is a templatized class that is specialized on the type of the setting and parameterized on the name of the setting. This sounds nasty, but in practice is simple. For example, say you needed to access whether or not NetLib redirection was turned on. You would use the following: Preference pref(kPrefKeyRedirectNetLib); if (*pref) { // It's on. } Changing a value works similarly: Preference pref(kPrefKeyDeviceType); *pref = kDevicePalmIII; When the Preference object is destructed, it's new value is written back out to the Preference Manager. The Preference Manager is the "container" for all the preferences used by the application. You can think of it as a map/dictionary/associative array. You directly access the Preference Manager in order to create it, have it load the collection of preferences from disk, have it save them to disk, and to destroy it. While there are GetPref and SetPref methods on this class, those are for the use of the Preference objects. All preferences are saved as text in the form: = is any unique string. It can consist of any text characters except for '='. Keys can have subparts separated by '.', and can indicate array indices with "[#]". For example: Scale=2 GremlinInfo.fNumber=100 PRC_MRU[0]=MyApplication.prc GremlinInfo.fAppList[0].name=AddressBook With the Preference class, it's possible to pull in all or part of the hierarchical information. For instance: Preference pref("GremlinInfo"); Preference pref("GremlinInfo.fAppList"); Preference pref("GremlinInfo.fAppList[0]"); Preference pref("GremlinInfo.fAppList[0].name"); */ typedef const char* PrefKeyType; bool PrefKeysEqual (PrefKeyType, PrefKeyType); class BasePreference { public: BasePreference (PrefKeyType name, bool = true); BasePreference (long index, bool = true); virtual ~BasePreference (void); bool Loaded (void) { return fLoaded; } void Flush (void) { this->Save (); } protected: void Load (void); void Save (void); protected: virtual bool DoLoad (void) = 0; virtual void DoSave (void) = 0; protected: string fName; bool fLoaded; bool fChanged; bool fAcquireLock; }; template class Preference : public BasePreference { public: Preference (PrefKeyType name, bool = true); Preference (long index, bool = true); virtual ~Preference (void); // I would *like* to have these operators. That way, I could pass in a // "Preference" any place that accepts a "const Foo&" as a parameter. // However, CodeWarrior seems to use the conversion operators here in place // that accept merely a "Foo&", which has lead to some problems. // operator const T&() const { return *GetValue (); } // operator const T*() const { return GetValue (); } const T& operator*() const { return *GetValue (); } const T* operator->() const { return GetValue (); } const T* GetValue () const { EmAssert (fLoaded); return &fValue; } const T& operator=(const T& rhs) { fValue = rhs; fLoaded = true; fChanged = true; this->Flush (); return fValue; } protected: virtual bool DoLoad (void); virtual void DoSave (void); private: T fValue; }; typedef void* PrefRefCon; typedef void (*PrefNotifyFunc)(PrefKeyType, PrefRefCon); typedef StringList PrefKeyList; enum { MRU_COUNT = 9 }; class Preferences { public: Preferences (void); virtual ~Preferences (void); virtual void Load (void); virtual void Save (void); // This should work, but CW doesn't appear to like it. // private: // template friend class Preference; public: bool GetPref (const string& key, string& value); void SetPref (const string& key, const string& value); void DeletePref (const string& key); public: void PushPrefix (const string& prefix); void PushPrefix (long index); void PopPrefix (void); string ExpandKey (const string& name); string AppendName (string key, const string& name); public: void AddNotification (PrefNotifyFunc, PrefKeyType, PrefRefCon = NULL); void AddNotification (PrefNotifyFunc, const PrefKeyList&, PrefRefCon = NULL); void RemoveNotification (PrefNotifyFunc); void RemoveNotification (PrefNotifyFunc, PrefKeyType); void RemoveNotification (PrefNotifyFunc, const PrefKeyList&); void DoNotify (const string& key); protected: virtual Bool ReadPreferences (StringStringMap&); virtual void WritePreferences (const StringStringMap&); virtual EmFileRef GetPrefRef (void); virtual void WriteBanner (FILE*); virtual Bool ReadBanner (FILE*); virtual void StripUnused (void); protected: typedef StringStringMap PrefList; typedef PrefList::value_type PrefPairType; typedef PrefList::iterator iterator; PrefList fPreferences; typedef StringList PrefixType; PrefixType fPrefixes; struct PrefNotifyType { PrefNotifyFunc fFunc; PrefKeyList fKeyList; PrefRefCon fRefCon; }; typedef vector PrefNotifyList; PrefNotifyList fNotifications; public: static omni_mutex fgPrefsMutex; }; extern Preferences* gPrefs; class EmulatorPreferences : public Preferences { public: EmulatorPreferences (void); virtual ~EmulatorPreferences(void); virtual void Load (void); void GetDatabaseMRU (EmFileRefList&); void GetSessionMRU (EmFileRefList&); void GetROMMRU (EmFileRefList&); EmFileRef GetIndPRCMRU (int); EmFileRef GetIndRAMMRU (int); EmFileRef GetIndROMMRU (int); EmFileRef GetIndMRU (const EmFileRefList&, int); void UpdatePRCMRU (const EmFileRef&); void UpdateRAMMRU (const EmFileRef&); void UpdateROMMRU (const EmFileRef&); void UpdateMRU (EmFileRefList&, const EmFileRef&); void RemovePRCMRU (const EmFileRef&); void RemoveRAMMRU (const EmFileRef&); void RemoveROMMRU (const EmFileRef&); void RemoveMRU (EmFileRefList&, const EmFileRef&); void SetTransports (void); void SetTransportForDevice (EmUARTDeviceType, EmTransport*); EmTransport* GetTransportForDevice (EmUARTDeviceType); // Utility routines for determining what should happen in DoDialog. Bool LogMessage (Bool isFatal); Bool ShouldQuit (Bool isFatal); Bool ShouldContinue (Bool isFatal); Bool ShouldNextGremlin (Bool isFatal); protected: virtual void WriteBanner (FILE*); virtual Bool ReadBanner (FILE*); virtual void StripUnused (void); void MigrateOldPrefs (void); EmTransport* fTransports[kUARTEnd]; }; extern EmulatorPreferences* gEmuPrefs; /* The FOR_EACH_PREF macro is used to manage the preferences keys. Preferences are accessed via keys passed to the Preference constructor. These keys have the symbolic form: kPrefKey