tde-i18n/tde-i18n-en_GB/docs/tdeedu/kstars/config.docbook

<chapter id="config">
<title
>Configuring &kstars;</title>

<sect1 id="setgeo">
<title
>Setting the Geographic Location</title>

<para
>Here is a screenshot of the <guilabel
>Set Geographic Location</guilabel
> window: <screenshot>
<screeninfo
>Changing the Geographic Location</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="geolocator.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>Set Location Window</phrase>
  </textobject>
</mediaobject>
</screenshot>
</para>

<para
>There is a list of over 2500 predefined cities available to choose from. You set your location by highlighting a city from this list. Each city is represented in the world map as a small dot, and when a city is highlighted in the list, a red crosshairs appears on its location in the map. </para>

<para>
<indexterm
><primary
>Geographic Location Tool</primary>
<secondary
>Filtering</secondary
></indexterm>
It is not practical to scroll through the full list of 2500 locations, looking for a specific city. To make searches easier, the list can be filtered by entering text in the boxes below the map. For example, in the screenshot, the text <quote
>Ba</quote
> appears in the <guilabel
>City Filter</guilabel
> box, while <quote
>M</quote
> has been entered in the <guilabel
>Province Filter</guilabel
> box, and <quote
>USA</quote
> is in the <guilabel
>Country Filter</guilabel
> box. Note that all of the cities displayed in the list have city, province and country names that begin with the entered filter strings, and that the message below the filter boxes indicates that 7 cities are matched by the filters. Also notice that the dots representing these seven cities in the map have been coloured white, while the unmatched cities remain grey. </para
><para
>The list can also be filtered by location in the map. Clicking anywhere in the world map will show only those cities within two degrees of the clicked location. At this time, you can search by name, or by location, but not both at once. In other words, when you click on the map, the name filters are ignored, and vice versa. </para
><para>
<indexterm
><primary
>Geographic Location Tool</primary>
<secondary
>Custom locations</secondary
></indexterm>
The <link linkend="ai-geocoords"
>longitude, latitude</link
> and <link linkend="ai-timezones"
>time zone</link
> information for the currently-selected location are displayed in the boxes at the bottom of the window. If you feel that any of these values are inaccurate, you can modify them and press the <guibutton
>Add to List</guibutton
> button to record your custom version of the location. You can also define a completely new location by pressing the <guibutton
>Clear Fields</guibutton
> button, and entering the data for the new location. Note that all fields except the optional <guilabel
>State/Province</guilabel
> must be filled before the new location can be added to the list. &kstars; will automatically load your custom locations for all future sessions. Please note, at this point, the only way to remove a custom location is to remove the appropriate line from the file <filename
>~/.kde/share/apps/kstars/mycities.dat</filename
>. </para
><para
>If you add custom locations (or modify existing ones), please send us your <filename
>mycities.dat</filename
> file so that we can add your locations to the master list. </para>
</sect1>

<sect1 id="settime">
<title
>Setting the Time</title>
<para>
<indexterm
><primary
>Date and Time</primary>
<secondary
>The simulation clock</secondary
></indexterm>
When &kstars; starts up, the time is set to your computer's system clock, and the &kstars; clock is running to keep up with the real time. If you want to stop the clock, select <guimenuitem
>Stop Clock</guimenuitem
> from the <guimenu
>Time</guimenu
> menu, or simply click on the <guiicon
>Pause</guiicon
> icon in the toolbar. You can make the clock run slower or faster than normal, or even make it run backward, using the time-step spinbox in the toolbar. This spinbox has two sets of up/down buttons. The first one will step through all 83 available time steps, one by one. The second one will skip to the next higher (or lower) unit of time, which allows you to make large timestep changes more quickly. </para>
<para>
<indexterm
><primary
>Date and Time</primary>
<secondary
>Setting</secondary
></indexterm>
You can set the time and date by selecting <guimenuitem
>Set Time...</guimenuitem
> from the <guimenu
>Time</guimenu
> menu, or by pressing the <guiicon
>time</guiicon
> icon in the toolbar. The <guilabel
>Set Time</guilabel
> window uses a standard &kde; Date Picker widget, coupled with three spinboxes for setting the hours, minutes and seconds. If you want to re-synchronise the simulation clock back to the current CPU time, just select <guimenuitem
>Set Time to Now</guimenuitem
> from the <guimenu
>Time</guimenu
> menu.</para>

<note
><para>
<indexterm
><primary
>Date and Time</primary>
<secondary
>Extended range of dates</secondary
></indexterm>
&kstars; can accept very remote dates beyond the usual limits imposed by QDate. Currently, you can set the date between the years -50000 and +50000. We may extend this range even further in future releases. However, please be aware that the accuracy of the simulation becomes more and more degraded as more remote dates are examined. This is especially true for the positions of solar system bodies. </para
></note>
</sect1>

<sect1 id="viewops">
<title
>The Configure &kstars; Window</title>
<para>
<indexterm
><primary
>Configure &kstars; window</primary
></indexterm
> The <guilabel
>Configure &kstars;</guilabel
> window allows you to modify a wide range of display options. You can access the window with the <guiicon
>configure</guiicon
> toolbar icon, or by selecting <guimenuitem
>Configure &kstars;...</guimenuitem
> from the <guimenu
>Settings</guimenu
> menu. The window is depicted below: <screenshot>
<screeninfo
>Configure &kstars; Window</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="viewops.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>Configure &kstars; Window</phrase>
  </textobject>
</mediaobject>
</screenshot>
</para>

<para
>The <guilabel
>Configure &kstars;</guilabel
> window is divided into five tabs: <guilabel
>Catalogues</guilabel
>, <guilabel
>Guides</guilabel
>, <guilabel
>Solar System</guilabel
>, <guilabel
>Colours</guilabel
> and <guilabel
>Advanced</guilabel
>. </para>
<para>
<indexterm
><primary
>Configure &kstars; window</primary>
<secondary
>Catalogues Tab</secondary
></indexterm>
In the <guilabel
>Catalogues</guilabel
> tab, you determine which object catalogues are displayed in the map. The <guilabel
>Stars</guilabel
> section also allows you to set the <quote
>faint <link linkend="ai-magnitude"
>magnitude</link
> limit</quote
> for stars, and the <link linkend="ai-magnitude"
>magnitude</link
> limit for displaying the names and/or magnitudes of stars. Below the stars section, the <guilabel
>Deep-Sky Objects</guilabel
> section controls the display of several non-stellar object catalogues. By default, the list includes the Messier, NGC and IC catalogues. You can add your own custom object catalogues by pressing the <guibutton
>Add Custom Catalog</guibutton
> button. For detailed instructions on preparing a catalogue data file, see the <filename
>README.customize</filename
> file that ships with &kstars;. </para>
<para>
<indexterm
><primary
>Configure &kstars; window</primary>
<secondary
>Solar System Tab</secondary
></indexterm>
In the <guilabel
>Solar System</guilabel
> tab, you can specify whether the Sun, Moon, planets, comets and asteroids are displayed, and whether the major bodies are drawn as coloured circles or actual images. You can also toggle whether solar system bodies have name labels attached, and control how many of the comets and asteroids get name labels. There is an option to automatically attach a temporary <quote
>orbit trail</quote
> whenever a solar system body is tracked, and another to toggle whether the colour of the orbit trail fades into the background sky colour. </para>
<para>
<indexterm
><primary
>Configure &kstars; window</primary>
<secondary
>Guides Tab</secondary
></indexterm>
The <guilabel
>Guides</guilabel
> tab lets you toggle whether non-objects are displayed (&ie;, constellation lines, constellation names, the Milky Way contour, the <link linkend="ai-cequator"
>celestial equator</link
>, <link linkend="ai-ecliptic"
>the ecliptic</link
>, <link linkend="ai-horizon"
>the horizon line</link
>, and the opaque ground). You can also choose whether you would like to see Latin constellation names, <acronym
>IAU</acronym
>-standard three-letter abbreviations, or constellation names using your local language. </para>
<para>
<indexterm
><primary
>Configure &kstars; window</primary>
<secondary
>Colours Tab</secondary
></indexterm>
<indexterm
><primary
>Colour Schemes</primary>
<secondary
>Customising</secondary
></indexterm>
The <guilabel
>Colours</guilabel
> tab allows you to set the colour scheme, and to define custom colour schemes. The tab is split into two panels: </para>
<para
>The left panel shows a list of all display items with adjustable colours. Click on any item to bring up a colour selection window to adjust its colour. Below the list is the <guilabel
>Star Colour Mode</guilabel
> selection box. By default, &kstars; draws stars with a <link linkend="ai-colorandtemp"
>realistic colour</link
> tint according to the spectral type of the star. However, you may also choose to draw the stars as solid white, black or red circles. If you are using the realistic star colours, you can set the saturation level of the star colours with the <guilabel
>Star Colour Intensity</guilabel
> spinbox. </para>
<para
>The right panel lists the defined colour schemes. There are four predefined schemes: the <guilabel
>Default</guilabel
> scheme, <guilabel
>Star Chart</guilabel
>, which uses black stars on a white background, <guilabel
>Night Vision</guilabel
>, which uses only shades of red in order to protect dark-adapted vision, and <guilabel
>Moonless Night</guilabel
>, a more realistic, dark theme. Additionally, you can save the current colour settings as a custom scheme by clicking the <guibutton
>Save Current Colors</guibutton
> button. It will prompt you for a name for the new scheme, and then your scheme will appear in the list in all future &kstars; sessions. To remove a custom scheme, simply highlight it in the list, and press the <guibutton
>Remove Colour Scheme</guibutton
> button. </para
><para>
<indexterm
><primary
>Configure &kstars; window</primary>
<secondary
>Advanced Tab</secondary
></indexterm>
The <guilabel
>Advanced</guilabel
> Tab provides fine-grained control over the more subtle behaviours of &kstars;. </para
><para>
<indexterm
><primary
>Atmospheric Refraction</primary
></indexterm
> The <guilabel
>Correct for atmospheric refraction</guilabel
> checkbox controls whether the positions of objects are corrected for the effects of the atmosphere. Because the atmosphere is a spherical shell, light from outer space is <quote
>bent</quote
> as it passes through the atmosphere to our telescopes or eyes on the Earth's surface. The effect is largest for objects near the horizon, and actually changes the predicted rise or set times of objects by a few minutes. In fact, when you <quote
>see</quote
> a sunset, the Sun's actual position is already well below the horizon; atmospheric refraction makes it seem as if the Sun is still in the sky. Note that atmospheric refraction is never applied if you are using <guilabel
>Equatorial coordinates</guilabel
>. </para
><para>
<indexterm
><primary
>Animated Slewing</primary
></indexterm
> The <guilabel
>Use animating slewing</guilabel
> checkbox controls how the display changes when a new focus position is selected in the map. By default, you will see the sky drift or <quote
>slew</quote
> to the new position; if you untick this option, then the display will instead <quote
>snap</quote
> immediately to the new focus position. </para
><para>
<indexterm
><primary
>Objects in the Sky</primary>
<secondary
>Labelling</secondary>
<tertiary
>Automatic</tertiary>
</indexterm>
If the <guilabel
>Attach label to centred object</guilabel
> checkbox is selected, then a name label will automatically be attached to an object when it is being tracked by the program. The label will be removed when the object is no longer being tracked. Note that you can also manually attach a persistent name label to any object with its <link linkend="popup-menu"
>popup menu</link
>. </para
><para>
<indexterm
><primary
>Objects in the Sky</primary>
<secondary
>Hiding</secondary
></indexterm>
There are three situations when &kstars; must redraw the sky display very rapidly: when a new focus position is selected (and <guilabel
>Use animated slewing</guilabel
> is checked), when the sky is dragged with the mouse, and when the time step is large. In these situations, the positions of all objects must be recomputed as rapidly as possible, which can put a large load on the <abbrev
>CPU</abbrev
>. If the <abbrev
>CPU</abbrev
> cannot keep up with the demand, then the display will seem sluggish or jerky. To mitigate this, &kstars; will hide certain objects during these rapid-redraw situations, as long as the <guilabel
>Hide objects while moving</guilabel
> checkbox is selected. The timestep threshold above which objects will be hidden is determined by the <guilabel
>Also hide if timescale greater than:</guilabel
> timestep-spinbox. You can specify the objects that should be hidden in the <guilabel
>Configure Hidden Objects</guilabel
> group box. </para>
</sect1>

<sect1 id="customize">
<title
>Customising the Display</title>

<para
>There are several ways to modify the display to your liking.</para>
<itemizedlist>
<listitem
><para>
<indexterm
><primary
>Colour Schemes</primary
><secondary
>Selecting</secondary
></indexterm>
Select a different colour scheme in the <menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>Colour Schemes</guimenuitem
></menuchoice
> menu. There are four predefined colour schemes, and you can define your own in the <link linkend="config"
><guilabel
>Configure &kstars;</guilabel
></link
> window. </para
></listitem>
<listitem
><para>
<indexterm
><primary
>Toolbars</primary>
<secondary
>Customising</secondary
></indexterm>
Toggle whether the Toolbars are drawn in the <menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>Toolbars</guimenuitem
></menuchoice
> menu. Like most KDE toolbars, they can also be dragged around and anchored on any window edge, or even detached from the window completely. </para
></listitem>
<listitem
><para>
<indexterm
><primary
>Info Boxes</primary
><secondary
>Customising</secondary
></indexterm>
<indexterm
><primary
>Info Boxes</primary
><secondary
>Shading</secondary
></indexterm>
Toggle whether the Info Boxes are drawn in the <menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>Info Boxes</guimenuitem
></menuchoice
> menu. In addition, you can manipulate the three Info Boxes with the mouse. Each box has additional lines of data that are hidden by default. You can toggle whether these additional lines are visible by double-clicking a box to <quote
>shade</quote
> it. Also, you can reposition a box by dragging it with the mouse. When a box hits a window edge, it will <quote
>stick</quote
> to the edge when the window is resized. </para
></listitem>
<listitem>
<para>
<indexterm
><primary
>Field-of-View Symbols</primary
><secondary
>Description</secondary
></indexterm>
Choose an <quote
>FOV Symbol</quote
> using the <menuchoice
><guimenu
>Settings</guimenu
><guimenuitem
>FOV Symbols</guimenuitem
></menuchoice
> menu. <firstterm
>FOV</firstterm
> is an acronym for <quote
>field-of-view</quote
>. An FOV symbol is drawn at the centre of the window to indicate where the display is pointing. Different symbols have different angular sizes; you can use a symbol to show what the view through a particular telescope would look like. For example, if you choose the <quote
>7x35 Binoculars</quote
> FOV symbol, then a circle is drawn on the display that is 9.2 degrees in diameter; this is the field-of-view for 7x35 binoculars. </para>
<para>
<indexterm
><primary
>Field-of-View Symbols</primary
><secondary
>Customising</secondary
></indexterm>
You can define your own FOV symbols (or modify the existing symbols) using the <guimenuitem
>Edit FOV Symbols...</guimenuitem
> menu item, which launches the FOV Editor: </para>
<screenshot>
<screeninfo
>Field-of-View Symbols Editor</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="fovdialog.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>FOV Symbol Editor</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para
>The list of defined FOV symbols is displayed on the left. On the right are buttons for adding a new symbol, editing the highlighted symbol's properties, and removing the highlighted symbol from the list. Note that you can even modify or remove the four predefined symbols (if you remove all symbols, the four defaults will be restored the next time you start &kstars;). Below these three buttons is a graphical preview display showing the highlighted symbol from the list. When the <guibutton
>New...</guibutton
> or <guibutton
>Edit...</guibutton
> button is pressed, the <guilabel
>New FOV Symbol</guilabel
> window is opened: </para>

<screenshot>
<screeninfo
>New Field-of-View Symbol</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="newfov.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase
>New FOV Symbol</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>
<indexterm
><primary
>Field-of-View Symbols</primary
><secondary
>Defining New</secondary
></indexterm>
This window lets you modify the four properties that define a FOV symbol: name, size, shape and colour. The angular size for the symbol can either be entered directly in the <guilabel
>Field of View</guilabel
> edit box, or you can use the Eyepiece/Camera Tabs to calculate the field-of-view angle, given parameters of your telescope/eyepiece or telescope/camera setup. The four available shapes are: Circle, Square, Crosshairs, and Bullseye. Once you have specified all four parameters, press <guibutton
>Ok</guibutton
>, and the symbol will appear in the list of defined symbols. It will also be available from the <guimenu
>Settings</guimenu
> | <guisubmenu
>FOV</guisubmenu
> menu. </para>
</listitem>
</itemizedlist>

</sect1>

</chapter>