Class Documentation

Name:Pen
Version:1.0
ID:ID_PEN
Status:Unspecified
Category:Graphics
Include:graphics/bitmap.h
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 1996-2001. All rights reserved.
Short:  Draws graphics to Bitmap objects.



Description

The Pen class is a graphical extension to the Bitmap class, providing extra functionality for the drawing of complex graphics primitives. It can draw ellipses, lines, rectangles and pixels, while you get to choose the shape of the pen tip and the tip size for the graphics routines to use.

A Pen object must be told what Bitmap it is to draw to by setting the Bitmap field. The destination Bitmap of a Pen can be changed at any time as the field is dynamic. The tip of the pen is adjusted through the TipSize and TipShape fields as well as its colour in the Red, Green and Blue fields.

There are two ways to draw using a Pen object - either call the method of the graphics primitive that you want to draw, or call the Draw action after setting certain parameters within a Pen object. Refer to the PenShape field for more information on the latter method.

Actions

The Pen class supports the following actions:

Draw  Draws a Pen object using preset parameters.

Methods

The Pen class implements the following methods:

PenArc  Draws an arc to a Bitmap.
PenEllipse  Draws an ellipse to a Bitmap.
PenLine  Draws a line across a Bitmap.
PenPoint  Draws a single pen tip to a Bitmap.
PenRectangle  Draws a rectangle to a Bitmap.

Structure

The Pen object consists of the following public fields:

Alpha  Determines the translucency level of a Pen.
Bitmap  The Bitmap that a Pen will draw to.
Blue  The blue component of a pen's colour.
Fill  Turns fill mode on and off when drawing a pen.
Green  The green component of a pen's colour.
Height  Determines the height of a Pen's shape when drawing.
PenShape  The shape to use when drawing a Pen.
Red  The red component of a pen's colour.
TipShape  Defines the shape of a pen's tip.
TipSize  The pixel size of a pen's tip.
Width  Determines the width of a pen's shape when drawing.
XCoord  This coordinate is used for drawing certain Pen shapes.
XEnd  This coordinate is used for drawing certain pen shapes.
YCoord  This coordinate is used for drawing pens.
YEnd  This coordinate is used for drawing certain pen shapes.
Method:PenArc()
Short:Draws an arc to a Bitmap.
Arguments:
OBJECTPTR Bitmap  Pointer to an initialised Bitmap.
LONG X1  The horizontal coordinate of the ellipse.
LONG Y1  The vertical coordinaet of the ellipse.
LONG X2  The horizontal coordinate of the ellipse.
LONG Y2  The vertical coordinaet of the ellipse.
LONG CX  The horizontal center of the arc's ellipse.
LONG CY  The vertical center of the arc's ellipse.

This function draws an ellipse within the area defined by the (XCoord, YCoord) and (Width, Height) arguments. If the Pen's Fill field is set then the ellipse will be filled. The colour of the ellipse is determined by the Red, Green and Blue fields.


Method:PenEllipse()
Short:Draws an ellipse to a Bitmap.
Arguments:
OBJECTPTR Bitmap  Pointer to an initialised Bitmap.
LONG XCoord  The horizontal coordinate of the ellipse.
LONG YCoord  The vertical coordinaet of the ellipse.
LONG Width  The width of the ellipse.
LONG Height  The height of the ellipse.

This function draws an ellipse within the area defined by the (XCoord, YCoord) and (Width, Height) arguments. If the Pen's Fill field is set then the ellipse will be filled. The colour of the ellipse is determined by the Red, Green and Blue fields.


Method:PenLine()
Short:Draws a line across a Bitmap.
Arguments:
OBJECTPTR Bitmap  Pointer to an initialised Bitmap.
LONG XCoord  The horizontal coordinate at which the line will start from.
LONG YCoord  The vertical coordinate at which the line will start from.
LONG XEnd  The horizontal coordinate at which the line will end.
LONG YEnd  The vertical coordinate at which the line will end.

This function draws a line from the coordinates (XCoord, YCoord) to (XEnd, YEnd). The thickness of the line can be adjusted with the TipSize and TipShape fields. The colour of the line is determined by the Red, Green and Blue fields.


Method:PenPoint()
Short:Draws a single pen tip to a Bitmap.
Arguments:
OBJECTPTR Bitmap  Pointer to an initialised Bitmap.
LONG XCoord  The horizontal coordinate of the point.
LONG YCoord  The vertical coordinate of the point.

This function draws a single Pen tip to coordinates (XCoord, YCoord) on a Bitmap. The resulting graphic may not necessarily be the size of a single pixel if you set the TipSize to a value larger than 1. The colour of the point is determined by the Red, Green and Blue fields.


Method:PenRectangle()
Short:Draws a rectangle to a Bitmap.
Arguments:
OBJECTPTR Bitmap  Pointer to an initialised Bitmap.
LONG XCoord  The left coordinate of the rectangle.
LONG YCoord  The top coordinate of the rectangle.
LONG Width  The width of the rectangle.
LONG Height  The height of the rectangle.

This method will draw a rectangle to a Bitmap. It will clip to the borders of the Bitmap and can optionally fill the rectangle or just draw the four sides depending on the value in the Pen's Fill field. The colour of the rectangle is determined by the Red, Green and Blue fields.


Field:Alpha
Short:Determines the translucency level of a Pen.
Type:LONG
Status:Read/Set

This field determines the translucency level of a pen. The default setting is 255, which means that the pen will be solid. Any other value that you set here will alter the impact of a pen graphic over the destination drawable. High values will retain the boldness of the pen, while low values can render it close to invisible.

Please note that the use of translucency will always have an impact on the time it normally takes to draw a pen.


Field:Bitmap
Short:The Bitmap that a Pen will draw to.
Type:struct Bitmap *
Status:Read/Write

Before calling the Draw action or any pen methods, the Bitmap field must refer to a valid Bitmap for the pen to draw to.


Field:Blue
Short:The blue component of a pen's colour.
Type:LONG
Status:Read/Write

This field determines the blue colour value when drawing pen graphics. It is set in conjunction with the Green and Red fields to create a complete RGB colour. Colour values are limited to settings between 0 and 255 inclusive.


Field:Fill
Short:Turns fill mode on and off when drawing a pen.
Type:LONG
Status:Read/Write

If this field set to TRUE, graphics primitives such as rectangles and ellipses will be filled when drawn. If set to FALSE, such shapes will not be filled. The default value on initialisation is FALSE.


Field:Green
Short:The green component of a pen's colour.
Type:LONG
Status:Read/Write

This field determines the green colour value when drawing Pen graphics. It is set in conjunction with the Blue and Red fields to create a complete RGB colour. Colour values are limited to settings between 0 and 255 inclusive.


Field:Height
Short:Determines the height of a Pen's shape when drawing.
Type:LONG
Status:Read/Write

Pen shapes that accept width and height dimensions (such as ellipses and rectangles) need to have their height set through this field. If the Height is not set, a default value will be used.


Field:PenShape
Short:The shape to use when drawing a Pen.
Type:LONG
Prefix:PEN
Status:Read/Write

If you will be using the Draw action to draw a Pen graphic, you will first need to set the PenShape field to define the shape that will be drawn. The shape that you choose will also require that you set additional fields to define the shape's size and coordinates. Available shapes and their associated parameters are listed in the following table:

TypeParameters
LINEXCoord, YCoord, XEnd, YEnd
SQUAREXCoord, YCoord, Width, Height
POINTXCoord, YCoord
RECTANGLE  XCoord, YCoord, Width, Height
ELLIPSEXCoord, YCoord, Width, Height

Field:Red
Short:The red component of a pen's colour.
Type:LONG
Status:Read/Write

This field determines the red colour value when drawing pen graphics. It is set in conjunction with the Green and Blue fields to create a complete RGB colour. Colour values are limited to settings between 0 and 255 inclusive.


Field:TipShape
Short:Defines the shape of a pen's tip.
Type:LONG
Status:Read/Set

This field defines the shape to use when drawing the borders of graphics primitives. Available shapes are TIP_CIRCLE for a circular tip, TIP_SQUARE for a square tip and TIP_PIXEL for a single pixel tip. The size of the tip is determined by the TipSize field.


Field:TipSize
Short:The pixel size of a pen's tip.
Type:LONG
Status:Read/Write

The pixel size of a pen's tip is defined in this field. This determines the thickness of graphics shapes when they are drawn. The range of the TipSize is limited between 1 and 50 inclusive. Be warned that tip sizes greater than 10 will be dramatically slower when drawing in comparison to smaller tip sizes.


Field:Width
Short:Determines the width of a pen's shape when drawing.
Type:LONG
Status:Read/Write

Pen shapes that accept width and height dimensions (such as ellipses and rectangles) need to have their width set through this field. If the Width is not set, a default value will be used.


Field:XCoord
Short:This coordinate is used for drawing certain Pen shapes.
Type:LONG
Status:Read/Write

Before drawing a pen shape with the Draw action, you will need to set its starting coordinate values. This particular field defines the horizontal coordinate and is paired with the YCoord field.


Field:XEnd
Short:This coordinate is used for drawing certain pen shapes.
Type:LONG
Status:Read/Write

This field needs to be set when using pen shapes that accept termination coordinates. The line shape is a common example. This field is paired with the YEnd field.


Field:YCoord
Short:This coordinate is used for drawing pens.
Type:LONG
Status:Read/Write

Before drawing a pen shape with the Draw action, you will need to set its starting coordinate values. This particular field defines the vertical coordinate and is paired with the XCoord field.


Field:YEnd
Short:This coordinate is used for drawing certain pen shapes.
Type:LONG
Status:Read/Write

This field needs to be set when using pen shapes that accept termination coordinates. The line shape is a common example. This field is paired with the XEnd field.