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 <boost/utility.hpp>
19 #include <boost/scoped_ptr.hpp>
23 class ButtonController;
26 /** \c Dialog collects the different parts of a Model-Controller-View
27 * split of a generic dialog together.
29 class Dialog : boost::noncopyable {
31 /** \param name the identifier given to the dialog by its parent
34 Dialog(LyXView &, string const & name);
37 /** the Dialog's name is the means by which a dialog identifies
38 * itself to the kernel.
40 string const & name() const { return name_; }
43 /** These methods are publicly accessible because they are invoked
44 * by the View when the user presses... guess what ;-)
53 /** These methods are publicly accessible because they are invoked
54 * by the parent container acting on commands from the kernel.
56 /** \param data The dialog is passed a string encoding the data
57 * that it is to display. This string is passed to the Controller
58 * which translates it into a useable form.
60 void show(string const & data);
61 /// \param data \see show().
62 void update(string const & data);
65 bool isVisible() const;
67 /** This function is called, for example, if the GUI colours
73 /** When applying, it's useful to know whether the dialog is about
74 * to close or not (no point refreshing the display for example).
76 bool isClosing() const { return is_closing_; }
78 /** The LyX kernel is made available through this wrapper class.
79 * In an ideal world, it will shrink as more info is passed to the
80 * show() and update() methods.
82 Kernel & kernel() { return kernel_; }
85 /** Different dialogs will have different Controllers and Views.
86 * deriving from these base classes.
93 /** Methods to set the Controller and View and so specialise
94 * to a particular dialog.
95 * \param ptr is stored here.
97 void setController(Controller * ptr);
98 void setView(View * ptr);
102 /// Get methods for the various components making up a dialog.
103 Controller & controller() const;
104 ButtonController & bc() const;
109 /// Invoked by both OKButton() and ApplyButton().
115 boost::scoped_ptr<ButtonController> bc_ptr_;
116 boost::scoped_ptr<Controller> controller_ptr_;
117 boost::scoped_ptr<View> view_ptr_;
121 /** \c Dialog::Controller is an abstract base class for the Controller
122 * of a Model-Controller-View split of a generic dialog.
124 class Dialog::Controller : boost::noncopyable {
126 Controller(Dialog & parent) : parent_(parent) {}
127 virtual ~Controller() {}
130 /** These few methods are all that a generic dialog needs of a
133 /** \param data The controller is passed a string encoding of the
134 * parameters that the dialog is to display.
135 * \return true if the translation was successful.
137 virtual bool initialiseParams(string const & data) = 0;
138 /** Invoked by Dialog::hide, allowing the controller to
139 * clean up its data structures.
141 virtual void clearParams() = 0;
142 /** Invoked by Dialog::apply, enabling the Controller to
143 * dispatch its data back to the LyX kernel.
145 virtual void dispatchParams() = 0;
146 /** \return true if the dialog should be shown only when
149 virtual bool isBufferDependent() const = 0;
150 /** \return true if the kernel should disconnect the dialog from
151 * a particular inset after the data has been applied to it.
152 * Clearly this makes sense only for dialogs modifying the contents
154 * In practise, only a very few dialogs (e.g. the citation dialog)
157 virtual bool disconnectOnApply() const { return false; }
162 /** Enable the derived classes to access the other parts of the
165 Dialog & dialog() { return parent_; }
166 Dialog const & dialog() const { return parent_; }
168 Kernel & kernel() { return parent_.kernel(); }
169 Kernel const & kernel() const { return parent_.kernel(); }
177 /** \c Dialog::View is an abstract base class to the View
178 * of a Model-Controller-View split of a generic dialog.
180 class Dialog::View : boost::noncopyable {
182 View(Dialog & parent, string title) : p_(parent), title_(title) {}
186 /** These few methods are all that a generic dialog needs of a
189 /** A request to modify the data structures stored by the
190 * accompanying Controller in preparation for their dispatch to
192 * Invoked by Dialog::apply.
194 virtual void apply() = 0;
195 /** Hide the dialog from sight
196 * Invoked by Dialog::hide.
198 virtual void hide() = 0;
199 /** Redraw the dialog (e.g. if the colors have been remapped).
200 * Invoked by Dialog::redraw.
202 virtual void redraw() {}
203 /** Create the dialog if necessary, update it and display it.
204 * Invoked by Dialog::show.
206 virtual void show() = 0;
207 /** Update the display of the dialog whilst it is still visible.
208 * Invoked by Dialog::update.
210 virtual void update() = 0;
211 /// \return true if the dialog is visible.
212 virtual bool isVisible() const = 0;
215 /** Defaults to nothing. Can be used by the Controller, however, to
216 * indicate to the View that something has changed and that the
217 * dialog therefore needs updating.
219 virtual void partialUpdate(int) {}
222 /** Enable the derived classes to access the other parts of the
225 Dialog & dialog() { return p_; }
226 Dialog const & dialog() const { return p_; }
228 /// sets the title of the dialog (window caption)
229 void setTitle(string const &);
230 /// gets the title of the dialog (window caption)
231 string const & getTitle() const;
234 Kernel & kernel() { return p_.kernel(); }
235 Kernel const & kernel() const { return p_.kernel(); }
237 Controller & getController() { return p_.controller(); }
238 Controller const & getController() const { return p_.controller(); }
240 ButtonController & bc() { return p_.bc(); }
241 ButtonController const & bc() const { return p_.bc(); }