The KDE Style Guide

Contents

• Introduction
• General guidelines
• Guidelines for menus
• Guidelines for dialogs
• Guidelines for new controls
• Guidelines for coding
• References
• Changes

In order to produce a consistent desktop in which the user can easily transfer skills and knowledge learned from one application to another it is necessary that those applications maintain a standard look and feel. The look and feel includes the appearance of the controls used in the GUI, the way those controls are applied and the terminology used by the application.

This document cannot enforce a good GUI design, but if you follow the guidelines set out here then hopefully you should avoid making any gross mistakes. The only way to ensure your GUI design is actually a good one is for your intended users to try it, fortunately this is easy in an open development model such as ours. It is essential that developers are aware of how the user perceives their application and that they are responsive to user feedback.

• Always try to be consistent
  This includes being consistent within your application, and being consistent with other applications.
• All functions of an application should be reachable using the keyboard.
• Always let the user know whats going on.
• Every application should provide online help.
• Remember that the user interface is for the convenience of the user not the programmer.
• Never use a control for anything except it's intended purpose.
  For example check boxes are interactive controls and should not be used as pretty labels. Users have a right to expect controls to operate in a consistent way.
• Don't overload windows with functionality or information that is irrelevant to the task in hand.
• If you use a standard term such as 'Cancel' then you must use the standard semantics.
• Test your code on toy problems if you have to, but test your user interface on real problems.
• Don't keep secrets from the user.
  This includes making sure the user can get all information relevant to the task, and also things such as keyboard accelerators which should be documented.
• Always let the user see at a glance what is expected of them.
  Making sure that command functions are separated from data entry areas, and grouping and labeling widgets correctly can help ensure this.
• Group things that perform similar operations together, not things which are implemented in similar ways.
  Think user interface.
• Remember that users scan from top to bottom and from left to right.
  Note also that they can scan faster vertically, so favor vertical lists over horizontal ones.
• Prevent unnecessary errors by disabling functions that cannot be performed at a given time.
• Organise the information your give the user, the more structured it is the faster they can understand and navigate it.

Every application should have a menubar containing at least two popup menus one of which must be the Help menu. The other menu is normally labelled 'File' though developers are free to use another name that is more appropriate to their application.

The File menu

The Help menu

The Help menu provides access to the applications' online help. It also provides a point of contact (eg. an email address) for the maintainer and the application version number via the About entry. A minimal Help looks like this:

Applications are free to add other menu items and separators between the Contents item and the separator. The actions that should be performed in response to each of these menu items is as follows:
Contents - Open the application help contents page with kdehelp. This should have the accelerator key 'C'.
About... - Display a dialog displaying the application name, version number and author(s). This should have the accelerator key 'A'. This dialog should also display information about application license. A typical 'About' dialog might look like this:

Note that occasionally dialogs can implemented as separate binaries, this does not change the fact that as far as the user is concerned the window is a dialog and should act as such. An example of such a dialog is klogout.

• The default action for a dialog should always be the least destructive, this is normally 'Cancel'.
• Tabbed dialogs are useful, but can be very confusing to users.
  You should never use more than two rows of tabs and should think carefully about your design if you need more than one, you would probably be better off breaking your dialog into two or more smaller ones.
• Don't offer the user a choice if they don't have one.
• Messages, especially error messages, should be written in terms of what the user is doing, not the program.
• Group related information to indicate the relationship.
• Never duplicate command buttons on a dialog.
• Avoid modal dialogs, disable functions of the application instead.

This section refers to controls rather than widgets because it includes cases where the look and feel of a control is changed without creating a new widget. An example of this situation is the addition of a popup menu to push button which dramatically changes the behaviour, but can be implemented without subclassing QButton.

• If you change a controls behaviour you should reflect this change in it's appearance.
  For example a button that displays a menu should indicate this with an arrow (see KPanel for an example).
• Don't invent new controls if there is an existing one that does the job.
  You should not make users learn another control unless it offers significant benefits for your application.
• When writing new controls try to make them reasonably general.
  If you write controls that other people can use then not only are you helping the KDE project towards it's goals, but you are also helping your users by allowing them to transfer their knowledge of the control between applications.

• Every literal string that the user will see should be made available for translation.
  This is very easy to achieve, for example to allow translation of a label that says 'Hello' in English you simply call

     klocale->translate("Hello");

  Instead of using the string directly. You do not need to provide any translations other than your default, they can be produced by others.
• Use geometry management wherever possible
  Using geometry management (eg. the QLayout classes) allows the layout of widgets in a window to be dynamically determined as the user resizes the window. When used well geometry management allows for excellent widget layouts which use the available space intelligently. It is especially important to use geometry management for KDE applications because when your application is translated to another language your text messages will have a different size.
• KDE applications should be configured using a GUI.
  All configuration options should be available from within a GUI, it should not be necessary for users to edit your configuration with a text editor. Note that it should still be possible for users to edit your configuration files if they need/wish to, this is ensured if you use the KConfig class.
• Use kdoc doc-comments
  You should document any code that you think could be usefully reused in another application (or placed in a library). The best way to do this is to use kdoc which generates well formatted class documentation and automatically hyperlinks it for you. You must follow the javadoc doc-comment style for any comments which you intend to process with kdoc.
• Be aware that people may need to subclass your widgets
  For example don't make critical functions that people may want to override private and ensure your destructor is virtual.

This section lists some useful documents on user interface design which influenced the contents of this style guide, and a few related standards.

• KDE File System Standard
  This describes the KDE standard directory organisation.
• KDE Key bindings Standard
  This describes the KDE standard key bindings.
• The User Interface Hall of Shame
  This site contains lots of examples of mistakes in existing user interfaces in which many common themes recur.
• Qt Documentation
  As well as being the essential source of information about the Qt classes, the documentation also has some hints about good user interface design.
• Designing Object-Oriented User Interfaces
  Dave Collins 1995. ISBN 0-8053-5350-X
  This is an excellent book for anyone interested in modern object oriented user interfaces.
• OSF/Motif Style Guide
  This is now quite old and mentions nothing of toolbars, wizards, tree widgets, tab dialogs... It is however a good guide to using the controls properly.

• 0.1 First draft
• 0.1.1 Minor upgrades ;-)
• 0.1.2 Added some stuff on menus including some of Martin's help menu plan and various other minor fixes.
• 0.2 Added some images for standard menus/dialogs.
• 0.2.1 Fixed link to the GUI hall of shame.