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 void resetGui() = 0;
 156
 157         ///
 158         virtual bool closeAllViews() = 0;
 159         ///
 160         virtual size_t viewCount() const = 0;
 161         ///
 162         virtual void hideDialogs(std::string const & name, Inset * inset) const = 0;
 163         ///
 164         virtual Buffer const * updateInset(Inset const * inset) const = 0;
 165
 166         /// Start the main event loop.
 167         /// The batch command is programmed to be execute once
 168         /// the event loop is started.
 169         virtual int exec() = 0;
 170
 171         /// Quit running LyX.
 172         /**
 173         * This may either quit directly or record the exit status
 174         * and only stop the event loop.
 175         */
 176         virtual void exit(int status) = 0;
 177
 178         /**
 179         * Given col, fills r, g, b in the range 0-255.
 180         * The function returns true if successful.
 181         * It returns false on failure and sets r, g, b to 0.
 182         */
 183         virtual bool getRgbColor(ColorCode col, RGBColor & rgbcol) = 0;
 184
 185         /** Eg, passing Color_black returns "000000",
 186         *      passing Color_white returns "ffffff".
 187         */
 188         virtual std::string const hexName(ColorCode col) = 0;
 189
 190         /**
 191         * update an altered GUI color
 192         */
 193         virtual void updateColor(ColorCode col) = 0;
 194
 195         /**
 196         * add a callback for socket read notification
 197         * @param fd socket descriptor (file/socket/etc)
 198         */
 199         typedef boost::function<void()> SocketCallback;
 200         virtual void registerSocketCallback(int fd, SocketCallback func) = 0;
 201
 202         /**
 203         * remove a I/O read callback
 204         * @param fd socket descriptor (file/socket/etc)
 205         */
 206         virtual void unregisterSocketCallback(int fd) = 0;
 207
 208         /// Create the main window with given geometry settings.
 209         /// \param geometry_arg: only for Windows platform.
 210         virtual LyXView & createView(std::string const & geometry_arg) = 0;
 211 };
 212
 213 } // namespace frontend
 214
 215 frontend::Application * theApp();
 216 frontend::Application * createApplication(int & argc, char * argv[]);
 217
 218 } // namespace lyx
 219
 220
 221 #endif // APPLICATION_H