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