Object: TagMan
use class::TagMan;
The file TagMan.pm is located in the subdirectory './class'
The TagMan object encapsulates all the functionality that deals with the different text tags in your document. Each DocForm object (DocForm.pm) has one associated TagMan object with it. The DocForm object contains the text of your document (inside of the Text widget) and the TagMan object contains all of the formatting information.
First I planned to create a new Text widget which inherits from the original Text widget and adds the functionality of the TagMan object, but there are several reasons to keep the stuff in 2 different objects.The major reason is that this design allows to add something like a document/view concept later.
The TagMan object with all its asociated objects could be the document (only the pure text info is missing there) and the DocForm object could act as a view.But this is a different story...
There are also other object associated with the TagMan object:
(+)Several NumList objects (NumList.pm), which allow the numbering of paragraphs, images and tables
(+)Always 1 NumList object per 'Numbered list'-environments that are placed in the document.
(+) Always 1 Object of a class derived from EmbObj (EmbObj.pm) per embeded object in your document.
All tags are created in the private method called '_before_add_tag(...)' and completed in the method '_after_add_tag(...)' which ensures that the naming of the tags follows a concrete scheme. Tags are named as followed:
'<STYLEGROUP><STYLENAME><DATA>:ID'
... what means that if you have an environment style (<END_STYLES>) with the name Itemize (<Itemize>) defined in the file <CODE>edoc.int</CODE>, one tag of this style could have the name '<ENV_STYLES><Itemize><some info>:12', another one could be named '<ENV_STYLES><Itemize>:54'. The paragraph style 'Chapter' could be '<PAR_STYLES><Chapter><>:2' and a table object (which belongs to the style group <EMBOBJ>) could be named <EMBOBJ><TBLOBJ><2||aaaa||bbbb>:34. All this stuff is very important because the style group and the style could be easily extracted from the name and the id ensures that every tag has a unique name. This is necessary because each tag can have multiple arguments and argument values with it.
Coding: 80% done
Documentation: up-do-date
Do not set/read them directly, use the Get/Set methods instead.
$self->{'tag_counter'} = $start_value; #An internal counter for tagnumbering
$self->{'docform'} = $ref_docform; #Reference to the corresponding DocForm object
$self->{'tags'}->{'names'} = $ref_namelist; #Reference to an Array of all stored tagnames
$self->{'tags'}->{$tagname}->{'positions'} = $number_of_positions; #How many seperate positions of a tag are stored (
$self->{'tags'}->{$tagname}->{$posnumber}->{'start_index'} = $index1; #Start index of a Position (The first position has number 0)
$self->{'tags'}->{$tagname}->{$posnumber}->{'end_index'} = $index2; #End index of a Position (The first position has number 0)
$self->{'args'}->{$tagname}->{'arg_number'} = $number_of_arguments; #How many arguments are defined to this tags style
$self->{'args'}->{$tagname}->{$argnumber}->{'name'} = $argumet_name; #Name of the argument (The first argument has number 0)
$self->{'args'}->{$tagname}->{$argnumber}->{'type'} =
$argumet_type; #Type of the argument. Possible values: TEXT, NUMBER,
MULTILINE, OPTION([item1,
item2, ...]),
REFERENCE([$stylegroup1.$stlye1.tag_name,
$stylegroup1.$stlye1.property_value(property_name)], ...), BOOL
$self->{'args'}->{$tagname}->{$argnumber}->{'value'} = $argumet_value; #The current value of the argument, if the arguments type is 'MULTILINE' then this value is a reference to an anonymous array that stores the lines
$self->{'objects'}->{$tagname} = ref_object; #Reference to an embeded object that is derived from the class 'EmbObj.pm'
$self->{'env_numlists'}->{$tagname} = ref_numlist; #Reference to an NumList object that manages the NumLabels of an environment style that is a numbered list or a bullet list.
$self->{'doc_numlists'}->{$name} = ref_numlist; #Reference to an NumList objects that are read from the file 'edoc.int' and used for paragraph and embed-object numbering
my $object
= TagMan->new($ref_docform);
This creates a new object of the class TagMan and returns a reference to it.
Parameters:
(+) $ref_docform: A reference to the DocForm object this new TagMan object belongs to. It initialises the internal attributes and creates the NumList object that belong to the new TagMan object.
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.
$ref_docform
= $object->docform(); #gets a reference to the
corresponding DocForm object
$object
->docform($ref_docform); #sets a reference to the
corresponding DocForm object
$ref_docform_wnd
= $object->docform_wnd();
Gets a reference to the Toplevel of the corresponding DocForm object
$ref_docform_ui
= $object->docform_ui();
Gets a reference to the {'ui'}-branch of the corresponding DocForm object.
$ref_docform_doctext
= $object->docform_doctext();
Gets a reference to the text widget inside of the corresponding DocForm object.
$doc_args_number
= $object->doc_args_number(); #gets the
number of document arguments
$object->doc_args_number($doc_args_number); #sets the number of document arguments
$object->set_doc_arg_value($index, $value);
Parameter:
(+) $index
: The index of the argument
(+) $value
: The value to be set
$object->refresh_doc_args();
Refreshes the Arguments that belong to that document_style
$object->init_num_lists();
$object
-> init_num_lists();
Passes the numbering properties of the current document into the right properties of the NumList objects and perform a renumbering of all already existing NumLabels if necessary
$object->create_num_lists();
$object
-> Create_num_lists();
Creates all NumLists that are defined in 'edoc.int' with the default parameters
$object->read_from_widget($source_text_widget);
Read all tags from the source text widget into the $self->{'tags'} branch.
$object->copy_text_widget($source_text_widget, $target_source_widget, $index1, $index2);
Copies all text info and tag info from one text widget into another one.
Parameters:
(+) $source_widget: A Reference to the text widget to copy
(+) $target_widget: A Reference to the text widget to copy into
(+) $index1, $index2: The start and the end index of the range to copy (Both should be '-1' if the whole widget should be copied)
@taglist
=
$object->sort_tags_by_stylegroup($ref_text_widget);
Sorts all tags in the following order
CHAR_SYTYLES,COMMANDS, EMBOBJ,ENV_STYLES, PAR_STYLES, CHAR_SYTYLES
Parameters:
(+) $ref_text_widget: A reference to the textwidget that holds the tags to sort
$tagname
= $object->add_par_tag($style, $index1, $index2,
$do_not_sort, $allow_add_tagdoc);
Adds a <PAR_STYLES> tag to the textwidget and the $self->{'tags'}
branch. All defined arguments are also initialised in the
$self->{'args'} branch. If this paragraph style is numbered, there will
be a NumLabel created automatically and added to the NumList object this
style is associated with. This NumLabel will be automatically sorted and
numbered if $do_not_sort
is unequal to 1.
The tags and arguments are created via the private methods '_before_add_tag' and '_after_add_tag'.
The method returns the full tagname of the newly created tag.
Arguments:
(+) $stlye: The name of the style to add
(+) $index1, $index2: The start index and the end index of the tag range
(+) $do_not_sort: If this flag is set to 1 the possibly automatically created NumLabel should not be sorted and renumbered to save time on document opening when many tags are created and one renumbering at the end is enough. This is why $self->renumber() has to be called at the end of those 'file_open' functions.
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
$tagname
= $object->add_env_tag($style, $index1, $index2,
$allow_add_tagdoc);
Adds a <ENV_STYLES> tag to the textwidget and the $self->{'tags'} branch. All defined arguments are also initialised in the $self->{'args'} branch. If this environment style is a sort of list, there will be created a seperate NumList object to handle this list and a reference to it will be stored in $self->{'env_numlists'}->{'tagname'}. There will be a NumLabels created automatically and added to the NumList object stored in $self->{'env_numlists'}->{'tagname'}.
The tags and arguments are created via the private method '_before_add_tag' and '_after_add_tag'.
The method returns the full tagname of the newly created tag.
Arguments:
(+) $stlye: The name of the style to add
(+) $index1, $index2: The start index and the end index of the tag range
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
$tagname
= $object->add_char_tag($style, $index1, $index2,
$allow_add_tagdoc);
Adds a <CHAR_STYLES> tag to the textwidget and the $self->{'tags'} branch. All defined arguments are also initialised in the $self->{'args'} branch.
The tags and arguments are created via the private method '_before_add_tag' and '_after_add_tag'.
The method returns the full tagname of the newly created tag.
Arguments:
(+) $stlye: The name of the style to add
(+) $index1, $index2: The start index and the end index of the tag range
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
$tagname
= $object->add_command_tag($command, $index1);
Adds a <COMMANDS> tag to the textwidget.
The tags and arguments are created in this method (not in '_before_add_tag').
The method returns the full tagname of the newly created tag.
The 'command' is an object of the class 'ComObj.pm' which is an derived Widget and embeded into the text widget. This widget uses the space of 1 character in the text widget and this space is tagged with the created tag in this method.
As noted in the description of '_before_add_tag', the process is quite different to the process used for text tags.
Arguments:
(+) $command: The name of the comand style to add
(+) $index1: The start index of the embeded ComObj object
$tagname
= $object->add_embobj_tag($classname, $index1,
$data, $do_not_sort_numlabel);
Adds a <EMBOBJ> tag to the textwidget.
The tags and arguments are created in this method (not in '_before_add_tag').
The method returns the full tagname of the newly created tag.
The 'EMBOBJ' is an object derived from the class 'EmbObj.pm' which is an derived Widget and embeded into the text widget. This widget uses the space of 1 character in the text widget and this space is tagged with the created tag in this method.
As noted in the description of '_before_add_tag', the process is quite different to the process used for text tags.
Arguments:
(+) $classname: The classname of the EmbObj-derived widget to embed. there has to be a file with the name {classname}.pm in the ./class-directory!
(+) $data
: The data that is needed for the EmbObj, is '' if
created from scratch
(+) $index1: The start index of the embeded EmbObj object
(+) $do_not_sort_numlabel: Prevent renumbering of the associated numlist at loading time when set to 1
$object->delete_par_tags_in_area($index1, $index2);
Removes all <PAR_STYLES> tag from the textwidget and the $self->{'tags'} branch. All defined arguments are also deleted in the $self->{'args'} branch.
The tags and arguments are created via the private method '_delete_tag'.
Arguments:
(+) $index1, $index2: The start index and the end index of the tag range to be removed
$object->delete_env_tags_in_area($index1, $index2);
Removes all <ENV_STYLES> tag from the textwidget and the $self->{'tags'} branch. All defined arguments are also deleted in the $self->{'args'} branch.
The tags and arguments are created via the private method '_delete_tag'.
Arguments:
(+) $index1, $index2: The start index and the end index of the tag range to be removed
$object->delete_char_tags_in_area($index1, $index2);
Removes all <CHAR_STYLES> tag from the textwidget and the $self->{'tags'} branch. All defined arguments are also deleted in the $self->{'args'} branch.
The tags and arguments are created via the private method '_delete_tag'.
Arguments:
(+) $index1, $index2: The start index and the end index of the tag range to be removed
$object->toggle_tagdoctor_tags();
Switches the tag-doctor tags on/off in the whole document
$object->insert_tag_doctor_objects($tagname, $stylegroup, $style);
Frame the tag with 2 TagDoc objects.
Parameters:
(+) $tagname: The name of the tag to border
(+) $stylegroup: The stylegroup name of the tag (if set to undef -> extracted from the tagname)
(+) $style: The style name of the tag (if set to undef -> extracted from the tagname)
$object->remove_tag_doctor_tags($tagname, $stylegroup, $style);
Remove the TagDoc-Objects from aspecific tag
Parameters:
(+) $tagname: The name of the tag to border
(+) $stylegroup: The stylegroup name of the tag (if set to undef -> extracted from the tagname)
(+) $style: The style name of the tag (if set to undef -> extracted from the tagname)
$object->get_num_list($stylegroup, $style);
Return a reference to the num_list that is correlated with the given style, or undef if there is none.
Parameters:
(+) $stylegroup: The stylegroup name
(+) $style: The style name
This methods are for the objects internal use only, do not call them from outside the object.
$value
= $object->_tag_counter(); #gets the actual value of
the tag counter
$object
->_tag_counter($value); #sets the actual value of
the tag counter (DO NOT USE, use _inc_tag_counter method for increasing it)
$new_value
= $object
->_inc_tag_counter();
#increases the actual value of the tag counter by 1
$object->_clear_tags();
Clears all stored data in the $self->{'tags'} branch.
$object->_build_list_items($list_tagname, $index1, $index2);
This private method creates all needed NumLabel objects for building up a numbered or a bullet list. After that the corresponding NumList object is renumbered.
Unfortionatly it cannot handle nested lists yet.
Arguments:
(+) $list_tagname: The tagname of the list to build up the items for
(+) $index1, $index2: The start index and the end index of the tag range, if both are set to -1, it means that the whole range of the tag is to be (re)build.
$object->_remove_list_items($list_tagname, $index1, $index2);
This private method removes all existing NumLabel objects for building up a numbered or a bullet list.
Unfortionatly it cannot handle nested lists yet.
Arguments:
(+) $list_tagname: The tagname of the list to build up the items for
(+) $index1, $index2: The start index and the end index of the tag range, if both are set to -1, it means that the whole range of the tag is to be (re)build.
%options
=
$object->_build_display_options_hash($stylegroup, $style);
Retrieves the options for displaying from the hash $main::internal and caches them in a branch $main::internal->{STYLEGROUP_NAME}->{STYLE_NAME}->{DISPLAY_OPTIONS}
The functions returns the options for configuring the tag (CHAR_STYLES, PAR_STYLES, ENV_STYLES) or the widget (COMMANDS, EMB_OBJ).
Parameters:
(+) $stylegroup: The name of the stylegroup
(+) $style: The name of the style
$tagnem
= $object->_before_add_tag($stylegroup, $style,
$index1, $index2, $do_not_sort_par_numlabel);
This is the main function where tags in the text widget are created. This ensures the correct registration of the tags.
The method '_after_add_tag' is called after the calling method of '_before_add_tag' has completed all things it does with this newly created tag to finnish it up.
For PAR_STYLE tags the NumLabels are created and for ENV_STYLE tags that represent lists are the item buildup methods called.
The method returns the full tagname of the newly created tag.
Arguments:
(+) $stylegroup: The style group the tag belongs to. (PAR_STYLES, ENV_STYLES, CHAR_STYLES, COMMANDS, EMB_OBJ)
(+) $stlye: The name of the style to add
(+) $index1, $index2: The start index and the end index of the tag range
(+) $do_not_sort_par_numlabel: If this flag is set to 1 the possibly automatically created NumLabel should not be sorted and renumbered to save time on document opening when many tags are created and one renumbering at the end is enough. This is why $self->renumber() has to be called at the end of those 'file_open' functions. (Is only working with the stylegroup 'PAR_STYLES')
$object->_after_add_tag($tagname, $stylegroup, $style, $allow_add_tagdoc);
This is called after all additional stuff with the tag (adding of NumLabels, PreText, PostText, etc...) is done and the definite range of characters is tagged with the tag.
Arguments:
(+) $tagname: The name of the tag where it happened
(+) $stylegroup: The stylegroup of the tag, if undef -> extracted from the tagname
(+) $style: The style of the tag, if undef -> extracted from the tagname
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
$object->_return_pressed($tagname);
This is a callback that is automatically bind to the hitting of the 'Enter' key inside of a numbered list or a bullet list. It calls the _build_list_items method to ensure to correct renumbering or setting of bullets.
Arguments:
(+) $tagname: The name of the tag where it happened
$object->_delete_tag($tagname, $index1, $index2);
Removes the tag with the given tagname from the area mentioned by
$index1
and $index2.
If the whole tag was removed, the arguments are deleted too from the $self->{'args'} branch using the method _delete_arguments.
Arguments:
(+) $tagname: The name of the tag to remove
(+) $index1, $index2: The start index and the end index of the removal range (If both are set to -1, the whole tagrange is removed. For <PAR_SYTLES> the indexes have to be set to -1 because they can only be removed as a whole.
$object->_delete_arguments($tagname);
Deletes the stored arguments in the $self->{'args'} branch for the given tag.
Arguments:
(+) $tagname: The name of the tag which arguments should be deleted
$arg_number
= $object->_add_arguments($tagname,
$stylegroup, $style);
Initalises the arguments in the $self->{'args'} branch for the given tagname. The stylegroup and stylename have to be known to retrieve the argument information from the data out of the 'edoc.int' file.
The method returns the number of initialised arguments.
Arguments:
(+) $tagname: The name of the tag which arguments should be initialised
(+) $stylegroup: The style group the tag belongs to
(+) $style: The style the tag belongs to
$object->_do_tag_click($tagname)
Callback for handling the mouse click on a tag of a style that has arguments defined in 'edoc.int'.
Arguments:
(+) $tagname: The name of the tag which arguments should be shown
$object
->get_par_styles_tags(); #Returns a list of all
paragraph styles <PAR_STYLES> that are in the document
$object
->get_env_sytles_tags(); #Returns a list of all
environment styles <ENV_STYLES> that are in the document
$object
->get_char_styles_tags(); #Returns a list of all
character styles <CHAR_STYLES> that are in the document
$object
->get_command_format_tags(); #Returns a list of all
commands <COMMANDS> that are in the document
$object
->get_embobj_tags(); #Returns a list of all embeded
objects <EMBOBJ> that are in the document
Get/Set-methods for the not-simple attributes that are sub-hashes in the $self-hash:
(+) The $self->{'tags'} - branch
(+) The $self->{'args'} - branch
(+) The $self->{'env_numlists'} - branch
(+) The $self->{'doc_numlists'} - branch
(+) The $self->{'objects'} - branch