X-Git-Url: https://git.lyx.org/gitweb/?a=blobdiff_plain;f=src%2Ffrontends%2Fcontrollers%2FREADME;h=aa0ebd0fc4e909cdce52e366980c89ff292c871f;hb=120c89f24fae05379fbdc8539d3cfae574c2aecd;hp=06f2c05c5f8469eabf2b655173f7ad92289637a7;hpb=9c36dd0f40f2e2e90fce8b2f33519a5d99d9be8b;p=lyx.git

diff --git a/src/frontends/controllers/README b/src/frontends/controllers/README
index 06f2c05c5f..aa0ebd0fc4 100644
--- a/src/frontends/controllers/README
+++ b/src/frontends/controllers/README
@@ -1,17 +1,93 @@
 This directory provides the controllers that act as an interface between the
-LyX kernel and the GUI-specific implementations of each popup. It also
+LyX kernel and the GUI-specific implementations of each dialog. It also
 provides abstract base classes from which GUI-specific implemetations of the
-ButtonController and each separate popup should be derived (see
+ButtonController and each separate dialog should be derived (see
 ButtonControlBase.[Ch] and ViewBase.h respectively).
 
-The Controller connects the GUI-specific popup to any appropriate signals and
+The Controller connects the GUI-specific dialog to any appropriate signals and
 dispatches any changes in the data to the kernel. It has no knowledge of the
 actual instantiation of the GUI-dependent View and ButtonController, which
 should therefore be created elsewhere. Once created, the Controller will take
 care of their initialisation, management and, ultimately, destruction.
 
-This leaves the GUI-specific popup (and its author!) to worry only about the
+This leaves the GUI-specific dialog (and its author!) to worry only about the
 data that it has been created to input/modify.
 
 This concept has been instatiated for the Citation dialog only at the moment.
 See xforms-new/FormCitation.[Ch] for an xforms-specific View of the dialog.
+
+How the code works.
+===================
+
+I'll describe Inset-type dialogs (eg, the Citation dialog). Non-inset-type
+(eg the Document dialog) have similar  flow, but the important controller 
+functions are to be found in ControlDialogs.h, not ControlInset.h.
+
+Let's use the citation dialog as an example.
+
+The dialog is launched by :
+	a) clicking on an existing inset, emitting the showCitation()
+(Dialogs.h) signal, connected to the showInset() slot
+(controllers/ControlInset.h) in theControlCitation c-tor.
+	b) request a new inset (eg from the menubar), emitting a
+createCitation() signal (Dialogs.h) connected to the createInset()
+slot (controllers/ControlInset.h) in theControlCitation c-tor. 
+
+The user presses the Ok, Apply, Cancel or Restore buttons. In xforms
+these are connected to the button controller (xforms/FormCitation.C:
+build) so: 
+	bc().setOK(dialog_->button_ok);
+	bc().setApply(dialog_->button_apply);
+	bc().setCancel(dialog_->button_cancel);
+	bc().setRestore(dialog_->button_restore);
+The button controller alters the state of the buttons (active/inactive). 
+xforms works by callbacks, so clicking on say the button_ok button
+causes a callback event to (see FormBase.C) 
+
+extern "C" void C_FormBaseOKCB(FL_OBJECT * ob, long)
+{
+	GetForm(ob)->OKButton();
+}
+
+GetForm() extracts the actual instance of FormCitation that caused the
+event and calls OKButton() (see controllers/ViewBase.h) which in turn
+calls the controller's OKButton method. (The ViewBase method exists
+only because : 
+	/** These shortcuts allow (e.g. xform's) global callback functions
+	    access to the buttons without making the whole controller_
+	    public. */
+
+So, ultimately, pressing button_ok on the Citation dialog calls
+ControlBase::OKButton(). 
+
+void ControlBase::OKButton()
+{
+	apply();
+	hide();
+	bc().ok();
+}
+
+
+apply() and hide() are pure virtual methods, instantiated in
+ControlInset.h because the Citation dialog is an inset dialog and all
+insets are functionally identical. 
+
+template <class Inset, class Params>
+void ControlInset<Inset, Params>::apply()
+{
+	if (lv_.buffer()->isReadonly())
+		return;
+
+	view().apply();
+
+	if (inset_ && params() != getParams(*inset_))
+		applyParamsToInset();
+	else
+		applyParamsNoInset();
+}
+
+applyParamsToInset() and applyParamsNoInset(); are to be found in
+FormCommand.[Ch] because the citation inset is derived from
+InsetCommand and this subset of insets have identical internal
+structure and so the params can be applied in the same way. 
+