docs/doxygen/overviews/persistence.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        docs/doxygen/overviews/persistence.h
   3 // Purpose:     overview of persistent objects
   4 // Author:      Vadim Zeitlin
   5 // Created:     2009-01-23
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org>
   8 // Licence:     wxWindows license
   9 /////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12
  13 @page overview_persistence Persistent Objects Overview
  14
  15 Persistent objects are simply the objects which automatically save their state
  16 when they are destroyed and restore it when they are recreated, even during
  17 another program invocation.
  18
  19 Most often, persistent objects are, in fact, persistent windows as it is
  20 especially convenient to automatically restore the UI state when the program is
  21 restarted but an object of any class can be made persistent. Moreover,
  22 persistence is implemented in a non-intrusive way so that the original object
  23 class doesn't need to be modified at all in order to add support for saving and
  24 restoring its properties.
  25
  26 The persistence framework involves
  27  - wxPersistenceManager which all persistent objects register themselves with.
  28    This class handles actual saving and restoring of persistent data as well as
  29    various global aspects of persistence, e.g. it can be used to disable
  30    restoring the saved data.
  31  - wxPersistentObject is the base class for all persistent objects or, rather,
  32    adaptors for the persistent objects as this class main purpose is to provide
  33    the bridge between the original class -- which has no special persistence
  34    support -- and wxPersistenceManager,
  35  - wxPersistentWindow<> which derives from wxPersistentObject and implements some
  36    of its methods using wxWindow-specific functionality. Notably,
  37    wxPersistenceManager handles the destruction of persistent windows
  38    automatically implicitly while it has to be done explicitly for the
  39    arbitrary persistent objects.
  40  - wxCreatePersistentObject() function which is used to create the
  41    appropriate persistence adapter for the object.
  42
  43
  44 @section persistence_using Using Persistent Windows
  45
  46 wxWidgets has built-in support for a (constantly growing) number of controls.
  47 Currently the following classes are supported:
  48     - wxTopLevelWindow (and hence wxFrame and wxDialog)
  49     - wxBookCtrlBase, i.e. wxNotebook, wxListbook, wxToolbook and wxChoicebook
  50     - wxTreebook
  51
  52 To automatically save and restore the properties of the windows of classes
  53 listed above you need to
  54
  55     -# Set a unique name for the window using wxWindow::SetName(): this step is
  56     important as the name is used in the configuration file and so must be
  57     unique among all windows of the same class.
  58     -# Call wxPersistenceManager::Register() at any moment after creating the
  59     window and then wxPersistenceManager::Restore() when the settings may be
  60     restored (which can't be always done immediately, e.g. often the window
  61     needs to be populated first). If settings can be restored immediately after
  62     the window creation, as is often the case for wxTopLevelWindow, for
  63     example, then wxPersistenceManager::RegisterAndRestore() can be used to do
  64     both at once.
  65     -# If you do not want the settings for the window to be saved (for example
  66     the changes to the dialog size are usually not saved if the dialog was
  67     cancelled), you need to call wxPersistenceManager::Unregister() manually.
  68     Otherwise the settings will be automatically saved when the control itself
  69     is destroyed.
  70
  71 Example of using a notebook control which automatically remembers the last open
  72 page:
  73 @code
  74     wxNotebook *book = new wxNotebook(parent, wxID_ANY);
  75     book->SetName("MyBook"); // do not use the default name
  76     book->AddPage(...);
  77     book->AddPage(...);
  78     book->AddPage(...);
  79     if ( !wxPersistenceManager::RegisterAndRestore(book) )
  80     {
  81         // nothing was restored, so choose the default page ourselves
  82         book->SetSelection(0);
  83     }
  84 @endcode
  85
  86
  87 @section persistence_defining Defining Custom Persistent Windows
  88
  89 User-defined classes can be easily integrated with wxPersistenceManager. To add
  90 support for your custom class @c MyWidget you just need to:
  91
  92     -# Define a new @c MyPersistentWidget class inheriting from
  93     wxPersistentWindow<MyWidget>.
  94     -# Implement its pure virtual GetKind() method returning a unique string
  95     identifying all @c MyWidget objects, typically something like @c "widget"
  96     -# Implement its pure virtual Save() and Restore() methods to actually save
  97     and restore the widget settings using wxPersistentObject::SaveValue() and
  98     wxPersistentObject::RestoreValue() methods.
  99     -# Define wxCreatePersistentObject() overload taking @c MyWidget * and
 100     returning a new @c MyPersistentWidget object.
 101
 102 If you want to add persistence support for a class not deriving from wxWindow,
 103 you need to derive @c MyPersistentWidget directly from wxPersistentObject and
 104 so implement its pure virtual wxPersistentObject::GetName() method too.
 105 Additionally, you must ensure that wxPersistenceManager::SaveAndUnregister() is
 106 called when your object is destroyed as this can be only done automatically for
 107 windows.
 108
 109  */
 110