NAME:

Widget: ComObj


SYNOPSIS:

use class::ComObj;


DIRECTORY/FILE:

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


DESCRIPTION:

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

It is used for representing commands which are different from the styles you can apply to some parts of the text. A style is applied to some text so it just encloses a part of the text and gives it a special meaning/formatting (f. ex. in LaTeX: ``\chapter{This is my chapter}'' or in HTML: ``<H1>This is my chapter</H1>''). A command is not layed over a text part, it is inserted into the text and could have some arguments with it (f.ex. in LaTeX: ``\footnote{some text}'' here is ``some text'' not part of the original document text, it is an ARGUMENT that belongs to the ``\footnote''-command. In HTML: ``<IMG SRC=''img.jpg``>''.) The difference between formatting a part of the documents text and arguments of a command is that the arguments belong to the command and are f. ex. deleted together with the command, whereas you can apply and remove all styles to textparts without harming this textparts themselves.

This object has 2 different states.

(+) In the collapsed state, it looks like a button and has the name of the command it reprents as caption on itself.

(+) In the expanded state, it shows one ArgEdit object per defined argument. NOTE: What arguments and how many arguments a command has is defined in the configuration file ``edoc.int''. A command with no argument can not be expanded. There can also be dfined some arguments for ``normal'' styles, but this arguments are not set by an embeded argument editor, they are set by the ``TagForm'' object (a special argument setting window for styles) which uses again ArgEdit objects to handle the arguments.

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: 80% done

Documentation: up-to-date


ATTRIBUTES:

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

$self->{'foreground'} #The foreground color definition

$self->{'background'} #The background color definition

$self->{'font'} #The font definition

$self->{'relief'} #The relief definition

$self->{'docform'} #A reference to the associated DocForm object

$self->{'tagman'} #A reference to the associated TagMan object

$self->{'command'} #The command name the object representates

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

$self->{'argedit'} #The automatically created ArgEdit object when the ComObj gets expanded

$self->{'_expanded'} #Flag wether the object is in expanded state ore not

NOTE: The following attributes are used for the Tk widgets building the GUI and are accessed directly (no get/set methods):

$self->{'_label'} #The label that holds the caption of the ComObj

$self->{'_label_text'} #What text should be displayed in the label

$self->{'_base'} #The frame that builds the base of the ComObj


METHODS:


Class Methods:


ClassInit($class, $parentwindow)

! Not called directly !

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


Constructors:


Populate

$object = ComObj(%options);

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

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

The keys/values in %options:

(+) '-foreground' => The foreground color

(+) '-background' => The background color

(+) '-relief' => The relief style ('flat', 'raised', 'sunken', 'ridged')

(+) '-font' => The font definition

(+) '-docform' => A reference to the ``DocForm'' object to which this ``ComObj'' widget belongs (!Circular references!)

(+) '-command' => The name of the command it representates

(+) '-window_tag' => The name of the tag that surrounds the embeded ``ComObj'' in the text widget


$object->on_create();

This method has to be called after the ComObj 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)'. Then the arguments stored in the TagMan-object should also be initialised correctly.

This is VERY IMPORTANT because this 'on_create' method performs the binding of events that are necessary to edit the arguments assigned to this ComObj.


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):


docform

$ref_doc_form = $object->docform(); #gets a reference to the DocForm object the ComObj belongs to

$object->docform($ref_doc_form); #sets a reference to the DocForm object the ComObj belongs to


tagman

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

$object->tagman($ref_tagman); #sets a reference to the Tagman object of the DocForm object the ComObj belongs to


argedit

$ref_argedit = $object->argedit(); #gets a reference to the ArgEdit object that is created at expansion time

$object->argedit($ref_argedit); #sets a reference to the ArgEdit object that is created at expansion time


foreground

$color_def = $object->foreground(); #gets the foreground color definition

$object->foreground($color_def); #sets the foreground color definition


background

$color_def = $object->background(); #gets the background color definition

$object->background($color_def); #sets the background color definition


font

$font_def = $object->font(); #gets the font definition

$object->font($font_def); #sets the font definition


relief

$relief_def = $object->relief(); #gets the relief definition

$object->relief($relief_def); #sets the relief definition


command

$command_name = $object->command(); #gets the command name of the ComObj

$object->command($command_name); #sets the command name of the ComObj


window_tag

$tag_name = $object->window_tag(); #gets the tag name of the ComObj

$object->window_tag($tag_name); #sets the tag name of the ComObj


expanded

$extpanded_flag = $object->expanded(); #gets the state of the ComObj

$object->expanded($expanded_flag); #sets the state of the ComObj


Other public methods:


get_current_line

$line = $object->get_current_line();

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


Private methods:


_do_click

$object->_do_click();

This is the callback function for the ``<Button-1>'' event (Click).

It causes the ComObj widget to collapse or expand itself.


_expand

$object->_expand();

Expands the object. (Creates and packs the ArgEdit widgets.)


_collapse

$object->_collapse();

Collapses the object. (Destroys the ArgEdit widgets.) ! a nice place for a memory leak -> test!


KNOWN BUGS:


STILL MISSING: