<chapter id="using-kturtle">
<title>Using &kturtle;</title>

<screenshot>
  <screeninfo>Here is a screenshot of &kturtle; in action</screeninfo>
  <mediaobject>
    <imageobject>
      <imagedata fileref="mainwindow_flower_nrs.png" format="PNG"/>
    </imageobject>
    <textobject>
      <phrase>&kturtle; Main Window</phrase>
    </textobject>
  </mediaobject>
</screenshot>

<para>The main window of &kturtle; has three main parts: <link linkend="the-editor">the editor</link> (1) on the left where you type the &turtlescript; commands, the <link linkend="the-canvas">the canvas</link> (2) on the right where the turtle make your drawing, and the <link linkend="the-inspector">inspector</link> (3) which gives you information when your program executes. Besides these you find <link linkend="the-menubar">the menu bar</link> (5) from where all the actions can be reached, <link linkend="the-toolbar">the toolbar</link> (4) that allows you to quickly select the most used actions, the <guilabel>Console:</guilabel> input box, that you can use to enter a one line command to test it, and <link linkend="the-statusbar">the statusbar</link> (along the bottom of the window) where you will find feedback on the state of &kturtle;.</para>

<sect1 id="the-editor">
<title>The Editor</title>
<para>In the editor you type the &turtlescript; commands. Most of functions of the editor can be found in the <link linkend="the-file-menu">File</link> and <link linkend="the-edit-menu">Edit</link> menus. The editor can be docked on each border of the main window or it can be detached and placed anywhere on your desktop.</para>
<para>You have several ways to get some code in the editor. The easiest way is to use an example: choose the <menuchoice><guimenu>File</guimenu><guisubmenu>Examples</guisubmenu></menuchoice> submenu and select an example. The file example you choose will be opened in the <link linkend="the-editor">the editor</link>, you can then use the <menuchoice><guimenu>Run</guimenu><guimenuitem>Run</guimenuitem></menuchoice> menu item (shortcut: <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>) or the <inlinemediaobject> <imageobject> <imagedata fileref="media-playback-pause.png" format="PNG"/> </imageobject> </inlinemediaobject> <guibutton>Run</guibutton> button from the toolbar to run the code if you like.</para>
<para>You can open &turtlescript; files by choosing the <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu item.</para>
<para>The third way is to directly type your own code in the editor or to copy/paste some code.</para>
</sect1>


<sect1 id="the-canvas">
<title>The Canvas</title>
<para>The canvas is the domain of the turtle, here the turtle draws according to the commands it gets. After getting some code in the <link linkend="the-editor">Editor</link> and executing it, two things can happen: either the code executes fine, and will you most likely see something change on the canvas; or you have made an error in your code in that case the error tab will appear explaining you what mistake you made.</para>
<para>You can zoom in and out the canvas with your mouse wheel.</para>
</sect1>


<sect1 id="the-inspector">
<title>The Inspector</title>
<para>The inspector informs you about the variables, the learned functions and show the code tree while the program is running.</para>
<para>The inspector can be docked on each border of the main window or it can be detached and placed anywhere on your desktop.</para>
</sect1>


<sect1 id="the-toolbar">
<title>The Toolbar</title>
<para>Here you can quickly reach the most used actions. The Toolbar also contains the <guilabel>Console:</guilabel> input box, where you can quickly invoke commands, this might be useful in case you want to test a command without modifying the content of the <link linkend="the-editor">Editor</link>.</para>
<para>You can configure the toolbar using <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem></menuchoice> to better fit your preferences.</para>
</sect1>


<sect1 id="the-menubar">
<title>The Menubar</title>
<para>In the menubar you find all the actions of &kturtle;. They are in the following groups: <guimenu>File</guimenu>, <guimenu>Edit</guimenu>, <guimenu>Canvas</guimenu>, <guimenu>Run</guimenu>, <guimenu>Tools</guimenu>, <guimenu>Settings</guimenu>, and <guimenu>Help</guimenu>. This section describes them all.</para>

<sect2 id="the-file-menu">
<title>The File Menu</title>

  <variablelist>
    <anchor id="file-new" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>N</keycap></keycombo>
        </shortcut>
        <guimenu>File</guimenu>
        <guimenuitem>New</guimenuitem>
      </menuchoice></term>
      <listitem><para>Creates a new, empty &turtlescript; file.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-open" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>O</keycap></keycombo>
        </shortcut>
        <guimenu>File</guimenu>
        <guimenuitem>Open...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Opens a &turtlescript; file.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-open-recent" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>File</guimenu>
        <guisubmenu>Open Recent</guisubmenu>
      </menuchoice></term>
      <listitem><para>Opens a &turtlescript; file that has been opened recently.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-open-examples" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>File</guimenu>
        <guisubmenu>Examples</guisubmenu>
      </menuchoice></term>
      <listitem><para>Open example &turtlescript; programs. The examples are in your favorite language that you can choose in the <menuchoice><guimenu>Settings</guimenu><guisubmenu>Script Language</guisubmenu></menuchoice> submenu.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-get-more-examples" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>Get more examples...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Open the <guilabel>Get Hot New Stuff</guilabel> dialog to download
      additional &turtlescript; files from the Internet.</para></listitem>
    </varlistentry>
  </variablelist>

  <variablelist>
    <anchor id="file-save" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>S</keycap></keycombo>
        </shortcut>
        <guimenu>File</guimenu>
        <guimenuitem>Save</guimenuitem>
      </menuchoice></term>
      <listitem><para>Saves the currently opened &turtlescript; file.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-save-as" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;&Shift;<keycap>S</keycap></keycombo>
        </shortcut>
        <guimenu>File</guimenu>
        <guimenuitem>Save As...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Saves the currently opened &turtlescript; file on a specified location.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-export-to-html" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>File</guimenu>
        <guimenuitem>Export to HTML...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Exports the current content of the Editor as an &HTML; file that includes highlighting colors.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-print" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>P</keycap></keycombo>
        </shortcut>
        <guimenu>File</guimenu>
        <guimenuitem>Print...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Prints the current code in the editor.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="file-quit" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>Q</keycap></keycombo>
        </shortcut>
        <guimenu>File</guimenu>
        <guimenuitem>Quit</guimenuitem>
      </menuchoice></term>
      <listitem><para>Quits &kturtle;.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="the-edit-menu">
  <title>The Edit Menu</title>
  <variablelist>
    <anchor id="edit-undo" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>Z</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Undo</guimenuitem>
      </menuchoice></term>
      <listitem><para>Undoes the last change to code. &kturtle; has unlimited undos.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-redo" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;&Shift;<keycap>Z</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Redo</guimenuitem>
      </menuchoice></term>
      <listitem><para>Redoes an undone change to the code.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-cut" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>X</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Cut</guimenuitem>
      </menuchoice></term>
      <listitem><para>Cuts the selected text from <link linkend="the-editor">the editor</link> to the clipboard.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-copy" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>C</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Copy</guimenuitem>
      </menuchoice></term>
      <listitem><para>Copies the selected text from <link linkend="the-editor">the editor</link> to the clipboard.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-paste" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>V</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Paste</guimenuitem>
      </menuchoice></term>
      <listitem><para>Pastes the text from the clipboard to <link linkend="the-editor">the editor</link>.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-select-all" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>A</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Select All</guimenuitem>
      </menuchoice></term>
      <listitem><para>Selects all the text from <link linkend="the-editor">the editor</link>.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-find" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>F</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Find...</guimenuitem>
      </menuchoice></term>
      <listitem><para>With this action you can find phrases in the code.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="edit-find-next" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo><keysym>F3</keysym></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Find Next</guimenuitem>
      </menuchoice></term>
      <listitem><para>Use this to find the next occurrence of the phrase you searched for.</para></listitem>
    </varlistentry>
  </variablelist>  
  <variablelist>
    <anchor id="edit-find-previous" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Shift;<keysym>F3</keysym></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Find Previous</guimenuitem>
      </menuchoice></term>
      <listitem><para>Use this to find the previous occurrence of the phrase you searched for.</para></listitem>
    </varlistentry>
  </variablelist>
  <!--<variablelist>
    <anchor id="edit-replace" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>R</keycap></keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Replace...</guimenuitem>
      </menuchoice></term>
      <listitem><para>With this action you can replace text in the code.</para></listitem>
    </varlistentry>
  </variablelist>-->
<variablelist>
    <anchor id="toggle-insert" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ins;</keycombo>
        </shortcut>
        <guimenu>Edit</guimenu>
        <guimenuitem>Overwrite Mode</guimenuitem>
      </menuchoice></term>
      <listitem><para>Toggle between the 'insert' and 'overwrite' mode.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>


<sect2 id="the-canvas-menu">
  <title>The Canvas Menu</title>
  <variablelist>
    <anchor id="canvas-export-to-image" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Canvas</guimenu>
        <guimenuitem>Export to Image (PNG)...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Exports the current content of the <link linkend="the-canvas">Canvas</link> as a raster image of the PNG (Portable Network Graphics) type.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="canvas-export-to-drawing" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Canvas</guimenu>
        <guimenuitem>Export to Drawing (SVG)...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Exports the current content of the <link linkend="the-canvas">Canvas</link> as a vector drawing of the &SVG; (Scalable Vector Graphics) type.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="canvas-print" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Canvas</guimenu>
        <guimenuitem>Print Canvas...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Prints the current content of the <link linkend="the-canvas">Canvas</link>.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="the-run-menu">
  <title>The Run Menu</title>
  <variablelist>
    <anchor id="run-execute" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo><keysym>F5</keysym></keycombo>
        </shortcut>
        <guimenu>Run</guimenu>
        <guimenuitem>Run</guimenuitem>
      </menuchoice></term>
      <listitem><para>Starts the execution of the commands in the editor.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="run-pause" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo><keysym>F6</keysym></keycombo>
        </shortcut>
        <guimenu>Run</guimenu>
        <guimenuitem>Pause</guimenuitem>
      </menuchoice></term>
      <listitem><para>Pauses the execution. This action is only enabled when the commands are actually executing.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="run-stop" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo><keysym>F7</keysym></keycombo>
        </shortcut>
        <guimenu>Run</guimenu>
        <guimenuitem>Abort</guimenuitem>
      </menuchoice></term>
      <listitem><para>Stops the execution. This action is only enabled when the commands are actually executing.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="run-speed" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Run</guimenu>
        <guisubmenu>Run Speed</guisubmenu>
      </menuchoice></term>
      <listitem><para>Present a list of possible execution speeds, consisting of: <guimenuitem>Full Speed (no highlighting and inspector)</guimenuitem>, <guimenuitem>Full Speed</guimenuitem>, <guimenuitem>Slow</guimenuitem>, <guimenuitem>Slower</guimenuitem>, <guimenuitem>Slowest</guimenuitem> and  <guimenuitem>Step-by-Step</guimenuitem>. When the execution speed is set to <guimenuitem>Full Speed</guimenuitem> (default) we can barely keep up with what is happening. Sometimes this behavior is wanted, but sometimes  we want to keep track of the execution. In the latter case you want to set the execution speed to <guimenuitem>Slow</guimenuitem>, <guimenuitem>Slower</guimenuitem> or <guimenuitem>Slowest</guimenuitem>. When one of the slow modes is selected the current position of the executor will be shown in the editor. <guimenuitem>Step-by-Step</guimenuitem> will execute one command at a time.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>



<sect2 id="the-tools-menu">
  <title>The Tools Menu</title>
  <variablelist>
    <anchor id="tools-direction-chooser" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Tools</guimenu>
        <guimenuitem>Direction Chooser...</guimenuitem>
      </menuchoice></term>
      <listitem><para>This action opens the direction chooser dialog.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="tools-color-chooser" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Tools</guimenu>
        <guimenuitem>Color Picker...</guimenuitem>
      </menuchoice></term>
      <listitem><para>This action opens the color picker dialog.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="the-setting-menu">
  <title>The Settings Menu</title>
  <variablelist>
    <anchor id="settings-set-script-language" />
    <varlistentry>
      <term><menuchoice><guimenu>Settings</guimenu><guisubmenu>Script Language</guisubmenu></menuchoice></term>
      <listitem><para><action>Choose</action> the language for the code.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-toggle-editor" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>E</keycap></keycombo>
        </shortcut>
        <guimenu>Settings</guimenu>
        <guimenuitem>Show Editor</guimenuitem>
      </menuchoice></term>
      <listitem><para>Show or hide the <link linkend="the-editor">Editor</link>.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-toggle-inspector" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo>&Ctrl;<keycap>I</keycap></keycombo>
        </shortcut>
        <guimenu>Settings</guimenu>
        <guimenuitem>Show Inspector</guimenuitem>
      </menuchoice></term>
      <listitem><para>Show or hide <link linkend="the-inspector">the inspector</link>.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-toggle-errors" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Settings</guimenu>
        <guimenuitem>Show Errors</guimenuitem>
      </menuchoice></term>
      <listitem><para>Show or hide the <guilabel>Errors</guilabel> tab with a list of errors resulting from running the code. If this option is enabled, click on <guilabel>Canvas</guilabel> to see the turtle again.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-toggle-linenumbers" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo><keysym>F11</keysym></keycombo>
        </shortcut>
        <guimenu>Settings</guimenu>
        <guimenuitem>Show Line Numbers</guimenuitem>
      </menuchoice></term>
      <listitem><para>With this action you can show the line numbers in <link linkend="the-editor">the editor</link>. This can be handy for finding errors.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-toggle-toolbar" />
    <varlistentry>
      <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Toolbar</guimenuitem></menuchoice></term>
      <listitem><para><action>Toggle</action> the Main Toolbar.</para></listitem>
    </varlistentry>
  </variablelist>  
  <variablelist>
    <anchor id="settings-toggle-statusbar" />
    <varlistentry>
      <term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem></menuchoice></term>
      <listitem><para><action>Toggle</action> the Statusbar.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-configure-shortcuts" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Settings</guimenu>
        <guimenuitem>Configure Shortcuts...</guimenuitem>
      </menuchoice></term>
      <listitem><para>Standard &kde; dialog to configure the shortcuts.</para></listitem>
    </varlistentry>
  </variablelist>
  <variablelist>
    <anchor id="settings-configure-toolbars" />
    <varlistentry>
      <term><menuchoice>
        <guimenu>Settings</guimenu>
        <guimenuitem>Configure Toolbars...</guimenuitem>
      </menuchoice></term>
      <listitem><para>The standard &kde; dialog for configuring the toolbars.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>

<sect2 id="the-help-menu">
  <title>The Help Menu</title>
<para>&kturtle; has a default &kde; <guimenu>Help</guimenu> menu as described in the 
<ulink url="help:/fundamentals/menus.html#menus-help">&kde; Fundamentals</ulink> 
with one additional entry:</para>
  <variablelist>
    <anchor id="help-context-help" />
    <varlistentry>
      <term><menuchoice>
        <shortcut>
          <keycombo><keysym>F2</keysym></keycombo>
        </shortcut>
        <guimenu>Help</guimenu>
        <guimenuitem>Help on: ...</guimenuitem>
      </menuchoice></term>
      <listitem><para>This is a very useful function: it provides help on the code where the cursor in the editor is at. So, &eg;, you have used the <userinput>print</userinput> command in your code, and you want to read and to know what the handbook says on this command. You just move your cursor so it is in the <userinput>print</userinput> command and you press <keysym>F2</keysym>. The handbook will then show all info on the <userinput>print</userinput> command.</para>
      <para>This function can prove to be useful while learning &turtlescript;.</para></listitem>
    </varlistentry>
  </variablelist>
</sect2>

</sect1>


<sect1 id="the-statusbar">
<title>The Statusbar</title>
<para>On the status bar you get feedback of the state of &kturtle;. On the left side it shows the feedback on the last action. On the right side you find the current location of the cursor (line and column numbers). In the middle of the status bar is indicated the current language used for the commands.</para>
</sect1>

</chapter>