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         /// LyX dispatcher: executes lyx actions and does necessary
 178         /// screen updates depending on results.
 179         /// This method encapsulates all the LyX command operations.
 180         /// This is the class of the LyX's "high level event handler".
 181         /// Every user command is processed here, either invocated from
 182         /// keyboard or from the GUI. All GUI objects, including buttons and
 183         /// menus should use this class and never call kernel functions directly.
 184         virtual void dispatch(FuncRequest const &) = 0;
 185
 186         /// LyX dispatcher: executes lyx actions and returns result.
 187         virtual void dispatch(FuncRequest const &, DispatchResult & dr) = 0;
 188
 189         ///
 190         virtual FuncStatus getStatus(FuncRequest const & cmd) const = 0;
 191
 192         ///
 193         virtual void resetGui() = 0;
 194
 195         /// Load files and restore GUI Session.
 196         virtual void restoreGuiSession() = 0;
 197
 198         ///
 199         virtual void hideDialogs(std::string const & name, Inset * inset) const = 0;
 200         ///
 201         virtual Buffer const * updateInset(Inset const * inset) const = 0;
 202
 203         /// Start the main event loop.
 204         /// The batch command is programmed to be execute once
 205         /// the event loop is started.
 206         virtual int exec() = 0;
 207
 208         /// Quit running LyX.
 209         /**
 210         * This may either quit directly or record the exit status
 211         * and only stop the event loop.
 212         */
 213         virtual void exit(int status) = 0;
 214
 215         /**
 216         * Given col, fills r, g, b in the range 0-255.
 217         * The function returns true if successful.
 218         * It returns false on failure and sets r, g, b to 0.
 219         */
 220         virtual bool getRgbColor(ColorCode col, RGBColor & rgbcol) = 0;
 221
 222         /** Eg, passing Color_black returns "000000",
 223         *      passing Color_white returns "ffffff".
 224         */
 225         virtual std::string const hexName(ColorCode col) = 0;
 226
 227         /**
 228         * add a callback for socket read notification
 229         * @param fd socket descriptor (file/socket/etc)
 230         */
 231         typedef boost::function<void()> SocketCallback;
 232         virtual void registerSocketCallback(int fd, SocketCallback func) = 0;
 233
 234         /**
 235         * remove a I/O read callback
 236         * @param fd socket descriptor (file/socket/etc)
 237         */
 238         virtual void unregisterSocketCallback(int fd) = 0;
 239
 240         virtual bool searchMenu(FuncRequest const & func,
 241                 docstring_list & names) const = 0;
 242
 243         /// \return the icon file name for the given action.
 244         virtual docstring iconName(FuncRequest const & f, bool unknown) = 0;
 245
 246         /// Handle a accented char key sequence
 247         /// FIXME: this is only needed for LFUN_ACCENT_* in Text::dispatch()
 248         virtual void handleKeyFunc(FuncCode action) = 0;
 249 };
 250
 251 /// Return the list of loadable formats.
 252 std::vector<std::string> loadableImageFormats();
 253
 254 } // namespace frontend
 255
 256 frontend::Application * theApp();
 257 frontend::Application * createApplication(int & argc, char * argv[]);
 258 void hideDialogs(std::string const & name, Inset * inset);
 259
 260 } // namespace lyx
 261
 262
 263 #endif // APPLICATION_H