_GRAPHICSBASE


Quick Data

Header file:graphics_base.h
Object name:_GRAPHICSBASE
Object index:1 of 1 Object

General Description

_GRAPHICSBASE is a class that is inherited by other classes that need graphics functions - you will not create an instance of _GRAPHICSBASE. However, three other objects use these functions, and as such, it's silly to go through and fully document all of them with the same methods. For that reason, all methods that are present in those classes through this class are documented here.

_GRAPHICSBASE handles graphics, like the name suggests. It handles setting pens and brushes, and drawing lines, shapes, text, and bitmaps. It paves the way so that all you need to do is work out a way to grab the Device Context for what you want to do - be that for a screen, a printer, or a bitmap. It is meant to make life easier, and so far it has.

The documentation for this class works a little differently than it has for other components. Instead of throwing all of the methods together in one large confusing table, the method table is broken up into subcategories which are more relevant, and I feel that makes this documentation a lot easier to use as a reference.

There is also an extra section in this documentation - how to make your class inherit these properties and still work reasonably.


Methods

The methods for this class have been seperated into categories to make browsing through them a lot easier than it might otherwise be. A list of the categories follows.


Setup methods

These methods deal with setting colours, fonts, brushes, and internal styles.


Prototype Description

void SetDC(HDC HDc); Should you need to short-circuit the normal operation of getting a Device context by suppling one you already had on hand, then this is the function to use to set that. The class will not overwrite a Device Context that you pass to this function - but when you are done, please un-set this by calling this function with HDc set to 0 (zero).
HDC ReturnDC(void); This function is used to return the HDC that is currently opened if you need it.
void StartDrawing(void); This function grabs the DC and tells the class to remember that HDC for later, which saves the time of having to go and get that HDC for every graphics function you call. Just make sure to call StopDrawing() when you are done, or otherwise the HDC will not be released, resulting in some wierd things. It is generally a good practise to call this function before you start drawing, as some functions may not work if you have not called this function first.
void StopDrawing(void); This function releases the HDC that was gained by the StartDrawing() function, and tells the class that any subsequent graphics operations need to get a HDC first.
void SetEnglishUnits(void);
void SetHiEnglishUnits(void);
void SetMetricUnits(void);
void SetHiMetricUnits(void);
void SetTwips(void);
void SetPixelUnits(void);
These function set what is known as the "mapping mode". The mapping mode describes how the units that you pass to a graphics function are interpreted - and there are many ways to interpret them. So what do each of these mean? A list follows.
  • English Units - each unit is worth 0.1 inches.
  • High English Units - each unit is worth 0.001 inches.
  • Metric Units - each unit is worth 0.1 millimetres.
  • High Metric Units - each unit is worth 0.01 millimetres.
  • Twips - each unit is worth 0.05 twips. What's a twip? A twip is 1/1440th of an inch.
  • Pixels - each unit is worth one pixel.
Most of these won't be overly useful to you, unless you are drawing on a printer, in which case it makes a lot of sense to draw in millimetres or inches. On a screen, however, pixels are the most logical choice, and the default is pixels. You can mostly assume though, if you want to use something other than pixels for the screen, that the screen has a resolution of 72 dots per inch. Don't ask me who made that up, but there you go. Note: you must have of called StartDrawing() first, or otherwise this function will not work. You will always need to call this function after StartDrawing(), because StopDrawing() makes the HDC revert to the old settings (It is not my fault. Blame Microsoft.)
void SetPen(int Style, int Width, COLORREF Colour); This function sets up all the options that you will need for a pen to draw lines with. These options affect any function that draws a line - be it the line function, or the rectangle function, or the ellipse function. The outside part will be drawn with the specified pen. Style is one of the following styles:
  • gpsSolid - A solid pen.
  • gpsDashed - A dashed-line pen.
  • gpsDotted - A dotted-line pen.
  • gpsDashDot - A dash-dot-line pen.
  • gpsDashDotDot - A dash-dot-dot-line pen.
  • gpsInvisible - A pen which doesn't draw a line. Useful if you want a filled circle/rectangle not to have a border.
Width is the width of the pen line, in pixels. Colour is the colour of the pen.
void SetPen(HPEN Pen); This function sets the pen to use from a HPEN that is passed along to the function. This pen is applied automatically and is not saved to apply next time.
void SetBrush(int Style, int Hatch, COLORREF Colour); This function sets the colour of the brush, which is used to paint areas. This brush will be used to paint the inside areas of things like filled circles and rectangles. It will also be used to fill areas if you use the fill area function. Style can be one of the following:
  • gbsHatched - A Hatched brush. See further down for the styles to use with this style of brush.
  • gbsHollow - A hollow brush. Good if you don't want to have an inside fill with the aforementioned graphics functions.
  • gbsSolid - A solid brush. You'll probably use this the most. It creates a brush that is a solid colour.
Now you can also specify a hatch pattern to make the brush draw, if you specify the brush style as gbsHatched. Otherwise, just pass 0 (Zero) for the hatch. If you do want a hatch, use one of these styles to make use of the hatch patterns:
  • ghsDiagonalB - A Backward diagonal hatch.
  • ghsDiagonalF - A Forward diagonal hatch.
  • ghsLattice - A lattice style hatch - with lines going down and across.
  • ghsDiagonalLattice - A lattice style hatch that goes diagonally.
  • ghsHorizontal - Simple horizontal lines.
  • ghsVertical - Simple vertical lines.
The Colour parameter specifies the colour of the brush.
void SetBrush(HBRUSH Brush); This function sets the brush to use from a HBRUSH that you might have already had. Please note that this brush is not saved for use later, and you must use this function after you have called StartDrawing().
void SetBackgroundColour(COLORREF Colour); This function sets the background colour for the background. The background would be things like the gaps between a dotted/dashed pen, the gaps between a hatched brush, the background colour for text, or even the background colour of a monochrome bitmap.

Lines and similar

These methods deal with drawing lines, boxes, rectangles, circles, and any other simply shape.


Prototype Description

void FillRectangle(RECT* Area); This function draws a filled rectangle with the dimensions specified by Area.
void FillRectangle(int X1, int Y1, int X2, int Y2); This function draws a rectangle and fills it with the current brush. The area is specified with the top left hand corner being (X1,Y1) and the bottom right hand corner being (X2,Y2).
void PlainRectangle(int X1, int Y1, int X2, int Y2); This function draws a plain rectangle that is not filled. The outside will be drawn with the current pen.
void Line(int X, int Y, int X2, int Y2); This function draws a line from the location specified by (X,Y) to the location specified by (X2,Y2) using the current pen.
void Circle(int X, int Y, int X2, int Y2); This function draws a circle or ellipse that fits within the specified area. (X,Y) is the top left corner of the rectangle and (X2,Y2) is the bottom right corner of this rectangle. This circle is filled with the current brush and outlined with the current pen.
void PixelPoint(int X, int Y, COLORREF Colour); This functions sets the point defined by (X,Y) to the colour that you passed to this function.
COLORREF GetPixelColour(int X, int Y); This function gets the colour of the pixel at the location (X,Y).
void Fill(int X, int Y, COLORREF BorderColour); This function does a flood fill of an area. The flood starts at (X,Y) and fills outward from that point until it reaches the colour specified by BorderColour. The current brush is used to do the fill.
void FillColourArea(int X, int Y, COLORREF FillColour); This function does a flood fill of an area. The flood starts at (X,Y) and fills outwards until it encounters a colour that is not FillColour. You should start on an pixel that is already FillColour, or otherwise this function won't do much.
int GetBitsPerPixel(void); This function returns the colour depth of the current device. This number would generally be one of a few values. It will most likely be either 1 (two colours, one bit), or 4 (16 colours, 4 bits), 16 (65536 colours, 16 bits), 24 (16,777,215 colours, 24 bits), 32 (16,777,215 colours, 32 bits, and an alpha channel), or could even be higher, depending on exactly what hardware you are running (I've heard of 48 bit colour devices - that is a lot of colours!).

Text

These methods deal with writing text, as well as changing the font styles, the colour, and some other associated properties for this text.


Prototype Description

void SetFont(HFONT Font); This function sets the font to use from a HFONT. Please note that this class does not save the handle for later, and you must apply this again when you need it, and only after calling StartDrawing().
void SetFont(fFONT* Font); This function sets the font from a fFONT object. It works just like the above function - and the handle is not saved for later.
void MakeBackgroundTransparent(bool Set); This function sets wether the background of the text is transparent or not. Pass TRUE to make the background transparent, or FALSE to make it un-transparent. By default it will be un-transparent.
void SetTextColour(COLORREF Colour); This function sets the colour of the text. This must be reapplied everytime that you start drawing.
void SetTextSpacing(int Space); This function sets the spacing between the characters in the text that you draw. It is specified in units - the units of whatever units you are using.
void Text(int X, int Y, char* Text); This outputs a single line of text at the location specified by X,Y.
void FormatText(char* Text, RECT* Rect, int Format); This function writes text out a little bit more fancier than the last function. This time you give a rectangle to draw in, and set some options that control how the text is drawn. Text is the text you want to write, Rect is the area inside which to draw it, and Format is one or a combination of the following values (if combining, use the OR (|) operator):
  • gtsAlignBottom - aligns the text on the bottom of the specified rectangle.
  • gtsAlignRight - aligns the text on the right hand side of the specified rectangle.
  • gtsAlignLeft - aligns the text on the left hand side of the specifed rectangle.
  • gtsAlignCenter - aligns the text to the center of the specified rectangle.
  • gtsVertAlignCenter - aligns the text so that it is vertically centred in the specified rectangle.
  • gtsCalculate - doesn't actually draw the text, rather it calculates how much space is required. You can use the GetTextOutRect() function to find what that area was afterwards.
  • gtsEndEllipse - if the function can't fit the text in, and this style is present, the function will draw as much text as it can fit in, and then add "..." to the end.
  • gtsPathEllipse - if the function can't fit the text in, and the text is a pathname, and this style is present, the function will format the text so that the most significant portions of the path a visible. Say you input "C:\Windows\System\Color\default.col" - and it can't be fitted in - windows might output "C:\Windows\Sy...\default.col".
  • gtsExpandTabs - if this style is present, the function will expand tab characters in the text to the default 8 spaces.
  • gtsNoClip - this style makes sure that the function does not clip the text to fit inside the specified rectangle.
  • gtsNoPrefix - normally when processing this string, if the string was "Hello&World", it would end up as "HelloWorld". If you set this style, the & character will be treated and drawn as a normal ampersand character, rather than an instruction to make the next character underlined.
  • gtsOneLine - this style specifies only to display a single line. Any type of carriage return or line feed will have no effect.
  • gtsBreakLines - this style makes the function do wordwrap if the lines do not fit in the specified rectangle. Also, this makes the function read and interpret carriage return and linefeed characters.
void FormatText(char* Text, int X, int Y, int X2, int Y2, int Format); Did you not like making up a RECT structure specially for sending to a FormatText function? Well, use this function instead - just specify the top left hand corner with (X,Y) and the bottom right hand corner with (X2,Y2). The same values for Format apply as did for the above function.
RECT* GetTextOutRect(void); This funcion returns a pointer to the RECT structure that is used to call the FormatText functions. If you specified the style of gtsCalculate, then you can retrieve what the function feels that the dimensions of the the text are.
void FormatShadowText(char* Text, int X, int Y, int X2, int Y2, int Format);
void FormatShadowText(char* Text, RECT* Rect, int Format);
These functions work just like the FormatText() function, except they draw text with a shadow.
void FormatHilightText(char* Text, int X, int Y, int X2, int Y2, int Format);
void FormatHilightText(char* Text, RECT* Rect, int Format);
These functions are like the FormatText() function, except that they draw text like it is hilighted.
int GetAveTextWidth(int StringLength); This function calculates what the average length of a string would be under the current font settings if the string had StringLength characters. The return value is in Pixels, unless you have changed the mapping mode.
int GetMaxTextWidth(int StringLength); This function returns the maximum length of a string that has specified number of characters under the current font settings.
int GetTextHeight(void); This function returns the height of any text drawn under the current font settings.
int GetTextHeight(char* String); This function returns the height of the specified string under the current font settings.
int GetTextWidth(char* String); This function returns the width of the specified string under the current font settings.

Bitmap methods

These methods deal with drawing bitmaps in various ways and styles.


Prototype Description

void Draw(int X, int Y, HBITMAP Bitmap); This function draws the specified bitmap at (X,Y). You will need to pass a handle to a bitmap for this function to work.
void DrawSection(int ScreenX, int ScreenY, int BitmapStartX, int BitmapStartY, int BitmapWidth, int BitmapHeight, HBITMAP Bitmap); This function draws a section of a bitmap on the current device. The section is drawn at (ScreenX,ScreenY). The section comes from the bitmap from (BitmapStartX,BitmapStartY) and goes for the width defined by BitmapWidth and for the height defined by BitmapHeight. Finally, you must pass a handle to a bitmap from which to gain this section from.
void StretchDraw(int X, int Y, int Width, int Height, HBITMAP Bitmap); This function draws the specified bitmap inside the area that starts at (X,Y) and goes Width wide and Height high. The bitmap will be stretched or shrunk to fit inside this area.
void StretchDrawSection(int ScreenX, int ScreenY, int ScreenWidth, int ScreenHeight, int BitmapX, int BitmapY, int BitmapWidth, int BitmapHeight, HBITMAP Bitmap); This function draws a section of the bitmap specified into a section of the screen that is specified. If the two sections are not the same size, the bitmap section will be stretched or shrunk to fit inside the area specified on the screen. The area of the screen that the bitmap fits into is specified by (ScreenX,ScreenY) and goes for ScreenWidth and ScreenHeight. The area of the bitmap to take out and draw is specified by (BitmapX,BitmapY) and goes for BitmapWidth and BitmapHeight.
void DrawWithMask(int SX, int SY, HBITMAP Mask, HBITMAP Bitmap); This function draws a bitmap with the specified mask. The mask is a black and white bitmap. The white areas of the mask indicate what areas of the bitmap to draw, and the black areas indicate what to discard. Use this carefully if you already have other things painted on the area that you wish to use this on.

Inheritance methods

These methods are the methods that you will be using should you inherit this class into another class. Pay attention now, or else your class won't work!


Prototype Description

virtual void Internal_GrabDC(void); This function will need to be replaced by your class. Inside this function you need to get the HDC for whereever you intend to draw to. The HDC will need to be placed into the member HandleDC.
virtual void Internal_ReleaseDC(void); This function will need to be replaced by your class. Inside this function you will need to release the HDC for whatever device you called it from. The HDC will be in the member HandleDC.
void Int_ChkRdy(void); This function is called to verify that a HDC has been obtained, and if not, it will obtain one. You should call this before trying a graphics function, if you write your own graphics function.
void Int_ChkAft(void); This function is called after a graphics function to release the HDC should that be required. You should call this function after a graphics function.

Sample Code

The following snippet gives a basic idea of how to use this component.


//Let's do some basic things.
//Like a rectangle, with black outline, red fill.
Graphics.StartDrawing(); //Not required, but good practise.

Graphics.SetBrush(gbsSolid, 0, RGB(255,0,0)); //The fill.
Graphics.SetPen(gpsSolid, RGB(0,0,0)); //The outline.

Graphics.FillRectangle(10,10,100,100);

//Maybe some text...
Graphics.SetFont(&Font);
Graphics.SetTextColour(RGB(0,255,0)); //Green text.
Graphics.MakeBackgroundTransparent(TRUE); //Transparent text.

Graphics.Text(10,10, "Hello there!!");

Graphics.FormatText("Hello there!!", 10,50, 100,20, gtsOneLine);
Graphics.FormatText("Hello there!!\nThis is cool!", 10,70, 100,40, gtsBreakLines);

//And when you are done (but only required if you called StartDrawing())
Graphics.StopDrawing();

The following code shows an example of how to inherit this class in one of your own functions. In this example, the code for the fSCREENGRAPHICS class is shown.


//Include nessecary headers...
#include "graphics_base.h"

class fSCREENGRAPHICS : public _GRAPHICSBASE {
      private:
              HWND FormHandle;

      public:
             //You must replace these functions with
             //however you need to get your HDC.
             void Internal_GrabDC(void)     { HandleDC = GetDC(FormHandle);                  };
             void Internal_ReleaseDC(void)  { ReleaseDC(FormHandle, HandleDC); HandleDC = 0; };

             //These functions are extra to this class.
             void Setup(HWND Handle)       { FormHandle = Handle;                  };
             void ValidateWindow(void)     { ValidateRect(FormHandle, NULL);       };

             //Now, one last note. If you write your own graphics function, you might
             //like to do this:
             void Line(...) 
                  {
                  Int_ChkRdy();
                  Graphics_Line(HDC, ...);
                  Int_ChkAft();
                  };
             //The functions Int_ChkRdy() and Int_ChkAft() check whether or not you
             //have a valid HDC ready. If not, it will get one or destroy one as required.
             //This means that you can either call the function after StartDrawing() or
             //just call it by itself. It's up to you.

};

Back to indexThe FreeFoote Foundation Classes Documentation