KStars Customization Guide.
copyright 2002 by Jason Harris and the KStars team
This document is licensed under the terms of the GNU Free 
Documentation License
---------------------------

This document provides a brief overview of the many advanced customization
features provided in the program.  If you have a useful customization that
you would like to share with the KStars community, please consider 
submitting it to kstars@30doradus.org; we may incorporate your data into
a future version of KStars!


1. Color Schemes

In the "Colors" tab of the KStars Configuration window, the colors of 
all items drawn in the sky map can be customized.  At any time,
you can save the current collection of colors into a custom color scheme.
Saved schemes will appear in the listbox on the right of the Colors 
tab, as well as in the "Settings|Color Schemes" menu.  In addition,
the custom color schemes are automatically reloaded when KStars starts up, 
so they will always be available.

You can remove a custom color scheme at any time by highlighting it in the 
listbox and then pressing the "remove" button.


2. Geographic Locations

The Change Location window allows you to set the geographic location
by choosing from a list of over 2000 predefined cities around the world.
If you would like to use a location that is not on the list, enter the
relevant information (longitude, latitude, city name, province name, and
country name), then press "Add to list".  All fields must be filled, except
the optional province field.

In addition, you can also modify the values for an existing city, by 
simply changing the values in the window, and adding it to the list.


3. Object Catalogs

You can easily add your own object data to KStars.  First, prepare the 
object catalog data file.  Each line in the file should contain the 
following space-separated fields:

for stars:
type(0 for stars), RA, Dec, mag, SpType, name(optional)

other types:
type(3-8), RA, Dec, mag, name(optional)

The types are:
0: star
1: star (in object catalog...probably don't want to use this)
2: planet (don't use this in custom catalog)
3: open cluster
4: globular cluster
5: gaseous nebula
6: planetary nebula
7: supernova remnant
8: galaxy

The SpType is a short string for the spectral type.  For example, "B5" or "G2"
The coordinates should be given as floating-point values, in the J2000.0 epoch.
The name can be anything you wish.  If the name is more than one word, it
must be enclosed in quotation marks.

Once you have constructed a custom data file, open the Configuration window
to the Catalogs tab, and press the "Add Custom Catalog" button.  A popup
window appears in which you can specify a name for the catalog, and the 
name of the file (including the path).  

When you press Ok, KStars will attempt to read the lines of your data file.
It will report any problems, and if any lines at all were successfully parsed,
you are given a choice to accept the data file (ignoring any unparsed lines),
or to cancel the operation to attempt to resolve the problems first.

Once the data file has been accepted, your custom catalog will be loaded on 
startup along with the standard catalogs, and there will be a checkbox in the 
Configuration window to toggle the display of your catalog objects.

You can remove custom catalogs by highlighting its checkbox in the 
Configuration window, and pressing the "Remove Custom Catalog" button (this
button is only active if a custom catalog is highlighted in the list
of checkboxes).


4. URL Links

You can add your own internet links to any object by selecting the 
"Add Link..." item from the object's right-click popup menu.  A
window opens in which you can enter text to appear in the new menu item,
and the URL which should be opened.  You should also specify whether the 
link points to an image or an HTML page (Image links open the Image Viewer,
HTML links open a Konqueror window).  The menu text is filled
with a default string at first; feel free to modify it.

Note that the URL can point to a file on your hard drive, so this is an 
interesting way to catalog your own astrophotos, or perhaps to keep 
observing notes about different objects...