Class Documentation
Pen |
1.0 |
ID_PEN |
Unspecified |
Graphics |
graphics/bitmap.h |
May 2001 |
Rocklyte Systems |
Rocklyte Systems, 1996-2001. All rights reserved. |
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:
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. |
PenArc() |
Draws an arc to a Bitmap. |
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.
|
|
PenEllipse() |
Draws an ellipse to a Bitmap. |
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.
|
|
PenLine() |
Draws a line across a Bitmap. |
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.
|
|
PenPoint() |
Draws a single pen tip to a Bitmap. |
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.
|
|
PenRectangle() |
Draws a rectangle to a Bitmap. |
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:
LINE | XCoord, YCoord, XEnd, YEnd |
SQUARE | XCoord, YCoord, Width, Height |
POINT | XCoord, YCoord |
RECTANGLE | XCoord, YCoord, Width, Height |
ELLIPSE | XCoord, 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.
|
|