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
  97     // Dtor destroys the dialog if still shown.
  98     virtual ~wxPreferencesEditor();
  99
 100     // Add a new page to the editor. The editor takes ownership of the page
 101     // and won't delete it until it is destroyed itself.
 102     void AddPage(wxPreferencesPage *page);
 103
 104     // Show the preferences dialog or bring it to the top if it's already
 105     // shown. Notice that this method may or may not block depending on the
 106     // platform, i.e. depending on whether the dialog is modal or not.
 107     virtual void Show(wxWindow* parent);
 108
 109     // Hide the currently shown dialog, if any. This is typically used to
 110     // dismiss the dialog if the object whose preferences it is editing was
 111     // closed.
 112     void Dismiss();
 113
 114     // Whether changes to values in the pages should be applied immediately
 115     // (OS X, GTK+) or only when the user clicks OK/Apply (Windows)
 116     static bool ShouldApplyChangesImmediately()
 117     {
 118 #ifdef wxHAS_PREF_EDITOR_APPLY_IMMEDIATELY
 119         return true;
 120 #else
 121         return false;
 122 #endif
 123     }
 124
 125     // Whether the dialog is shown modally, i.e. Show() blocks, or not.
 126     static bool ShownModally()
 127     {
 128 #ifdef wxHAS_PREF_EDITOR_MODELESS
 129         return false;
 130 #else
 131         return true;
 132 #endif
 133     }
 134
 135 private:
 136     wxPreferencesEditorImpl* m_impl;
 137
 138     wxDECLARE_NO_COPY_CLASS(wxPreferencesEditor);
 139 };
 140
 141 #endif // _WX_PREFERENCES_H_