#!/afs/ece/usr/tcl/bin/wish -f

set Bind_Keyword [file tail [info script]]
source "[file dirname [info script]]/../aux/teach_bind.tcl"

# Help text.
set Help "" ; append Help {Gridth -- Add row or column numbers to text.

This program teaches widgets that contain text to show their line or column
numbers. It provides two functions, one to turn on or off a horizontal 'grid'
of column numbers, and one to turn on or off a vertical 'grid' of row numbers.
It works on text, listbox and entry widgets.

} $TH_Bindings_Help {

Widgets of Gridth

The Packing Radiobuttons

These buttons indicate on what sides of the remote widget the horizontal
and vertical grids should be placed.


The Vertical Grid Width Scale

Using this scale, you can select how many digits of precision the vertical
grid can hold. For example, using a scale value of 2 lets the grid display 2
digits, so it gives you unique numbers from 1 to 100.

} $TH_Teach_Bind_Help {

Bugs / Limitations

When putting both grids up on a Text or Listbox (entries only support horizontal
grids), if you put up the horizontal grid before the vertical grid, the
horizontal grid can get packed badly. To avoid this, put up the vertical grid
before the horizontal one.

The size of the grid is determined by the dimensions of the text inside the
widget. The grid does not automatically change when the dimensions of the text
change, to change the grid, you must turn it off and on again.

For Text widgets, the horizontal grid is automatically set to the width of the
Text widget. This is determined by the -width configuration option; if the
actual text width does not match the value in the configuration, the horizontal
grid will not be the same width as the text. This can happen if the widget gets
expanded via packing or interactive resizing by the window manager. You can
avoid this by using resizeth on your text widgets, or using gridded text
widgets.

Entry widgets with special characters (such as "\x0d", better known as newline)
can offset their horizontal grid. The grid number always matches the leftmost
entry position, but if a control character like newline is visible in the entry,
the grid numbers after the newline will be offset. However, this won't affect
scanning or scrolling...if you scroll past the odd character, the grid's
counting system will right itself once again.

Likewise, text widgets that have word or character wrapping will not always
agree with the value on their vertical grid. The top value on the grid will
match the top line on the text, however, long text lines will screw up the count
on the grid lower on. Again, this disappears when the long line is scrolled or
scanned past the top of the widget. You can also avoid this by selecting -wrap
char or -wrap word on your text widget's configuration options (configureth can
do this for you).

If the numbers in the vertical grid contain more digits than the width can
support, then the numbers are truncated in the smallest digits. This can be
alleviated by using a larger width for the grid. (You can also resize the
grid widget with resizeth.)

The grid numbers are desinged to match the indices of the row or column they
identify. So the first item on a listbox gets grid number 0, since the listbox
knows it as item 0. And the first line on a text widget gets grid number 1,
since its index is 1.0.
}

# Gives app all the code necessary to do our functions.
proc teach_code {app widget} {
  set class [send $app winfo class $widget]
  global TH_Dir
  if {[file exists "$TH_Dir/lib/grid.[set class].tcl"]} {
    include_files $app [list grid.$class.tcl "th_[set class]_toggle_grid_x"]
}}

# For a widget, returns the appropriate bindings. (They will depend on the
# widget, it must be able to support scrollbars.)
proc widget_bindings {app w} {
  global TH_Dir Bindings Grid_Y_Width Side
  set class [send $app winfo class $w]
  if {![file exists "$TH_Dir/lib/grid.[set class].tcl"]} {return ""}

  set bindings [list [regexp_replace $Bindings(Grid,X) %XP \
		 	[pack_side_parms $w $Side(X) "send \"$app\""]]]
  if {$class != "Entry"} {
    lappend bindings [regexp_replace [regexp_replace \
			$Bindings(Grid,Y) %GW $Grid_Y_Width] %YP \
			[pack_side_parms $w $Side(Y) "send \"$app\""]]
  }
  return $bindings
}


create_form_scale .gyw "Vertical Grid Width" Grid_Y_Width 4 -from 1 -to 7
label .gp -text "Packing Sides for Grids" ; pack .gp -side top -fill x -expand no
radiobutton .top -text "Top" -variable Side(X) -value top
radiobutton .bottom -text "Bottom" -variable Side(X) -value bottom
radiobutton .left -text "Left" -variable Side(Y) -value left
radiobutton .right -text "Right" -variable Side(Y) -value right
foreach widget {.top .bottom .left .right} {pack $widget -side left -expand yes -fill x}
update_arguments Side(X) top
update_arguments Side(Y) left


