The AstroCat, AstroQuery and QueryResult Widgets

These widgets are used for querying catalogs and viewing query results.

The AstroCat(n) widget implements the top level window shown above. The layout of the window is dependent on settings in the config entry for the catalog. The window shown above is for the GSC catalog. The AstroCat widget combines an AstroQuery(n) widget at top, containing the search options with a QueryResult(n) widget for displaying the query results. The menubar at top and the short help window at the bottom are inherited from AstroCat 's base class, TopLevelWidget (see the tclutil package documentation for a description of this class). The button frame at the bottom is just a Tk frame containing some buttons that access AstroCat methods.

The AstroQuery widget, at top, creates a frame with labels and entries for searching the catalog, based on the catalog configuration entry. The Object Name entry as well as the a and d entries are only displayed if the catalog supports world coordinates, otherwise, if the catalog uses image pixel coordinates, X and Y entries are displayed. When the user types return or hits the Search button, a caller specified command is evaluated. Below is an example of how the AstroCat class creates an instance of the AstroQuery widget:

 
method add_search_options {} { 
    itk_component add searchopts { 
        set searchopts_ [AstroQuery $w_.searchopts \ 
            -relief groove \ 
            -borderwidth 2 \ 
            -astrocat [code $w_.cat] \ 
            -command [code $this query_done]] 
   } 
   pack $itk_component(searchopts) -side top -fill x 
}

The - astrocat option specifies the name of the C++ astrocat object used to access the catalog. The caller specified method, query_done , is called whenever a query has completed, with the following arguments:

errorMessage	If this is not empty, it contains an error message and the following arguments should be ignored. If there were no errors, this arg is an empty string.
headings	These are the column headings of the query result, in the form of a Tcl list.
info	This is a Tcl list of rows, the result of the query, where each row is a list of column values.
more	This flag is set to 1 if there were more rows available that were not returned due to the maximum row limit set.

The widget used to display the results of a catalog query is called QueryResult . This widget is basically a TableList widget (described in the tclutil documentation) with a few methods added for working with catalogs (It is not displayed for image servers). The main job of this widget is to format the query results and add bindings so that the user can click on the list to do something with the data. This class also implements some methods for adding, removing, and editing rows in a local catalog using the EnterObject(n) widget (see below).

The EnterObject Widget

This widget is used for entering or editing catalog data. It is basically a simple EntryForm widget (described in the tclutil documentation), with some added functionality. You specify the list of column names (headings) and optionally the values, and the widget displays entries for each value.

Example:

 
EnterObject $w_.ef \ 
    -title {Please enter the data for a new object below:} \ 
    -labels $headings \ 
    -command [code $this enter_object]

See teh man page EnterObject(n) for more details.

The CatalogInfo Widget

This widget is used for browsing catalog directory hierarchies. It displays a hierarchical list of catalogs and catalog directories.

When first started, the window displays the default list, which is either taken from a local config file or from some HTTP server. The default configuration file is taken from http://archive.eso.org/skycat/ , however this can be overridden with the CATLIB_CONFIG environment variable.

When the user clicks on a directory entry, the contents of the catalog configuration file at the given site are fetched (usually via HTTP GET) and the new catalog information is inserted in the list at the appropriate place in the list.

You can navigate the list by clicking on the + and - directory buttons. Double-clicking on a catalog entry also opens a window for the catalog. You can add and remove catalog entries using the interface and save the result to a local catalog config file that can then be used as the new default catalog list.

Example:

 
CatalogInfo .catinf \ 
    -id $id \ 
    -classname $classname\ 
    -debug $debug \ 
    -command [code AstroCat::update_catalog_menus]

The example above creates a CatalogInfo window. This code is implemented in an AstroCat method, catalog_directory .

 
catalog_directory $id $classname $debug

The arguments are all optional: $ id is a unique string used when creating new catalog windows ( skycat uses this to pass the image name, for example). $ classname is the name of the class used to create a new catalog window (defaults to AstroCat ). This can be overridden to use a derived class. $ debug is a flag that is also passed to any new catalog windows created. The - command argument specifies a command to be evaluated whenever the list of catalogs changes. In the above example, this is used to update the catalog menus. See CatalogInfo(n) for more details.

The SymbolConfig Widget

This widget is used for setting plot symbol options. The information goes into a catalog configuration file and can be used by applications to plot catalog objects over an image.

Each row in the table at the top of the window describes one symbol to be plotted for each object in the catalog matching the given condition . All of the type-in entries may contain Tcl style expressions using selected column names as variables. These variables are set for each row in the results of a catalog query before plotting any symbols.

You do need to indicate which column names you plan to use as variables in the Used list at the top of the frame.

Example:

 
set_plot_symbols

The AstroCat::set_plot_symbols method creates this window. The AstroCat::plot method is called whenever the information is changed to update the plot window. Since the AstroCat class does not actually do any plotting, this method must be defined in a derived class to do plotting. See the skycat package for an example of this. See SymbolConfig(n) for more details.

The SearchConfig Widget

This widget is used for setting or editing the list of search columns for a catalog. The listbox on the right side contains all of the column headings for the catalog. You can use the arrow buttons to move column headings to the left listbox or rearrange them there. For each name in the list, you can specify the labels to appear in the AstroCat (or derived class) widget. The default labels are " Min ..." and " Max ..." (replace ... with the column name).

When a query is made, the values the user typed in at these labels are made available through the %cond variable in the catalog query URL. This variable expands to a string of the form:

 
colname1=minValue,maxValue&colname2=value&...

If the second (max) value is empty, only the first (min) value is considered (i.e.: colName=value ).. So, for example, if the catalog configuration file contained the following line:

 
url: http://archive.eso.org/skycat/servers/foo?%ra%dec%cond

The resulting URL might look like this (only the entries with one or both values are used):

 
http://archive.eso.org/skycat/servers/foo?03:22:41-37:12:36&mag=0,16%p=2

See SearchConfig(n) for more details.

The PreviewPlot Widget

The PreviewPlot widget is used to display a graph of data returned from the special Preview catalog columns. Some catalogs (such as the HST catalogs) return a column containing a URL that points to data that can be retrieved and plotted in a graph. By convention, the column name is Preview (case insensitive).

The format of the data is a tab table (the same as the local catalog format) with 2 columns, one for each axis. The column headings are displayed as the X and Y axis labels.

This widget is created automatically by the AstroCat class when the Preview button is pushed (in method get_preview ). See PreviewPlot(n) for more details.