220 lines
7 KiB
C++
220 lines
7 KiB
C++
///////////////////////////////////////////////////////////////////////////////
|
|
// Name: interface/wx/preferences.h
|
|
// Purpose: wxPreferencesEditor class documentation.
|
|
// Author: Vaclav Slavik
|
|
// Created: 2013-02-26
|
|
// 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.
|
|
|
|
@param title The title overriding the default title of the top level
|
|
window used by the editor. It is recommended to not specify this
|
|
parameter to use the native convention for the preferences dialogs
|
|
instead.
|
|
*/
|
|
wxPreferencesEditor(const wxString& title = wxString());
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
virtual void Show(wxWindow* parent);
|
|
|
|
/**
|
|
Hide the currently shown dialog, if any.
|
|
|
|
This is typically 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()
|
|
|
|
/**
|
|
Returns whether the preferences dialog is shown modally.
|
|
|
|
If this method returns false, as it currently does in wxGTK and wxOSX,
|
|
Show() simply makes the dialog visible and returns immediately. If it
|
|
returns true, as it does in wxMSW and under the other platforms, then
|
|
the dialog is shown modally, i.e. Show() blocks until the user
|
|
dismisses it.
|
|
|
|
Notice that it isn't necessary to test the return value of this method
|
|
to use this class normally, its interface is designed to work in both
|
|
cases. However it can sometimes be necessary to call it if the program
|
|
needs to handle modal dialogs specially, e.g. perhaps to block some
|
|
periodic background update operation while a modal dialog is shown.
|
|
*/
|
|
static bool ShownModally();
|
|
};
|
|
|
|
|
|
/**
|
|
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:
|
|
/// Constructor.
|
|
wxPreferencesPage();
|
|
|
|
/// 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);
|
|
|
|
/// Returns the page's kind.
|
|
Kind GetKind() const;
|
|
|
|
/// 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;
|
|
};
|