wxPython/src/_renderer.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _renderer.i
   3 // Purpose:     SWIG interface for wxRendererNative
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     9-June-2005
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2005 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15 //---------------------------------------------------------------------------
  16 %newgroup
  17
  18 %{
  19 #include "wx/renderer.h"
  20 %}
  21
  22
  23 // control state flags used in wxRenderer and wxColourScheme
  24 enum
  25 {
  26     wxCONTROL_DISABLED   = 0x00000001,  // control is disabled
  27     wxCONTROL_FOCUSED    = 0x00000002,  // currently has keyboard focus
  28     wxCONTROL_PRESSED    = 0x00000004,  // (button) is pressed
  29     wxCONTROL_ISDEFAULT  = 0x00000008,  // only applies to the buttons
  30     wxCONTROL_ISSUBMENU  = wxCONTROL_ISDEFAULT, // only for menu items
  31     wxCONTROL_EXPANDED   = wxCONTROL_ISDEFAULT, // only for the tree items
  32     wxCONTROL_CURRENT    = 0x00000010,  // mouse is currently over the control
  33     wxCONTROL_SELECTED   = 0x00000020,  // selected item in e.g. listbox
  34     wxCONTROL_CHECKED    = 0x00000040,  // (check/radio button) is checked
  35     wxCONTROL_CHECKABLE  = 0x00000080,  // (menu) item can be checked
  36     wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE, // (check) undetermined state
  37
  38     wxCONTROL_FLAGS_MASK = 0x000000ff,
  39
  40     // this is a pseudo flag not used directly by wxRenderer but rather by some
  41     // controls internally
  42     wxCONTROL_DIRTY      = 0x80000000
  43 };
  44
  45
  46
  47 DocStr(wxSplitterRenderParams,
  48 "This is just a simple struct used as a return value of
  49 `wx.RendererNative.GetSplitterParams` and contains some platform
  50 specific metrics about splitters.
  51
  52     * widthSash: the width of the splitter sash.
  53     * border: the width of the border of the splitter window.
  54     * isHotSensitive: ``True`` if the splitter changes its
  55       appearance when the mouse is over it.
  56
  57 ", "");
  58
  59 struct wxSplitterRenderParams
  60 {
  61     wxSplitterRenderParams(wxCoord widthSash_, wxCoord border_, bool isSens_);
  62     ~wxSplitterRenderParams();
  63
  64     // the width of the splitter sash
  65     const wxCoord widthSash;
  66
  67     // the width of the border of the splitter window
  68     const wxCoord border;
  69
  70     // true if the splitter changes its appearance when the mouse is over it
  71     const bool isHotSensitive;
  72 };
  73
  74
  75
  76
  77 DocStr(wxRendererVersion,
  78 "This simple struct represents the `wx.RendererNative` interface
  79 version and is only used as the return value of
  80 `wx.RendererNative.GetVersion`.", "");
  81
  82 struct wxRendererVersion
  83 {
  84     wxRendererVersion(int version_, int age_);
  85     ~wxRendererVersion();
  86
  87     enum
  88     {
  89         Current_Version,
  90         Current_Age
  91     };
  92
  93
  94     // check if the given version is compatible with the current one
  95     static bool IsCompatible(const wxRendererVersion& ver);
  96
  97     const int version;
  98     const int age;
  99 };
 100
 101 //---------------------------------------------------------------------------
 102
 103
 104 DocStr(wxRendererNative,
 105 "One of the design principles of wxWidgets is to use the native widgets
 106 on every platform in order to be as close to the native look and feel
 107 on every platform.  However there are still cases when some generic
 108 widgets are needed for various reasons, but it can sometimes take a
 109 lot of messy work to make them conform to the native LnF.
 110
 111 The wx.RendererNative class is a collection of functions that have
 112 platform-specific implementations for drawing certain parts of
 113 genereic controls in ways that are as close to the native look as
 114 possible.
 115
 116 Note that each drawing function restores the `wx.DC` attributes if it
 117 changes them, so it is safe to assume that the same pen, brush and
 118 colours that were active before the call to this function are still in
 119 effect after it.
 120 ", "");
 121
 122 class wxRendererNative
 123 {
 124 public:
 125
 126
 127     DocDeclStr(
 128         virtual void , DrawHeaderButton(wxWindow *win,
 129                                         wxDC& dc,
 130                                         const wxRect& rect,
 131                                         int flags = 0),
 132         "Draw the header control button (such as what is used by `wx.ListCtrl`
 133 in report mode.)", "");
 134
 135
 136
 137     DocDeclStr(
 138         virtual void , DrawTreeItemButton(wxWindow *win,
 139                                           wxDC& dc,
 140                                           const wxRect& rect,
 141                                           int flags = 0),
 142         "Draw the expanded/collapsed icon for a tree control item.", "");
 143
 144
 145     DocDeclStr(
 146         virtual void , DrawSplitterBorder(wxWindow *win,
 147                                           wxDC& dc,
 148                                           const wxRect& rect,
 149                                           int flags = 0),
 150         "Draw the border for a sash window: this border must be such that the
 151 sash drawn by `DrawSplitterSash` blends into it well.", "");
 152
 153
 154     DocDeclStr(
 155         virtual void , DrawSplitterSash(wxWindow *win,
 156                                         wxDC& dc,
 157                                         const wxSize& size,
 158                                         wxCoord position,
 159                                         wxOrientation orient,
 160                                         int flags = 0),
 161         "Draw a sash. The orient parameter defines whether the sash should be
 162 vertical or horizontal and how the position should be interpreted.", "");
 163
 164
 165     DocDeclStr(
 166         virtual void , DrawComboBoxDropButton(wxWindow *win,
 167                                               wxDC& dc,
 168                                               const wxRect& rect,
 169                                               int flags = 0),
 170         "Draw a button like the one used by `wx.ComboBox` to show a drop down
 171 window. The usual appearance is a downwards pointing arrow.
 172
 173 The ``flags`` parameter may have the ``wx.CONTROL_PRESSED`` or
 174 ``wx.CONTROL_CURRENT`` bits set.", "");
 175
 176
 177     DocDeclStr(
 178         virtual void , DrawDropArrow(wxWindow *win,
 179                                      wxDC& dc,
 180                                      const wxRect& rect,
 181                                      int flags = 0),
 182         "Draw a drop down arrow that is suitable for use outside a combo
 183 box. Arrow will have a transparent background.
 184
 185 ``rect`` is not entirely filled by the arrow. Instead, you should use
 186 bounding rectangle of a drop down button which arrow matches the size
 187 you need. ``flags`` may have the ``wx.CONTROL_PRESSED`` or
 188 ``wx.CONTROL_CURRENT`` bit set.", "");
 189
 190
 191     DocDeclStr(
 192         virtual void , DrawCheckBox(wxWindow *win,
 193                                     wxDC& dc,
 194                                     const wxRect& rect,
 195                                     int flags = 0),
 196         "Draw a check button.  Flags may use wx.CONTROL_CHECKED,
 197 wx.CONTROL_UNDETERMINED and wx.CONTROL_CURRENT.", "");
 198
 199
 200     DocDeclStr(
 201         virtual void , DrawPushButton(wxWindow *win,
 202                                       wxDC& dc,
 203                                       const wxRect& rect,
 204                                       int flags = 0),
 205         "Draw a blank button.  Flags may be wx.CONTROL_PRESSED, wx.CONTROL_CURRENT and
 206 wx.CONTROL_ISDEFAULT", "");
 207
 208
 209     DocDeclStr(
 210         virtual void , DrawItemSelectionRect(wxWindow *win,
 211                                              wxDC& dc,
 212                                              const wxRect& rect,
 213                                              int flags = 0),
 214         "Draw rectangle indicating that an item in e.g. a list control has been
 215 selected or focused
 216
 217 The flags parameter may be:
 218
 219     ====================  ============================================
 220     wx.CONTROL_SELECTED   item is selected, e.g. draw background
 221     wx.CONTROL_CURRENT    item is the current item, e.g. dotted border
 222     wx.CONTROL_FOCUSED    the whole control has focus, e.g. blue
 223                           background vs. grey otherwise
 224     ====================  ============================================
 225 ", "");
 226
 227
 228     DocDeclStr(
 229         virtual wxSplitterRenderParams , GetSplitterParams(const wxWindow *win),
 230         "Get the splitter parameters, see `wx.SplitterRenderParams`.", "");
 231
 232
 233
 234     MustHaveApp(Get);
 235     DocDeclStr(
 236         static wxRendererNative& , Get(),
 237         "Return the currently used renderer", "");
 238
 239
 240     MustHaveApp(GetGeneric);
 241     DocDeclStr(
 242         static wxRendererNative& , GetGeneric(),
 243         "Return the generic implementation of the renderer. Under some
 244 platforms, this is the default renderer implementation, others have
 245 platform-specific default renderer which can be retrieved by calling
 246 `GetDefault`.", "");
 247
 248
 249     MustHaveApp(GetDefault);
 250     DocDeclStr(
 251         static wxRendererNative& , GetDefault(),
 252         "Return the default (native) implementation for this platform -- this
 253 is also the one used by default but this may be changed by calling `Set`
 254 in which case the return value of this method may be different from
 255 the return value of `Get`.", "");
 256
 257
 258
 259
 260 //     // load the renderer from the specified DLL, the returned pointer must be
 261 //     // deleted by caller if not NULL when it is not used any more
 262 //     static wxRendererNative *Load(const wxString& name);
 263
 264
 265     MustHaveApp(Set);
 266     DocDeclStr(
 267         static wxRendererNative *, Set(wxRendererNative *renderer),
 268         "Set the renderer to use, passing None reverts to using the default
 269 renderer.  Returns the previous renderer used with Set or None.", "");
 270
 271
 272
 273     DocDeclStr(
 274         virtual wxRendererVersion , GetVersion() const,
 275         "Returns the version of the renderer.  Will be used for ensuring
 276 compatibility of dynamically loaded renderers.", "");
 277
 278 };
 279
 280
 281 //---------------------------------------------------------------------------