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         @param title The title overriding the default title of the top level
  43             window used by the editor. It is recommended to not specify this
  44             parameter to use the native convention for the preferences dialogs
  45             instead.
  46      */
  47     wxPreferencesEditor(const wxString& title = wxString());
  48
  49     /**
  50         Destructor.
  51
  52         Destroying this object hides the associated preferences window if it is
  53         open at the moment.
  54
  55         The destructor is non-virtual as this class is not supposed to be
  56         derived from.
  57      */
  58     ~wxPreferencesEditor();
  59
  60     /**
  61         Add a new page to the editor.
  62
  63         The editor takes ownership of the page and will delete it from its
  64         destructor (but not sooner).
  65
  66         @see wxPreferencesPage, wxStockPreferencesPage
  67      */
  68     void AddPage(wxPreferencesPage *page);
  69
  70     /**
  71         Show the preferences dialog or bring it to the top if it's already
  72         shown.
  73
  74         Notice that this method may or may not block depending on the platform,
  75         i.e. depending on whether the dialog is modal or not.
  76
  77         @param parent The window that invokes the preferences.
  78                       Call Dismiss() before it's destroyed.
  79      */
  80     virtual void Show(wxWindow* parent);
  81
  82     /**
  83         Hide the currently shown dialog, if any.
  84
  85         This doesn't do anything on the platforms using modal preferences
  86         dialogs (e.g. Windows) but should be called to dismiss the dialog if
  87         the object whose preferences it is editing was closed.
  88      */
  89     void Dismiss();
  90
  91     /**
  92         Returns whether changes to values in preferences pages should be
  93         applied immediately or only when the user clicks the OK button.
  94
  95         Currently, changes are applied immediately on OS X and GTK+.
  96
  97         The preprocessor macro `wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY` is defined
  98         in this case as well.
  99      */
 100     static bool ShouldApplyChangesImmediately()
 101
 102     /**
 103         Returns whether the preferences dialog is shown modally.
 104
 105         If this method returns false, as it currently does in wxGTK and wxOSX,
 106         Show() simply makes the dialog visible and returns immediately. If it
 107         returns true, as it does in wxMSW and under the other platforms, then
 108         the dialog is shown modally, i.e. Show() blocks until the user
 109         dismisses it.
 110
 111         Notice that it isn't necessary to test the return value of this method
 112         to use this class normally, its interface is designed to work in both
 113         cases. However it can sometimes be necessary to call it if the program
 114         needs to handle modal dialogs specially, e.g. perhaps to block some
 115         periodic background update operation while a modal dialog is shown.
 116      */
 117     static bool ShownModally();
 118 };
 119
 120
 121 /**
 122     One page of preferences dialog.
 123
 124     This is the base class for implementation of application's preferences. Its
 125     methods return various properties of the page, such as title or icon. The
 126     actual page is created by CreateWindow().
 127
 128     @see wxStockPreferencesPage
 129
 130     @library{wxcore}
 131
 132     @since 2.9.5
 133  */
 134 class wxPreferencesPage
 135 {
 136 public:
 137     /// Constructor.
 138     wxPreferencesPage();
 139
 140     /// Destructor.
 141     virtual ~wxPreferencesPage();
 142
 143     /**
 144         Return name of the page.
 145
 146         The name is used for notebook tab's label, icon label etc., depending
 147         on the platform.
 148      */
 149     virtual wxString GetName() const = 0;
 150
 151     /**
 152         Return 32x32 icon used for the page on some platforms.
 153
 154         Currently only used on OS X.
 155
 156         @note This method is only pure virtual on platforms that require it
 157               (OS X). On other platforms, it has default implementation that
 158               returns an invalid bitmap. The preprocessor symbol
 159               `wxHAS_PREF_EDITOR_ICONS` is defined if this method must be
 160               implemented.
 161      */
 162     virtual wxBitmap GetLargeIcon() const = 0;
 163
 164     /**
 165         Create a window for this page.
 166
 167         The window will be placed into the preferences dialog in
 168         platform-specific manner. Depending on the platform, this method may
 169         be called before showing the preferences window, when switching to its
 170         tab or even more than once. Don't make assumptions about the number of
 171         times or the specific time when it is called.
 172
 173         The caller takes ownership of the window.
 174
 175         wxPanel is usually used, but doesn't have to be.
 176
 177         @param parent Parent window to use.
 178      */
 179     virtual wxWindow *CreateWindow(wxWindow *parent) = 0;
 180 };
 181
 182
 183 /**
 184     Specialization of wxPreferencesPage useful for certain commonly used
 185     preferences page.
 186
 187     On OS X, preferences pages named "General" and "Advanced" are commonly used
 188     in apps and the OS provides stock icons for them that should be used.
 189     Instead of reimplementing this behavior yourself, you can inherit from
 190     wxStockPreferencesPage and get correct title and icon.
 191
 192     Notice that this class only implements GetName() and GetLargeIcon(), you
 193     still have to provide the rest of wxPreferencesPage implementation.
 194
 195     @library{wxcore}
 196
 197     @since 2.9.5
 198  */
 199 class wxStockPreferencesPage : public wxPreferencesPage
 200 {
 201 public:
 202     /// Kinds of stock pages.
 203     enum Kind
 204     {
 205         /// The "General" page
 206         Kind_General,
 207         /// The "Advanced" page
 208         Kind_Advanced
 209     };
 210
 211     /// Constructor.
 212     wxStockPreferencesPage(Kind kind);
 213
 214     /// Returns the page's kind.
 215     Kind GetKind() const;
 216
 217     /// Reimplemented to return suitable name for the page's kind.
 218     virtual wxString GetName() const;
 219     /// Reimplemented to return stock icon on OS X.
 220     virtual wxBitmap GetLargeIcon() const;
 221 };