XGraphics unit of XCL is containing only definition of
necessarily both for MFC-based and self-painted (using canvas) controls simple graphic
objects - XPen, XBrush and XFont. All these three classes are direved from XGraphicObject,
which is descendent of poor Pascal object TObject. So, if You create any of these objects,
You are responsible for its freeing. This is made as well as it is in VCL.
But using of XPen, XBrush and/or XFont in XCL classes does not require
canvases as it is done in Delhi VCL. It is because XGraphicObject knows nothing about its
owner, it is usual object of Delphi, which can own of handle of its appropriate windows
GDI object (if it is actually created).
Because XCL is intended to create small applets, it usually does not
need in complex threads-oriented controlling of GDI objects. Therefore, there is exist
add-on, which allows caching of GDI resources and avoid its duplicating. You may include
it and use it if You create applet with very large painting (or with great number of
controls) - to economy GDI resources.
I'd like to notice You that XFont of
XCL (vs TFont of VCL) has embedded property Orientation, which potentially allows painting
of rotated text. But some additional conditions have to be met:
Another difference is follow: if You want to set bitmap to XBrush object, use HBitmap type (Windows handle of bitmap object). This allows to XBrush and other XGraphicObject to know nothing about bitmap objects similar Delphi ones (having canvas, supporting load/save to/from stream, and other overbloats).
Also, this unit contains definition of class XGraphicsManager and declaration of single global variable of that type GlobalGraphicsManager, which is used to provide interface with optional add-ons (e.g., with add-on XCanvasObjects.pas).
XGraphicObject = class( TObject );
Properties of XGraphicObject:
- This property returns Windows handle of GDI object, creating it if it is not
created before. To prevent creating of GDI object first test if it is created using
function HandleAllocated. If add-on XCanvasObjects.pas is not used, new Windows GDI object is created for every graphic object. Add-on XCanvasObjects.pas allows multiple usage of GDI objects with the same properties and economize GDI resources (this can be important in Win95/98 environment). |
- Color property of GDI object. All three types of graphic object (XPen, XBrush and XFont need it, so it is declared here. |
Methods of XGraphicObject:
- assigns parameters of other graphic object with the same type (XPen, XBrush or XFont). Handle is not copied and it will be created when property Handle will be read first time. |
- allows to copy handle of graphic object. This method is used in external add-on XCanvasObjects.pas and is not recommended to use by any other way (at least, You must know what You do). |
- returns True only if handle is already allocated. Use this function before reading of Handle property, if You do not want to create GDI object in case when it is not yet created. |
- returns handle of incapsulated GDI object (if it is already created) or 0 and
releases it from graphic object, so the graphic object no longer know about the handle.
Returned handle (is any) is not freeing. You may use this function to force freeing of GDI
object, calling DeleteObject for released handle (if it is not 0). Also this function is used in external add-on XCanvasObjects.pas. |
- called when property Handle is read. Creates it if it is not already created. |
Event of XGraphicObject:
- this event is called when object properties are changed. It is privilege for owner of graphic object to set this event and it is used usually if master object is keeping graphic object as readable property. It is not recommended to change this event for graphic objects, which are owned by another object and available as public property of this last. |
XPen = class( XGraphicObject );
XPen properties:
- Pen width. Default is 0. |
- Pen style. Default is psSolid. |
- Pen mode. It is not used when pen is created, but it is used in XCanvas class during painting to set ROP2 mode (see Win32.hlp). |
XBrush = class( XGraphicObject );
XBrush properties:
- default is 0. You may set it using handle of bitmap. But XBrush is not responsible for freeing that bitmap resource. You have to free it by yourself. |
- style of brush. Default is bsSolid. |
All newly created XBrush objects have Color = clBtnFace.
XFont = class( XGraphicObject );
XFont properties:
- font height. It is possible to use (default) 0 to use default user settings for fonts, or even negative values to set font height in points, thereas positive values are set font size in pixels. I recommend use positive values (i.e. set font height in pixels). Some controls can be confused with negative values. |
- font pitch. |
- font style. |
- current font chartset. |
- font orientation specifies angle, in tenths of degree, between the x-axis and baseline of font. I.e. to rotate text onto 90 dgrees, set Orientatin to 900. It is not sufficient to change Orientation to paint rotated text. Font must be True Type, and origin of text output rectangle has to be calculated correctly. To perform this task, I recommend use special add-on XRotateFonts.pas, which supports rotating of XLabel control. |
- font family name (e.g., 'MS Sans Serif', 'Times' etc.) If You set DefFontName to 'Default', default font name is used (usually Fixedsys). |
When new XFont object is created, it obtains its value from several global variables:
You may change these values above to change default font parameters for all futher created fonts. This will have influence onto all controls of all forms of applet.
XGraphicsManager = class( TObject );
XGraphicsManager events:
A single global variable GlobalGraphicsManager : XGraphicsManager is declared here. It is only used to keep these two event above. These events are called by graphic objects. If add-on XCanvasObjects.pas is included, it uses these two events to extend XGraphics.pas unit with ability to avoid duplicating of GDI resources.
Also, all color constants (clBlack, clWhite, etc.) are defined here and a couple of useful functions to manipulate with colors:
- The same as ColorToRGB in Delhi VCL. |
- Returns average of two given colors. Can be used in graying of colors or in 3D-painting to get light and shadow version of base color. |
This module can be extended by
using external optional add-on XCanvasObjects.pas. To use it, call UseCanvasObjectManager
procedure (the best place to do it is dpr-file of your applet - before creating of first
form). When used, this add-on keeps all graphic object handles, avoiding creating
duplicated handles for GDI objects of the same type with the same property values. This
allows to reduce needs in GDI resources of applet.
This add-on is not necessary in very small applets. Use it only in
larger applets wth great number of controls or with a lot of painting.