interface/wx/preferences.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        interface/wx/preferences.h
   3 // Purpose:     wxPreferencesEditor class documentation.
   4 // Author:      Vaclav Slavik
   5 // Created:     2013-02-26
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2013 Vaclav Slavik <vslavik@fastmail.fm>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 /**
  12     Manage preferences dialog.
  13
  14     This class encapsulates the differences -- both in appearance and
  15     behaviour -- between preferences dialogs on different platforms.  In
  16     particular, OS X preferences look very different from the typical notebook
  17     control used on other platforms, and both OS X and GTK+ preferences windows
  18     are modeless unlike Windows options dialogs that are typically modal.
  19
  20     wxPreferencesEditor is able to hide the differences by hiding the creation
  21     of preferences window from the API. Instead, you create an instance of
  22     wxPreferencesEditor and add page descriptions in the form of
  23     wxPreferencesPage using its AddPage() method. After setting up the editor
  24     object, you must call Show() to present preferences to the user.
  25
  26     @note Notice that this class is not derived from wxWindow and hence
  27           doesn't represent a window, even if its Show() method does create one
  28           internally.
  29
  30     @library{wxcore}
  31
  32     @since 2.9.5
  33  */
  34 class wxPreferencesEditor
  35 {
  36 public:
  37     /**
  38         Constructor.
  39
  40         Creates an empty editor, use AddPage() to add controls to it.
  41      */
  42     wxPreferencesEditor();
  43
  44     /**
  45         Destructor.
  46
  47         Destroying this object hides the associated preferences window if it is
  48         open at the moment.
  49
  50         The destructor is non-virtual as this class is not supposed to be
  51         derived from.
  52      */
  53     ~wxPreferencesEditor();
  54
  55     /**
  56         Add a new page to the editor.
  57
  58         The editor takes ownership of the page and will delete it from its
  59         destructor (but not sooner).
  60
  61         @see wxPreferencesPage, wxStockPreferencesPage
  62      */
  63     void AddPage(wxPreferencesPage *page);
  64
  65     /**
  66         Show the preferences dialog or bring it to the top if it's already
  67         shown.
  68
  69         Notice that this method may or may not block depending on the platform,
  70         i.e. depending on whether the dialog is modal or not.
  71
  72         @param parent The window that invokes the preferences.
  73                       Call Dismiss() before it's destroyed.
  74      */
  75     void Show(wxWindow* parent);
  76
  77     /**
  78         Hide the currently shown dialog, if any.
  79
  80         This doesn't do anything on the platforms using modal preferences
  81         dialogs (e.g. Windows) but should be called to dismiss the dialog if
  82         the object whose preferences it is editing was closed.
  83      */
  84     void Dismiss();
  85
  86     /**
  87         Returns whether changes to values in preferences pages should be
  88         applied immediately or only when the user clicks the OK button.
  89
  90         Currently, changes are applied immediately on OS X and GTK+.
  91
  92         The preprocessor macro `wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY` is defined
  93         in this case as well.
  94      */
  95     static bool ShouldApplyChangesImmediately()
  96 };
  97
  98
  99 /**
 100     One page of preferences dialog.
 101
 102     This is the base class for implementation of application's preferences. Its
 103     methods return various properties of the page, such as title or icon. The
 104     actual page is created by CreateWindow().
 105
 106     @see wxStockPreferencesPage
 107
 108     @library{wxcore}
 109
 110     @since 2.9.5
 111  */
 112 class wxPreferencesPage
 113 {
 114 public:
 115     /// Constructor.
 116     wxPreferencesPage();
 117
 118     /// Destructor.
 119     virtual ~wxPreferencesPage();
 120
 121     /**
 122         Return name of the page.
 123
 124         The name is used for notebook tab's label, icon label etc., depending
 125         on the platform.
 126      */
 127     virtual wxString GetName() const = 0;
 128
 129     /**
 130         Return 32x32 icon used for the page on some platforms.
 131
 132         Currently only used on OS X.
 133
 134         @note This method is only pure virtual on platforms that require it
 135               (OS X). On other platforms, it has default implementation that
 136               returns an invalid bitmap. The preprocessor symbol
 137               `wxHAS_PREF_EDITOR_ICONS` is defined if this method must be
 138               implemented.
 139      */
 140     virtual wxBitmap GetLargeIcon() const = 0;
 141
 142     /**
 143         Create a window for this page.
 144
 145         The window will be placed into the preferences dialog in
 146         platform-specific manner. Depending on the platform, this method may
 147         be called before showing the preferences window, when switching to its
 148         tab or even more than once. Don't make assumptions about the number of
 149         times or the specific time when it is called.
 150
 151         The caller takes ownership of the window.
 152
 153         wxPanel is usually used, but doesn't have to be.
 154
 155         @param parent Parent window to use.
 156      */
 157     virtual wxWindow *CreateWindow(wxWindow *parent) = 0;
 158 };
 159
 160
 161 /**
 162     Specialization of wxPreferencesPage useful for certain commonly used
 163     preferences page.
 164
 165     On OS X, preferences pages named "General" and "Advanced" are commonly used
 166     in apps and the OS provides stock icons for them that should be used.
 167     Instead of reimplementing this behavior yourself, you can inherit from
 168     wxStockPreferencesPage and get correct title and icon.
 169
 170     Notice that this class only implements GetName() and GetLargeIcon(), you
 171     still have to provide the rest of wxPreferencesPage implementation.
 172
 173     @library{wxcore}
 174
 175     @since 2.9.5
 176  */
 177 class wxStockPreferencesPage : public wxPreferencesPage
 178 {
 179 public:
 180     /// Kinds of stock pages.
 181     enum Kind
 182     {
 183         /// The "General" page
 184         Kind_General,
 185         /// The "Advanced" page
 186         Kind_Advanced
 187     };
 188
 189     /// Constructor.
 190     wxStockPreferencesPage(Kind kind);
 191
 192     /// Returns the page's kind.
 193     Kind GetKind() const;
 194
 195     /// Reimplemented to return suitable name for the page's kind.
 196     virtual wxString GetName() const;
 197     /// Reimplemented to return stock icon on OS X.
 198     virtual wxBitmap GetLargeIcon() const;
 199 };