<chapter id="using-kstars">
<title>A Quick Tour of &kstars;</title>

<para>
This chapter introduces most of the useful features of &kstars;, in the
form of a guided tour.

<screenshot>
<screeninfo>
Here's a screenshot of the &kstars; main window:
</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="screen1.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Main Window</phrase>
  </textobject>
</mediaobject>
</screenshot>
</para>

<para>
In the above screenshot, you can see the sky display centered on the
constellation Taurus.  Stars are displayed with realistic colors and relative
brightnesses.  The brightest stars have their names labeled (&eg;, Aldebaran).
Saturn is visible near the center, and there are a couple dozen deep-sky
objects (shown as colored symbols) throughout the region.  Above the sky
display, there is an information panel displaying the current time and date
(left), the coordinates of the screen center (middle), and the current
geographic location (right). There is a tool bar and a menu bar above the
information panel.  There is a status bar at the bottom of the window, which
displays the name of any object you click on, and the sky coordinates of the
mouse cursor.
</para>

<sect1 id="geolocation">
<title>Where am I?</title>
<para>
The first thing to do is to set the geographic location.  By default,
&kstars; assumes you are in Greenwich, UK (home of the Royal Observatory,
where longitude=0 is defined).  Since you are probably somewhere else,
you'll want to change this.
</para>
<para>
Open the <guilabel>Set Location</guilabel> window by selecting
<guimenuitem>Geographic...</guimenuitem> from the
<guimenu>Location</guimenu> menu, or by pressing the
<guiicon>Globe</guiicon> icon in the toolbar.
</para>

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

<para>
In the upper right, there is a list of over 2000 predefined cities.  You set
your location by highlighting a city from this list.  If your town is not in
the list, you can simply choose the nearest town to you.  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>
It isn't practical to scroll through the full list of 2000 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>US</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.
</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>
If you want to use the exact coordinates of your location, or if there is no
predefined city near your location, you can manually define a new location
using the edit boxes at the bottom of the window.  You must fill in each
of these boxes (except <guilabel>State/Province</guilabel>, which is optional)
before you can add the location to the list of known places.  &kstars; will
automatically load your custom locations in 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>
</sect1>

<sect1 id="settime">
<title>What Time Is It?</title>
<para>
The next thing you may want to do is change the time and/or date.  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 press the <guiicon>Pause</guiicon> icon in the toolbar.  You can make the
clock run slower or faster than normal using the time-step spinbox in the
toolbar.
</para><para>
You can change to any time or date by selecting <guimenuitem>Set
Time...</guimenuitem> from the <guimenu>Time</guimenu> menu, or by
pressing the <guiicon>hourglass</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
ever need to reset the clock back to the current time, just select
<guimenuitem>Set Time to Now</guimenuitem> from the
<guimenu>Time</guimenu> menu.
</para>
</sect1>

<sect1 id="lookaround">
<title>Have a Look Around!</title>
<para>
Now that we have the time and location set, let's have a look around.
You can pan the display using the arrow keys.  If you hold down the
<keycap>Shift</keycap> key before panning, the scrolling speed is doubled.  The
display can also be panned by clicking and dragging with the mouse.  Note that
while the display is scrolling, not all objects are displayed.  This is
done to cut down on the CPU load of recomputing object positions, which
makes the scrolling smoother.  You can zoom in and out with the
<keycap>+</keycap> and <keycap>-</keycap> keys, with the zoom in/out buttons in
the toolbar, or by selecting <guimenuitem>Zoom
In</guimenuitem>/<guimenuitem>Zoom Out</guimenuitem> in the
<guimenu>View</guimenu> menu.  Notice that as you zoom in, you can see fainter
stars than at lower zoom settings.
</para><para>
Zoom out until you can see a green curve; this represents your local
horizon.  If you haven't adjusted the &kstars; configuration, the
display will be solid green below the horizon, representing the solid
ground of the Earth.  There is also a white curve, which represents
the celestial equator (an imaginary line which divides the sky into
northern and southern hemispheres).  There is also a tan curve,
which represents the Ecliptic, the path that the Sun appears to follow
across the sky over the course of a year.  Therefore, the Sun is
always found somewhere along the Ecliptic, and the planets are never
far from it.
</para>
</sect1>

<sect1 id="skyobjects">
<title>Objects in the Sky</title>
<para>
&kstars; displays thousands of objects: stars, planets, clusters,
nebulae and galaxies.  You can identify any object by clicking on it
(its name appears in the statusbar at the bottom of the window.  You
can get more information about an object by right-clicking on it.  A
popup menu will appear, showing its name(s), object type, and links to
images and information from the internet.
</para><para>
If you know of an additional URL with information or an image of the
object, you can add a custom link to the object's popup menu using the
<guimenuitem>Add Link...</guimenuitem> item.  This opens a window in which you
can enter the URL and the text that should appear in the popup menu.  You can
make sure the URL is correct with the <guibutton>Check URL</guibutton> button,
which will test the URL in your web browser.  Please specify whether the URL
points to an Image, or to an HTML document!  If you specify Image here, the new
menu item will open the Image Viewer, not the web browser.  You can also
point to files on your local disk, so this feature could be used to attach
observing logs or other custom information to objects in &kstars;.  Your custom
links are automatically loaded whenever &kstars; starts up, and they are stored
in the directory
<filename class="directory">~/.kde/share/apps/kstars/</filename>, in files
<filename>myimage_url.dat</filename> and <filename>myinfo_url.dat</filename>.
</para><para> You can search for named objects by clicking on the
<guiicon>search</guiicon> icon in the toolbar, or by selecting <guimenuitem>Find
Object...</guimenuitem> from the <guimenu>Location</guimenu> menu.  The
<guilabel>Find Object</guilabel> window lists all the named objects in the
&kstars; database.  Many objects are listed only by their catalog name (for
example, NGC 3077), but some are also listed by their common name (for example,
Whirlpool Galaxy).  You can filter the list by name, or by object type.
Highlight the desired object, and press Ok.  The display will center on the
object and begin tracking it. Note that if the object is below the horizon, you
may not see anything except the ground.  You can make the ground invisible in
the <guilabel>Display Options</guilabel> window.
</para><para>
Object Tracking is automatically engaged whenever an object is
centered in the display, either by using the <guilabel>Find Object</guilabel>
window, by double-clicking on an object, or by selecting <guimenuitem>Center and
Track</guimenuitem> from the right-click popup menu.  You can
disengage tracking by panning the display, pressing the
<guiicon>Lock</guiicon> icon in the toolbar, or selecting
<guimenuitem>Track Object</guimenuitem> from the
<guimenu>Location</guimenu> menu.
</para>
</sect1>
</chapter>