# A Quick Tour of &kstars;

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

Here's a screenshot of the &kstars; main window: Main Window

In the above screenshot, you can see the sky display centered on the constellation Orion, which is about to set below the western horizon. Stars are displayed with realistic colors and relative brightnesses. The brightest stars have their names labeled (&eg;, Betelgeuse). M 42, the Orion Nebula, is visible below Orion's "belt" stars, just above the horizon. In three corners of the Sky display, there are on-screen text labels displaying data on the current time ("LT: 11:38:34 09/10/02"), the current Geographic Location ("Greenwich, United Kingdom"), and the current object in the center of the display ("Focused on: nothing"). Above the sky display, there are two toolbars. The main toolbar contains shortcuts for menu functions, as well as a time-step widget which controls how fast the simulation clock runs. The view toolbar contains buttons that toggle the display of different kinds of objects in the sky. At the bottom of the window, there is a status bar which displays the name of any object you click on, and the sky coordinates (Right Ascension and Declination) of the mouse cursor.

## Where am I?

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.

Open the Set Geographic Location window by selecting Set Geographic Location... from the Settings menu, or by pressing the Globe icon in the toolbar, or by typing Ctrlg.

Here is a screenshot of the Set Geographic Location window: Changing the Geographic Location Set Location Window

In the upper right, there is a list of over 2000 predefined cities. 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.

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 Ba appears in the City Filter box, while M has been entered in the Province Filter box, and USA is in the Country Filter 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 colored white, while the unmatched cities remain grey.

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.

The longitude, latitude and time zone 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 Add to List button to record your custom version of the location. You can also define a completely new location by pressing the Clear Fields button, and entering the data for the new location. Note that all fields except the optional State/Province 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 `~/.kde/share/apps/kstars/mycities.dat`.

If you add custom locations (or modify existing ones), please send us your `mycities.dat` file so that we can add your locations to the master list.

## What Time Is It?

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 Stop Clock from the Time menu, or simply click on the Pause icon in the toolbar. You can make the clock run slower or faster (even backward) than normal 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.

You can change to any time or date by selecting Set Time... from the Time menu, or by pressing the hourglass icon in the toolbar. The Set Time 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 Set Time to Now from the Time menu. [NB: the current version of KStars cannot accept dates before October 1, 1752, nor dates after the year 8000. These are limitations of the Qt Date/Time class. We may implement our own date/time class in a future version.]

## Have a Look Around!

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 &Shift; 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 configure what gets hidden while scrolling in the Display Options window; this is covered in the next chapter). There are five ways to change the magnification of the display: (1) use the + and - keys, (2) press the zoom in/out buttons in the toolbar, (3) select Zoom In/Zoom Out in the View menu, (4) use the scroll wheel on your mouse, or (5) drag the mouse up and down with the middle button pressed. Notice that as you zoom in, you can see fainter stars than at lower zoom settings.

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.

## Objects in the Sky

&kstars; displays thousands of objects: stars, planets, clusters, nebulae and galaxies. By default, stars are drawn as white circles with a colored border that simulates the star's real color. Planets are drawn as colored dots at low zoom levels, but as an actual image of the planet as you zoom in. Deep-sky objects (clusters, nebulae and galaxies) are drawn with symbols color-coded to indicate the catalog to which they belong (Messier, NGC or IC). Most Messier objects are drawn as real images on the map at higher zoom levels. Deep-sky objects with extra image or information links available are drawn with a special color (red by default). Clicking on an object will identify it in the status bar. Double-clicking will recenter the display on the object and begin tracking the object (so that it will remain centered as time passes). Right-clicking an object opens a popup menu with more options.

### The Popup Menu

Here is an example of the right-click popup menu, for the Orion Nebula: Popup Menu for M 42 Popup Menu for M 42

The appearance of the popup menu depends somewhat on the kind of object you right-click on, but the basic structure is the following:

The top section contains information labels, which are not selectable. The top one to three labels display the object's name(s) and object type. The next three labels show the object's rise, transit, and set times. The next section contains two selectable items. First, a "Center and Track" item, which will recenter the display on the object, and keep it centered as time passes (you can also center and track an object by simply double-clicking on it). Next, a "Details..." item, which will show a window with more detailed information about the object. The bottom section contains links to images and/or informative webpages about the selected object.

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 Add Link... item at the bottom of the menu. 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 Check URL 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 `~/.kde/share/apps/kstars/`, in files `myimage_url.dat` and `myinfo_url.dat`. If you build an extensive list of custom links, consider submitting them to us, we would like to include them in the next version of &kstars;!

### Finding Objects

You can search for named objects by clicking on the search icon in the toolbar, by selecting Find Object... from the Focus menu, or by pressing Ctrlf. The Find Object 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 in the list, and press Ok. The display will center on the object and begin tracking it. Note that if the object is below the horizon, the program will warn you that you may not see anything except the ground (you can make the ground invisible in the Display Options window, or by pressing the Ground button in the View toolbar).

Object Tracking is automatically engaged whenever an object is centered in the display, either by using the Find Object window, by double-clicking on an object, or by selecting Center and Track from the right-click popup menu. You can disengage tracking by panning the display, pressing the Lock icon in the Main toolbar, or selecting Track Object from the Focus menu.

## Customizing the Display

There are several ways to modify the display to your liking. First of all, you can select a different color scheme in the Settings|Color Schemes menu. There are three predefined color schemes, and you can define your own in the View Options window (covered in the next chapter). You can hide the Toolbars in the Settings|Toolbars menu, and hide the Info Boxes in the Settings|Info Boxes menu. In addition, you can manipulate the 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 "shade" it. Also, you can reposition a box by dragging it with the mouse. When a box hits a window edge, it will "stick" to the edge when the window is resized.

The remaining customizations are covered in the next chapter.