src/frontends/controllers/README

   1 This directory provides the controllers that act as an interface between the
   2 LyX kernel and the GUI-specific implementations of each dialog. It also
   3 provides abstract base classes from which GUI-specific implemetations of the
   4 ButtonController and each separate dialog should be derived (see
   5 ButtonControlBase.[Ch] and ViewBase.h respectively).
   6
   7 The Controller connects the GUI-specific dialog to any appropriate signals and
   8 dispatches any changes in the data to the kernel. It has no knowledge of the
   9 actual instantiation of the GUI-dependent View and ButtonController, which
  10 should therefore be created elsewhere. Once created, the Controller will take
  11 care of their initialisation, management and, ultimately, destruction.
  12
  13 This leaves the GUI-specific dialog (and its author!) to worry only about the
  14 data that it has been created to input/modify.
  15
  16 This concept has been instatiated for the Citation dialog only at the moment.
  17 See xforms-new/FormCitation.[Ch] for an xforms-specific View of the dialog.
  18
  19 How the code works.
  20 ===================
  21
  22 I'll describe Inset-type dialogs (eg, the Citation dialog). Non-inset-type
  23 (eg the Document dialog) have similar  flow, but the important controller
  24 functions are to be found in ControlDialogs.h, not ControlInset.h.
  25
  26 Let's use the citation dialog as an example.
  27
  28 The dialog is launched by :
  29         a) clicking on an existing inset, emitting the showCitation()
  30 (Dialogs.h) signal, connected to the showInset() slot
  31 (controllers/ControlInset.h) in theControlCitation c-tor.
  32         b) request a new inset (eg from the menubar), emitting a
  33 createCitation() signal (Dialogs.h) connected to the createInset()
  34 slot (controllers/ControlInset.h) in theControlCitation c-tor.
  35
  36 The user presses the Ok, Apply, Cancel or Restore buttons. In xforms
  37 these are connected to the button controller (xforms/FormCitation.C:
  38 build) so:
  39         bc().setOK(dialog_->button_ok);
  40         bc().setApply(dialog_->button_apply);
  41         bc().setCancel(dialog_->button_cancel);
  42         bc().setRestore(dialog_->button_restore);
  43 The button controller alters the state of the buttons (active/inactive).
  44 xforms works by callbacks, so clicking on say the button_ok button
  45 causes a callback event to (see FormBase.C)
  46
  47 extern "C" void C_FormBaseOKCB(FL_OBJECT * ob, long)
  48 {
  49         GetForm(ob)->OKButton();
  50 }
  51
  52 GetForm() extracts the actual instance of FormCitation that caused the
  53 event and calls OKButton() (see controllers/ViewBase.h) which in turn
  54 calls the controller's OKButton method. (The ViewBase method exists
  55 only because :
  56         /** These shortcuts allow (e.g. xform's) global callback functions
  57             access to the buttons without making the whole controller_
  58             public. */
  59
  60 So, ultimately, pressing button_ok on the Citation dialog calls
  61 ControlBase::OKButton().
  62
  63 void ControlBase::OKButton()
  64 {
  65         apply();
  66         hide();
  67         bc().ok();
  68 }
  69
  70
  71 apply() and hide() are pure virtual methods, instantiated in
  72 ControlInset.h because the Citation dialog is an inset dialog and all
  73 insets are functionally identical.
  74
  75 template <class Inset, class Params>
  76 void ControlInset<Inset, Params>::apply()
  77 {
  78         if (lv_.buffer()->isReadonly())
  79                 return;
  80
  81         view().apply();
  82
  83         if (inset_ && params() != getParams(*inset_))
  84                 applyParamsToInset();
  85         else
  86                 applyParamsNoInset();
  87 }
  88
  89 applyParamsToInset() and applyParamsNoInset(); are to be found in
  90 FormCommand.[Ch] because the citation inset is derived from
  91 InsetCommand and this subset of insets have identical internal
  92 structure and so the params can be applied in the same way.
  93