4 * This file is part of LyX, the document processor.
5 * Licence details can be found in the file COPYING.
7 * \author Angus Leeming
9 * Full author contact details are available in file CREDITS.
18 #include "support/docstring.h"
20 #include <boost/utility.hpp>
21 #include <boost/scoped_ptr.hpp>
28 /** \c Dialog collects the different parts of a Model-Controller-View
29 * split of a generic dialog together.
31 class Dialog /*: boost::noncopyable*/ {
33 /// \param lv is the access point for the dialog to the LyX kernel.
34 /// \param name is the identifier given to the dialog by its parent
36 Dialog(LyXView & lv, std::string const & name);
39 /** The Dialog's name is the means by which a dialog identifies
40 * itself to the kernel.
42 std::string const & name() const { return name_; }
44 /** \name Container Access
45 * These methods are publicly accessible because they are invoked
46 * by the parent container acting on commands from the LyX kernel.
49 /// \param data is a string encoding of the data to be displayed.
50 /// It is passed to the Controller to be translated into a useable form.
51 void show(std::string const & data);
52 void update(std::string const & data);
55 bool isVisible() const;
57 // Override in GuiDialog
58 virtual void preShow() {}
59 virtual void postShow() {}
60 virtual void preUpdate() {}
61 virtual void postUpdate() {}
63 virtual void OkButton() {}
64 virtual void ApplyButton() {}
65 virtual void CancelButton() {}
66 virtual void RestoreButton() {}
68 /** This function is called, for example, if the GUI colours
74 /** Check whether we may apply our data.
76 * The buttons are disabled if not and (re-)enabled if yes.
80 /** When applying, it's useful to know whether the dialog is about
81 * to close or not (no point refreshing the display for example).
83 bool isClosing() const { return is_closing_; }
85 /** The LyX kernel is made available through this wrapper class.
86 * In an ideal world, it will shrink as more info is passed to the
87 * show() and update() methods.
89 Kernel & kernel() { return kernel_; }
91 /** Different dialogs will have different Controllers and Views.
92 * deriving from these base classes.
99 /** \name Dialog Specialization
100 * Methods to set the Controller and View and so specialise
101 * to a particular dialog.
104 /// \param ptr is stored and destroyed by \c Dialog.
105 void setController(Controller * ptr);
106 /// \param ptr is stored and destroyed by \c Dialog.
107 void setView(View * ptr);
110 /** \name Dialog Components
111 * Methods to access the various components making up a dialog.
114 Controller & controller() const;
119 virtual void setButtonsValid(bool valid);
126 boost::scoped_ptr<Controller> controller_ptr_;
127 boost::scoped_ptr<View> view_ptr_;
131 /** \c Dialog::Controller is an abstract base class for the Controller
132 * of a Model-Controller-View split of a generic dialog.
134 class Dialog::Controller : boost::noncopyable {
136 /// \param parent Dialog owning this Controller.
137 Controller(Dialog & parent);
138 virtual ~Controller() {}
140 /** \name Generic Controller
141 * These few methods are all that a generic dialog needs of a
145 /** Enable the controller to initialise its data structures.
146 * \param data is a string encoding of the parameters to be displayed.
147 * \return true if the translation was successful.
149 virtual bool initialiseParams(std::string const & data) = 0;
151 /// Enable the controller to clean up its data structures.
152 virtual void clearParams() = 0;
154 /// Enable the Controller to dispatch its data back to the LyX kernel.
155 virtual void dispatchParams() = 0;
157 /** \return true if the dialog should be shown only when
160 virtual bool isBufferDependent() const = 0;
162 /** \return true if the dialog can apply data also
163 * for ReadOnly buffers.
164 * This has to be distinguished from isBufferDependent()
166 virtual bool canApplyToReadOnly() const { return false; }
168 /** The lfun that is sent for applying the data.
170 * This method is used by the default implementation of canApply()
171 * for buffer dependent dialogs that send one lfun when applying the
173 * It should be used in dispatchParams(), too for consistency reasons.
174 * \returns the lfun that is sent for applying the data.
176 virtual kb_action getLfun() const { return LFUN_INSET_APPLY; }
178 /** Check whether we may apply our data.
180 * The default implementation works for all dialogs that send one
181 * lfun when applying the data. Dialogs that send none or more than
182 * one lfun need to reimplement it.
183 * \returns whether the data can be applied or not.
185 virtual bool canApply() const;
187 /** \return true if the kernel should disconnect the dialog from
188 * a particular inset after the data has been applied to it.
189 * Clearly this makes sense only for dialogs modifying the contents
191 * In practise, only a very few dialogs (e.g. the citation dialog)
194 virtual bool disconnectOnApply() const { return false; }
196 /** \return true if Dialog::View::show() should not display the dialog
197 * after running update. Currently, only ControlSpellchecker
200 virtual bool exitEarly() const { return false; }
203 /// Main Window access.
204 /// This is unfortunately needed for the qt4 frontend and the \c
205 /// QDialogView framework. This permits to give a parent to the
206 /// constructed \c QDialog via a cast to \c GuiView.
207 LyXView * view() { return &parent_.kernel().lyxview(); }
210 /** \name Controller Access
211 * Enable the derived classes to access the other parts of the whole.
214 Dialog & dialog() { return parent_; }
215 Dialog const & dialog() const { return parent_; }
217 Kernel & kernel() { return parent_.kernel(); }
218 Kernel const & kernel() const { return parent_.kernel(); }
226 /** \c Dialog::View is an abstract base class to the View
227 * of a Model-Controller-View split of a generic dialog.
229 class Dialog::View : boost::noncopyable {
231 /** \param parent Dialog owning this Controller.
232 * \param title is the dialog title displayed by the WM.
234 View(Dialog & parent, docstring title);
237 /** \name Generic View
238 * These few methods are all that a generic dialog needs of a
242 /** A request to modify the data structures stored by the
243 * accompanying Controller in preparation for their dispatch to
246 virtual void apply() = 0;
248 /// Hide the dialog from sight
249 virtual void hide() = 0;
251 /// Redraw the dialog (e.g. if the colors have been remapped).
252 virtual void redraw() {}
254 /// Create the dialog if necessary, update it and display it.
255 virtual void show() = 0;
257 /// Update the display of the dialog whilst it is still visible.
258 virtual void update() = 0;
260 /// \return true if the dialog is visible.
261 virtual bool isVisible() const = 0;
264 /** Defaults to nothing. Can be used by the Controller, however, to
265 * indicate to the View that something has changed and that the
266 * dialog therefore needs updating.
267 * \param id identifies what should be updated.
269 virtual void partialUpdate(int id);
271 /// sets the title of the dialog (window caption)
272 void setTitle(docstring const &);
273 /// gets the title of the dialog (window caption)
274 docstring const & getTitle() const;
276 /** \name View Access
277 * Enable the derived classes to access the other parts of the whole.
280 Dialog & dialog() { return p_; }
281 Dialog const & dialog() const { return p_; }
284 Kernel & kernel() { return p_.kernel(); }
285 Kernel const & kernel() const { return p_.kernel(); }
287 Controller & getController() { return p_.controller(); }
288 Controller const & getController() const { return p_.controller(); }
296 } // namespace frontend