libgui/README

   1 libgui - Handy GUI code
   2
   3 This module has various pieces of code that are useful for a GUI.  For
   4 the most part, they are Tcl/Tk-related.
   5
   6 Open issues:
   7 - bitmaps and canvas code are duplicated in S-N; should look into
   8   sharing
   9 - tkTreeTable taken from S-N but modified; should use the same
  10   version in both places.  Better yet, replace this widget with
  11   one that works better
  12
  13 Here's a brief runthrough:
  14
  15 library/
  16   Directory of Tcl code
  17
  18   balloon.tcl
  19     Tcl code to implement balloon help (aka tooltips)
  20
  21     Primary interface is the "balloon" command.  See last function in
  22     file for details on usage
  23
  24   bindings.tcl
  25     Provides bind_widget_after_class proc; rearranges bindtags in
  26     a frequently-useful way.
  27
  28   canvas.tcl
  29     Tcl procs relating to canvas widgets
  30
  31     set_scroll_region canvas
  32       Set the scroll region on CANVAS to include all items in the
  33       canvas.  Most easily used when bound to <Configure> on the
  34       canvas.
  35
  36   def.tcl
  37       Defining words.
  38
  39       defarray name ?value?
  40         Define a global array named NAME.  VALUE, if present, is the
  41         initial value.  VALUE is in the format expected by "array
  42         set".
  43
  44       defvar name ?value?
  45         Define a new global variable named NAME.
  46
  47   gensym.tcl
  48       Provides the proc "gensym", which generates new symbol names.
  49
  50   gettext.tcl
  51       Defines the stub proc "gettext", used for looking up text in a
  52       localization database.
  53
  54   hooks.tcl
  55       Provides procs for handling hooks (lists of functions that
  56       should be run when something happens).
  57
  58   lframe.tcl
  59       Provides the Labelledframe widget -- a frame with a groove and
  60       a label.
  61
  62   list.tcl
  63       Defines useful list procs.  Some of these are Tcl versions of C
  64       functions in TclX.
  65
  66       lvarpush listvar element ?index?
  67         Insert ELEMENT into list stored in LISTVAR (a variable).
  68         Element is inserted at INDEXth position.  INDEX defaults to
  69         0.
  70
  71       lvarpop listvar ?index?
  72         Remove INDEXth element from list stored in LISTVAR (a
  73         variable).  Returns the removed element.  INDEX defaults to
  74         0.
  75
  76       lassign list args
  77         Assign successive elements from LIST to variables named in
  78         ARGS.  If LIST is longer than ARGS, assign a list of remaining
  79         elements to last variable.
  80
  81       lrmdups list args
  82         Remove duplicates and sort list.  ARGS, if specified, are
  83         arguments to lsort
  84
  85       lremove list element
  86         Return list created by removing the first item `ELEMENT'
  87
  88   mono.tcl
  89     Procs for handling monochrome displays or colorblind users
  90
  91   prefs.tcl
  92     Application preference code.  This will probably vanish at some
  93     point, once we figure out how we really want to do this.  I just
  94     had this code lying around, and it was useful to me, so I included
  95     it.
  96
  97     Defines a single interface, "preference", which has several
  98     subcommands:
  99
 100         preference define name default docstring ?handler?
 101           Define a new preference.  HANDLER, if specified, is a proc
 102           to run whenever the preference's value changes.
 103
 104         preference get name
 105           Return value of preference.
 106
 107         preference documentation name
 108           Return doc string of preference
 109
 110         preference varname name
 111           Return name of variable representing named preference.  This
 112           can be used eg as the -variable of a radiobutton.
 113
 114         preference set name value
 115           Set preference.
 116
 117         preference get_commands
 118           Return text of commands which, when evalled, will restore
 119           the current state of all defined preferences.
 120
 121   sendpr.tcl
 122     The sendpr widget; a GUI for send-pr.
 123
 124   topbind.tcl
 125     Code for bindings on toplevels.
 126
 127     bind_for_toplevel_only toplevel sequence script
 128       Put a binding on window TOPLEVEL for event SEQUENCE.  When the
 129       event is seen, SCRIPT will run.  This proc adds a new bindtag
 130       to the toplevel to avoid the problems associated with putting
 131       bindings directly on toplevels.
 132
 133   ulset.tcl
 134     Attempt to make setting the -underline option easier.  This is
 135     particular good when using gettext.  Unfortunately the interface
 136     is hard to use; it should be changed.
 137
 138     extract_label_info option label
 139       Extract underline and label info from descriptor string LABEL.
 140       Any underline in LABEL is extracted, and the next character's
 141       index is used as the -underline value.  There must be only one
 142       underline in LABEL.  This proc returns a list of the form:
 143
 144          OPTION NEWLABEL -underline INDEX
 145
 146       Eg:  extract_label_info -text _File
 147         -> {-text File -underline 0}
 148
 149 src/
 150   Directory of C code.  This is all put into libide.a.
 151
 152   paths.c
 153     Useful startup code that all applications should run.
 154
 155     int ide_initialize (Tcl_Interp *interp, char *appname);
 156
 157     This function:
 158     - Sets the global Tcl variable ide_application_name to APPNAME.
 159     - Searches the filesystem for the libide Tcl code, and sets
 160       up the auto_path appropriately.  The IDE_LIBRARY environment
 161       variable can override the searching.
 162     - Sets up the auto_path to include the application's Tcl library
 163       as well (if possible).  Applications should install their Tcl
 164       code in $(datadir)/APPNAME/
 165     - Runs the application's startup file - $(datadir)/APPNAME/APPNAME.tcl
 166     - Sets these entries in the global array Paths:
 167         Paths(bitmapdir)  Location of libide bitmaps
 168         Paths(appdir)     Location of application's scripts
 169
 170     This function returns TCL_OK on success, and something else on
 171     error.
 172
 173   subcommand.c
 174     Makes it easy to write commands which are split into a number of
 175     subcommands (eg, like the Tcl "file" command).
 176
 177     int create_command_with_subcommands (Tcl_interp *interp, char *name,
 178                                          struct subcommand_table *table)
 179
 180     Create a new Tcl command name NAME.  TABLE describes the
 181     subcommands; see subcommand.h for details.  Returns TCL_OK on
 182     success, TCL_ERROR on failure.
 183
 184   tkCanvEdge.c, tkCanvLayout.c, tkCanvLayout.h, tkCanvas.c, tkCanvas.h
 185     Patched versions (ugh) of the corresponding Tk files, and some new
 186     files.  These files implement graph layout for canvases.