KDE 3 Styleguide

Basics
Scope of this document
This document attempts to specify the look-and-feel for KDE applications. The goal is
to provide some rules-of-thumb for developers to create their applications interface so
that KDE software will have a consistent look-and-feel.

The guidelines in this style guide are only suggestions - they are not set in stone. It is
the application designer's duty to create a decent interface. Following rules will not do
that, but common sense will.

These guidelines are aimed at a typical application consisting of a menubar, toolbar,

working area and statusbar. Not every application necessarily needs to have all these
components, but if your application does, then the components should work as
described here. Please note that not every component described must be present in
your application.

Example
The KNotes program consists solely of a working area. Its interface is such that it
resembles the well-known paper Post-It notes of 3M.

Although it doesn't have a menubar or toolbar, the rest of its interface (e.g. dialogs,
use of mouse) should still follow these guidelines.

Conventions in this document

The recommendations in this style guide that are in normal text have been agreed
upon by the KDE Team.

Items marked like the following paragraph have not been agreed upon yet and are still
open for discussion:

Open for discussion

This is an example of an item we couldn't agree upon.
To stay compatible with other desktops, an application should crash when the user
moves the mouse.
Items marked like the following paragraph are an example only and are meant to
clarify a prior statement. If an example conflicts in some point with any statement

1
 KDE 3 Styleguide

made in this style guide, the statement is authorative. Please send a bugreport to
bugs@kde.orgif you notice such a conflict so that we can update the example.
Example
This is an example of an example.
In the following menu Alt-P is an accelerator for the Pasteitem.
Undo Ctrl+Z
Redo Shift+Ctrl+Z
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Select All
Find... Ctrl+F
Find Next F3
Replace... Ctrl+R
Application specific
entries
This style guide specifies what a KDE program should look like and how it should
behave. It does not specify how you should writeyour program (the implementation).
However, because KDE offers very convenient ways to obtain the described behaviour,
we will often provide a suggestion to make developers aware of the possibilities. The
suggestion will be marked as an implementation note, as the example below shows:

Implementation Note
Example of an implementation note.
If you use the KDialogBase class, the buttons in your dialog will automatically be laid
out according to this style guide.
Basics

GUI Usage
Most modern applications have a very similar layout to their main windows. They
offer a view of a documentand the controls needed to manipulate it. Controls for
actions are accessed through menus, with short cuts available through tool barsand
the keyboard. Feedback of what is happening to the document is usually displayed on
a status bar.

The model for this user interface is so prevalent that it is used even when the content
being displayed by an application is only a document in a very loose sense, for
example, in a file manager.

Several points must be fulfilled before a piece of software may be termed "user
friendly" (note that even today, 80 to 90% of software doesn't fulfill every point).

To be user friendly, software must be:

task-suitable:Don't offer so much functionality that it confuses the user or harms

functionality. understandable:When the user uses the application for the first time,
the user should be able to see quickly what it does and how to use it. navigable:The

2
 KDE 3 Styleguide

user should always be able to tell where he/she/it is. Don't restrict navigation too
much. conformable to expectations:The application should be consistent
throughout! tolerant of mistakes:Users are human - they make mistakes. The
application should allow them to Undo (without crashing, in particular). feedback-
rich:The application should always give immediate feedback to the user regarding
which actions(s) are being taken.

Basics

Terminology
A User Interface should be designed from the point of view of the user. Sometimes,
however, the views of the developer are quite different from the views of the user. The
story of Quitserves as an educational example.

To make sure that no misunderstanding occurs, The Definition of Termsdefines a few

of the most important terms when it comes to User Interface design.

The story of Quit

The term applicationoften causes confusion. To the user, each entry in the taskbar is
an instance of a running application. To a programmer, however, each UNIX process
is an instance of a running application.

Because users are not usually interested in implementation details (unless your
application crashes very often...), the number of UNIX processes the programmer
needs to give the application is irrelevant to them. The User Interface should express
itself in terms of the application as perceived by the user - not in terms of a UNIX
process.

It is very bad then, from a User Interface point of view, to have a "Quit" option that
terminates all applications (all application-like windows) handled by the UNIX
process. Instead, the "Quit" option should just terminate the single application
(window) in which the user selected the option. Other applications should remain
unaffected, whether they share the same UNIX process or not.

A quick overview of how to use quit and close in your application can be found here.

Definition of Terms
Above, we have used the rather technical term instance. Aninstanceof something is
much like an exampleofsomething. To clarify:

Example
Suppose you own two cars of the same brand and type. These cars are both the same
and different: They are the same in that they are of the same brand and type; but
they are different in that one can be in Rome while the other is in Paris. When you
refer to "a car", it is not always clear whether you are referring to the brand and
typeor to a single very specific car.But when you refer to an instanceof a car, you are
always referringto a single, specific car.

3
 KDE 3 Styleguide

The following terms are important for a good understanding of how theUser Interface
is perceived by the user. Each term is described based on properties known to most
users.

UNIX-process. A UNIX process takes up resources UNIX-processes show up in "ps",

"top" or similar programs. A UNIX process can crash.
Application Each window that has a menubar and/or toolbar is perceived by the user
as a single instance of a running application. Each instance of a running application
shows up in the task bar. Applications are represented by Icons. Clicking on such an
icon starts a new instance of the application. If it does not make sense to have more
instances of the same application around, it activates the already running instance.
Note:This is unrelated to the number of UNIX processes required. All instances of the
application could be served by a single UNIX process.
Document A document contains information A document has a storage location
associated with it, often in the form of a filename or URL. It can be opened in an
application. Only open documents can be modified. Changes can often be saved. An
open document can be closed. Documents are represented by Icons. Clicking on such
an icon opens the document in an appropriate application.
Window A window is part of an application and is used to present documents,
information, and/or tools to the user.

There are a number of ways in which the above terms can berelated. The simplest is
when one UNIX process is responsible for one application which consists of a single
window that presents a single document.

How many applications should be hosted by a singleUNIX process and how many
UNIX processes are needed by a single application are implementation issues. They
should be addressed by the developer based on technical issues. As such, they are
beyond the scope of this style guide.

The relationships between application, document(s), and window(s)are discussed in

the nextsection of this style guide.

Basics

Windows
Windowing Interfaces
This section of the style guide describes the rules that KDE applicationsshould follow
when dealing with windows.

KDE, like all windowing systems, presents its applications in on-screenwindows,

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 tothe strength of

4
 KDE 3 Styleguide

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.

KDE does not use MDI

Before we proceed, let us start by dismissing one popular, but flawedwindowing
interface, known as the Multi Document Interface, orMDI. MDI was conceived
several years ago, and was widely adopted byMicrosoft 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, itwas the accepted
way of doing things. But times and technology moveon, 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,
orSDI.

KDE uses SDI

An SDI-based application doesn't have a mother window that contains allthe 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 logicallybe children of other windows, in the sense that a dialog window belongsto
some document window, butthere 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 allapplications can be written using this model.
This may or may not betrue, 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 CooperatingSDIand Controlled SDI.
Application developers areencouraged to implement their applications using the Pure
SDI model,resorting to other models only when serious usability problems occur.

5
 KDE 3 Styleguide

Pure SDI
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 ownQuitbutton and
other features. Closing one terminal window hasno effect whatsoever on others that
may be open. Beneath thesurface, 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 SDImodel. It should be
the first line of thinking when developers begin to design an application.

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

Each window should have a complete application menu that should belaid out
according to the guidelines given in the Menussection of this guide. The Newoption
should open a new window with either a blank document inside itor 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. Forexample,
"www.kde.org - Konqueror", "StyleGuide.ps - KGhostView", or"(untitled) -
KEdit".

Implementation Note
KMainWindow::setCaption() adds the application name for you already. For other
windows you can use KApplication::makeStdCaption() to ensure style-guide compliant
captions.
If a Pure SDI application is iconified, its document window and anyother windows it
has opened, such as help windows, dialogs, toolbarsand so on, should be iconified with

6
 KDE 3 Styleguide

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
Newaction, thus making a newapplication appear. This guideline is so that large
programs, such aWordprocessors, 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 separateapplications,
which may in fact be one application below the surface, they should be allowed to do
so. Consider that if there weretwoapplications, there would be nothing to complain
about, and that is the waythe 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, perwindow, 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 anOpenon the
dragged document in that window.

Co-operating SDI
Some argue that Pure SDI is all that is required, but some examples ofapplications
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 aremore 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.

7
 KDE 3 Styleguide

If a programmer decides that this kind of interaction is necessary inhis/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 thePure SDI
model with the following modifications:

Each window still contains exactly one document, and each documentstill represents
one instance of the application. There is still amenu 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, labelledWindows. If present,

this should be the rightmost entry (exceptfor Help). The menu will contain a list of the
other documentscurrently open in other windows; selecting one from the list will raise
the appropriate window.

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

Controlled SDI
Pure SDI and Co-operating SDI have one feature which many considera problem. If an
application requires the ability to open more filesthan 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 controllingwindow, 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 doesnot contain or in

any way restrict the movement of the documentwindows. 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 theCo-operating

SDI model is available in the Controlled SDI model, togetherwith the following
features:

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

The control window should have a menu laid out according to the normalguidelines.

8
 KDE 3 Styleguide

This menu will probably not be the same as the menus on thedocument windows. The
Filemenu will have a Newentry, but noOpen.

The Quitoption of the control window closes all thedocument windows (after any
necessary save prompts) and exits the entireapplication.

The Windowsmenu entriesintroduced in the Co-operating SDI model, should be

available on thecontrol 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 theseguidelines. In instances
where the Controlled SDI model is moreappropriate 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 bethe control
window.

SDI, MDI summary

The windowing interface model used by KDE is based on SDI - theSingle Document
Interface. The SDI approach should be used in all KDEapplications. 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.

Windows size
A window, be it a dialog, main window or any other type, mustdisplay 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.

Basics

Labels
There are two major styles for capitalizing labels, book titleandsentence style. Some
people argue back and forth how one styleis more readable than the other, but what
plays the deciding role here is information hierarchy.

Book title capitalization capitalizes the first letter of a single-word item.

9
 KDE 3 Styleguide

Capitalization of amulti-word item should be based on title capitalization in the native

language. Thus, in English the first letter of the first and last words should always be
capitalized and the first letter of all intervening words should all be capitalized except
for (i) prepositions having less than five letters, except "From", which should be
capitalized (e.g. "for", "in", "with" or "to", but "From" or "Under"), (ii) conjunctions
("and", "or" and "but") and (ii) articles ("the", "a" and "an"). In short titles (buttons,
menus) articles are usually dropped and "and" is replaced with "&".

Example
This is an example of different label styles:

Example of Book Title CapitalizationExample of sentence style capitalization

Use either book title capitalization or sentence style capitalization asindicated in the
lists below.

Book title capitalization

window and dialog box titlesgroup box / group line labelsbutton labelstab
labelslistview column headersmenu titles / menu itemsderivatives of
KCommandcombobox itemslistbox itemstree list itemsother heading/title text

Tree list and listbox items that are representative of items found elsewherein the
system, like folders for example, should utilize the capitalization of the
representeditems.

Sentence style capitalization

edit box labelslist box labelscombo box labelsspin box labelscheck box labelsoption
button labelsspin box labelsslider labelspop-up hint textother non heading/title text
Use of colons
The label used for group boxes (that is, the title in a frame that surrounds a group of
options) should NOTend with acolon, ':'.

A label in frontof an option should end with a colon, ':'.

Basics

Settings
KDE applications have three different types of settings: options, document optionsand
the configuration.

Below an overview is given of each of these types of settings as well as how they
interact with Session Management.

Options
Options can be changed from the settings menu or by direct manipulation of GUI
elements and only apply to the current application instance. An example is positioning
of toolbars. Saving these options when the application closes is a nice optional feature
for the user. But not strickly needed.

10
 KDE 3 Styleguide

Note:in former versions of the styleguide the menu option 'save changes' was added.
This is obsolete and the application should always save the changed options instead.

Document Options
Document options are settings which are logically bound to a specific document or
location. When the document or location changes the options from the new
document/location will take effect. The options are saved whenever the document is
saved. The application may choose to save the options inside the file containing the
document or in some other place.

If the application does not save the document or location it may offer an option
"Save options for this URL." to let the user save the options explicitly.

Configuration
The configuration of an application can be changed with the "Configure..."menu
option(s). Changes in the configuration of an application are saved when the user
presses "OK"in the configuration dialog and take immediate effect in all application
instances!. (Even if the other instances belong to a different UNIX process.)

Session Management
Session Management is the ability of KDE to save the state of all desktops and to
restore this state at a later point in time. The state of all desktops is also referred to as
a "Session".

When an application gets saved by Session Management it needs to take care that
each application instance saves its own options in the save file it got assigned for that
session.

In addition the application needs to save any open file to a session specific location.
Document settings are, as usual, saved together with this document.

Session Management never saves and/or changes the configuration of an application.

Basics

Example
Here's an example of a document-centric user interface. Please have a look at the
order of the menus and the design of the tool bar, the status bar and the content area.

Please note that the content area as shown here may not always be so obvious. A
printer queue comes to mind, where the jobs might be displayed in the content area.
The rule is that variable data that can be manipulated with buttons or menus should
be displayed in the content area.

11
 KDE 3 Styleguide

Basics

Bad Interface
Some applications, usually small utilities, do not fit the document-centric UI
paradigm. For these applications it is usually best to design the UI as a dialog box.
However, combining the two paradigms in one window usually leads to a confused and
inelegant UI. Rule-of-thumb: Don't mix the dialog box paradigm(see Dialogs) with
the document-centric UI paradigm.

There is perhaps no better example of how applications should notbe designed than
the Find Applet in Windows95.

12
 KDE 3 Styleguide

The Find Applet is a truly bizarre mix of interface elements: a dialog box with a menu
bar. This is typically regarded as a common mistake for beginning programmers.
There has always been a rather simple rule to follow when designing a window:
dialog boxes don't have menus. Menus indicate a document-centric application,
such as a text editor or graphics application.

An Editmenu? What is there to cut, copy or paste? Since this dialog box has no Cancel
button, the first menu the user is likely to use is the File menu, since it contains the
Close command.

The Find window is not really a dialog box. Well, it is - sort of - until you perform a
search. The menus become relevant only after you have hit the Find Now button (as
opposed to Find Later?), and they are only relevant if the search was successful. As
soon as the user presses Find Now, the dialog box becomes taller to display the results
of the search. Of course, if you've moved the window to the lower portion of your
screen, you might never know that your search was successful.

In this way, the Find dialog exists as both a dialog box and a document-centric
application. Confused?

The basic problem is that the Find window attempts to display together content that
really should be displayed separately. There should be an initial Find dialog for the
user to enter search criteria, and a separate results window. This would allow the
design of a window optimized for its distinct purpose, without confusing the user with
extra irrelevant controls.

Thanks to the Interface Hall Of Shamefor this example!

Menus
Fixed menus provide access to all the actions possible on the document. It is important
that all possible actionsbe available! If an action should not be executed (e. g.
Cutwhen nothing is selected) then you should disable the entry in the menu.

This style-guide defines what the layout of the menubar should look like. Your

13
 KDE 3 Styleguide

application does not have to provide all the menu-options mentioned in this style
guide. However, if your application doesprovide a menu-option, its meaning and
location should match the meaning and location given here.

You may add additional menu entries (referred to as "application-specific" entries)

where you see fit. If, however, this style guide specifies a location for application-
specific entries, your application should only add additional entries at that location.

The menus should be placed in the following order, leaving out menus which your
application does not need:

File Edit View Go Application specific menus Bookmarks Tools Settings Help
Notice that every item in a menu that first opens a dialog requiring additional
informationmust be labelled with a trailing ellipsis (...)(e.g. Save As..., Open...).
There's no space between the menu item and the "...". A simple confirmation dialog is
not considered a dialog that requires additional information.

Please use separatorsin the same way as in the examples.

Do notput anything other than menus and menu-options in the menus or the menu-
bar.

Don't put status information in the menubar.Use a statusbarfor that!

Menu items should not be added or removed during runtime. Disable or enable them
instead. An exception to this is the case where an application has a list of items placed
in the menu, such as a list of bookmarks or a list of recently-visited web-pages. Such a
list requires the addition and removal of items to keep it up-to-date.

Menus

File
The contents of the Filemenu strongly depends on the type of application. For the
purpose of defining how Filemenus should look, we group applications into three
categories:

14
 KDE 3 Styleguide

Document-Oriented Applications, e.g. text editors, word processors, and image

manipulation programs. Games Other Applications.

Please note: This list may be extended in the future.

Document-Oriented Applications
This section describes the file menu for a document-oriented application. An
application is document-oriented if it operates on a document of some sort. Examples
of documents can be: Text Files, Images, Drawings, etc.

A document always has a storage locationassociated with it. This is the location where
the document is normally stored. The storage location can be undefined if the
document has just been created. The storage location is often a filename or a URL.

For a document-oriented application, a typical Filemenu might look like this:

New Ctrl+N
Open... Ctrl+O
Open Recent >
Save Ctrl+S
Save As...
Revert
Print... Ctrl+P
Close Ctrl+W
Quit Ctrl+Q
Not all menu items have to be present. If they are present, the items should have the
following meaning:

Opens a new empty document.

New If the application supports templates, this option may open a sub-
menu from which a template can be chosen.

Opens an existing document.

Open A file selection dialog should pop up to let the user choose which
document to open.

Open Offers a sub-menu listing documents that have recently been opened
Recent (the latest first).

Saves the document to its storage location.

Save If the document does not have a storage locationyet, this option is the
same as the Save Asoption below.

Opens the standard file-dialog to let the user select a storage

Save As... locationfor the document.
It then saves the document to this location.

15
 KDE 3 Styleguide

Revert the document to the version stored at the storage location.

Revert This is basically the same as closing the document without saving and
then re-opening it again.

Print... Opens a dialog from which you can print the document.

Close Closes the document.

Closes the application.

Quit Note that the application is _NOT_ necessarily the same as the
UNIX Process.
If the Newoption has a sub-menu then the Newoption does not have a shortcut key
combination assigned but rather a little arrow indicating that a sub-menu will be
presented when selected. The application may offer the shortcut key combination
Ctrl+N to select the default template from this sub-menu. The default template should
be the topmost item in the sub-menu.

If the application only offers a read-only view or if the data in the main document area
can never be saved back to the original source, Save As...should be the only saving
option offered in the File menu. It should also be bound to the default save keyboard
accelerator. The Saveentry is only appropriate when files can be opened, editted and
then saved back to the original file.

If the user has made modifications to the document and invokes the Closeor
Quitoptions, he/she should be asked by means of a dialog box whether the document
should be saved.

If the user has made modifications to the document and the Revertoption has been
invoked, the user should be asked for confirmation by means of a dialog box.

Depending on whether your application is an SDI or an MDI application, its behaviour

should follow the rules outlined below. Note that KDE applications should follow the
SDI model. The MDI model is listed for informational purposes only.

SDI applications
In SDI the application is represented by the document-window. Each document-
window can contain a single document.

Starting up an SDI application without specifying a document to load causes the

application to enter its initial state.

In the initial state an empty default document is shown in the document window. An
application may, by means of a modal dialog, ask the user whether to create a new
document or open an existing document. The dialog should provide an option for
experienced users to skip the dialog in the future. The dialog should also have an
option to Quit the application.

Example

16
 KDE 3 Styleguide

In the initial state an application might use a dialog like this:

After a document has been created or opened, the application is no longer in the initial
state. An application also leaves the initial state when modifications to the empty
default document are made.

If the application is in its initial state and the user opens a new document by selecting
Newin the File-menu or opens an existing document by selecting Openin the File-
menu, then the document is loaded into the application, replacing the empty default
document. This causes the application to leave the initial state.

If the application is NOT in the initial state and the user opens a new document by
selecting either Newor Openin the File-menu, then a new application is started in
which the document is loaded.

Implementation Note
Please note that a single UNIX process may serve multiple application instances.
Within KOffice a new application is started by creating a new KoShellWindow; in
other KDE programs, this is usually accomplished by creating a new KTMainWindow.

See the Terminologysection for the definition of applicationas used within this style
guide.
Closing the document by selecting Closein the File-menu causes the application to
return to the initial state. Note that this may cause a dialog to pop up asking the user
whether to create a new document or open an existing document.

Closing the application by selecting Quitin the File-menu closes the document-window
and the document within it. Closing the document-window by selecting the X on the

17
 KDE 3 Styleguide

window border is equivalent to selecting Quitin the File-menu.

Implementation Note
Please note that closing the application does not necessarily mean terminating the
UNIX process - other application instances may be using the same UNIX process and
they should remain unaffected!
MDI Applications

In MDI the application is represented by the application-window. The application-

window can contain a number of document-windows. Each opened document is
represented by a document-window. KDE applications should not use this model, but
use the SDI model instead.

Starting up an MDI application without specifying a document to load will result in an

application-window without any document windows.

When the user selects either Newor Openin the File-menu, a new document-window
appears.

When the user selects Closein the File-menu, the document-window is closed as well
as the document. Closing a document-window by selecting the X on the window border
is equivalent to selecting Closein the File-menu.

When the user selects Quitin the File-menu, the application window is closed as well
as all the document-windows and the documents with them. Closing the application-
window by selecting the X on the window border is equivalent to selecting Quitin the
File-menu.

Games
In games, the Filemenu is replaced with a Gamemenu. It often looks like this:

New Game Ctrl+N

Load Game Ctrl+L
Save Game Ctrl+S
Show Highscores Ctrl+H
Quit Ctrl+Q
As with all menus, options that are not available in a specific game can be left out, and
additional options can be added.

The Quit option should always be available and should always be at the bottom of the
menu. Selecting it terminates the application.

Other applications
Applications that do not fit any of the above categories should have a file menu
consistent with:

Print... Ctrl+P
Quit Ctrl+Q
As with all menus, options that are not available in a specific application can be left

18
 KDE 3 Styleguide

out and additional options can be added.

The Quit option should always be available and should always be at the bottom of the
menu. Selecting it terminates the application.

Menus

Edit
All actions available in the Editmenu manipulate elements of the content
area(nothing else!).

Undo Ctrl+Z
Redo Shift+Ctrl+Z
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Select All
Find... Ctrl+F
Find Next F3
Replace... Ctrl+R
Application specific
entries
Note:

Disable Undoif there is nothing to undo.Disable Redoif there is nothing to redo.Disable

Cutand Copyif nothing is selected.Disable Pasteif nothing was cut or copied
before.Disable Find Nextuntil Findhas been executed for the first time.

Menus

View
All actions available in the Viewmenu manipulate the view of the content area-
they don't manipulate elements of the content area itself!

Actual Size
Fit To Page
Fit To Page Width
Fit To Page Height
Zoom In Ctrl+Plus
Zoom Out Ctrl+Minus
Zoom...
Redisplay
Items relating to
document window info etc.
Application specific
entries

19
 KDE 3 Styleguide

Open for discussion

Should the "Zoom" options be placed at the top of the menu? They are probably used
more often than the "Fit" options.
Menus

Go
Depending on the application, an application can have a web-style Go menuor a
document Go menu. Or it can, of course, have no Go menu at all.

The web-style Go menu

Up
Back
Forward
Home
Application specific
entries
Note:

Disable Backif you're on the first page.Disable Forwardif you're on the last page.
The document Go menu

Previous Page Ctrl+PgUp

Next Page Ctrl+PgDn
Go To Page...
First Page
Last Page
Application specific
entries
Note:

Disable Previous Pageif you're on the first page.Disable Next Pageif you're on the last
page.Disable First Pageand Last Pageif there is only one page.

Menus

Bookmarks
Add Bookmark Ctrl+B
Edit Bookmarks...
Tree of bookmarks
Menus

20
 KDE 3 Styleguide

Tools
Spelling...
Application-specific
entries
Menus

Settings
o Show Menubar
o Show Toolbar
o Show Statusbar
o Show any other hideable elements
Application-specific entries
Configure Key Bindings...
Configure Component...
Configure Appname...
If you allow the user to hide the menubar, it can lead to a confusing situation because
the user can not go back to the menubar to re-enable the menu. Therefore, when the
menubar is hidden, the application should provide a "Show Menubar" option as the
first item in popup menus in the content area (RMB menus). The application should
always make sure the user knows how to re-enable the menu.

Example
A good way to teach the user how to get the menubar back is to pop up a dialog when
the menubar is hidden. This dialog should explain how the menubar can be re-
enabled. Since more experienced users will not be interested in this information, the
dialog should have a checkbox labeled "Don't show this dialog again", which should do
just that.
KDE distinguishes between options and the configuration of an application. See also
the Settingschapter of this style guide.

Options are the top part of the setting menu. Everything above the bottom seperator
can be changed like this. For almost all needs there will not have to be an extra dialog
for the options part. As said in the Settingspart the options are automatically saved
when the application exits.

The configuration of an application can be changed with the "Configure...."menu

option(s). Changes in the configuration of an application are saved when the user
presses "OK"in the configuration dialog and take immediate effect in all application
instances!. (Even if the other instances belong to a different UNIX process.)

Menus

Help
21
 KDE 3 Styleguide

AppNameHandbook... F1
What's This? Shift+F1
Application-specific entries
About Application name...
About KDE...

Toolbar
The classic toolbar is a buttonbar. KDE toolbars can also contain other widgets, e. g.,
labels, line edits, combo boxes, and frames (which can contain everything else!).

The tool bar offers a quick way to invoke actions that are used frequently. Remember:
allactions should be accessible through the menu bar - don't have an action in the
toolbar that isn't also in the menubar!

Implementation Note
The KAction class offers an easy way to ensure consistency between the menubar and
the toolbar.

Buttonbar
It is not necessary to put every action in the buttonbar. However, the following actions
should appear on the buttonbar if your application offers them:

NewOpenSavePrintPrint PreviewUndoRedoCutCopyPasteFindZoomPrevious
Page/BackNext Page/ForwardGo To Page/HomeHelp

The icons designed for the standard buttons should never be used for any other
purpose.

The order given here is the default order. Your application may allow users to
configure the buttonbar as they wish. By default, your application should put the
items in the same order as they appear in the menus.

Your application may also offer additional options in the buttonbar.

The help button should offer context-sensitive help when available. When available,
the help button should be the last item in the toolbar and aligned to the left.(Not to
the right!)

You may choose to have more than one buttonbar. For example, you might offer
drawing tools or a palette on other toolbars. Users may then position them as they
wish (to the side or bottom of the document) or tear them off and resize them to form a
button box. However, be careful not to split toolbars up unnecessarily and arbitrarily.
In particular, don't split the standard menu entry actions across more than one
toolbar.

Insert separators in the same places as in the menus and also between buttons for

22
 KDE 3 Styleguide

actions from different menus.

Other Toolbars
You can put anything you like in a toolbar. The label, line edit and combo box widgets
probably appear most regularly. For example, a label and a line edit are often put
together to make a browser location bar, and a combo box is often used to list available
font sizes.

But remember here as well: don't have actions in the toolbar that do not exist in the
menu bar!

Statusbar
The status bar is for displaying information on the state of the document you are
working on. Typically you will have more than one field for information in the bar. The
first of these inserted will have their size fixed and the last will span the remaining
width of the window.

Content Area
The content area contains everything else to be shown in the main window of your
application - usually this simply means the document view, but if necessary, non-
standard controls for the document may also appear. Your content area may also
employ some of the advanced UI elements such as tree lists.

Tile the widgets for the content area in vertically and horizontally running groups.
There should be no unfilled corners or blank areas. The dominant central part of the
content area should be reserved for the document view. Non-standard controls should
be arranged around this and may be hidden through menu entries and the panner
widget.

The border between the document view and surrounding widgets should be set to zero.
A frame for the document view is optional. The spacing of non-standard control
widgets should be zero in most cases and have a standard margin where a clear
division is required. Raised non-standard controls should use a one pixel width raised
panel frame like the KDE toolbar and menubar widgets.

Implementation Note
The actual size of the standard margin depends on the style used on the desktop. You
can obtain the standard margin by calling the KDialog::marginHint() method.

Dialogs
23
 KDE 3 Styleguide

A dialog is a powerful and convenient way to let users interact with an application. It
provides users with the relevant options for a certain task and allows users to select
the options that suit them.

Broadly speaking, there are two kinds of dialogs:

Simple Dialogs, which ask a question. This includes Yes-No questions and
confirmation requests. Complex Dialogs, which allow users to fine-tune an operation.
Standard Dialogs, which are complex dialogs that KDE provides for frequently-used
operations such as printing and file selection.

All dialogs should have a title that describes what the dialog is about. The title should
also contain the name of the application to which the dialog belongs.

Dialogs should never have menu bars or tool bars inside them.

Dialogs, just as all other types of windows, must conform to the window size
requirements.

ButtonUsageDetails
The action button can be 'ok', 'save' or 'print' or similar.
Mutually
When used together with Cancel the dialog will be closed
<action> exclusive
after pressing this button. When used together with Close
with Apply
the dialog will stay open.
Mutually Pressing this button will close the dialog discarding
Cancel exclusing changes. Changes made earlier with the apply button will
with close be used.
Mutually Pressing this button will close the dialog discarding
Close exclusing changes. Changes made earlier with the apply button will
with cancel be used.
Optional, but Apply changes made in the dialog and keep the dialog open.
Apply never with Using this button only makes sense when the
Close <action>button (see above) is an 'ok' button.
A button labeled "Help" when activated should show a help-
Help Optional
window with help relating to the dialog.
The button sets all the settings in the dialog to the system
Defaults Optional defaults. This is only usefull for dialogs that change
settings of some sort.
This is the opposite of Apply and is therefor only usefull in
conjunction with an apply button. The reset button does not
close the dialog, and resets the values to the ones used in
Reset Optional the system currently. It has the same result as closing the
dialog without saving changes and re-opening it again.
Reset is depricated for most dialogs; only dialogs that are
hard to reach after closing may benefit from a reset button.
Dialogs

24
 KDE 3 Styleguide

Simple Dialogs
Simple Dialogs always ask the user a single simple question. Simple Dialogs can be
categorized as follows:

NotificationsProgress DialogsYes-No questionsConfirmation Requests

The first two categories ask their questions implicitly: "Have you read this message?"
and "Do you want me to stop?".

Notifications
A notification is a message from the application to the user. The user is not offered any
choices. When the user has read the message, he/she can click a button labeled
"OK"which will make the the dialog disappear. Pressing Returnor Escapehas the same
effect.

A notification dialog is modal to the application. The user should take note of the
message before continuing.

Applications usually report error conditions with a notification dialog.

Implementation Note
KMessageBox::information() should be used for notifications ofan informational kind.
KMessageBox::sorry() should be used for error notifications.
It is extremely irritating to users to have notification dialogs popping up for expected
events. Messages like "Printing completed"or "Mail sent"should be avoided. Instead,
the application might show these messages in the statusbar. A notification dialog
should be used only when users need to be notified of an event which they
did not specifically ask for, or were not necessarily expecting.

Applications should not bother the user with unnecessary notifications. If you are not
sure whether a possibly often-recurring notification is useful or simply an unnecessary
burden, you can offer the user an option by means of a checkbox not to show the
message again.

Example

25
 KDE 3 Styleguide

When the user hides the menubar, it is useful to inform him/her how to get it back.
Experienced users may get annoyed by this notification, so there should be a checkbox
to allow them to disable the notification in the future.

For the sake of completeness, you should provide users the option in Preferencesto
"Show all messages again".

Progress Dialogs
Progress dialogs are used to show the progress of an ongoing activity. The user should
be offered an option to abort the activity.

If the application can do anything useful during the activity the progress dialog should
be modeless.

The button on the progress dialog that aborts the activity should be labeled
"Cancel"when aborting the activity is the same as never having started the activity at
all. The button should be labeled "Stop"when aborting the activity leads to a partial
result of some sort.

Example

26
 KDE 3 Styleguide

The following progress dialog might be shown when opening a file across the Internet.
It has a "Cancel"button because when it is pressed, the file is not opened at all.

The following progress dialog might be shown when a document is printed. It has a
"Stop"button: when it is pressed, no further pages will be sent to the printer, but
some of the pages might already have been printed.

Yes-No Questions
The Yes-No question is just that, a question which asks for a Yesor Noanswer. As such
it has a "Yes"button and a "No"button.

Example
An example of a Yes-No question.

Although Yes-No questions have an appealing simplicity, they do have a downside.

While the implications of the Yesanswer are usually very clear, the implications of the
Noanswer are often not clear at all. The question "Do you want to save your
changes?"serves as a good example. Pressing "Yes"will get the changes saved, but
what happens when the user presses the "No"button? Rephrasing the question as an
Either-Or question will help make this more clear: "Do you want to save or discard
your changes?". Now there can be buttons labeled "Save"and "Discard", and the
consequences of both are equally clear.

Yes-No and Either-Or dialogs have another disadvantage: sometimes a user might not
know the correct answer to the question, or might find both options equally
unattractive. In this case, it is helpful to add a third button labeled "Cancel", which
will abort the whole sequence of events.

27
 KDE 3 Styleguide

The Canceloption should always be labeled "Cancel". Even if the user does not know
what the dialog is about, he or she knows that pressing "Cancel"is always a safe
choice.

Example
When an application is being terminated and it has a document open which has been
changed, the application asks whether it should save the changes or not. Since the
user might find both saving or discarding the changes unacceptable, he/she can
choose Cancelto abort the termination of the application.

Confirmation Requests
Confirmation request dialogs ask the user to approve the action that is about to take
place. The user has two choices: approve the operation by pressing the "OK"button or
abort the operation by selecting the "Cancel"button.

Instead of labeling the OKoption "OK", it is better to provide options that are
named in a way that describes what will happen when they are pressed.This
is known as voice-active prompt. Only if no clear verb can be found that describes the
action should the option be labeled "OK".

Again, the Canceloption should always be labeled "Cancel". Even if the user does not
know what the dialog is about, he/she knows that pressing "Cancel"is always a safe
choice.

Example
A dialog that asks for confirmation to delete a file offers a "Delete"button and a
"Cancelbutton. If an "OK"option had been offered, there would be a bigger chance of
the user's selecting this option without actually understanding the consequences.

Dialogs

Complex Dialogs
A complex dialogis a dialog that allows the user to fine-tune an operation. When such
a dialog does not apply so much to a specific operation but rather to one or more

28
 KDE 3 Styleguide

operations in general, we refer to it as a Configuration Dialog.

The actions that are listed in the menubar or toolbar often need additional
parameters. The best way to ask the user for these additional parameters is by means
of a complex dialog. If, for example, the user selects "Open Document" from the "File"
menu, the application will use a complex dialogto ask the user which file should be
opened.

Note that KDE provides a standard "File Selection Dialog" so that you don't need to
write your own for every application you write.

A complex dialogshould preferrably be modeless. This means that while the dialog is
shown the user can still make use of the other functions of the application.

A dialog should be designed such that it does not need to be bigger than 4/5th of the
screen dimensions. So with a screen size of 800x600 pixels (width by height) the dialog
should not exceed 640x480 pixels in any dimension.

KDE assumes a minimum screen size of 800x600 pixels.

Dialogs should be resizable.

Dialogs should preferrably be resizable. If not all information in a dialog can be

presented on the screen due to size constraints, enlarging the dialog should make
more of the information visible.

Example
A dialog that contains a scrollable list of items should assign more space for this list
when the user enlarges the dialog.
Implementation Note
Do not give your widgets fixed widths and positions but use Qt Layouts. That way the
dialog will still be readable with a larger font or when translated into another
language. Texts can be longer in other languages.
All controls on a dialog should be accesible from the keyboard.

Dialog windows should pop up in the center of the application they belong to unless
they interact with the content of the application window, such as a "Replace Dialog".
These dialogs should appear directly next to the application.

Dialogs

Standard Dialogs
KDE provides a number of standard dialogs for tasks that are not limited to a single
application. It is strongly recommended that you use standard dialogs whenever
possible.

When a standard dialog does not address the needs of your application, consider using
it as the base class of your new dialog.

29
 KDE 3 Styleguide

If your application uses a dialog that might prove useful for other applications, please
consider adding it to the KDE library as a standard dialog.

Below are the standard dialogs in KDE that existed at the time of writing:

About Dialog
The About Dialogprovides information about the application: the name of the
author(s), licensing information, and instructions for reporting bugs.

Implementation Note
The KHelpMenu class generates a help menu complete with an About Dialog for you.
Color Selection Dialog
The Color Selection Dialogshould be used whenever the user needs to select a color.

Implementation Note
The Color Selection Dialog is provided by the KColorDialog class. There is also an
easy-to-use KColorButton class. This class provides a colored button which, when
pressed, activates a Color Selection Dialog. The color of the button shows the
currently-selected color.
File Selection Dialog
The File Selection Dialogshould be used whenever the user needs to select a file.

Implementation Note
This is the KFileDialog class.
Font Selection Dialog
The Font Selection Dialogshould be used whenever the user needs to select a font.

Implementation Note
This is the KFontDialog class.
Icon Selection Dialog
The Icon Selection Dialogshould be used whenever the user needs to select an icon for
something. Most applications use predefined icons and do not require the user to select
any icons. The dialog lets the user select a single icon from the icons installed on the
KDE system.

Implementation Note
This is the KIconLoaderDialog class.
Key Configuration Dialog
The Key Configuration Dialogcan be used to let the user change key-bindings or
shortcut-keys within your application.

The default shortcut-key combinations of your application should comply with the
guidelines found in this style guide. Your application may, of course, allow users to
configure different shortcut-keys as they wish.

Implementation Note

30
 KDE 3 Styleguide

The Key Configuration Dialog is provided by the KKeyDialog class. It should be used
in conjunction with the KAccel class which provides your application with shortcut-
key combinations.
Text Edit Dialogs
To support simple text editing functions, standard Goto Line, Searchand Search &
Replacedialogs are available.

Implementation Note
These dialogs are provided by the classes KEdGotoLine, KEdSrch, and KEdReplace,
respectively.

Keys
KDE makes use of Acceleratorkeys and Shortcutkeys.

Accelerators
An acceleratorkey is an alphanumeric key that can be pressed together with a Meta-
key, usually Alt, to select an item which is visible on the screen. If an item has an
accelerator key, this is shown by underlining that character. Note that an accelartor
key is subject to translation: a French menu will have different accelerators from those
of an English menu.

Example
In the following menu, Alt-P is an accelerator for the Pasteitem.
Undo Ctrl+Z
Redo Shift+Ctrl+Z
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Select All Ctrl+A
Find... Ctrl+F
Find Next F3
Replace... Ctrl+R
Application specific
entries

Shortcuts
A shortcutkey is a combination of Ctrl and another key. When pressed together they
start an action from any of the menus. In the menu, the shortcut is printed after each
item so that the user can learn about the shortcuts by using the application.

Within an application a specific shortcut key will always start the same action. If the
action is not possible within a certain context, no action will be taken.

31
 KDE 3 Styleguide

Where possible, applications should try to use the same shortcut keys for the same
actions. To make this easier, this style guide has defined a set of predefined shortcuts.

Please be aware that the user may configure these predefined shortcuts otherwise, on
a system-wide basis.

Shortcut keys are not subject to translation: The shortcut for "Open a document" will
be Ctrl-O in all languages, even if the menu-item doesn't contain an O at all in one
language.

Example
In the following menu, Ctrl-V is a shortcut for the Pasteitem.
Undo Ctrl+Z
Redo Shift+Ctrl+Z
Cut Ctrl+X
Copy Ctrl+C
Paste Ctrl+V
Select All Ctrl+A
Find... Ctrl+F
Find Next F3
Replace... Ctrl+R
Application specific
entries
Implementation Note
Shortcuts and accelerators are often mixed up because Qt and KDE use the
QAcceland KAccelclasses to define SHORTCUTS!!.

No special classes are needed to define accelerators. An accelerator is created

automatically by QLabel. The developer (or translator) can specify which key to use as
accelerator by preceding this character in the label text with an ampersand (&).
Implementation Note
Do not hardcode shortcut keys - use the KStdAcceland its friends for defining them.
That way, your application will stay consistent with other applications if the user
decides to configure other keys as shortcut keys.
Keys

Shortcuts
Default shortcuts
The following keys are the standard shortcut key bindings included in the KDE
distribution. For the sake of consistency, application programmers should
neverredefine these keys in their programs to have functionalities other than those
listed below.

Key
Action Comment
Binding

32
 KDE 3 Styleguide

New Ctrl+N Create a new document

Open Ctrl+O Open a document
Save Ctrl+S Save the current document
Print Ctrl+P Print the current document
Close Ctrl+W Close the current document
Quit Ctrl+Q Quit the application
Undo Ctrl+Z Undo the last operation
Cut Ctrl+X Cut the selected area and store it in the clipboard
Copy Ctrl+C Copy the selected area into the clipboard
Paste Ctrl+V Paste contents of clipboard at mouse/cursor position
Select All Ctrl+A Select everything in the contents area
Find Ctrl+F Find
Find Next F3 Find the next match
Replace Ctrl+R Find and replace matches
Zoom In Ctrl+Plus Zoom in on the document. (magnify)
Zoom Out Ctrl+Minus Zoom out on the document.
Add
Ctrl+B Add a bookmark for the current location
Bookmark
Help F1 Obtain help and documentation for the application.
Scroll down one "Screen", displaying the next page if the
Page Down Space
application normally displays a page at a time.

Shift modifier
Shortcuts should always be either a combination of Ctrl and a key or a single function-
key. We allow one exception: if a function exists which has a logical counter-function,
the shortcut of this counter-function is the same as the shortcut of the original
function pressed together with the Shift key. Using this mechanism, the following
standard shortcuts are defined:

Key
Action Comment
Binding
Shift+Ctrl+
Redo Redo last undone operation
Z
Find
Shift+F3 Find previous match
Previous
Scroll up one "Screen", displaying the previous page if the
Page Up Shift+Space
application normally displays a page at a time.

Reserved combinations
For compatibility with existing UNIX applications and standards, the following keys

33
 KDE 3 Styleguide

are reserved:

Key Binding Comment

Ctrl-A Equivalent to Home(See also Select All)
Ctrl-E Equivalent to End
Ctrl-H Equivalent to Backspace
Ctrl-K Delete till end of line
Ctrl-U Delete from start of line
Note that both Select Alland Move to begin of Linemake use of Ctrl+A. Normally
Ctrl+A is bound to Select All. Users can configure a different shortcut for Select All,
which will make Ctrl+A a shortcut for Move to begin of Linein addition to the
Homekey.

Keys

Cursor Keys
In editors and word-processors, the caretmarks the location at which editing
commands will take effect. Cursor keys allow the user to move the caret, scroll a
graphic window, select list items, etc.

(The caret is also known as the text-cursor. Note that the mouse-pointer is also
referred to as cursor. This is the reason the term caretis used insted of cursorin this
document.)

Movement with Ctrl pressed

Key Movement
additionally
Move left one proportionally larger unit,
Left Move left one unit, e. g., character
e. g., one word
Move right one proportionally larger
Right Move right one unit
unit
Move up one proportionally larger unit,
Up Move up one unit, e. g., line
e. g., to the previous paragraph
Move down one proportionally larger
Down Move down one unit
unit, e. g., to the next paragraph
Move to the left-most position, Move to the top-most position, e. g., to
Home
e. g., to the beginning of a line the beginning of document
Move to the right-most position, Move to the bottom-most position, e. g.,
End
e. g., to the end of a line to the end of document
Move up one logical screen, e. g., to the
Page Up Move up one screen
previous page
Page Move down one logical screen, e. g., to
Move down one screen
Down the next page
Example

34
 KDE 3 Styleguide

For example, take a postscript viewer, which displays the pages of a postscript
document. The program might not always be able to show a complete page on the
screen, so it shows only a part of the page and provides a scrollbar to scroll the page
up and down. To make navigation easier, all the pages are stacked vertically, so that
scrolling one page down enough will get you to the top of page two.

This application might have the following key-bindings:

will scroll the pages so that one or more of the lines visible at the bottom
Page Down
of the screen will appear at the top of the screen after scrolling.
will scroll the pages so that one or more of the lines visible at the top of
Page Up
the screen will appear at the bottom of the screen after scrolling.
Ctrl+Page
will show the next postscript page.
Down
Ctrl+Page
will show the previous postscript page.
Up
(Screenrefers here to the visible area of the document.)
Keys

Selection
Often it is unsuitible to select text areas with the mouse, especially if the user is
currently editing. Text can be selected using the cursor keys with a pressed Shift-key.
Ctrl extends the size of the unit as applied in Cursor Keys.

Selection with Ctrl pressed

Key Selection
additionally
Select left to the beginning of the
Shift+Left Select left one character
word
Shift+Right Select right one character Select right to the end of the word
Select one line up over current
Shift+Up Select to beginning of paragraph
position
Select one line down below
Shift+Down Select to end of paragraph
current position
Shift+Home Select to beginning of line Select to beginning of document
Shift+End Select to end of line Select to end of document
Shift+Page
Select area one screen up Select area one print page up
Up
Shift+Page
Select area one screen down Select area one print page down
Down
Keys

Dialog Navigation
The user should not have to use the mouse to be able to use an application. In fact, it
is often more efficient to navigate a dialog using the keyboard because the user does

35
 KDE 3 Styleguide

not need to switch to the mouse. Furthermore, it is easier to navigate by keyboard

when one's only available pointer device is sluggish (e.g., a touchpad or a touchpoint).

Key Focus Movement

Tab Move to the next field (dialog control)
Shift+Tab Move to the previous field (dialog control)
Keys

Completion
When the user needs to fill in an entry field in the UI, the application is often able to
offer an educated guess after the user has provided only a part of the actual
information.

Example
When a user has typed the first few characters of an e-mail address, the application
can often guess the rest based on prior e-mails sent or an addressbook, etc.

All KDE applications that provide a completion feature should follow the guidelines
given here. The functionality provided by this feature will, of course, be different on a
per application basis.

Open for discussion

No agreement has yet been reached on a single completion mechanism. Two
mechanisms are nominated: auto-completionand end of line completion.

Auto Completion

End of Line Completion

This completion mechanism is only available when the caretis positioned at the end of
the input line. When the user now presses either the Rightarrow key or the Endkey
the application will try to find a completion based on the current contents of the input
line.

If no suitable completion is found a Beepis sounded. The caret is not moved. If a single
suitable completion is found, the completion is inserted in the input line and the caret
is placed at the end of the line. If multiple completions are found, a list of possible
completions is shown.

(The caret is also known as the text-cursor. Note that the mouse-pointer is also
referred to as cursor. This is the reason the term cursoris avoided in this document.)

Implementation Note

36
 KDE 3 Styleguide

This style guide only covers completion for QLineEdit like entry fields. It does not
cover multi-line edit widgets.

Mouse
This chapter of the style guide describes the behaviour of the mouse buttons. First the
behaviour in conjunction with selectable objectsis described. Then the behaviour in
conjunction with buttons and linksis described.

Some special attention is given to the RMB-menu, a popup menu that appears when
the right mouse button is pressed.

The names Left Mouse Buttonand Right Mouse Buttonare based on a mouse for a
right-handed person. A left-handed person can configure his mouse to have the right
and left buttons reversed. In this case, the Left Mouse Buttonwill be positioned at the
right-side of the mouse and the Right Mouse Buttonwill be positioned at the left-side
of the mouse.

Clicking on Objects
The following describes standard behaviour when clicking on an objectin the content
area:

Left Mouse Button

Single Click (SC) Action
Mark the object (double-click mode)
OR
SC Mark the object and execute default action on the object
(single-click mode)
In both cases other objects will be unmarked.
Mark all objects from the first selected object to the current
Shift + SC
object
Ctrl + SC Mark the object (leave other marked objects marked)
mouse move + SC Mark the object and move it (unmark other marked objects)
mouse Mark all objects from the first selected object to the current
move + Shift + SC object and move them
mouse Mark the object (leave other marked objects marked) and move
move + Ctrl + SC them
Double Click (DC) Action
Mark the object and execute default action on the object
DC (double-click mode).
Other objects will be unmarked.
Mark all objects from the first selected object to the current
Shift + DC object and execute the default action on all marked objects
(double-click mode).

37
 KDE 3 Styleguide

Mark the object (leaving other marked objects marked) and

Ctrl + DC execute the default action on all marked objects (double-click
mode).
KDE is designed to make use of either single-clicks or double-clicks, but the default is
single-click mode. The reason for this is that double-clicks are hard to learn for new
users and can cause RSI (Repetitive Strain Injury). To accommodate users who are
already used to double-clicking and who don't want to change, as well as to
accommodate users who work on a daily basis with systems that require double-clicks,
KDE will allow the user switch to double-click mode on a system-wide basis.
Otherwise, a double-click is treated as one single-click.

To be compliant with this styleguide, an application should support both single-click

and double-click.

Right Mouse Button

Click Action
If the clicked object is marked, it does not change any of the marks. If the
clicked object is not marked, the object is marked and any other objects are
single
unmarked. Then a popup menu (RMB-menu) appears where the user has
click
clicked. The RMB-menu contains the most important actions available for
the marked object(s).
double
-
click
The action that you get by clicking on an item with the Left Mouse Button (default
action) should appear in the RMB-menu as the first option.

Clicking on Buttons & Links

The standard behaviour for click on a buttonor a linkis described below. Note: a link
was originally an object, but because there was a defacto standard stipulating that a
single-click on a link leads to an action, it was decided to treat links like buttons.

Left mouse button

Click Action
single click Execute an action (e. g. Cut, Copy, follow a link, etc.)
double click -

Right mouse button

Click Action
single Opens a popup menu (RMB-menu) with the most important actions
click available for the button/link (e. g. Move, Properties, etc.)

38
 KDE 3 Styleguide

double
-
click

RMB Menu
A RMB-menu (right mouse button menu) appears when the right mouse button is
pressed, not when it is released. The user can operate the RMB in two ways:

The user can directly select an option and release the right mouse button to activate
the option. The user can release the right mouse button directly (single click), select an
option and click again (either with the right or the left mouse button) to activate the
option.

Mouse

Selection
Certain content areas represent their content in terms of textual objects like plain
text, formatted text, text with embedded objects etc. Those areas should provide the
following modes of text selection.

Left Mouse Button

Single Click
Action
(SC)
All selections are unmarked.
SC
The caret is placed onto the click position if applicable.
SC + drag Select from the pointer, extending selection by letters.
Shift + SC Extend the end of the existing selection up to the pointer position.1
Double
Action
Click (DC)
Select the targeted word.2
DC
Existing selections will be unmarked.
Select the targeted word and continue to select by word as the pointer
DC + drag moves, selecting to the beginning and end of any word the pointer
moves onto.
Extend the end of the existing selection up to the cursor position, then
extending the beginning of the selection to the beginning of the first
Shift + DC word covered by the selection, and the end of the selection to the end of
the last word.1
Triple Click
Action
(TC)
Select the targeted row.3, 4
TC
Existing selections will be unmarked.

39
 KDE 3 Styleguide

Select the targeted row and continue to select by row as the pointer
TC + drag
moves, selecting to (inclusively) any line the pointer is dragged over.
Extend the end of the existing selection up to the cursor position, then
extending the beginning of the selection to the beginning of the first
Shift + TC
row covered by the selection, and the end of the selection to the end of
the last row.1
1

Using the shift modifier when no selection is existing behaves as if it were not
pressed in the first place.
2
The definition of word is not consistent and may need to be standardized
elsewhere, but not here. Especially which characters to consider as a word
boundaries are not subject to this style guide.
3
A row refers to a displayed row of text, not to the underlying row up to the next
line-break. This is not selection by paragraph.
4
When selecting by row, the row size changes if the window is resized. In this
case, keep the current text selected, even though it may no longer be a whole row.
If the selection by row is further expanded by the user in a row-by-row manner,
expand the selection to encompass every row it is a part of.

Right Mouse Button

The RMB is not intended to be used for text selection.

Applicability
Application types which this style guide is applicable to are text editors, word
processors, visual user agents (web browsers), and any other application type that
features displaying textual content.

Drag and Drop

Drag & Drop allows the user to dragan object across the desktop and to dropit onto
some other object. The user starts a drag by clicking on an object with the left mouse
button (LMB) and, while keeping the mouse button pressed, moving the mouse. An
iconrepresenting the dragged object will now follow the mouse pointer. When the user
releases the mouse button, the object is dropped.

Drag & Drop can be an efficient way to select an interaction between two objects if
both objects are visible on the desktop. The Drag & Drop action itself selects the two
objects. After the drop, a popup menu should be shown which allows the user to select
the desired action.

The following two sections describe the Dragand the Dropin more detail.

40
 KDE 3 Styleguide

The Drag
To prevent unintented drags in the case where the user wants to click on the object
but accidently moves the mouse a little, drags should not start immediately. Only
after the mouse has moved a certain number of pixels should the drag actually start. If
the user releases the mouse button before the drag has actually started, the action
should be considered a single mouse click (SC). Note that the origin of the drag is
where the mouse button was pressed. The origin is NOTwhere the mouse pointer is
when the drag starts! (a small but subtle difference)

Example
The following picture illustrates a Drag & Drop operation. The user presses the LMB
at point A and then moves the mouse along the black line, via point B, to point to C,
where the user releases the LMB.
The actual drag will start at point B but it is the object at point A that is being
dragged.

Implementation Note

41
 KDE 3 Styleguide

The following example code leads to the desired behaviour:

void myWidget::mousePressEvent( QMouseEvent *e )

{
// Only interested in LMB
if( !(e->state() & LeftButton)) return;
// Store the position of the mouse press.
mPos = e->pos();
}

void myWidget::mouseMoveEvent( QMouseEvent *e )

{
// Only interested in LMB
if( !(e->state() & LeftButton)) return;

// Check whether the user has moved far enough.

int delay = QApplication::startDragDistance();
if ( (mPos - e.pos()).manhattanLength() > delay )
{
// Find color at the position of the mouse press (mPos)
QColor myColor = colorAtPos(mPos);
// Create a drag-object for myColor
KColorDrag *d = KColorDrag::makeDrag( myColor, this);
// Start the drag
d->dragCopy();
}
}
If, while dragging, the mouse pointer is above an object on which a drop is possible,
this object should change its visual appearance to indicate that a drop would mean
dropping into this very object. If a drop is NOT possible, the mouse-pointer should
change into a stop-sign.

Implementation Note
In a dragEnterEvent method one can indicate whether a drop is possible or not. Qt
takes care of changing the mouse pointer accordingly. See the Drag & Drop section in
the Qt documentation for more details.

void myOtherWidget::dragEnterEvent( QDragEnterEvent *event)

{
if (!KColorDrag::canDecode( event))
{
event->accept(false); // We don't support this type
return;
}
highlight(); // Change visual appearance to indicate we accept drop.
event->accept( true ); // Tell Qt we are willing to accept the drop.
}
Pressing ESCduring the drag cancels the Drag & Drop operation.

The Drop
A drop causes a popup menu to appear that offers possible actions. Typical actions are:
Move, Copyand Link.

The popup menu should always contain Cancelas the last option.

There should also be a popup menu if there is only one action (other than Cancel)

42
 KDE 3 Styleguide

possible. Actions that aren't possible should not appear in the menu.

If, while dragging, a drop is not possible at the location of the mouse pointer and/or
there are no actions possible at all, the mouse cursor should change into a stop-sign.
Doing a drop at such a location effectively cancels the whole Drag & Drop operation.

Experienced users may speed this process up a bit by keeping a modifier key down
when the dragged object is dropped. If any of the following modifier keys is pressed
during the drop, no popup menu will appear but the related action will be selected
immediately.

Shift - Move Ctrl - Copy Shift+Ctrl - Link

If, in this case, the selected action is not possible at the location of the mouse-pointer,
the mouse pointer should change into a stop-sign. A drop at such location effectively
cancels the whole Drag & Drop operation.

43