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 struct RGBColor;
  29
  30 namespace frontend {
  31
  32 class Clipboard;
  33 class FontLoader;
  34 class Gui;
  35 class LyXView;
  36 class Selection;
  37
  38 /// The main application class
  39 /**
  40 There should be only one instance of this class. No Qt object
  41 initialisation should be done before the instanciation of this class.
  42
  43  Model/View/Controller separation at frontend level in LyX-qt4:
  44
  45  BufferList (N Buffers)
  46    |
  47    Buffer-a
  48    Buffer-b
  49    Buffer-c
  50    Buffer-d
  51
  52  Application (this is the frontend really, should probably be renamed).
  53    |
  54    LyXView-1 (M1 WorkAreas, M1 <= N)
  55    |  |
  56    |  <tab-widget>
  57    |     | (many)
  58    |     WorkArea-1
  59    |       |
  60    |       BufferView <-----------> Buffer-c
  61    |         |
  62    |         Cursor
  63    |
  64    LyXView-2 (M2 WorkAreas, M2 <= N, M2 independent of M1)
  65       |
  66      ...
  67
  68
  69  1) The Model: \c Buffer
  70
  71  The Buffer is the in-memory representation of a LyX file format. The
  72  Buffer does not (should not) have any information on what part of it
  73  is represented on screen. There is one unique Buffer per opened LyX
  74  file. A Buffer may or may not be represented on screen; typically, a
  75  child document does not have an associated BufferView unless the user
  76  choose to visualize it.
  77
  78
  79  2) The Controller: \c BufferView / \c Painter \c Cursor
  80
  81  The BufferView is a tool used by the view (\sa WorkArea) that
  82  translates a part of the Buffer contents into drawing routines. The
  83  BufferView asks each inset of the Buffer to draw itself onto the
  84  screen using the Painter. There can be only one Buffer displayed in
  85  a BufferView and it is set on construction. Ideally, a BufferView
  86  should not be able to change the contents of its associated Buffer.
  87  A BufferView is instanciated and destroyed by a \c WorkArea; it is
  88  automatically destroyed by the parent WorkArea when its Buffer is
  89  closed.
  90
  91  \todo Move all Buffer changing LFUN to LyXFunc or Cursor.
  92  \todo BufferView::buffer() should only offer const access.
  93
  94  The \c Painter is just a virtual interface to formalize each kind of
  95  drawing routines (text, line, rectangle, etc).
  96
  97  The \c BufferView also contains a Cursor which may or may not be
  98  visible on screen. The cursor is really just a bookmark to remember
  99  where the next Buffer insertion/deletion is going to take place.
 100
 101
 102  3) The View: \c WorkArea (and it's qt4 specialisation GuiWorkArea)
 103
 104  This contains the real screen area where the drawing is done by the
 105  Painter. One WorkArea holds one unique \c BufferView. While it could
 106  be possible that multiple WorkArea share one BufferView, this is not
 107  something desirable because a BufferView is dependent of the WorkArea
 108  size.
 109  The WorkArea also provide a scrollbar which position is translated
 110  into scrolling command to the inner \c BufferView.
 111
 112  The WorkArea use the BufferView to translate each keyboard or mouse
 113  events into terms that the Buffer can understand:
 114  - insert/delete char
 115  - select char
 116  - etc.
 117
 118
 119  4) The Window: \c LyXView (and its qt4 specialisation \c GuiView)
 120
 121  This is a full window containing a menubar, toolbars and a central
 122  widget. A LyXView is in charge of creating and closing a View for a
 123  given Buffer.
 124  In the qt4 specialisation, \c GuiView, the central widget is a tab
 125  widget. Each tab is reverved to the visualisation of one Buffer and
 126  contains one WorkArea. In the qt4 frontend, one LyXView thus contains
 127  multiple WorkAreas but this number can limited to one for another
 128  frontend. The idea is that the kernel should not know how a Buffer
 129  is displayed on screen; it's the frontend business.
 130  In the future, we may also have multiple Workareas showing
 131  simultaneously in the same GuiView (ex: with split window).
 132
 133  \todo Implement split-window
 134
 135  In any case, there would be only one WorkArea that gets the focus
 136  at a time.
 137
 138  With our current implementation using a QTabWidget, each Tab own its
 139  own \c WorkArea. Clicking on a tab switch a WorkArea and not really
 140  a Buffer. LFUN_BUFFER_SWITCH will tell the frontend to search the
 141  WorkArea associated to this Buffer. The WorkArea is automatically
 142  created if not already present.
 143
 144  A WorkArea is connected to the Buffer::closing signal and is thus
 145  automatically destroyed when its Buffer is closed.
 146
 147 */
 148 class Application
 149 {
 150 public:
 151         ///
 152         Application() {}
 153         ///
 154         virtual ~Application() {}
 155
 156         ///
 157         virtual FuncStatus getStatus(FuncRequest const & cmd) = 0;
 158         /// dispatch command.
 159         virtual void dispatch(FuncRequest const & cmd) = 0;
 160
 161         ///
 162         virtual void resetGui() = 0;
 163
 164         ///
 165         virtual bool closeAllViews() = 0;
 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         /// Create the main window with given geometry settings.
 214         /// \param geometry_arg: only for Windows platform.
 215         virtual void createView(std::string const & geometry_arg = std::string()) = 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