tdewebdev/quanta/DESIGN

This document tries to give a little overview about Quanta classes and their
interactions. The document is for Quanta+ 3.3 as of 27-05-2004.

1. src directory
-----------------
- the main classes

KSplash:  the splash screen class (used only for KDE < 3.2.3). Called from the
               KQApplication classes.

KQApplicationPrivate: the common class for the unique and non-unique mode
                Quanta application.

KQApplication: the non-unique version of the Quanta application.

KQUniqueApplication: the unique version of the Quanta application.

QuantaApp: the main window class of Quanta. The main purpose is to handle
                  general user events and to process and provide general informations.
                  As it inherits from KMdiMainFrm it also does some window managing
                  jobs.
                  There is one global object of this type called quantaApp, but it's
                  recommended that you use the signal/slot mechanism instead of
                  calling directly the QuantaApp methods. It interacts almost with
                  every other class.

QuantaInit: a class used only on startup to build the user interface, load the options,
                  set up the signal/slot connections, etc. It has a very short life and can be
                  imagined as a part of QuantaApp.

QuantaDoc: an old class inherited from the pre-KMDI design of Quanta. The methods
                   from it most probably belong somewhere else (eg. QuantaApp). The main
                   tasks now are related to document opening and handling of some user
                   events. There is only one object of this type.

QuantaView: a QuantaView can be imagined as a visual representation of a document,
                    plugin, part. It's the widget on a "tab" in the user interface. Each object
                    may hold either a Document (real document), QuantaPlugin (a plugin) and/or
                    a common widget (anything, like the preview part, documentation part).
                    It has methods to save the document, switch between different view modes
                    (VPL, source) and reacts to some events, like getting the focus.
                    The views are managed by the ViewManager.

ViewManager: singleton object which manages the QuantaView's. It has methods to
                    create, remove, save views, reacts to view change, handles the
                    tab context menus and the D&D of tabs. Interacts with QuantaApp and
                    QuantaView.

Document: an editable (KTextEditor) document with advanced, Quanta specific features.
                 There is a 1-1 relation between a Document and QuantaView. Each view can
                 have one Document and each Document can have only one view. Multiple
                 views of the same document is not supported by Quanta at this moment.
                 The class has methods to manipulate the KTextEditor::Document and
                 KTextEditor::View via the various KTextEditor interfaces in an editor
                 independent mode. Main tasks are:
                    - react to user keypresses
                    - handle autocompletion (when it should appear, what should appear in the
                      completion box, autocompleting of child tags)
                    - react to changes in the document and ask for a rebuild of the node tree
                    - modify the closing/opening tags based on the node tree
                    - create temporary files of opened documents (and after each save)
                    - create backups of documents
                    - handle text and tag insertion
                    - handling tag modifications
                    - react to changes made to the document outside of Quanta
                    - detect the main DTD of the document. Each Document has a main DTD,
                       but may contain other pseudo-DTDs inside.
                    - provides convenience methods to work with text documents (find,
                       findRev, findWordRev, currentWord, text selection)
                    - keeps track of untitled and modified status

DTDs: stores and loads the DTEPs from disk as they are requested. Works with
           DTDStruct classes (structures). Interacts with every class which works with
           DTEPs. Singleton.

DCOP* classes: the DCOP interfaces of Quanta. WindowManagerIf is the general
           purpose interface working mainly with views and files, implemented in the
           QuantaApp class. SettingsIf is an interfaces towards various Quanta settings and
           QuantaIf is an interface towards Quanta internals like selectors, used in some
           of the DTEP definition files. The interfaces (except WindowManagerIf) have a separate implementation class.


2. parsers directory
---------------------
- parsing and node tree related classes (yes, QTag might not belong here)

Parser: parses a document and builds the node tree. It does a quick parsing of XML
            tags, special areas are not parsed in detail, only their start and end region is
            determined. For XML areas it parses also for groups and does a quick
            parsing of included (XML) files as well. It has a method to parse only the
            changed area of the document (rebuild) and a method to find the node from
            the tree corresponding for a place in the document (nodeAt). It calls
            the detailed special area parser in the background via a singleshot timer.
            Interacts with the SAParser, StructureTreeView and any other class requesting
            information from the node tree.
            There is usually only one Parser object in the memory, but it is not a singleton
            as it's used in the table editor as well.

SAParser: special area (pseudo DTEP) parser. Parses scripts, CSS, etc. Can do a quick
            or detailed parsing in synchronous or asynchronous mode. The later means that
            the parsing is done in small steps, using singleshot timers to call the next step, so
            the user interface is not blocked while the detailed, time consuming parsing is
            done. The parsing is context based. Calls the special area group parser for
            every special area node. Emits signals to indicate the ending of parsing and
            the need of the structure tree rebuilding.

SAGroupParser: the special area group parser called from SAParser. This can behave
           asynchronously as well. Emits signals to indicate the ending of parsing and
            the need of the rebuilding of the group part of the structure tree.

ParserCommon: common (static) methods used by the Parser and SAParser, and holds
           parser-global data structures as well.

Node:  an element of the Node tree. Each Node has a parent, child, next and previous
           Node (of course they can be NULL) and a Tag. The Tag cannot be NULL.
           Each node appears at least once under the visual structure tree (mainListItem),
           but can appear more than once if it's part of some structure groups (listItems)
           There are convenience methods which helps navigating through the node tree and
           some flags noting the status of the node. See the description of the class
           attributes.

Tag:  a parsed tag. Each node has a tag. A tag can be a real XML tags from the
        document or some other special tag noting text, empty area, structure begin,
        structure end, comment, etc. XML tags are parsed and it's possible to read
        the available attributes and attribute values, modify them, etc. Each tag has a
        DTD associated with it, meaning that "this tag was parsed and should be
        interpreted as part of this DTD", holds the position in the document, the
        original text found at that position, a cleaned version of that text (without
        comments), etc. A Tag is not necessary a valid tag of the DTD. <foo foo1="foo">
        is a tag in any DTD.

QTag: a valid DTD tag. When the tagXML files are read, each DTDStruct will contain many
        QTag objects describing the valid tags in that DTD. The QTag gives us the
        possible attributes and their values, the relationship regarding other QTags and
        some other status information (single, optional, etc.). A QTag can hold
        information about pseudo-DTD tags, which are not real XML tags, but they can
        describe methods, classes, functions, etc.

DTDParser: parses a real DTD definition file and converts to tagXML.


3. utility directory
-------------------
- helper, convenience classes; other classes not belonging anywhere else

QuantaCommon: static convenience methods, used in many places.

QConfig: holds the Quanta configuration settings.

QuantaToolBar/ToolbarTabWidget/ToolbarXMLGUI: classes needed to make the
              user toolbars work.

TagAction: an extended KAction, which can be modified in Quanta. May be of three
                types: Tag, Script, Text. Script actions can be executed in synchronous
                (execute) or async. mode (insertTag). TagActions are usually put on the
                user toolbars and under Tags menu, but they can be plugged anywhere
                just like the normal KActions.


4. treeviews directory
-----------------------
- classes dealing with the different treeviews

FilesTreeView/FilesTreeBranch/FilesTreeViewItem: shows the file and directory
                structure in a tree. Can show more than one tree at once. By default
                it shows a tree starting with the root directory (/) and one starting with the
                $HOME directory of the current user. It's possible to specify other
                such top-level directories. The toplevel directories can be remote directories
                as well. The class handles the events of the file and folder context menus and
                communicates using signals with QuantaApp, for example to indicate that
                a file must be opened.
                It's an extension of the KFileTreeView.

ProjectTree* : an extension of the FilesTree* classes to show the project files in a
               tree. The project files are not what are under the project directory, but
               only those that are listed in the .webprj file. Communicates with QuantaApp
               and the Project object via signals. It's a singleton class.

TemplatesTree*: an extension of the FilesTree* classes to show the three special
               template directories (global, local and project template directory). Handles
               template specific actions (insert, template settings, send in email), D&D.
               It's a singleton.

ScriptTreeView: an extension of FilesTreeView class which shows the global and
               local script directories, makes possible to execute or edit the scripts,
               view or edit their descriptions.

StructTreeView: the visual representation of the internal node tree. Build the visual
                tree from the node tree,  makes possible to navigate through the document
                using the tree.

StructTreeTag: an element of the structure tree. Every element has an associated Node
                and the element is included in the listItems of the Node.
                The problem checker is done in the constructor of the StructTreeTag element,
                by verifying if the Node associated with the element holds a valid Tag for the
                current DTD and the relation between the Node and the surrounding nodes
                are valid in this DTD.

UploadTree*: a treeview and it's file/folder elements with a special look. There is a
                column with a 3 state checkbox. In case of folders checked means that
                every element under the folder is checked, un-checked means that none
                of the elements under the folder are checked and grayed means that some
                elements (but not all) are checked. Used in the project upload dialog, the
                project folder scanning dialog and in the new project wizard.

TagAttributeTree/EnhancedTagAttributeTree/EditableTree/
DualEditableTree/TopLevelItem/Attribute*: classes used to edit the attributes of a tag.

DocTreeView/DocItem/DocFolder: the treeview and it's elements which show the
                different loaded documentation files, including the project documentation.
                The tree shows the documentation titles and the content is opened in a
                HTML part embedded in a QuantaView or a separated toolview.


5. project directory
---------------------
- project management related classes

Project: the main project management class. Loads, stores, modifies the .webprj file.
             Project related actions like project rescan, new project, project upload,
             project properties, adding/removing files to the project are handled here.
             It's a singleton.

ProjectNew*: classes for different stages of the new project wizard. They are
             instantiated from the Project object.

ProjectUpload: class that handles uploading of project files. It has also a special mode
            when the UI is minimized and in this mode the class can be used to modify
            the upload profiles.

RescanPrj: class that handles rescanning of the project directory and marking the
            files that are under the directory but not in the .webprj file. It does not show
            or mark the files that are excluded from the project in the project options.

ProjectURL: an extended KURL with some status informations including description,
            upload status and a note if the URL is a document-base folder or not.
            Used inside Project and the other classes dealing with the project files (ProjectUpload, ProjectTreeView)


6. plugins directory
---------------------
- (mainly) classes related to the plugin system

QuantaPlugin: manages a configured Quanta plugin (a KPart). Takes care of loading and
                     unloading of the part, embedding it in a widget and calling the part's
                     openURL method with the configured argument. Special plugins that
                     needs to have a more detailed communication with Quanta can have
                     a plugin class inherited from QuantaPlugin.

QuantaPluginInterface: the interface between QuantaApp and the QuantaPlugins. Reads
                     the plugins, returns pointers to them on request, validates them, etc.

QuantaPluginEditor and QuantaPluginConfig: classes which helps configuring the plugins.

SpellChecker: Quanta specific spellchecker. Not a real QuantaPlugin and most probably
                    it belongs to the utility directory.


7. parts directory
------------------
- KParts used inside Quanta.

WHTMLPart: simple KHTML based class which can display HTML pages. Used in preview
                    and documentation.

kafka directory: VPL related classes


8. messages directory
------------------------
- messaging system

MessageOutput/MessageItem: widget to show messages from external applications or
                      from Quanta. Used to display the result of actions, but used by the
                      Problem reporter as well. It has a methods to find the line and column
                      number inside a message and clicking on a text containing the line and
                      column moves the cursor in the editor to that position.


9. dialogs directory
---------------------
- some dialog implementations used in Quanta. The settings subdirectory contains the
widget implementations for the different Quanta setting pages, the tagdialog directory
contains classes dealing with the tagXML dialogs.

ActionConfigDialog: makes TagAction configuration possible. Displays all possible
                      actions (not just TagActions) in a tree, all loaded user toolbars with
                      the actions on them. TagActions can be created, deleted, modified and
                      plugged/unplugged in a user toolbar.

CopyTo: class which is used in many places to do asynchronous file copy. It signals
              when the file copy is done and the object can be deleted. Mainly used
              inside the Project* classes to add files to the project.

DirtyDlg: dialog offering some possibilities for the user when a document was changed
              outside of Quanta. In case of comparing the files it launches Kompare, waits
              until it finishes and returns afterwards, this way blocking Quanta while Kompare
              is running.

FileCombo: widget class offering a combobox and a button to select files. Used in the
              Tagxml class.

SpecialCharDialog: a dialog which offers the user a list of special characters.

AbbreviationDlg: handles the code abbreviations (adding/removing/editing them)

FileMasks: a badly named class. Currently takes care of editing the environment settings.

ParserOptions: make possible to finetune the parser and the structure tree behavior.

PreviewOptions: another not so well named class, as currently it makes possible to
                configure the UI look and behavior. Between others it offers possibility to
                change the preview and documentation location, the tab and toolview
                behavior, etc.

tagdialogs directory: classes and widgets used to build a dialog from a tagXML file, which
                makes possible to edit a tag in a document. Based on a Tag and the
                corresponding QTag.


10. components directory
---------------------------
- holds classes dealing with specific functions, many are DTD specific.

csseditor directory: classes for the visual CSS editor

cvsservice directory: a classes providing CVS functions for different context menus
              (document context menu, treeview context menus) using cvsservice from
              Cervisia.

debugger directory: classes providing interface towards different debuggers, including
              the Gubed PHP debugger.

framewizard directory: classes for the visual HTML framewizard (frame editor)

tableeditor directory: dialog to visually edit HTML tables