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