Add wxPreferencesEditor class.

Implements native UI for preferences editing.  In particular, the API
handles the differences between modal (Windows) and non-modal (OS X) preferences windows and provides platform's native look.

Currently implemented natively for wxOSX/Cocoa, wxGTK and Windows (the latter is used as a fallback generic implementation as well).

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@73576 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

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 <vslavik@fastmail.fm>
+// 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;
+};