src/frontends/Application.h

   1 /**
   2  * \file frontend/Application.h
   3  * This file is part of LyX, the document processor.
   4  * Licence details can be found in the file COPYING.
   5  *
   6  * \author Abdelrazak Younes
   7  *
   8  * Full author contact details are available in file CREDITS.
   9  */
  10
  11 #ifndef APPLICATION_H
  12 #define APPLICATION_H
  13
  14 #include "ColorCode.h"
  15
  16 #include "support/strfwd.h"
  17
  18 #include <boost/function.hpp>
  19
  20
  21 namespace lyx {
  22
  23 class BufferView;
  24 class Buffer;
  25 class FuncRequest;
  26 class FuncStatus;
  27 class Inset;
  28 class MenuBackend;
  29 struct RGBColor;
  30
  31 namespace frontend {
  32
  33 class Clipboard;
  34 class FontLoader;
  35 class Gui;
  36 class LyXView;
  37 class Selection;
  38
  39 /// The main application class
  40 /**
  41 There should be only one instance of this class. No Qt object
  42 initialisation should be done before the instanciation of this class.
  43
  44  Model/View/Controller separation at frontend level in LyX-qt4:
  45
  46  BufferList (N Buffers)
  47    |
  48    Buffer-a
  49    Buffer-b
  50    Buffer-c
  51    Buffer-d
  52
  53  Application (this is the frontend really, should probably be renamed).
  54    |
  55    LyXView-1 (M1 WorkAreas, M1 <= N)
  56    |  |
  57    |  <tab-widget>
  58    |     | (many)
  59    |     WorkArea-1
  60    |       |
  61    |       BufferView <-----------> Buffer-c
  62    |         |
  63    |         Cursor
  64    |
  65    LyXView-2 (M2 WorkAreas, M2 <= N, M2 independent of M1)
  66       |
  67      ...
  68
  69
  70  1) The Model: \c Buffer
  71
  72  The Buffer is the in-memory representation of a LyX file format. The
  73  Buffer does not (should not) have any information on what part of it
  74  is represented on screen. There is one unique Buffer per opened LyX
  75  file. A Buffer may or may not be represented on screen; typically, a
  76  child document does not have an associated BufferView unless the user
  77  choose to visualize it.
  78
  79
  80  2) The Controller: \c BufferView / \c Painter \c Cursor
  81
  82  The BufferView is a tool used by the view (\sa WorkArea) that
  83  translates a part of the Buffer contents into drawing routines. The
  84  BufferView asks each inset of the Buffer to draw itself onto the
  85  screen using the Painter. There can be only one Buffer displayed in
  86  a BufferView and it is set on construction. Ideally, a BufferView
  87  should not be able to change the contents of its associated Buffer.
  88  A BufferView is instanciated and destroyed by a \c WorkArea; it is
  89  automatically destroyed by the parent WorkArea when its Buffer is
  90  closed.
  91
  92  \todo Move all Buffer changing LFUN to LyXFunc or Cursor.
  93  \todo BufferView::buffer() should only offer const access.
  94
  95  The \c Painter is just a virtual interface to formalize each kind of
  96  drawing routines (text, line, rectangle, etc).
  97
  98  The \c BufferView also contains a Cursor which may or may not be
  99  visible on screen. The cursor is really just a bookmark to remember
 100  where the next Buffer insertion/deletion is going to take place.
 101
 102
 103  3) The View: \c WorkArea (and it's qt4 specialisation GuiWorkArea)
 104
 105  This contains the real screen area where the drawing is done by the
 106  Painter. One WorkArea holds one unique \c BufferView. While it could
 107  be possible that multiple WorkArea share one BufferView, this is not
 108  something desirable because a BufferView is dependent of the WorkArea
 109  size.
 110  The WorkArea also provide a scrollbar which position is translated
 111  into scrolling command to the inner \c BufferView.
 112
 113  The WorkArea use the BufferView to translate each keyboard or mouse
 114  events into terms that the Buffer can understand:
 115  - insert/delete char
 116  - select char
 117  - etc.
 118
 119
 120  4) The Window: \c LyXView (and its qt4 specialisation \c GuiView)
 121
 122  This is a full window containing a menubar, toolbars and a central
 123  widget. A LyXView is in charge of creating and closing a View for a
 124  given Buffer.
 125  In the qt4 specialisation, \c GuiView, the central widget is a tab
 126  widget. Each tab is reverved to the visualisation of one Buffer and
 127  contains one WorkArea. In the qt4 frontend, one LyXView thus contains
 128  multiple WorkAreas but this number can limited to one for another
 129  frontend. The idea is that the kernel should not know how a Buffer
 130  is displayed on screen; it's the frontend business.
 131  In the future, we may also have multiple Workareas showing
 132  simultaneously in the same GuiView (ex: with split window).
 133
 134  \todo Implement split-window
 135
 136  In any case, there would be only one WorkArea that gets the focus
 137  at a time.
 138
 139  With our current implementation using a QTabWidget, each Tab own its
 140  own \c WorkArea. Clicking on a tab switch a WorkArea and not really
 141  a Buffer. LFUN_BUFFER_SWITCH will tell the frontend to search the
 142  WorkArea associated to this Buffer. The WorkArea is automatically
 143  created if not already present.
 144
 145  A WorkArea is connected to the Buffer::closing signal and is thus
 146  automatically destroyed when its Buffer is closed.
 147
 148 */
 149 class Application
 150 {
 151 public:
 152         ///
 153         Application() {}
 154         ///
 155         virtual ~Application() {}
 156
 157         ///
 158         virtual FuncStatus getStatus(FuncRequest const & cmd) = 0;
 159         /// dispatch command.
 160         /// \return true if the \c FuncRequest has been dispatched.
 161         virtual bool dispatch(FuncRequest const & cmd) = 0;
 162
 163         ///
 164         virtual void resetGui() = 0;
 165
 166         ///
 167         virtual void hideDialogs(std::string const & name, Inset * inset) const = 0;
 168         ///
 169         virtual Buffer const * updateInset(Inset const * inset) const = 0;
 170
 171         /// Start the main event loop.
 172         /// The batch command is programmed to be execute once
 173         /// the event loop is started.
 174         virtual int exec() = 0;
 175
 176         /// Quit running LyX.
 177         /**
 178         * This may either quit directly or record the exit status
 179         * and only stop the event loop.
 180         */
 181         virtual void exit(int status) = 0;
 182
 183         /**
 184         * Given col, fills r, g, b in the range 0-255.
 185         * The function returns true if successful.
 186         * It returns false on failure and sets r, g, b to 0.
 187         */
 188         virtual bool getRgbColor(ColorCode col, RGBColor & rgbcol) = 0;
 189
 190         /** Eg, passing Color_black returns "000000",
 191         *      passing Color_white returns "ffffff".
 192         */
 193         virtual std::string const hexName(ColorCode col) = 0;
 194
 195         /**
 196         * update an altered GUI color
 197         */
 198         virtual void updateColor(ColorCode col) = 0;
 199
 200         /**
 201         * add a callback for socket read notification
 202         * @param fd socket descriptor (file/socket/etc)
 203         */
 204         typedef boost::function<void()> SocketCallback;
 205         virtual void registerSocketCallback(int fd, SocketCallback func) = 0;
 206
 207         /**
 208         * remove a I/O read callback
 209         * @param fd socket descriptor (file/socket/etc)
 210         */
 211         virtual void unregisterSocketCallback(int fd) = 0;
 212
 213         ///
 214         virtual MenuBackend const & menuBackend() const = 0;
 215         virtual MenuBackend & menuBackend() = 0;
 216 };
 217
 218 } // namespace frontend
 219
 220 frontend::Application * theApp();
 221 frontend::Application * createApplication(int & argc, char * argv[]);
 222
 223 } // namespace lyx
 224
 225
 226 #endif // APPLICATION_H