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