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