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     wxCONTROL_UPICON     = 0x00000100,  // header button has an up arrow icon
  38     wxCONTROL_DOWNICON   = 0x00000200,  // header button has a down arrow icon
  39
  40     wxCONTROL_FLAGS_MASK = 0x000002ff,
  41
  42     // this is a pseudo flag not used directly by wxRenderer but rather by some
  43     // controls internally
  44     wxCONTROL_DIRTY      = 0x80000000
  45 };
  46
  47
  48
  49 DocStr(wxSplitterRenderParams,
  50 "This is just a simple struct used as a return value of
  51 `wx.RendererNative.GetSplitterParams` and contains some platform
  52 specific metrics about splitters.
  53
  54     * widthSash: the width of the splitter sash.
  55     * border: the width of the border of the splitter window.
  56     * isHotSensitive: ``True`` if the splitter changes its
  57       appearance when the mouse is over it.
  58
  59 ", "");
  60
  61 struct wxSplitterRenderParams
  62 {
  63     wxSplitterRenderParams(wxCoord widthSash_, wxCoord border_, bool isSens_);
  64     ~wxSplitterRenderParams();
  65
  66     // the width of the splitter sash
  67     const wxCoord widthSash;
  68
  69     // the width of the border of the splitter window
  70     const wxCoord border;
  71
  72     // true if the splitter changes its appearance when the mouse is over it
  73     const bool isHotSensitive;
  74 };
  75
  76
  77
  78 DocStr(wxHeaderButtonParams,
  79 "Extra (optional) parameters for `wx.RendererNative.DrawHeaderButton`", "");
  80
  81 struct wxHeaderButtonParams
  82 {
  83     wxHeaderButtonParams();
  84     ~wxHeaderButtonParams();
  85
  86     // So wxColour_helper will be used when assigning to the colour items in the struct
  87     %typemap(in) wxColour* (wxColour temp) {
  88         $1 = &temp;
  89         if ( ! wxColour_helper($input, &$1)) SWIG_fail;
  90     }
  91     wxColour    m_arrowColour;
  92     wxColour    m_selectionColour;
  93     wxString    m_labelText;
  94     wxFont      m_labelFont;
  95     wxColour    m_labelColour;
  96     wxBitmap    m_labelBitmap;
  97     int         m_labelAlignment;
  98 };
  99
 100
 101
 102 DocStr(wxRendererVersion,
 103 "This simple struct represents the `wx.RendererNative` interface
 104 version and is only used as the return value of
 105 `wx.RendererNative.GetVersion`.", "");
 106
 107 struct wxRendererVersion
 108 {
 109     wxRendererVersion(int version_, int age_);
 110     ~wxRendererVersion();
 111
 112     enum
 113     {
 114         Current_Version,
 115         Current_Age
 116     };
 117
 118
 119     // check if the given version is compatible with the current one
 120     static bool IsCompatible(const wxRendererVersion& ver);
 121
 122     const int version;
 123     const int age;
 124 };
 125
 126 //---------------------------------------------------------------------------
 127
 128
 129 DocStr(wxRendererNative,
 130 "One of the design principles of wxWidgets is to use the native
 131 widgets on every platform in order to be as close as possible to
 132 the native look and feel on every platform.  However there are
 133 still cases when some generic widgets are needed for various
 134 reasons, but it can sometimes take a lot of messy work to make
 135 them conform to the native LnF.
 136
 137 The wx.RendererNative class is a collection of functions that have
 138 platform-specific implementations for drawing certain parts of
 139 genereic controls in ways that are as close to the native look as
 140 possible.
 141
 142 Note that each drawing function restores the `wx.DC` attributes if it
 143 changes them, so it is safe to assume that the same pen, brush and
 144 colours that were active before the call to this function are still in
 145 effect after it.
 146 ", "");
 147
 148 class wxRendererNative
 149 {
 150 public:
 151
 152
 153     DocDeclStr(
 154         virtual void , DrawHeaderButton(wxWindow *win,
 155                                         wxDC& dc,
 156                                         const wxRect& rect,
 157                                         int flags = 0,
 158                                         wxHeaderButtonParams* params=NULL),
 159         "Draw the header control button (such as what is used by `wx.ListCtrl`
 160 in report mode.)", "");
 161
 162
 163     DocDeclStr(
 164         virtual void , DrawHeaderButtonContents(wxWindow *win,
 165                                                 wxDC& dc,
 166                                                 const wxRect& rect,
 167                                                 int flags = 0,
 168                                                 wxHeaderButtonParams* params=NULL),
 169         "Draw the contents of a header control button, (label, sort
 170 arrows, etc.)  Normally this is only called by `DrawHeaderButton`.", "");
 171
 172     DocDeclStr(
 173         virtual int , GetHeaderButtonHeight(wxWindow *win),
 174         "Returns the default height of a header button, either a fixed platform
 175 height if available, or a generic height based on the window's font.", "");
 176
 177
 178     DocDeclStr(
 179         virtual void , DrawTreeItemButton(wxWindow *win,
 180                                           wxDC& dc,
 181                                           const wxRect& rect,
 182                                           int flags = 0),
 183         "Draw the expanded/collapsed icon for a tree control item.", "");
 184
 185
 186     DocDeclStr(
 187         virtual void , DrawSplitterBorder(wxWindow *win,
 188                                           wxDC& dc,
 189                                           const wxRect& rect,
 190                                           int flags = 0),
 191         "Draw the border for a sash window: this border must be such that the
 192 sash drawn by `DrawSplitterSash` blends into it well.", "");
 193
 194
 195     DocDeclStr(
 196         virtual void , DrawSplitterSash(wxWindow *win,
 197                                         wxDC& dc,
 198                                         const wxSize& size,
 199                                         wxCoord position,
 200                                         wxOrientation orient,
 201                                         int flags = 0),
 202         "Draw a sash. The orient parameter defines whether the sash should be
 203 vertical or horizontal and how the position should be interpreted.", "");
 204
 205
 206     DocDeclStr(
 207         virtual void , DrawComboBoxDropButton(wxWindow *win,
 208                                               wxDC& dc,
 209                                               const wxRect& rect,
 210                                               int flags = 0),
 211         "Draw a button like the one used by `wx.ComboBox` to show a drop down
 212 window. The usual appearance is a downwards pointing arrow.
 213
 214 The ``flags`` parameter may have the ``wx.CONTROL_PRESSED`` or
 215 ``wx.CONTROL_CURRENT`` bits set.", "");
 216
 217
 218     DocDeclStr(
 219         virtual void , DrawDropArrow(wxWindow *win,
 220                                      wxDC& dc,
 221                                      const wxRect& rect,
 222                                      int flags = 0),
 223         "Draw a drop down arrow that is suitable for use outside a combo
 224 box. Arrow will have a transparent background.
 225
 226 ``rect`` is not entirely filled by the arrow. Instead, you should use
 227 bounding rectangle of a drop down button which arrow matches the size
 228 you need. ``flags`` may have the ``wx.CONTROL_PRESSED`` or
 229 ``wx.CONTROL_CURRENT`` bit set.", "");
 230
 231
 232     DocDeclStr(
 233         virtual void , DrawCheckBox(wxWindow *win,
 234                                     wxDC& dc,
 235                                     const wxRect& rect,
 236                                     int flags = 0),
 237         "Draw a check button.  Flags may use wx.CONTROL_CHECKED,
 238 wx.CONTROL_UNDETERMINED and wx.CONTROL_CURRENT.", "");
 239
 240
 241     DocDeclStr(
 242         virtual void , DrawPushButton(wxWindow *win,
 243                                       wxDC& dc,
 244                                       const wxRect& rect,
 245                                       int flags = 0),
 246         "Draw a blank button.  Flags may be wx.CONTROL_PRESSED, wx.CONTROL_CURRENT and
 247 wx.CONTROL_ISDEFAULT", "");
 248
 249
 250     DocDeclStr(
 251         virtual void , DrawItemSelectionRect(wxWindow *win,
 252                                              wxDC& dc,
 253                                              const wxRect& rect,
 254                                              int flags = 0),
 255         "Draw rectangle indicating that an item in e.g. a list control has been
 256 selected or focused
 257
 258 The flags parameter may be:
 259
 260     ====================  ============================================
 261     wx.CONTROL_SELECTED   item is selected, e.g. draw background
 262     wx.CONTROL_CURRENT    item is the current item, e.g. dotted border
 263     wx.CONTROL_FOCUSED    the whole control has focus, e.g. blue
 264                           background vs. grey otherwise
 265     ====================  ============================================
 266 ", "");
 267
 268
 269     DocDeclStr(
 270         virtual wxSplitterRenderParams , GetSplitterParams(const wxWindow *win),
 271         "Get the splitter parameters, see `wx.SplitterRenderParams`.", "");
 272
 273
 274
 275     MustHaveApp(Get);
 276     DocDeclStr(
 277         static wxRendererNative& , Get(),
 278         "Return the currently used renderer", "");
 279
 280
 281     MustHaveApp(GetGeneric);
 282     DocDeclStr(
 283         static wxRendererNative& , GetGeneric(),
 284         "Return the generic implementation of the renderer. Under some
 285 platforms, this is the default renderer implementation, others have
 286 platform-specific default renderer which can be retrieved by calling
 287 `wx.RendererNative.GetDefault`.", "");
 288
 289
 290     MustHaveApp(GetDefault);
 291     DocDeclStr(
 292         static wxRendererNative& , GetDefault(),
 293         "Return the default (native) implementation for this platform -- this
 294 is also the one used by default but this may be changed by calling
 295 `wx.RendererNative.Set` in which case the return value of this method
 296 may be different from the return value of `wx.RendererNative.Get`.", "");
 297
 298
 299
 300
 301 //     // load the renderer from the specified DLL, the returned pointer must be
 302 //     // deleted by caller if not NULL when it is not used any more
 303 //     static wxRendererNative *Load(const wxString& name);
 304
 305
 306     MustHaveApp(Set);
 307     DocDeclStr(
 308         static wxRendererNative *, Set(wxRendererNative *renderer),
 309         "Set the renderer to use, passing None reverts to using the default
 310 renderer.  Returns the previous renderer used with Set or None.", "");
 311
 312
 313
 314     DocDeclStr(
 315         virtual wxRendererVersion , GetVersion() const,
 316         "Returns the version of the renderer.  Will be used for ensuring
 317 compatibility of dynamically loaded renderers.", "");
 318
 319
 320     %property(SplitterParams, GetSplitterParams, doc="See `GetSplitterParams`");
 321     %property(Version, GetVersion, doc="See `GetVersion`");
 322 };
 323
 324
 325 //---------------------------------------------------------------------------