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