* Give Dialog::Controller::initialiseParams a bool return type.

* Constify many ButtonController/View methods.
* Try and document the code ;-)


git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@6495 a592a061-630c-0410-9148-cb99ea01b6c8

src/frontends/controllers/BCView.C

@@ -36,7 +36,7 @@ void BCView::addCheckedWidget(CheckedWidget * ptr)
 }
 
 
-bool BCView::checkWidgets()
+bool BCView::checkWidgets() const
 {
 	bool valid = true;
 

src/frontends/controllers/BCView.h

@@ -14,13 +14,26 @@
 #ifndef BCVIEW_H
 #define BCVIEW_H
 
+
 #include "LString.h"
 #include <boost/shared_ptr.hpp>
 #include <list>
 
+
 class ButtonController;
 class ButtonPolicy;
 
+
+/** \class CheckedWidget is an abstract base class that can be stored
+ *  in the button controller's view and can be interrogated by it
+ *  when the activation state of the Ok, Apply buttons is refreshed.
+ *  Ideally, the user will be prevented from returning invalid data
+ *  to the LyX kernel.
+ *
+ *  Many widgets can be grouped together in the derived class if they
+ *  make a logical whole. E.g., an input and a choice widget that together
+ *  are used to set a LyXLength can be interrogated together. 
+ */
 struct CheckedWidget {
 	///
 	virtual ~CheckedWidget();
@@ -33,30 +46,40 @@ struct CheckedWidget {
 };
 
 
+/** \class BCView is the View to ButtonController's Controller. It
+ *  stores the individual GUI widgets and sets their activation state
+ *  upon receipt of instructions from the controller.
+ *
+ *  It is a base class. The true, GUI, instantiations derive from it.
+ */
 class BCView {
 public:
 	BCView(ButtonController const &);
-	///
 	virtual ~BCView() {}
-	///
+
-	virtual void refresh() = 0;
+	//@{
-	///
+	/// Refresh the status of the Ok, Apply, Restore, Cancel buttons.
-	virtual void refreshReadOnly() = 0;
+	virtual void refresh() const = 0;
-	///
+	/// Refresh the status of any widgets in the read_only list
+	virtual void refreshReadOnly() const = 0;
+	//@}
+
+	/// A shortcut to the BP of the BC.
 	ButtonPolicy & bp() const;
-	///
+
+	/** Add a widget to the list of all widgets whose validity should
+	 *  be checked explicitly when the buttons are refreshed.
+	 */
 	void addCheckedWidget(CheckedWidget * ptr);
+
 protected:
-	///
+	/// \return true if all CheckedWidgets are in a valid state.
-	bool checkWidgets();
+	bool checkWidgets() const;
 
 private:
-	///
 	typedef boost::shared_ptr<CheckedWidget> checked_widget_ptr;
 	typedef std::list<checked_widget_ptr> checked_widget_list;
-	///
 	checked_widget_list checked_widgets;
-	///
 	ButtonController const & parent;
 };
 
@@ -71,33 +94,37 @@ public:
 	GuiBC(ButtonController const & parent,
 	      string const & cancel, string const & close);
 
-	///
+	//@{
+	/** Store pointers to these widgets. The pointers are _not_
+	 *  owned by GuiBC.
+	 */
 	void setOK(Button * obj) { okay_ = obj; }
-	///
 	void setApply(Button * obj) { apply_ = obj; }
-	///
 	void setCancel(Button * obj) { cancel_ = obj; }
-	///
 	void setRestore(Button * obj) { restore_ = obj; }
-	///
+	//@}
+
+	/** Add a pointer to the list of widgets whose activation
+	 *  state is dependent upon the read-only status of the
+	 *  underlying buffer.
+	 */
 	void addReadOnly(Widget * obj) { read_only_.push_back(obj); }
-	///
-	void eraseReadOnly() { read_only_.clear(); }
 
 	/// Refresh the status of the Ok, Apply, Restore, Cancel buttons.
-	void refresh();
+	virtual void refresh() const;
 	/// Refresh the status of any widgets in the read_only list
-	void refreshReadOnly();
+	virtual void refreshReadOnly() const;
+
 private:
 	/// Enable/Disable a widget
-	virtual void setWidgetEnabled(Widget * obj, bool enable) = 0;
+	virtual void setWidgetEnabled(Widget * obj, bool enable) const = 0;
 	/// Enable/Disable a button
-	virtual void setButtonEnabled(Button * obj, bool enable) = 0;
+	virtual void setButtonEnabled(Button * obj, bool enable) const = 0;
 	/// Set the Label on the button
-	virtual void setButtonLabel(Button * obj, string const & label) = 0;
+	virtual void setButtonLabel(Button * obj, string const & label) const = 0;
 
-	string cancel_label_;
+	string const cancel_label_;
-	string close_label_;
+	string const close_label_;
 
 	Button * okay_;
 	Button * apply_;

src/frontends/controllers/BCView.tmpl

@@ -29,7 +29,7 @@ GuiBC<Button, Widget>::GuiBC(ButtonController const & parent,
 
 
 template <class Button, class Widget>
-void GuiBC<Button, Widget>::refresh()
+void GuiBC<Button, Widget>::refresh() const
 {
 	lyxerr[Debug::GUI] << "Calling BC refresh()" << std::endl;
 
@@ -61,7 +61,7 @@ void GuiBC<Button, Widget>::refresh()
 
 
 template <class Button, class Widget>
-void GuiBC<Button, Widget>::refreshReadOnly()
+void GuiBC<Button, Widget>::refreshReadOnly() const
 {
 	if (read_only_.empty()) return;
 

src/frontends/controllers/ButtonController.C

@@ -16,10 +16,6 @@
 #include "debug.h"
 
 
-ButtonController::~ButtonController()
-{}
-
-
 BCView & ButtonController::view() const
 {
 	lyx::Assert(view_.get());
@@ -44,25 +40,25 @@ void ButtonController::bp(ButtonPolicy * bp)
 }
 
 
-void ButtonController::refresh()
+void ButtonController::refresh() const
 {
 	view().refresh();
 }
 
-		
+
-void ButtonController::refreshReadOnly()
+void ButtonController::refreshReadOnly() const
 {
 	view().refreshReadOnly();
 }
 
 
-void ButtonController::ok()
+void ButtonController::ok() const
 {
 	input(ButtonPolicy::SMI_OKAY);
 }
 
 
-void ButtonController::input(ButtonPolicy::SMInput in)
+void ButtonController::input(ButtonPolicy::SMInput in) const
 {
 	if (ButtonPolicy::SMI_NOOP == in)
 		return;
@@ -71,31 +67,31 @@ void ButtonController::input(ButtonPolicy::SMInput in)
 }
 
 
-void ButtonController::apply()
+void ButtonController::apply() const
 {
 	input(ButtonPolicy::SMI_APPLY);
 }
 
 
-void ButtonController::cancel()
+void ButtonController::cancel() const
 {
 	input(ButtonPolicy::SMI_CANCEL);
 }
 
 
-void ButtonController::restore()
+void ButtonController::restore() const
 {
 	input(ButtonPolicy::SMI_RESTORE);
 }
 
 
-void ButtonController::hide()
+void ButtonController::hide() const
 {
 	input(ButtonPolicy::SMI_HIDE);
 }
 
 
-void ButtonController::valid(bool v)
+void ButtonController::valid(bool v) const
 {
 	if (v) {
 		input(ButtonPolicy::SMI_VALID);
@@ -105,13 +101,7 @@ void ButtonController::valid(bool v)
 }
 
 
-void ButtonController::invalid()
+bool ButtonController::readOnly(bool ro) const
-{
-	input(ButtonPolicy::SMI_INVALID);
-}
-
-
-bool ButtonController::readOnly(bool ro)
 {
 	lyxerr[Debug::GUI] << "Setting controller ro: " << ro << std::endl;
 
@@ -124,9 +114,3 @@ bool ButtonController::readOnly(bool ro)
 	view().refresh();
 	return ro;
 }
-
-
-void ButtonController::readWrite()
-{
-	readOnly(false);
-}

src/frontends/controllers/ButtonController.h

@@ -19,64 +19,73 @@
 #include <boost/scoped_ptr.hpp>
 
 
-/** Controls the activation of the OK, Apply and Cancel buttons.
+class BCView;
+
+
+/** \class ButtonController controls the activation of the OK, Apply and
+ *  Cancel buttons.
  *
- * Actually supports 4 buttons in all and it's up to the user to decide on
+ * It actually supports 4 buttons in all and it's up to the user to decide on
  * the activation policy and which buttons correspond to which output of the
  * state machine.
- * Author: Allan Rae <rae@lyx.org>.
- * This class stripped of xforms-specific code by
- * Angus Leeming <leeming@lyx.org>
  */
-class BCView;
 
 class ButtonController : boost::noncopyable {
 public:
-	///
+	//@{
-	~ButtonController();
+	/** Methods to set and get the GUI view (containing the actual
-
+	 *   button widgets.
-	///
+	 *  \param ptr is owned by the ButtonController.
+	 */
+	void view(BCView * ptr);
 	BCView & view() const;
-	///
+	//@}
-	void view(BCView *);
 
-	///
+	//@{
+	/** Methods to set and get the ButtonPolicy.
+	 *  \param ptr is owned by the ButtonController.
+	 */
+	void bp(ButtonPolicy * ptr);
 	ButtonPolicy & bp() const;
-	///
+	//@}
-	void bp(ButtonPolicy *);
 
 	///
-	void input(ButtonPolicy::SMInput);
+	void input(ButtonPolicy::SMInput) const;
-	///
-	void ok();
-	///
-	void apply();
-	///
-	void cancel();
-	///
-	void restore();
-	///
-	void hide();
 
-	///
+	//@{
-	void refresh();
+	/// Tell the BC that a particular button has been pressed.
-	///
+	void ok() const;
-	void refreshReadOnly();
+	void apply() const;
+	void cancel() const;
+	void restore() const;
+	//@}
 
-	/// Passthrough function -- returns its input value
+	/// Tell the BC that the dialog is being hidden
-	bool readOnly(bool = true);
+	void hide() const;
-	///
-	void readWrite();
 
-	///
+	/**Refresh the activation state of the Ok, Apply, Close and
-	void valid(bool = true);
+	 * Restore buttons.
-	///
+	 */
-	void invalid();
+	void refresh() const;
+
+	/** Refresh the activation state of all the widgets under the control
+	 *  of the BC to reflect the read-only status of the underlying buffer.
+	 */
+	void refreshReadOnly() const;
+	//@}
+
+	/** Passthrough function -- returns its input value
+	 *  Tell the BC about the read-only status of the underlying buffer.
+	 */
+	bool readOnly(bool = true) const;
+
+	/** \param validity Tell the BC that the data is, or is not, valid.
+	 *  Sets the activation state of the buttons immediately.
+	 */
+	void valid(bool = true) const;
 
 private:
-	///
 	boost::scoped_ptr<ButtonPolicy> bp_;
-	///
 	boost::scoped_ptr<BCView> view_;
 };
 

src/frontends/controllers/ChangeLog

@@ -1,3 +1,18 @@
+2003-03-13  Angus Leeming  <angus@localhost.localdomain>
+
+	* ButtonController.h: 
+
+2003-03-13  Angus Leeming  <leeming@lyx.org>
+
+	* Dialog.h (initialiseParams): return a bool to indicate successful
+	translation of the string.
+
+	* Dialog.h:
+	* Kernel.h
+	* ControlAbout.h: a serious attempt at documenting the code.
+
+	* ButtonController.[Ch] (readWrite): it wasn't used, so remove it.
+
 2003-03-13  Angus Leeming  <leeming@lyx.org>
 
 	* ControlParagraph.[Ch]: rewrite to use the Dialog-based scheme and

src/frontends/controllers/ControlAboutlyx.h

@@ -16,31 +16,28 @@
 #include "Dialog.h"
 #include <iosfwd>
 
-/** A controller for the About LyX dialogs.
+/** \class ControlAboutlyx is a controller for the "About LyX" dialogs.
  */
 class ControlAboutlyx : public Dialog::Controller {
 public:
-	///
+	ControlAboutlyx(Dialog & parent);
-	ControlAboutlyx(Dialog &);
-	///
-	virtual void initialiseParams(string const &) {}
-	///
-	virtual void clearParams() {}
-	///
-	virtual void dispatchParams() {}
-	///
-	virtual bool isBufferDependent() const { return false; }
 
-	///
+	//@{
+	/// Instantiate Dialog::Controller methods.
+	virtual bool initialiseParams(string const &) { return true; }
+	virtual void clearParams() {}
+	virtual void dispatchParams() {}
+	virtual bool isBufferDependent() const { return false; }
+	//@}
+
+	//@{
+	/// Provide the View with specific pieces of information.
 	void getCredits(std::ostream &) const;
-	///
 	string const getCopyright() const;
-	///
 	string const getLicense() const;
-	///
 	string const getDisclaimer() const;
-	///
 	string const getVersion() const;
+	//@}
 };
 
 #endif // CONTROLABOUTLYX_H

src/frontends/controllers/ControlChanges.h

@@ -22,7 +22,7 @@ public:
 	///
 	ControlChanges(Dialog &);
 	///
-	virtual void initialiseParams(string const &) {}
+	virtual bool initialiseParams(string const &) { return true; }
 	///
 	virtual void clearParams() {}
 	///

src/frontends/controllers/ControlCharacter.C

@@ -26,7 +26,7 @@ ControlCharacter::ControlCharacter(Dialog & parent)
 {}
 
 
-void ControlCharacter::initialiseParams(string const &)
+bool ControlCharacter::initialiseParams(string const &)
 {
 	// Do this the first time only.
 	if (!font_.get())
@@ -41,6 +41,8 @@ void ControlCharacter::initialiseParams(string const &)
 	    getColor()    != LColor::ignore ||
 	    font_->language() != ignore_language)
 		dialog().bc().valid();
+
+	return true;
 }
 
 

src/frontends/controllers/ControlCharacter.h

@@ -22,7 +22,7 @@ public:
 	///
 	ControlCharacter(Dialog &);
 	///
-	virtual void initialiseParams(string const &);
+	virtual bool initialiseParams(string const & data);
 	///
 	virtual void clearParams();
 	///

src/frontends/controllers/ControlCitation.C

@@ -27,7 +27,7 @@ ControlCitation::ControlCitation(Dialog & d)
 {}
 
 
-void ControlCitation::initialiseParams(string const & data)
+bool ControlCitation::initialiseParams(string const & data)
 {
 	ControlCommand::initialiseParams(data);
 
@@ -49,6 +49,8 @@ void ControlCitation::initialiseParams(string const & data)
 		    (!usingNatbib() && citeStyles_.size() != 1))
 			citeStyles_ = biblio::getCiteStyles(usingNatbib());
 	}
+
+	return true;
 }
 
 

src/frontends/controllers/ControlCitation.h

@@ -24,7 +24,7 @@ public:
 	ControlCitation(Dialog &);
 
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 

src/frontends/controllers/ControlCommand.C

@@ -23,9 +23,10 @@ ControlCommand::ControlCommand(Dialog & dialog, string const & lfun_name)
 {}
 
 
-void ControlCommand::initialiseParams(string const & data)
+bool ControlCommand::initialiseParams(string const & data)
 {
 	InsetCommandMailer::string2params(data, params_);
+	return true;
 }
 
 

src/frontends/controllers/ControlCommand.h

@@ -32,7 +32,7 @@ public:
 	///
 	InsetCommandParams const & params() const { return params_; }
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlERT.C

@@ -20,9 +20,10 @@ ControlERT::ControlERT(Dialog & parent)
 {}
 
 
-void ControlERT::initialiseParams(string const & data)
+bool ControlERT::initialiseParams(string const & data)
 {
 	InsetERTMailer::string2params(data, status_);
+	return true;
 }
 
 

src/frontends/controllers/ControlERT.h

@@ -27,7 +27,7 @@ public:
 	///
 	void setStatus(InsetERT::ERTStatus status) { status_ = status; }
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlError.C

@@ -18,7 +18,7 @@ ControlError::ControlError(Dialog & parent)
 {}
 
 
-void ControlError::initialiseParams(string const & data)
+bool ControlError::initialiseParams(string const & data)
 {
 	params_ = data;
 }

src/frontends/controllers/ControlError.h

@@ -21,7 +21,7 @@ public:
 	///
 	ControlError(Dialog &);
 	///
-	virtual void initialiseParams(string const &);
+	virtual bool initialiseParams(string const & data);
 	///
 	virtual void clearParams();
 	///

src/frontends/controllers/ControlExternal.C

@@ -28,13 +28,14 @@ ControlExternal::ControlExternal(Dialog & parent)
 {}
 
 
-void ControlExternal::initialiseParams(string const & data)
+bool ControlExternal::initialiseParams(string const & data)
 {
 	inset_.reset(new InsetExternal);
 	InsetExternal::Params params;
 	InsetExternalMailer::string2params(data, params);
 	inset_->setFromParams(params);
 	inset_->setView(kernel().bufferview());
+	return true;
 }
 
 

src/frontends/controllers/ControlExternal.h

@@ -25,7 +25,7 @@ public:
 	///
 	ControlExternal(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlFloat.C

@@ -20,11 +20,12 @@ ControlFloat::ControlFloat(Dialog & parent)
 {}
 
 
-void ControlFloat::initialiseParams(string const & data)
+bool ControlFloat::initialiseParams(string const & data)
 {
 	InsetFloatParams params;
 	InsetFloatMailer::string2params(data, params);
 	params_.reset(new InsetFloatParams(params));
+	return true;
 }
 
 

src/frontends/controllers/ControlFloat.h

@@ -21,7 +21,7 @@ public:
 	///
 	ControlFloat(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlGraphics.C

@@ -47,11 +47,12 @@ ControlGraphics::ControlGraphics(Dialog & parent)
 {}
 
 
-void ControlGraphics::initialiseParams(string const & data)
+bool ControlGraphics::initialiseParams(string const & data)
 {
 	InsetGraphicsParams params;
 	InsetGraphicsMailer::string2params(data, params);
 	params_.reset(new InsetGraphicsParams(params));
+	return true;
 }
 
 

src/frontends/controllers/ControlGraphics.h

@@ -31,7 +31,7 @@ public:
 	///
 	ControlGraphics(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlInclude.C

@@ -31,11 +31,12 @@ ControlInclude::ControlInclude(Dialog & parent)
 {}
 
 
-void ControlInclude::initialiseParams(string const & data)
+bool ControlInclude::initialiseParams(string const & data)
 {
 	InsetInclude::Params params;
 	InsetIncludeMailer::string2params(data, params);
 	inset_.reset(new InsetInclude(params));
+	return true;
 }
 
 

src/frontends/controllers/ControlInclude.h

@@ -36,7 +36,7 @@ public:
 	ControlInclude(Dialog &);
 
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.
@@ -45,7 +45,7 @@ public:
 	virtual bool isBufferDependent() const { return true; }
 
 	///
-	InsetInclude::Params const & params() const 
+	InsetInclude::Params const & params() const
 		{ return inset_->params(); }
 	///
 	void setParams(InsetInclude::Params const &);

src/frontends/controllers/ControlMinipage.C

@@ -20,11 +20,12 @@ ControlMinipage::ControlMinipage(Dialog & parent)
 {}
 
 
-void ControlMinipage::initialiseParams(string const & data)
+bool ControlMinipage::initialiseParams(string const & data)
 {
 	InsetMinipage::Params params;
 	InsetMinipageMailer::string2params(data, params);
 	params_.reset(new InsetMinipage::Params(params));
+	return true;
 }
 
 

src/frontends/controllers/ControlMinipage.h

@@ -21,7 +21,7 @@ public:
 	///
 	ControlMinipage(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlParagraph.C

@@ -26,7 +26,7 @@ ControlParagraph::ControlParagraph(Dialog & parent)
 {}
 
 
-void ControlParagraph::initialiseParams(string const & data)
+bool ControlParagraph::initialiseParams(string const & data)
 {
 	istringstream is(data);
 	LyXLex lex(0,0);
@@ -37,7 +37,7 @@ void ControlParagraph::initialiseParams(string const & data)
 	// action == 1: update dialog, accept changes
 	// action == 2: update dialog, do not accept changes
 	int action = 0;
-	
+
 	if (lex.isOK()) {
 		lex.next();
 		string const token = lex.getString();
@@ -50,7 +50,7 @@ void ControlParagraph::initialiseParams(string const & data)
 			action = accept ? 1 : 2;
 		} else {
 			// Unrecognised token
-			lyx::Assert(0);
+			return false;
 		}
 	}
 
@@ -79,9 +79,9 @@ void ControlParagraph::initialiseParams(string const & data)
 			Int = lex.getInteger();
 		} else {
 			// Unrecognised token
-			break;
+			return false;
 		}
-		    
+
 		++nset;
 
 		if (token == "\\alignpossible") {
@@ -92,13 +92,15 @@ void ControlParagraph::initialiseParams(string const & data)
 			ininset_ = Int;
 		}
 	}
-	lyx::Assert(nset == 3);
+	if (nset != 3)
+		return false;
 
 	// If "update", then set the activation status of the button controller
 	if (action > 0) {
 		bool const accept = action == 1;
 		dialog().bc().valid(accept);
 	}
+	return true;
 }
 
 

src/frontends/controllers/ControlParagraph.h

@@ -22,7 +22,7 @@ public:
 	///
 	ControlParagraph(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/ControlTabular.C

@@ -23,11 +23,11 @@ ControlTabular::ControlTabular(Dialog & parent)
 {}
 
 
-void ControlTabular::initialiseParams(string const & data)
+bool ControlTabular::initialiseParams(string const & data)
 {
 	Buffer * buffer = kernel().buffer();
 	if (!buffer)
-		return;
+		return false;
 
 	InsetTabular tmp(*buffer);
 	int cell = InsetTabularMailer::string2params(data, tmp);
@@ -35,6 +35,7 @@ void ControlTabular::initialiseParams(string const & data)
 		params_.reset(new LyXTabular(*tmp.tabular.get()));
 		active_cell_ = cell;
 	}
+	return true;
 }
 
 

src/frontends/controllers/ControlTabular.h

@@ -25,7 +25,7 @@ public:
 
 	ControlTabular(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// We use set() instead.

src/frontends/controllers/ControlTabularCreate.C

@@ -20,9 +20,10 @@ ControlTabularCreate::ControlTabularCreate(Dialog & parent)
 {}
 
 
-void ControlTabularCreate::initialiseParams(string const &)
+bool ControlTabularCreate::initialiseParams(string const &)
 {
 	params_.first = params_.second = 5;
+	return true;
 }
 
 

src/frontends/controllers/ControlTabularCreate.h

@@ -22,7 +22,7 @@ public:
 	///
 	ControlTabularCreate(Dialog &);
 	///
-	virtual void initialiseParams(string const &);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	///

src/frontends/controllers/ControlWrap.C

@@ -21,11 +21,12 @@ ControlWrap::ControlWrap(Dialog & parent)
 {}
 
 
-void ControlWrap::initialiseParams(string const & data)
+bool ControlWrap::initialiseParams(string const & data)
 {
 	InsetWrapParams params;
 	InsetWrapMailer::string2params(data, params);
 	params_.reset(new InsetWrapParams(params));
+	return true;
 }
 
 

src/frontends/controllers/ControlWrap.h

@@ -21,7 +21,7 @@ public:
 	///
 	ControlWrap(Dialog &);
 	///
-	virtual void initialiseParams(string const & data);
+	virtual bool initialiseParams(string const & data);
 	/// clean-up on hide.
 	virtual void clearParams();
 	/// clean-up on hide.

src/frontends/controllers/Dialog.C

@@ -15,6 +15,7 @@
 
 #include "ButtonController.h"
 #include "BCView.h"
+#include "debug.h"
 #include "support/LAssert.h"
 
 
@@ -67,7 +68,13 @@ void Dialog::show(string const & data)
 	if (controller().isBufferDependent() && !kernel().isBufferAvailable())
 		return;
 
-	controller().initialiseParams(data);
+	if (!controller().initialiseParams(data)) {
+		lyxerr << "Dialog \"" << name_
+		       << "\" failed to translate the data "
+			"string passed to show()" << std::endl;
+		return;
+	}
+
 	bc().readOnly(kernel().isBufferReadonly());
 	view().show();
 
@@ -81,7 +88,12 @@ void Dialog::update(string const & data)
 	if (controller().isBufferDependent() && !kernel().isBufferAvailable())
 		return;
 
-	controller().initialiseParams(data);
+	if (!controller().initialiseParams(data)) {
+		lyxerr << "Dialog \"" << name_
+		       << "\" failed to translate the data "
+			"string passed to update()" << std::endl;
+		return;
+	}
 
 	bc().readOnly(kernel().isBufferReadonly());
 	view().update();

src/frontends/controllers/Dialog.h

@@ -7,9 +7,6 @@
  * \author Angus Leeming
  *
  * Full author contact details are available in file CREDITS
- *
- * The dialogs use a Model-Controller-View split, instantiated here
- * by class Dialog.
  */
 
 #ifndef DIALOG_H
@@ -26,182 +23,220 @@ class LyXView;
 class ButtonController;
 
 
+/** \class Dialog collects the different parts of a Model-Controller-View
+ *  split of a generic dialog together.
+ */
 class Dialog : boost::noncopyable {
 public:
-	/** the Dialog's "name" is the means with which a dialog identifies
+	/** \param name is the identifier given to the dialog by its parent
-	 *  itself to the kernel.
+	 *  container.
 	 */
 	Dialog(LyXView &, string const & name);
-	///
 	~Dialog();
 
-	///
+	/** the Dialog's name is the means by which a dialog identifies
+	 *  itself to the kernel.
+	 */
 	string const & name() const { return name_; }
 
-	/** These methods are publicly accessible because they are invoked
-	    by the View.
-	*/
 	//@{
-	///
+	/** These methods are publicly accessible because they are invoked
+	 *  by the View when the user presses... guess what ;-)
+	 */
 	void ApplyButton();
-	///
 	void OKButton();
-	///
 	void CancelButton();
-	///
 	void RestoreButton();
 	//@}
 
-	/** These methods are publicly accessible because they are invoked
-	 *  by the Dialogs class.
-	 */
 	//@{
-	/** Some dialogs, eg the Tabular or Preferences dialog, can extract
+	/** These methods are publicly accessible because they are invoked
-	    the information they require from the kernel. These dialogs will
+	 *  by the parent container acting on commands from the kernel.
-	    probably be passed an empty string by the calling Dialogs class.
-	    The inset dialogs, however, require information specific to
-	    an individual inset. This information will be encoded in "data"
-	    and must be translated into a set of parameters that can be
-	    updated from the dialog.
 	 */
-	void show(string const & data = string());
+	/** \param data The dialog is passed a string encoding the data
-	///
+	 *  that it is to display. This string is passed to the Controller
-	void update(string const & data = string());
+	 *  which translates it into a useable form.
-	///
+	 */
+	void show(string const & data);
+	/// \param data \see show().
+	void update(string const & data);
+
 	void hide();
-	///
 	bool isVisible() const;
-	/// (Eg, the GUI colours have been changed.)
+
+	/** This function is called, for example, if the GUI colours
+	 *  have been changed.
+	 */
 	void redraw();
 	//@}
 
-	/** When Applying it's useful to know whether the dialog is about
+	/** When applying, it's useful to know whether the dialog is about
 	 *  to close or not (no point refreshing the display for example).
 	 */
 	bool isClosing() const { return is_closing_; }
 
-	/// The LyX kernel is made available through this.
+	/** The LyX kernel is made available through this wrapper class.
+	 *  In an ideal world, it will shrink as more info is passed to the
+	 *  show() and update() methods.
+	 */
 	Kernel & kernel() { return kernel_; }
 
-	/** Different dialogs will have different
-	    Controllers, Views and ButtonControllers.
-	*/
 	//@{
-	///
+	/** Different dialogs will have different Controllers and Views.
+	 * deriving from these base classes.
+	 */
 	class Controller;
-	///
 	class View;
+	//@}
 
-	///
+	//@{
-	void setController(Controller *);
+	/** Methods to set the Controller and View and so specialise
-	///
+	 *  to a particular dialog.
-	void setView(View *);
+	 *  \param ptr is stored here.
+	 */
+	void setController(Controller * ptr);
+	void setView(View * ptr);
+	//@}
 
-	///
+	//@{
+	/// Get methods for the various components making up a dialog.
 	Controller & controller() const;
-	///
 	ButtonController & bc() const;
-	///
 	View & view() const;
 	//@}
 
 private:
-	///
+	/// Invoked by both OKButton() and ApplyButton().
 	void apply();
 
-	///
 	bool is_closing_;
-	///
 	Kernel kernel_;
-	///
 	string name_;
-	///
 	boost::scoped_ptr<ButtonController> bc_ptr_;
-	///
 	boost::scoped_ptr<Controller> controller_ptr_;
-	///
 	boost::scoped_ptr<View> view_ptr_;
 };
 
 
+/** \class Dialog::Controller is an abstract base class for the Controller
+ *  of a Model-Controller-View split of a generic dialog.
+ */
 class Dialog::Controller : boost::noncopyable {
 public:
-	///
 	Controller(Dialog & parent) : parent_(parent) {}
-	///
 	virtual ~Controller() {}
-	///
+
-	virtual void initialiseParams(string const & data) = 0;
+	//@{
-	///
+	/** These few methods are all that a generic dialog needs of a
+	 *  controller.
+	 */
+	/** \param data The controller is passed a string encoding of the
+	 *  parameters that the dialog is to display.
+	 *  \return true if the translation was successful.
+	 */
+	virtual bool initialiseParams(string const & data) = 0;
+	/** Invoked by Dialog::hide, allowing the controller to
+	 *  clean up its data structures.
+	 */
 	virtual void clearParams() = 0;
-	///
+	/** Invoked by Dialog::apply, enabling the Controller to
+	 *  dispatch its data back to the LyX kernel.
+	 */
 	virtual void dispatchParams() = 0;
-	///
+	/** \return true if the dialog should be shown only when
+	 *  a buffer is open
+	 */
 	virtual bool isBufferDependent() const = 0;
-	///
+	/** \return true if the kernel should disconnect the dialog from
+	 *  a particular inset after the data has been applied to it.
+	 *  Clearly this makes sense only for dialogs modifying the contents
+	 *  of an inset :-)
+	 *  In practise, only a very few dialogs (e.g. the citation dialog)
+	 *  return true.
+	 */
 	virtual bool disconnectOnApply() const { return false; }
-	///
+	//@}
+
+protected:
+	//@{
+	/** Enable the derived classes to access the other parts of the
+	 * whole.
+	 */
 	Dialog & dialog() { return parent_; }
-	///
 	Dialog const & dialog() const { return parent_; }
-	///
+
 	Kernel & kernel() { return parent_.kernel(); }
-	///
 	Kernel const & kernel() const { return parent_.kernel(); }
+	//@}
 
 private:
-	///
 	Dialog & parent_;
 };
 
 
+/** \class Dialog::View is an abstract base class to the View
+ *  of a Model-Controller-View split of a generic dialog.
+ */
 class Dialog::View : boost::noncopyable {
 public:
-	///
 	View(Dialog & parent) : p_(parent) {}
-	///
 	virtual ~View() {}
 
-	/// Apply changes to LyX data from dialog.
+	//@{
+	/** These few methods are all that a generic dialog needs of a
+	 *  view.
+	 */
+	/** A request to modify the data structures stored by the
+	 *  accompanying Controller in preparation for their dispatch to
+	 *  the LyX kernel.
+	 *  Invoked by Dialog::apply.
+	 */
 	virtual void apply() = 0;
-	/// Hide the dialog.
+	/** Hide the dialog from sight
+	 *  Invoked by Dialog::hide.
+	 */
 	virtual void hide() = 0;
-	/// Redraw the dialog (e.g. if the colors have been remapped).
+	/** Redraw the dialog (e.g. if the colors have been remapped).
+	 *  Invoked by Dialog::redraw.
+	 */
 	virtual void redraw() {}
-	/// Create the dialog if necessary, update it and display it.
+	/** Create the dialog if necessary, update it and display it.
+	 *  Invoked by Dialog::show.
+	 */
 	virtual void show() = 0;
-	/// Update dialog before/whilst showing it.
+	/** Update the display of the dialog whilst it is still visible.
+	 *  Invoked by Dialog::update.
+	 */
 	virtual void update() = 0;
-	///
+	/// \return true if the dialog is visible.
 	virtual bool isVisible() const = 0;
+	//@}
 
-	/** Defaults to nothing. Can be used by the controller, however, to
+	/** Defaults to nothing. Can be used by the Controller, however, to
-	 *  indicate to the view that something has changed and that the
+	 *  indicate to the View that something has changed and that the
 	 *  dialog therefore needs updating.
 	 */
 	virtual void partialUpdate(int) {}
 
-	///
+	//@{
+	/** Enable the derived classes to access the other parts of the
+	 * whole.
+	 */
 	Dialog & dialog() { return p_; }
-	///
 	Dialog const & dialog() const { return p_; }
 
-	///
+protected:
 	Kernel & kernel() { return p_.kernel(); }
-	///
 	Kernel const & kernel() const { return p_.kernel(); }
 
-	///
 	Controller & getController() { return p_.controller(); }
-	///
 	Controller const & getController() const { return p_.controller(); }
 
-	///
 	ButtonController & bc() { return p_.bc(); }
-	///
 	ButtonController const & bc() const { return p_.bc(); }
+	//@}
 
-protected:
+private:
 	///
 	Dialog & p_;
 };

src/frontends/controllers/Kernel.C

@@ -1,3 +1,15 @@
+/**
+ * \file Kernel.h
+ * This file is part of LyX, the document processor.
+ * Licence details can be found in the file COPYING.
+ *
+ * \author Angus Leeming
+ *
+ * Full author contact details are available in file CREDITS
+ */
+
+#include <config.h>
+
 #include "Kernel.h"
 
 #include "buffer.h"
@@ -60,6 +72,7 @@ Kernel::DocTypes Kernel::docType() const
 	return DOCBOOK;
 }
 
+
 BufferView * Kernel::bufferview()
 {
 	return lyxview_.view().get();

src/frontends/controllers/Kernel.h

@@ -1,4 +1,13 @@
 // -*- C++ -*-
+/**
+ * \file Kernel.h
+ * This file is part of LyX, the document processor.
+ * Licence details can be found in the file COPYING.
+ *
+ * \author Angus Leeming
+ *
+ * Full author contact details are available in file CREDITS
+ */
 
 #ifndef KERNEL_H
 #define KERNEL_H
@@ -13,49 +22,76 @@ class FuncRequest;
 class LyXView;
 
 
+/** \class Kernel is a wrapper making the LyX kernel available to the dialog.
+ * (Ie, it provides an interface to the Model part of the Model-Controller-
+ *  View split.
+ *  In an ideal world, it will shrink as more info is passed to the
+ *  Dialog::show() and update() methods.
+ */
 class Kernel {
 public:
-	///
+	/// \param lv is the access point for the dialog to the LyX kernel.
-	enum DocTypes {
+	Kernel(LyXView & lv);
-		///
-		LATEX,
-		///
-		LITERATE,
-		///
-		LINUXDOC,
-		///
-		DOCBOOK
-	};
 
-	///
+	/** This method is the primary prupose of the class. It provides
-	Kernel(LyXView &);
+	    the "gateway" by which the dialog can send a request (of a
-	///
+	    change in the data, for more information) to the kernel,
-	void dispatch(FuncRequest const &, bool verbose = false) const;
+	    encoded as \param fr.
-	/** The Dialog has received a request from the user to update
+	    \param verbose Set to true if the completed action should
-	    its contents. It must, therefore, ask the kernel to provide
+	    be displayed in the minibuffer.
-	    this information to Dialog 'name'.
+	 */
+	void dispatch(FuncRequest const & fr, bool verbose = false) const;
+
+	/** The dialog has received a request from the user
+	    (who pressed the "Restore" buuton) to update  contents.
+	    It must, therefore, ask the kernel to provide this information.
+	    \param name is used as an identifier by the kernel
+	    when the information is posted.
 	 */
 	void updateDialog(string const & name) const;
-	///
+
+	/** A request from the Controller that future changes to the data
+	 *  stored by the dialog are not applied to the inset currently
+	 *  connected to the dialog. Instead, they will be used to generate
+	 *  a new inset at the cursor position.
+	 */
 	void disconnect(string const & name) const;
-	///
+
+	//@{
+	/// Simple wrapper functions to Buffer methods.
 	bool isBufferAvailable() const;
-	///
 	bool isBufferReadonly() const;
-	///
+	//@}
+
+	//@{
+	/** \enum DocTypes is used to flag the different kinds of buffer
+	 *  without making the kernel header files available to the
+	 *  dialog's Controller or View.
+	 */
+	enum DocTypes {
+		LATEX,
+		LITERATE,
+		LINUXDOC,
+		DOCBOOK
+	};
+	/// The type of the current buffer.
 	DocTypes docType() const;
-	///
+	//@}
+
+
+	//@{
+	/** Unpleasantly public internals of the LyX kernel.
+	 *  We should aim to reduce/remove these from the interface.
+	 */
 	LyXView & lyxview() { return lyxview_; }
-	///
 	LyXView const & lyxview() const { return lyxview_; }
-	///
+
 	Buffer * buffer();
-	///
 	Buffer const * buffer() const;
-	///
+
 	BufferView * bufferview();
-	///
 	BufferView const * bufferview() const;
+	//@}
 
 private:
 	LyXView & lyxview_;

src/frontends/qt2/QDialogView.C

@@ -81,11 +81,7 @@ void QDialogView::changed()
 {
 	if (updating_)
 		return;
-
+	bc().valid(isValid());
-	if (isValid())
-		bc().valid();
-	else
-		bc().invalid();
 }
 
 

src/frontends/qt2/Qt2BC.C

@@ -25,13 +25,13 @@ Qt2BC::Qt2BC(ButtonController const & parent,
 {}
 
 
-void Qt2BC::setButtonEnabled(QButton * obj, bool enabled)
+void Qt2BC::setButtonEnabled(QButton * obj, bool enabled) const
 {
 	obj->setEnabled(enabled);
 }
 
 
-void Qt2BC::setWidgetEnabled(QWidget * obj, bool enabled)
+void Qt2BC::setWidgetEnabled(QWidget * obj, bool enabled) const
 {
 	// yuck, rtti, but the user comes first
 	if (obj->inherits("QLineEdit")) {
@@ -47,7 +47,7 @@ void Qt2BC::setWidgetEnabled(QWidget * obj, bool enabled)
 }
 
 
-void Qt2BC::setButtonLabel(QButton * obj, string const & label)
+void Qt2BC::setButtonLabel(QButton * obj, string const & label) const
 {
 	obj->setText(toqstr(label));
 }

src/frontends/qt2/Qt2BC.h

@@ -34,13 +34,13 @@ public:
 	      string const & = _("Cancel"), string const & = _("Close"));
 private:
 	/// Updates the button sensitivity (enabled/disabled)
-	void setButtonEnabled(QButton *, bool enabled);
+	void setButtonEnabled(QButton *, bool enabled) const;
 
 	/// Updates the widget sensitivity (enabled/disabled)
-	void setWidgetEnabled(QWidget *, bool enabled);
+	void setWidgetEnabled(QWidget *, bool enabled) const;
 
 	/// Set the label on the button
-	void setButtonLabel(QButton *, string const & label);
+	void setButtonLabel(QButton *, string const & label) const;
 };
 
 #endif // QT2BC_H

src/frontends/qt2/Qt2Base.C

@@ -76,11 +76,7 @@ void Qt2Base::changed()
 {
 	if (updating_)
 		return;
-
+	bc().valid(isValid());
-	if (isValid())
-		bc().valid();
-	else
-		bc().invalid();
 }
 
 

src/frontends/qt2/qscreen.h

@@ -70,7 +70,7 @@ private:
 	/// the mini-pixmap used for backing store for the blinking cursor
 	boost::scoped_ptr<QPixmap> nocursor_pixmap_;
 
-	//{@ the cursor pixmap position/size
+	//@{ the cursor pixmap position/size
 	int cursor_x_;
 	int cursor_y_;
 	int cursor_w_;

src/frontends/qt2/qsetborder.C

@@ -1,5 +1,5 @@
 /**
- * \file QSetBorder.C
+ * \file qsetborder.C
  * This file is part of LyX, the document processor.
  * Licence details can be found in the file COPYING.
  *

src/frontends/qt2/qsetborder.h

@@ -1,6 +1,6 @@
 // -*- C++ -*-
 /**
- * \file QSetBorder.h
+ * \file qsetborder.h
  * This file is part of LyX, the document processor.
  * Licence details can be found in the file COPYING.
  *

src/frontends/xforms/FormForks.C

@@ -49,7 +49,7 @@ void FormForks::build() {
 	bcview().setOK(dialog_->button_ok);
 	bcview().setApply(dialog_->button_apply);
 	bcview().setCancel(dialog_->button_close);
-	bc().invalid();
+	bc().valid(false);
 
 	// Set up the tooltip mechanism
 	string str = _("All currently running child processes forked by LyX.");

src/frontends/xforms/xformsBC.C

@@ -24,19 +24,19 @@ xformsBC::xformsBC(ButtonController const & parent,
 {}
 
 
-void xformsBC::setButtonEnabled(FL_OBJECT * obj, bool enabled)
+void xformsBC::setButtonEnabled(FL_OBJECT * obj, bool enabled) const
 {
 	setEnabled(obj, enabled);
 }
 
 
-void xformsBC::setWidgetEnabled(FL_OBJECT * obj, bool enabled)
+void xformsBC::setWidgetEnabled(FL_OBJECT * obj, bool enabled) const
 {
 	setEnabled(obj, enabled);
 }
 
 
-void xformsBC::setButtonLabel(FL_OBJECT * obj, string const & label)
+void xformsBC::setButtonLabel(FL_OBJECT * obj, string const & label) const
 {
 	fl_set_object_label(obj, label.c_str());
 }

src/frontends/xforms/xformsBC.h

@@ -27,13 +27,13 @@ public:
 
 private:
 	/// Updates the button sensitivity (enabled/disabled)
-	void setButtonEnabled(FL_OBJECT *, bool enabled);
+	void setButtonEnabled(FL_OBJECT *, bool enabled) const;
 
 	/// Updates the widget sensitivity (enabled/disabled)
-	void setWidgetEnabled(FL_OBJECT *, bool enabled);
+	void setWidgetEnabled(FL_OBJECT *, bool enabled) const;
 
 	/// Set the label on the button
-	void setButtonLabel(FL_OBJECT *, string const & label);
+	void setButtonLabel(FL_OBJECT *, string const & label) const;
 };
 
 #endif // XFORMSBC_H