IP电话/视频会议

开发平台：
Visual C++

canvas.h：源码内容
							/*
 * canvas.h
 *
 * Canvas ancestor class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Log: canvas.h,v $
 * Revision 1.42  1999/03/10 03:49:50  robertj
 * More documentation adjustments.
 *
 * Revision 1.41  1999/03/09 08:01:47  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.40  1998/12/01 12:55:50  robertj
 * new directory structure.
 *
 * Revision 1.39  1998/10/16 11:08:10  robertj
 * GNU compatibility.
 *
 * Revision 1.38  1998/09/23 06:22:55  robertj
 * Added open source copyright license.
 *
 * Revision 1.37  1998/03/20 03:14:36  robertj
 * Added function to get physical bounds of canvas. Allows to scale drawing.
 *
 * Revision 1.36  1997/07/08 13:02:05  robertj
 * DLL support.
 *
 * Revision 1.35  1996/08/17 10:00:29  robertj
 * Changes for Windows DLL support.
 *
 * Revision 1.34  1996/01/02 11:49:49  robertj
 * Removed redundent comma.
 *
 * Revision 1.33  1995/07/02 01:16:51  robertj
 * Added ability to set the clip region.
 *
 * Revision 1.32  1995/03/14 12:41:01  robertj
 * Updated documentation to use HTML codes.
 *
 * Revision 1.31  1995/02/22  10:50:28  robertj
 * Changes required for compiling release (optimised) version.
 *
 * Revision 1.30  1995/01/27  11:03:12  robertj
 * Added FillRect function.
 * "Commonised" DrawRect function.
 *
 * Revision 1.29  1995/01/21  05:13:04  robertj
 * Documentation.
 *
 * Revision 1.28  1995/01/07  06:42:51  robertj
 * Unix requires virtual functions.
 *
 * Revision 1.27  1995/01/07  04:39:35  robertj
 * Redesigned font enumeration code and changed font styles.
 *
 * Revision 1.26  1995/01/06  10:43:45  robertj
 * Changed PRealFont usage from pointer to reference.
 *
 * Revision 1.25  1994/12/12  10:00:37  robertj
 * Added return value of height to DrawString()
 *
 * Revision 1.24  1994/12/05  11:34:01  robertj
 * Major rewrite of images, pictures and pixmaps.
 * Renamed PPict, PPixels and PImage to make sure all uses are found.
 *
 * Revision 1.23  1994/11/26  03:44:21  robertj
 * Documentation.
 *
 * Revision 1.23  1994/11/26  01:33:17  robertj
 * Documentation.
 *
 * Revision 1.22  1994/10/30  11:32:30  robertj
 * Added functions for checking in clip region.
 *
 * Revision 1.21  1994/09/25  10:35:33  robertj
 * Added clip region functions.
 *
 * Revision 1.20  1994/08/23  11:32:52  robertj
 * Oops
 *
 * Revision 1.19  1994/08/22  00:46:48  robertj
 * Added pragma fro GNU C++ compiler.
 *
 * Revision 1.18  1994/07/17  10:46:06  robertj
 * Changed returned font faces to sorted string list.
 *
 * Revision 1.17  1994/07/02  03:03:49  robertj
 * Made device resolution protected.
 *
 * Revision 1.16  1994/06/25  11:55:15  robertj
 * Unix version synchronisation.
 *
 * Revision 1.15  1994/04/01  14:09:14  robertj
 * Added low level draw line function.
 *
 * Revision 1.14  1994/03/07  07:38:19  robertj
 * Major enhancementsacross the board.
 *
 * Revision 1.13  1994/01/15  02:46:51  robertj
 * Fixed missing return value in private assignment operator to PCanvas.
 *
 * Revision 1.12  1994/01/13  11:30:39  robertj
 * Fixed PCanvasState assignment to be virtual.
 *
 * Revision 1.11  1994/01/03  04:42:23  robertj
 * Mass changes to common container classes and interactors etc etc etc.
 *
 * Revision 1.10  1993/12/31  06:39:16  robertj
 * Made inlines optional for debugging purposes.
 * Added DrawImgIcon and DrawIcon functions.
 *
 * Revision 1.9  1993/12/24  04:20:52  robertj
 * Mac CFront port.
 *
 * Revision 1.8  1993/12/16  03:41:01  robertj
 * Made overloaded functions virtual so all can be overridden.
 *
 * Revision 1.7  1993/11/20  17:26:28  robertj
 * Added assignment operator to assign from PCanvasState.
 * Some formatting
 *
 * Revision 1.6  1993/10/16  20:33:20  robertj
 * Extracted PCanvasState class out of the PCanvas.
 *
 * Revision 1.5  1993/09/27  16:35:25  robertj
 * Capitilised macros.
 *
 * Revision 1.4  1993/08/27  18:17:47  robertj
 * Added general function for drawing 3D bevelled areas.
 *
 * Revision 1.3  1993/07/14  12:49:16  robertj
 * Fixed RCS keywords.
 *
 */
#define _PCANVAS
#ifdef __GNUC__
#pragma interface
#endif
#ifndef _PCANVASSTATE
#include <pwlib/canstate.h>
#endif
/**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 Ref{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!
  ****************************************************************************
 */
class PCanvas : public PObject, public PCanvasState {
  PCLASSINFO(PCanvas, PObject);
  protected:
   /**Create a new canvas. This constructor is protected so only descendent
       classes can be instantiated.
     */
    PCanvas();
  public:
    /** Destroy the canvas, freeing any resources held by the canvas. */
    virtual ~PCanvas();
    // Overrides from class PObject
   /**Compare two canvas objects returning their relative rank. As a canvas
       really cannot be ranked only equality is really returned.
       @return
       #EqualTo# if the two objects reference the same canvas,
       otherwise it returns #GreaterThan#.
     */
    virtual Comparison Compare(
      const PObject & obj /// Another object to compare against
    ) const;
    /**@name New functions for class */
   /**Set the state of the canvas from the canvas state object. All drawing
       modes etc are set in one go with this function.
       @return
       the new canvas state for the canvas.
     */
    virtual PCanvasState & operator=(
      const PCanvasState & state  /// The new canvas state for the canvas
    );
   /**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
       Ref{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.
       @return
       pointer to the current font used by the canvas. Note that the user of
       this pointer should {bf not} delete it.
     */
    const PRealFont & GetFont() 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.
       @return
       a list of font families.
     */
    virtual PFontFamilyList GetAvailableFonts() const;
   /**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.
     */
    virtual void Save();
   /**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.
     */
    virtual void Restore();
    virtual void SetCurrentPosition(
      const PPoint & pos  /// New position for line drawing operations
    );
   /**Set the current position for line drawing operations. The current
       position can be viewed as the "pen" position on the canvas.
     */
    virtual void SetCurrentPosition(
      PORDINATE x,  /// New x position for line drawing operations
      PORDINATE y   /// New y position for line drawing operations
    );
   /**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.
     */
    virtual void MoveCurrentPosition(
      PORDINATE x,  /// X amount to offset the position for line drawing.
      PORDINATE y   /// Y amount to offset the position for line drawing.
    );
   /**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.
     */
    virtual void MoveCurrentPosition(
      const PPoint & pos  /// Amount to offset the position for line drawing.
    );
   /**Get the current position for line drawing operations. The current
       position can be viewed as the "pen" position on the canvas.
       @return
       point representing the x and y position.
     */
    virtual PPoint GetCurrentPosition() const;
   /**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.
     */
    virtual void DrawLine(
      PORDINATE x,  /// X position to draw the line to.
      PORDINATE y   /// Y position to draw the line to.
    );
   /**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.
     */
    virtual void DrawLine(
      const PPoint & pt  /// Position to draw the line to.
    );
   /**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.
     */
    virtual void DrawLineRelative(
      PORDINATE x,  /// X offset to draw the line to.
      PORDINATE y   /// Y offset to draw the line to.
    );
    virtual void DrawLineRelative(
      const PPoint & pt  /// X & Y offset to draw the line to.
    );
   /**Draw a line, using the current canvas state pen modes, colour etc, from
       a source point to a destination point, note that this does {bf not}
       update the current position for line drawing.
     */
    virtual void DrawLine(
      PORDINATE x1, /// X position to start the line from.
      PORDINATE y1, /// Y position to start the line from.
      PORDINATE x2, /// X position to draw the line to.
      PORDINATE y2  /// Y position to draw the line to.
    );
    virtual void DrawLine(
      const PPoint & p1, /// X & Y position to start the line from.
      const PPoint & p2  /// X & Y position to draw the line to.
    );
   /**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.
     */
    void DrawRect(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to draw.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to draw.
      PDIMENSION width, /// Width of the rectangle to draw.
      PDIMENSION height /// Height of the rectangle to draw.
    );
    void DrawRect(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to draw.
      const PPoint & botRight
      /// X & Y position of the bottom right corner of the rectangle to draw.
    );
    void DrawRect(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to draw.
      const PDim & dim
      /// The width & height of the rectangle to draw.
    );
    void DrawRect(
      const PRect & rect   /// The rectangle to draw.
    );
   /**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.
     */
    void FillRect(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to draw.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to draw.
      PDIMENSION width, /// Width of the rectangle to draw.
      PDIMENSION height /// Height of the rectangle to draw.
    );
    void FillRect(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to draw.
      const PPoint & botRight
      /// X & Y position of the bottom right corner of the rectangle to draw.
    );
    void FillRect(
      const PPoint & topLeft,
      /// X & Y position of the top left corner of the rectangle to draw.
      const PDim & dim
      /// The width & height of the rectangle to draw.
    );
    void FillRect(
      const PRect & rect   /// The rectangle to draw.
    );
   /**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.
     */
    virtual void DrawFocusRect(
      const PRect & rect /// The bounds of the focus rectangle to draw.
    );
   /**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 Ref{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.
     */
    virtual void DrawBevelledRect(
      const PRect & rect, /// The bounds of the bevelled rectangle to draw.
      BOOL raised,        /// Indicate that the rectangle looks raised or sunk.
      BOOL deep           /// Indicate that rectangle looks deep or shallow.
    );
   /**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.
     */
    virtual void DrawRoundRect(
      const PRect & rect,     /// The bounds of the rounded rectangle to draw.
      PDIMENSION cornerWidth, /// The width of the rounded corners.
      PDIMENSION cornerHeight /// The height of the rounded corners.
    );
   /**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.
     */
    virtual void DrawEllipse(
      const PRect & rect  /// The bounds of the ellipse to draw.
    );
   /**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.
     */
    virtual void DrawArc(
      const PRect & rect,  /// The bounds of the arc to draw.
      int startAngle,      /// The angle in degrees to start drawing the arc.
      int endAngle         /// The angle in degrees to finish drawing the arc.
    );
    virtual void DrawArc(
      const PRect & rect,     /// The bounds of the arc to draw.
      const PPoint & startPt, /// The point along the arc to start drawing.
      const PPoint & endPt    /// The point along the arc to finish drawing.
    );
   /**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.
     */
    virtual void DrawPie(
      const PRect & rect,  /// The bounds of the pie to draw.
      int startAngle,      /// The angle in degrees to start drawing the pie.
      int endAngle         /// The angle in degrees to finish drawing the pie.
    );
    virtual void DrawPie(
      const PRect & rect,     /// The bounds of the pie to draw.
      const PPoint & startPt, /// The point along the pie to start drawing.
      const PPoint & endPt    /// The point along the pie to finish drawing.
    );
   /**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.
     */
    virtual void DrawChord(
      const PRect & rect,  /// The bounds of the chord to draw.
      int startAngle,      /// The angle in degrees to start drawing the chord.
      int endAngle         /// The angle in degrees to finish drawing the chord.
    );
    virtual void DrawChord(
      const PRect & rect,     /// The bounds of the chord to draw.
      const PPoint & startPt, /// The point along the chord to start drawing.
      const PPoint & endPt    /// The point along the chord to finish drawing.
    );
   /**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.
     */
    virtual void DrawPolyLine(
      const PPointArray & ptArray  /// Array of points to draw lines between.
    );
    virtual void DrawPolyLine(
      const PPoint * ptArray,  /// Array of points to draw lines between.
      PINDEX numPts            /// Number of points in the array.
    );
   /**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 "outside" 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.
     */
    virtual void DrawPolygon(
      const PPointArray & ptArray  /// Array of points for each polygon vertex.
    );
    virtual void DrawPolygon(
      const PPoint * ptArray,  /// Array of points for each polygon vertex.
      PINDEX numPts            /// Number of points in the array.
    );
   /**Draw the specified pixel bitmap image icon at the specified position. A
       Ref{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.
     */
    virtual void DrawImgIcon(
      PORDINATE x,          /// The X position at which to draw the image icon.
      PORDINATE y,          /// The Y position at which to draw the image icon.
      const PImgIcon & icn  /// The image icon to draw.
    );
    virtual void DrawImgIcon(
      const PPoint & pt,    /// The position at which to draw the image icon.
      const PImgIcon & icn  /// The image icon to draw.
    );
   /**Draw the specified pixel bitmap icon at the specified position. Note
       that a Ref{PIcon} differs from a Ref{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.
     */
    virtual void DrawIcon(
      PORDINATE x,          /// The X position at which to draw the icon.
      PORDINATE y,          /// The Y position at which to draw the icon.
      const PIcon & icn     /// The icon to draw.
    );
    virtual void DrawIcon(
      const PPoint & pt,    /// The position at which to draw the icon.
      const PIcon & icn     /// The icon to draw.
    );
   /**Draw the specified pixel bitmap image at the specified position. Note
       that a Ref{PPixels} differs from a Ref{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.
     */
    virtual void DrawPixels(
      PORDINATE x,             /// The X position at which to draw the pixels.
      PORDINATE y,             /// The Y position at which to draw the pixels.
      const PPixelImage & pix  /// The pixel image to draw.
    );
    virtual void DrawPixels(
      const PPoint & pt,       /// The position at which to draw the pixels.
      const PPixelImage & pix  /// The pixel image to draw.
    );
   /**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.
     */
    virtual void DrawPixels(
      const PRect & rect,    /// The destination rectangle to draw the image to.
      const PPixelImage & pix  /// The pixel image to draw.
    );
   /**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.
     */
    virtual void DrawPict(
      PORDINATE x,            /// The X position at which to draw the picture.
      PORDINATE y,            /// The Y position at which to draw the picture.
      const PPictImage & pic  /// The picture to draw.
    );
    virtual void DrawPict(
      const PPoint & pt,      /// The position at which to draw the picture.
      const PPictImage & pic  /// The picture to draw.
    );
   /**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.
     */
    virtual void DrawPict(
      const PRect & rect,    /// The destination rectangle to draw the image to.
      const PPictImage & pic    /// The picture to draw.
    );
   /**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.
     */
    enum DrawStringOptions {
     /**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.
       */
      LeftAlign = 0x00,
     /**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.
       */
      RightAlign = 0x01,
     /**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.
       */
      Centred = 0x02,
     /**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.
       */
      Justified = 0x03,
     /**Mask to extract the horizontal alignment values from the DrawString
         options value. */
      HorizontalAlignmentMask = 0x03,
     /**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.
       */
      TopAlign = 0x00,
     /**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.
       */
      BottomAlign = 0x04,
     /**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.
       */
      CentreVertical = 0x08,
     /**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.
       */
      BaseLine = 0x0c,
     /**Mask to extract the vertical alignment values from the DrawString
         options value. */
      VerticalAlignmentMask = 0x0c,
     /**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.
       */
      NoWrapping = 0x00,
     /**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.
       */
      WordWrap = 0x10,
     /**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.
       */
      CentreEllipses = 0x20,
     /**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.
       */
      EndEllipses = 0x30,
     /**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.
       */
      HorizontalWrapMask = 0x30,
     /**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.
       */
      NoTruncation = 0x00,
     /**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.
       */
      CentreTruncation = 0x40,
     /**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.
       */
      EndTruncation = 0x80,
     /**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.
       */
      VerticalTruncationMask = 0xc0
    };
   /**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 Ref{DrawStringOptions} for
       more infromation.
       
       Note the Justified alignment is not relevent for this function and is
       treated as LeftAlign.
     */
    virtual void DrawString(
      PORDINATE x,            /// The X position at which to draw the string.
      PORDINATE y,            /// The Y position at which to draw the string.
      const PString & str,    /// The string to draw.
      int options = LeftAlign /// The alignment of the lines in the string.
    );
    virtual void DrawString(
      const PPoint & pt,      /// The position at which to draw the string.
      const PString & str,    /// The string to draw.
      int options = LeftAlign /// The alignment of the lines in the string.
    );
   /**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.
       @return
       the height of the text lines drawn.
     */
    virtual PDIMENSION DrawString(
      const PRect & rect,     /// The rectangle into which to draw the string.
      const PString & str,    /// The string to draw.
      int options = LeftAlign /// The alignment of the lines in the string.
    );
   /**Get the width and height of the string if it were to be drawn in the
       current font selected for the canvas.
       
       @return
       the width and height of the text lines.
     */
    virtual PDim MeasureString(
      const PString & str   /// The string to measure.
    );
   /**Return the height of the string if drawn with word wrapping about the
       specified width.
       @return
       the height of the text lines.
     */
    virtual PDIMENSION MeasureString(const PString & str, PDIMENSION width);
   /**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.
     */
    virtual void DrawTextLine(
      PORDINATE x,                   /// The X position to draw the text.
      PORDINATE y,                   /// The Y position to draw the text.
      const char * textChars,        /// The array of characters to draw.
      const PDIMENSION * 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.
       */
      PINDEX len                     /// The number of characters to draw.
    );
   /**Get the limits of the drawable area for this canvas. This is dependent
       on the specific descendent of PCanvas. For example the
       Ref{PPrintCanvas} would return the size of the printer page while a
       Ref{PInteractorCanvas} would return the size of the interactor window.
       @return
       drawing bounds rectangle in current canvas coordinate system.
     */
    virtual PRect GetDrawingBounds() const;
   /**Get the physical size of the drawable area for this canvas in pixels or
       millimeters.This is dependent on the specific descendent of PCanvas. For
       example the Ref{PPrintCanvas} would return the size of the printer page
       while a Ref{PInteractorCanvas} would return the size of the interactor
       window.
       @return
       drawing bounds rectangle in current canvas coordinate system.
     */
    virtual PRect GetPhysicalBounds(BOOL inPixels = FALSE) const;
   /**Set the clip region for the canvas. Any drawing operations that are
       outside this region are not actually drawn.
     */
    virtual void SetClipRegion(
      const PRegion & rgn   /// clip region in current canvas coordinate system.
    );
   /**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.
       @return
       clip region in current canvas coordinate system.
     */
    virtual PRegion GetClipRegion() const;
   /**Set the bounding rectangle around the clip region for the canvas. Any
       drawing operations that are outside this region may not be actually
       drawn.
     */
    virtual void SetClipRect(
      const PRect & rect /// clip rectangle in current canvas coordinate system.
    );
   /**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.
       @return
       clip rectangle in current canvas coordinate system.
     */
    virtual PRect GetClipRect() 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.
       @return
       clip rectangle in current canvas coordinate system.
     */
    BOOL IsInClipRegion(
      const PPoint & pt   /// Point to test as being in the clip region.
    ) const;
    BOOL IsInClipRegion(
      const PRect & rect
        /// Rectangle to test for intersection with the clip region.
    ) 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.
     */
    PDIMENSION FromPixelsDX(
      PDIMENSION dx /// X distance to scale.
    ) const;
    PDIMENSION FromPixelsDY(
      PDIMENSION dy /// Y distance to scale.
    ) const;
    PDim FromPixels(
      const PDim & dim /// Width and Height to scale.
    ) const;
    PORDINATE FromPixelsX(
      PORDINATE x  /// X position to scale and offset.
    ) const;
    PORDINATE FromPixelsY(
      PORDINATE y  /// Y position to scale and offset.
    ) const;
    PPoint FromPixels(
      const PPoint & p  /// X and Y position to scale and offset.
    ) const;
    PRect FromPixels(
      const PRect & r  /// Rectangle to scale and offset.
    ) 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.
     */
    PDIMENSION ToPixelsDX(
      PDIMENSION dx /// X distance to scale.
    ) const;
    PDIMENSION ToPixelsDY(
      PDIMENSION dy /// Y distance to scale.
    ) const;
    PDim ToPixels(
      const PDim & dim /// Width and Height to scale.
    ) const;
    PORDINATE ToPixelsX(
      PORDINATE x  /// X position to scale and offset.
    ) const;
    PORDINATE ToPixelsY(
      PORDINATE y  /// Y position to scale and offset.
    ) const;
    PPoint ToPixels(
      const PPoint & p  /// X and Y position to scale and offset.
    ) const;
    PRect ToPixels(
      const PRect & r  /// Rectangle to scale and offset.
    ) const;
   /**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.
     */
    PDIMENSION FromPointsX(
      PDIMENSION dx /// X distance to scale.
    );
    PDIMENSION FromPointsY(
      PDIMENSION dy /// Y distance to scale.
    );
   /**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.
     */
    PDIMENSION ToPointsX(
      PDIMENSION dx /// X distance to scale.
    );
    PDIMENSION ToPointsY(
      PDIMENSION dy /// Y distance to scale.
    );
  protected:
      /** Really draw the rectangle. */
    virtual void _DrawRect(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to draw.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to draw.
      PDIMENSION width, /// Width of the rectangle to draw.
      PDIMENSION height /// Height of the rectangle to draw.
    );
      /** Really fill the rectangle. */
    virtual void _FillRect(
      PORDINATE x,
      /// X position of the top left corner of the rectangle to draw.
      PORDINATE y,
      /// Y position of the top left corner of the rectangle to draw.
      PDIMENSION width, /// Width of the rectangle to draw.
      PDIMENSION height /// Height of the rectangle to draw.
    );
    /**@name Member variables */
    PORDINATE deviceResX, deviceResY;
      /** Device (usually screen) resolution for conversion functions */
    PRealFont realFont;
      /** Actual font used by the canvas derived from the font in the canvas
          state. */
    class State : public PObject, public PCanvasState {
      PCLASSINFO(State, PObject)
      public:
        State(const PCanvas & canvas)
          : PCanvasState(canvas), font(canvas.GetFont()) { }
        Comparison Compare(const PObject &) const
          { return EqualTo; }
        PRealFont font;
    };
    PSTACK(StateStack, State);
    StateStack stack;
  private:
    PCanvas(const PCanvas &) { }
    PCanvas & operator=(const PCanvas &) { return *this; }
      // Prevent descendents from ever doing copy/assignment of canvases.
#ifdef DOC_PLUS_PLUS
};
#endif
// Class declaration continued in platform specific header file ///////////////

						