CGraphicsContext Class Reference

Determine if the Gc is a CFbsBitGc

Gets the amount of space in pixels by which to adjust letter or word spacing, given the total number of words and spaces, a start space, and the number of units to be adjusted.

The first two arguments are the number of pixels (character groups) and the number of units (word spaces) over which justification is to occur. The third argument specifies the current character group or word space, while the final argument specifies the number of units that are to be adjusted.

A panic occurs if aExcessPixels is 0, aTotalUnits is not greater than 0, or aFirstUnit is not less than aTotalUnits.

See also: SetWordJustification() SetCharJustification()

Gets the amount of space in pixels by which to adjust the current letter or word spacing, and also retrieves the number of excess pixels and word spaces remaining after the adjustment is performed.

The arguments are the number of remaining pixels (character groups) and units (word spaces) over which justification is to occur. The function can be called repetitively until the number of units is zero, and hence justification is complete. A panic occurs if the number of units is less than one or the amount of pixels is zero.

See also: SetWordJustification() SetCharJustification()

Maps pixels in the specified rectangle. The function tries to match the colour of a pixel with one of the RGB values in an array of RGB pairs. If there is a match, the colour is changed to the value specified in the other RGB in the RGB pair.

Sets the drawing point relative to the current co-ordinates.

A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing point as the start point for the line drawn.

Notes

The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline() also change the internal drawing position to the last point of the drawn line(s).

The internal drawing position is set to the co-ordinate origin if no drawing or moving operations have yet taken place.

Sets the drawing point relative to the co-ordinate origin.

A subsequent call to DrawLineTo() or DrawLineBy() uses the new drawing point as the start point for the line drawn.

Notes

The operations DrawLine(), DrawLineTo(), DrawLineBy() and DrawPolyline() also change the internal drawing position to the last point of the drawn line(s).

The internal drawing position is set to the co-ordinate origin if no drawing or moving operations have yet taken place.

Draws a single point. The point is drawn with the current pen settings using the current drawing mode.

Note:

If the pen size is greater than one pixel, a filled circle of the current pen colour is drawn, with the pen size as the diameter and the plotted point as the centre. If the pen size is an even number of pixels, the extra pixels are drawn below and to the right of the centre.

See also: SetPenSize()

Reserved function for future use.

A reserved virtual function for future use.

Resets the graphics context to its default settings:

the drawing mode is TDrawMode::EDrawModePen (pen and brush colours used as they are)

there is no clipping rectangle

the pen settings are: black, solid, single pixel size

the brush style is null

no text font is selected

Sets the brush colour.

The effective brush colour depends on the drawing mode.

Notes:

The brush is used for filling shapes and the background of text boxes. In case of outlined text, the brush is used for filling the font. The brush has colour, style, pattern and pattern origin parameters.

If no brush colour has been set, it defaults to white. However the default brush style is null, so when drawing to a window the default appears to be the window's background colour.

See also: SetDrawMode()

Sets the brush pattern origin.

This specifies the top left-hand corner position for the pattern tile around which copies of the pattern are tiled.

The brush pattern may be a built-in style, or a bitmap. To use a bitmap, the brush must have a pattern set and the brush style must be set to TBrushStyle::EPatternedBrush.

Notes

The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters.

If SetBrushOrigin() is not used, then the origin defaults to (0,0).

This brush origin remains in effect for all fillable shapes drawn subsequently, until a new brush origin is set. Shapes can thus be considered as windows onto a continuous pattern field (covering the whole clipping region of a screen device, or the whole device area of a printer).

See also: SetBrushStyle() UseBrushPattern()

Sets the brush style.

Ten brush styles are provided, including six built-in hatching patterns. Note: The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters. Note: Use TBrushStyle::ENullBrush to draw the outline of a fillable shape on its own, without filling. Note: If the TBrushStyle::EPatternedBrush style is set, but no bitmap pattern has been selected using UseBrushPattern(), then the function panics. Note: Hatching lines are done in the current pen colour, set using SetPenColor(). The hatching pattern starts at the brush origin, set using SetBrushOrigin().

See also: TBrushStyle::ENullBrush TBrushStyle::EPatternedBrush UseBrushPattern() SetPenColor() SetBrushOrigin()

Sets character justification.

This function is required by the Text Views API, and is not intended for regular use by developers.

It affects the strings of text used in the calls to DrawText() that follow, until the number of characters drawn equals aNumChars.

The text line that is to be justified has a certain number of characters this includes the spaces between the words. It also has a distance (in pixels) between the end of the last word and the actual end of the line (right hand margin, usually). These excess width pixels are distributed amongst all the characters, increasing the gaps between them, to achieve full justification of the text line.

Use CFont::TextCount() to return the excess width.

Notes:

This function is provided to allow simulation of printer fonts on screen. Due to the fact that fully-scalable fonts are not used before v5, large printer fonts can be simulated by using the nearest smaller font and widening it slightly.

If the excess width is zero, then calling SetCharJustification() has no effect.

SetCharJustification() is required for WYSIWYG where the layout uses printer font metrics but screen fonts have to be drawn on the screen. Because continuously scalable typefaces (c.f. TrueType) are not used before v5 and because screen fonts are coarser and less numerous in their variety than the printer fonts, the best matching smaller screen font must be used with character justification to simulate the printer font on the screen.

There is also a situation where the gaps between characters on screen have to be reduced with character clipping. The screen font that best matches the printer font may have the required height, but has characters that are too wide. A line of text that works on the printer will then be too long on the screen, unless it is squashed horizontally. The number of pixels that overlap the end of the screen line must now be removed from the gaps between the characters, i.e. there is a negative excess width. This situation is especially important where adding a TAB on screen gives perfectly acceptable printout, but would push the last character of the line off the right hand side of the screen.

In practice what you do in printer layout mode is:

Calculate where the line breaks will come on the printer. To do this you use a printer font (which in practice means a table of character widths of the font that the printer will use).

Now change to use a screen font that is the closest font which is no taller that the printer font. In practice it will often be fatter maybe only for certain characters such as 'i'.

You have to recalculate the width of the characters using the screen fonts. You can do this using CFont::TextWidth() as you have already determined how many characters will fit on the line.

If, in the screen font, the characters are not as wide as the line then you can just use word justification to expand the line. You would only do this if the text is to be justified.

If, however, the characters are wider than the line then you would use character justification to clip each character. You would need to do this even if the line is not justified.

Thus, in practice, character justification will only very rarely be used to expand a line of characters.

Sets the clipping rectangle.

The area of visible drawing depends on the clipping rectangle, any items that fall outside the extent of the clipping rectangle will not be drawn. The default clipping rectangle is the full device area.

Note that clipping is additive. If a clipping region has been set using SetClippingRegion() then clipping will be to the intersection of that region and this rectangle.

See also: CGraphicsContext::SetClippingRegion() CGraphicsContext::SetOrigin()

Sets the clipping region, any items that fall outside the extent of the clipping region will not be drawn.

Note that clipping is additive. If a clipping rectangle has been set using SetClippingRect() then clipping will be to the intersection of that rectangle and this region.

See also: CGraphicsContext::CancelClippingRegion() CGraphicsContext::SetClippingRect()

Sets the drawing mode.

The way that the pen and brush draw depends on the drawing mode. The drawing mode affects the colour that is actually drawn, because it defines the way that the current screen colour logically combines with the current pen colour and brush colour. There are many drawing modes, each giving different logical combinations of pen, brush and screen colours. Each mode is produced by ORing together different combinations of seven drawing mode components.

The three most important modes are TDrawMode::EDrawModePEN, TDrawMode::EDrawModeNOTSCREEN and TDrawMode::EDrawModeXOR. The default drawing mode is TDrawMode::EDrawModePEN.

The drawing mode is over-ridden for line and shape drawing functions when a wide pen line has been selected. It is forced to TDrawMode::EDrawModePEN. This is to prevent undesired effects at line joins (vertexes).

Notes:

TDrawMode::EDrawModeAND gives a "colour filter" effect. For example:

TDrawMode::EDrawModeOR gives a "colour boost" effect. For example:

TDrawMode::EDrawModeXOR gives an "Exclusive OR" effect. For example:

TDrawMode::EDrawModeWriteAlpha should not normally need to be used by client code. The following are exceptions:-

Note that if you have a transparent brush or source bitmap and you are drawing to a window, then it is a defect to use EDrawModeWriteAlpha.

See also: CGraphicsContext::TDrawMode CGraphicsContext::TDrawModeComponents

Sets the position of the co-ordinate origin.

All subsequent drawing operations are done relative to this origin.

Sets the pen colour.

The effective pen colour depends on the drawing mode. The default pen colour is black.

Note:

The pen is used to draw lines, the outlines of filled shapes, and text. In case of outlined text, the pen is used to draw the outline of the font.

The class provides member functions to set the colour of the pen, the style of line and the line size drawn.

See also: CGraphicsContext::SetDrawMode()

Sets the line drawing size for the pen.

Lines of size greater than one pixel:

are drawn with rounded ends that extend beyond the end points, (as if the line is drawn using a circular pen tip of the specified size).

are always drawn in TDrawMode::EDrawModePEN mode, overriding whatever mode has been set using SetDrawMode().

Notes:

The pen is used to draw lines, the outlines of filled shapes, and text. The class provides member functions to set the colour of the pen, the style of line and the line size drawn.

Wide straight lines and arcs have rounded ends so that concatenated wide lines have smoothly rounded corners at the vertexes.

When lines are made wide, the extra strips of pixels are added equally to both sides of the line. This works precisely for lines of odd pixel size (3, 5, 7, etc.). Wide lines of even pixel size, (2, 4, 6, etc.), have the extra strip of pixels added to the right and/or below the line.

Wide outlines of ellipses and wide line arcs are drawn with the pixels distributed either side of a thin (single pixel wide) true ellipse constructed in the normal manner. Wide ellipses and arcs of even pixel size have the extra strip of pixels added to the right and/or below the curved line. This gives a slight asymmetry to ellipses.

If the pen style is dotted or dashed, the size specification is ignored: a single-pixel wide primitive is drawn, (this is device dependant).

A line size of zero is handled as if the pen style had been set to TPenStyle::ENullPen.

Sets the line drawing style for the pen.

There are 6 pen styles. If no pen style is set, then the default is TPenStyle::ESolidPen. To use a pen style, its full context must be given, e.g. for a null pen:

CGraphicsContext::TPenStyle::ENullPen Notes:

The pen is used to draw lines, the outlines of filled shapes, and text. CGraphicsContext member functions are provided to set the colour of the pen, the style of line and the line size drawn.

The TPenStyle::ENullPen style should be used if a border is not required around a filled shape.

Dotted and dashed pen styles have a device dependant implementation, always give single-pixel size lines on the screen whatever the pen size set by SetPenSize() and can only be used for straight lines, polylines, non-rounded rectangles and polygons.

The dotted/dashed pattern is continued, without re-starting, for all consecutively drawn straight lines, i.e.

the outlines of rectangles the pattern starts in the top left corner. It is reset at the end of the function call.

the outlines of polygons the pattern starts at the first point. It is reset at the end of the function call.

polylines and straight lines the pattern starts at the first point initially. Consecutive calls to DrawLine() and/or DrawPolyLine(), whether the lines are concatenated or not, continue the pattern. It can be reset by a further call to SetPenStyle() using the same dotted/dashed style parameter.

See also: CGraphicsContext::TPenStyle

Set the font's shadow colour

Sets the strikethrough style.

This is applied to all subsequently drawn text.

Sets the underline style.

This is applied to all subsequently drawn text.

Adjusts the spaces between words to stretch or squeeze to a certain width.

The function is required by the Text Views API, and is not intended for regular use by developers.

The text line that is to be justified has a certain number of gaps (spaces) between the words. It also has a distance (in pixels) between the end of the last word and the actual end of the line (right hand margin, usually). These excess width pixels are distributed amongst the gaps between the words to achieve full justification of the text line. Spaces become fat spaces to keep underlining/strikethrough consistent. Pixels are distributed to the inter-word gaps starting from the left end of the string. The spacing between characters in each word remains unchanged.

After a call to SetWordJustification(), subsequent calls to either of the two DrawText() functions are affected until the number of spaces specified by aNumSpaces is used up.

The easiest way to find out the excess width and number of spaces is to call CFont::MeasureText(). This function can also perform counting, which is finding how much of some text will fit into a given width.

Use CFont::TextCount() to return the excess width.

For example, in the string "To be, or not to be", there are five inter-word gaps. If there are six excess pixels they will be distributed in the proportion 2, 1, 1, 1, 1 between the words. If there are nine excess pixels they will be distributed in the proportion 2, 2, 2, 2, 1 between the words.

Notes:

If the excess width is zero, then calling SetWordJustification() has no effect.

At first sight it may appear that SetWordJustification() is not required because you can simply call DrawText() for each word. However, underlined justified text does not work using this strategy you get a non-underlined gap between the space and the beginning of the next word.

Sets the brush pattern to the specified bitmap.

For the brush to actually use the bitmap, TBrushStyle::EPatternedBrush must be used to set the brush style.

When the brush pattern is no longer required, use DiscardBrushPattern() to free up the memory used, if the bitmap is not being shared. If UseBrushPattern() is used again without using DiscardBrushPattern() then the previous pattern is discarded automatically.

Notes:

The brush is used for filling shapes and the background of text boxes. The brush has colour, style, pattern and pattern origin parameters.

When loading a bitmap, the bitmap is checked to see if it is already in memory. If the bitmap is already there, then that copy is shared.

The brush does not need to have a pattern set at all. There are several built-in hatching patterns which can be selected using SetBrushStyle().

See also: SetBrushStyle()

Sets the device font to be used for text drawing.

If the font is already in memory, then that copy is shared.

Notes:

The CFont* argument must have been previously initialised by calling MGraphicsDeviceMap::GetNearestFontInTwips() with the required font-specification. If the CFont* has not been initialised correctly, and therefore does not point to an available font-bitmap, then a panic is raised.

When the font is no longer required, use DiscardFont() to free up the memory used. If UseFont() is used again without using DiscardFont() then the previous font is discarded automatically.

If no font has been selected, and an attempt is made to draw text with DrawText(), then a panic is raised.

See also: MGraphicsDeviceMap::GetNearestFontInTwips()