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 "support/strfwd.h"
35 /// The main application class
37 There should be only one instance of this class. No Qt object
38 initialisation should be done before the instantiation of this class.
40 Model/View/Controller separation at frontend level in qt frontend:
42 BufferList (N Buffers)
49 Application (this is the frontend really, should probably be renamed).
51 GuiView-1 (one or more in case of split-view mode).
55 | | WorkArea-1-1-1 (M1-1 WorkAreas, M1-1 <= N)
57 | | | BufferView <-----------> Buffer-c
63 | | | BufferView <-----------> Buffer-a
69 GuiView-2 (one or more in case of split-view mode).
73 | | WorkArea-2-1-1 (M2-1 WorkAreas, M2-1 <= N, M2-1 independent of M1-1)
77 1) The Model: \c Buffer
79 The Buffer is the in-memory representation of a LyX file format. The
80 Buffer does not (should not) have any information on what part of it
81 is represented on screen. There is one unique Buffer per opened LyX
82 file. A Buffer may or may not be represented on screen; typically, a
83 child document does not have an associated BufferView unless the user
84 choose to visualize it.
87 2) The Controller: \c BufferView / \c Painter \c Cursor
89 The BufferView is a tool used by the view (\sa WorkArea) that
90 translates a part of the Buffer contents into drawing routines. The
91 BufferView asks each inset of the Buffer to draw itself onto the
92 screen using the Painter. There can be only one Buffer displayed in
93 a BufferView and it is set on construction. Ideally, a BufferView
94 should not be able to change the contents of its associated Buffer.
95 A BufferView is instantiated and destroyed by a \c WorkArea; it is
96 automatically destroyed by the parent WorkArea when its Buffer is
99 \todo Move all Buffer changing LFUN to Buffer::dispatch(),
100 LyXFunc::dispatch() or Cursor::dispatch().
101 \todo BufferView::buffer() should only offer const access.
103 The \c Painter is just a virtual interface to formalize each kind of
104 drawing routines (text, line, rectangle, etc).
106 The \c BufferView also contains a Cursor which may or may not be
107 visible on screen. The cursor is really just a bookmark to remember
108 where the next Buffer insertion/deletion is going to take place.
111 3) The View: \c WorkArea (and its qt specialisation GuiWorkArea)
113 This contains the real screen area where the drawing is done by the
114 Painter. One WorkArea holds one unique \c BufferView. While it could
115 be possible that multiple WorkArea share one BufferView, this is not
116 something desirable because a BufferView is dependent of the WorkArea
118 The WorkArea also provide a scrollbar which position is translated
119 into scrolling command to the inner \c BufferView.
121 The WorkArea use the BufferView to translate each keyboard or mouse
122 events into terms that the Buffer can understand:
128 4) The Window: \c GuiView
130 This is a full window containing a menubar, toolbars and a central
131 widget. A GuiView is in charge of creating and closing a View for a
133 In the qt specialisation, \c GuiView, the central widget is a tab
134 widget. Each tab is reserved to the visualisation of one Buffer and
135 contains one WorkArea. In the qt frontend, one GuiView thus contains
136 multiple WorkAreas but this number can limited to one for another
137 frontend. The idea is that the kernel should not know how a Buffer
138 is displayed on screen; it's the frontend business.
139 It is also possible to have multiple Workareas showing
140 simultaneously in the same GuiView (ex: with split window), thus
141 sharing the menubar and toolbars.
143 In any case, there should be only one WorkArea that gets the focus
146 With our current implementation using a QTabWidget, each Tab own its
147 own \c WorkArea. Clicking on a tab switch a WorkArea and not really
148 a Buffer. LFUN_BUFFER_SWITCH will tell the frontend to search the
149 WorkArea associated to this Buffer. The WorkArea is automatically
150 created if not already present.
152 A WorkArea is connected to the Buffer::closing signal and is thus
153 automatically destroyed when its Buffer is closed.
162 virtual ~Application() {}
164 /// LyX dispatcher: executes lyx actions and does necessary
165 /// screen updates depending on results.
166 /// This method encapsulates all the LyX command operations.
167 /// This is the class of the LyX's "high level event handler".
168 /// Every user command is processed here, either invocated from
169 /// keyboard or from the GUI. All GUI objects, including buttons and
170 /// menus should use this class and never call kernel functions directly.
171 virtual DispatchResult const & dispatch(FuncRequest const &) = 0;
173 /// LyX dispatcher: executes lyx actions and returns result.
174 virtual void dispatch(FuncRequest const &, DispatchResult & dr) = 0;
177 virtual FuncStatus getStatus(FuncRequest const & cmd) const = 0;
179 /// Load files and restore GUI Session.
180 virtual void restoreGuiSession() = 0;
183 virtual Buffer const * updateInset(Inset const * inset) const = 0;
185 /// Start the main event loop.
186 /// The batch command is programmed to be execute once
187 /// the event loop is started.
188 virtual int exec() = 0;
190 /// Quit running LyX.
192 * This may either quit directly or record the exit status
193 * and only stop the event loop.
195 virtual void exit(int status) = 0;
198 * Given col, fills r, g, b in the range 0-255.
199 * The function returns true if successful.
200 * It returns false on failure and sets r, g, b to 0.
202 virtual bool getRgbColor(ColorCode col, RGBColor & rgbcol) = 0;
203 /// Like getRgbColor(), but static and slower
204 static bool getRgbColorUncached(ColorCode col, RGBColor & rgbcol);
207 * @return true if LyX uses a dark theme
209 virtual bool isInDarkMode() = 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 std::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 virtual bool hasBufferView() const = 0;
234 /// \return the icon file name for the given action.
235 static docstring iconName(FuncRequest const & f, bool unknown);
236 /// \return the math icon name for the given command.
237 static docstring mathIcon(docstring const & c);
239 /// The language associated to current keyboard
240 virtual std::string inputLanguageCode() const = 0;
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;
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;
254 // Add a buffer to the current view, do not switch to it.
255 virtual bool unhide(Buffer * buf) = 0;
258 /// Return the list of loadable formats.
259 std::vector<std::string> loadableImageFormats();
261 } // namespace frontend
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
272 #endif // APPLICATION_H