/ 
Tk-LineNumberText-0.5
River stage zero No dependents
/ Tk::LineNumberText

NAME

Tk::LineNumberText - Line numbers for your favorite Text-derived widget

SYNOPSIS

$linenumtext = $parent->LineNumberText(Text-Derived Widget,?options?);

EXAMPLE

use Tk;
use Tk::LineNumberText;

my $mw=tkinit;
$mw->LineNumberText('Text',
  -wrap=>'word',
  -font=>['Courier',12],
  -linenumfont=>['Courier',12],
  -curlinehighlight=>'both',
  -bg=>'white')->pack(-fill=>'both', -expand=>1);

MainLoop;

RELEASE NOTES

This version is NOT backwards compatible. Some options have been deleted and others have changed. This was to be expected anyways - as v0.1 was documented as beta. For various reasons - I have jumped straight to a v0.5. Whenever the word "Text" is used within this documentation - it is assumed that it refers to the "Text-derived widget" you pass at instantiation.

DESCRIPTION

LineNumberText is a composite widget which provides line numbers for your favorite widget derived from Tk::Text or, of course, even for Tk::Text itself.

SUPER-CLASS

LineNumberText ISA Tk::Frame consisting of a Canvas to plot the line numbers and a Scrolled Text widget. This code has been tested using Tk::Text, Tk::CodeText and Tk::TextUndo.

The line numbers should adjust automatically as text is edited or scrolled (either programmatically or interactively). If you find cases where this doesn't happen - please contact the author with the particulars.

LineNumberText does not sub-class any of the Text methods. Instead, AUTOLOAD is used to get at the Text methods and then the line number update is done. The previous version used to actually override all these methods, which caused problems for some users. This is no longer the case.

WIDGET-SPECIFIC OPTIONS

All options should be available as per your Text widget documentation. Additionally the following options are offered..

In Alphabetical Order

-allowbookmarks

Boolean to allow <1> or disallow <0> user-interactive bookmarks.

-bookmarkfill

Fill color for bookmark.

-bookmarkoutline

Outline color for bookmark.

-bookmarkshape

Shape of bookmark must be one of: rectangle, circle or triangle

-bookmarkstipple

Bitmap stipple for bookmarks. eg/ gray50

-curlinebg

Background color of the current line. The current line is defined as the line containing the insert cursor.

-curlinefg

Foreground color of the current line. The current line is defined as the line containing the insert cursor.

-curlinehighlight

Must be ONE of the following:

none

Current line will NOT be highlighted. This is the default.

text

Highlight the entire current line in the text widget only.

linenum

Highlight the current line number only.

both

Highlight the current line in both the text widget and the line number.

-curlinestipple

Bitmap stipple to use on the current line highlight background. Default is no stipple (i.e. undef).

-linenumactivefg

Active color of the line numbers. Done by adjusting the -activefill option of a canvas text item.

-linenumalign

Anchor position for the line numbers with respect to the canvas. Must be one of left, center or right.

-linenumbg

Background color of the line numbers. This is the background color of the canvas itself.

-linenumfg

Foreground color of the line numbers. Done by adjusting the -fill option of a canvas text item.

-linenumfont

Font type of the line numbers. Done by adjusting the -font option of a canvas text item.

-linenumside

Specifies which side of the text widget to place the line numbers. Must be either left or right. Default is left.

WIDGET METHODS

As stated above, all methods should find their way to the proper module by the AUTOLOAD routine. The following widget-specific methods also exist.

$linenumtext->addbookmarks(<Line number list>)

Programmatically add bookmarks to each line number specified in the list passed. Note: Array references are not yet supported.

$linenumtext->deletebookmarks(<Line number list>)

Programmatically delete bookmarks at each line number specified in the list passed. Note: Array references are not yet supported.

$linenumtext->hidelinenum

Hide the linenumber widget. (i.e. gridForget)

$linenumtext->showlinenum

Show the linenumber widget. (i.e. grid)

$linenumtext->togglelinenum

Toggle the visibility of the linenumber widget.

$linenumtext->lineshowing

Returns a boolean value to indicate the visibility of the linenumber widget.

$linenumtext->lineupdate

Force line numbers to update.

NOTE: This method should not have to be called manually. This widget is designed to do the updates for you. However - I have provided this to allow the force the update just in case there are situations when it fails to do so. But I hope you would e-mail me if you come across any bugs.

CANVAS BINDINGS

<ButtonPress-1>

Set insert mark of text widget to the line number clicked.

<ButtonPress-2>

Toggle bookmark.

<ButtonPress-3>

Navigation menu.

TEXT-WIDGET BINDINGS

<F5>

Go to previous bookmark.

<F6>

Go to next bookmark.

ADVERTISED WIDGETS

The following widgets are advertised:

scrolled

The text or text-derived widget.

text

The text or text-derived widget. (Same as scrolled above)

frame

The frame containing the scrollbars and text widget (As per the Tk::Scrolled method).

yscrollbar

The scrollbar widget using for vertical scrolling.

xscrollbar

The Scrollbar widget using for horizontal scrolling.

corner

The frame in the corner between the vertical and horizontal scrollbars.

linenum

The canvas widget used for the line numbers.

BUGS

There will always be a line number on the first display line -- even if the text could actually be wrapped from a line which is off screen. I did this to ensure that at least one line number is shown at all times.

OTHER STUFF

  • By design - the text widget will have tags placed within it in order to support bookmarks next to the line numbers. You will see these tags if you use the dump method.

  • By design - a blank line cannot be bookmarked. I made a valor attempt to use marks instead of tags - to no avail. Tags are easy and will be deleted through user interaction; marks always stay.

WISH LIST

  • Allow selection of lines by interacting with the line number.

  • Allow user defined images for bookmarks.

  • Allow bookmarks to remain persistent so they are not lost on a save.

  • Allow bookmarking of blank lines.

  • How about someone building a full-fledged perl/Tk IDE now that we have line numbers and bookmarks !

SEE ALSO

Tk::Frame, Tk::Text, Tk::Scrolled, Tk::Canvas.

THANK YOU

Thanks go to the following people for their kind advice, suggestions and code samples.

Dean Arnold, Eric Hodges, Darin McBride, Brian McCauley, Brian McGonigle, Ala Qumsieh, Steve Schulze.

AUTHOR

Jack Dunnigan <goodcall1@hotmail.com>

Copyright (C) 2004. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Inspired by ctext.tcl written by George Peter Staplin.

See http://wiki.tcl.tk/4134.