Welcome to the notation_toolbar_2 branch:

Revision 2.1 – 08/29/2009

This page is a reference for the branch/obsolete/notation_toolbar_2 branch.

NOTE: This branch was not intended as a rewrite of the entire notation view interface but is limited to a few very focused aspects related to notation entry which requires a rewrite of the NoteInserter and RestInserter classes.

Create a consistent notation entry flow in notation view (mouse, keyboard, or MIDI device–step record.)

• Primary Task:
  • Creating a Notation Inserter Tool
• Secondary tasks:
  • Cleaning up code associated with the duration toolbar
  • Set an example of cooperation and foster creativity, and communication.

NOTE: This tool will actually add little new code. The Notation Inserter Tool will basically just act a the glue to make restInserter and noteInserter behave as two parts of one tool. Doing this will all the gui and users to treat it as one tool and see it as distinct mode in notation view.

Basic Information:

The Notation Inserter Tool will:

• treat the restInserter and noteInserter as two parts of a single tool.
• remember its current state (noteInserter/restInserter mode, and duration information) when another mode is entered.
• recall its prior state (noteInserter/restInserter, and duration) when reentering Notaiton Insertion mode.

GUI related information:

• Graphic: red pencil (data/pixmaps/stock/pencil.png)
• Shortcut key: F3
• Scope: Accessible on same level as Select Tool, and Erase Tool (From most places within notation view)
• Location: Tools Toolbar, and Tools pulldowm menu.

NOTE: Notation Inserter Tool will have one icon associated with it to match the Draw mode of other RG windows.

Notation Inserter Tool State Information:

NOTE: These states are listed to show how things will work, they do not imply how things will actually be coded. Code that achieves the same effect in a relatively efficient matter is acceptable.

Initial State:

NOTE: This state is entered only when notation view first opens. After entering Initial State, a duration will always be associated with throughout the life of the notation view window. This is new. Initial state was handled differently.

• Notation Inserter Tool is selected as the current tool (Draw mode on the Tools toolbar.)
• Notation Inserter Tool is set to noteInserter mode.
• Duration is set to a default based on the time signature of the earliest measure being viewed.
  • x/2 time = half note/rest
  • x/4 time = quarter note/rest
  • x/8 time = eighth note/rest
  • etc.
• the Notation Inserter Tool enters Non-active State (Select Tool is selected) or the Select Tool is selected in there is existing events (Thanks Michael for the input.)

Non-active State:

NOTE: This state occurs when another tool (mode) is entered. These actions outline what happens during this time visually and also mentions methods the will trigger Active State, but does not imply any special coding.

• New modes button is depressed (Cleft Inserter, Text Inserter, Selection Tool, Eraser, etc.)
• Last palette on duration toolbar stays visible with note or rest duration remaining depressed.
  • Note: This is new. Trunk de-selects the button. This feature will help users understand what duration will be used upon entering active state (regardless of noteInserter / restInserter mode). This will also serve as a reminder as to which state the Notation Inserter Tool is in (though not currently active.)
• 'Y' keystroke does nothing. (NOTE: We can debate the value of this, but this is the current behavior in trunk)
• '.' keystroke does nothing.
  • NOTE: This is new. In trunk a message box appears saying “no duration is selected.” We could do something, since it is currently wired to be processed. What value does it add to process it. So to be consistent with the 'Y' keystroke in this state, just ignore it and don't display the message box.

Entering Active State:

NOTE: These items outline commands that trigger active state along with the actions tied to the keys. Basically, with all of the actions and ways to interact via keyboard, mouse, etc. a proper notationInsert mode or restInserter mode can be entered in a consistent (and hopefully sane matter) that allows for predictable keyboard sequences and predictable durations based on the state recall of the Notation Inserter Tool.

• duration shortcut keys
• NOTE: These keys are active in all modes in the notation view window. These action are a result of a 'best' compromise between competing needs of keyboard entry, visual feedback, and hybrid keyboard/mouse entry (keyboard durations and mouse pitch and location actions.)
  • keystrokes: 1 2 3 4 5 6 8 0
  • Actions attached to keystrokes:
    • NOTE: the duration attached to the keystrokes have not changed. This is a description “conceptually” as to what happens when these actions are selected.
    • the recall state of the Notation Inserter Tool is set to note_mode
      • NOTE: this is different than trunk. This is a restoring of what happens in Classic when the shortcut is selected
    • the recall state of the Notation Inserter Tool is set to no dots.
      • NOTE: this is the current behavior in trunk and classic.
    • Process Duration Shortcut (Enter Active State and let it process the keystroke)

• note shortcuts keys
• NOTE: These keys are active in all modes in the notation view window. This is the behavior in trunk, but not in classic. Classic displays a message box that says “no duration was selected”
  • keystrokes: A B C D E F J I K L M N O Q R S U V W X Z
  • Actions attached to keystrokes:
    • NOTE: The actual pitch assigned to the keys have not changes
    • the recall state of the Notation Inserter Tool is set to noteInserter.
      • NOTE: This is new. Classic inserted rests when restInserter or is active (probably a bug). Trunk insert notes via switching to noteInserter briefly then restoring restInserter (which is better). But just switching to noteInserter is more consistent and we loose nothing for inserting rests (see rest shortcut below)
  • Process Note Shortcut (where keystroke is processed and then enter Active State)

• rest shortcut
• NOTE: This key is active in all modes, trunk / classic and this branch all will exhibit different behavior.
  • keystrokes: P
  • Action attached to keystroke:
    • the recall state of the Notation Inserter Tool is set to restInserter.
    • Process Note Shortcut (Enter Active State and let it process the keystroke)

• Notation Inserter Tool tool
• NOTE: This refers to selecting Notation Inserter Tool from the keyboard, pulldown menu, or mouse selection. This design will allow the Notation Inserter Tool tool to act in the same fashion as the other notation view tools.
• If not in Active State
  • Enter Active State
• else do nothing.

Active State:

• Depress Notation Inserter Tool button on Tools Toolbar.
• Recall Notation Inserter Tool state
  • If recalled state is noteInserter:
    • Update the duration Toolbar to display the note palette (honor dot settings from recall)
  • If the recalled state is restInserter:
    • Update the duration Toolbar to display the rest palette (honor dot settings from recall)
  • Accept 'Y' shortcut to toggle between noteInserter and restInserter
  • Accept '.' shortcut to toggle between dot durations and non-dotted durations.
  • Plus cursor used for pointer on canvas.
  • process commands via keyboard, mouse, etc.
    • '.', duration toolbar, or pulldown menu - toggle the dot / no-dots duration values for the the active inserter (restInserter/ noteInserter).
    • 'Y', duration toolbar, or pulldown menu - switch between restInserter / noteInserter.
    • rest insert shortcut key ('P')
      • Update Notation Inserter Tool according to Entering Active State
      • Insert a rest based Notation Inserter Tool state information.
    • duration shortcuts keys
      • Update Notation Inserter Tool according to Entering Active State
    • note shortcut keys
      • Update Notation Inserter Tool according to Entering Active State
      • Insert note based on Notation Inserter Tool state information and pitch assigned to shortcut.
      • NOTE: This is the current behavior in trunk, and also the current behavior in classic when in noteInserter or restInserter modes.
    • Duration toolbar events (mouse clicks)
    • No change from trunk behavior.

• Cleaning up code associated with the duration toolbar
  • Look as 'switch to rest', 'switch to note', and 'toggle dot' code to set if some refactoring is needed. Current implementation has these coded differently, but essentially act in the same manner as toggles.
  • Try to eliminate the need for duplicate action names. currently there are 'duration_' prefixed actions that have almost equivalent non-prefixed actions.
• Set an example of cooperation and foster creativity, and communication.

These terms a used to help focus the discussion in a way top make this page readable and transparent. So when these words are used, they are meant in the context as stated in this section.

Draw (Tool): This name is given in the source code. Draw is the draw mode, typically represented by a red pencil and accessed via the Tools toolbar button, the F3 key, or from the pulldown menu.

Mode: I refer to this as the current state of input activity. Draw mode, Select Mode, Erase Mode. So this suggests RG functions in modes or states.

Inserter: In the RG source code, it appear to be anything that draw events. Ther word inserter appears to be asscociated with clefs, text, notes, rest, etc.

noteInserter: The name is given in the source code. noteInserts deal with drawing notes. restInserter: The name is given in the source code. restInserters deal with drawing rests.

Notation: Notes and Rests. Other items are notation, but not in the context of this page.

Notation Inserter Tool: A Tool for drawing notes and rests. The Draw (Tool) for notation view. (See main text for details).

Current state / prior state: In reference to Notation Inserter Tool, The tool remembers its last state (noteInserter/restInserter, and duration) upon returning to it from another mode (tool).

Depress: to show that a current item of a group is selected (implies the other items in group an “deselecte.”

Branch location: http://rosegarden.svn.sourceforge.net/viewvc/rosegarden/branches/obsolete/notation_toolbar_2

Branch date: August 25, 2009

Estimated branch merge date: September 6th, 2009

Branch creation commit information: Committed revision 10761.

Branch Milestones:

• September 2, 2009 – Major initial programming complete (Committed revision 10802).
• September 2, 2009 – First round of revision complete (Committed revision 10806).
• September 5, 2009 – Merge to trunk (Committed revision Revision 10828).