This unit contains definition of XApplet class and declaration of global variable Applet, which is intended to replace Delphi Application:TApplication variable. XApplet class is derived from XWindow because it defines application button window.
XApplet = class( XWindow );
XApplet properties:
- it is set to true when Applet.Run called and it is set to False before returning from this method. |
- it is set to True in procedure Applet.Terminate and stay the same to the end of executing. |
- first created XWindow (or its descender, i.g. XForm) becomes "main" and it is returned here. |
Properties, inherited from XWindow:
- 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). |
- 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. |
- window class style. Default is CS_OWNDC + CS_HREDRAW +
CS_VREDRAW. 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. |
- window style. Default is WS_VISIBLE + WS_CLIPCHILDREN
+ WS_CLIPSIBLINGS + WS_CAPTION + WS_SYSMENU + WS_MINIMIZEBOX + WS_MAXIMIZEBOX +
WS_OVERLAPPEDWINDOW. 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. |
- extended window style. Default is 0. 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. In particular, it is possible set flags WS_EX_TOOLWINDOW to remove applet from tasks list available by ALT-TAB keys and WS_EX_TOPMOST to place its forms on top of other windows on screen. Set ExStyle property before creating a window. And it is possible to change style later. |
- default cursor for window class. |
- default icon for window class. |
- default menu for window. |
- caption of window. |
- background color of client area not overlapped by children. This property inherited from XVisual and made public in XWindow. |
- possible states are: wsNormal, wsMinimized, wsMaximized. Default is wsNormal. |
- 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:
- Default is True. Set it to False to disable focusing (and keyboard input) and all mouse events for this object. |
- 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. In XApplet, making it False vanishes applet button from system task bar but not from tasks list (available by ALT-TAB). To make applet also unavailable by ALT-TAB, add also WS_EX_TOOLWINDOW flag to Applet.ExStyle property. |
- 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). Do not use this property and follows similar bounds-related ones in XApplet, because its window itself is invisible and operating system replaces it with applet button and control its bounds on task bar and its appearance. |
- 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. |
Properties inherited from XClass:
XApplet methods:
- XApplet can not have parent. So it's constructor is reintroduced to eliminate AParent parameter. |
- call this method after creating of main window (and possibly other windows) of applet. It starts message dispatchering loop, which works while applet is running. This loop is finishing either by receiving message WM_QUIT (sended anywhere in program by calling PostQuitMessage) or by calling Applet.Terminate. |
- call it to start terminating process of applet. After this call property Terminated retrns True. And when control is returned into applet messages loop, it is finishing, and applet is closing. |
- minimizies applet, hiding its windows and deactivating its applet button (if it is visible). This method is called automatically when main window receives WM_SYSCOMMAND message with SC_MINIMIZE command (thus is, when user clicks onto minimize box of main window). |
- restores applet windows in its last state after minimizing. Called automatically on activating the applet (e.g. by click on applet button, or swithcing to it with ALT-TAB key). |
- this method has to be called when new windowed descendent of XVisual is created.
You do not need to call it manually when override constructor of XVisual - it is called in
inherited constructor. Applet stores list of all windowed visual elements (forms, windowed controls) to redirect them messages from messages queue. |
- similar above, this method is called from destructor of XVisual. And You usually do not need call it manually. |
XWindow methods:
- 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.) You do not need use of CreateParams, thereas it is protected and You must not derive new classes from XApplet. |
- subclasses window with certain standard Windows control data ('STATIC',
'BUTTON', etc.). Must be used in overriden CreateParams method. As fo above method, it can not be used in Applet. |
- makes window visible and brings it to front of view (making it active). |
- makes window invisible. |
- transforms coordinates of point given respectively to topleft corner of client
area of window to coordinates in screen. Do not use ClientToScreen and ScreenToClient for XApplet object (this has no sence). |
- 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. |
- 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. |
- overrides correspondent method of XVisual, returning True. |
Methods, inherited from XVisual:
- This function do nothing in XVisual excluding call of CreateChildWindows and
returns False. When new windowed XVisual descender is designing, it must override this
function to create its window. It is supposing, that before creating window it forces
parent windows to be created (if it is not so) and after creating its own window calls
CreateChildWindows. Look XWindow for more details. In XApplet, CreateWindow can be called to force creating applet button window and applet's forms created before. Any way it is called when method Run is called, so You do not usually need call CreateWindow manually. |
- calls CreateWindow for all childs of the XVisual object. |
- 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 . |
- 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. Has no sense for XApplet. |
- 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. Has no sense for XApplet. |
- this function is overridden to return actual window bounds rectangle if window
is existing. Has no sense for XApplet. |
- similar function above, this method is overridden to change actual bounding rectangle of window. |
- Invalidates window. Has no sense for XApplet. |
Following several virtual functions and procedures just inherited but not overridden. |
- This procedure has no sense for XApplet object. For other XVisual descenders 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. |
- 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). This method has no sense for XApplet. |
- Erases the rest of (non-clipped) Rect area after painting the control and
excludes Rect from clipping region calling ExcludeUpdRect. Has no sense for XApplet. |
- 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. Has no sense for XApplet. |
- 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). Has no sense for XApplet. |
- 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. Has no sense for XApplet. |
Methods inherited from XClass:
- destructor first calls DeleteChild method for parent XClass object. |
- 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. |
- also do not call it usually. It is called for parent when child is destroying. |
Events of XApplet object:
- called in Applet.Minimize. Add your handler here to do something when applet is minimized. |
- called in Applet.Restore. Add your handler here to do something when applet is restored. |
- called in Applet.WndProc when message WM_ACTIVATE is received and it leads to activating of applet. Add your handler to do something on activating of applet. |
- called when applet is deactivating. Add your handler to do something in that case. |
- called for each message. You may add your handler by the usual way, assigning it
to this event. But if You use some XCL classes which can attach to this event, or if You
are creating such class yourself, please use technique of joining by chains:
This above procedure of attaching/deattaching is not mandatory here but only recommended. Therefore, I insist upon using this techinique in joining to events which are named with prefix On_ (e.g. XForm.On_AutoSizeForm, which is intended to make possible FormAutoSizer add-on). |
Event, ihherited from XWindow:
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. In XApplet I suggest You do not use this event but instead use such event of main window. |
Other definitions of XApplets.pas unit:
- this global variable represents a single instance of XApplet class. Create it in dpr-file and use XApplet class method Run to execute your applet. |
- use this procedure instead of API call ShowWindow( Wnd, ShowCommand) to perform showing/hiding window without animation (fast). |
Tasks.
Usually You have not to descend objects from XApplet. Just create it and call its method Run to start executing of applet.
I found that here is the best place to show as an example
how to start XCL project
which does not use VCL forms, controls and components and is extremely small.
First, create new project in Delphi. Then, open Project Manager and remove
Unit1 from list. Open Project|Options and in tab sheet Directories/... clear search
directories list. Save Your project (I prefer to create subdirectory for it in folder,
where XCL units are stored). In menu View|Project source (in D3) or Project|View source
(in D4) open .dpr-file which represents Delphi project but actually is pascal program.
Delete reference to Forms in uses clause, and add references to Windows and Messages
units. Also delete all lines between begin and end statements and save project. If You
uncheck now options 'Local symbols', 'Refernce info' (in tabsheet Compiler of
Project|Options dialog) and build this project, You obtain very small application (about
17Kbytes). But it can not do nothing and if You want to add some code to it, You will need
to create and show at least main window and some controls. And application becomes big
again. If not XCL...
Add now to uses clause of dpr-file references to XForms, XApplets, XClasses,
XWindows, XStrUtils, XVisuals, XGraphics (theses seven are minimal set of modules You
need) and other XCL and your units, which You need here. References to seven above minimal
necessary units have to be qualified with in operator (I suppose here that your XCL
project is located in subfolder of directory with XCL units):
uses Windows, Messages, XForms in '..\XForms.pas', XApplets in '..\XApplets.pas', XClasses in '..\XClasses.pas', XWindows in '..\XWindows.pas', XStrUtils in '..\XStrUtils.pas', XVisuals in '..\XVisuals.pas', XGraphics in '..\XGraphics.pas', MyMain; |
If You do so as above, You need to add here refernces to other XCL units
if You receive message 'can not found some_name.pas unit'. If You do not like it,
just open Project|Options dialog and in tab 'Directories/..' add directory where XCL units
are located (if You followed to my advice to locate project in subfolder of such
directory, it is sufficient to write '..' (without commas) as a single path). In that case
it is possible to list only XForms and XApplets units in uses clause of XCL project file,
and without full qualifying of names as above.
Then, write code similar following between begin and end statements (pay
attantion that existing global variable Applet is referred here and You must not create
other instances of XApplet class in your project):
Applet := XApplet.Create; MyForm := XMyForm.Create(Applet); Applet.Run; |
Second line here is calling your XMyForm class constructor, which declaration (I suppose) is located in your unit (e.g. mymain.pas) and such unit is listed in uses clause of this dpr-file (didn't forget to do it?). Another, You may create instance of XForm without deriving new one from it and just write:
Applet := XApplet.Create; XForm.Create; Applet.Run; |
As You see You even do not need to store created form in variable (because it is the first window, so it can be referenced as Applet.MainWindow). Try now to build this project and run it. You will see simple applet with one nonamed window, and even its button on system start bar has no caption. And if You made all right, its size must be about 28Kbytes.