X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d52a1abad31942f32364bb40808150c4be6c56cd..2aab96f58d53e83313cc1d619dde1c00f6ccaa80:/interface/wx/preferences.h diff --git a/interface/wx/preferences.h b/interface/wx/preferences.h new file mode 100644 index 0000000000..222419e035 --- /dev/null +++ b/interface/wx/preferences.h @@ -0,0 +1,196 @@ +/////////////////////////////////////////////////////////////////////////////// +// Name: interface/wx/preferences.h +// Purpose: wxPreferencesEditor class documentation. +// Author: Vaclav Slavik +// Created: 2013-02-26 +// RCS-ID: $Id$ +// Copyright: (c) 2013 Vaclav Slavik +// Licence: wxWindows licence +/////////////////////////////////////////////////////////////////////////////// + +/** + Manage preferences dialog. + + This class encapsulates the differences -- both in appearance and + behaviour -- between preferences dialogs on different platforms. In + particular, OS X preferences look very different from the typical notebook + control used on other platforms, and both OS X and GTK+ preferences windows + are modeless unlike Windows options dialogs that are typically modal. + + wxPreferencesEditor is able to hide the differences by hiding the creation + of preferences window from the API. Instead, you create an instance of + wxPreferencesEditor and add page descriptions in the form of + wxPreferencesPage using its AddPage() method. After setting up the editor + object, you must call Show() to present preferences to the user. + + @note Notice that this class is not derived from wxWindow and hence + doesn't represent a window, even if its Show() method does create one + internally. + + @library{wxcore} + + @since 2.9.5 + */ +class wxPreferencesEditor +{ +public: + /** + Constructor. + + Creates an empty editor, use AddPage() to add controls to it. + */ + wxPreferencesEditor(); + + /** + Destructor. + + Destroying this object hides the associated preferences window if it is + open at the moment. + + The destructor is non-virtual as this class is not supposed to be + derived from. + */ + ~wxPreferencesEditor(); + + /** + Add a new page to the editor. + + The editor takes ownership of the page and will delete it from its + destructor (but not sooner). + + @see wxPreferencesPage, wxStockPreferencesPage + */ + void AddPage(wxPreferencesPage *page); + + /** + Show the preferences dialog or bring it to the top if it's already + shown. + + Notice that this method may or may not block depending on the platform, + i.e. depending on whether the dialog is modal or not. + + @param parent The window that invokes the preferences. + Call Dismiss() before it's destroyed. + */ + void Show(wxWindow* parent); + + /** + Hide the currently shown dialog, if any. + + This doesn't do anything on the platforms using modal preferences + dialogs (e.g. Windows) but should be called to dismiss the dialog if + the object whose preferences it is editing was closed. + */ + void Dismiss(); + + /** + Returns whether changes to values in preferences pages should be + applied immediately or only when the user clicks the OK button. + + Currently, changes are applied immediately on OS X and GTK+. + + The preprocessor macro `wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY` is defined + in this case as well. + */ + static bool ShouldApplyChangesImmediately() +}; + + +/** + One page of preferences dialog. + + This is the base class for implementation of application's preferences. Its + methods return various properties of the page, such as title or icon. The + actual page is created by CreateWindow(). + + @see wxStockPreferencesPage + + @library{wxcore} + + @since 2.9.5 + */ +class wxPreferencesPage +{ +public: + /// Destructor. + virtual ~wxPreferencesPage() {} + + /** + Return name of the page. + + The name is used for notebook tab's label, icon label etc., depending + on the platform. + */ + virtual wxString GetName() const = 0; + + /** + Return 32x32 icon used for the page on some platforms. + + Currently only used on OS X. + + @note This method is only pure virtual on platforms that require it + (OS X). On other platforms, it has default implementation that + returns an invalid bitmap. The preprocessor symbol + `wxHAS_PREF_EDITOR_ICONS` is defined if this method must be + implemented. + */ + virtual wxBitmap GetLargeIcon() const = 0; + + /** + Create a window for this page. + + The window will be placed into the preferences dialog in + platform-specific manner. Depending on the platform, this method may + be called before showing the preferences window, when switching to its + tab or even more than once. Don't make assumptions about the number of + times or the specific time when it is called. + + The caller takes ownership of the window. + + wxPanel is usually used, but doesn't have to be. + + @param parent Parent window to use. + */ + virtual wxWindow *CreateWindow(wxWindow *parent) = 0; +}; + + +/** + Specialization of wxPreferencesPage useful for certain commonly used + preferences page. + + On OS X, preferences pages named "General" and "Advanced" are commonly used + in apps and the OS provides stock icons for them that should be used. + Instead of reimplementing this behavior yourself, you can inherit from + wxStockPreferencesPage and get correct title and icon. + + Notice that this class only implements GetName() and GetLargeIcon(), you + still have to provide the rest of wxPreferencesPage implementation. + + @library{wxcore} + + @since 2.9.5 + */ +class wxStockPreferencesPage : public wxPreferencesPage +{ +public: + /// Kinds of stock pages. + enum Kind + { + /// The "General" page + Kind_General, + /// The "Advanced" page + Kind_Advanced + }; + + /// Constructor. + wxStockPreferencesPage(Kind kind) : m_kind(kind) {} + + /// Returns the page's kind. + Kind GetKind() const { return m_kind; } + + /// Reimplemented to return suitable name for the page's kind. + virtual wxString GetName() const; + /// Reimplemented to return stock icon on OS X. + virtual wxBitmap GetLargeIcon() const; +};