TIP #223: Full-Screen Toplevel Support for Tk

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[1] 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.

[Index] [History] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]