]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/preferences.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / preferences.h
CommitLineData
2aab96f5
VS
1///////////////////////////////////////////////////////////////////////////////
2// Name: interface/wx/preferences.h
3// Purpose: wxPreferencesEditor class documentation.
4// Author: Vaclav Slavik
5// Created: 2013-02-26
2aab96f5
VS
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 */
33class wxPreferencesEditor
34{
35public:
36 /**
37 Constructor.
38
39 Creates an empty editor, use AddPage() to add controls to it.
654c4b7b
VZ
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.
2aab96f5 45 */
654c4b7b 46 wxPreferencesEditor(const wxString& title = wxString());
2aab96f5
VS
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 */
eaa69588 79 virtual void Show(wxWindow* parent);
2aab96f5
VS
80
81 /**
82 Hide the currently shown dialog, if any.
83
615f9ff0
VZ
84 This is typically called to dismiss the dialog if the object whose
85 preferences it is editing was closed.
2aab96f5
VS
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()
b5c96277
VZ
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();
2aab96f5
VS
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 */
132class wxPreferencesPage
133{
134public:
a150fade
RD
135 /// Constructor.
136 wxPreferencesPage();
137
2aab96f5 138 /// Destructor.
a150fade 139 virtual ~wxPreferencesPage();
2aab96f5
VS
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 */
197class wxStockPreferencesPage : public wxPreferencesPage
198{
199public:
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.
a150fade 210 wxStockPreferencesPage(Kind kind);
2aab96f5
VS
211
212 /// Returns the page's kind.
a150fade 213 Kind GetKind() const;
2aab96f5
VS
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};