NAME:

Object: PrjForm


SYNOPSIS:

use class::PrjForm;


DIRECTORY/FILE:

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


DESCRIPTION:

The object PrjForm encapsulates the project 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/uiPrjForm.pm''.


STATUS:

Coding: 10% done

Documentation: up-do-date


ATTRIBUTES:

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

$self->{'authors'} = [...] #A Reference to an array that holds the authors (Will later become a reference to an hash, when more info per author is stored)

$self ->{'file_ext_array'} #An Array of arrays of arrays that is used for the getOpenFile dialog .

$self->{'filetypes'}->{$name} #A hash that holds info apout the filetypes

$self->{'filetypes'}->{$name}->{'extensions'} = [...] # A reference to an array of extensions of this filetype

$self->{'filetypes'}->{$name}->{'caption'} # The caption (full name) that is used in the tree for that filetype

$self->{'files'}->{$file_name}; #Reference to a hash that holds the additional info to an registered file

$self->{'files'}->{$file_name}->{'type'} #Could be 'LOCAL' for autoread files in the project directory or 'LINK' if a file from somewhere else on the disk was linked into the project

$self->{'files'}->{$file_name}->{'size'} #The filesize on the last refreshing

$self->{'files'}->{$file_name}->{'changed'} #The date/time of the last filechange

$self->{'files'}->{$file_name}->{'file_type'} #The filetype that file belongs to

$self->{'files'}->{$file_name}->{'args'}->{$i}->{'value'} #The value of the argument

$self->{'files'}->{$file_name}->{'args'}->{$i}->{'type'}; #The type of the argument

$self->{'files'}->{$file_name}->{'args'}->{$i}->{'default'}; #The default value of the argument

$self->{'files'}->{$file_name}->{'args'}->{$i}->{'settings'}; #Additional info for the argument

$self->{'files'}->{$file_name}->{'args'}->{$i}->{'hint'}; #The hint-text of the argument

$self->{'current_file'}->{'args'}->{'arg_number'} #The number of arguments of the selected file

$self->{'current_file'}->{'args'}->{$i}->{'value'} #The value of this argument of the selected file

$self->{'current_file'}->{'args'}->{$i}->{'type'}; #The type of the argument of the selected file

$self->{'current_file'}->{'args'}->{$i}->{'default'}; #The default value of the argument of the selected file

$self->{'current_file'}->{'args'}->{$i}->{'settings'}; #Additional info for the argument of the selected file

$self->{'current_file'}->{'args'}->{$i}->{'hint'}; #The hint-text of the argument of the selected file

$self->{'prj_parts'}; #A reference to an hash of arrays. Each hash-key represents the name of a project-part, each array contains the parts content in the clipboard format

$self->{'prj_args'}; #A hash that holds the project arguments

$self->{'prj_args'}->{'arg_number'}; #The number of arguments

$self->{'prj_args'}->{$i}->{'name'}; #The name of the argument

$self->{'prj_args'}->{$i}->{'type'}; #The type of the argument

$self->{'prj_args'}->{$i}->{'default'}; #The default value of the argument

$self->{'prj_args'}->{$i}->{'settings'}; #Additional info for the argument

$self->{'prj_args'}->{$i}->{'hint'}; #The hint-text of the argument

$self->{'prj_args'}->{$i}->{'value'}; #The value of the argument

$self->{'ui'}->{'app_window'} #A referenece to the MainWindow

$self->{'ui'}->{'content'} #A referenece to the content outline (Tree widget)

$self->{'ui'}->{...the rest of this branch...} #References to the widgets that build the user interface


METHODS:


Class Methods:


Constructors:


new

$object = PrjForm->new();

This constructor creates a new object of the class PrjForm.

This calls class::ui::uiPrjForm::build_ui($self) which builds the window and its containing widgets.

The window is a MainWindow() which is the applications main_window (later refered as $app_window)


Destructors:


DESTROY;

The standard automatically called PERL destructor for objects. Unfortionatly it is called very late (when the whole application terminates.)


do_destroy

$object ->do_destroy();

This destructor is binded to the protocol-message WM_DELETE_WINDOW and performs the 'unsaved changes'-check, destroys the MainWindow manually and then destroys the PrjForm object manually too.


Public data methods (=Get/Set methods):


app_window

$ref_app_window = $object->app_window(); #gets a reference to the main application window (READ-ONLY)


content

$ref_content_outline = $object->content(); #gets a reference to the projects content outline (=tree widget) (READ-ONLY)


prj_parts_root

$ref_root = $object->prj_parts_root(); #gets a reference to the root of the hash of arrays that holds the parts


prj_parts_names

@prj_parts_names = $object->prj_parts_names(); #gets an array containing the names of all parts in this project (READONLY)


ref_prj_part

$ref_content = $object->ref_prj_part( $name ); #gets a reference to an array containing the part in clipboard-format

$object->ref_prj_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


prj_args_number

$prj_args_number = $object->prj_args_number(); #gets the number of project arguments

$object->prj_args_number($prj_args_number); #sets the number of project arguments


file_args_number

$file_args_number = $object->file_args_number(); #gets the number of file arguments

$object->file_args_number($file_args_number); #sets the number of file arguments


file_arg_value

$object->file_arg_value($filename, $index, $new_value); #Set a file args value

$value = $object->file_arg_value($filename, $index); #Get a file args value

This method gets or sets the value of a file argument.

If the filename isn't in the project or does not have that many arguments, it returns undef.

Parameter:

(+) $filename : The filename the argument belongs to

(+) $index : The index of the argument

(+) $value : The value to be set


authors

$object->authors($ref_authors_list); #Set the reference to the authors array

$ref_authors_list = $object->authors(); #Get the reference to the authors array


Other public methods:


project_exit

$object->project_exit();

Terminate the applictaion.


set_prj_arg_value

$object->set_prj_arg_value($index, $value);

Parameter:

(+) $index : The index of the argument

(+) $value : The value to be set


project_new

$object->project_new();

Resets the PrjForm object for starting a new project.


project_open

$object->project_open([$filename]);

Calls InOut::project_open($self, [$filename]), which opens a new project into this PrjForm.

Parameters:

(+) $filename: OPTIONAL, if this is set to undef or not set, the filename is queried by a FileOpen dialog


project_save

$object->project_save();

Calls InOut::project_save($self), which saves the PrjForm into the ALREADY EXISTING file


open_empty_docform

$ref_docform = $object->open_empty_docform();

Opens a new document window (DocForm) and returns a reference to it.


open_docform_file

$ref_docform = $object->open_docform_file($filename);

Opens a new document window (DocForm), opens a document into it and returns a reference to it.

Parameters:

(+) $filename: The filename of the document to open (incl. path)


new_file_from_template

$new_filename = $object->new_file_from_template();

This method queries first for a template, than queries the filename the new file should have.

Next it copies the template to the new filename and initialise the file argument and refreshes the projects content.

After all that is executed the newly created document is opened.

The method returns the filename of the created file if all went ok and undef if there was an error or it was canceled.


new_document_from_scratch

$new_filename = $object->new_document_from_scratch();

This method queries the new filename. Afterwards it creates an empty docform and saves it with this filename.

Next it initialises the file argument and refreshes the projects content.

The method returns the filename of the created file if all went ok and undef if there was an error or it was canceled.


project_refresh

$object->project_refresh();

Refreshes the displayed content of the project (now the content of the directory)


update_window_caption

$object->update_window_caption();

Updates the text for the window caption


open_tutorial

$object->open_tutorial();

Opens the file ``/samples/tutorial.edp''.


file_add

$filename = $object->file_add();

Adds a file to the project. If all went ok, it returns the filename, else it returns undef.

The added file will be copied into the project directory and added into the project structure.

If a file already exists in the project with this filename, a number is added to the filename.


file_link

$filename = $object->file_link();

Links a file to the project. If all went ok, it returns the filename, else it returns undef.

The added file will NOT be copied into the project directory. Ther si just a shortcut stored in the project structure.

In this case not only the filename is stored, it gets storet together with the full path.

If a file already exists in the project with this filename, a number is added to the filename.


file_remove

$ok = $object->file_remove();

Removes a file from the project. If all went ok, it returns 1, else it returns 0.

The file will be deleted (physically) from the projects directory. Linked files cannot be deleted.


file_rename

$ok = $object->file_rename();

Renamesa file from the project. If all went ok, it returns the new name, else undef.

The file will be renamed (physically) in the projects directory.

Linked files cannot be renamed.


file_duplicate

$new_name = $object->file_duplicate();

Duplicate a file in the project. If all went ok, it returns the new name, esle undef.

Linked files cannot be duplicated


file_unlink

$ok = $object->file_unlink();

Unlinks the selected file from the project. If all went ok, it returns 1 esle 0.


Private methods:


_content_dbl_click

$ref_docform = $object->_content_dbl_click();

Callback for the doubleclick event on one content entry. Opens a document window (DocForm) or starts an external application to open the file.


_init_args

my $arg_number = $object->_init_args($type [,$filename] );

Initialises the argument-storing branches.

This is only performed if there are not already arguments stored for that file to preven overwriting of already existing values.

The method returns the number of initialised arguments.

Parameters:

(+) $type: What arguments should be initialised, could be 'PROJECT_ARGS', 'FILE_ARGS', 'CURRENT_FILE'

(+) $filename: The name of the file (Only to be set when $type is 'FILE_ARGS')


_on_browse_content

$object->_on_browse_content();

Callback for browsing in the content tree.


_write_back_current_file_args

$object->_write_back_current_file_args();

Writes back the data stored for editing in the {'current_file'}->{'args'}-branch.


_select_in_content

$object->_select_in_content($entry_path);

Selects the specified entry in the content-tree and performs 'browsecmd'.

Parameters:

(+) $entry_path: The path of the entry


KNOWN BUGS:

Properties (hash values) are often directly accessed now, this should be done with more Get/Set methods.


STILL MISSING:

(+) More PIM and project management functionality, backup, zip and deploy mechanisms.

(+) Drag&Drop inside of the tree and between the project form and the document form.