diff options
Diffstat (limited to 'quanta/DESIGN')
| -rw-r--r-- | quanta/DESIGN | 338 |
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
+
+
|