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.
6 * \author Abdelrazak Younes
8 * Full author contact details are available in file CREDITS.
14 #include "ColorCode.h"
16 #include "support/strfwd.h"
17 #include "support/docstring.h"
19 #include <boost/function.hpp>
42 /// The main application class
44 There should be only one instance of this class. No Qt object
45 initialisation should be done before the instanciation of this class.
47 Model/View/Controller separation at frontend level in LyX-qt4:
49 BufferList (N Buffers)
56 Application (this is the frontend really, should probably be renamed).
58 LyXView-1 (one or more in case of split-view mode).
62 | | WorkArea-1-1-1 (M1-1 WorkAreas, M1-1 <= N)
64 | | | BufferView <-----------> Buffer-c
70 | | | BufferView <-----------> Buffer-a
76 LyXView-2 (one or more in case of split-view mode).
80 | | WorkArea-2-1-1 (M2-1 WorkAreas, M2-1 <= N, M2-1 independent of M1-1)
84 1) The Model: \c Buffer
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.
94 2) The Controller: \c BufferView / \c Painter \c Cursor
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
106 \todo Move all Buffer changing LFUN to LyXFunc or Cursor.
107 \todo BufferView::buffer() should only offer const access.
109 The \c Painter is just a virtual interface to formalize each kind of
110 drawing routines (text, line, rectangle, etc).
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.
117 3) The View: \c WorkArea (and it's qt4 specialisation GuiWorkArea)
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
124 The WorkArea also provide a scrollbar which position is translated
125 into scrolling command to the inner \c BufferView.
127 The WorkArea use the BufferView to translate each keyboard or mouse
128 events into terms that the Buffer can understand:
134 4) The Window: \c LyXView (and its qt4 specialisation \c GuiView)
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
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).
148 \todo Implement split-window
150 In any case, there would be only one WorkArea that gets the focus
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.
159 A WorkArea is connected to the Buffer::closing signal and is thus
160 automatically destroyed when its Buffer is closed.
169 virtual ~Application() {}
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;
178 virtual void resetGui() = 0;
180 /// Load files and restore GUI Session.
181 virtual void restoreGuiSession() = 0;
184 virtual void hideDialogs(std::string const & name, Inset * inset) const = 0;
186 virtual Buffer const * updateInset(Inset const * inset) const = 0;
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;
193 /// Quit running LyX.
195 * This may either quit directly or record the exit status
196 * and only stop the event loop.
198 virtual void exit(int status) = 0;
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.
205 virtual bool getRgbColor(ColorCode col, RGBColor & rgbcol) = 0;
207 /** Eg, passing Color_black returns "000000",
208 * passing Color_white returns "ffffff".
210 virtual std::string const hexName(ColorCode col) = 0;
213 * update an altered GUI color
215 virtual void updateColor(ColorCode col) = 0;
218 * read and create the menu structure
220 virtual void readMenus(Lexer & lex) = 0;
223 * initialize the global menubar on Mac
225 virtual void initGlobalMenu() = 0;
228 * add a callback for socket read notification
229 * @param fd socket descriptor (file/socket/etc)
231 typedef boost::function<void()> SocketCallback;
232 virtual void registerSocketCallback(int fd, SocketCallback func) = 0;
235 * remove a I/O read callback
236 * @param fd socket descriptor (file/socket/etc)
238 virtual void unregisterSocketCallback(int fd) = 0;
240 virtual bool searchMenu(FuncRequest const & func,
241 std::vector<docstring> & names) const = 0;
244 } // namespace frontend
246 frontend::Application * theApp();
247 frontend::Application * createApplication(int & argc, char * argv[]);
248 void hideDialogs(std::string const & name, Inset * inset);
253 #endif // APPLICATION_H