Notes2 Specification

Improved notes

Specification Status
Author	Mathias Bauer
Last Change
Status	Preliminary Help

Abstract

<START TYPING HERE>

References

Reference Document	Check	Location (URL)
Specification Process Entry Check	[passed/failed]	n/a
Product Requirement, RFE, Issue ID (required)	[available]	http://www.openoffice.org/issues/show_bug.cgi?id=6193
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		http://wiki.services.openoffice.org/wiki/Notes2

Contacts

Role	Name	E-Mail Address
Developer	Max Odendahl	<mod@openoffice.org>
Quality Assurance	Éric Savary	<es@openoffice.org>
Documentation	Uwe Fischer	<ufi@openoffice.org>
User Experience	Christoph Noack	<christophnoack@openoffice.org>

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. 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.

Visibility of notes

In general notes will be visible in the print layout view of a text document but not in the print preview or the web layout view. The visibility can be switch on and off in "Tools - Options - Writer - View - Display", default is "On". TBD: the visibility of own notes or the notes of a particular author can be switched.

The Notes side pane

The Notes side pane is an area that is added to left or right side of the each displayed document page. It's height is the same as the page height and the witdh is TBD at a zoom level of 100%. 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. For left-to-right text (GUI language), the side pane is located at the right side of the writer document. For right-to-left text (GUI language), the side pane is located at the left side of the writer document. 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: 1 screen pixel Color: Decimal R200, G200, B200, A255 (Hex: c8c8c8ff) At the moment (OOo 2.2), is colored black and the shadow of the page seems not be dependent on the zoom level. Therefore... Width: 3 screen pixels Delta with reference to the document page: horizontal 3 pixels, vertical 3 screen pixels Dark Color (beginning at page): Decimal R83, G83, B83, A255 (Hex: 535353ff) Bright Color (ending at writer background, same color as writer background in current OOo): R150, G150, B150, A255 (Hex: 969696ff) Please note that the shadow may be deactivated when the user edits the notes user data inside the notes windows.

The note window

The window of a note displays the text of the note, the name of its author and the date of creation.

TBD: create new screenshots without the button.

A single note has a minimum height that allows to show date, author and at least two lines of text in the default notes font size. If the note contains more text than two lines can cover, the height of the note can be expanded. If no other notes have to be considered (see below), the size of the note can be expanded until it reaches the height of the notes side pane. If the text is still too big, scroll bars will be added to the note window.

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). All used colors are chosen from a fixed set of colors. They are related to the color of the note anchor and connector.

TBD: mouse over effect

TBD: create new picture showing the colors

TBD: future task to assign colors to authors

The two colors of the note window and the color of its connector and anchor are chosen from a set of 9 different color triples, each of them is assigned to another author. It is not possible to set the color of individual notes, colors represent authors. 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.

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 the line is solid, otherwise dotted, the line width is 1px.

TBD: mouse over

Arrangement of notes on the notes side pane

The vertical position of a note places its content at nearly the same height as the text position of the anchor. If the necessary space to display a note is not available, the size and position of the note and also those of other notes will be adjusted in a way that the used space is as evenly distributed amongst them as possible. If the size of a notes window is too small to show the complete notes text scroll bars will be shown.

If the height of the side pane is not enough to display all notes even with the minimum height, some notes will not be displayed and scroll buttons will be shown at the top and bottom of the side pane of the page. The scroll buttons allow to shift the position of all notes up and down, thus leaving space for the prior invisible ones and moving out others instead. See the pictures below for further reference.

Working with Notes

Creating or Editing Notes

Please note that the subsequent text refers to the number of text lines representing the Notes User Data in default notes font size.

• Creation of Notes
  • If a Note is created, the Notes Functionality must insert the newly created Note Window at a position given by the rules of “Distribution of Notes Windows in the Side Pane”.

    Example: refer to the graphic below, Example D, Step 1.2

  • If a Note is created, the Notes Functionality must sets the height of the newly created Note Window to a value that makes it possible to insert three lines of Notes User Data without resizing the Notes Window. (newly created Note Window: does not contain any Note User Data)

    Rationale: If there is few space available (e.g. for one line of text), some users “fear” that this will not be enough and will initially entering some blank lines to get some more room. We prevent this by providing enough space right from the start.

    Example: refer to the graphic below, Example A, Step 1.2

  • If a Note is created and the Note Window is not completely visible on the screen, the Notes Functionality must pan the view port area to completely show the Note Window inside the Writer Document window.

    Rationale: The user wants to see the newly created object.

  • If a Note is created, the Notes Functionality must set the focus to the newly created Note Window and places the cursor inside the Note Window. (inside: the area reserved for the Notes User Data)

    Rationale: The user may want to just start typing.

  • If a Note is created, the Notes Functionality must create the Notes Window with the obligatory elements shown in “Structure of the Notes Window”. (elements: e.g. Notes Property Data, option button)
  • If the keyboard button ESC is pressed directly after creating a Note, the Notes Functionality must reverse the action of creating the Note. (directly after creating a note: e.g. the user did not leave the note or added any information; reverse: the state of the Document before creating the Note is restored)

    Rationale: The user may want to revert the action of an accidentally inserted Note.

    Please note: The reversion should be undo-able with the function Undo.

• Inserting or Editing Notes User Data
  • If the user inserts Notes User Data in a Note Window and there is enough both free and visible space below the Notes Window, the Notes Functionality must expand the Notes Window to fit to the amount of Notes User Data. (visible: the space visible for the user; space: space in the Notes Side Pane; expands: expands the height downwards)

    Example: refer to the graphic below, Example B, Step 1.3

  • If the user inserts Notes User Data in a small Note Window and there is neither enough and/or visible space available, then the Notes Functionality must... (small: the height of the Notes is adjusted for less than three lines of Notes User Data; visible: the space visible for the user; space: space in the Notes Side Pane)
    • expand the Notes Window to fit to the amount of Notes User Data.

      Example: refer to the graphic below, Example C, Step 2.1

    • pan the view port area to completely show the Note Window inside the Writer Document Window.
    • Rationale: This is a very special case. If we want to keep the position of the other Notes Windows stable during editing, we have to chose this kind of implementation (overlap parts of the subsequent note). Anyway, we should wait for some feedback from the user base.
  • If less space is available for the Notes Window than it is required to completely display the Notes User Data and the Notes Window has normal size, the Notes Functionality must provide scrollbar functionality inside the Note Window. (space: space in the Notes Side Pane; normal size: the height of the Note Window fits to three lines of Notes User Data; scrollbar functionality: refer to “Design of the Scrollbars”)

    Example: refer to the graphic below, Example C, Step 2.3

Inserting and Editing Notes

The graphic shows: The insertion of Notes (Step 1.1 to Step 1.4) and the editing of Notes (Step 2.1 to Step 2.4) in different situations. The situations show different amount of Notes User Data and different count of already shown Note Windows. Please note: The intention of this graphic is to start a discussion of the Notes behavior. Hopefully, the graphic is self-explanatory. If not, then more detailed information can be found in the text above this graphic. The situation in Step 2.4 of Example D is a bit simplified. Here, the size of the yellow note is the same like in the previous step although there is some more text in it. The real size is based on the amount of Notes User Data there and in the other notes.

Open Points:

• What to do with notes bigger (e.g. higher) than the current ? I propose to not do any scrolling/panning if those notes get the focus (e.g. by viewing/editing). Then, the text cursor inside the Note Window should affect the scrolling behavior of the Document text and simultaneously the Notes Side Pane.
• Answer the question if the panning does annoy the user.

Realization: Realization required for first implementation of Notes.

Future work: At the moment we only focus on a static Notes Windows layout without any smooth animation and re-positioning. If animations were supported this would solve some problems and the described behavior should be revised.

Anchors

The Notes Functionality does provide a Notes Anchor to mark up the text portion which is related to the Notes Data. The kind of Notes Anchor depends on the status of Writer Document text selection when calling the command for inserting the Note.

• If the document has the focus and no document text is selected, then inserting causes the Notes Anchor to be dependent of the text next to the text cursor...
  • If there is some kind of word or string, then the Notes Anchor Area will contain the whole word. (refer to Examples 1 ... 4)
  • If no reasonable text can be detected next to the cursor, then a simple Note Anchor Point is inserted. (refer to Example 5)
• If the document has the focus and document text is selected, then inserting a note causes the Notes Anchor Area to span the current selection of the document text. (refer to Example 6)

In the following examples, symbols are used for the representation of other elements:

• Cursor is represented by |
• Anchor Area start is represented by >
• Anchor Area end is represented by <
• Anchor Point is represented by ^
• Text selection start is represented by [
• Text selection end is represented by ]

Example 1: The Notes Anchor Area for the text “This is some phone number 1030/73506|9495” would be “This is some phone number >1030/73506|9495<”.

Example 2: The Notes Anchor Area for the text “This is we|ird, isn't it?” would be “This is >we|ird<, isn't it?”

Example 3: The Notes Anchor Area for the text “This is weird|, isn't it?” would be “This is >weird|<, isn't it?”

Example 4: The Notes Anchor Area for the text “I do not think this is too good ..|.” would be “I do not think this is too good >..|.<”

Example 5 (with whitespaces): The Notes Anchor Area for the text “And then he said       |      nothing at all.” would be “And then he said       ^|      nothing at all.”.

Example 6: The Notes Anchor for such a selection “This is [some selected] text.” would be “This is >some selected< text.”.

Viewing Notes

(proposal will be provided soon)

If in doubt, draw the notes elements according to their document text position (document text position: considering the reading direction of the document language)

Editing Document Text

Editing the document text may have influence on the Notes in general.

Editing the document text has influence on the Notes Anchors:

• In general, the Notes Anchors keep their position relative to the document text.
• The size of the Notes Anchor Area is dependent on the the text it includes. If the user edits the document text, which is included in the Note Anchor Area then the Note Anchor Area will be adapted accordingly.
  • If characters are deleted inside the Note Anchor Area, then the Notes Anchor Area is reduced accordingly. (refer to Example 1)
  • If characters are added inside the Note Anchor Area, then the Notes Anchor Area is expanded accordingly. (refer to Example 2)
  • If the Note Anchor Area is reduced from on character to “zero” characters, then the Note Anchor Area is converted to a Note Anchor Point at the same position.
  • If the Notes Anchor Point is deleted (e.g. by using the backspace key), then the Note is deleted too. (Todo: If necessary, move this point to Deleting notes.)
  • A Note Anchor Point behaves similar to a normal character in the document text. This behavior is similar to the current implementation of the Notes Anchor in OpenOffice.org Writer.
  • Please note: The kind of Notes Anchor cannot be explicitly altered afterwards by the user.

Example 1: If the text “This is woonderful text.” is corrected to “This is wonderful text.” the Notes Anchor Area “This is >woonderful< text.” would be “This is >wonderful< text.”.

Example 2: If the text “This is wnderful text.” is corrected to “This is wonderful text.” the Notes Anchor Area “This is >wnderful< text.” would be “This is >wonderful< text.”.

Help | User Interface Element Templates | Example Spec

Migration

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

Configuration

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.

Help | File Format Table Template

Open Issues

<State a bulleted list of issues Issue here>