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