CoolTrayIcon, ver. 4.0.2

[Properties] [Methods] [Events]
[Known Bugs] [Hints] [Comments]

CoolTrayIcon is a tray icon component. It allows you to easily implement tray icons in your own applications, with various appearances and behaviors.

CoolTrayIcon can be used in a service. See my developer remarks on services.

Properties

Icon	property Icon: TIcon; The icon to display in the tray. This icon is 16x16 pixels and 256 colors (16 colors in Win9x and NT). If you use an icon file (*.ico) containing more than one icon, Delphi will use the first icon. If it's not 16x16 it will be scaled, which probably won't look good.
IconVisible	property IconVisible: Boolean; Whether to display the icon. This property has no effect in design mode.	Default false
Hint	type THintString = ShortString; property Hint: THintString; The tray icon's hint (max 128 chars), which is displayed when you move the mouse cursor over the tray icon. NOTE: On some older Windows versions (before IE 5) the hint is max 64 chars. NOTE: The time until the hint window closes is determined by Windows, so don't bother trying to change the interval, because you can't. Setting Application.HintPause and Application.HintHidePause has no effect.
ShowHint	property ShowHint: Boolean; Whether to show the hint.	Default true
PopupMenu	property PopupMenu: TPopupMenu; The popup menu you want to display when the icon is clicked.	Default true
LeftPopup	property LeftPopup: Boolean; Whether you want the popup menu to pop up when you click the left mouse button. Default is false, meaning only the right button will work. NOTE: LeftPopup must be false (or the popup menu unassigned) if you want to double click the tray icon without displaying the popup menu. LeftPopup must be false if you want CoolTrayIcon to handle a menu that has a default menu item.	Default false
Enabled	property Enabled: Boolean; Works like Enabled for other controls, enabling/disabling keyboard and mouse input. Useful when you want to temporarily disable the popup menu, say while you are displaying an about box or some other modal window.	Default true
IconList	property IconList: TCustomImageList; An ImageList containing icons. If it contains other images than icons, the tray icon won't change when using CycleIcons, but no error occurs. NOTE: When you assign to IconList IconIndex is set to 0. NOTE: In D2 and D3 the property is of type TImageList in stead of TCustomImageList.
IconIndex	property IconIndex: Integer; The current icon in the assigned iconlist (or 0 if no iconlist is assigned).
CycleIcons	property CycleIcons: Boolean; Animates the tray icon by cycling through all the icons stored in IconList and assigning them to Icon. When you set CycleIcons to true, it will begin with the first icon in IconList. NOTE: CycleIcons can be true even though you have no IconList. No cycling will occur in that case, but the cycle timer is still active, which will consume some resources.	Default false
CycleInterval	property CycleInterval: Cardinal; The time interval in milisecs. before selecting a new icon from IconList.
DesignPreview	property DesignPreview: Boolean; Enables you to preview the tray icon in design mode. You can watch what the icon looks like, see its hint, enable/disable it, test the popupmenu, and animate it via CycleIcons. NOTE: Set DesignPreview to false to avoid the design time icon appearing when you run your program. This is only a problem in the Delphi IDE, not in the finished exe-file. I couldn't find a way to kill the design icon in run-time, so you'll have to do it yourself. NOTE: Setting DesignPreview in run-time has no effect.	Default false
Handle	property Handle: HWND; The tray icon's handle.
WantEnterExitEvents	property WantEnterExitEvents: Boolean; Whether you would like to receive the OnMouseEnter and OnMouseExit events. These events require an internal timer to be active, so if you have no use for them set WantEnterExitEvents to false to minimize resource usage.	Default false
MinimizeToTray	This property applies only when the owner of the tray icon component is a form. property MinimizeToTray: Boolean; Whether you want to hide the main form instead of minimizing it. The form will hide and the tray icon will show.	Default false

Methods

Refresh	function Refresh: Boolean; Redraws the tray icon. You probably don't need to ever call this method.	Returns true or false
ShowBalloonHint	type TBalloonHintIcon = (bitNone, bitInfo, bitWarning, bitError); type TBalloonHintTimeOut = 10..60; function ShowBalloonHint(Title: String; Text: String; IconType: TBalloonHintIcon; TimeoutSecs: TBalloonHintTimeOut): Boolean; Shows a balloon hint (a kind of "sticky" popup hint). NOTE: Balloon hints are available in WinME, Win2000, and WinXP only. Calling this method in other Windows versions has no effect. NOTE: You can use a max. of 64 chars for the title and max. 255 chars for the text. The hint is visible for 10-60 seconds, or until the user clicks it (or until you programmatically hide it). You cannot show a balloon hint if the tray icon is not showing, and hiding the tray icon hides any balloon hint. NOTE: The HideBalloonHint method is automatically called by ShowBalloonHint, so you don't get multiple balloon hints.	Returns true or false
HideBalloonHint	function HideBalloonHint: Boolean; Hides the balloon hint (if any).	Returns true or false
PopupAtCursor	procedure PopupAtCursor; Pops up the associated popupmenu (if any). This method is usually called automatically in response to an OnClick event, but you can call it manually if you want the popupmenu to appear at other times. The menu will appear at the current cursor coordinates.
BitmapToIcon	function BitmapToIcon(const Bitmap: TBitmap; const Icon: TIcon; MaskColor: TColor): Boolean; Renders and returns an existing icon based on the bitmap given as parameter. The bitmap should be 16x16 pixels. Specify a color to be shown transparently or clNone for no transparency. NOTE: Bitmaps that are not exactly 16x16 will be scaled up or down.	Returns true or false
GetTooltipHandle	function GetTooltipHandle: HWND; All tray icons share the same tooltip window (the hint popup). This method returns the tooltip handle.	Returns handle or 0 if error
GetClientIconPos	function GetClientIconPos(X, Y: Integer): TPoint; Returns the cursor position inside the tray icon. Will return coordinates between (-1,-1) and (16,16). You would expect the coordinates to vary between 0 and 15, but Windows adds a border 1 pixel wide to all tray icons, which is appparently considered to be part of the tray icons. Depending on whether the tray icon has other tray icons as neighbours to the left, right, top, or bottom, the border is inserted as Windows sees fit. So in other words, this method is not exact. You should expect a variation of 2 pixels. If anyone sees a way to patch this, let me know.	Returns position in a TPoint
ShowMainForm	This method applies only when the owner of the tray icon component is a form. procedure ShowMainForm; Shows the main form. NOTE: It is important that you use this method when displaying the form, as it contains important calls that affect how the form and the application display themselves. See the demo app.
HideMainForm	This method applies only when the owner of the tray icon component is a form. procedure HideMainForm; Hides the main form.

Events

OnClick	TNotifyEvent; Works like the similar event for window controls. NOTE: The Click event corresponds to a MouseDown followed by a MouseUp. If no DblClick event is assigned the Click event fires immediately (ie. after the MouseUp). Otherwise it will wait for a small period of time to see if the user clicks again, in which case we have a double click. If no DblClick event is assigned a double click will actually cause the Click event to fire. This is intentional.
OnDblClick	TNotifyEvent; Works like the similar event for window controls.
OnMouseDown	TMouseEvent; Works like the similar event for window controls.
OnMouseUp	TMouseEvent; Works like the similar event for window controls.
OnMouseMove	TMouseMoveEvent; Works like the similar event for window controls.
OnMouseEnter	TNotifyEvent; Fired after the cursor enters the tray icon. Requires the WantEnterExitEvents property to be true.
OnMouseExit	TNotifyEvent; Fired after the cursor leaves the tray icon. Requires the WantEnterExitEvents property to be true.
OnCycle	procedure(Sender: TObject; NextIndex: Integer) of object; Fired just before the icon changes via CycleIcons. Returns the next index in the assigned imagelist.
OnBalloonHintClick	TNotifyEvent; Fired when the user clicks the balloon hint.
OnBalloonHintHide	TNotifyEvent; Fired after the balloon hint closes because another application needs to show a balloon hint, or because you called the BalloonHintHide method.
OnBalloonHintTimeout	TNotifyEvent; Fired after the balloon hint closes because it timed out.
OnStartup	This event applies only when the owner of the tray icon component is a form. procedure(Sender: TObject; var ShowMainForm: Boolean) of object; Fired initially at application startup when the main form is about to display. Set the ShowMainForm parameter to false if you don't want the form to display. NOTE: May fire multiple times for an MDI form (once for every child form created at startup). NOTE: Replaces the StartMinimized property found in earlier versions.

Known Bugs

The tray icon may disappear in NT4 if it is used in an interactive service and you log out, then log back in. This may be fixed in CoolTrayIcon ver. 4.0.1, but I'm not sure, as I don't have an appropriate NT machine to test on. Please tell me if you experience this problem on NT4 (BTW: some service packs, like SP6 seem to fix this problem). An explanation for why the problem occurs can be found here.
Some people report that the balloon hint events never fire. This is a bug in Win2000. It may be an issue with the SP2 service pack, but that is only a guess on my part. If you experience this bug, please report your service pack version, your Internet Explorer version, and your version of comctl32.dll. I can't fix the bug, but it would be interesting to locate it more exactly.
Occasionally someone reports that an application using CoolTrayIcon prevents the user from logging off until he manually terminates the application. I've more or less come to the conclusion that this is not a bug in CoolTrayIcon. More likely it's a bug in some other third party component. At least it seems people always get this error when they use CoolTrayIcon together with other third party components. If you get this error try removing the other components one at a time and see if that doesn't solve the problem (or even simpler - run my demo app. and see if it has the problem). Afterwards, if you still have reason to believe CoolTrayIcon is the problem, don't hesitate to tell me, but please perform this simple test of exclusion first.

Hints

How do you start your app. with the tray icon visible and the main form invisible?
At design time set IconVisible to true and set the form's Visible property to false. Set the ShowMainForm parameter to false in the OnStartup event. See the StartHidden demo.
What is the proper way to restore the form?
ALWAYS use the method ShowMainForm! This method contains important calls that affect how the form and the application display themselves. Simply setting the form visible is not enough.
I used the OnStartup event to hide the form, but I can still see a quick flash on the taskbar when the app. is starting?
If it bothers you you can set the Application.ShowMainForm property in the main project source, like this:
```
  .....
  Application.Initialize;
  Application.ShowMainForm := False;
  .....
```
How do I hide the application's icon from the taskbar?
Well, it's very simple:
```
  ShowWindow(Application.Handle, SW_HIDE);
```
To show it again, use SW_RESTORE or SW_SHOW as parameter. Also, if you display a child form the application icon will become visible again automatically.
Why does the tray icon not appear in my NT/2000/XP service app.?
Set the service's Interactive property to true and set IconVisible to true.
I want multiple tray icons in my app.?
Just create a CoolTrayIcon object for each tray icon you want. The component is optimized to share resources between the tray icons.

Comments

The CoolTrayIcon component is freeware. Feel free to use and improve it, but please include all original files if you redistribute the zip-file. If you have any comments or corrections to the component I would very much like to hear them. A lot of Delphi programmers have already told me they like the component and use it, which is a huge boost for my ego. Thanks a lot, guys - especially those of you who gave suggestions and pointed out the bugs.

If you use the component some credit somewhere in your app. would be a nice gesture, but it is not a requirement.

The component should work on any Windows platform (Win9x, ME, NT, 2000, XP). If you experience any problems related to the operating system you use, please tell me. Also, it should work in Delphi 4 and up (2 and 3?) and C++Builder 3 and up. Again, tell me if I'm wrong.

A word about services: CoolTrayIcon was updated in ver. 3.1.0 so it will no longer automatically assume its owner is a form. This allows you to use it for other purposes such as service apps. that have no form. Some of the properties, methods, and events don't make sense without a form, but rather than creating a superclass without these properties/methods/events I've simply let them stay in CoolTrayIcon itself. You can use them in your service app., but they will not do anything. I figured the component would be more flexible and easier to extend into subclasses this way.

Get the latest version from http://www3.ewebcity.com/troels/delphi.asp.

Troels Jakobsen
delphiuser@get2net.dk