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