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"
17 #include "KeyModifier.h"
19 #include "support/strfwd.h"
21 #include <boost/function.hpp>
46 /// The main application class
48 There should be only one instance of this class. No Qt object
49 initialisation should be done before the instanciation of this class.
51 Model/View/Controller separation at frontend level in LyX-qt4:
53 BufferList (N Buffers)
60 Application (this is the frontend really, should probably be renamed).
62 LyXView-1 (one or more in case of split-view mode).
66 | | WorkArea-1-1-1 (M1-1 WorkAreas, M1-1 <= N)
68 | | | BufferView <-----------> Buffer-c
74 | | | BufferView <-----------> Buffer-a
80 LyXView-2 (one or more in case of split-view mode).
84 | | WorkArea-2-1-1 (M2-1 WorkAreas, M2-1 <= N, M2-1 independent of M1-1)
88 1) The Model: \c Buffer
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.
98 2) The Controller: \c BufferView / \c Painter \c Cursor
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
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.
114 The \c Painter is just a virtual interface to formalize each kind of
115 drawing routines (text, line, rectangle, etc).
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.
122 3) The View: \c WorkArea (and it's qt4 specialisation GuiWorkArea)
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
129 The WorkArea also provide a scrollbar which position is translated
130 into scrolling command to the inner \c BufferView.
132 The WorkArea use the BufferView to translate each keyboard or mouse
133 events into terms that the Buffer can understand:
139 4) The Window: \c LyXView (and its qt4 specialisation \c GuiView)
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
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.
154 In any case, there should be only one WorkArea that gets the focus
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.
163 A WorkArea is connected to the Buffer::closing signal and is thus
164 automatically destroyed when its Buffer is closed.
173 virtual ~Application() {}
175 virtual LyXView
* currentWindow() = 0;
177 virtual bool getStatus(FuncRequest
const & cmd
, FuncStatus
& flag
) const = 0;
178 /// dispatch command.
179 virtual void dispatch(FuncRequest
const & cmd
, DispatchResult
& dr
) = 0;
182 virtual void resetGui() = 0;
184 /// Load files and restore GUI Session.
185 virtual void restoreGuiSession() = 0;
188 virtual void hideDialogs(std::string
const & name
, Inset
* inset
) const = 0;
190 virtual Buffer
const * updateInset(Inset
const * inset
) const = 0;
192 /// Start the main event loop.
193 /// The batch command is programmed to be execute once
194 /// the event loop is started.
195 virtual int exec() = 0;
197 /// Quit running LyX.
199 * This may either quit directly or record the exit status
200 * and only stop the event loop.
202 virtual void exit(int status
) = 0;
205 * Given col, fills r, g, b in the range 0-255.
206 * The function returns true if successful.
207 * It returns false on failure and sets r, g, b to 0.
209 virtual bool getRgbColor(ColorCode col
, RGBColor
& rgbcol
) = 0;
211 /** Eg, passing Color_black returns "000000",
212 * passing Color_white returns "ffffff".
214 virtual std::string
const hexName(ColorCode col
) = 0;
217 * add a callback for socket read notification
218 * @param fd socket descriptor (file/socket/etc)
220 typedef boost::function
<void()> SocketCallback
;
221 virtual void registerSocketCallback(int fd
, SocketCallback func
) = 0;
224 * remove a I/O read callback
225 * @param fd socket descriptor (file/socket/etc)
227 virtual void unregisterSocketCallback(int fd
) = 0;
229 virtual bool searchMenu(FuncRequest
const & func
,
230 docstring_list
& names
) const = 0;
232 /// \return the icon file name for the given action.
233 virtual docstring
iconName(FuncRequest
const & f
, bool unknown
) = 0;
235 /// Handle a accented char key sequence
236 /// FIXME: this is only needed for LFUN_ACCENT_* in Text::dispatch()
237 virtual void handleKeyFunc(FuncCode action
) = 0;
240 /// Return the list of loadable formats.
241 std::vector
<std::string
> loadableImageFormats();
243 } // namespace frontend
245 frontend::Application
* theApp();
246 frontend::Application
* createApplication(int & argc
, char * argv
[]);
247 void hideDialogs(std::string
const & name
, Inset
* inset
);
252 #endif // APPLICATION_H