TIP 222: Add [wm attributes -alpha] Attribute on Windows

Author:		Jeff Hobbs <[email protected]>
Author:		Andreas Kupries <[email protected]>
State:		Final
Type:		Project
Vote:		Done
Created:	16-Sep-2004
Tcl-Version:	8.5
Keywords:	Tk
Tk-Ticket:	892194


This TIP proposes a new controlled attribute -alpha to control toplevel alpha transparency for the wm attributes command on Windows.


Windows 2000/XP+ has the ability to create windows with alpha transparency. This attribute would expose control for that functionality for Tk users. This is mostly an eye candy feature, but could be useful for fade-in splash screens or fancy demos.


A new attribute -alpha will be recognized by wm attributes. It will take a double value from 0.0 (completely transparent) to 1.0 (opaque) that signifies the percentage transparency of the toplevel. Thus, -alpha 0.9 would make the toplevel 90% visible (10% transparent). Any value outside [0.0..1.0] will be constrained to the nearest bound.

There are some special considerations for this feature. It only works on Windows 2000/XP+. The code handles the dynamic lookup of the necessary functionality. If you do not have the functionality, then any attempt to set the -alpha value will be ignored, and queries to -alpha will always return 0 (opaque).

Layered windows cannot use the CS_CLASSDC class style, so an alternative class must be made available. This is handled in the implementation transparently, with UpdateWrapper choosing the appropriate class as necessary. Transparent windows will use TkToplevelNoDC as their class name (normal is TkToplevel).

Efforts have been made to reduce calls to UpdateWrapper.

Reference Implementation

See Tk Patch 892194 http://sf.net/support/tracker.php?aid=892194

The reference patch implements the functionality along with one bug fix to UpdateWrapper - correct setting of the Z order of the window based on the previous wrapper window.

While this patch addresses Windows alpha transparency, it is available for other platforms. It is recommended that the same syntax be used across platforms.


Discussion focused around the use of -alpha versus -transparency. Some felt that the latter was more familiar to end users. The author refutes this with several points. First, the existing TIP#166 uses -alpha as well, for the same functionality specific to Tk images (using the same [0..1] value as well). Also, the underlying APIs for each platform refer to the alpha level as well. In looking over various documentation, transparency is often a boolean concept, which alpha is the gradual level. This is how it will be used in Tk.


This document has been placed in the public domain.