wxPython/src/_renderer.i

/////////////////////////////////////////////////////////////////////////////
// Name:        _renderer.i
// Purpose:     SWIG interface for wxRendererNative
//
// Author:      Robin Dunn
//
// Created:     9-June-2005
// RCS-ID:      $Id$
// Copyright:   (c) 2005 by Total Control Software
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

// Not a %module

//---------------------------------------------------------------------------
%newgroup

%{
#include "wx/renderer.h"
%}


// control state flags used in wxRenderer and wxColourScheme
enum
{
    wxCONTROL_DISABLED   = 0x00000001,  // control is disabled
    wxCONTROL_FOCUSED    = 0x00000002,  // currently has keyboard focus
    wxCONTROL_PRESSED    = 0x00000004,  // (button) is pressed
    wxCONTROL_ISDEFAULT  = 0x00000008,  // only applies to the buttons
    wxCONTROL_ISSUBMENU  = wxCONTROL_ISDEFAULT, // only for menu items
    wxCONTROL_EXPANDED   = wxCONTROL_ISDEFAULT, // only for the tree items
    wxCONTROL_CURRENT    = 0x00000010,  // mouse is currently over the control
    wxCONTROL_SELECTED   = 0x00000020,  // selected item in e.g. listbox
    wxCONTROL_CHECKED    = 0x00000040,  // (check/radio button) is checked
    wxCONTROL_CHECKABLE  = 0x00000080,  // (menu) item can be checked
    wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE, // (check) undetermined state

    wxCONTROL_FLAGS_MASK = 0x000000ff,

    // this is a pseudo flag not used directly by wxRenderer but rather by some
    // controls internally
    wxCONTROL_DIRTY      = 0x80000000
};


DocStr(wxSplitterRenderParams,
"This is just a simple struct used as a return value of
`wx.RendererNative.GetSplitterParams` and contains some platform
specific metrics about splitters.

    * widthSash: the width of the splitter sash.
    * border: the width of the border of the splitter window.
    * isHotSensitive: ``True`` if the splitter changes its
      appearance when the mouse is over it.

", "");

struct wxSplitterRenderParams
{
    wxSplitterRenderParams(wxCoord widthSash_, wxCoord border_, bool isSens_);
    ~wxSplitterRenderParams();

    // the width of the splitter sash
    const wxCoord widthSash;

    // the width of the border of the splitter window
    const wxCoord border;

    // true if the splitter changes its appearance when the mouse is over it
    const bool isHotSensitive;
};


DocStr(wxRendererVersion,
"This simple struct represents the `wx.RendererNative` interface
version and is only used as the return value of
`wx.RendererNative.GetVersion`.", "");

struct wxRendererVersion
{
    wxRendererVersion(int version_, int age_);
    ~wxRendererVersion();

    enum
    {
        Current_Version,
        Current_Age
    };


    // check if the given version is compatible with the current one
    static bool IsCompatible(const wxRendererVersion& ver);

    const int version;
    const int age;
};

//---------------------------------------------------------------------------


DocStr(wxRendererNative,
"One of the design principles of wxWidgets is to use the native widgets
on every platform in order to be as close to the native look and feel
on every platform.  However there are still cases when some generic
widgets are needed for various reasons, but it can sometimes take a
lot of messy work to make them conform to the native LnF.

The wx.RendererNative class is a collection of functions that have
platform-specific implementations for drawing certain parts of
genereic controls in ways that are as close to the native look as
possible.
", "");

class wxRendererNative
{
public:


    DocDeclStr(
        virtual void , DrawHeaderButton(wxWindow *win,
                                        wxDC& dc,
                                        const wxRect& rect,
                                        int flags = 0),
        "Draw the header control button (such as what is used by `wx.ListCtrl`
in report mode.)", "");


    DocDeclStr(
        virtual void , DrawTreeItemButton(wxWindow *win,
                                          wxDC& dc,
                                          const wxRect& rect,
                                          int flags = 0),
        "Draw the expanded/collapsed icon for a tree control item.", "");


    DocDeclStr(
        virtual void , DrawSplitterBorder(wxWindow *win,
                                          wxDC& dc,
                                          const wxRect& rect,
                                          int flags = 0),
        "Draw the border for a sash window: this border must be such that the
sash drawn by `DrawSplitterSash` blends into it well.", "");


    DocDeclStr(
        virtual void , DrawSplitterSash(wxWindow *win,
                                        wxDC& dc,
                                        const wxSize& size,
                                        wxCoord position,
                                        wxOrientation orient,
                                        int flags = 0),
        "Draw a sash. The orient parameter defines whether the sash should be
vertical or horizontal and how the position should be interpreted.", "");


    DocDeclStr(
        virtual void , DrawComboBoxDropButton(wxWindow *win,
                                              wxDC& dc,
                                              const wxRect& rect,
                                              int flags = 0),
        "Draw a button like the one used by `wx.ComboBox` to show a drop down
window. The usual appearance is a downwards pointing arrow.

The ``flags`` parameter may have the ``wx.CONTROL_PRESSED`` or
``wx.CONTROL_CURRENT`` bits set.", "");


    DocDeclStr(
        virtual void , DrawDropArrow(wxWindow *win,
                                     wxDC& dc,
                                     const wxRect& rect,
                                     int flags = 0),
        "Draw a drop down arrow that is suitable for use outside a combo
box. Arrow will have a transparent background.

``rect`` is not entirely filled by the arrow. Instead, you should use
bounding rectangle of a drop down button which arrow matches the size
you need. ``flags`` may have the ``wx.CONTROL_PRESSED`` or
``wx.CONTROL_CURRENT`` bit set.", "");


    DocDeclStr(
        virtual void , DrawCheckBox(wxWindow *win,
                                    wxDC& dc,
                                    const wxRect& rect,
                                    int flags = 0),
        "Draw a check button.  Flags may use wx.CONTROL_CHECKED,
wx.CONTROL_UNDETERMINED and wx.CONTROL_CURRENT.", "");


    DocDeclStr(
        virtual void , DrawPushButton(wxWindow *win,
                                      wxDC& dc,
                                      const wxRect& rect,
                                      int flags = 0),
        "Draw a blank button.  Flags may be wx.CONTROL_PRESSED, wx.CONTROL_CURRENT and
wx.CONTROL_ISDEFAULT", "");


    DocDeclStr(
        virtual void , DrawItemSelectionRect(wxWindow *win,
                                             wxDC& dc,
                                             const wxRect& rect,
                                             int flags = 0),
        "Draw rectangle indicating that an item in e.g. a list control has been
selected or focused

The flags parameter may be:

    ====================  ============================================
    wx.CONTROL_SELECTED   item is selected, e.g. draw background
    wx.CONTROL_CURRENT    item is the current item, e.g. dotted border
    wx.CONTROL_FOCUSED    the whole control has focus, e.g. blue
                          background vs. grey otherwise
    ====================  ============================================
", "");


    DocDeclStr(
        virtual wxSplitterRenderParams , GetSplitterParams(const wxWindow *win),
        "Get the splitter parameters, see `wx.SplitterRenderParams`.", "");


    DocDeclStr(
        static wxRendererNative& , Get(),
        "Return the currently used renderer", "");


    DocDeclStr(
        static wxRendererNative& , GetGeneric(),
        "Return the generic implementation of the renderer. Under some
platforms, this is the default renderer implementation, others have
platform-specific default renderer which can be retrieved by calling
`GetDefault`.", "");


    DocDeclStr(
        static wxRendererNative& , GetDefault(),
        "Return the default (native) implementation for this platform -- this
is also the one used by default but this may be changed by calling `Set`
in which case the return value of this method may be different from
the return value of `Get`.", "");


//     // load the renderer from the specified DLL, the returned pointer must be
//     // deleted by caller if not NULL when it is not used any more
//     static wxRendererNative *Load(const wxString& name);


    DocDeclStr(
        static wxRendererNative *, Set(wxRendererNative *renderer),
        "Set the renderer to use, passing None reverts to using the default
renderer.  Returns the previous renderer used with Set or None.", "");


    DocDeclStr(
        virtual wxRendererVersion , GetVersion() const,
        "Returns the version of the renderer.  Will be used for ensuring
compatibility of dynamically loaded renderers.", "");

};


//---------------------------------------------------------------------------
Commit	Line	Data
	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
	117	class wxRendererNative
	118	{
	119	public:
	120
	121
	122	DocDeclStr(
	123	virtual void , DrawHeaderButton(wxWindow *win,
	124	wxDC& dc,
	125	const wxRect& rect,
	126	int flags = 0),
	127	"Draw the header control button (such as what is used by `wx.ListCtrl`
	128	in report mode.)", "");
	129
	130
	131
	132	DocDeclStr(
	133	virtual void , DrawTreeItemButton(wxWindow *win,
	134	wxDC& dc,
	135	const wxRect& rect,
	136	int flags = 0),
	137	"Draw the expanded/collapsed icon for a tree control item.", "");
	138
	139
	140	DocDeclStr(
	141	virtual void , DrawSplitterBorder(wxWindow *win,
	142	wxDC& dc,
	143	const wxRect& rect,
	144	int flags = 0),
	145	"Draw the border for a sash window: this border must be such that the
	146	sash drawn by `DrawSplitterSash` blends into it well.", "");
	147
	148
	149	DocDeclStr(
	150	virtual void , DrawSplitterSash(wxWindow *win,
	151	wxDC& dc,
	152	const wxSize& size,
	153	wxCoord position,
	154	wxOrientation orient,
	155	int flags = 0),
	156	"Draw a sash. The orient parameter defines whether the sash should be
	157	vertical or horizontal and how the position should be interpreted.", "");
	158
	159
	160	DocDeclStr(
	161	virtual void , DrawComboBoxDropButton(wxWindow *win,
	162	wxDC& dc,
	163	const wxRect& rect,
	164	int flags = 0),
	165	"Draw a button like the one used by `wx.ComboBox` to show a drop down
	166	window. The usual appearance is a downwards pointing arrow.
	167
	168	The ``flags`` parameter may have the ``wx.CONTROL_PRESSED`` or
	169	``wx.CONTROL_CURRENT`` bits set.", "");
	170
	171
	172	DocDeclStr(
	173	virtual void , DrawDropArrow(wxWindow *win,
	174	wxDC& dc,
	175	const wxRect& rect,
	176	int flags = 0),
	177	"Draw a drop down arrow that is suitable for use outside a combo
	178	box. Arrow will have a transparent background.
	179
	180	``rect`` is not entirely filled by the arrow. Instead, you should use
	181	bounding rectangle of a drop down button which arrow matches the size
	182	you need. ``flags`` may have the ``wx.CONTROL_PRESSED`` or
	183	``wx.CONTROL_CURRENT`` bit set.", "");
	184
	185
	186	DocDeclStr(
	187	virtual void , DrawCheckBox(wxWindow *win,
	188	wxDC& dc,
	189	const wxRect& rect,
	190	int flags = 0),
	191	"Draw a check button. Flags may use wx.CONTROL_CHECKED,
	192	wx.CONTROL_UNDETERMINED and wx.CONTROL_CURRENT.", "");
	193
	194
	195	DocDeclStr(
	196	virtual void , DrawPushButton(wxWindow *win,
	197	wxDC& dc,
	198	const wxRect& rect,
	199	int flags = 0),
	200	"Draw a blank button. Flags may be wx.CONTROL_PRESSED, wx.CONTROL_CURRENT and
	201	wx.CONTROL_ISDEFAULT", "");
	202
	203
	204	DocDeclStr(
	205	virtual void , DrawItemSelectionRect(wxWindow *win,
	206	wxDC& dc,
	207	const wxRect& rect,
	208	int flags = 0),
	209	"Draw rectangle indicating that an item in e.g. a list control has been
	210	selected or focused
	211
	212	The flags parameter may be:
	213
	214	==================== ============================================
	215	wx.CONTROL_SELECTED item is selected, e.g. draw background
	216	wx.CONTROL_CURRENT item is the current item, e.g. dotted border
	217	wx.CONTROL_FOCUSED the whole control has focus, e.g. blue
	218	background vs. grey otherwise
	219	==================== ============================================
	220	", "");
	221
	222
	223	DocDeclStr(
	224	virtual wxSplitterRenderParams , GetSplitterParams(const wxWindow *win),
	225	"Get the splitter parameters, see `wx.SplitterRenderParams`.", "");
	226
	227
	228
	229
	230	DocDeclStr(
	231	static wxRendererNative& , Get(),
	232	"Return the currently used renderer", "");
	233
	234
	235	DocDeclStr(
	236	static wxRendererNative& , GetGeneric(),
	237	"Return the generic implementation of the renderer. Under some
	238	platforms, this is the default renderer implementation, others have
	239	platform-specific default renderer which can be retrieved by calling
	240	`GetDefault`.", "");
	241
	242
	243	DocDeclStr(
	244	static wxRendererNative& , GetDefault(),
	245	"Return the default (native) implementation for this platform -- this
	246	is also the one used by default but this may be changed by calling `Set`
	247	in which case the return value of this method may be different from
	248	the return value of `Get`.", "");
	249
	250
	251
	252
	253	// // load the renderer from the specified DLL, the returned pointer must be
	254	// // deleted by caller if not NULL when it is not used any more
	255	// static wxRendererNative *Load(const wxString& name);
	256
	257
	258	DocDeclStr(
	259	static wxRendererNative , Set(wxRendererNative renderer),
	260	"Set the renderer to use, passing None reverts to using the default
	261	renderer. Returns the previous renderer used with Set or None.", "");
	262
	263
	264
	265	DocDeclStr(
	266	virtual wxRendererVersion , GetVersion() const,
	267	"Returns the version of the renderer. Will be used for ensuring
	268	compatibility of dynamically loaded renderers.", "");
	269
	270	};
	271
	272
	273	//---------------------------------------------------------------------------