Warning, /education/cantor/DESIGN is written in an unsupported language. File is not indexed.

0002 General:
0004 Cantor is designed to be very modular. It is split into these important parts:
0006 - Main application:
0007 The Cantor application itself is stored in the src/ directory. It implements the worksheet and all the
0008 Graphical user interface. It uses the Cantor library to access the different backends.
0009 Cantor consists of two important parts, a KPart that contains one Worksheet, and a shell,
0010 that contains several parts, and sorts them into Tabs.
0012 - Cantor library:
0013 The library provides all the interfaces for using the different Backends. It should be completely
0014 independent of the final graphical representation of the results. (e.g. always keep the possibility
0015 of a Cantor KRunner or plasmoid in mind). It resides in src/lib/
0017 - Backends
0018 The src/backends directory contains all the different Backends. They all reimplement the interfaces found in
0019 the Cantor library, to enable access to a math package. There are lots of different ways to communicate with the
0020 Math app. To check how a backend is designed, look at the DESIGN file in the backends directory.
0022 For dependencies between these modules, these rules apply:
0023 - everything can depend on lib
0024 - the main app can depend on any other module
0025 - lib doesn't depend on other modules
0026 - each backend, and the assistants only depend on lib
0029 Coding style:
0031 Generally Cantor follows the KDELibs coding style (see http://techbase.kde.org/Policies/Kdelibs_Coding_Style ).
0032 Some notes:
0033 - use 4 spaces for indentation
0034 - use m_ prefix for member variables. no other prefixes
0035 - for the library use d-pointers (see http://techbase.kde.org/Policies/Library_Code_Policy#D-Pointers) to allow binary compatibility later
0036 - if you add things to the library, remember to add apidocs
0039 The Worksheet:
0041 Cantor's worksheet is implemented as a QGraphicsScene (the Worksheet class) with a corresponding QGraphicsView (the WorksheetView class).
0042 Each entry in the worksheet is represented by its own WorksheetEntry, which is a subclass of QGraphicsObject.
0043 The entries can have child items to display text (WorksheetTextItem) or images (WorksheetImageItem). The layout of
0044 these child items is defined in WorksheetEntry::layOutForWidth(double width, bool force).
0045 To display the calculation results the special items TextResultItem, ImageResultItem and AnimationResultItem are available.
0047 The WorksheetEntry holds an Expression object, and reacts on its status changes, and arriving results.
0048 Also it is in charge of requesting Completions or SyntaxHelp.
0050 The worksheet also stores one instance of the EpsRenderer, which is used whenever eps images need to be displayed,
0051 e.g. in LaTeX results.
0053 Note: The HelpResult is not handled by the Entry, but by the Worksheet, and it forwards
0054 it's content outside of the part using a signal. So the CantorShell can show it in the
0055 side-panel.
0058 The library:
0059 The library consists of a bunch of interfaces, for the different backends, and some
0060 stuff that is useful for math applications, independent of the Design of the ui(not limited to Worksheet-interfaces).
0061 Things should not be depending on a specific backend, but it's acceptable to have interfaces only implemented by
0062 one backend. (although that might change once a better plugin infrastructure is in place)
0064 - Basic design of a backend:
0065 This is just a brief introduction of the concepts relevant to the Backends.
0066 For more information please see the apidocs of the relevant classes.
0067 For a simple sample of a backend you can look at the NullBackend. It only echoes
0068 the entered command, or shows an image if you type "img", so it akts as a good
0069 example on how to do things.
0071 Backends are implemented as plugins that are found on runtime, to allow easy installation of
0072 additional backends.
0074 A backend consists of the following parts:
0075 - Backend:
0076   This class is used to store some static information of the backend, like its name, some links, or the
0077   features it supports. Each backend can supply a widget, for changing the relevant settings.
0078 - Session:
0079   A session is where a connection to an instance of the math-app is created, e.g. by spawning a maxima process.
0080   It implements methods for evaluating expressions, it delivers a syntax highlighter, or CompletionObjects.
0081   The most important methods are login(), logout() and evaluateExpression(). see the apidocs for more information.
0082 - Expression:
0083   The Expression encapsulates one specific command send to the backend, and its result. It gets created by
0084   the session, and destroyed by the Worksheet when the entry is deleted or replaced by a new Expression.
0085   When the expression is run, it sends the command to the underlying backend to do the computation, and sets
0086   the state to Computing.
0087   Once the task is completed it should sets the state to Done or Error, depending on the result, to notify
0088   the worksheet that it is no longer busy.
0089   Once the result arrives, it emits the resultChanged() signal, so that the Worksheet can display it.
0090   Remember, the state and the result are independent, e.g. if you have typesetting enabled, the state will
0091   be set to done when the computation is finished, and the result will be set to a text-result. Once the
0092   typesetting is done the result changes again.
0094   To be as flexible as possible regarding different kinds of results (a computation can deliver some text,
0095   a plot, a formula, an animation etc.), Cantor uses the concept of Results.
0096   For each kind of result there is a subclass, that stores the information relevant for the kind of result
0097   (e.g. the text, the image, an url etc.). Your backend is in charge of creating the right Result Type, and
0098   feeding it the information. The ResultProxy is then used to render the result in the Worksheet(@see The Worksheet)
0101 - Syntax Highlighting:
0102   Syntax highlighting is a very useful feature for entering commands. In Cantor it's implemented using
0103   Qt's QSyntaxHighlighter functionality. The Session is in charge for creating a SyntaxHighlighter object,
0104   so it can access all the Session relevant information (if you want to). While you can use an ordinary
0105   QSyntaxHighlighter object, you may want to use the DefaultHighlighter class. It delivers highlighting for
0106   parenthesis, and information on the different Blocks inside a Worksheet, e.g. to check if the part
0107   you're highlighting is a command or not.
0109 - Completion:
0110   To allow Completion of partially entered Commands in a Backend-agnostic way, Cantor uses
0111   so called CompletionObjects. To get a completion, Cantor calls the Sessions completionFor
0112   method which is then in charge of creating a Backend-Specific CompletionObject.
0113   A CompletionObject should fetch the information from the backend, and emit the done()
0114   signal when finished, so the process of fetching should (but doesn't have to) be async
0115   to make sure the gui doesn't get blocked.
0117 - SyntaxHelp:
0118   Syntax Help is the little tooltip, you get when pressing Tab, on an already complete
0119   command, that shows syntax information (see Maxima or KAlgebra for an implementation).
0120   The concept works similar to Completion. Cantor asks the session for a SyntaxHelpObject
0121   which then fetches the information asynchronously, and emits done().
0123 - Extensions:
0124   To allow backend-independend functionalities like Assistant dialogs, Cantor uses so called
0125   Extensions.
0126   These are subclasses of the Cantor::Extension class, that are created by the backend,
0127   and that translate between Cantor and the Backends specific Syntax. For example the
0128   PlotExtension translates PlotExtension::plot2d("sin(x)","x","-3.14","3.14") to maxima
0129   syntax "plot2d(sin(x),[x,-3.14,3.14])"
0131 - Assistants
0132   Assistants are Dialogs, used for common tasks like entering a matrix, solving equations etc.
0133   Assistants are implemented as plugins, found at runtime. Each assistant has a list
0134   of Extensions it needs to work (located in the .desktop file), so they only will be shown
0135   for backends, capable of all the needed things. The Assistant will be run, and once it
0136   is finished, it returns a list of commands, to achieve the task. They will then be
0137   added to the Worksheet and executed.
0138   The philosophy behind this is not to hide the syntax from the user, so he may
0139   learn how things are done.
0140   NOTE: currently assistants can only work through extensions, but in the future,
0141   also backend-specific assistants will be possible.