Applied patch #15286: documentation and col/rowspan demo by dghart

[wxWidgets.git] / interface / wx / preferences.h

///////////////////////////////////////////////////////////////////////////////
// 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.

        @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;
};