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