class PCanvas: public PObject, public PCanvasState

A class representing something that can be drawn into.

Inheritance:


Public Classes

[more]enum DrawStringOptions
The text alignment options determine the manner in which the drawn text related to the position it is being drawn into.

Public Methods

[more]virtual ~PCanvas ()
Destroy the canvas, freeing any resources held by the canvas.
[more]virtual Comparison Compare ( const PObject & obj ) const
Compare two canvas objects returning their relative rank.
[more]virtual PCanvasState& operator= ( const PCanvasState & state )
Set the state of the canvas from the canvas state object.
[more]const PRealFont& GetFont () const
Get the current physical font that is used by drawing operations.
[more]virtual PFontFamilyList GetAvailableFonts () const
Get the list of available fonts the canvas currently supports.
[more]virtual void Save ()
Save the state of the canvas on an internal stack.
[more]virtual void Restore ()
Restore the state of the canvas to the last one saved.
[more]virtual void SetCurrentPosition ( PORDINATE x, PORDINATE y )
Set the current position for line drawing operations.
[more]virtual void MoveCurrentPosition ( PORDINATE x, PORDINATE y )
Move the current position for line drawing operations relative to the previous current position.
[more]virtual void MoveCurrentPosition ( const PPoint & pos )
Move the current position for line drawing operations relative to the previous current position.
[more]virtual PPoint GetCurrentPosition () const
Get the current position for line drawing operations.
[more]virtual void DrawLine ( PORDINATE x, PORDINATE y )
Draw a line, using the current canvas state pen modes, colour etc, from the current "pen position" to the specified point.
[more]virtual void DrawLine ( const PPoint & pt )
Draw a line, using the current canvas state pen modes, colour etc, from the current "pen position" to the specified point.
[more]virtual void DrawLineRelative ( PORDINATE x, PORDINATE y )
Draw a line, using the current canvas state pen modes, colour etc, from the current "pen position" to the point offset from that position.
[more]virtual void DrawLine ( PORDINATE x1, PORDINATE y1, PORDINATE x2, PORDINATE y2 )
Draw a line, using the current canvas state pen modes, colour etc, from a source point to a destination point, note that this does not update the current position for line drawing.
[more]void DrawRect ( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Draw a rectangle, using the current canvas state pen modes, fill modes, colours etc.
[more]void FillRect ( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Fill a rectangle, using the current canvas state fill modes, colours etc.
[more]virtual void DrawFocusRect ( const PRect & rect )
Draw a system standard focus indication rectangle.
[more]virtual void DrawBevelledRect ( const PRect & rect, BOOL raised, BOOL deep )
Draw a bevelled "3D look" rectangle.
[more]virtual void DrawRoundRect ( const PRect & rect, PDIMENSION cornerWidth, PDIMENSION cornerHeight )
Draw a rectangle with rounded corners, using the current canvas state pen modes, fill modes, colours etc.
[more]virtual void DrawEllipse ( const PRect & rect )
Draw an ellipse that fits into the specified rectangle, using the current canvas state pen modes, fill modes, colours etc.
[more]virtual void DrawArc ( const PRect & rect, int startAngle, int endAngle )
Draw an arc, using the current canvas state pen modes, colours etc.
[more]virtual void DrawPie ( const PRect & rect, int startAngle, int endAngle )
Draw a pie segment, using the current canvas state pen modes, fill modes, colours etc.
[more]virtual void DrawChord ( const PRect & rect, int startAngle, int endAngle )
Draw a chord segment, using the current canvas state pen modes, fill modes, colours etc.
[more]virtual void DrawPolyLine ( const PPointArray & ptArray )
Draw a series of lines between each consecutive point in the array, using the current canvas state pen modes, colours etc.
[more]virtual void DrawPolygon ( const PPointArray & ptArray )
Draw a closed polygon where the array of points determine its vertices.
[more]virtual void DrawImgIcon ( PORDINATE x, PORDINATE y, const PImgIcon & icn )
Draw the specified pixel bitmap image icon at the specified position.
[more]virtual void DrawIcon ( PORDINATE x, PORDINATE y, const PIcon & icn )
Draw the specified pixel bitmap icon at the specified position.
[more]virtual void DrawPixels ( PORDINATE x, PORDINATE y, const PPixelImage & pix )
Draw the specified pixel bitmap image at the specified position.
[more]virtual void DrawPixels ( const PRect & rect, const PPixelImage & pix )
Draw the specified pixel bitmap image scaling it to fit the spcified destination rectangle.
[more]virtual void DrawPict ( PORDINATE x, PORDINATE y, const PPictImage & pic )
Draw the specified picture image at the specified position.
[more]virtual void DrawPict ( const PRect & rect, const PPictImage & pic )
Draw the specified picture image into the specified rectangle, scaling it to fit.
[more]virtual void DrawString ( PORDINATE x, PORDINATE y, const PString & str, int options = LeftAlign )
Draw a string at the specified location, using the current canvas text font, modes and colours.
[more]virtual PDIMENSION DrawString ( const PRect & rect, const PString & str, int options = LeftAlign )
Draw a string within the bounds of the rectangle, using the current canvas text font, modes and colours.
[more]virtual PDim MeasureString ( const PString & str )
Get the width and height of the string if it were to be drawn in the current font selected for the canvas.
[more]virtual PDIMENSION MeasureString (const PString & str, PDIMENSION width)
Return the height of the string if drawn with word wrapping about the specified width.
[more]virtual void DrawTextLine ( PORDINATE x, PORDINATE y, const char * textChars, const PDIMENSION * charWidths, PINDEX len )
Draw a single line of text at the specified starting position.
[more]virtual PRect GetDrawingBounds () const
Get the limits of the drawable area for this canvas.
[more]virtual PRect GetPhysicalBounds (BOOL inPixels = FALSE) const
Get the physical size of the drawable area for this canvas in pixels or millimetersThis is dependent on the specific descendent of PCanvas.
[more]virtual void SetClipRegion ( const PRegion & rgn )
Set the clip region for the canvas.
[more]virtual PRegion GetClipRegion () const
Get the clip region for the canvas.
[more]virtual void SetClipRect ( const PRect & rect )
Set the bounding rectangle around the clip region for the canvas.
[more]virtual PRect GetClipRect () const
Get the bounding rectangle around the clip region for the canvas.
[more]BOOL IsInClipRegion ( const PPoint & pt ) const
Determine if the specified point or any part of the specified rectangle is inside the clip region, ie any drawing operation would not be inhibited due to clipping.
[more]PDIMENSION FromPixelsDX ( PDIMENSION dx ) const
Convert the specified parameter from pixels to the coordinate system for this canvas.
[more]PDIMENSION ToPixelsDX ( PDIMENSION dx ) const
Convert the specified parameter from the coordinate system for this canvas to pixels.
[more]PDIMENSION FromPointsX ( PDIMENSION dx )
Convert the specified parameter from printers points (1/72 inch) to the coordinate system for this canvas.
[more]PDIMENSION ToPointsX ( PDIMENSION dx )
Convert the specified parameter from the coordinate system for this canvas to printers points (1/72 inch).

Public

[more] New functions for class

Protected Classes

[more]class State : public PObject, public PCanvasState
Actual font used by the canvas derived from the font in the canvas state.

Protected Fields

[more]PRealFont realFont
Device (usually screen) resolution for conversion functions

Protected Methods

[more] PCanvas ()
Create a new canvas.
[more]virtual void _DrawRect ( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Really draw the rectangle.
[more]virtual void _FillRect ( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Really fill the rectangle.

Protected

[more]PORDINATE Member variables


Inherited from PObject:

Public

Run Time Type functions

Comparison functions

I/O functions

Miscellaneous functions


Inherited from PCanvasState:

Public Classes

oenum PenStyles
oenum DrawingModes
oenum PolyFillMode

Public Methods

ovirtual BOOL SetPenStyle( PenStyles style )
oPenStyles GetPenStyle() const
ovirtual BOOL SetPenWidth( int width )
oint GetPenWidth() const
ovirtual BOOL SetPenMode( DrawingModes mode )
oDrawingModes GetPenMode() const
ovirtual BOOL SetPenFgColour( const PColour & colour )
oconst PColour& GetPenFgColour() const
ovirtual BOOL SetPenBkColour( const PColour & colour )
oconst PColour& GetPenBkColour() const
ovirtual BOOL SetFillPattern( const PPattern & pattern )
oPPattern GetFillPattern() const
ovirtual BOOL SetPatternOrigin( const PPoint & pt )
oPPoint GetPatternOrigin() const
ovirtual BOOL SetFillMode(DrawingModes style)
oDrawingModes GetFillMode() const
ovirtual BOOL SetFillFgColour( const PColour & colour )
oconst PColour& GetFillFgColour() const
ovirtual BOOL SetFillBkColour( const PColour & colour )
oconst PColour& GetFillBkColour() const
ovirtual BOOL SetFont(const PFont & newFont)
ovirtual BOOL SetTextFgColour( const PColour & colour )
oconst PColour& GetTextFgColour() const
ovirtual BOOL SetTextBkColour( const PColour & colour )
oconst PColour& GetTextBkColour() const
ovirtual BOOL SetPolyFillMode( PolyFillMode newMode )
oPolyFillMode GetPolyFillMode() const
ovirtual BOOL SetPalette( const PPalette & newPal )
oPPalette GetPalette() const
ovirtual BOOL SetMappingRect( const PRect & rect )
oPRect GetMappingRect() const
ovirtual BOOL SetViewportRect( const PRect & rect )
oPRect GetViewportRect() const
ovoid SetOrigin(const PPoint & pt)
oPPoint GetOrigin() const


Documentation

A class representing something that can be drawn into. There are three main; destinations of drawing that descend from this class: an area of the screen in a PInteractor, a printer device or an off screen image.

NOTE *********************************** On Some platforms, canvases are a limited resource. Do NOT create and leave them around for long periods. As soon as it is not required till the next user event, destroy it!

o PCanvas()
Create a new canvas. This constructor is protected so only descendent classes can be instantiated.

ovirtual ~PCanvas()
Destroy the canvas, freeing any resources held by the canvas.

ovirtual Comparison Compare( const PObject & obj ) const
Compare two canvas objects returning their relative rank. As a canvas really cannot be ranked only equality is really returned.

Returns:
EqualTo if the two objects reference the same canvas, otherwise it returns GreaterThan.
Parameters:
obj - Another object to compare against

o New functions for class

ovirtual PCanvasState& operator=( const PCanvasState & state )
Set the state of the canvas from the canvas state object. All drawing modes etc are set in one go with this function.

Returns:
the new canvas state for the canvas.
Parameters:
state - The new canvas state for the canvas

oconst PRealFont& GetFont() const
Get the current physical font that is used by drawing operations. This is the font that will actually be used by the canvas. The font in the PCanvasState is only a request for what font to use. As the particular drawing environment may not have that font availale, a matching algorithm is applied to get the nearest font available. This is described by the PRealFont.

Returns:
pointer to the current font used by the canvas. Note that the user of this pointer should not delete it.

ovirtual PFontFamilyList GetAvailableFonts() const
Get the list of available fonts the canvas currently supports. Each list entry consists of the font family specification. A font family are all variations of a particular face name eg Times italic, Times bold are two fonts of the Times font family.

Returns:
a list of font families.

ovirtual void Save()
Save the state of the canvas on an internal stack. This function in combination with Restore() can be used to do many drawing operations within a subroutine and not affect external users of the canvas.

ovirtual void Restore()
Restore the state of the canvas to the last one saved. This function in combination with Save() can be used to do many drawing operations within a subroutine and not affect external users of the canvas.

ovirtual void SetCurrentPosition( PORDINATE x, PORDINATE y )
Set the current position for line drawing operations. The current position can be viewed as the "pen" position on the canvas.
Parameters:
x - New x position for line drawing operations
y - New y position for line drawing operations

ovirtual void MoveCurrentPosition( PORDINATE x, PORDINATE y )
Move the current position for line drawing operations relative to the previous current position. The current position can be viewed as the "pen" position on the canvas.
Parameters:
x - X amount to offset the position for line drawing.
y - Y amount to offset the position for line drawing.

ovirtual void MoveCurrentPosition( const PPoint & pos )
Move the current position for line drawing operations relative to the previous current position. The current position can be viewed as the "pen" position on the canvas.
Parameters:
pos - Amount to offset the position for line drawing.

ovirtual PPoint GetCurrentPosition() const
Get the current position for line drawing operations. The current position can be viewed as the "pen" position on the canvas.

Returns:
point representing the x and y position.

ovirtual void DrawLine( PORDINATE x, PORDINATE y )
Draw a line, using the current canvas state pen modes, colour etc, from the current "pen position" to the specified point. The current position is updated to the destination of this drawing operation. Thus consecutive calls of DrawLine() function would draw a series of connected line segments.
Parameters:
x - X position to draw the line to.
y - Y position to draw the line to.

ovirtual void DrawLine( const PPoint & pt )
Draw a line, using the current canvas state pen modes, colour etc, from the current "pen position" to the specified point. The current position is updated to the destination of this drawing operation. Thus consecutive calls of DrawLine() function would draw a series of connected line segments.
Parameters:
pt - Position to draw the line to.

ovirtual void DrawLineRelative( PORDINATE x, PORDINATE y )
Draw a line, using the current canvas state pen modes, colour etc, from the current "pen position" to the point offset from that position. The current position is updated to the destination of this drawing operation. Thus consecutive calls of DrawLine() function would draw a series of connected line segments.
Parameters:
x - X offset to draw the line to.
y - Y offset to draw the line to.

ovirtual void DrawLine( PORDINATE x1, PORDINATE y1, PORDINATE x2, PORDINATE y2 )
Draw a line, using the current canvas state pen modes, colour etc, from a source point to a destination point, note that this does not update the current position for line drawing.
Parameters:
x1 - X position to start the line from.
y1 - Y position to start the line from.
x2 - X position to draw the line to.
y2 - Y position to draw the line to.

ovoid DrawRect( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Draw a rectangle, using the current canvas state pen modes, fill modes, colours etc. A number of options are available for how to specify the rectangle to draw.
Parameters:
x - X position of the top left corner of the rectangle to draw.
y - Y position of the top left corner of the rectangle to draw.
width - Width of the rectangle to draw.
height - Height of the rectangle to draw.

ovoid FillRect( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Fill a rectangle, using the current canvas state fill modes, colours etc. A number of options are available for how to specify the rectangle to draw.
Parameters:
x - X position of the top left corner of the rectangle to draw.
y - Y position of the top left corner of the rectangle to draw.
width - Width of the rectangle to draw.
height - Height of the rectangle to draw.

ovirtual void DrawFocusRect( const PRect & rect )
Draw a system standard focus indication rectangle. This will ignore the pen modes, fill modes, colours etc and draw a rectangle in a manner typical for the platform. This would typically be an inverting dotted line with no fill.
Parameters:
rect - The bounds of the focus rectangle to draw.

ovirtual void DrawBevelledRect( const PRect & rect, BOOL raised, BOOL deep )
Draw a bevelled "3D look" rectangle. This is achieved by drawing carefully coloured shadows and highlights about the rectangle. By convention all lighting appears from the top left corner. Thus by reversing the edges that are lighted or shadowed the rectangle can look raised above the plane of the background or sunk into it. The thickness of the shadow determines how deeply sunk (or raised) the inside of the rectangle is.

There are a set of system parameter available in the PApplication object that determine the way a bevelled rectangle is drawn. These are the colours for highlight and shadow and the standard width of a border. A "deep" bevell is 2 standard border widths.

Parameters:
rect - The bounds of the bevelled rectangle to draw.
raised - Indicate that the rectangle looks raised or sunk.
deep - Indicate that rectangle looks deep or shallow.

ovirtual void DrawRoundRect( const PRect & rect, PDIMENSION cornerWidth, PDIMENSION cornerHeight )
Draw a rectangle with rounded corners, using the current canvas state pen modes, fill modes, colours etc. The amount of roundness to the corner is determined by the cornerWidth and cornerHeight parameters which indicate the amount inside the actuak corner to begin the curve. Thus values of zero would result in a standard square corner rectangle.
Parameters:
rect - The bounds of the rounded rectangle to draw.
cornerWidth - The width of the rounded corners.
cornerHeight - The height of the rounded corners.

ovirtual void DrawEllipse( const PRect & rect )
Draw an ellipse that fits into the specified rectangle, using the current canvas state pen modes, fill modes, colours etc. Note that ellipses semi-major axes must be aligned with the vertical and horizontal.
Parameters:
rect - The bounds of the ellipse to draw.

ovirtual void DrawArc( const PRect & rect, int startAngle, int endAngle )
Draw an arc, using the current canvas state pen modes, colours etc. An arc is an unfilled object so only a line segment is drawn.

The arc is always part of an ellipse that would fit in the rectangle. The start and end indicate how much of the arc is drawn. Thus drawing from 0 to 360 degrees would result in a complete ellipse.

The start and end points do not actually need to be on the ellipse boundary. Conceptually, a vector from the centre of the ellipse out to the boundary is drawn and this represents the starting and end of the drawn arc.

Parameters:
rect - The bounds of the arc to draw.
startAngle - The angle in degrees to start drawing the arc.
endAngle - The angle in degrees to finish drawing the arc.

ovirtual void DrawPie( const PRect & rect, int startAngle, int endAngle )
Draw a pie segment, using the current canvas state pen modes, fill modes, colours etc. A pie is an arc with two lines connecting the ends of the arc to the centre of the ellipse the arc is part of.

The arc is always part of an ellipse that would fit in the rectangle. The start and end indicate how much of the arc is drawn. Thus drawing from 0 to 360 degrees would result in a complete ellipse.

The start and end points do not actually need to be on the ellipse boundary. Conceptually, a vector from the centre of the ellipse out to the boundary is drawn and this represents the starting and end of the drawn arc.

Parameters:
rect - The bounds of the pie to draw.
startAngle - The angle in degrees to start drawing the pie.
endAngle - The angle in degrees to finish drawing the pie.

ovirtual void DrawChord( const PRect & rect, int startAngle, int endAngle )
Draw a chord segment, using the current canvas state pen modes, fill modes, colours etc. A chord is an arc with a single line connecting the ends of the arc across the chord of the ellipse.

The arc is always part of an ellipse that would fit in the rectangle. The start and end indicate how much of the arc is drawn. Thus drawing from 0 to 360 degrees would result in a complete ellipse.

The start and end points do not actually need to be on the ellipse boundary. Conceptually, a vector from the centre of the ellipse out to the boundary is drawn and this represents the starting and end of the drawn arc.

Parameters:
rect - The bounds of the chord to draw.
startAngle - The angle in degrees to start drawing the chord.
endAngle - The angle in degrees to finish drawing the chord.

ovirtual void DrawPolyLine( const PPointArray & ptArray )
Draw a series of lines between each consecutive point in the array, using the current canvas state pen modes, colours etc.

Note that there should be at least 2 points in the array provided.

Parameters:
ptArray - Array of points to draw lines between.

ovirtual void DrawPolygon( const PPointArray & ptArray )
Draw a closed polygon where the array of points determine its vertices. The polygon is drawn using the current canvas state pen modes, fill modes, colours etc. Also important if the PolyFillMode which determines the filling of complex polygons. A complex polygon is one where some of the line segments cross over. The PolyFillMode determines what constitutes "inside" and öutside" of the polygon.

There is an implicit line between the first and last points in the array to close the polygon.

Note that there should be at least 2 points in the array provided.

Parameters:
ptArray - Array of points for each polygon vertex.

ovirtual void DrawImgIcon( PORDINATE x, PORDINATE y, const PImgIcon & icn )
Draw the specified pixel bitmap image icon at the specified position. A PImgIcon is usually a small pixel image used for screen interface elements, eg a picture in a push button on a tool bar.

If the image is black and white (1 bit per pixel) then white pixels are actually in the fill foreground colour and the black pixels are in the fill background colour.

Parameters:
x - The X position at which to draw the image icon.
y - The Y position at which to draw the image icon.
icn - The image icon to draw.

ovirtual void DrawIcon( PORDINATE x, PORDINATE y, const PIcon & icn )
Draw the specified pixel bitmap icon at the specified position. Note that a PIcon differs from a PImgIcon in that it is a platform dependent entity that has a particular form.

If the image is black and white (1 bit per pixel) then white pixels are actually in the fill foreground colour and the black pixels are in the fill background colour.

Parameters:
x - The X position at which to draw the icon.
y - The Y position at which to draw the icon.
icn - The icon to draw.

ovirtual void DrawPixels( PORDINATE x, PORDINATE y, const PPixelImage & pix )
Draw the specified pixel bitmap image at the specified position. Note that a PPixels differs from a PImgIcon in that it is usually a large image which has an associated colour translation.

If the image is black and white (1 bit per pixel) then white pixels are actually in the fill foreground colour and the black pixels are in the fill background colour.

Parameters:
x - The X position at which to draw the pixels.
y - The Y position at which to draw the pixels.
pix - The pixel image to draw.

ovirtual void DrawPixels( const PRect & rect, const PPixelImage & pix )
Draw the specified pixel bitmap image scaling it to fit the spcified destination rectangle. This may involve stretching or shrinking the original image.

If the image is black and white (1 bit per pixel) then white pixels are actually in the fill foreground colour and the black pixels are in the fill background colour.

Parameters:
rect - The destination rectangle to draw the image to.
pix - The pixel image to draw.

ovirtual void DrawPict( PORDINATE x, PORDINATE y, const PPictImage & pic )
Draw the specified picture image at the specified position. The current canvas state may affect the drawing depending on the picture.

A picture image is a platform dependent representation of a series of drawing instructions. This is usually much smaller than a pixel image but is not as portable.

Parameters:
x - The X position at which to draw the picture.
y - The Y position at which to draw the picture.
pic - The picture to draw.

ovirtual void DrawPict( const PRect & rect, const PPictImage & pic )
Draw the specified picture image into the specified rectangle, scaling it to fit. The current canvas state may affect the drawing depending on the picture.

A picture image is a platform dependent representation of a series of drawing instructions. This is usually much smaller than a pixel image but is not as portable.

Parameters:
rect - The destination rectangle to draw the image to.
pic - The picture to draw.

oenum DrawStringOptions
The text alignment options determine the manner in which the drawn text related to the position it is being drawn into. There are some variations of these options depending on whether the alignment is to be made to a point or to a rectangle.

o LeftAlign
The text lines are positioned on the left side with blank space on the right side. When aligned to a point the X value is on the left of the text. When aligned to a rectangle the left side is used.

o RightAlign
The text lines are positioned so the right side of the text is on the right with blank space on the left before each line. When aligned to a point the X value is on the right of the text. When aligned to a rectangle the right side is used.

o Centred
The text lines are positioned so there is an even amount of space on the left and right sides of the text. When aligned to a point the X value is at the centre of the text. When aligned to a rectangle the median between the left and right sides is used. In the latter the text is horizontally centred in the rectangle.

o Justified
The text lines are broken up into words (space separated characters) and the space between then increased so that the line completely fills the width and there is no blank space at either end of the line.

This mode is only relevent when aligment is to a rectangle. When a point is used this is the same as LeftAligned.

o HorizontalAlignmentMask
Mask to extract the horizontal alignment values from the DrawString options value.

o TopAlign
The top of the text line is set to the drawing position. The text is thus drawn entirely underneath the position specified. The position is either the Y of a point or the top of a rectangle.

o BottomAlign
The bottom of the text line is set to the drawing position. The text is thus drawn entirely above the position specified. The position is either the Y of a point or the bottom of a rectangle.

o CentreVertical
The centre of the text line is set to the drawing position. The text is thus drawn half above and half below the position specified. The position is either the Y of a point or the bedian between the top and bottom of a rectangle. In the latter the text is vertically centred in the rectangle.

o BaseLine
The baseline of the font of the text line is set to the drawing position. The text is thus drawn mostly above position specified, with descenders on characters such as 'p' being below that position.

o VerticalAlignmentMask
Mask to extract the vertical alignment values from the DrawString options value.

o NoWrapping
No word wrapping is performed. The text lines are drawn beyond the right side of the rectangle ignoring the width. Note that the normal canvas clipping still occurs.

o WordWrap
The text lines are broken up into words and if too wide to fit into the rectangles width, additional lines are inserted into the string

o CentreEllipses
The text lines are forced to fit within the width of the rectangle. No word wrapping is performed. The string is shortened by removing characters from the centre of the line and replacing them with an ellipses (" ... "). Enough characters are removed so that the width of the string will fit into the rectangle. Similarly in the vertical direction whole lines are dropped and replaced with an ellipses to fit the lines into the vertical height of the rectangle.

o EndEllipses
As in CentreEllipses the text lines are forced to fit within the width of the rectangle. In this case the truncation occurs at the opposite end of the horizontal alignment. Thus for LeftAlign text the right hand end of the string is clipped at the rectangle boundary.

o HorizontalWrapMask
Mask to extract the horizontal alignment wrapping values from the DrawString options value.

These modes are only relevent when aligment is to a rectangle. When a point is used they are ignored.

o NoTruncation
No truncation of lines is performed. The text lines are drawn beyond the bottom of the rectangle ignoring the height. Note that the normal canvas clipping still occurs.

o CentreTruncation
The lines in the string are truncated to fit into the height of the rectangle by removing whole lines from the string and replacing them with an ellipses (" . "). The first part of the first line removed and the last part of the last line removed is put onto the line in the centre of the rectangle.

o EndTruncation
As in CentreTruncation the text lines are forced to fit within the height of the rectangle. In this case the truncation occurs at the opposite end of the vertical alignment. Thus for TopAlign text the last lines of the string is clipped at the rectangle boundary.

o VerticalTruncationMask
Mask to extract the verical alignment truncation values from the DrawString options value.

These modes are only relevent when aligment is to a rectangle. When a point is used they are ignored.

ovirtual void DrawString( PORDINATE x, PORDINATE y, const PString & str, int options = LeftAlign )
Draw a string at the specified location, using the current canvas text font, modes and colours.

The options parameter determines the relationship between the text string drawn and the location it is drawn at. The point is placed at the position relative to the rectangle formed around the text (as returned by MeasureText()). Thus:

options = bottomAlign | centred

would result in the text positioned such that the specified point is at the bottom centre of the line of text. See DrawStringOptions for more infromation.

Note the Justified alignment is not relevent for this function and is treated as LeftAlign.

Parameters:
x - The X position at which to draw the string.
y - The Y position at which to draw the string.
str - The string to draw.
options - The alignment of the lines in the string.

ovirtual PDIMENSION DrawString( const PRect & rect, const PString & str, int options = LeftAlign )
Draw a string within the bounds of the rectangle, using the current canvas text font, modes and colours.

The options parameter determines the relationship between the text string drawn and the rectangle it is drawn in.

The BaseLine alignment is not relevent for this function and is treated as BottomAlign.

Returns:
the height of the text lines drawn.
Parameters:
rect - The rectangle into which to draw the string.
str - The string to draw.
options - The alignment of the lines in the string.

ovirtual PDim MeasureString( const PString & str )
Get the width and height of the string if it were to be drawn in the current font selected for the canvas.

Returns:
the width and height of the text lines.
Parameters:
str - The string to measure.

ovirtual PDIMENSION MeasureString(const PString & str, PDIMENSION width)
Return the height of the string if drawn with word wrapping about the specified width.

Returns:
the height of the text lines.

ovirtual void DrawTextLine( PORDINATE x, PORDINATE y, const char * textChars, const PDIMENSION * charWidths, PINDEX len )
Draw a single line of text at the specified starting position. The text block may contain any characters for the block length. Note that there cannot be any control characters in the string.

No checking for lines or word wrapping is performed by this function. With charWidths = NULL, this is the fastest way to draw text on the canvas.

Parameters:
x - The X position to draw the text.
y - The Y position to draw the text.
textChars - The array of characters to draw.
charWidths - An array with the width of each character in the text array. If this is NULL then the default character width for the font is used.
len - The number of characters to draw.

ovirtual PRect GetDrawingBounds() const
Get the limits of the drawable area for this canvas. This is dependent on the specific descendent of PCanvas. For example the PPrintCanvas would return the size of the printer page while a PInteractorCanvas would return the size of the interactor window.

Returns:
drawing bounds rectangle in current canvas coordinate system.

ovirtual PRect GetPhysicalBounds(BOOL inPixels = FALSE) const
Get the physical size of the drawable area for this canvas in pixels or millimetersThis is dependent on the specific descendent of PCanvas. For example the PPrintCanvas would return the size of the printer page while a PInteractorCanvas would return the size of the interactor window.

Returns:
drawing bounds rectangle in current canvas coordinate system.

ovirtual void SetClipRegion( const PRegion & rgn )
Set the clip region for the canvas. Any drawing operations that are outside this region are not actually drawn.
Parameters:
rgn - clip region in current canvas coordinate system.

ovirtual PRegion GetClipRegion() const
Get the clip region for the canvas. Any drawing operations that are outside this region are not actually drawn.

An application can optimise drawing operations by verifying that the operation would actually do something. This can save significant processing time under some circumstances.

Returns:
clip region in current canvas coordinate system.

ovirtual void SetClipRect( const PRect & rect )
Set the bounding rectangle around the clip region for the canvas. Any drawing operations that are outside this region may not be actually drawn.
Parameters:
rect - clip rectangle in current canvas coordinate system.

ovirtual PRect GetClipRect() const
Get the bounding rectangle around the clip region for the canvas. Any drawing operations that are outside this region may not be actually drawn.

An application can optimise drawing operations by verifying that the operation would actually do something. This can save significant processing time under some circumstances.

Returns:
clip rectangle in current canvas coordinate system.

oBOOL IsInClipRegion( const PPoint & pt ) const
Determine if the specified point or any part of the specified rectangle is inside the clip region, ie any drawing operation would not be inhibited due to clipping.

An application can optimise drawing operations by verifying that the operation would actually do something. This can save significant processing time under some circumstances.

Returns:
clip rectangle in current canvas coordinate system.
Parameters:
pt - Point to test as being in the clip region.

oPDIMENSION FromPixelsDX( PDIMENSION dx ) const
Convert the specified parameter from pixels to the coordinate system for this canvas. Note that for the PDIMENSION and PDim versions, no origin translation is made, only the scaling transform is applied.
Parameters:
dx - X distance to scale.

oPDIMENSION ToPixelsDX( PDIMENSION dx ) const
Convert the specified parameter from the coordinate system for this canvas to pixels. Note that for the PDIMENSION and PDim versions, no origin translation is made, only the scaling transform is applied.
Parameters:
dx - X distance to scale.

oPDIMENSION FromPointsX( PDIMENSION dx )
Convert the specified parameter from printers points (1/72 inch) to the coordinate system for this canvas. This is mainly used in support of the font system.
Parameters:
dx - X distance to scale.

oPDIMENSION ToPointsX( PDIMENSION dx )
Convert the specified parameter from the coordinate system for this canvas to printers points (1/72 inch). This is mainly used in support of the font system.
Parameters:
dx - X distance to scale.

ovirtual void _DrawRect( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Really draw the rectangle.
Parameters:
x - X position of the top left corner of the rectangle to draw.
y - Y position of the top left corner of the rectangle to draw.
width - Width of the rectangle to draw.
height - Height of the rectangle to draw.

ovirtual void _FillRect( PORDINATE x, PORDINATE y, PDIMENSION width, PDIMENSION height )
Really fill the rectangle.
Parameters:
x - X position of the top left corner of the rectangle to draw.
y - Y position of the top left corner of the rectangle to draw.
width - Width of the rectangle to draw.
height - Height of the rectangle to draw.

oPORDINATE Member variables

oPRealFont realFont
Device (usually screen) resolution for conversion functions


Direct child classes:
PPrintCanvas
PMemoryCanvas
PInteractorCanvas

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.