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     /// Destructor.
 116     virtual ~wxPreferencesPage() {}
 117
 118     /**
 119         Return name of the page.
 120
 121         The name is used for notebook tab's label, icon label etc., depending
 122         on the platform.
 123      */
 124     virtual wxString GetName() const = 0;
 125
 126     /**
 127         Return 32x32 icon used for the page on some platforms.
 128
 129         Currently only used on OS X.
 130
 131         @note This method is only pure virtual on platforms that require it
 132               (OS X). On other platforms, it has default implementation that
 133               returns an invalid bitmap. The preprocessor symbol
 134               `wxHAS_PREF_EDITOR_ICONS` is defined if this method must be
 135               implemented.
 136      */
 137     virtual wxBitmap GetLargeIcon() const = 0;
 138
 139     /**
 140         Create a window for this page.
 141
 142         The window will be placed into the preferences dialog in
 143         platform-specific manner. Depending on the platform, this method may
 144         be called before showing the preferences window, when switching to its
 145         tab or even more than once. Don't make assumptions about the number of
 146         times or the specific time when it is called.
 147
 148         The caller takes ownership of the window.
 149
 150         wxPanel is usually used, but doesn't have to be.
 151
 152         @param parent Parent window to use.
 153      */
 154     virtual wxWindow *CreateWindow(wxWindow *parent) = 0;
 155 };
 156
 157
 158 /**
 159     Specialization of wxPreferencesPage useful for certain commonly used
 160     preferences page.
 161
 162     On OS X, preferences pages named "General" and "Advanced" are commonly used
 163     in apps and the OS provides stock icons for them that should be used.
 164     Instead of reimplementing this behavior yourself, you can inherit from
 165     wxStockPreferencesPage and get correct title and icon.
 166
 167     Notice that this class only implements GetName() and GetLargeIcon(), you
 168     still have to provide the rest of wxPreferencesPage implementation.
 169
 170     @library{wxcore}
 171
 172     @since 2.9.5
 173  */
 174 class wxStockPreferencesPage : public wxPreferencesPage
 175 {
 176 public:
 177     /// Kinds of stock pages.
 178     enum Kind
 179     {
 180         /// The "General" page
 181         Kind_General,
 182         /// The "Advanced" page
 183         Kind_Advanced
 184     };
 185
 186     /// Constructor.
 187     wxStockPreferencesPage(Kind kind) : m_kind(kind) {}
 188
 189     /// Returns the page's kind.
 190     Kind GetKind() const { return m_kind; }
 191
 192     /// Reimplemented to return suitable name for the page's kind.
 193     virtual wxString GetName() const;
 194     /// Reimplemented to return stock icon on OS X.
 195     virtual wxBitmap GetLargeIcon() const;
 196 };