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.
+
projects / lyx.git / blobdiff