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