TIP:		222
Title:		Add [wm attributes -alpha] Attribute on Windows
Version:	$Revision: 1.8 $
Author:		Jeff Hobbs <jeffh@activestate.com>
Author:		Andreas Kupries <akupries@shaw.ca>
State:		Final
Type:		Project
Vote:		Done
Created:	16-Sep-2004
Post-History:	
Tcl-Version:	8.5
Keywords:	Tk

~ Abstract

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

~ Rationale

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.

~ Specification

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.

~ Comments

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.

~ Copyright

This document has been placed in the public domain.
