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