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