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