Notes2 Specification

From Apache OpenOffice Wiki
Jump to: navigation, search
Please do not edit this page! This specification won't change because the described functionality has been integrated. Your feedback and comments are welcomed, please visit the Notes2 main page for contact information.

Improved notes

Specification Status
Author Mathias Bauer
Last Change
Status Standard Help



Reference Document Check Location (URL)
Specification Process Entry Check [passed/failed] n/a
Product Requirement, RFE, Issue ID (required) [available]
Product Concept Document [not available]
Test case specification (required) [available/not available] <PLEASE ENTER LOCATION HERE>
IDL Specification [available/not available]
Software Specification Rules n/a n/a
Other, e.g. references to related specs


Role Name E-Mail Address
Developer Max Odendahl <>
Quality Assurance Éric Savary <>
Documentation Uwe Fischer <>
User Experience Christoph Noack <>

Acronyms and Abbreviations

Acronym / Abbreviation Definition
<WYSIWYG> <What You See Is What You Get>

Detailed Specification

General Aspects

Notes can be attached to any text in the document except text in drawing objects. For each note a reference point is added to the text that is stored as a character, very much the same like text fields. No content is displayed at that text position, notes will be shown as small windows in a side pane of the text. A graphical element will serve as an anchor that points to the text position of the note and a connector will connect the anchor with the corresponding text of the note.

Writer prototype001.png

Visibility of notes

In general notes will be visible in the print layout or web layout view of a text document but not in the print preview. The visibility can be switch on and off using the "View-Notes" menu entry or in "Tools - Options - Writer - View - Display", default is "On".

The Notes side pane

The Notes side pane is an area that is added to the right side of each displayed document page. It's height is the same as the page height and the witdh of it is 2700 Twips.

It is considered to be an integral part of the document view. Thus it adds to the width to the document view so that the special zoom modes "Optimal", "Page width" or "Entire page" will need to consider it. As Writer centers its view it will center the combined width of document content and notes. In the Web Layout the side pane is always visible and so the space usable for text is reduced by the side pane width.

Further defitions:

  • The color of the side pane is used to reduce the brightness contrast of notes windows and the (generally) dark writer background.
    • Color: Decimal R230, G230, B230, A255 (Hex: e6e6e6ff)
  • The line between page and side pane area marks the end of the physical page and delimits the notes windows (similar to page margin indication):
    • Width: 2 screen pixel
    • Color: Decimal R200, G200, B200, A255 (Hex: c8c8c8ff)
Notes2 SidePane DesignAndPosition NormalHeight.png

The note window

The window of a note displays the text of the note and its meta data. The meta data consists of the name of its author (taken from the user data in Tools - Options - User Data) and the date of creation. The configured locale setting (Tools - Options - Language Settings - Languages - Locale Settings) will be used to select the date format.

Notes2 note.png A single note has a minimum height that allows to show date, author and at least three lines of text in the default notes font size (10 pt). If the note contains more text than the available number of lines can cover, the size of the note will be expanded on demand. The maximum possible size of a single note window is given by the page height (minus a border of some pixels). If the text is still too big to fit into the notes window size, scroll bars will be added at the right side of the note window. If more than one note window is present, space conflicts can arise that will resolved as described below. Notes2 srollednote.png

The background of the note window in view mode shows a color gradient defined by a lighter starting color and a darker end color. In editing mode the background is a bulk color (the darker color of the two gradient colors). A third color is used for the text of the meta data. The same color is used for the "anchor" of the note at the text position that it refers and the connecting line between the anchor and the note window (see below). All three colors make up a color triple that belongs together and is part of a set of 9 triples, each of them representing one author.

Notes2 2007-09-04 ColorsForTheNotes ForWiki.png

It is not possible to configure the color of individual notes, colors represent authors, not notes. The colors have been designed very carefully regarding the following criteria:

  • unobtrusive but appealing colors that (as a set) go together well
  • how distinguishable are the colors for people with visual impairments (inabilities or weaknesses in seeing some particular colors)
  • how readable is text written on a background using one of these colors
  • how do the note connectors line and borders look in contrast to the notes window itself

So consequently the colors can't be changed by users.

The note window also contains a button in the lower right corner. If the button is clicked, a menu pops up that presents some notes related functions. The same functions are available from the context menu that the user gets by right mouse click on the text area of the note window. It also contains some functions for text editing. All these functions are disabled when the document is not editable.

Menu when using the button inside the note window (the exemplary name "Christoph Noack" is replaced by the name of the corresponding author):


Contextmenu for the note window (the exemplary name "Christoph Noack" is replaced by the name of the corresponding author):


Notes connector and anchor

At the text position where a note has been inserted a graphical element representing the note anchor is displayed. It is a triangle whose upper angle points to the anchor position. The anchor and the corresponding note window are connected with a line. The color of the line and the anchor are the "accent color" of the color triples shown above. If the note window has the focus or the mouse is hovered over the note window, the line is solid, otherwise dotted, the line width is 15 Twips (1px at 100% zoom factor).

Arrangement of notes on the notes side pane

A note window places its text content at nearly the same vertical position as the text position of the anchor. The window by default has a size as explained above. If the notes side pane contains more than one note window is is possible that the necessary space to display all notes with the desired position and size is not available. Then sizes and positions of notes will be adjusted in a way that the used space is as evenly distributed amongst them as possible. This happens in the following way:

  • if the total height of the notes side pane is big enough to show all notes with their desired height, only positions of note windows are changed by shifting them upwards and downwards until none of them overlap any more
  • if all space in the notes side pane is occupied, all note windows are shrinked to the absolute minimum that allows to show all text in them (empty notes will be shrinked to one line of text)
  • if there is still not enough space, all windows will be shrinked to two lines of text. Windows containing more text will get scroll bars.
  • if there is still not enough space,, some note windows will not be displayed and scroll buttons will be shown at the top and bottom of the notes side pane of the page. The scroll buttons allow to shift the position of all notes up and down, thus showing the prior invisible ones and moving out others instead (refer to Scroll Buttons).
Note Side Pane scroll buttons (simplified)

Rearrangements of note windows can happen when notes are inserted or deleted, when the position of a notes anchor relative to its page changes or after a user has edited a note and its height has changed. No rearrangement happens if the view of the document changes (scrolling, zooming, resizing of the document window in print layout). Changing the page size (changing page layout or even entering text in web layout) also can cause the rearrangement of notes.

Creating or editing notes

If a Note is created, a notes anchor is inserted at the current cursor position. A new note window is shown in the notes side pane. This window will show the current date and the name of the current user (taken from the user data in the configuration) and it will reserve space for two lines of text in the default font size (10Pt). A connector between anchor and note will be shown with a solid line as the note window will automatically get the focus. If necessary, the view is moved so that the note is visible.

If the user leaves the note without entering text by pressing "ESC" the note is removed. Selecting "Undo" will bring the empty note back. A freshly created empty note is not removed if the user leaves it by clicking somewhere else.

Users can enter text into the note window and they can assign attributes to the text. While a note window has the focus, the formatting tool bar for text remains active. All character and paragraph attributes that can be applied to text in drawing objects (shapes) can also be applied to the text in notes. Hyperlinks are supported also. Spell Checking and auto correction are available.

If more text is entered than fits into the window the window will be expanded until its lower border reaches the next note window. If more text is entered, scroll bars are shown. While a note is edited no further rearrangements of notes in the notes side pane will happen but after leaving the note window all notes belonging to the same page may be reordered and resized as described above.

Undo gets a special treatment. While a user is editing a note an undo step usually comprises entering a complete word, changing an attribute etc. Once the note window loses the focus all changes made in the editing "session" are summarized into a single undo step that can be carried out to bring the document back to the point before the last editing session of the notes was started. While editing the note the complete past Undo hierarchy of the document is accessible.

keyboard navigation

CTRL - ALT - N (cursor inside the document) create a new note at current position

CTRL - ALT - N (cursor inside the note) jump out of the note

CTRL - ALT - Page Up/Down (cursor inside the document) go to to previous/next Note Anchor

CTRL - ALT - Page Up/Down (cursor inside a note) go to to previous/next Note Window

ESC (cursor inside a note) jump back into the document, cursor is placed after the notes anchor position to continue writing easily. If the note is empty, it is deleted.

Names for Access/Configuration via UNO

According to the request in issue 87951, the functions of the Note Windows have to be named properly for the availability in the menu "Tools -> Customize -> Keyboard -> Function" (which in fact are uno functions). The functions of Note Windows refer to both the drop-down menu in the Window and the context menu for the Note User Data (text).

uno API Identifier User Interface Label for UNO User Interface Item in Note Window (for reference only) Comment
.uno:DeleteNote Delete Note Delete Note none
.uno:DeleteAllNotes Delete All Notes Delete All Notes none
.uno:DeleteAuthor Delete All Notes by This Author Delete All Notes by <AuthorName> The string <AuthorName> is replaced with the author's name of the Note, so the UI string for author "Foo Bar" would be "Delete All Notes by Foo Bar". The name of the author is not known without a Note, e.g. during the keyboard customization. Therefore the replacement "This Author" is used for the uno function.

Focus Visualization (Shadow)

This section covers the shadow behavior for focus visualization. It is based on the description at Visualization of Focus and has been adapted to technical limitations.

  • The following descriptions of the shadows consider the Note Window to be displayed in the document at 100% zoom level. Similar to the Notes Window itself, the shadow is dependent on the zoom level inside the document.
  • Color dark gradient: base color R83 G83 B83 (Hex: 535353), from alpha 255 to 0
  • Color bright gradient: base color R180 G180 B180 (Hex: b4b4b4), from alpha 255 to 0
  • State "Normal" of the Note Window:
    • If the Note Window is neither "Viewed" nor "Edited" (please see below), then the state of the Note Window is "Normal."
    • Element N1: width same as Note Window, height 2px, color linear bright gradient
  • State "View" of the Note Window:
    • If the Anchor of a Note is hovered by a) the text cursor in the Writer document window or b) hovered by the mouse pointer, then the state of the Note Window is "Viewed".
    • Element V1: width same as Note Window, height 4px, color linear bright gradient
  • State "Edit" of the Note Window
    • If the text cursor is placed inside the Note Window, then the state of the Note Window is "Edit".
    • Element E1: width same as Note Window, height 4px, color dark gradient linear
Notes2 FocusVisualization Shadow Composition OOo300.png

Help | User Interface Element Templates | Example Spec


Old documents containing notes will works flawlessly with the new user interface.


No configuration means are needed to use the new functionality.

Help | Configuration Table Template

File Format

A single file format change is needed that will be part of ODF 1.2. The functionality using this (assign notes to a selection of text) will be implemented in the next version of this feature.

Help | File Format Table Template
Personal tools