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>
29 class ButtonController;
31 /** \c Dialog collects the different parts of a Model-Controller-View
32 * split of a generic dialog together.
34 class Dialog /*: boost::noncopyable*/ {
36 /// \param lv is the access point for the dialog to the LyX kernel.
37 /// \param name is the identifier given to the dialog by its parent
39 Dialog(LyXView & lv, std::string const & name);
41 /** The Dialog's name is the means by which a dialog identifies
42 * itself to the kernel.
44 std::string const & name() const { return name_; }
47 * These methods are publicly accessible because they are invoked
48 * by the View when the user presses... guess what ;-)
57 /** \name Container Access
58 * These methods are publicly accessible because they are invoked
59 * by the parent container acting on commands from the LyX kernel.
62 /// \param data is a string encoding of the data to be displayed.
63 /// It is passed to the Controller to be translated into a useable form.
64 void show(std::string const & data);
65 void update(std::string const & data);
68 bool isVisible() const;
70 /** This function is called, for example, if the GUI colours
76 /** Check whether we may apply our data.
78 * The buttons are disabled if not and (re-)enabled if yes.
82 /** When applying, it's useful to know whether the dialog is about
83 * to close or not (no point refreshing the display for example).
85 bool isClosing() const { return is_closing_; }
87 /** The LyX kernel is made available through this wrapper class.
88 * In an ideal world, it will shrink as more info is passed to the
89 * show() and update() methods.
91 Kernel & kernel() { return kernel_; }
93 /** Different dialogs will have different Controllers and Views.
94 * deriving from these base classes.
101 /** \name Dialog Specialization
102 * Methods to set the Controller and View and so specialise
103 * to a particular dialog.
106 /// \param ptr is stored and destroyed by \c Dialog.
107 void setController(Controller * ptr);
108 /// \param ptr is stored and destroyed by \c Dialog.
109 void setView(View * ptr);
112 /** \name Dialog Components
113 * Methods to access the various components making up a dialog.
116 Controller & controller() const;
117 ButtonController & bc() const;
127 boost::scoped_ptr<ButtonController> bc_ptr_;
128 boost::scoped_ptr<Controller> controller_ptr_;
129 boost::scoped_ptr<View> view_ptr_;
133 /** \c Dialog::Controller is an abstract base class for the Controller
134 * of a Model-Controller-View split of a generic dialog.
136 class Dialog::Controller : boost::noncopyable {
138 /// \param parent Dialog owning this Controller.
139 Controller(Dialog & parent);
140 virtual ~Controller() {}
142 /** \name Generic Controller
143 * These few methods are all that a generic dialog needs of a
147 /** Enable the controller to initialise its data structures.
148 * \param data is a string encoding of the parameters to be displayed.
149 * \return true if the translation was successful.
151 virtual bool initialiseParams(std::string const & data) = 0;
153 /// Enable the controller to clean up its data structures.
154 virtual void clearParams() = 0;
156 /// Enable the Controller to dispatch its data back to the LyX kernel.
157 virtual void dispatchParams() = 0;
159 /** \return true if the dialog should be shown only when
162 virtual bool isBufferDependent() const = 0;
164 /** The lfun that is sent for applying the data.
166 * This method is used by the default implementation of canApply()
167 * for buffer dependent dialogs that send one lfun when applying the
169 * It should be used in dispatchParams(), too for consistency reasons.
170 * \returns the lfun that is sent for applying the data.
172 virtual kb_action getLfun() const { return LFUN_INSET_APPLY; }
174 /** Check whether we may apply our data.
176 * The default implementation works for all dialogs that send one
177 * lfun when applying the data. Dialogs that send none or more than
178 * one lfun need to reimplement it.
179 * \returns whether the data can be applied or not.
181 virtual bool canApply() const;
183 /** \return true if the kernel should disconnect the dialog from
184 * a particular inset after the data has been applied to it.
185 * Clearly this makes sense only for dialogs modifying the contents
187 * In practise, only a very few dialogs (e.g. the citation dialog)
190 virtual bool disconnectOnApply() const { return false; }
192 /** \return true if Dialog::View::show() should not display the dialog
193 * after running update. Currently, only ControlSpellchecker
196 virtual bool exitEarly() const { return false; }
199 /// Main Window access.
200 /// This is unfortunately needed for the qt4 frontend and the \c
201 /// QDialogView framework. This permits to give a parent to the
202 /// constructed \c QDialog via a cast to \c GuiView.
203 LyXView * view() { return &parent_.kernel().lyxview(); }
206 /** \name Controller Access
207 * Enable the derived classes to access the other parts of the whole.
210 Dialog & dialog() { return parent_; }
211 Dialog const & dialog() const { return parent_; }
213 Kernel & kernel() { return parent_.kernel(); }
214 Kernel const & kernel() const { return parent_.kernel(); }
222 /** \c Dialog::View is an abstract base class to the View
223 * of a Model-Controller-View split of a generic dialog.
225 class Dialog::View : boost::noncopyable {
227 /** \param parent Dialog owning this Controller.
228 * \param title is the dialog title displayed by the WM.
230 View(Dialog & parent, docstring title);
233 /** \name Generic View
234 * These few methods are all that a generic dialog needs of a
238 /** A request to modify the data structures stored by the
239 * accompanying Controller in preparation for their dispatch to
242 virtual void apply() = 0;
244 /// Hide the dialog from sight
245 virtual void hide() = 0;
247 /// Redraw the dialog (e.g. if the colors have been remapped).
248 virtual void redraw() {}
250 /// Create the dialog if necessary, update it and display it.
251 virtual void show() = 0;
253 /// Update the display of the dialog whilst it is still visible.
254 virtual void update() = 0;
256 /// \return true if the dialog is visible.
257 virtual bool isVisible() const = 0;
260 /** Defaults to nothing. Can be used by the Controller, however, to
261 * indicate to the View that something has changed and that the
262 * dialog therefore needs updating.
263 * \param id identifies what should be updated.
265 virtual void partialUpdate(int id);
267 /// sets the title of the dialog (window caption)
268 void setTitle(docstring const &);
269 /// gets the title of the dialog (window caption)
270 docstring const & getTitle() const;
272 /** \name View Access
273 * Enable the derived classes to access the other parts of the whole.
276 Dialog & dialog() { return p_; }
277 Dialog const & dialog() const { return p_; }
280 Kernel & kernel() { return p_.kernel(); }
281 Kernel const & kernel() const { return p_.kernel(); }
283 Controller & getController() { return p_.controller(); }
284 Controller const & getController() const { return p_.controller(); }
286 ButtonController & bc() { return p_.bc(); }
287 ButtonController const & bc() const { return p_.bc(); }
295 } // namespace frontend