
XWindows.pas
unit
This unit contains definition of XWindow, which is a base class for
XForm and XApplet. It is a descender of XVisual and adds to it a set of properties and methods
peculiar to windows (i.e. to windows, which are to be registered in Windows environment) :
handle, styles, cursor, icon, menu and so on.
Creating of MFC-based controls, which use XWindow class, had required some
changes in its implementation, making it more similar to corresponding VCL class
TWinControl. But this does not lead to essencial increasing of size of resulting
executable, moreover with using of MFC-based classes only (vs self-painting controls) it
can become even smaller though this even expands set of possible controls, which could be
used by applet.
XWindow = class( XVisual );
XWindow properties:

Handle : HWnd;
- it is set when window is created and handle is allocated. Use it to pass it to
Windows API functions, requiring window handle (e.g. ShowWindow). |

ParentWindow: HWnd;
- returns handle of parent window. If this object is XForm, parent window is an
applet button window. For windowed controls, parent window is a form of type XForm and its
descenders. For MDI child form, parent window is its MDI parent window. |
ClsStyle : Integer;
- window class style. Default is CS_OWNDC.
Look at WNDCLASS topic in Win32.hlp to get more info about other possible flags.
Set it before creating a window (just after constructing the object). It
is possible to change class style at any time after creating but it is necessary to
repaint the window in that case (e.g. invalidating it) to apply changes. |
Style : Integer;
- window style. Default is WS_VISIBLE + WS_CLIPCHILDREN
+ WS_CLIPSIBLINGS + WS_CAPTION + WS_SYSMENU + WS_MINIMIZEBOX + WS_MAXIMIZEBOX +
WS_OVERLAPPEDWINDOW + WS_BORDER + WS_THICKFRAME.
Look at CreateWindow topic in Win32.hlp to get more info about window styles.
Set Style property before creating a
window. It is also possible to change style at any time after creating the window. |
ExStyle : Integer;
- extended window style. Default is WS_EX_CONTROLPARENT.
Other possible flags are WS_EX_ACCEPTFILES, WS_EX_APPWINDOW, and more. Look at CreateWindowEx topic in
Win32.hlp to get more info about extended window style flags.
Set ExStyle property before creating a
window. And it is possible to change style later. |
- Cursor : HCursor;
- default cursor for window class. |
- Icon : HIcon;
- default icon for window class. |
- Menu : HMenu;
- default menu for window. |
Caption : String;
Color : XColor;
- background color of client area not overlapped by children. This property is
inherited from XVisual and made public in XWindow. |
WindowsState : XWindowState;
- possible states are: wsNormal, wsMinimized, wsMaximized. Default is wsNormal. |
Canvas : Pointer;
- this property is a type of pointer. It can point to a canvas of type XCanvas but
only in case when canvases module is included into executable (unit XCanvases.pas is used
at least in one of linked modules). To know how it works, look at the XCanvas type
definition.
If applet is using canvases, canvas of window can be obtained by calling
function WindowCanvas( Window : XWindow ) : XCanvas. |
Properties inherited from XVisual:
- Enabled : Boolean;
- Default is True. Set it to False to disable focusing (and keyboard input) and
all mouse events for this object. |
Visible : Boolean;
- Default is True. Set it to False to void painting of object (form, control) and
taking its rectangle into account while autoplacing of aligned controls. |
BoundsRect : TRect;
- Use it to change position and size of visual object by the single operation to
avoid flicks (instead of consequence assignments of values to follow Left, Top, Width and
Height properties). |
- Left : Integer;
- Top : Integer;
- Width : Integer;
- Height : Integer;
Position : TPoint;
- Use it to change position of visual object with a single operation instead
assigning values to Left and Top properties to reduce resize and realign operations and to
avoid flicks. |
- Color : XColor;
Properties inherited from XClass:
Parent : XClass;
ChildCount : Integer;
Children[ Idx : Integer ] : XClass;
XWindow methods:
procedure CreateParams(
var Params : TCreateParams ); virtual;
- this method is intended to make process of creating MFC-based controls more
similar to this one in VCL. It is created from CreateWindow method to fill Params with
some values. Override it to make changes in Params fields before further processing. For
example, You may want to call CreateSubclass before returning (this will rewrite some
fields of Params with values, sensible for appropriate Windows control, eg. 'STATIC',
'BUTTON', etc.)
See for more detailes lesson 'how to create MFC-based controls' in
XMfcControl definition. |
procedure CreateSubclass(
var Params : TCreateParams; ClassName : PChar );
- subclasses window with certain standard Windows control data ('STATIC',
'BUTTON', etc.). Must be used in overriden CreateParams method. |
- procedure Show;
- makes window visible and brings it to front of view (making it active). |
- procedure Hide;
- makes window invisible. |
function ClientToScreen(
P : TPoint ) : TPoint;
- transforms coordinates of point given respectively to topleft corner of client
area of window to coordinates in screen. |
function ScreenToClient(
P : TPoint ) : TPoint;
function WndProc(
Msg : TMsg ) : Integer; override;
- handles Windows messages (WM_CLOSE, WM_NCDESTROY, WM_SIZE, WM_SHOWWINDOW,
WM_SYSCOMMAND.SC_MINIMIZE, WM_SETFOCUS, WM_SETCURSOR are handled only. To handle other
messages, override this function and supply code to implement its).
This method made public to simplify calling of it from XApplets.pas
unit. Usually You do not need call it directly, excluding calling of inherited one in
descending class. |
function GetIcon
: HIcon; virtual;
function GetWindowHandle
: HWnd; override;
- overrides method inherited from XVisual and returns Handle. This method used
internally to handle messages and usually You do not need to call
XVisuals.GetWindowHandle( ... ) to obtain window handle. |
function Windowed
: Boolean; override;
- overrides correspondent method of XVisual, returning True. |
Methods, inherited from XVisual:
- function ClientRect
: TRect; virtual; abstract;
- This method is leaving as abstract to prevent creating of instances of XVisual
class. Descenders of XVisual (XWindow and XControl)
are implementing this method by the way inherent in each of these two.
ClientRect usually is less or equal to BoundsRect
in size (but it is always is originating from topleft corner of the client area of visual
object itself, so Left and Top are 0 and Right and Bottom are equal to ClientWidth and
ClientHeight accordingly).
If You want to get ClientWidth and ClientHeight, first call ClientRect
once to obtain client rectangle and then use Right and Bottom
of that rectangle as ClientWidth and ClientHeight. This is more efficient then calling
ClientRect twice (or more) and using ClientRect.Right and ClientRect.Bottom . |
- function ElementAtPos(
X, Y : Integer; IgnoreDisabled : Boolean ) : XVisual;
- Searches visual child element taking place at the given position. Only Visible
childs are taking into consideration, and if IgnoreDisabled parameter is
set to True, then only Enabled childs can be found. If
two or more childs are overlapped, then first found is last created. |
- function ControlRect
: TRect; virtual;
- This method is intended in XVisual to return bounding rectangle from topleft
corner of client area of parent window (usually XForm).
For XWindow, this function returns ClientRect with topleft corner in (0,0)
point. |
function GetBoundsRect:TRect; override;
- this function is overridden to return actual window bounds rectangle if window
is existing. |
procedure SetBoundsRect(Value:TRect); override;
- similar function above, this method is overridden to change actual bounding
rectangle of window. |
procedure Invalidate;
virtual;
- Invalidates window. |
|
Following several virtual functions and procedures just inherited but not
overridden. |
-
function GetEnabled:Boolean; virtual;
procedure SetEnabled(Value:Boolean); virtual;
function GetVisible:Boolean; virtual;
procedure SetVisible(Value:Boolean); virtual;
procedure SetColor(Value:XColor); virtual;

procedure
DoPaint(DC:HDC; Rect:TRect); virtual;
- This is very important procedure. It must paint visual element (form, control)
onto given device context into given rectangle. XVisual implement just calls PaintChilds
and then PaintErase. If some painting need to be done between these two calls, override
DoPaint and do not call inherited one.
Take in attention, that XCustomControl overrides DoPaint, first calling
PaintChilds and then PaintTo virtual method, so descending self-painting (not windowed)
controls have to use PaintTo to perform painting. |

procedure
PaintChilds(DC:HDC; Rect:TRect); virtual;
- Paints childs of visual element. It has to be called before other painting of
visual control itself, because painting of each child is finishing with excluding its area
from clipping area (so it becomes unavailable for further drawing).
Such method of painting allows to prevent flickering in most cases (if
message WM_ERASEBKGND is ignoring - and it is made so in XCL). The main requirement for
self-painting controls is: avoid setting of the pixel more then ones during single paint
operation. And all area, what did not fill during painting must be filled with background
color AFTER painting. |

procedure
PaintErase(DC:HDC; Rect:TRect);
- Erases the rest of (non-clipped) Rect area after painting the control and
excludes Rect from clipping region calling ExcludeUpdRect. |
function GetUpdWndRgn:HRgn;
virtual;
- Returns handle of updating region for device context, which was obtained (by
XForm) when WM_PAINT message was come in. Virtual method of XVisual returns 0, and it is
overriding in XForm and XControl. |
procedure ExcludeUpdRect(DC:HDC;
Rect:TRect); virtual;
- Excludes rectangle from clip area of given device context. Use this procedure
instead of calling API function ExcludeClipRect, because overridden method of XControl and
XForm additionally excludes Rect from FUpdRgn:HRgn member, allowing to avoid repainting of
other controls not overlapping clipping area (anyway its will not be painted because of
clipping but simultaneous deleting excluded Rects from FUpdRgn speeds up executing). |
procedure ExcludeUpdRgn(DC:HDC;
Rgn:HRgn); virtual;
- Similar ExcludeUpdRect above. Use it instead of ExtSelectClipRgn because it does
not only call this API, but also excludes Rgn from FUpdRgn to reduce further painting. |
Methods inherited from XClass:
- constructor Create(
AParent : XClass );
- use it to create new XClass instance and to assign AParent to it as parent
XClass object (this will call method AddChild for AParent to
add newly created XClass instance as a child - if AParent is not nil) |
- destructor Destroy;
- destructor first calls DeleteChild method for parent XClass object. |
- procedure AddChild(
Child : XClass ); virtual;
- usually You do not need call AddChild manually. When child created with AParent
parameter, procedure AddChild is called automatically for parent to add newly created
object as a child of it. |
- procedure DeleteChild(
Child : XClass ); virtual;
- also do not call it usually. It is called for parent when child is destroying. |
Events of XWindow object:
OnClose : XEventAccept;
XEventAccept = procedure( Sender : TObject; var Accept : Boolean
);
- use this event to decide if window can be closed in response to
Windows message WM_CLOSE. If not, set Accept to False before return. |
Other definitions of XWindows.pas unit:
- XEventAccept = procedure(
Sender : TObject; var Accept : Boolean ) of object;
- XOnMessage = procedure( var Msg : TMsg; var Rslt : Integer; var Handled : Boolean ) of object;
- XColor = Integer;
- XWindowState =
(xwsNormal,xwsMinimized,xwsMaximized);
Also interface class XWindowsManager is declared here and
single variable GlobalWindowsManager of this type. This is
derived from TObject and has no methods and properties, but has events:
- OnCreateWindow : XOnEvent;
- OnDestroyWindow : XOnEvent;
- OnBeginPaint : XOnPaint;
- OnEndPaint : XOnPaint;
- These events are not calling by GlobalWindowsManager itself (this object exists
only in a single copy and applet has no other objects of XWindowsManager class, similar
that Applet is a single copy of XApplet class). These
events are only stored here.
Events OnCreateWindow and OnDestroyWindow of GlobalWindowsManager are called
in XWindow class only if its are assigned. And its are assigned only if XCanvases unit is
used and in that case its are redirected to GlobalCanvasManager which adds creating and
destroying of Canvas for XWindow when it is creating and destroying.
Similar above, events OnBeginPaint and OnEndPaint are used to make add-on to
XForm (derived from XWindow), which allow to prepare Canvas of XWindow object to paint
using given device context.
This object is intended here to provide optional extending of XForm with
canvases, which are not mandatory in XCL. Canvases are provided only if XCanvases unit is
used in your applet (for example, if You use self-painting controls, derived from
XCustomControl). |
Tasks.
Usually You have not to descend objects directly from XWindow. To
create new control, use XControl as a base. And to create new type of form use XForm as an
ancestor. Type XWindow can be useful if You are not going to use XForm capabilities of
containing controls and managing of active ones.
In XCL, XWindow is used to derive both XForm and XApplet classes. So, XWindow includes some code to support
capabilities to handle Windows messages:
- module XWindows is containing function WndFunc(hWnd,Msg,wParam,lParam):Integer,
which is used by default as WndProc for all XWindow objects. And WndFunc redirects
messages to Applet.WndProc (so, XWindows.pas uses XApplets
unit in implementation part to have access to Applet variable and XApplet type).
- when creating, XWindow object calls Applet.AddWindowed(Self) to get it know about itself
and to receive Windows messages from queue, addressed to it.
- virtual function WndProc( Msg : TMsg ) : Integer is introduced in XWindow class to
handle received messages.
goto XCL page
goto home
page