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