NAME:

Package: Utils


SYNOPSIS:

use lib::Utils;


DIRECTORY/FILE:

The file Utils.pm is located in the subdirectory './lib'


DESCRIPTION:

This package contains all function that did not fit into one of the other lib-packages.


STATUS:

Coding: this is an open-end package, so no status percentage can be mentioned here

Documentation: up-do-date


FUNCTIONS:


get_index_info

$line_number = Utils::get_index_info($index);

or

($line_number, $col_number) = Utils::get_index_info($index);

Extracts the linenumber (and the column number) from the given index and returns it


test_hash_value

$reult = Utils::test_hash_value($ref_hashbranch, $entryname);

Tests if the hash-value exists, is defined and has a value

Returns 0 if the value doesn't exist, is not defined or ''.

Returns the value if there is a value.

Parameters:

(+) $ref_hashbranch: The branch in the hash that contains the entry

(+) $entryname: The name of the entry there

Example:

If you wan to test $hash->{'xxx'}->{'yyy'}, you have to call:

my $result = Utils::test_hash_value($hash->{'xxx'}, 'yyy');


build_display_font

$display_font = Utils::build_display_font($base_font, $lower_font, $lower_mask, $higher_font, $higher_mask);

One BIG problem is that in the Perl/Tk text widget one tag has one font-definition and if tags overlap each other only the uppermost tags font is displayed.

So I have to develop amechanism that collects all informations from all tags that overlap each other, calculate the appropriate font definition and add a special display-only uppermost tag with the combined font definition.

To decide what part of a styles font definition is important I invented the font_mask property. Look at the following example:

The base font of the textwidget is f. ex.:

font = ``-adobe-times-*-*-*--*-160-*-*-*-*-*-*''

font_mask = ``-*-*-*-*-*--*-*-*-*-*-*-*-*''

which means that the base font is 'Adobe Times 16pt' and none of the definitions parts is very important

The font definition for the style 'Bold' is:

font = ``-adobe-times-bold-r-normal-*-180-*-*-*-*-*-*-*''

font_mask ``-*-*-bold-*-*-*-*-*-*-*-*-*-*-*''

which means that the 'Bold' style applied to an area without any existing tags (formatting) is 'Adobe Times 18pt bold', but only the '-bold-' attribute is _very_important_ for the style.

The font definition of the style 'Italic' is:

font = ``-adobe-times-medium-o-normal-*-180-*-*-**p-*-*-*''

font_mask ``-*-*-*-o-*-*-*-*-*-*-*-*-*-*''

which means that only the '-o-' attributes are _very_important_ for this style.

So if both styles overlap each other, there should be applied another tag with the font definition a follows:

font = ``-adobe-times-bold-o-normal-*-180-*-*-*-*-*-*-*'' which is a combination of the 3 definitions in respect of the 'font_mask' properties.

This function will return the new font definition of the display-font.

NOTE: THIS FUNCTION IS NOT CODED YET !

Parameters:

(+) $base_font: The base font of the text widget

(+) $lower_font: The lower fonts definition

(+) $lower_mask: The lower fonts mask

(+) $higher_font: The lower fonts definition

(+) $higher_mask: The lower fonts mask


get_tagnames_from_line

@names = Utils::get_tagnames_from_line($ref_text_widget, $line);

Builds a list of tagnames from that line

It returns the value of the given $optionin the existing data-stringlist ($data).

Utils::get_embobj_data('[[[rows=2||cols=4]]]','rows') would return the value 2.

Parameters:

(+) $ref_text_widget: A reference to the text widget

(+) $line: The linenumber


textwidget_sel_exists

Utils::textwidget_sel_exists($ref_text_widget);

Tests for an existing selection in the text_widget and return 1 if the sel exists, otherwise the function returns 0.

Parameters:

(+) $ref_text_widget: A reference to the text widget


textwidget_select

Utils::textwidget_select($ref_text_widget, $index1, $index2);

Sets the selection in the text_widget

Parameters:

(+) $ref_text_widget: A reference to the text widget

(+) $index1, $index2 : The range for the selection


textwidget_unselect

Utils::textwidget_unselect($ref_text_widget);

Removes all ranges of the 'sel'-tag in the textwidget.

Parameters:

(+) $ref_text_widget: A reference to the text widget


create_balloonhelp

$ref_baloon = Utils::create_balloonhelp($ref_widget, $text, $state, $ref_statusbar);

Creates a balloonhelp and associates it with the widget

The functions returns a reference to the created balloon widget.

Parameters:

(+) $ref_widget: A reference to the widget

(+) $text: The text do be displayed in the balloon

(+) $state: The state of the balloon ('balloon', 'status', 'both', 'none'). Default is 'balloon'

(+) $ref_statusbar: A reference for the statusbar(Label) that should display the balloonhelp's text, if state is 'status' or 'both', else set it to undef


set_browseentry_color

Utils::set_browseentry_color($ref_browseentry, $color);

Sets the given color in a BrowseEntry widget.

Parameters:

(+) $ref_browseentry: A reference to the BrowseEntry widget.

(+) $color: The color to be set.


beautify_browseentry

Utils::beautify_browseentry($ref_browseentry);

Changes the BrowseEntry widget into the right e:doc look.

Parameters:

(+) $ref_browseentry: A reference to the BrowseEntry widget.


process_filename

$new_filename = Utils::process_filename($filename);

This function checks if the given file exists. If not, it tries to append the e:doc-filepath stored in '$main::edoc_path' in front of the filename. If this does not exist also, it returns undef, which means that the file was not found.

It returns the processed filename&path.

Parameters:

(+) $filename: The filename to be processed


process_filename_in_document

$new_filename = Utils::process_filename_in_document($filename, $ref_docform);

This function checks if the given file exists. If not, it tries to append the active document's filepath stored in front of the filename. If this does not exist also, it returns undef, which means that the file was not found.

It returns the processed filename&path.

Parameters:

(+) $filename: The filename to be processed

(+) $ref_docform: A reference to the DocForm object that holds the document


extract_path

$path_only = Utils::extract_path($filename_incl_path);

Extracts and returns the filepath of the given filename. If there is no path, the function returns ''.

Parameters:

(+) $filename_incl_path: The filename to be processed


extract_filename

$filename_only = Utils::extract_filename($filename_incl_path);

Extracts and returns the filepath of the given filename. If there is no path, the function returns ''.

Parameters:

(+) $filename_incl_path: The filename to be processed


KNOWN BUGS:


STILL MISSING: