Extended Tcl Commands

Any Tcl commands that are implemented in C or C++ are considered part of the public interface. This makes sense, since the private part is hidden in the C or C++ code. This includes central commands such as rtdimage (an extended Tk image type and also a Tcl command) and astrocat , the Tcl interface to the catalog library, and also any of the commands provided by the Tcl, Tk, TclX, Itcl, and BLT Toolkits.

C++ Classes

The public methods of any C++ classes are naturally part of the public interface.

Derived classes also have access to protected methods and member variables. You might need this access in order to derive a subclass of, for example, the RtdImage or Skycat classes, for adding new image features.

Derived classes may redefine base class methods, however if the derived class version does not also call the parent class version, we can not guarantee future compatibility.

C Libraries

The C interfaces used by skycat and rtd all have C++ class wrappers, so none of the C libraries belong to the "supported" public interface. Use the C++ classes instead. In this way, we can replace a C library, while still keeping the same C++ class interface. This is also very likely to happen, especially for classes, such as FitsIO and WCS.

Itcl Classes, Itk Widgets

The Itcl classes used by skycat use the keywords public , private , and protected to indicate which parts of the class belong to the public interface, which parts are private, and which parts may only be used in derived classes. Itcl is not as strict as C++ at enforcing these restrictions, since you can get around them, for example, by calling a method with the full "scope" path name. Still, this helps to document the public interface. The man pages for the classes also list the public and protected methods as well as the Itk components , which are the symbolic names of the internal widget components.

Any Itk components are public, so you can use the Itk component command to access internal widgets. Thus, it is okay to use " $w component canvas ", but not " $w.canvas ", which might change to something else in the future, such as " $w.top.left.canvas ".

Any Itk options or public class variables are also public. You can access these values with the built-in cget and configure methods.

Derived classes may need to also access the protected member variables and methods. For example, nearly all of the Itk widgets used by skycat are derived from either TopLevelWidget or FrameWidget and refer to their widget frames as $w_ , which is a protected variable in the base class. Protected variables for widget names are okay to use in derived classes, however hard coded widget path names (even relative path names) should be avoided, if possible.

As with the C++ interface, derived classes may redefine base class methods, however if the derived class version does not also call the parent class version, we can not guarantee future compatibility.

Most of the Itcl classes used in skycat define Itk widgets that interact with the user. There are not normally many methods that are meant to be called from outside the class hierarchy. These include any callback methods for button presses or other events and any methods that add new menus or other widgets to the display or return the names of existing widgets. For example, the following methods, which are defined in the TopLevelWidget base class, are part of the public interface:

start	Member proc to start an application from the main class.
busy	Display the busy cursor over the window while evaluating some commands.
add_menubar	Add a menu bar to the window.
add_menubutton	Add a menubutton to the menu bar.
add_menuitem	Add a menu item to a menubutton.
configure_menubutton	Configure a menubutton.
get_menu	Get the widget name of a menu from the menubutton label.
add_help_button	Add a help button to the menubar.
list_windows	Return a list of top level windows, besides this one.
hide_windows	Hide all top level windows besides this one.
add_short_help	Add a short help window to the main window.
quit	Quit the window and exit the application, if there are no more windows.

Tcl Procs

There are a number of utility procs defined in the tclutil package (in tkutil.tcl and tclutil.tcl). These are part of the public interface and are not likely to change.

Also, all of the dialog procs in the tclutil package (in udialog.tcl) are public. These include procs such as error_dialog , info_dialog , and warning_dialog (see the plugin example earlier in this chapter).