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