Basics
Windows

This section of the style guide describes the rules that KDE applications should follow when dealing with windows.

KDE, like all windowing systems, presents its applications in on-screen windows, which are normally movable and resizable, and can be positioned according to the user's wishes. Attempting to write guidelines which govern how applications present their data is fraught with danger; application developers know their users better than anyone else, and must be free to design their application in the way they feel best suits the way their users will want to work.

Guidelines, however, must be made. It is important to users, and to the strength of KDE in general, that all applications look, feel and work in a similar (or at least consistent) way. This allows users to apply the knowledge they have learned in the use of one application to another, and another, and so forth.

Before we proceed, let us start by dismissing one popular, but flawed windowing interface, known as the Multi Document Interface, or MDI. MDI was conceived several years ago, and was widely adopted by Microsoft for its Windows products. The MDI concept involves a single, large "mother window" which completely contains the entire application. In this sense, the "entire application" means all the document windows, toolbar windows, help windows and so on. Anything that the application shows on-screen will appear in this mother window. Probably the best-known MDI application is the File Manager supplied with Windows 3.1.

MDI makes things simple for the programmer and for a long time, it was the accepted way of doing things. But times and technology move on, and today MDI is widely considered to impose unnecessary restrictions on the way users work. Users with multiple desktops or large, high-resolution monitors don't want to be constrained by one mother window. Users expect the freedom to move windows where they want, and spread them out over as many desktops as suits them. The MDI mother window offers the programmer a simple way to control what is being displayed by the application, but it offers no benefits to the user. KDE applications, and in fact, all X based applications, do not use MDI. Instead, they use the Single Document Interface, or SDI.

An SDI-based application doesn't have a mother window that contains all the windows of the application. The application windows are all direct children of the X root window, which means they are controlled by the window manager and can be moved about the desktop environment as the user wishes. If the application needs to open and close additional windows, they are all opened as children of the root window. They may logically be children of other windows, in the sense that a dialog window belongs to some document window, but there is no control on the way the dialog window is used or positioned.

There are several levels of SDI. Some people argue that the first, known as Pure SDI, is the only one necessary, and that all applications can be written using this model. This may or may not be true, and debate rages on the issue. Time, and the efforts of programmers, will settle this debate, but in the meantime, this style guide will describe other levels of SDI, known as Cooperating SDI and Controlled SDI. Application developers are encouraged to implement their applications using the Pure SDI model, resorting to other models only when serious usability problems occur.

In the Pure SDI model, one window contains exactly one document, and, to all intents and purposes, that one document is the entire application. There is no overall controlling window of any sort, and windows that appear to be running the same application are not related. Consider a virtual terminal window, such as xterm. One window is one application. Each has its own menubar with its own Quit button and other features. Closing one terminal window has no effect whatsoever on others that may be open. Beneath the surface, it is possible that there is one process running all of these virtual terminals, but short of looking at the process table, the user has no way of knowing if that is the case.

If possible, KDE applications developers should use the Pure SDI model. It should be the first line of thinking when developers begin to design an application.

When implementing a Pure SDI based application, the developer should apply the following rules-of-thumb:

Each window should have a complete application menu that should be laid out according to the guidelines given in the Menus section of this guide. The New option should open a new window with either a blank document inside it or a copy of the current window's document. The document, in this context, means a new shell, a new (untitled) text file, a new (untitled) image, etc. KDE applications should not have empty windows. All windows must contain a document, which may be empty. Beneath the surface, the application may have opened another window of its own or forked off another process to handle the new window; but this is an implementation detail that can be decided by the programmer. The user of the (now) two applications need not know or care.

The application window should be labelled with the name of the document in the window, and the application name, separated by a hyphen. For example, "www.kde.org - Konqueror", "StyleGuide.ps - KGhostView", or "(untitled) - KEdit".

If a Pure SDI application is iconified, its document window and any other windows it has opened, such as help windows, dialogs, toolbars and so on, should be iconified with it. The window manager should present just one icon, which should bring back all the windows when activated.

Whenever a Pure SDI application is started, it should, if possible, check for an already running copy of itself. If such a copy is found, it should be that copy which performs a New action, thus making a new application appear. This guideline is so that large programs, such a Wordprocessors, don't simply run in multiple copies of themselves and hog all the user's memory. There may be applications which, for technical reasons, are unable to comply with this rule. If this is the case, so be it, but programmers are requested to be nice with their users' resources whenever possible!

If the user attempts to open the same file twice in apparently separate applications, which may in fact be one application below the surface, they should be allowed to do so. Consider that if there were two applications, there would be nothing to complain about, and that is the way the user would expect things to happen. Users work in many strange ways and must be allowed to do what they want to do, even when it seems odd. The application should be able to cope with such things.

There should be one instance of an extra window, such as a toolbar, per window, as required by the user. Two application windows must not be allowed to share one toolbar, even if this is technically possible because of the way the application has been implemented.

A drag and drop operation into a document window should perform an Open on the dragged document in that window.

Some argue that Pure SDI is all that is required, but some examples of applications have been put forward in which the Pure SDI model seems too restrictive or complicated. One potential problem with Pure SDI is where one application wants to change a setting that might be of use to other instances of that application. For example, consider a web browser, implemented as a Pure SDI application, in which each window can contain one web page. Each window works in isolation of the others, and is, in effect a complete web browser in of itself. This model works well, but suppose the user wants to change the bookmarks file, or the default font in which pages are rendered. Does it make sense to change just the bookmarks for one web browser application or all of them? Should the font change in all browsers or just the one the user actually made the change in?

In some cases, these questions are easy to answer; in others, they are more difficult. The application programmer must decide what is best. But as soon as the programmer decides that a change should affect all open documents running under the application, the Pure SDI model breaks, for under that model, applications are separate; and changing something in one of them may not in any way affect what happens in another.

If a programmer decides that this kind of interaction is necessary in his/her application, then he/she must move away from the Pure SDI model and work within the Co-operating SDI model. The Co-operating SDI model builds on the Pure SDI model by adding some optional features that the programmer can utilise and by allowing some things that Pure SDI forbids.

The Co-operating SDI model contains all the rules and requirements of the Pure SDI model with the following modifications:

Each window still contains exactly one document, and each document still represents one instance of the application. There is still a menu on each window, and the menu items work as described for the Pure SDI model. However, each application window is aware of the other windows that are running the same application, and this awareness may be utilised by the application.

An application may have another menu on its menubar, labelled Windows. If present, this should be the rightmost entry (except for Help). The menu will contain a list of the other documents currently open in other windows; selecting one from the list will raise the appropriate window.

The Windows menu may also contain a Close all option. This option should be located at the bottom and be separated from the items above it. It should close all the listed documents and their windows.

Pure SDI and Co-operating SDI have one feature which many consider a problem. If an application requires the ability to open more files than there are windows available to view them, some form of control must be taken over those open files, and the way they are represented in the available windows. As an example, suppose an application is launched with a command like "Kapp *.jpg", and there are 2000 JPEG files in the working directory. Under Pure SDI or Co-operating SDI, where one document has one window, 2000 windows would open. This would be a bad thing.

The solution to this problem is to have some sort of controlling window, often containing a list of the files which are open and ready for use. New document windows are created in order to work with these files as required. In the example given, there could be between 0 and 2000 open document windows at any one time, with one controlling window managing them. This is known a Controlled SDI.

It is vitally important to understand that the controlling window does not contain or in any way restrict the movement of the document windows. This is not an MDI interface; it is an SDI interface that uses a controlling mechanism.

Controlled SDI builds on the Co-operating SDI model. Everything in the Co-operating SDI model is available in the Controlled SDI model, together with the following features:

The control window should be labelled "<App> - Control".

The control window should have a menu laid out according to the normal guidelines. This menu will probably not be the same as the menus on the document windows. The File menu will have a New entry, but no Open.

The Quit option of the control window closes all the document windows (after any necessary save prompts) and exits the entire application.

The Windows menu entries introduced in the Co-operating SDI model, should be available on the control window File menu as well as the document windows. Document windows should have the same menu items that they would have in the Co-operating SDI model.

The contents of the control window are not laid down by these guidelines. In instances where the Controlled SDI model is more appropriate to the application than the Co-operating SDI model, the content of the control window should be fairly obvious. Care should be taken, however, to avoid putting controls that are really document-specific in the control window. An example of this is Gimp-1.1, which has a toolbar and menubar applicable to all document windows controlled by the control window. If Gimp-1.1 were a KDE application, each document window would have its own menu and toolbar, and the control window would contain the global configuration menu, a list of the documents currently open, or possibly a simple splash screen in the style of Wordperfect 8.

The top entry in the Window menu of each document window should be the control window.

The windowing interface model used by KDE is based on SDI - the Single Document Interface. The SDI approach should be used in all KDE applications. Pure SDI is the preferred model, and should be used whenever possible. When Pure SDI is not feasible, the developer should use the Co-operating SDI model for applications that need to share configuration information among application instances, or the Controlled SDI model for applications that require more documents open than windows displayed on the screen.

A window, be it a dialog, main window or any other type, must display conveniently in a size corresponding to 640x480 pixels. Further, when used in combination with the KDE enviroment the window must be usable and practical when the display runs in 800x600 resolution.

Previous Next