Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

revised b* headers; moved wxPenList and wxBrushList to the correct places; partially revised wxPen docs

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52578 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-03-17 00:47:38 +00:00
parent ed7ec76de3
commit 8024723d76
9 changed files with 659 additions and 839 deletions
Download Patch File Download Diff File Expand all files Collapse all files

436
interface/pen.h
View File

@@ -1,35 +1,165 @@
/////////////////////////////////////////////////////////////////////////////
// Name: pen.h
// Purpose: interface of wxPen
// Purpose: interface of wxPen* classes
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
The possible styles for a wxPen.
*/
enum wxPenStyle
{
wxPENSTYLE_SOLID,
/**< Solid style. */
wxPENSTYLE_DOT,
/**< Dotted style. */
wxPENSTYLE_LONG_DASH,
/**< Long dashed style. */
wxPENSTYLE_SHORT_DASH,
/**< Short dashed style. */
wxPENSTYLE_DOT_DASH,
/**< Dot and dash style. */
wxPENSTYLE_USER_DASH,
/**< Use the user dashes: see wxPen::SetDashes. */
wxPENSTYLE_TRANSPARENT,
/**< No pen is used. */
wxPENSTYLE_STIPPLE_MASK_OPAQUE,
/**< @todo WHAT's this? */
wxPENSTYLE_STIPPLE_MASK,
/**< @todo WHAT's this? */
wxPENSTYLE_STIPPLE,
/**< Use the stipple bitmap. */
wxPENSTYLE_BDIAGONAL_HATCH,
/**< Backward diagonal hatch. */
wxPENSTYLE_CROSSDIAG_HATCH,
/**< Cross-diagonal hatch. */
wxPENSTYLE_FDIAGONAL_HATCH,
/**< Forward diagonal hatch. */
wxPENSTYLE_CROSS_HATCH,
/**< Cross hatch. */
wxPENSTYLE_HORIZONTAL_HATCH,
/**< Horizontal hatch. */
wxPENSTYLE_VERTICAL_HATCH,
/**< Vertical hatch. */
wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH,
wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH,
wxPENSTYLE_MAX
};
/**
The possible join values of a wxPen.
@todo use wxPENJOIN_ prefix
*/
enum wxPenJoin
{
wxJOIN_INVALID = -1,
wxJOIN_BEVEL = 120,
wxJOIN_MITER,
wxJOIN_ROUND,
};
/**
The possible cap values of a wxPen.
@todo use wxPENCAP_ prefix
*/
enum wxPenCap
{
wxCAP_INVALID = -1,
wxCAP_ROUND = 130,
wxCAP_PROJECTING,
wxCAP_BUTT
};
/**
@class wxPen
@wxheader{pen.h}
A pen is a drawing tool for drawing outlines. It is used for drawing
lines and painting the outline of rectangles, ellipses, etc. It has a
colour, a width and a style.
lines and painting the outline of rectangles, ellipses, etc.
It has a colour, a width and a style.
On a monochrome display, wxWidgets shows all non-white pens as black.
Do not initialize objects on the stack before the program commences,
since other required structures may not have been set up yet.
Instead, define global pointers to objects and create them in wxApp::OnInit
or when required.
An application may wish to dynamically create pens with different characteristics,
and there is the consequent danger that a large number of duplicate pens will
be created. Therefore an application may wish to get a pointer to a pen by using
the global list of pens wxThePenList, and calling the member function
wxPenList::FindOrCreatePen().
See the entry for wxPenList.
This class uses reference counting and copy-on-write internally so that
assignments between two instances of this class are very cheap.
You can therefore use actual objects instead of pointers without efficiency problems.
If an instance of this class is changed it will create its own data internally
so that other instances, which previously shared the data using the reference
counting, are not affected.
@library{wxcore}
@category{gdi}
@stdobjects
::Objects:, ::wxNullPen, ::Pointers:, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN,
::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN,
::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN,
::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN,
::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN
@see wxPenList, wxDC, wxDC::SetPen
*/
class wxPen : public wxGDIObject
{
public:
//@{
/**
Copy constructor, uses @ref overview_trefcount "reference counting".
Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
*/
wxPen();
/**
Constructs a pen from a colour object, pen width and style.
*/
wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxSOLID);
/**
Constructs a pen from a colour name, pen width and style.
*/
wxPen(const wxString& colourName, int width, wxPenStyle style);
/**
Constructs a stippled pen from a stipple bitmap and a width.
*/
wxPen(const wxBitmap& stipple, int width);
/**
Copy constructor, uses @ref overview_refcount "reference counting".
@param colour
A colour object.
@param colourName
@@ -42,183 +172,22 @@ public:
@param pen
A pointer or reference to a pen to copy.
@param style
The style may be one of the following:
wxSOLID
Solid style.
wxTRANSPARENT
No pen is used.
wxDOT
Dotted style.
wxLONG_DASH
Long dashed style.
wxSHORT_DASH
Short dashed style.
wxDOT_DASH
Dot and dash style.
wxSTIPPLE
Use the stipple bitmap.
wxUSER_DASH
Use the user dashes: see SetDashes().
wxBDIAGONAL_HATCH
Backward diagonal hatch.
wxCROSSDIAG_HATCH
Cross-diagonal hatch.
wxFDIAGONAL_HATCH
Forward diagonal hatch.
wxCROSS_HATCH
Cross hatch.
wxHORIZONTAL_HATCH
Horizontal hatch.
wxVERTICAL_HATCH
Vertical hatch.
The style may be one of the ::wxPenStyle values.
@remarks Different versions of Windows and different versions of other
platforms support very different subsets of the styles
above - there is no similarity even between Windows95
and Windows98 - so handle with care.
@see SetStyle(), SetColour(), SetWidth(), SetStipple()
*/
wxPen();
wxPen(const wxColour& colour, int width = 1,
int style = wxSOLID);
wxPen(const wxString& colourName, int width, int style);
wxPen(const wxBitmap& stipple, int width);
wxPen(const wxPen& pen);
//@}
/**
Destructor.
See @ref overview_refcountdestruct "reference-counted object destruction" for
more info.
@remarks Although all remaining pens are deleted when the application
exits, the application should try to clean up all pens
itself. This is because wxWidgets cannot know if a
@@ -231,14 +200,14 @@ public:
Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
wxCAP_PROJECTING and
@b wxCAP_BUTT. The default is @b wxCAP_ROUND.
@see SetCap()
*/
int GetCap() const;
wxPenCap GetCap() const;
/**
Returns a reference to the pen colour.
@see SetColour()
*/
wxColour GetColour() const;
@@ -248,7 +217,7 @@ public:
@a dashes is a pointer to the internal array. Do not deallocate or store this
pointer.
The function returns the number of dashes associated with this pen.
@see SetDashes()
*/
int GetDashes(wxDash** dashes) const;
@@ -257,28 +226,28 @@ public:
Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
wxJOIN_ROUND and
@b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
@see SetJoin()
*/
int GetJoin() const;
wxPenJoin GetJoin() const;
/**
Gets a pointer to the stipple bitmap.
@see SetStipple()
*/
wxBitmap* GetStipple() const;
/**
Returns the pen style.
@see wxPen(), SetStyle()
*/
int GetStyle() const;
wxPenStyle GetStyle() const;
/**
Returns the pen width.
@see SetWidth()
*/
int GetWidth() const;
@@ -292,15 +261,15 @@ public:
Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
and
@b wxCAP_BUTT. The default is @b wxCAP_ROUND.
@see GetCap()
*/
void SetCap(int capStyle);
void SetCap(wxPenCap capStyle);
//@{
/**
The pen's colour is changed to the given colour.
@see GetColour()
*/
void SetColour(wxColour& colour);
@@ -315,7 +284,7 @@ public:
with the pen. The array is not deallocated by wxPen, but neither must it be
deallocated by the calling application until the pen is deleted or this
function is called with a @NULL array.
@see GetDashes()
*/
void SetDashes(int n, wxDash* dashes);
@@ -324,28 +293,28 @@ public:
Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
and
@b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
@see GetJoin()
*/
void SetJoin(int join_style);
void SetJoin(wxPenJoin join_style);
/**
Sets the bitmap for stippling.
@see GetStipple()
*/
void SetStipple(wxBitmap* stipple);
/**
Set the pen style.
@see wxPen()
*/
void SetStyle(int style);
void SetStyle(wxPenStyle style);
/**
Sets the pen width.
@see GetWidth()
*/
void SetWidth(int width);
@@ -370,24 +339,11 @@ public:
bool operator ==(const wxPen& pen);
};
/**
FIXME
*/
wxPen Objects:
;
/**
FIXME
*/
wxPen wxNullPen;
/**
FIXME
*/
wxPen Pointers:
;
/**
FIXME
*/
@@ -439,3 +395,71 @@ wxPen wxMEDIUM_GREY_PEN;
wxPen wxLIGHT_GREY_PEN;
/**
@class wxPenList
@wxheader{gdicmn.h}
There is only one instance of this class: ::wxThePenList.
Use this object to search for a previously created pen of the desired
type and create it if not already found. In some windowing systems,
the pen may be a scarce resource, so it can pay to reuse old
resources if possible. When an application finishes, all pens will
be deleted and their resources freed, eliminating the possibility of
'memory leaks'. However, it is best not to rely on this automatic
cleanup because it can lead to double deletion in some circumstances.
There are two mechanisms in recent versions of wxWidgets which make the
pen list less useful than it once was. Under Windows, scarce resources
are cleaned up internally if they are not being used. Also, a referencing
counting mechanism applied to all GDI objects means that some sharing
of underlying resources is possible. You don't have to keep track of pointers,
working out when it is safe delete a pen, because the referencing counting does
it for you. For example, you can set a pen in a device context, and then
immediately delete the pen you passed, because the pen is 'copied'.
So you may find it easier to ignore the pen list, and instead create
and copy pens as you see fit. If your Windows resource meter suggests
your application is using too many resources, you can resort to using
GDI lists to share objects explicitly.
The only compelling use for the pen list is for wxWidgets to keep
track of pens in order to clean them up on exit. It is also kept for
backward compatibility with earlier versions of wxWidgets.
@library{wxcore}
@category{gdi}
@stdobjects
::wxThePenList
@see wxPen
*/
class wxPenList
{
public:
/**
Constructor. The application should not construct its own pen list:
use the object pointer ::wxThePenList.
*/
wxPenList();
/**
Finds a pen with the specified attributes and returns it, else creates a
new pen, adds it to the pen list, and returns it.
@param colour
Colour object.
@param width
Width of pen.
@param style
Pen style. See ::wxPenStyle for a list of styles.
*/
wxPen* FindOrCreatePen(const wxColour& colour, int width, wxPenStyle style);
};
/**
The global list of wxPen objects ready to be re-used (for better performances).
*/
wxPenList* wxThePenList;