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 #include <vector>
  21
  22
  23 namespace lyx {
  24
  25 class BufferView;
  26 struct RGBColor;
  27 class Buffer;
  28 class Inset;
  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() : current_view_(0) {}
 153         ///
 154         virtual ~Application() {}
 155
 156         ///
 157         virtual int createRegisteredView() = 0;
 158         ///
 159         virtual bool unregisterView(int id) = 0;
 160         ///
 161         virtual bool closeAllViews() = 0;
 162
 163         ///
 164         virtual LyXView & view(int id) const = 0;
 165         ///
 166         std::vector<int> const & viewIds() { return view_ids_; }
 167
 168         ///
 169         virtual void hideDialogs(std::string const & name, Inset * inset) const = 0;
 170         ///
 171         virtual Buffer const * updateInset(Inset const * inset) const = 0;
 172
 173         /// Start the main event loop.
 174         /// The batch command is programmed to be execute once
 175         /// the event loop is started.
 176         virtual int exec() = 0;
 177
 178         /// Quit running LyX.
 179         /**
 180         * This may either quit directly or record the exit status
 181         * and only stop the event loop.
 182         */
 183         virtual void exit(int status) = 0;
 184
 185         /**
 186         * Synchronise all pending events.
 187         */
 188         virtual void syncEvents() = 0;
 189         ///
 190         virtual FontLoader & fontLoader() = 0;
 191
 192         /// return a suitable serif font name.
 193         virtual std::string const romanFontName() = 0;
 194
 195         /// return a suitable sans serif font name.
 196         virtual std::string const sansFontName() = 0;
 197
 198         /// return a suitable monospaced font name.
 199         virtual std::string const typewriterFontName() = 0;
 200
 201         /**
 202         * Given col, fills r, g, b in the range 0-255.
 203         * The function returns true if successful.
 204         * It returns false on failure and sets r, g, b to 0.
 205         */
 206         virtual bool getRgbColor(ColorCode col, RGBColor & rgbcol) = 0;
 207
 208         /** Eg, passing Color_black returns "000000",
 209         *      passing Color_white returns "ffffff".
 210         */
 211         virtual std::string const hexName(ColorCode col) = 0;
 212
 213         /**
 214         * update an altered GUI color
 215         */
 216         virtual void updateColor(ColorCode col) = 0;
 217
 218         /**
 219         * add a callback for socket read notification
 220         * @param fd socket descriptor (file/socket/etc)
 221         */
 222         typedef boost::function<void()> SocketCallback;
 223         virtual void registerSocketCallback(int fd, SocketCallback func) = 0;
 224
 225         /**
 226         * remove a I/O read callback
 227         * @param fd socket descriptor (file/socket/etc)
 228         */
 229         virtual void unregisterSocketCallback(int fd) = 0;
 230
 231         /// Create the main window with given geometry settings.
 232         /// \param geometry_arg: only for Windows platform.
 233         virtual LyXView & createView(std::string const & geometry_arg) = 0;
 234
 235         ///
 236         LyXView const * currentView() const { return current_view_; }
 237         ///
 238         LyXView * currentView() { return current_view_; }
 239         ///
 240         void setCurrentView(LyXView & view) { current_view_ = &view; }
 241
 242 protected:
 243         /// This LyXView is the one receiving Clipboard and Selection
 244         /// events
 245         LyXView * current_view_;
 246         ///
 247         std::vector<int> view_ids_;
 248 };
 249
 250 } // namespace frontend
 251
 252 frontend::Application * theApp();
 253 frontend::Application * createApplication(int & argc, char * argv[]);
 254
 255 } // namespace lyx
 256
 257
 258 #endif // APPLICATION_H