Widget: EmbObj
use class::EmbObj;
The file EmbObj.pm is located in the subdirectory './class'
This is a widget derived from Tk::Frame that gets embeded into the documents text widget in the DocForm object (=document window).
It is the base class for all embeded widgets which are defined in the configuration file ``edoc.obj''. This class contains the functionality of beeing embeded into the text widget (doctext) of a document window (DocForm object), to be expanded or collapsed and to be numbered by one of the numbering engines (NumList object) also defined in ``edoc.obj'' and to be shown in the outline view as an item in the objects branch.
This class EmbObj is never used, it just builds the base class for all embeded objects like images (ImgObj) or tables (TblObj).
This object has 2 different states.
(+) In the collapsed state, it displays 3 Labels, the right one contains the numbering, the middle one the caption and the right one contains a sort of button to open (if exists) the property editor of the (derived) class.
(+) In the expanded state, it shows the content of the object too.
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.
Coding: 20% done
Documentation: up-to-date
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->{'window_tag'} #The name of the tag the EmbObj is tagged with in the text widget
$self->{'content_changed'} #Flag, if the content changed (unsaved)
$self->{'numlist'} #A referenve of the Numlist that should hold the internal NumLabel
$self->{'pre_number_text'} #The text that should be shown before the number
$self->{'post_number_text'} #The text that should be shown after the number
$self->{'do_number'} #If the object is numbered or not
$self->{'propedit_classname'} #The classname of the objects property
editor is stored here. The default class of propertyeditor is 'TagForm',
the same property editor that is used for editing Tag-Properties. This
property editor can only edit a flat one-dimensional set of
arguments(properties).
If the derived widget is more
complicated, you have to design your own property editor by deriving from
'ObjPropForm.pm' (STILL MISSING). You will have to call
$self->propedit_classname($propedit_classname) in the '_build_ui' method
of the derived widget.
$self->{'classname'} #The name of the EmbObj derived class (later this will be got by perl-methods)
$self->{'_obj_config'} #The configuration data for this object (coming from edoc.int)
$self->{'_expanded'} #Flag wether the object is in expanded state ore not
$self->{'_data'} #The save data of the object (needed for saving it on disk and restoring it again) This attribute consists of a ONE-LEVEL hash holding the attributes of the object.
$self->{'_data'}->{'caption'} #The caption to be displayed
$self->{'_backend'} #Export information for the current backend (Normaly a sub-hash with the depth of one level)
NOTE: The following attributes are used for the Tk widgets building the GUI and are accessed directly (no get/set methods):
$self->{'_top_base'}
$self->{'_bottom_base'}
$self->{'_resize_handle'}
$self->{'_img_prop'}
$self->{'_btn_prop'}
$self->{'_balloon_prop'}
$self->{'numlabel'} #The internal NumLabel
$self->{'embed_base'} #PUBLIC:A reference to the Frame where the derived class should pack its content into
! Not called directly !
This ``constructor'' initialises a new object of the class EmbObj and calls
ClassInit()
of the Superclass.
$object
= EmbObj(%options);
This ``constructor'' sets the options of the new object of the class EmbObj.
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!)
(+) '-window_tag' => The name of the tag that surrounds the embeded ``ComObj'' in the text widget
(+) '-numlist' => A reference of the associated NumLabel widget
(+) '-classname' => The name of the EmbObj derived class (later this will be got by perl-methods)
(+) '-do_not_sort_numlabel' => If 1 then this numlabel will not be autoamtically sorted (loading time)
(+) '-pre_number_text' => The text that should be shown before the number
(+) '-post_number_text' => The text that should be shown after the number
(+) '-data' => The saved data to be stored into $self->data()
(+) '-obj_config' => The configuration data for this object, stored in $self->obj_config(). This is a reference to a hash that holds the additional configuration data stored in 'edoc.int'.
(+) '-do_number' => If the object is numbered or not
This message is called ONLY in the EmbObj-derived classes to fill the frame that is thought for embeding the new widgets.
This is an abstract base function, it HAS TO BE overwritten by the derived class.
$object->on_create();
This method has to be called after the object 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)'.
This is IMPORTANT because this 'on_create' method performs the creation of the contained widgets, binding of events and some more important stuff.
The standard automatically called PERL destructor for objects.
$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.
$classname
= $object->propedit_classname(); #gets the
classname of the property editor for that opject-class
$object->propedit_classname($classname); #seets the classname of the property editor for that opject-class
$ref_docform
= $object->docform(); #gets a reference to the
DocForm object the ComObj belongs to
$object->docform($ref_docform); #sets a reference to the DocForm object the ComObj belongs to
$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
$flag
= $object->content_changed(); #gets the changed-flag
of the object
$object->content_changed($flag); #sets the changed-flag of the object
$ref_emb_base
= $object->embed_base(); #gets a reference to
the Frame where the content of the derived widget should be packed into
$object->embed_base($ref_emb_base); #sets a reference to the Frame where the content of the derived widget should be packed into
$text
= $object->caption(); #gets the caption text for the
object
$object->caption($text); #sets the caption text for the object
$do_not_sort_numlabel
= $object->do_not_sort_numlabel();
#gets the 'do_not_sort_numlabel'-property
$object->do_not_sort_numlabel($do_not_sort_numlabel); #sets the 'do_not_sort_numlabel'-property
$ref_numlist
= $object->numlist(); #gets a reference of the
NumList that manages this EmbObj-derived widgets
$object->numlist($ref_numlist); #sets a reference of the NumList that manages this EmbObj-derived widgets
$ref_numlabel
= $object->numlabel(); #gets a reference of
the internal NumLabel object
$object->numlabel($ref_numlabel); #sets a reference of the internal NumLabel object
$pre_number_text
= $object->pre_number_text(); #gets the
value of the 'pre_number_text' attribute
$object->pre_number_text($pre_number_text); #sets the value of the 'pre_number_text' attribute
$post_number_text
= $object->post_number_text(); #gets the
value of the 'post_number_text' attribute
$object->post_number_text($post_number_text); #sets the value of the 'post_number_text' attribute
$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
This tells the EmbObj if it has to register itself in the Numlist and be numbered.
$classname
= $object->classname(); #gets the name of the
EmbObj-derived class
$object->classname($classname); #sets the name of the EmbObj-derived class
Stupid to pass that to the EmbObj-class, but this will be later automatically dedected by perl-methods.
$ref_obj_config
= $object->obj_config(); #gets a reference
to an hash that stores the objects configuration data
$object->obj_config($ref_obj_config); #sets a reference to an hash that stores the objects configuration data
$color_def
= $object->foreground(); #gets the foreground
color definition
$object->foreground($color_def); #sets the foreground color definition
$color_def
= $object->background(); #gets the background
color definition
$object->background($color_def); #sets the background color definition
$font_def
= $object->font(); #gets the font definition
$object->font($font_def); #sets the font definition
$relief_def
= $object->relief(); #gets the relief
definition
$object->relief($relief_def); #sets the relief definition
$tag_name
= $object->window_tag(); #gets the tag name of
the ComObj
$object->window_tag($tag_name); #sets the tag name of the ComObj
$extpanded_flag
= $object->expanded(); #gets the state of
the ComObj
$object->expanded($expanded_flag); #sets the state of the ComObj
$ref_backend
= $object->backend(); #gets a reference to the
objects backend hash
$object->backend($ref_backend); #sets a reference to the objects backend hash
$object->set_backend($ref_hash); #Builds up the $self->{'_backend'}-subhash.
This method is called at export-time to feed the EmbObj-derived object with the export-definition of the actual backend. This is done before calling the method 'export_to_backend()'.
$result_string
=
$object->process_arguments($source_string);
This function parses for special commands (Arguments, other backend definition commands) in the given string and replaces them with the right values.
The function returns the parsed result.
Parameters:
(+) $source_string: The string to be paresed
$line
= $object->get_current_line();
This returns the line number where the EmbObj widget is situated inside of the text widget it belongs to.
my $save_data
= $object->get_save_data();
This function builds a string out of the whole $self->{'_data'} structure and returns it.
my @export_text
= $object->export_to_backend();
This function exports the content of the object to the current backend.
The function is called in the document-exporting process, whenever an embeded object is found.
It returns the text for exporting the object.
The function HAS TO BE overwritten in the derived objects, otherwise this dummy function wil be called.
$object->_set_save_data($data);
This function builds the whole $self->{'_data'} structure out of the string $data.
Parameters:
(+) $data
: The saved data from file
$object->_do_click();
This is the callback function for the ``<Button-1>'' event (Click).
It causes the EmbObj widget to collapse or expand itself.
$object->_expand();
Expands the object. (Creates and packs the '$self->embed_base()' widget.)
$object->_collapse();
Collapses the object. (Destroys the '$self->embed_base()' widget.) ! a nice place for a memory leak -> test!
$object->_on_btn_prop_click();
Callback for clicking on the 'Properties'-button.
$object->_grip_mouse_button1_pressed();
This is the callback for pressing the left mousebutton on the resizeing grip.
$object->_grip_mouse_button1_released();
This is the callback for releasing the left mousebutton on the resizing grip.
$object->_before_save();
This function is called before the $self->{'_data'}-subbranch gets saved.
Use this for flatten complicated data structures into {'_data'}.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_after_save();
This function is called after the $self->{'_data'}-subbranch got saved.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_before_load();
This function is called before the $self->{'_data'}-subbranch is loaded from file.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_after_load();
This function is called after the $self->{'_data'}-subbranch is loaded from file.
Use this function to build up complicated data structures from the flat {'_data'}-subbranch
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_before_expand();
This function is called before the object gets expanded.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_after_expand();
This function is called after the object gets expanded.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_before_collapse();
This function is called before the object gets collapsed.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_after_collapse();
This function is called after the object gets collapsed.
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj
$object->_after_backend_changed();
This function is called after the current backend changed
This Function is just the abstract base function, it has to be overwritten by the classes that derive from EmbObj