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