Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdewebdev@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 338 insertions, 0 deletions

diff --git a/quanta/DESIGN b/quanta/DESIGN
new file mode 100644
index 00000000..c2b6e68b
--- /dev/null
+++ b/quanta/DESIGN
@@ -0,0 +1,338 @@
+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

+

+