include/wx/preferences.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/preferences.h
   3 // Purpose:     Declaration of wxPreferencesEditor class.
   4 // Author:      Vaclav Slavik
   5 // Created:     2013-02-19
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2013 Vaclav Slavik <vslavik@fastmail.fm>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_PREFERENCES_H_
  12 #define _WX_PREFERENCES_H_
  13
  14 #include "wx/defs.h"
  15
  16 #if wxUSE_PREFERENCES_EDITOR
  17
  18 #include "wx/bitmap.h"
  19 #include "wx/vector.h"
  20
  21 class WXDLLIMPEXP_FWD_CORE wxWindow;
  22
  23 class wxPreferencesEditorImpl;
  24
  25 #if defined(__WXOSX_COCOA__)
  26     // GetLargeIcon() is used
  27     #define wxHAS_PREF_EDITOR_ICONS
  28     // Changes should be applied immediately
  29     #define wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY
  30     // The dialog is shown non-modally.
  31     #define wxHAS_PREF_EDITOR_MODELESS
  32 #elif defined(__WXGTK__)
  33     // Changes should be applied immediately
  34     #define wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY
  35     // The dialog is shown non-modally.
  36     #define wxHAS_PREF_EDITOR_MODELESS
  37 #endif
  38
  39 // ----------------------------------------------------------------------------
  40 // wxPreferencesEditor: Native preferences editing
  41 // ----------------------------------------------------------------------------
  42
  43 // One page of a preferences window
  44 class WXDLLIMPEXP_CORE wxPreferencesPage
  45 {
  46 public:
  47     wxPreferencesPage() {}
  48     virtual ~wxPreferencesPage() {}
  49
  50     // Name of the page, used e.g. for tabs
  51     virtual wxString GetName() const = 0;
  52
  53     // Return 32x32 icon used for the page. Currently only used on OS X, where
  54     // implementation is required; unused on other platforms. Because of this,
  55     // the method is only pure virtual on platforms that use it.
  56 #ifdef wxHAS_PREF_EDITOR_ICONS
  57     virtual wxBitmap GetLargeIcon() const = 0;
  58 #else
  59     virtual wxBitmap GetLargeIcon() const { return wxBitmap(); }
  60 #endif
  61
  62     // Create a window (usually a wxPanel) for this page. The caller takes
  63     // ownership of the returned window.
  64     virtual wxWindow *CreateWindow(wxWindow *parent) = 0;
  65
  66     wxDECLARE_NO_COPY_CLASS(wxPreferencesPage);
  67 };
  68
  69
  70 // Helper for implementing some common pages (General, Advanced)
  71 class WXDLLIMPEXP_CORE wxStockPreferencesPage : public wxPreferencesPage
  72 {
  73 public:
  74     enum Kind
  75     {
  76         Kind_General,
  77         Kind_Advanced
  78     };
  79
  80     wxStockPreferencesPage(Kind kind) : m_kind(kind) {}
  81     Kind GetKind() const { return m_kind; }
  82
  83     virtual wxString GetName() const;
  84 #ifdef __WXOSX_COCOA__
  85     virtual wxBitmap GetLargeIcon() const;
  86 #endif
  87
  88 private:
  89     Kind m_kind;
  90 };
  91
  92
  93 // Notice that this class does not inherit from wxWindow.
  94 class WXDLLIMPEXP_CORE wxPreferencesEditor
  95 {
  96 public:
  97     // Ctor creates an empty editor, use AddPage() to add controls to it.
  98     wxPreferencesEditor(const wxString& title = wxString());
  99
 100     // Dtor destroys the dialog if still shown.
 101     virtual ~wxPreferencesEditor();
 102
 103     // Add a new page to the editor. The editor takes ownership of the page
 104     // and won't delete it until it is destroyed itself.
 105     void AddPage(wxPreferencesPage *page);
 106
 107     // Show the preferences dialog or bring it to the top if it's already
 108     // shown. Notice that this method may or may not block depending on the
 109     // platform, i.e. depending on whether the dialog is modal or not.
 110     virtual void Show(wxWindow* parent);
 111
 112     // Hide the currently shown dialog, if any. This is typically used to
 113     // dismiss the dialog if the object whose preferences it is editing was
 114     // closed.
 115     void Dismiss();
 116
 117     // Whether changes to values in the pages should be applied immediately
 118     // (OS X, GTK+) or only when the user clicks OK/Apply (Windows)
 119     static bool ShouldApplyChangesImmediately()
 120     {
 121 #ifdef wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY
 122         return true;
 123 #else
 124         return false;
 125 #endif
 126     }
 127
 128     // Whether the dialog is shown modally, i.e. Show() blocks, or not.
 129     static bool ShownModally()
 130     {
 131 #ifdef wxHAS_PREF_EDITOR_MODELESS
 132         return false;
 133 #else
 134         return true;
 135 #endif
 136     }
 137
 138 private:
 139     wxPreferencesEditorImpl* m_impl;
 140
 141     wxDECLARE_NO_COPY_CLASS(wxPreferencesEditor);
 142 };
 143
 144 #endif // wxUSE_PREFERENCES_EDITOR
 145
 146 #endif // _WX_PREFERENCES_H_