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