NAME:

Widget: NumLabel


SYNOPSIS:

use class::NumLabel;


DIRECTORY/FILE:

The file NumLabel.pm is located in the subdirectory './class'


DESCRIPTION:

This is a widget derived from Tk::Label that gets embeded into the documents text widget in the DocForm object (=document window).

This NumLabel object is one item of the numbering engine (NumList.pm). Each NumLabel is added to ONE (never more) NumList and (in most cases) embeded into the text widget to show the numbering text (f. ex. ``3.1.1'') there. The NumLabels are menaged by their NumList and kept in a sorted list (sorted by the place they are embeded in the text widget).

If the NumLabel is assocaited with a EmbObj-derived object, it is not embeded into the text widget, so the position of the assocated EmbObj-derived object is taken instead of the NumLabels position.

Each numlabe has its ``level''-attribute which distincts f. ex. ``1'' from ``1.1''.

The NumLabel/NumList - engines are used to work for:

(+) Numbering paragraphs

(+) Numbering several kinds of EmbObj-derived objects (Tables, Images...)

(+) Numbering of ``Numbered lists'' (environments)

(+) Numbering of ``Bulletlists'' (environments) [Here the NumLabels do not show numberings, they just display the bullets].

This object is coded as an Perl/Tk widget, so it has no Constructor new, it has the standard Tk functions to initialise itself (Populate,ClassInit,...) The function Populate() is used like an constructor here.


STATUS:

Coding: 99% done

Documentation: up-to-date


ATTRIBUTES:

Do not set/read them directly, use the Get/Set methods instead.

$self->{'show_bullet'} #If set to 1 the NumLabel displays the bullet defined in $self->numlist()->bullet_img()

$self->{'show_number'} #If set to 1 the NumLabel shows the numbering

$self->{'text'} #The text to be shown (f. ex. ``Chapter 1:'')

$self->{'text_widget'} #Reference to the textwidget where the NumLabel is embeded

$self->{'numlist'} #A reference to the NumList the NumLabel belongs to

$self->{'pre_number_text'} #The text that should be shown before the number

$self->{'post_number_text'} #The text that should be shown after the number

$self->{'associated_tag'} #The name of the the NumLabel is associated with (PAR_STYLES or EMBOBJ or ENV_STYLES)

$self->{'window_tag'} #The name of the tag the NumLabel itself is tagged with in the text widget


METHODS:


Class Methods:


ClassInit($class, $parentwindow)

! Not called directly !

This ``constructor'' initialises a new object of the class NumLabel and calls ClassInit() of the Superclass.


Constructors:


Populate

$object = NumLabel(%options);

This ``constructor'' sets the options of the new object of the class NumLabel.

The binding of events and the creation of the associated Baloonhelp is done here too.

The keys/values in %options:

(+) '-show_bullet' => If set to 1 the NumLabel displays the bullet defined in $self->numlist()->bullet_img()

(+) '-show_number' => If set to 1 the NumLabel shows the numbering

(+) '-text_widget' => Reference to the textwidget where the NumLabel is embeded

(+) '-numlist' => A reference to the NumList the NumLabel belongs to

(+) '-pre_number_text' => The text that should be shown before the number

(+) '-post_number_text' => The text that should be shown after the number

(+) '-associated_tag' => The name of the the NumLabel is associated with (PAR_STYLES or EMBOBJ or ENV_STYLES)

(+) '-window_tag' => The name of the tag the NumLabel itself is tagged with in the text widget


on_create

$object->on_create($do_not_sort);

This method has to be called after the NumLabel has been correctly created, embeded into the textwidget and tagged with his own tag. Afterwards the 'window_tag' attribute should be set to this tagname by using the method '$obj->window_tag($tagname)'. After that is done, you have to call this '$obj->on_create()' method to fully initialise the NumLabel.

This is VERY IMPORTANT because this 'on_create' method performs the registration of the NumLabel to its NumList and can only be done AFTER the surrounding tag of the NumLabel is set correctly.

Parameters:

(+) $do_not_sort: If set to 1, the NumLabel is not automatically sorted into the NumList (for document opening where many NumLabels are created. Its enough to sort the list once when all NumLabels are created).


Destructors:


DESTROY;

The standard automatically called PERL destructor for objects.


do_detstroy

$object->do_detsroy();

This ``destructor'' method is binded to the ``<DESTROY>'' event and should be performed whenever the element is destroyed. It should not be called directly.


Public data methods (=Get/Set methods):


text

$text = $object->text(); #gets the text that should be displayed on the NumLabel

$object->text($text); #sets the text that should be displayed on the NumLabel


ref_text

$ref_text = $object->ref_text(); #gets a reference to the text that should be displayed on the NumLabel (!READ-ONLY!)


show_number

$show_number = $object->show_number(); #gets the value of the 'show_number' attribute

$object->show_number($show_number); #sets the value of the 'show_number' attribute


show_bullet

$show_bullet = $object->show_bullet(); #gets the value of the 'show_bullet' attribute

$object->show_bullet($show_bullet); #sets the value of the 'show_bullet' attribute


text_widget

$ref_text_widget = $object->text_widget(); #gets a referenece to the Text widget the NumLabel is embeded in

$object->text_widget($ref_text_widget); #sets a referenece to the Text widget the NumLabel is embeded in


window_tag

$tag_name = $object->window_tag(); #gets the name of the tag the NumLabel is tagged with

$object->window_tag($tag_name); #sets the name of the tag the NumLabel is tagged with


associated_tag

$tag_name = $object->associated_tag(); #gets the name of the tag the NumLabel is associated with

$object->associated_tag($tag_name); #sets the name of the tag the NumLabel is associated with


pre_number_text

$pre_number_text = $object->pre_number_text(); #gets the value of the 'pre_number_text' attribute

$object->pre_number_text($pre_number_text); #sets the value of the 'pre_number_text' attribute


post_number_text

$post_number_text = $object->post_number_text(); #gets the value of the 'post_number_text' attribute

$object->post_number_text($post_number_text); #sets the value of the 'post_number_text' attribute


level

$level = $object->level(); #gets the value of the 'level' attribute

$object->level($level); #sets the value of the 'level' attribute


numlist

$ref_numlist = $object->numlist(); #gets a reference to the associated NumList object

$object->numlist($ref_numlist); #sets a reference to the associated NumList object


Other public methods:


get_current_line

$line = $object->get_current_line();

This returns the line number where the NumLabel widget is situated inside of the text widget it belongs to.


renumber

$object->renumber();

Cause all NumLabels in the associated NumList to be renumbered.


Private methods:

nothing here yet.


KNOWN BUGS:


STILL MISSING: