// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ In wxBitmap and wxBitmapHandler context this value means: "use the screen depth".
+*/
+#define wxBITMAP_SCREEN_DEPTH (-1)
+
/**
@class wxBitmapHandler
@wxheader{bitmap.h}
@param height
The height of the bitmap in pixels.
@param depth
- The depth of the bitmap in pixels. If this is -1, the screen depth is used.
+ The depth of the bitmap in pixels.
+ If this is ::wxBITMAP_SCREEN_DEPTH, the screen depth is used.
@param data
Data whose type depends on the value of type.
@param type
A bitmap type identifier - see ::wxBitmapType for a list
of possible values.
-@todo why type is an int and not a wxBitmapType?
-
@returns @true if the call succeeded, @false otherwise (the default).
*/
- virtual bool Create(wxBitmap* bitmap, const void* data, int type,
- int width, int height, int depth = -1);
+ virtual bool Create(wxBitmap* bitmap, const void* data, wxBitmapType type,
+ int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
/**
Gets the file extension associated with this handler.
*/
- const wxString GetExtension() const;
+ const wxString& GetExtension() const;
/**
Gets the name of this handler.
*/
- const wxString GetName() const;
+ const wxString& GetName() const;
/**
Gets the bitmap type associated with this handler.
-@todo why type is an int and not a wxBitmapType?
*/
- long GetType() const;
+ wxBitmapType GetType() const;
/**
Loads a bitmap from a file or resource, putting the resulting data into
Either a filename or a Windows resource name.
The meaning of name is determined by the type parameter.
@param type
- See wxBitmap::wxBitmap for values this can take.
+ See ::wxBitmapType for values this can take.
@returns @true if the operation succeeded, @false otherwise.
-@todo why type is an int and not a wxBitmapType?
-
@see wxBitmap::LoadFile, wxBitmap::SaveFile, SaveFile()
*/
- bool LoadFile(wxBitmap* bitmap, const wxString& name, long type);
+ bool LoadFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type);
/**
Saves a bitmap in the named file.
@param name
A filename. The meaning of name is determined by the type parameter.
@param type
- See wxBitmap::wxBitmap for values this can take.
+ See ::wxBitmapType for values this can take.
@param palette
An optional palette used for saving the bitmap.
@returns @true if the operation succeeded, @false otherwise.
-@todo why type is an int and not a wxBitmapType?
-
@see wxBitmap::LoadFile, wxBitmap::SaveFile, LoadFile()
*/
- bool SaveFile(wxBitmap* bitmap, const wxString& name, int type,
+ bool SaveFile(wxBitmap* bitmap, const wxString& name, wxBitmapType type,
wxPalette* palette = NULL);
/**
/**
Sets the handler type.
-@todo why type is an int and not a wxBitmapType?
-
@param type
Handler type.
*/
- void SetType(long type);
+ void SetType(wxBitmapType type);
};
either monochrome or colour or colour with alpha channel support.
@note
- Many wxBitmap functions take a @e type parameter, which is a value of
- the ::wxBitmapType enumeration.
+ Many wxBitmap functions take a @e type parameter, which is a value of the
+ ::wxBitmapType enumeration.
The validity of those values depends however on the platform where your program
is running and from the wxWidgets configuration.
If all possible wxWidgets settings are used, the Windows platform supports BMP file,
*/
wxBitmap(const wxBitmap& bitmap);
- /**
+
+ /*
Creates a bitmap from the given @a data which is interpreted in
platform-dependent manner.
@param depth
Specifies the depth of the bitmap.
If this is omitted, the display depth of the screen is used.
+ wxBitmap(const void* data, int type, int width, int height, int depth = -1);
-@todo why type is an int and not a wxBitmapType?
+ NOTE: this ctor is not implemented by all port, is somewhat useless
+ without further description of the "data" supported formats and
+ uses 'int type' instead of wxBitmapType, so don't document it.
*/
- wxBitmap(const void* data, int type, int width, int height, int depth = -1);
/**
Creates a bitmap from the given array @a bits.
For other bit depths, the behaviour is platform dependent: under Windows,
the data is passed without any changes to the underlying CreateBitmap() API.
- Under other platforms, only monochrome bitmaps may be created using this constructor
- and wxImage should be used for creating colour bitmaps from static data.
+ Under other platforms, only monochrome bitmaps may be created using this
+ constructor and wxImage should be used for creating colour bitmaps from
+ static data.
@param bits
Specifies an array of pixel values.
Specifies the height of the bitmap.
@param depth
Specifies the depth of the bitmap.
- If this is omitted, the display depth of the screen is used.
+ If this is omitted, then a value of 1 (monochrome bitmap) is used.
*/
wxBitmap(const char bits[], int width, int height, int depth = 1);
/**
- Creates a new bitmap. A depth of -1 indicates the depth of the current
- screen or visual. Some platforms only support 1 for monochrome and -1 for
+ Creates a new bitmap. A depth of ::wxBITMAP_SCREEN_DEPTH indicates the
+ depth of the current screen or visual.
+ Some platforms only support 1 for monochrome and ::wxBITMAP_SCREEN_DEPTH for
the current colour setting.
A depth of 32 including an alpha channel is supported under MSW, Mac and GTK+.
*/
- wxBitmap(int width, int height, int depth = -1);
+ wxBitmap(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
/**
Creates a bitmap from XPM data.
@see LoadFile()
*/
- wxBitmap(const wxString& name, long type);
+ wxBitmap(const wxString& name, wxBitmapType type = wxBITMAP_TYPE_XPM);
/**
- Creates bitmap object from the image. This has to be done to actually
- display an image as you cannot draw an image directly on a window.
+ Creates this bitmap object from the given image.
+ This has to be done to actually display an image as you cannot draw an
+ image directly on a window.
The resulting bitmap will use the provided colour depth (or that of the
- current system if depth is -1) which entails that a colour reduction has
- to take place.
+ current system if depth is ::wxBITMAP_SCREEN_DEPTH) which entails that a
+ colour reduction may take place.
When in 8-bit mode (PseudoColour mode), the GTK port will use a color cube
created on program start-up to look up colors. This ensures a very fast conversion,
Specifies the depth of the bitmap.
If this is omitted, the display depth of the screen is used.
*/
- wxBitmap(const wxImage& img, int depth = -1);
-
+ wxBitmap(const wxImage& img, int depth = wxBITMAP_SCREEN_DEPTH);
/**
Destructor.
*/
bool CopyFromIcon(const wxIcon& icon);
-
/**
Creates a fresh bitmap.
If the final argument is omitted, the display depth of the screen is used.
This overload works on all platforms.
*/
- virtual bool Create(int width, int height, int depth = -1);
+ virtual bool Create(int width, int height, int depth = wxBITMAP_SCREEN_DEPTH);
- /**
+ /*
Creates a bitmap from the given data, which can be of arbitrary type.
@param data
@returns @true if the call succeeded, @false otherwise.
This overload depends on the @a type of data.
- */
virtual bool Create(const void* data, int type, int width,
int height, int depth = -1);
+ NOTE: leave this undoc for the same reason of the relative ctor.
+ */
+
/**
Finds the handler with the given @a name.
static wxBitmapHandler* FindHandler(wxBitmapType bitmapType);
/**
- Gets the colour depth of the bitmap. A value of 1 indicates a
- monochrome bitmap.
+ Gets the colour depth of the bitmap.
+ A value of 1 indicates a monochrome bitmap.
*/
int GetDepth() const;
@see LoadFile()
*/
bool SaveFile(const wxString& name, wxBitmapType type,
- wxPalette* palette = NULL);
+ const wxPalette* palette = NULL);
/**
Sets the depth member (does not affect the bitmap data).
@wxheader{bmpbuttn.h}
A bitmap button is a control that contains a bitmap.
- It may be placed on a @ref overview_wxdialog "dialog box" or panel(), or indeed
- almost any other window.
+ It may be placed on a wxDialog or a wxPanel, or indeed almost any other window.
+
+ @remarks
+ A bitmap button can be supplied with a single bitmap, and wxWidgets will draw
+ all button states using this bitmap. If the application needs more control,
+ additional bitmaps for the selected state, unpressed focused state, and greyed-out
+ state may be supplied.
+
+ @section wxbitmapbutton_states Button states
+ This class supports bitmaps for several different states:
+
+ @li @b normal: this is the bitmap shown in the default state, it must be always
+ valid while all the other bitmaps are optional and don't have to be set.
+ @li @b disabled: bitmap shown when the button is disabled.
+ @li @b selected: bitmap shown when the button is pushed (e.g. while the user
+ keeps the mouse button pressed on it)
+ @li @b focus: bitmap shown when the button has keyboard focus but is not pressed.
+ @li @b hover: bitmap shown when the mouse is over the button (but it is not pressed).
+ Notice that if hover bitmap is not specified but the current platform UI uses
+ hover images for the buttons (such as Windows XP or GTK+), then the focus bitmap
+ is used for hover state as well. This makes it possible to set focus bitmap only
+ to get reasonably good behaviour on all platforms.
@beginStyleTable
@style{wxBU_AUTODRAW}:
If this is specified, the button will be drawn automatically using
the label bitmap only, providing a 3D-look border. If this style is
not specified, the button will be drawn without borders and using
- all provided bitmaps. WIN32 only.
+ all provided bitmaps. Has effect only under MS Windows.
@style{wxBU_LEFT}:
- Left-justifies the bitmap label. WIN32 only.
+ Left-justifies the bitmap label. Has effect only under MS Windows.
@style{wxBU_TOP}:
- Aligns the bitmap label to the top of the button. WIN32 only.
+ Aligns the bitmap label to the top of the button.
+ Has effect only under MS Windows.
@style{wxBU_RIGHT}:
- Right-justifies the bitmap label. WIN32 only.
+ Right-justifies the bitmap label. Has effect only under MS Windows.
@style{wxBU_BOTTOM}:
- Aligns the bitmap label to the bottom of the button. WIN32 only.
+ Aligns the bitmap label to the bottom of the button.
+ Has effect only under MS Windows.
@endStyleTable
+ Note that the wxBU_EXACTFIT style supported by wxButton is not used by this
+ class as bitmap buttons don't have any minimal standard size by default.
+
@beginEventTable
@event{EVT_BUTTON(id, func)}:
- Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
- clicked.
+ Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
@endEventTable
@library{wxcore}
class wxBitmapButton : public wxButton
{
public:
- //@{
+ /**
+ Default ctor.
+ */
+ wxBitmapButton();
+
/**
Constructor, creating and showing a button.
-
+
@param parent
Parent window. Must not be @NULL.
@param id
@param pos
Button position.
@param size
- Button size. If wxDefaultSize is specified then the button is
- sized
+ Button size. If wxDefaultSize is specified then the button is sized
appropriately for the bitmap.
@param style
Window style. See wxBitmapButton.
Window validator.
@param name
Window name.
-
- @remarks The bitmap parameter is normally the only bitmap you need to
- provide, and wxWidgets will draw the button correctly
- in its different states. If you want more control, call
- any of the functions SetBitmapSelected(),
- SetBitmapFocus(),
- SetBitmapDisabled().
-
+
+ @remarks The bitmap parameter is normally the only bitmap you need to provide,
+ and wxWidgets will draw the button correctly in its different states.
+ If you want more control, call any of the functions SetBitmapSelected(),
+ SetBitmapFocus(), SetBitmapDisabled().
+
@see Create(), wxValidator
*/
- wxBitmapButton();
wxBitmapButton(wxWindow* parent, wxWindowID id,
const wxBitmap& bitmap,
const wxPoint& pos = wxDefaultPosition,
long style = wxBU_AUTODRAW,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = "button");
- //@}
/**
Destructor, destroying the button.
~wxBitmapButton();
/**
- Button creation function for two-step creation. For more details, see
- wxBitmapButton().
+ Button creation function for two-step creation.
+ For more details, see wxBitmapButton().
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxBitmap& bitmap,
//@{
/**
- Returns the bitmap for the disabled state, may be invalid.
-
+ Returns the bitmap for the disabled state, which may be invalid.
+
@returns A reference to the disabled state bitmap.
-
+
@see SetBitmapDisabled()
*/
- const wxBitmap GetBitmapDisabled();
- const wxBitmap& GetBitmapDisabled();
+ const wxBitmap& GetBitmapDisabled() const;
+ wxBitmap& GetBitmapDisabled();
//@}
//@{
/**
- Returns the bitmap for the focused state, may be invalid.
-
+ Returns the bitmap for the focused state, which may be invalid.
+
@returns A reference to the focused state bitmap.
-
+
@see SetBitmapFocus()
*/
- const wxBitmap GetBitmapFocus();
- const wxBitmap& GetBitmapFocus();
+ const wxBitmap& GetBitmapFocus() const;
+ wxBitmap& GetBitmapFocus();
//@}
//@{
/**
- Returns the bitmap used when the mouse is over the button, may be invalid.
-
+ Returns the bitmap used when the mouse is over the button, which may be invalid.
+
@see SetBitmapHover()
*/
- const wxBitmap GetBitmapHover();
- const wxBitmap& GetBitmapHover();
+ const wxBitmap& GetBitmapHover();
+ wxBitmap& GetBitmapHover();
//@}
//@{
/**
Returns the label bitmap (the one passed to the constructor), always valid.
-
+
@returns A reference to the button's label bitmap.
-
+
@see SetBitmapLabel()
*/
- const wxBitmap GetBitmapLabel();
- const wxBitmap& GetBitmapLabel();
+ const wxBitmap& GetBitmapLabel();
+ wxBitmap& GetBitmapLabel();
//@}
/**
Returns the bitmap for the selected state.
-
+
@returns A reference to the selected state bitmap.
-
+
@see SetBitmapSelected()
*/
- wxBitmap GetBitmapSelected() const;
+ wxBitmap& GetBitmapSelected() const;
/**
Sets the bitmap for the disabled button appearance.
-
+
@param bitmap
The bitmap to set.
-
+
@see GetBitmapDisabled(), SetBitmapLabel(),
SetBitmapSelected(), SetBitmapFocus()
*/
/**
Sets the bitmap for the button appearance when it has the keyboard focus.
-
+
@param bitmap
The bitmap to set.
-
+
@see GetBitmapFocus(), SetBitmapLabel(),
SetBitmapSelected(), SetBitmapDisabled()
*/
/**
Sets the bitmap to be shown when the mouse is over the button.
-
- @wxsince{2.7.0} and the hover bitmap is
- currently only supported in wxMSW.
-
+
+ @wxsince{2.7.0}
+
+ The hover bitmap is currently only supported in wxMSW.
+
@see GetBitmapHover()
*/
void SetBitmapHover(const wxBitmap& bitmap);
/**
Sets the bitmap label for the button.
-
+
@param bitmap
The bitmap label to set.
-
+
@remarks This is the bitmap used for the unselected state, and for all
other states if no other bitmaps are provided.
-
+
@see GetBitmapLabel()
*/
void SetBitmapLabel(const wxBitmap& bitmap);
/**
Sets the bitmap for the selected (depressed) button appearance.
-
+
@param bitmap
The bitmap to set.
*/
It currently only allows using bitmaps of one size, and resizes itself
so that a bitmap can be shown next to the text field.
+ @remarks
+ While wxBitmapComboBox contains the wxComboBox API, but it might not actually
+ be derived from that class. In fact, if the platform does not have a native
+ implementation, wxBitmapComboBox will inherit from wxOwnerDrawnComboBox.
+ You can determine if the implementation is generic by checking whether
+ @c wxGENERIC_BITMAPCOMBOBOX is defined.
+
@beginStyleTable
@style{wxCB_READONLY}:
Creates a combobox without a text editor. On some platforms the
@style{wxTE_PROCESS_ENTER}:
The control will generate the event wxEVT_COMMAND_TEXT_ENTER
(otherwise pressing Enter key is either processed internally by the
- control or used for navigation between dialog controls). Windows
- only.
+ control or used for navigation between dialog controls).
+ Windows only.
@endStyleTable
+ @todo create wxCB_PROCESS_ENTER rather than reusing wxTE_PROCESS_ENTER!
+
@beginEventTable
@event{EVT_COMBOBOX(id, func)}:
Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
the list is selected.
@event{EVT_TEXT(id, func)}:
- Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
- changes.
+ Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text changes.
@event{EVT_TEXT_ENTER(id, func)}:
Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
the combobox.
class wxBitmapComboBox : public wxComboBox
{
public:
+ /**
+ Default ctor.
+ */
+ wxBitmapComboBox();
+
//@{
/**
Constructor, creating and showing a combobox.
-
+
@param parent
Parent window. Must not be @NULL.
@param id
@param pos
Window position.
@param size
- Window size. If wxDefaultSize is specified then the window is
- sized
+ Window size. If wxDefaultSize is specified then the window is sized
appropriately.
@param n
Number of strings with which to initialise the control.
Window validator.
@param name
Window name.
-
+
@see Create(), wxValidator
*/
- wxBitmapComboBox();
wxBitmapComboBox(wxWindow* parent, wxWindowID id,
const wxString& value = "",
const wxPoint& pos = wxDefaultPosition,
*/
~wxBitmapComboBox();
- //@{
/**
- Adds the item to the end of the combo box, associating the given, typed or
- untyped, client data pointer with the item.
+ Adds the item to the end of the combo box.
*/
int Append(const wxString& item,
const wxBitmap& bitmap = wxNullBitmap);
+
+ //@{
+ /**
+ Adds the item to the end of the combo box, associating the given, typed or
+ untyped, client data pointer @a clientData with the item.
+ */
int Append(const wxString& item, const wxBitmap& bitmap,
void* clientData);
int Append(const wxString& item, const wxBitmap& bitmap,
*/
wxBitmap GetItemBitmap(unsigned int n) const;
+ /**
+ Inserts the item into the list before @a pos.
+ Not valid for @c wxCB_SORT style, use Append() instead.
+ */
+ int Insert(const wxString& item, const wxBitmap& bitmap,
+ unsigned int pos);
+
//@{
/**
Inserts the item into the list before pos, associating the given, typed or
untyped, client data pointer with the item.
- Not valid for @c wxCB_SORT style, use Append instead.
+ Not valid for @c wxCB_SORT style, use Append() instead.
*/
- int Insert(const wxString& item, const wxBitmap& bitmap,
- unsigned int pos);
+
int Insert(const wxString& item, const wxBitmap& bitmap,
unsigned int pos,
void* clientData);
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+/**
+ The possible brush styles.
+*/
+enum wxBrushStyle
+{
+ wxBRUSHSTYLE_SOLID = wxSOLID,
+ /**< Solid. */
+
+ wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
+ /**< Transparent (no fill). */
+
+ wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
+ /**< @todo WHAT's THIS?? */
+
+ wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
+ /**< @todo WHAT's THIS?? */
+
+ wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
+ /**< Uses a bitmap as a stipple. */
+
+ wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
+ /**< Backward diagonal hatch. */
+
+ wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
+ /**< Cross-diagonal hatch. */
+
+ wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
+ /**< Forward diagonal hatch. */
+
+ wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
+ /**< Cross hatch. */
+
+ wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
+ /**< Horizontal hatch. */
+
+ wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
+ /**< Vertical hatch. */
+
+ wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
+ wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
+ wxBRUSHSTYLE_MAX
+};
+
+
+
/**
@class wxBrush
@wxheader{brush.h}
A brush is a drawing tool for filling in areas. It is used for painting
- the background of rectangles, ellipses, etc. It has a colour and a
- style.
+ the background of rectangles, ellipses, etc. It has a colour and a style.
+
+ On a monochrome display, wxWidgets shows all brushes as white unless the
+ colour is really 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 create brushes with different characteristics
+ dynamically, and there is the consequent danger that a large number of
+ duplicate brushes will be created. Therefore an application may wish to
+ get a pointer to a brush by using the global list of brushes ::wxTheBrushList,
+ and calling the member function wxBrushList::FindOrCreateBrush().
+
+ 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:, ::wxNullBrush, ::Pointers:, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH,
- ::wxWHITE_BRUSH, ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH, ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH,
+ ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
+ ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH,
+ ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH
@see wxBrushList, wxDC, wxDC::SetBrush
*/
class wxBrush : public wxGDIObject
{
public:
- //@{
/**
- Copy constructor, uses @ref overview_trefcount "reference counting".
-
+ Default constructor.
+ The brush will be uninitialised, and wxBrush:IsOk() will return @false.
+ */
+ wxBrush();
+
+ /**
+ Constructs a brush from a colour object and @a style.
+
@param colour
Colour object.
+ @param style
+ One of the ::wxBrushStyle enumeration values.
+ */
+ wxBrush(const wxColour& colour, wxBrushStyle style = wxSOLID);
+
+ /**
+ Constructs a brush from a colour name and @a style.
+
@param colourName
Colour name. The name will be looked up in the colour database.
@param style
- One of:
-
-
-
-
-
-
- wxTRANSPARENT
-
-
-
-
- Transparent (no fill).
-
-
-
-
-
- wxSOLID
-
-
-
-
- Solid.
-
-
-
-
-
- wxSTIPPLE
-
-
-
-
- Uses a bitmap as a stipple.
-
-
-
-
-
- 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.
- @param brush
- Pointer or reference to a brush to copy.
- @param stippleBitmap
- A bitmap to use for stippling.
-
- @remarks If a stipple brush is created, the brush style will be set to
- wxSTIPPLE.
-
- @see wxBrushList, wxColour, wxColourDatabase
+ One of the ::wxBrushStyle enumeration values.
+
+ @see wxColourDatabase
+ */
+ wxBrush(const wxString& colourName, wxBrushStyle style);
+
+ /**
+ Constructs a stippled brush using a bitmap.
+ The brush style will be set to wxBRUSHSTYLE_STIPPLE.
*/
- wxBrush();
- wxBrush(const wxColour& colour, int style = wxSOLID);
- wxBrush(const wxString& colourName, int style);
wxBrush(const wxBitmap& stippleBitmap);
+
+ /**
+ Copy constructor, uses @ref overview_refcount "reference counting".
+ */
wxBrush(const wxBrush& brush);
- //@}
/**
Destructor.
- See @ref overview_refcountdestruct "reference-counted object destruction" for
- more info.
-
+
+ See @ref overview_refcount_destruct for more info.
+
@remarks Although all remaining brushes are deleted when the application
- exits, the application should try to clean up all
- brushes itself. This is because wxWidgets cannot know
- if a pointer to the brush object is stored in an
- application data structure, and there is a risk of
- double deletion.
+ exits, the application should try to clean up all brushes itself.
+ This is because wxWidgets cannot know if a pointer to the brush
+ object is stored in an application data structure, and there is
+ a risk of double deletion.
*/
~wxBrush();
/**
Returns a reference to the brush colour.
-
+
@see SetColour()
*/
wxColour GetColour() const;
/**
- Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE
- style,
- this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok
- wxBitmap:IsOk returns @false).
-
+ Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
+ style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
+
@see SetStipple()
*/
wxBitmap* GetStipple() const;
/**
- Returns the brush style, one of:
-
- @b wxTRANSPARENT
-
- Transparent (no fill).
-
- @b wxSOLID
-
- Solid.
-
- @b wxBDIAGONAL_HATCH
-
- Backward diagonal hatch.
-
- @b wxCROSSDIAG_HATCH
-
- Cross-diagonal hatch.
-
- @b wxFDIAGONAL_HATCH
-
- Forward diagonal hatch.
-
- @b wxCROSS_HATCH
-
- Cross hatch.
-
- @b wxHORIZONTAL_HATCH
-
- Horizontal hatch.
-
- @b wxVERTICAL_HATCH
-
- Vertical hatch.
-
- @b wxSTIPPLE
-
- Stippled using a bitmap.
-
- @b wxSTIPPLE_MASK_OPAQUE
-
- Stippled using a bitmap's mask.
-
+ Returns the brush style, one of the ::wxBrushStyle values.
+
@see SetStyle(), SetColour(), SetStipple()
*/
- int GetStyle() const;
+ wxBrushStyle GetStyle() const;
/**
Returns @true if the style of the brush is any of hatched fills.
-
+
@see GetStyle()
*/
bool IsHatch() const;
//@{
/**
Sets the brush colour using red, green and blue values.
-
+
@see GetColour()
*/
void SetColour(wxColour& colour);
/**
Sets the stipple bitmap.
-
+
@param bitmap
The bitmap to use for stippling.
-
- @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask
- associated to it, in which case the style will be set
- to wxSTIPPLE_MASK_OPAQUE.
-
+
+ @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
+ has a mask associated to it, in which case the style will be set
+ to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
+
@see wxBitmap
*/
void SetStipple(const wxBitmap& bitmap);
/**
Sets the brush style.
-
+
@param style
- One of:
-
-
-
-
-
-
- wxTRANSPARENT
-
-
-
-
- Transparent (no fill).
-
-
-
-
-
- wxSOLID
-
-
-
-
- Solid.
-
-
-
-
-
- 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.
-
-
-
-
-
- wxSTIPPLE
-
-
-
-
- Stippled using a bitmap.
-
-
-
-
-
- wxSTIPPLE_MASK_OPAQUE
-
-
-
-
- Stippled using a bitmap's mask.
-
+ One of the ::wxBrushStyle values.
+
@see GetStyle()
*/
- void SetStyle(int style);
+ void SetStyle(wxBrushStyle style);
/**
Inequality operator.
- See @ref overview_refcountequality "reference-counted object comparison" for
- more info.
+ See @ref overview_refcount_equality for more info.
*/
bool operator !=(const wxBrush& brush);
/**
- Assignment operator, using @ref overview_trefcount "reference counting".
+ Assignment operator, using @ref overview_refcount "reference counting".
*/
wxBrush operator =(const wxBrush& brush);
/**
Equality operator.
- See @ref overview_refcountequality "reference-counted object comparison" for
- more info.
+ See @ref overview_refcount_equality for more info.
*/
bool operator ==(const wxBrush& brush);
};
-
/**
- FIXME
-*/
-wxBrush Objects:
-;
-
-/**
- FIXME
+ An empty brush.
*/
wxBrush wxNullBrush;
/**
- FIXME
+ Blue brush.
*/
-wxBrush Pointers:
-;
+wxBrush* wxBLUE_BRUSH;
/**
- FIXME
+ Green brush.
*/
-wxBrush wxBLUE_BRUSH;
+wxBrush* wxGREEN_BRUSH;
/**
- FIXME
+ White brush.
*/
-wxBrush wxGREEN_BRUSH;
+wxBrush* wxWHITE_BRUSH;
/**
- FIXME
+ Black brush.
*/
-wxBrush wxWHITE_BRUSH;
+wxBrush* wxBLACK_BRUSH;
/**
- FIXME
+ Grey brush.
*/
-wxBrush wxBLACK_BRUSH;
+wxBrush* wxGREY_BRUSH;
/**
- FIXME
+ Medium grey brush.
*/
-wxBrush wxGREY_BRUSH;
+wxBrush* wxMEDIUM_GREY_BRUSH;
/**
- FIXME
+ Light grey brush.
*/
-wxBrush wxMEDIUM_GREY_BRUSH;
+wxBrush* wxLIGHT_GREY_BRUSH;
/**
- FIXME
+ Transparent brush.
*/
-wxBrush wxLIGHT_GREY_BRUSH;
+wxBrush* wxTRANSPARENT_BRUSH;
/**
- FIXME
+ Cyan brush.
*/
-wxBrush wxTRANSPARENT_BRUSH;
+wxBrush* wxCYAN_BRUSH;
/**
- FIXME
+ Red brush.
*/
-wxBrush wxCYAN_BRUSH;
+wxBrush* wxRED_BRUSH;
+
+
/**
- FIXME
+ @class wxBrushList
+ @wxheader{gdicmn.h}
+
+ A brush list is a list containing all brushes which have been created.
+
+ @library{wxcore}
+ @category{gdi}
+
+ @see wxBrush
*/
-wxBrush wxRED_BRUSH;
+class wxBrushList : public wxList
+{
+public:
+ /**
+ Constructor. The application should not construct its own brush list:
+ use the object pointer ::wxTheBrushList.
+ */
+ wxBrushList();
+ /**
+ Finds a brush with the specified attributes and returns it, else creates a new
+ brush, adds it to the brush list, and returns it.
+ @param colour
+ Colour object.
+ @param style
+ Brush style. See ::wxBrushStyle for a list of styles.
+ */
+ wxBrush* FindOrCreateBrush(const wxColour& colour,
+ wxBrushStyle style = wxBRUSHSTYLE_SOLID);
+};
+
+/**
+ The global wxBrushList instance.
+*/
+wxBrushList* wxTheBrushList;
@wxheader{buffer.h}
A @b wxMemoryBuffer is a useful data structure for storing arbitrary sized
- blocks
- of memory. wxMemoryBuffer guarantees deletion of the memory block when the
- object
- is destroyed.
+ blocks of memory. wxMemoryBuffer guarantees deletion of the memory block when
+ the object is destroyed.
@library{wxbase}
- @category{FIXME}
+ @category{data}
*/
class wxMemoryBuffer
{
public:
- //@{
+ /**
+ Copy constructor, refcounting is used for performance, but wxMemoryBuffer
+ is not a copy-on-write structure so changes made to one buffer effect all
+ copies made from it.
+
+ @see @ref overview_refcount
+ */
+ wxMemoryBuffer(const wxMemoryBuffer& src);
+
/**
Create a new buffer.
-
+
@param size
- size of new buffer.
+ size of the new buffer.
*/
- wxMemoryBuffer(const wxMemoryBuffer& src);
wxMemoryBuffer(size_t size);
- //@}
/**
Append a single byte to the buffer.
-
+
@param data
New byte to append to the buffer.
*/
/**
Ensure that the buffer is big enough and return a pointer to the start
of the empty space in the buffer. This pointer can be used to directly
- write data into the buffer, this new data will be appended to
- the existing data.
-
+ write data into the buffer, this new data will be appended to the
+ existing data.
+
@param sizeNeeded
Amount of extra space required in the buffer for
the append operation
void SetBufSize(size_t size);
/**
- Sets the length of the data stored in the buffer. Mainly useful for truncating
- existing data.
-
+ Sets the length of the data stored in the buffer.
+ Mainly useful for truncating existing data.
+
@param size
New length of the valid data in the buffer. This is
distinct from the allocated size
/**
Update the length after completing a direct append, which
you must have used GetAppendBuf() to initialise.
-
+
@param sizeUsed
This is the amount of new data that has been
appended.
/**
Update the buffer after completing a direct write, which
you must have used GetWriteBuf() to initialise.
-
+
@param sizeUsed
The amount of data written in to buffer
by the direct write
For example:
@code
- wxBusyInfo wait("Please wait, working...");
+ wxBusyInfo wait("Please wait, working...");
- for (int i = 0; i 100000; i++)
+ for (int i = 0; i < 100000; i++)
{
DoACalculation();
}
@endcode
- It works by creating a window in the constructor,
- and deleting it in the destructor.
+ It works by creating a window in the constructor, and deleting it
+ in the destructor.
You may also want to call wxTheApp-Yield() to refresh the window
periodically (in case it had been obscured by other windows, for
example) like this:
@code
- wxWindowDisabler disableAll;
+ wxWindowDisabler disableAll;
wxBusyInfo wait("Please wait, working...");
- for (int i = 0; i 100000; i++)
+ for (int i = 0; i < 100000; i++)
{
DoACalculation();
@endcode
but take care to not cause undesirable reentrancies when doing it (see
- wxApp::Yield for more details). The simplest way to do
- it is to use wxWindowDisabler class as illustrated
- in the above example.
+ wxApp::Yield for more details). The simplest way to do it is to use
+ wxWindowDisabler class as illustrated in the above example.
@library{wxcore}
- @category{FIXME}
+ @category{cmndlg}
*/
class wxBusyInfo
{
public:
/**
- Constructs a busy info window as child of @a parent and displays @e msg
- in it.
- @b NB: If @a parent is not @NULL you must ensure that it is not
- closed while the busy info is shown.
+ Constructs a busy info window as child of @a parent and displays @e msg in it.
+
+ @note If @a parent is not @NULL you must ensure that it is not
+ closed while the busy info is shown.
*/
wxBusyInfo(const wxString& msg, wxWindow* parent = NULL);
@class wxButton
@wxheader{button.h}
- A button is a control that contains a text string,
- and is one of the most common elements of a GUI. It may be placed on a
- @ref overview_wxdialog "dialog box" or panel(), or indeed
- almost any other window.
+ A button is a control that contains a text string, and is one of the most
+ common elements of a GUI.
+
+ It may be placed on a @ref wxDialog "dialog box" or on a @ref wxPanel panel,
+ or indeed on almost any other window.
@beginStyleTable
@style{wxBU_LEFT}:
@beginEventTable
@event{EVT_BUTTON(id, func)}:
- Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
- clicked.
+ Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
@endEventTable
@library{wxcore}
class wxButton : public wxControl
{
public:
- //@{
+ /**
+ Default ctor.
+ */
+ wxButton();
+
/**
Constructor, creating and showing a button.
+
The preferred way to create standard buttons is to use default value of
- @e label. If no label is supplied and @a id is one of standard IDs from
- @ref overview_stockitems "this list", standard label will be used. In addition
- to
- that, the button will be decorated with stock icons under GTK+ 2.
-
+ @a label. If no label is supplied and @a id is one of standard IDs from
+ @ref page_stockitems "this list", a standard label will be used.
+
+ In addition to that, the button will be decorated with stock icons under GTK+ 2.
+
@param parent
Parent window. Must not be @NULL.
@param id
Button size. If the default size is specified then the button is sized
appropriately for the text.
@param style
- Window style. See wxButton.
+ Window style. See wxButton class description.
@param validator
Window validator.
@param name
Window name.
-
+
@see Create(), wxValidator
*/
- wxButton();
wxButton(wxWindow* parent, wxWindowID id,
const wxString& label = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = "button");
- //@}
/**
Destructor, destroying the button.
~wxButton();
/**
- Button creation function for two-step creation. For more details, see
- wxButton().
+ Button creation function for two-step creation.
+ For more details, see wxButton().
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxString& label = wxEmptyString,
/**
Returns the string label for the button.
-
- @returns The button's label.
-
+
@see SetLabel()
*/
wxString GetLabel() const;
/**
- This sets the button to be the default item for the panel or dialog
- box.
-
+ This sets the button to be the default item for the panel or dialog box.
+
+ As normal, pressing return causes the default button to be depressed when
+ the return key is pressed.
+
+ See also wxWindow::SetFocus() which sets the keyboard focus for windows
+ and text panel items, and wxTopLevelWindow::SetDefaultItem().
+
@remarks Under Windows, only dialog box buttons respond to this function.
- As normal under Windows and Motif, pressing return
- causes the default button to be depressed when the
- return key is pressed. See also wxWindow::SetFocus
- which sets the keyboard focus for windows and text
- panel items, and wxTopLevelWindow::SetDefaultItem.
*/
void SetDefault();
/**
Sets the string label for the button.
-
+
@param label
The label to set.
*/
This method is the opposite from Inflate():
Deflate(a, b) is equivalent to Inflate(-a, -b).
Please refer to Inflate() for full description.
-
+
@see Inflate()
*/
void Deflate(wxCoord dx, wxCoord dy) const;
/**
Gets the size.
-
+
@see SetSize()
*/
wxSize GetSize() const;
independently. In the above example, the width is reduced by 20,
whereas the height is reduced by the full 30 (rather than also stopping
at 20, when the width reached zero).
-
+
@see Deflate()
*/
void Inflate(wxCoord dx, wxCoord dy) const;
/**
Sets the size.
-
+
@see GetSize()
*/
void SetSize(const wxSize& s);
-/**
- @class wxBrushList
- @wxheader{gdicmn.h}
-
- A brush list is a list containing all brushes which have been created.
-
- @library{wxcore}
- @category{gdi}
-
- @see wxBrush
-*/
-class wxBrushList : public wxList
-{
-public:
- /**
- Constructor. The application should not construct its own brush list:
- use the object pointer @b wxTheBrushList.
- */
- wxBrushList();
-
- /**
- Finds a brush with the specified attributes and returns it, else creates a new
- brush, adds it
- to the brush list, and returns it.
-
- @param colour
- Colour object.
- @param style
- Brush style. See wxBrush::SetStyle for a list of styles.
- */
- wxBrush* FindOrCreateBrush(const wxColour& colour,
- int style = wxSOLID);
-};
-
-
-
/**
@class wxPoint
@wxheader{gdicmn.h}
By @e size.x and @e size.y for the first overload
By @a dx and @a dy for the second one
By @a d and @a d for the third one
-
+
@see IncBy()
*/
void DecBy(const wxSize& size);
/**
Decrements this object so that both of its dimensions are not greater than the
corresponding dimensions of the @e size.
-
+
@see IncTo()
*/
void DecTo(const wxSize& size);
By @e size.x and @e size.y for the first overload
By @a dx and @a dy for the second one
By @a d and @a d for the third one
-
+
@see DecBy()
*/
void IncBy(const wxSize& size);
/**
Increments this object so that both of its dimensions are not less than the
corresponding dimensions of the @e size.
-
+
@see DecTo()
*/
void IncTo(const wxSize& size);
Combine this size object with another one replacing the default (i.e. equal
to -1) components of this object with those of the other. It is typically
used like this:
-
+
@see IsFullySpecified()
*/
void SetDefaults(const wxSize& sizeDefault);
-/**
- @class wxPenList
- @wxheader{gdicmn.h}
-
- There is only one instance of this class: @b 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}
-
- @see wxPen
-*/
-class wxPenList
-{
-public:
- /**
- Constructor. The application should not construct its own pen list:
- use the object pointer @b 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 colourName
- Colour name, which should be in the colour database.
- @param width
- Width of pen.
- @param style
- Pen style. See wxPen::wxPen for a list of styles.
- */
- wxPen* FindOrCreatePen(const wxColour& colour, int width,
- int style);
- wxPen* FindOrCreatePen(const wxString& colourName, int width,
- int style);
- //@}
-};
-
// ============================================================================
/////////////////////////////////////////////////////////////////////////////
// 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
@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
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;
@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;
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;
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);
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);
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);
bool operator ==(const wxPen& pen);
};
-
-/**
- FIXME
-*/
-wxPen Objects:
-;
-
/**
FIXME
*/
wxPen wxNullPen;
-/**
- FIXME
-*/
-wxPen Pointers:
-;
-
/**
FIXME
*/
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;
+
projects / wxWidgets.git / commitdiff
