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