Calligra/Guidelines

Note

This is work in progress. You can contribute to this page or request updates.

Draft

This document is unfinished and in need of refinement and approval.

Introduction

This document attempts to supercede and comprise all previous documents written on the KOffice gui guidelines. It aims to be compatible with and to extend the KDE Human Interaction Guidelines (which do not exist yet, but are being drafted at http://wiki.openusability.org/guidelines).

In this document the words must, may, and should are to be in http://tools.ietf.org/html/rfc2119. In particular, where the word “must” is used, no KOffice application can be considered complete with this feature.

Interaction Design

Mouse Handling

Left Button

The left mouse button is the most frequently used button of the mouse. There are two types of clicks: single and double click.

A single click should be on the canvas, so within the editing area, should be associated with the select action.

Right Button

The right button is traditionally associated with a context menu.

Mouse Wheel

Strg - Wheel -> Zoom

Common GUI Elements

Toolbar

KOffice applications use ordinary toolbars as sparingly as possible.

Menu Bar

The menu bar contains the common file, edit, view, tools, settings and help menu. In between view and tools application specific menu entries can be placed. Menu's must not be nested more than one sub-menu deep.

Status Bar

The statusbar contains the following obligatory elements:

• help area
• zoom area
• progress reporting area

The following areas are application-specific:

• current page indication
• cursor indication
• further state indications

Dockers

Dockers show, manipulate or show and manipulate the contents of the document or part of the document. All KOffice applications show by default the Tool Options Docker that contains widgets needed for setting the state of the current tool. All KOffice applications show by default the Shape Options Docker that contains widgets needed for setting the state of the current shape. All KOffice applications must show a document structure docker by default. (The KOffice gui utils library contains a docker that can show the document structure as thumbnails, flat list or tree view. This should be the first choice for implemented the document structure view docker). Other dockers may be shown or hidden according to the purpose of the application.

Collection dockers

Collection dockers are dockers that offer the user a selection from a collection of items. Examples are layers and styles dockers. Collection dockers have tool buttons for adding, modifying and removing entries under the listview. The order of these buttons is:

• new
• modify
• spacer
• remove

The buttons need to have the flat style: property AutoRaise must be true

Document Area

The document area shows the document. When the zoom level is small enough that the document does not cover the document area completely, a dark (XXX: palette) background is shown. This is easily implemented using the flake canvascontroller class.

Color Scheme

Widgets

All widgets must follow the common KDE color scheme. No KOffice application may hard-code colors for widgets.

The KOffice canvascontroller background, must be darker than the document.

Interaction element colors

Tools

Whenever you have a tool that draws something it should use colors of the oxygen color palette. Here are some colors already in use with their usecase:

//TODO create table Selection with cursor; Selected text;

Default window layout

When a new user starts up KOffice his opinion will be very much depend on the first impression. So we should pay a lot of attention to the default layout of the GUI. General paradigms are simplicity and tidiness. The user should be able to start working without rearranging dockers or select tools.

Zoom level and zoom widget

There are several possibilities how to integrate zoom widgets in the GUI. There is the toolbar solution with a drop-down menu, the statusbar solution and you can also choose the zoom tool. As most of the KOffice apps use the toolbar solution all apps should do so. The other solutions should stay as configurable options.

Startup zoom level is something application specific but be careful what you choose. Here is a table on what to choose:

Page applications ( KWord, Kivio )-ZoomToWidth; KPresenter-ZoomToFit; Canvas(Krita, Karbon)-???

Toolbar

The default tool bar should look like this in every app ( written in groups ):

New - Open - Save |

Undo - Redo - Cut - Copy - Paste |

Add shape - Delete shape (??) |

Zoom tool - Zoom drop down

Rulers

The rulers aren't used so much so they should be disabled by default as they also use a lot of screen space.

Page shadow

The page shadow should be acitvated by default as the default oxygen color ( some grey ) is not to different from the white color of a page and it is hard to see where the page actually begins.

Dockers

Without an official decision it is common at the moment that dockers appear on the right side of the main window so all apps should do so. A problem related to dockers during startup is that there are too many dockers open so that the mainwindow grows over the screen's size. Dockers that should be open at startup are: Shape Selector, Tool Selector, and Default Tool Options. All on the right side with the order from top to bottom: Tool Selector, Default Tool Options, Shape Selector.

Tools

An application should start with its most commonly used tool activated. For example KWord should start with the text tool activated and set to the main text frame. Some apps like KPresenter don't have a dedicated tool to use at startup so they should choose the default tool.

The same applies to the activation of tools when a shape is inserted, the default shape editing tool should be actived automatically.

Dockers

With KOffice 2 most of the functionality that was previously placed in the toolbar or in a menu moved to one of the various dockers. These are either independent widgets available for all applications or the option widget of a tool. Often the general functionality is similar with just a different context.

Example: The text tool's option widget provides predefined styles, the gradient docker provides predefined gradients, the color docker might provide predefined colors that the user can choose as a template for fast editing. All the dockers name their templates differently and have different approaches GUI wise.

General

A dock widget is a very flexible widget and can be arrange inside the main window and undocked etc. This is nice but the normal user should not be forced to do so if he doesn't want to. So the dockers have to fit inside the main window at startup and should not clutter it.

As some displays don't provide that much width the dockers width should be limited. If not there is a risk that the editing area shrinks to much when using certain dock widgets. To limit the dockers width there shouldn't be more than two tabs at the highest level. If there are too many options you could create an options dialog that provides the very advanced stuff. Also try to not exceed in height as there are most likely more than just one docker open at one time.

Default tab

The tab page which is open by default when a docker is created should be tidy and clear. It should be named correctly with a name that describes the topic it provides options for. Try to not put every single option on the first tab but the option that are used most frequently and often. If you have further options consider to create an "Advanced" tab page.

Predefined templates tab

When the docker provides predefined templates for fast editing they should be available in a second tab, directly after the standart tab. This tab should be names "Templates".

To add or remove a template there should be buttons with a plus and a minus sign on the templates tab aligned to bottom. A click on this button takes the current configuration and puts it in a template.