Object: DocForm
use class::DocForm;
The file DocForm.pm is located in the subdirectory './class'
The object DocForm encapsulates the document window. It is now coded as a normal non-visual Perl class that creates an user interface in the $self->{'ui'} branch. It might be more clever to (later) transform it into a Toplevel-derived widget.
This form class is derived form the class 'BaseForm' that builds up the basic GUI elements and does form-registrations and deregistartaions in the global @main::forms array. For viewing this inherited functionality see the files '/class/BaseForm.pm' and '/class/ui/uiBaseForm.pm'.
Now the GUI buildup functions are stored in the package ``./ui/uiDocForm.pm''.
Coding: 80% done
Documentation: up-do-date
Do not set/read them directly, use the Get/Set methods instead.
$self->{'ui'}->{'doctext'} #Reference to the text widget that contains the documents text
$self->{'ui'}->{'outline'} #Reference to the tree widget that contains the documents outline view
$self->{'ui'}->{'top'} #Reference to the toplevel of the document window
$self->{'tagman'} #Reference to the TagMan object this Docform is working with
$self->{'app_window'} #Reference to the main application window
$self->{'backend'} #Reference to the anonymous $backend
hash. This is an anonymous configuration hash, that holds the export
definition of the current backend. Each DocForm object has his own one,
this allows several DocForm objects to export the same document into
different backends.
$self->{'document'}->{'current_doc_style'} # The current document
style name(=
stylegroup 'DOC_STYLES') of the document.
$self->{'document'}->{'current_par_style'} # The current paragraph style name (= stylegroup 'PAR_STYLES').
$self->{'document'}->{'current_char_style'} # The current character style name (= stylegroup 'CHAR_STYLES').
$self->{'document'}->{'current_env_style'} # The current environment style name (= stylegroup 'ENV_STYLES').
$self->{'document'}->{'current_command'} # The current command name (= stylegroup 'COMMANDS').
$self->{'document'}->{'current_backend_name'} # The current backends name (got fromt the *.out files)
$self->{'document'}->{'search_history'} #A reference to an array that holds the search history of this document
$self->{'document'}->{'replace_history'} #A reference to an array that holds the replace history of this document
$self->{'backend_names'}; #Reference to an array of all names of the available backends (*.out files)
$self->{'no_style_text'} ; #What text should appear if there is no style selected in the Optionmenue (Standard is ``-none-'')
$self->{'doc_styles'}; #Reference to an array of all available document styles (DOC_STYLES)
$self->{'par_styles'}; #Reference to an array of all available paragraph styles (PAR_STYLES)
$self->{'char_styles'}; #Reference to an array of all available character styles (CHAR_STYLES)
$self->{'env_styles'}; #Reference to an array of all available environment styles (ENV_STYLES)
$self->{'commands'}; #Reference to an array of all available commands (COMMANDS)
$self->{'search_dialog'}; #A reference to the search and replace dialog
$self->{'doc_parts'}; #A reference to an hash of arrays. Each hash-key represents the name of a document-part, each array contains the parts content in the clipboard format
$self->{'_tag_doctor_on'}; #The flag if the TAG-DOCTOR features is turned on or off (CAn have the values 'TAG-DOCTOR:ON' or 'TAG-DOCTOR:OFF', just for internal use, use Get/Set-method ``&tag_doctot_on()'' instead
$self->{'_full_screen_mode'}; #The flag if the FULL SCREEN MODE features is turned on or off (CAn have the values 'TAG-DOCTOR:ON' or 'TAG-DOCTOR:OFF', just for internal use, use Get/Set-method ``&full_screen_mode()'' instead
$object
= DocForm->new($prj_form);
This constructor creates a new object of the class DocForm.
Parameters:
(+) $prj_form: a reference to the project form that created this document form
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.
$object
->do_destroy();
This destructor is binded to the protocol-message WM_DELETE_WINDOW and performs the 'unsaved changes'-check, destroys the TopLevel manually and then destroys the DocForm object manually too.
$ref_doctext
= $object->doctext(); #gets a reference to the
text widget that contains the document
$object
->doctext($ref_textwidget); #sets a reference to
the text widget that contains the document
$ref_prj_form
= $object->prjform(); #gets a reference to
the project form that created this document form
$object
->prjform($ref_prj_form); #sets a reference to the
project form that created this document form
$ref_app_window
= $object->app_window(); #gets a reference
to the main application window
$object
->doctext($ref_app_window); #sets a reference to
the main application window
$ref_treewidget
= $object->outline(); #gets a reference to
the tree widget that contains the documents outline view
$object->outline($ref_treewidget); #sets a reference to the tree widget that contains the documents outline view
$ref_tagman
= $object->tagman(); #gets a reference to the
TagMan object this Docform is working with
$object
->tagman($ref_tagman): #sets a reference to the
TagMan object this Docform is working with
$ref_backend
= $object->backend(); #gets a reference to the
anonymous $backend
hash
$object
->backend($ref_backend); #sets a reference to the
anonymous $backend
hash
This is an anonymous configuration hash, that holds the export definition of the current backend. Each DocForm object has his own one, this allows several DocForm objects to export the same document into different backends.
$doc_style_name
= $object->current_doc_style(); #gets the
current document style name (= stylegroup 'DOC_STYLES')
$object->current_doc_style($doc_style_name); #sets the current document style name (= stylegroup 'DOC_STYLES')
$style_name
= $object->current_par_style(); #gets the
current paragraph style name (= stylegroup 'PAR_STYLES')
$object->current_par_style($style_name); #sets the paragraph style name (= stylegroup 'PAR_STYLES')
$style_name
= $object->current_env_style(); #gets the
current environment style name (= stylegroup 'ENV_STYLES')
$object->current_env_style($style_name); #sets the current environment style name (= stylegroup 'ENV_STYLES')
$style_name
= $object->current_char_style(); #gets the
current character style name (= stylegroup 'CHAR_STYLES')
$object->current_char_style($style_name); #sets the current character style name (= stylegroup 'CHAR_STYLES')
$command_name
= $object->current_command(); #gets the
current command name (= stylegroup 'COMMANDS')
$object->current_command($command_name); #sets the current command name (= stylegroup 'COMMANDS')
$current_backend_name
= $object->current_backend_name();
#gets the current backends name
$object->current_backend_name($current_backend_name); #sets the current backends name
$ref_doc_style_name
= $object->ref_current_doc_style();
#returns a reference to the current document style name (= stylegroup
'DOC_STYLES') (for use with Tk widgets that need a reference, READONLY)
$ref_style_name
= $object->ref_current_par_style();
#returns a reference to the current paragraph style name (= stylegroup
'PAR_STYLES') (for use with Tk widgets that need a reference, READONLY)
$ref_style_name
= $object->current_env_style(); #returns a
reference to the current environment style name (= stylegroup 'ENV_STYLES')
(for use with Tk widgets that need a reference, READONLY)
$ref_style_name
= $object->current_char_style(); #returns a
reference to the current character style name (= stylegroup 'CHAR_STYLES')
(for use with Tk widgets that need a reference, READONLY)
$ref_command_name
= $object->current_command(); #returns a
reference to the current command name (= stylegroup 'COMMANDS') (for use
with Tk widgets that need a reference, READONLY)
$ref_current_backend_name
=
$object->ref_current_backend_name(); #returns a reference to the current
backends name. (for use with Tk widgets that need a reference, READONLY)
$text
= $object->no_style_text(); #gets a reference to the
text that shoul appear in the optionmenu when no style is selected
$object
->no_style_text($text); #sets a reference to the
text that shoul appear in the optionmenu when no style is selected
$ref_doc_styles_array
= $object->doc_styles(); #gets a
reference to the list (array) of all available document styles
$object->doc_styles($ref_doc_styles_array); #sets a reference to the list (array) of all available document styles
$ref_par_styles_array
= $object->par_styles(); #gets a
reference to the list (array) of all available paragraph styles
$object->par_styles($ref_par_styles_array); #sets a reference to the list (array) of all available paragraph styles
$ref_env_styles_array
= $object->env_styles(); #gets a
reference to the list (array) of all available environment styles
$object->env_styles($ref_env_styles_array); #sets a reference to the list (array) of all available environment styles
$ref_char_styles_array
= $object->char_styles(); #gets a
reference to the list (array) of all available character styles
$object->char_styles($ref_char_styles_array); #sets a reference to the list (array) of all available character styles
$ref_commands_array
= $object->commands(); #gets a
reference to the list (array) of all available commands
$object->commands($ref_commands_array); #sets a reference to the list (array) of all available commands
$ref_backend_names_array
= $object->backend_names(); #gets
a reference to the list (array) of all available document styles
$object->backend_names($ref_backend_names_array); #sets a reference to the list (array) of all available document styles
$ref_doc_styles_array
= $object->ref_doc_styles(); #gets a
reference to the list (array) of all available document styles
$ref_par_styles_array
= $object->ref_par_styles(); #gets a
reference to the list (array) of all available paragraph styles
$ref_env_styles_array
= $object->ref_env_styles(); #gets a
reference to the list (array) of all available environment styles
$ref_char_styles_array
= $object->ref_char_styles(); #gets
a reference to the list (array) of all available character styles
$ref_commands_array
= $object->ref_commands(); #gets a
reference to the list (array) of all available commands
$ref_root
= $object->doc_parts_root(); #gets a reference to
the root of the hash of arrays that holds the parts
@doc_parts_names
= $object->doc_parts_names(); #gets an
array containing the names of all parts in this document (READONLY)
$ref_content
= $object->ref_doc_part( $name
);
#gets a reference to an array containing the part in clipboard-format
$object->ref_doc_part( $name, $ref_content
); #stores a
reference to an array containing the part in clipboard-format
Returns undef, if the given part doesn't exist.
Parameters:
(+) $name: The name of the part (has to be an unique string)
(+) $ref_content: A reference to an array holding the content of a part in clipboard format
$ref_backend_names_array
= $object->ref_backend_names();
#gets a reference to the list (array) of all available document styles
$flag
= $object->tag_doctor_on(); #Gets the State of the
Tagdoctor
$object->tag_doctor_on($flag); #Sets the state of the Tagdoctor
Checks if the TagDoctor feature is turned on.
Returns 0 if no and 1 if yes.
$flag
= $object->full_screen_mode(); #Gets the State of the
full screen mode
$object->full_screen_mode($flag); #Sets the state of the full screen mode
Checks if the Full_SCREEN_MODE feature is turned on.
Returns 0 if no and 1 if yes.
$ref_dialog
= $object->search_dialog(); #gets an reference
to the search dialog if it is already created
$object->search_dialog($ref_dialog); #sets an reference to the search dialog
$ref_array
= $object->ref_search_history(); #gets a
reference to an array that holds the search history
$object->ref_search_history($ref_array); #sets a reference to an array that holds the search history
$ref_array
= $object->ref_replace_history(); #gets a
reference to an array that holds the replace history
$object->ref_replace_history($ref_array); #sets a reference to an array that holds the replace history
$object->document_exit();
Exit the DocForm.
$object->build_docstyle_list();
Builds an sorted array of all (visible = non-abstract) document styles (DOC_STYLES) and writes it into the ``doc_styles()'' attribute.
$object->build_backend_list();
Builds an sorted array of all available backends. This means all *.out files that exist.
$object->file_new();
Resets the DocForm object for starting a new document. This function destroys the whole Text widget and creates a new one, which is significantly faster then deleting the old one. It does the same with the corresponding ``TagMan'' object.
$object->file_open_ascii([$filename]);
Calls InOut::file_open_ascii($self, [$filename]), which opens a normal unformatted text file in the DocForm object.
Parameters:
(+) $filename: OPTIONAL, if this is set to undef or not set, the filename is queried by a FileOpen dialog
$object->file_open([$filename]);
Calls InOut::file_open($self, [$filename]), which opens an e:doc document in the DocForm object.
Parameters:
(+) $filename: OPTIONAL, if this is set to undef or not set, the filename is queried by a FileOpen dialog
$object->file_save_as([$filename]);
Calls InOut::file_save_as($self [, $filename]), which queries for a filename (if not passed here) and saves an e:doc document.
Parameters:
(+) $filename: The filename to be saved (OPTIONAL)
$object->file_save_as_template([$filename]);
Save the actual document into a new template stored in the template-directory defined in 'edoc.cfg'.
Queries for a filename (if not passed here) and saves an e:doc document by calling InOut::file_save($self, $filename);
Parameters:
(+) $filename: The filename to be saved (OPTIONAL)
$object->file_save([$filename]);
Calls InOut::file_save($self, [$filename]), which saves an e:doc document .
Parameters:
(+) $filename: OPTIONAL, if this is set to undef or not set, the filename is queried by a FileSave dialog
$object->export_to_backend( [$edc_filename] );
Calls InOut::export_to_backend($self, $edc_filename), which converts the e:doc document (edc file) into the backend format
Parameters:
(+) $edc_filename: The name of the e:doc documents file (if not given (undef), the current filename of the document is taken)
$object->par_style_changed($style, $index1, $index2, $renumber, $do_not_sort, $allow_add_tagdoc, $do_check_line);
This method is called whenever a part of the document has to be formatted as a different paragraph style (PAR_STYLE). NOTE: a paragraph style can only be applied to one whole line, so if only a fraction of a line is selected, the formatting still covers the whole line. There could only be one paragraph style in one line, so an existing paragraph style is automatically removed.
This method is called as an callback from the OptionMenu widget that sets the paragraph styles and from the InOut.pm package for opening a document from the disk.
This method calls the corresponding ``TagMan'' objects ``add_par_tag'' method.
The method returns the name of the newly created paragraph style.
Parameters:
(+) $style: The name of the style to be applied to the selected line.
(+) $index1, $index2: The index in the Text widget of the line that should be formatted. If the current cursor selection should be used, the values of these two parameters should be -1.
(+) $renumber: If this flag is set, the whole NumList this style belongs to gets renumbered. This is necessary if the paragraph style is set by user interaction to keep the paragraph numbering right, but if you open a whole document it is enough to renumber after all paragraph styles are set (TIME).
(+) $do_not_sort: To allow a correct paragraph numbering the automatically created NumLabels are kept in a sorted list in the NumList object. This sorting takes time and again its not necessary to do this after each paragraph style when you open a document from disk. Also here it is enough to sort after all paragraphs are read in.
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
(+) $do_check_line: If set to 0 or undef, do not check the line for previous PAR_STYLES tags (File_open and Paste).
$object->env_style_changed($style, $index1, $index2, $allow_add_tagdoc, $do_check_area);
This method is called whenever a part of the document has to be formatted as a different environment style (ENV_STYLE). NOTE: a environment style can only be applied to whole lines, so if only a fraction of a line is selected, the formatting still covers the whole lines.
This method is called as an callback from the OptionMenu widget that sets the environment styles and from the InOut.pm package for opening a document from the disk.
This method calls the corresponding ``TagMan'' objects ``add_env_tag'' method.
The method returns the name of the newly created environment style.
Parameters:
(+) $style: The name of the style to be applied to the selected
line(s).
(+) $index1, $index2: The index in the Text widget of the line that should be formatted. If the current cursor selection should be used, the values of these two parameters should be -1.
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
(+) $do_check_area: If set to 0 then do not check area for previous ENV_STYLES tags (File_open and Paste)
$object->char_style_changed($style, $index1, $index2, $allow_add_tagdoc);
This method is called whenever a part of the document has to be formatted as a different character style (CHAR_STYLE).
This method is called as an callback from the OptionMenu widget that sets the character styles and from the InOut.pm package for opening a document from the disk.
This method calls the corresponding ``TagMan'' objects ``add_char_tag'' method.
The method returns the name of the newly created character style.
Parameters:
(+) $style: The name of the style to be applied to the selected text.
(+) $index1, $index2: The index in the Text widget of the line that should be formatted. If the current cursor selection should be used, the values of these two parameters should be -1.
(+) $allow_add_tagdoc: If set to 0 or undef, do not add TagDoc-objects (disturbing at loading/paste-time)
$object->commands_changed($command, $index1);
This method is called whenever a new command should be inserted into the document (COMMANDS). NOTE: a command is represented by the embeding of a ``ComObj'' object which uses always the index range of one character.
This method is called as an callback from the OptionMenu widget that inserts the commands and from the InOut.pm package for opening a document from the disk.
This method calls the corresponding ``TagMan'' objects ``add_commad_tag'' method.
The method returns the name of the newly created command tag.
Parameters:
(+) $command: The name of the command to be inserted
(+) $index1: The index in the Text widget where the command should be inserted. If the current cursor position should be used, the values of the parameter should be -1.
$object->doc_style_changed($style);
This method is called whenever the currents document DOC_STYLE gets changed. This changes the way the numbering of paragraphs, images, tables and other objects is done in the document and also changes the number available styles. Several paragraph, environment, character styles and commands are only available in some document styles.
This method is called as an callback from the OptionMenu widget that sets the document style and from the InOut.pm package for opening a document from the disk.
Parameters:
(+) $style: The name of the document style to be applied to the document.
$object->backend_changed($backend_name);
This method is called whenever the currents backend gets changed.
It sets the current $self->out()-hash to undef and rebuilds it afterwards.
Parameters:
(+) $backend_name: The name of the new backend
$object->get_number_of_lines();
This method returns the number of lines that exist in the current document.
$object->refresh_outline();
This method refreshes the outline view in the tree widget. It uses the information of the NumList objects that are used for numbering the paragraph styles and the images and tables.
$object->goto_outline();
Jumps to the top of the fraction in the document that is selected in the outline view.
$object->refresh_backend();
Refreshes the backend view.
$object->add_part( $parts_group
[, $part_name,
$ref_part_content] );
This method adds the selected text of the parts-archive.
It asks for a name for that part, if it already exists, it overwrites the old one.
Parameters:
(+) $parts_group: The subbranch the part should be added (Values are: 'GLOBAL', 'PROJECT' or 'DOCUMENT')
(+) $part_name: The name for the part. If not given or undef, it will be queried. [Optional argument !]
(+) $ref_part_content: A reference to an array holding the content of the part to be added. If this argument is not undef, this content will be used instead of the currently selected text in the document ! [Optional argument !]
$object->use_part( [$parts_group, $part_name, $cursor_index] );
This method Inserts the content of a part into the document at the current cursor position. If BOTH of the first 2 optional arguments are given and the specified part exists, this part is inserted, otherwise the currently selected part (if any) is used for insertion.
If the third optional argument is given, this position will be used in the text for insertion and not the current cursor position.
Parameters:
(+) $parts_group: In which subbranch of the parts-archive the part is located. Could be 'DOCUMENT', 'PROJECT' or 'GLOBAL'. [Optional argument !]
(+) $part_name: The name for the part. [Optional argument !]
(+) $cursor_index: The insertion point as an valid Textwidget index. [Optional argument !]
$object->rename_part( [$parts_group, $part_name, $new_name] );
This method renames a part. If BOTH of the first 2 optional arguments are given and the specified part exists, this part is renamed otherwise the currently selected part (if any) is used for renaming.
If the third optional argument is given, this new name will be used, otherwise it will be queried.
Parameters:
(+) $parts_group: In which subbranch of the parts-archive the part is located. Could be 'DOCUMENT', 'PROJECT' or 'GLOBAL'. [Optional argument !]
(+) $part_name: The name for the part. [Optional argument !]
(+) $new_name: The new name for the part. [Optional argument !]
$object->copy_part( [$parts_group, $part_name, $new_name] );
This method copies a part. If BOTH of the first 2 optional arguments are given and the specified part exists, this part is copied otherwise the currently selected part (if any) is used for copying.
If the third optional argument is given, this new name will be used, otherwise it will be queried.
Parameters:
(+) $parts_group: In which subbranch of the parts-archive the part is located. Could be 'DOCUMENT', 'PROJECT' or 'GLOBAL'. [Optional argument !]
(+) $part_name: The name for the part. [Optional argument !]
(+) $new_name: The new name for the part. [Optional argument !]
$object->delete_part( [$parts_group, $part_name] );
This method deletes a part. If BOTH of the first 2 optional arguments are given and the specified part exists, this part is deleted otherwise the currently selected part (if any) is used for deletion.
Parameters:
(+) $parts_group: In which subbranch of the parts-archive the part is located. Could be 'DOCUMENT', 'PROJECT' or 'GLOBAL'. [Optional argument !]
(+) $part_name: The name for the part. [Optional argument !]
$object->update_parts_all();
Updates the all subbranches of the parts-treeview.
$object->update_parts_document();
Updates the DOCUMENT-subbranch of the parts-treeview.
$object->update_parts_project();
Updates the PROJECT-subbranch of the parts-treeview.
$object->update_parts_global();
Updates the GLOBAL-subbranch of the parts-treeview.
$tagname
= $object->insert_embobj($classname, $data,
$index1, $renumber, $do_not_sort);
Inserts an EmbObj-derived widget into the document.
The method returns the tag name of the new created ``EMBOBJ''-tag.
Parameters:
(+) $classname: The classname of the EmbObj derived widget to insert
(+) $data: All configuaration data the object needs
(+) $index1: The place in the text widget where the object should be embeded
(+) $renumber: Automatically the associated ``NumList'' object. [Here: $tagman->img_num_list(), later it will be a ``NumList'' object defined in the configuration file ``edoc.obj'' and there associated with this ``EmbObj''-derived class. These ``NumList'' objects will be stored in a seperate hash-property in the corresponding ``TagMan'' object called ``$tagman->numlists($obj_class_name)'']
(+) $do_not_sort: If set to 1, the automatically created ``NumList'' will not be automatically sorted in the corresponding ``NumList'' object. This is for document loading from disk.
$object->edit_doc_args();
Shows a TagForm window that allows editing of the document arguments
$object->copy_to_edoc_clipboard();
Copies the selected text to the e:dco internal clipboard.
$object->cut_to_edoc_clipboard();
Cuts the selected text to the e:dco internal clipboard.
$object->paste_from_edoc_clipboard();
Pastes the e:dco internal clipboard into the current document at the cursor position.
$object->get_selection();
Returns 0 if there is no selection otherwise it returns a reference to a hash where the following indizes are stored:
$result->{'start_index'}: The start index of the selection
$result->{'end_index'}: The end index of the selection
$object->tag_doctor_pressed();
Toggles ON/OFF the Tag-Doctor feature
$object->show_search_form();
Shows the ``search and replace'' dialog
$object->update_window_caption();
Updates the text for the window caption
my $ref_hash
= $object->_get_parts_root($parts_group);
Get the root of the hash containing the infos of this parts-group.
Parameters:
(+) $parts_group: The name of the 'parts group'. Can be: 'DOCUMENT', 'PROJECT' or 'GLOBAL'.
$object->_update_parts_branch($parts_group);
Updates the subbranch of the parts tree that holds this parts_group
Parameters:
(+) $parts_group: The name of the 'parts group'. Can be: 'DOCUMENT', 'PROJECT' or 'GLOBAL'.
$object->_key_pressed();
Callback for any KeyPress event. This method sets the
content_changed()
flag.
$object->_cursor_moved();
Callback for any cursor movements or mouseclicks in the text widget. This method ensures that there are always the right paragraph, environment, character styles and command names displayed in the OptionMenu widgets.
NOTE: This method should be disabled when a document is loaded from disk, because I think it is often called then and this just costs time for nothing.
$object->_build_backend_menu();
(Re)builds the 'Backend' menu.
$object->_show_full_screen_mode();
Turns on the full_screen mode.
$object->_hide_full_screen_mode();
Turns off the full_screen mode.