<chapter id="entering">
<title>Entering Scores</title>

<para>
&frescobaldi; provides a host of features to help you to enter &lilypond; music scores as fast as possible.
</para>

<sect1 id="scorewiz">
<title>Score Setup Wizard</title>

<para>
The Score Setup Wizard, at <menuchoice>
  <shortcut><keycombo><keycap>Ctrl+Shift+N</keycap></keycombo></shortcut>
  <guimenu>&lilypond;</guimenu>
  <guimenuitem>Setup New Score...</guimenuitem>
</menuchoice>, makes
for a quick start of many types of music score. In the first tab you can enter
titling information, in the second tab you can compose your score of many
available part types. Doubleclick a part type to add it to your score (or click
<guibutton>Add</guibutton>). Select the part in the score list to change some settings for the selected
part, if desired. Many parts, especially Choir, have powerful options to set up
the score the way you want it.
</para>

<figure>
  <title>Score Wizard: Titles and Headers</title>
  <mediaobject>
  <imageobject><imagedata format="PNG" fileref="scorewiz1.png"/></imageobject>
  <textobject>
  <phrase>Score Wizard: Titles and Headers</phrase>  
  </textobject>
  </mediaobject>
</figure>

<figure>
  <title>Score Wizard: Parts setup</title>
  <mediaobject>
  <imageobject><imagedata format="PNG" fileref="scorewiz2.png"/></imageobject>
  <textobject>
  <phrase>Score Wizard: Parts setup</phrase>
  </textobject>
  </mediaobject>
</figure>

<para>
In the third tab you can set some general adjustments, e.g. whether to create
MIDI output or not, which key and time signature you want to use, etc:
</para>

<figure>
  <title>Score Wizard: Score settings</title>
  <mediaobject>
  <imageobject><imagedata format="PNG" fileref="scorewiz3.png"/></imageobject>
  <textobject>
  <phrase>Score Wizard: Score settings</phrase>
  </textobject>
  </mediaobject>
</figure>

<para>
Clicking <guibutton>Try</guibutton> presents a demo score with some random notes filled in.
Clicking <guibutton>Ok</guibutton> writes the &lilypond; code to your text document,
waiting for music etc. to be added.
</para>
</sect1>

<sect1 id="autocomplete">
<title>Context Sensitive Autocompletion</title>

<para>
&frescobaldi; has a context-sensitive automatic
completion feature. In most cases it will be enabled by default. It will pop up
relevant completions as you type. The autocompletion popup can be enabled or
disabled under 
<menuchoice>
  <guimenu>Settings</guimenu>
  <guisubmenu>Configure &frescobaldi;</guisubmenu>
  <guisubmenu>Editor component</guisubmenu>
  <guisubmenu>Editing</guisubmenu>
  <guimenuitem>Auto Completion</guimenuitem>
</menuchoice>.
Even if disabled, you can always show the popup with <keycap>Ctrl+Space</keycap>.
</para>
</sect1>

<sect1 id="expand">
<title>Quick Text Expansions</title>

<para>
Type e.g. <userinput>rel</userinput> and then press <keycap>Ctrl+.</keycap> (period).
&frescobaldi; will expand it to:
</para>

<programlisting>
\relative c' {

}
</programlisting>

<para>
and place the cursor right after the pitch so you could change it. If you then
move the cursor a line down, you can start typing music notes or other
shortcut names. E.g. typing <userinput>F</userinput> and then <keycap>Ctrl+.</keycap> yields <computeroutput>\key f \major</computeroutput>.
There are many more default shortcuts.
</para>

<para>
Press <keycap>Ctrl+.</keycap> (without having entered an existing
shortcut name) to open a dialog with all defined text snippets. In this dialog you
can also add, alter or remove snippets.
It is also possible to assign a keyboard shortcut to a snippet so that it can be entered
with a simple keystroke, without typing the short name.
</para>

<para>
All changes you make in the dialog are immediately saved.
So clicking <guibutton>Cancel</guibutton> will still keep the changes.
Clicking OK will enter the currently selected snippet in the text editor.
See the "What's This" info (<keycap>Shift+F1</keycap>) in the dialog
for more information.
</para>

<para>
Some quick text expansions have default keyboard shortcuts.
The most important ones are listed below:
</para>

<informaltable>
<tgroup cols="2">
<tbody>

<row>
<entry><para><keycap>Alt+1</keycap></para></entry>
<entry><para>Enter <userinput>\voiceOne</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Alt+2</keycap></para></entry>
<entry><para>Enter <userinput>\voiceTwo</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Alt+3</keycap></para></entry>
<entry><para>Enter <userinput>\voiceThree</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Alt+4</keycap></para></entry>
<entry><para>Enter <userinput>\voiceFour</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Alt+0</keycap></para></entry>
<entry><para>Enter <userinput>\oneVoice</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Ctrl+3</keycap></para></entry>
<entry><para>Enter <userinput>\times 2/3 { }</userinput> and leave the cursor between the brackets</para></entry>
</row>

<row>
<entry><para><keycap>Alt+M</keycap>, <keycap>Alt+B</keycap></para></entry>
<entry><para>Enter <userinput>\markup \bold { }</userinput> and leave the cursor between the brackets</para></entry>
</row>

<row>
<entry><para><keycap>Alt+M</keycap>, <keycap>Alt+I</keycap></para></entry>
<entry><para>Enter <userinput>\markup \italic { }</userinput> and leave the cursor between the brackets</para></entry>
</row>

</tbody></tgroup></informaltable>

</sect1>

<sect1 id="rumor">
<title>MIDI input via Rumor (&linux; only)</title>

<para>
&frescobaldi; can use an external program called
<productname>Rumor</productname>, enabling you to enter music just by playing it on a
MIDI keyboard (or even your computer keyboard). This has some limitations: you
can only play monophonic music (notes or chords). Rumor also does not support
tuplets. To use Rumor within &frescobaldi;, you must have installed it separately.
Refer to the <ulink url="http://www.volny.cz/smilauer/rumor/">Rumor homepage</ulink>
for download and install information.
</para>

<sect2>
<title>Setup</title>
<para>
Start the Rumor plugin with <keycap>Meta+Alt+R</keycap> or by clicking on its
tab in the bottom of the &frescobaldi; window. The Rumor panel appears at the
bottom. In the panel is a settings button where you can configure which MIDI
input and output you want to use.
</para>

<para>
If you have a MIDI keyboard controller but no audible output device you can run
an ALSA MIDI-client like &timidity;. Many &linux; distributions already start
&timidity; by default on bootup. But &frescobaldi; can also run it for you when you
press the TiMidity-button. You can configure the command to run
in the main settings dialog under &menu.settings.rumor;.
</para>

<para>
If you have no MIDI-controller you can also set the MIDI input to 'Computer
Keyboard' in the settings screen of the Rumor plugin. This way you can play on
your computer keyboard like a piano.
</para>
</sect2>

<sect2>
<title>Entering music</title>
<para>
Clicking the <guibutton>Record</guibutton> button starts Rumor. If all is well you hear
a metronome and you can start playing; you'll see the notes appear. Clicking
<guibutton>Record</guibutton> again or pressing <keycap>Escape</keycap> stops Rumor. If you already entered the key and
time signature in your document, &frescobaldi; will automatically use it, to
interpret alterations correctly. &frescobaldi; will also output pitches
automatically in the language you use in the document.
</para>

<para>
You can configure the shortest note value to use using the <guilabel>Quantise</guilabel> option.
If you enable the <guilabel>Step</guilabel> checkbox, Rumor will directly output every note played,
without a duration.
If you enable the <guilabel>Mono</guilabel> checkbox, Rumor will not output chords, but only single
notes.
</para>

<para>
Under the <guibutton>Settings</guibutton> button you can configure some more settings.
A powerful feature of Rumor is that it can load special scripts that change the Rumor
output. This is useful when you write e.g. music with complicated rhythms. You
can configure which scripts to load, and even put your own Rumor Guile scripts
in <filename class="directory">~/.kde/share/apps/frescobaldi/rumor/</filename>.
More information about writing Rumor scripts is on the
<ulink url="http://www.volny.cz/smilauer/rumor/">Rumor homepage</ulink>.
</para>
</sect2>
</sect1>

<sect1 id="quickinsert">
<title>Quick Insert Panel</title>

<para>
The Quick Insert Panel (<keycap>Meta+Alt+I</keycap>) is available in the left dock.
It has panels to add articulations, dynamics and other symbols to your music.
You can use the mouse wheel to quickly flip through the panels.
</para>

<para>
Some music symbols can be place above the staff or below, or in a neutral (default) position.
If you want to use an explicit position for those symbols, you can adjust the
<guilabel>Direction</guilabel> control to <guilabel>Up</guilabel>, <guilabel>Down</guilabel>
or <guilabel>Neutral</guilabel> before clicking the symbol.
</para>

<para>
Right-click a button to configure its keyboard shortcut if you want to.
Some buttons have default keyboard shortcuts:
</para>

<informaltable>
<tgroup cols="2">
<tbody>

<row>
<entry><para><keycap>Alt+'</keycap></para></entry>
<entry><para>Enter a breathing sign <userinput>\breathe</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Ctrl+(</keycap></para></entry>
<entry><para>Enter a slur over the selected music fragment</para></entry>
</row>

<row>
<entry><para><keycap>Alt+.</keycap></para></entry>
<entry><para>Enter a final bar line <userinput>\bar "|."</userinput></para></entry>
</row>

<row>
<entry><para><keycap>Alt+;</keycap></para></entry>
<entry><para>Enter a double bar line <userinput>\bar "||"</userinput></para></entry>
</row>

</tbody></tgroup></informaltable>


<sect2 id="quickinsert-articulations">
<title>The Articulations panel</title>

<para>
You can just click on a note in the PDF preview and then on an articulation symbol in the
articulations panel.
The articulations panel is smart enough to place the articulation after the current
note or chord and its duration.
</para>

<para>
If you select a range of text and then click a symbol, the symbol will be added
to all notes or chords in the selected music fragment.
</para>
 
<tip><para>
You can select a music fragment using the PDF preview: click the first note of
the range you want to select and then shift-click the second note.
</para></tip>
</sect2>

<sect2 id="quickinsert-dynamics">
<title>The Dynamics panel</title>

<para>
Typing single dynamics in &lilypond; is not difficult at all, but the power of this panel
is the possibility to easily insert crescendos and diminuendos in ranges of music.
</para>

<para>
If no music is selected the dynamic sign is just placed after the current note or chord.
If a range of music has been selected (e.g. using the preview), you can click
e.g. a dynamic mark, a spanner and another mark, to add them to your music.
If you only click a spanner and a mark, the mark will be added at the end.
</para>

</sect2>

<sect2 id="quickinsert-spanners">
<title>The Spanners panel</title>

<para>
This panel lets you add slurs, beams or trills to a selected music fragment.
Arpeggios can be added to the chord the cursor is at,
and glissandos can be added to the current note; &lilypond; will automatically 
conenct them with the next note.
</para>
</sect2>

<sect2 id="quickinsert-barlines">
<title>The Bar Lines panel</title>

<para>
With this panel you can insert many different kinds of bar lines and breathing signs.
</para>
</sect2>

</sect1>

<sect1 id="other">
<title>Other shortcuts</title>

<para>
<menuchoice>
  <shortcut><keycombo><keycap>Ctrl+;</keycap></keycombo></shortcut>
  <guimenuitem>Repeat last note or chord</guimenuitem>
</menuchoice> repeats the last entered note or chord with
all its suffixes (ties, articulations, etc.)
</para>

<para>
<menuchoice>
  <shortcut><keycombo><keycap>Ctrl+{</keycap></keycombo></shortcut>
  <guimenuitem>Insert pair of braces</guimenuitem>
</menuchoice> inserts a pair of braces <userinput>{ }</userinput> with an empty,
indented line in between and places the cursor there.
If text is selected, it is placed between the braces.
</para>

<para id="charselect">
<menuchoice>
  <shortcut><keycombo><keycap>Ctrl+Y</keycap></keycombo></shortcut>
  <guimenuitem>Special Characters</guimenuitem>
</menuchoice> opens a dialog where characters from the Unicode table can be
browsed and selected. Doubleclick a character (or click <guibutton>Apply</guibutton>)
to insert the currently selected character into the document. It is also possible
to assign a keyboard shortcut to the currently selected character.
</para>

</sect1>
</chapter>
