SYNOPSIS:

use class::NumList;


DIRECTORY/FILE:

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


DESCRIPTION:

The NumList object is the core element of the numbering engines you can define.

It works together with the NumLabel objects which are kept in a sorted list (sorted by linenumber in the text widget) in the NumList object. The NumList objects does calculate the right numbering the NumLabels should show.

There are different kinds of NumLists used in e:doc:

(+) The NumList for paragraph numbering. [ $docform()->tagman()->par_num_list() ]

(+) The NumLists for numbering Images and Tables. [ $docform()->tagman()->img _num_list() and $docform()->tagman()->tbl_num_list() ]

(+) Later there will be multiple numlists (defined in 'edoc.obj') you can associate with embeded objects instead of the img_num_list and tbl_num_list. These will be kept in $docform()->tagman()->num_lists()

(+) Several NumLists for numbered lists and bullet lists kept in $docform()->tagman()->lists() =head1 STATUS:

Coding: 90% done

Documentation: up-do-date


ATTRIBUTES:

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

$self->{'do_number'} #if the associated NumLabels should be numbered

$self->{'max_number_depth'} #The maximum numbering depth of the list (Level 3 = '2.3.4')

$self->{'start_number_level'} #At which level the numbering should start

$self->{'tagman'} #A reference to the TagMan object the NumList belongs to (!!!CIRCULAR REFERENCE!!!)

$self->{'bullet_file'} #The filename of the bullet image file that should be used if the NumList shows bullets

...The properties show_bullet, show_number should move from the NumLabel object to the NumList object, because these attributes are valid for the whole list.

$self->{'bullet_img'} #A reference to the Photo widget that shows the bullet image (Only set if the list is used for a bullet list)

@{$self->{'list'}} #An reference to the sorted array which holds the NumLabel items that are added to this NumList in a sorted list


METHODS:


Class Methods:


Constructors:


new

my $object = NumList->new($start_number_level, $do_number, $max_number_depth, $tagman , $bullet_file);

This creates a new object of the class NumList and returns a reference to it.

FIXME: Here we have to check if the given bullet_file really exists an give an error message if it doesn't

Parameters:

(+) $start_number_level: At what level the numbering should start

(+) $do_number: If the numbering should be performed (To allow On/Of switching of the engines)

(+) $max_number_depth: How far (to what level) the numbering should work.

(+) $tagman: A reference to the TagMan object the NumList belongs to.

(+) $bullet_file: The filename of the bullets image file


Destructors:


DESTROY

The standard automatically called PERL destructor for objects. Unfortionatly it is called very late (when the whole application terminates.) This is due to the circular cross references between DocForm, TagMan, NumList etc. I will have to unlink them manually in the closing method of the document window.


Public data methods (=Get/Set methods):


tagman

$ref_tagman = $object->tagman(); #gets a reference to the TagMan object

$object ->tagman($ref_tagman); #sets a reference to the TagMan object


do_number

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

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


max_number_depth

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

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


start_number_level

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

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


bullet_file

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

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


bullet_img

$ref_photo = $object->bullet_img(); #gets a reference to the Photo widget that holds the bullet picture

$object ->bullet_img($ref_photo); #sets a reference to the Photo widget that holds the bullet picture


list

@list = $object->list(); #gets a reference to the sorted array of the NumLabels hold by this NumList (READONLY)


Other public methods:


clear

$object->clear();

Clears the list of NumLabels


add_numlabel

$object->add_numlabel($ref_numlabel, $do_not_sort);

Adds a NumLabel to the NumList.

All NumLabel objects are kept in a sorted list (sorted by linenumber inside of the text widget..sort later by col-index too for the case that some NumLabels have the same line number (only possible with Numlabels of EmbObj-derived widgets, not with PAR_STYLES and ENV_STYLES) To speed up the sorting, I use the always-divide-in-the-middle method which you can only use if you sort one new element into an already sorted list. To make things easier the last three iterations are done with a normal bubblesort.

Parameters:

(+) $ref_numlabel: A reference of the NumLabel to add

(+) $do_not_sort: If set to 1, the NumLabel is not sorted into the list, its just appended (For document opening time) Because of the sorting algorithm you can only use $do_not_sort=1 if you know that the added element belongs to the end of the list, because the sorting algorithm insists of an already sorted list to add new elements into. You can only know that you can append a new element at the end when you open a document from disk, because in the saved file the styles are kept sorted by their appearance in the document. Thats why the InOut::file_open() function is the only place where $do_not_sort is set to 1.


delete_NumLabel

$object->delete_NumLabel($ref_numlabel);

Remove the given NumLabel from the NumList.

Parameters:

(+) $ref_numlabel: A reference of the NumLabel to remove


renumber

$object->renumber();

Cause all NumLabels in the NumList to be renumbered.


Private methods:

nothing here yet.


KNOWN BUGS:


STILL MISSING: