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