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.

Note that each drawing function restores the `wx.DC` attributes if it
changes them, so it is safe to assume that the same pen, brush and
colours that were active before the call to this function are still in
effect after it.
", "");

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`.", "");


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


    MustHaveApp(GetGeneric);
    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`.", "");


    MustHaveApp(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);


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