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