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.
11 #ifndef LYX_APPLICATION_H
12 #define LYX_APPLICATION_H
14 #include <boost/function.hpp>
32 /// The main application class
34 There should be only one instance of this class. No Qt object
35 initialisation should be done before the instanciation of this class.
37 Model/View/Controller separation at frontend level in LyX-qt4:
39 BufferList (N Buffers)
46 Application (this is the frontend really, should probably be renamed).
48 LyXView-1 (M1 WorkAreas, M1 <= N)
54 | BufferView <-----------> Buffer-c
58 LyXView-2 (M2 WorkAreas, M2 <= N, M2 independent of M1)
63 1) The Model: \c Buffer
65 The Buffer is the in-memory representation of a LyX file format. The
66 Buffer does not (should not) have any information on what part of it
67 is represented on screen. There is one unique Buffer per opened LyX
68 file. A Buffer may or may not be represented on screen; typically, a
69 child document does not have an associated BufferView unless the user
70 choose to visualize it.
73 2) The Controller: \c BufferView / \c Painter \c Cursor
75 The BufferView is a tool used by the view (\sa WorkArea) that
76 translates a part of the Buffer contents into drawing routines. The
77 BufferView asks each inset of the Buffer to draw itself onto the
78 screen using the Painter. There can be only one Buffer displayed in
79 a BufferView and it is set on construction. Ideally, a BufferView
80 should not be able to change the contents of its associated Buffer.
81 A BufferView is instanciated and destroyed by a \c WorkArea; it is
82 automatically destroyed by the parent WorkArea when its Buffer is
85 \todo Move all Buffer changing LFUN to LyXFunc or Cursor.
86 \todo BufferView::buffer() should only offer const access.
88 The \c Painter is just a virtual interface to formalize each kind of
89 drawing routines (text, line, rectangle, etc).
91 The \c BufferView also contains a Cursor which may or may not be
92 visible on screen. The cursor is really just a bookmark to remember
93 where the next Buffer insertion/deletion is going to take place.
96 3) The View: \c WorkArea (and it's qt4 specialisation GuiWorkArea)
98 This contains the real screen area where the drawing is done by the
99 Painter. One WorkArea holds one unique \c BufferView. While it could
100 be possible that multiple WorkArea share one BufferView, this is not
101 something desirable because a BufferView is dependent of the WorkArea
103 The WorkArea also provide a scrollbar which position is translated
104 into scrolling command to the inner \c BufferView.
106 The WorkArea use the BufferView to translate each keyboard or mouse
107 events into terms that the Buffer can understand:
113 4) The Window: \c LyXView (and its qt4 specialisation \c GuiView)
115 This is a full window containing a menubar, toolbars and a central
116 widget. A LyXView is in charge of creating and closing a View for a
118 In the qt4 specialisation, \c GuiView, the central widget is a tab
119 widget. Each tab is reverved to the visualisation of one Buffer and
120 contains one WorkArea. In the qt4 frontend, one LyXView thus contains
121 multiple WorkAreas but this number can limited to one for another
122 frontend. The idea is that the kernel should not know how a Buffer
123 is displayed on screen; it's the frontend business.
124 In the future, we may also have multiple Workareas showing
125 simultaneously in the same GuiView (ex: with split window).
127 \todo Implement split-window
129 In any case, there would be only one WorkArea that gets the focus
132 With our current implementation using a QTabWidget, each Tab own its
133 own \c WorkArea. Clicking on a tab switch a WorkArea and not really
134 a Buffer. LFUN_BUFFER_SWITCH will tell the frontend to search the
135 WorkArea associated to this Buffer. The WorkArea is automatically
136 created if not already present.
138 A WorkArea is connected to the Buffer::closing signal and is thus
139 automatically destroyed when its Buffer is closed.
146 Application(int & argc, char ** argv);
148 virtual ~Application() {}
151 virtual Gui & gui() = 0;
153 /// Start the main event loop.
154 /// The batch command is programmed to be execute once
155 /// the event loop is started.
156 virtual int const exec() = 0;
158 /// Quit running LyX.
160 * This may either quit directly or record the exit status
161 * and only stop the event loop.
163 virtual void exit(int status) = 0;
166 * Synchronise all pending events.
168 virtual void syncEvents() = 0;
170 virtual Clipboard & clipboard() = 0;
172 virtual Selection & selection() = 0;
174 virtual FontLoader & fontLoader() = 0;
176 /// return a suitable serif font name.
177 virtual std::string const romanFontName() = 0;
179 /// return a suitable sans serif font name.
180 virtual std::string const sansFontName() = 0;
182 /// return a suitable monospaced font name.
183 virtual std::string const typewriterFontName() = 0;
186 * Given col, fills r, g, b in the range 0-255.
187 * The function returns true if successful.
188 * It returns false on failure and sets r, g, b to 0.
190 virtual bool getRgbColor(Color_color col, RGBColor & rgbcol) = 0;
192 /** Eg, passing Color::black returns "000000",
193 * passing Color::white returns "ffffff".
195 virtual std::string const hexName(Color_color col) = 0;
198 * update an altered GUI color
200 virtual void updateColor(Color_color col) = 0;
203 * add a callback for socket read notification
204 * @param fd socket descriptor (file/socket/etc)
206 virtual void registerSocketCallback(
207 int fd, boost::function<void()> func) = 0;
210 * remove a I/O read callback
211 * @param fd socket descriptor (file/socket/etc)
213 virtual void unregisterSocketCallback(int fd) = 0;
215 /// Create the main window with given geometry settings.
216 LyXView & createView(unsigned int width, unsigned int height,
217 int posx, int posy, int maximized,
218 unsigned int iconSizeXY, const std::string & geometryArg);
221 LyXView const * currentView() const;
224 LyXView * currentView();
227 void setCurrentView(LyXView & current_view);
230 /// This LyXView is the one receiving Clipboard and Selection
232 LyXView * current_view_;
236 } // namespace frontend
238 frontend::Application * theApp();
239 frontend::Application * createApplication(int & argc, char * argv[]);
245 #endif // LYX_APPLICATION_H