TIP:            223
Title:          Full-Screen Toplevel Support for Tk
Version:        $Revision: 1.6 $
Author:         Mo DeJong <mdejong@users.sourceforge.net>
State:          Final
Type:           Project
Vote:           Done
Created:        21-Sep-2004
Post-History:   
Tcl-Version:    8.5

~ Abstract

Tk lacks an optimal method for creating a full-screen '''toplevel'''.
A full-screen toplevel is one that has no borders and a client drawing
area that covers the entire screen.  On some UNIX systems, one can
create a normal toplevel that is a little larger than size of the
screen and place the upper left corner of the client drawing area at
at (0,0).  This option is not available under Windows as the position
and dimensions of normal windows are constrained to keep them from
covering up the start menu and task bar. Under Windows, a zoomed toplevel
with the ''overrideredirect'' flag set avoids this size restriction and
displays with no borders, both desirable properties. Unfortunately,
setting the ''overrideredirect'' flag also keeps an icon for the
toplevel from being displayed in the task bar and in the programs list
accessed via Alt-Tab. There are also some UNIX systems that restrict
the placement of a normal toplevel window. For example, the default
window manager for the KDE desktop restricts size and placement of a
normal toplevel in much the same way as Windows. This TIP and its associated patch implement full-screen functionality that also
displays an icon in the taskbar and is accessible via Alt-Tab.
The implementation adds a new '''-fullscreen''' option to the '''wm attributes''' subcommand.

~ Motivation

A Tk developer will at some point need to create a full-screen
application.  Existing Tk commands under Windows can be used to create
a mostly working full-screen application, but the edge cases where it
does not work well make the application look unprofessional. The
example code[http://wiki.tcl.tk/12506] was created to support a native
looking full-screen Windows application using only existing Tk commands.

The main problem this example attempts to work around is that a
toplevel with the overrideredirect flag set does not show an icon in
the Windows taskbar. To address this issue, a second fake window was
created and certain events for the fake window are redirected to the
full-screen window. This approach works for the most part but there
are some real user visible problems that don't seem to be fixable.
When a toplevel switched from regular to full-screen mode the user
observes two resizing operations, first to switch to the zoomed state
and another to switch to the overrideredirect state. Another user
visible problem shows when the interpreter is busy processing code
between the time a focus event is delivered to the fake window and it
is redirected to the full-screen window. The fake window is mapped
with a solid color fill for a moment which is visually disruptive.

A similar user visible problem can be seen when the Windows desktop is
stretched across two monitors. If the toplevel is moved over to the
second monitor and then placed in full-screen mode, the fake window
appears in the main desktop. This is especially disruptive because the
fake window needs to mirror the zoomed state of the full-screen window
so that the state available via a right click in the Windows taskbar
match up. The result is that the fake window covers up all the other
applications on the first monitor.

The final user visible issue shows up when a full-screen window is
first mapped. The window gets mapped in the normal state and is then
resized to full-screen instead of being mapped at the size of the
screen. These application behaviors do not match native Windows apps
and just look unprofessional. As a result, a project was undertaken to
create a Tk patch to address these issues.

~ Proposal

The implementation adds a '''-fullscreen''' attribute that can be
set to a boolean value of 0 or 1. Example code to switch a window
from normal to full-screen mode is as follows.

|proc fullscreen_switch { top } {
|    if {[wm attributes $top -fullscreen]} {
|        wm attributes $top -fullscreen 0
|    } else {
|        wm attributes $top -fullscreen 0
|    }
|}

An implementation for Windows has been created to support this
new '''-fullscreen''' attribute. The list of changed files
is as follows:

 > ''doc/wm.n, tests/winWm.test, tests/wm.test, win/tkWinWm.c''

Tk patch 1032982 has been created to track these modifications. The
patch mostly duplicates the way an overrideredirect window is created
with some modifications so that the window is the proper size and has
an icon in the taskbar. In ''UpdateWrapper'' the Win32
''CreateWindowEx'' function is invoked with the WS_EX_APPWINDOW flag
passed as the ''dwExStyle'' argument and
(WS_POPUP|WS_CLIPCHILDREN|CS_DBLCLKS) passed as the ''dwStyle''
argument. Example Win32 code to create a standalone example
of such a window is also attached and can be found in the file
named ''full_screen.c''. The patch also includes additions to the
Tk test suite and documentation to cover these modifications.

~ Alternatives

One alternative is to do nothing. The existing pure Tcl implementation
works for most cases. Reasons for rejecting this alternative have
already been covered in this TIP.

An earlier approach that added a new '''fullscreen''' state available
via the '''wm state''' subcommand was abandoned based on advice
from Joe English. After implementing it both ways, both the Tk,
and the end user code seemed cleaner using the attributes approach.

Assuming the TIP is accepted and a new attribute is added, there
is one implementation alternative that might be useful to explore.
There may be a way to pass a window manager hint to the Windows OS so
that it allows the creation of a normal window that is larger than the
height of the screen minus the height of the task bar.  That would
mean a regular window class could be used instead of a popup
class. The only user visible change would be that right clicking on
the icon in the taskbar would show a context menu with the Restore,
Minimize, Maximise, and Close options. The current patch creates a
taskbar icon that always pops the full-screen window to the top on a
left or right click. It is not clear that this minor detail is
important enough to worry about.

~ Risks

The complexity of Unix and Mac implementation of this TIP is currently
not known.

~ See Also

SourceForge patch: 1032982

~ Copyright

This document has been placed in the public domain.
