Canvas Reference Documentation

Canvas

Parent class: Widget

A drawing area widget. This class provides general purpose drawing functions and generates events for low-level windowing system events. It also provides functions to draw and measure text in various fonts. The top-left origin coordinate is (0, 0).

Important note: Drawing functions can only be called from within the Paint() event handler! Calling drawing functions from outside this method will result in undefined behavior. Furthermore, changing the font, color, or line style outside of the Paint method may work in some contexts, but not others. To force the Canvas to generated a paint event, call the redraw() method.

Object Events:

Paint	The canvas needs to be repainted.
Resize	The canvas was resized.
MouseMove	The mouse moved without a button being pressed.
MouseDrag	The mouse moved while a button was being held down.
MousePress	A mouse button was pressed.
MouseRelease	A mouse button was released.
KeyDown	A key was pressed.
KeyUp	A key was released.
MouseEnter	The mouse cursor entered the canvas area.
MouseLeave	The mouse cursor left the canvas area.
GotFocus	The canvas received the input focus.
LostFocus	The canvas lost the input focus.

Method Summary:
	Canvas::Canvas	();
void	Canvas::setState	(int pState);
int	Canvas::getState	();
void	Canvas::setColor	(const Color& pColor);
void	Canvas::setColor	(const String& pName);
void	Canvas::setColor	(unsigned char r, unsigned char g, unsigned char b);
void	Canvas::setFont	(Font pFont, FontStyle pStyle, int pSize);
void	Canvas::setDrawMode	(DrawMode pMode);
void	Canvas::setLineStyle	(LineStyle pStyle, int (=0) pWidget);
void	Canvas::pushClip	(int pX, int pY, int pWidth, int pHeight);
void	Canvas::popClip	();
void	Canvas::drawPoint	(int pX, int pY);
void	Canvas::drawLine	(int pX1, int pY1, int pX2, int pY2);
void	Canvas::drawRect	(int pX, int pY, int pWidth, int pHeight);
void	Canvas::fillRect	(int pX, int pY, int pWidth, int pHeight);
void	Canvas::drawArc	(int pX, int pY, int pWidth, int pHeight, double pAngle1, double pAngle2);
void	Canvas::fillArc	(int pX, int pY, int pWidth, int pHeight, double pAngle1, double pAngle2);
bool	Canvas::drawXpm	(char** pData, int pX, int pY);
Size	Canvas::getXpmSize	(char** pData);
void	Canvas::drawImage	(unsigned char* pData, int pX, int pY, int pWidth, int pHeight, int(=3) pDepth);
void	Canvas::drawMonoImage	(unsigned char* pData, int pX, int pY, int pWidth, int pHeight);
void	Canvas::drawString	(int pX, int pY, const String& pStr);
void	Canvas::drawText	(int pX, int pY, const char* pStr, int pLen);
void	Canvas::getTextExtent	(int& pWidth, int& pHeight);
int	Canvas::getStringWidth	(const String& pStr);
int	Canvas::getTextWidth	(const char* pStr, int pLen);
int	Canvas::getFontHeight	();
int	Canvas::getFontDescent	();

Canvas::Canvas

Canvas::Canvas();

Creates a new drawing canvas.

void Canvas::setState

void Canvas::setState(int pState);

Sets a internal flag to indicate what should be redrawn. For example, a mouse drag might set the state to '1', and call redraw(). Then the redraw method queries the state, and if it is '1', only draws what is necessary to respond to the mouse drag event. Any integer values can be used. The Canvas class itself does not query this value.

Parameters:
int	pState	A value representing a drawing state.

int Canvas::getState

int Canvas::getState();

Returns the internal state variable. See setState() for more information.

void Canvas::setColor

void Canvas::setColor(const Color& pColor);

Changes the current drawing color.

Parameters:
const Color&	pColor	The new color.

void Canvas::setColor

void Canvas::setColor(const String& pName);

Changes the current drawing color.

Parameters:
const String&	pName	A string-identified color. Set the Color class documentation for a list of recognized color names.

void Canvas::setColor

void Canvas::setColor(unsigned char r, unsigned char g, unsigned char b);

Changes the current drawing color.

Parameters:
unsigned char	r	The red value.
unsigned char	g	The green value.
unsigned char	b	The blue value.

void Canvas::setFont

void Canvas::setFont(Font pFont, FontStyle pStyle, int pSize);

Changes the current text drawing font.

Parameters:
Font	pFont	The new font. Recognized typefaces are TIMES, HELVETICA, and COURIER.
FontStyle	pStyle	The font style. Possible styles are NORMAL, BOLD, ITALIC, and BOLD_ITALIC.
int	pSize	The font size in pixels.

void Canvas::setDrawMode

void Canvas::setDrawMode(DrawMode pMode);

Changes the way pixels are copied to the screen. STANDARD mode will simply copy the new pixel value over the existing one, while INVERT and XOR identify a logical function indicated how the new pixel value will be combined with the old one.

Parameters:
DrawMode	pMode	The drawing mode. Accepted values are STANDARD, INVERT, and XOR.

void Canvas::setLineStyle

void Canvas::setLineStyle(LineStyle pStyle, int (=0) pWidget);

Changes the current line style.

Parameters:
LineStyle	pStyle	The new line style. Possible values are SOLID, DASHED, DOTTED, and DASHDOTTED.
int (=0)	pWidget	The line width. Defaults to 0, which is a nice thin line.

void Canvas::pushClip

void Canvas::pushClip(int pX, int pY, int pWidth, int pHeight);

Sets the current clipping region. This limits all drawing to the specified region. Anything drawn outside the region will not actually be drawn. Every call to pushClip() must be accompanied by a call to popClip(), or undefined behavior will result.

Parameters:
int	pX	The X-coordinate.
int	pY	The Y-coordinate.
int	pWidth	The width of the clip region.
int	pHeight	The height of the clip region.

void Canvas::popClip

void Canvas::popClip();

Restores the previous clipping region state.

void Canvas::drawPoint

void Canvas::drawPoint(int pX, int pY);

Draws a 1 pixel by 1 pixel point on the canvas with the current color.

Parameters:
int	pX	The X-coordinate.
int	pY	The Y-coordinate.

void Canvas::drawLine

void Canvas::drawLine(int pX1, int pY1, int pX2, int pY2);

Draws a line in the current style and color between the two points indicated.

Parameters:
int	pX1	The starting X-coordinate.
int	pY1	The starting Y-coordinate.
int	pX2	The ending X-coordinate.
int	pY2	The ending Y-coordinate.

void Canvas::drawRect

void Canvas::drawRect(int pX, int pY, int pWidth, int pHeight);

Draws a 1-pixel wide rectangle within the given bounding box.

Parameters:
int	pX	The X-coordinate.
int	pY	The Y-coordinate.
int	pWidth	The width of the rectangle.
int	pHeight	The height of the rectangle.

void Canvas::fillRect

void Canvas::fillRect(int pX, int pY, int pWidth, int pHeight);

Fills the specified rectangular region with the current color.

Parameters:
int	pX	The X-coordinate.
int	pY	The Y-coordinate.
int	pWidth	The width of the rectangle.
int	pHeight	The height of the rectangle.

void Canvas::drawArc

void Canvas::drawArc(int pX, int pY, int pWidth, int pHeight, double pAngle1, double pAngle2);

Draw an elliptical outline within the specified bounding box.

Parameters:
int	pX	The X-coordinate.
int	pY	The Y-coordinate.
int	pWidth	The width of the bounding box.
int	pHeight	The height of the bounding box.
double	pAngle1	The starting angle, measured in degrees, counterclockwise. 0 degrees is at 3 o'clock.
double	pAngle2	The ending angle, measured in degrees, counterclockwise. This must be greater than the starting angle.

void Canvas::fillArc

void Canvas::fillArc(int pX, int pY, int pWidth, int pHeight, double pAngle1, double pAngle2);

Fill an elliptical area specified by bounding box with the current color.

Parameters:
int	pX	The X-coordinate.
int	pY	The Y-coordinate.
int	pWidth	The width of the bounding box.
int	pHeight	The height of the bounding box.
double	pAngle1	The starting angle, measured in degrees, counterclockwise. 0 degrees is at 3 o'clock.
double	pAngle2	The ending angle, measured in degrees, counterclockwise. This must be greater than the starting angle.

bool Canvas::drawXpm

bool Canvas::drawXpm(char** pData, int pX, int pY);

Draws XPM image data with the top-left corner at the given position. The image is dithered on 8-bit displays. The current canvas color is used for transparent colors.

Returns: Returns false if there was an error decoding the XPM data. Otherwise, returns true.

Parameters:
char**	pData	The XPM pixmap data.
int	pX	The top-left X coordinate.
int	pY	The top-left Y coordinate.

Size Canvas::getXpmSize

Size Canvas::getXpmSize(char** pData);

Returns the size of an XPM image.

Returns: Returns a size of (-1,-1) if there were errors decoding the image.

Parameters:
char**	pData	The XPM pixmap data.

void Canvas::drawImage

void Canvas::drawImage(unsigned char* pData, int pX, int pY, int pWidth, int pHeight, int(=3) pDepth);

Draws a 8-bit per color RGB image directly onto the canvas. Color data must be in RGB order. X, Y are where to put the top-left pixel.

Parameters:
unsigned char*	pData	The image data.
int	pX	The left-most pixel coordinate.
int	pY	The top-most pixel coordinate.
int	pWidth	The width of the image.
int	pHeight	The height of the image.
int(=3)	pDepth	The depth of the image in bytes per pixel. Defaults to 3.

void Canvas::drawMonoImage

void Canvas::drawMonoImage(unsigned char* pData, int pX, int pY, int pWidth, int pHeight);

Draws a 8-bit grayscale image directly onto the canvas. X, Y are where to put the top-left pixel.

Parameters:
unsigned char*	pData	The grayscale image data.
int	pX	The left-most pixel coordinate.
int	pY	The top-most pixel coordinate.
int	pWidth	The width of the image.
int	pHeight	The height of the image.

void Canvas::drawString

void Canvas::drawString(int pX, int pY, const String& pStr);

Draws text on the canvas in the current font and style.

Parameters:
int	pX	The X-coordinate, aligned to the left of the text.
int	pY	The Y-coordinate, aligned to the baseline of the text in the current font.
const String&	pStr	The string to draw.

void Canvas::drawText

void Canvas::drawText(int pX, int pY, const char* pStr, int pLen);

Draws text on the canvas in the current font and style.

Parameters:
int	pX	The X-coordinate, aligned to the left of the text.
int	pY	The Y-coordinate, aligned to the baseline of the text in the current font.
const char*	pStr	The text to draw.
int	pLen	The length of the text.

void Canvas::getTextExtent

void Canvas::getTextExtent(int& pWidth, int& pHeight);

Measure the size of some text in the current font.

Parameters:
int&	pWidth	The width will be assigned to this parameter.
int&	pHeight	The height will be assigned to this parameter.

int Canvas::getStringWidth

int Canvas::getStringWidth(const String& pStr);

Returns the width of the string in the current font.

Parameters:
const String&	pStr	The string to measure.

int Canvas::getTextWidth

int Canvas::getTextWidth(const char* pStr, int pLen);

Returns the width of the text in the current font.

Parameters:
const char*	pStr	The string to measure.
int	pLen	The length of the string.

int Canvas::getFontHeight

int Canvas::getFontHeight();

Returns the height of the current font from the baseline.

int Canvas::getFontDescent

int Canvas::getFontDescent();

Returns the number of pixels the font descends below the baseline.