src/frontends/Dialog.h

   1 // -*- C++ -*-
   2 /**
   3  * \file Dialog.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Angus Leeming
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  */
  11
  12 #ifndef DIALOG_H
  13 #define DIALOG_H
  14
  15 #include "lfuns.h"
  16
  17 #include "support/docstring.h"
  18 #include <string>
  19
  20 namespace lyx {
  21
  22 class Buffer;
  23 class BufferView;
  24 class FuncRequest;
  25
  26 namespace frontend {
  27
  28 class LyXView;
  29
  30 /** \enum KernelDocType used to flag the different kinds of buffer
  31  *  without making the kernel header files available to the
  32  *  dialog's Controller or View.
  33  */
  34 enum KernelDocType
  35 {
  36         LATEX,
  37         LITERATE,
  38         DOCBOOK
  39 };
  40
  41
  42 /** Different dialogs will have different Controllers and Views.
  43  *  deriving from these base classes.
  44  */
  45 //@{
  46 class Controller;
  47 //@}
  48
  49 /** \c Dialog collects the different parts of a Model-Controller-View
  50  *  split of a generic dialog together.
  51  */
  52 class Dialog
  53 {
  54 public:
  55         /// \param lv is the access point for the dialog to the LyX kernel.
  56         /// \param name is the identifier given to the dialog by its parent
  57         /// container.
  58         Dialog() {}
  59         virtual ~Dialog();
  60
  61         /** \name Container Access
  62          *  These methods are publicly accessible because they are invoked
  63          *  by the parent container acting on commands from the LyX kernel.
  64          */
  65         //@{
  66         /// \param data is a string encoding of the data to be displayed.
  67         /// It is passed to the Controller to be translated into a useable form.
  68         virtual void showData(std::string const & /*data*/) {}
  69         virtual void updateData(std::string const & /*data*/) {}
  70
  71         virtual void hide() {}
  72
  73         // Override in GuiDialog
  74         virtual void slotOK() {}
  75         virtual void slotApply() {}
  76         virtual void slotRestore() {}
  77         virtual void slotClose() {}
  78
  79         /** This function is called, for example, if the GUI colours
  80          *  have been changed.
  81          */
  82         virtual void redraw() {}
  83         //@}
  84
  85         /** Check whether we may apply our data.
  86          *
  87          *  The buttons are disabled if not and (re-)enabled if yes.
  88          */
  89         virtual void checkStatus() {}
  90
  91         /** When applying, it's useful to know whether the dialog is about
  92          *  to close or not (no point refreshing the display for example).
  93          */
  94         virtual bool isClosing() const { return false; }
  95
  96         /** \name Dialog Specialization
  97          *  Methods to set the Controller and View and so specialise
  98          *  to a particular dialog.
  99          */
 100         //@{
 101         virtual Controller & controller() = 0;
 102         //@}
 103
 104         /** \c Button controller part
 105          */
 106         virtual void setButtonsValid(bool /*valid*/) {}
 107
 108
 109         /** \c View part
 110          *  of a Model-Controller-View split of a generic dialog.
 111          *  These few methods are all that a generic dialog needs of a
 112          *  view.
 113          */
 114         //@{
 115         /** A request to modify the data structures stored by the
 116          *  accompanying Controller in preparation for their dispatch to
 117          *  the LyX kernel.
 118          */
 119         virtual void applyView() = 0;
 120
 121         /// Hide the dialog from sight
 122         virtual void hideView() = 0;
 123
 124         /// Redraw the dialog (e.g. if the colors have been remapped).
 125         virtual void redrawView() = 0;
 126
 127         /// Create the dialog if necessary, update it and display it.
 128         virtual void showView() = 0;
 129
 130         /// Update the display of the dialog whilst it is still visible.
 131         virtual void updateView() = 0;
 132
 133         /// \return true if the dialog is visible.
 134         virtual bool isVisibleView() const = 0;
 135         //@}
 136
 137         /** Defaults to nothing. Can be used by the Controller, however, to
 138          *  indicate to the View that something has changed and that the
 139          *  dialog therefore needs updating.
 140          *  \param id identifies what should be updated.
 141          */
 142         virtual void partialUpdateView(int /*id*/) = 0;
 143
 144         ///
 145         virtual std::string name() const = 0;
 146
 147 protected:
 148         virtual void apply() {}
 149
 150 private:
 151         /// intentionally unimplemented, therefore uncopiable
 152         Dialog(Dialog const &);
 153         void operator=(Dialog const &);
 154 };
 155
 156
 157 /** \c Controller is an abstract base class for the Controller
 158  *  of a Model-Controller-View split of a generic dialog.
 159  */
 160 class Controller
 161 {
 162 public:
 163         /// \param parent Dialog owning this Controller.
 164         Controller(Dialog & parent);
 165         // the same. avoids ambiguity with the (non-existent) copy constructor
 166         Controller(Dialog * parent);
 167         virtual ~Controller();
 168         void setLyXView(LyXView & lv) { lyxview_ = &lv; }
 169
 170         /** \name Generic Controller
 171          *  These few methods are all that a generic dialog needs of a
 172          *  controller.
 173          */
 174         //@{
 175         /** Enable the controller to initialise its data structures.
 176          *  \param data is a string encoding of the parameters to be displayed.
 177          *  \return true if the translation was successful.
 178          */
 179         virtual bool initialiseParams(std::string const & data) = 0;
 180
 181         /// Enable the controller to clean up its data structures.
 182         virtual void clearParams() = 0;
 183
 184         /// Enable the Controller to dispatch its data back to the LyX kernel.
 185         virtual void dispatchParams() = 0;
 186
 187         /** \return true if the dialog should be shown only when
 188          *  a buffer is open.
 189          */
 190         virtual bool isBufferDependent() const = 0;
 191
 192         /** \return true if the dialog can apply data also
 193          *  for ReadOnly buffers.
 194          *  This has to be distinguished from isBufferDependent()
 195          */
 196         virtual bool canApplyToReadOnly() const { return false; }
 197
 198         /** The lfun that is sent for applying the data.
 199          *
 200          * This method is used by the default implementation of canApply()
 201          * for buffer dependent dialogs that send one lfun when applying the
 202          * data.
 203          * It should be used in dispatchParams(), too for consistency reasons.
 204          *  \returns the lfun that is sent for applying the data.
 205          */
 206         virtual kb_action getLfun() const { return LFUN_INSET_APPLY; }
 207
 208         /** Check whether we may apply our data.
 209          *
 210          * The default implementation works for all dialogs that send one
 211          * lfun when applying the data. Dialogs that send none or more than
 212          * one lfun need to reimplement it.
 213          *  \returns whether the data can be applied or not.
 214          */
 215         virtual bool canApply() const;
 216
 217         /** \return true if the kernel should disconnect the dialog from
 218          *  a particular inset after the data has been applied to it.
 219          *  Clearly this makes sense only for dialogs modifying the contents
 220          *  of an inset :-)
 221          *  In practise, only a very few dialogs (e.g. the citation dialog)
 222          *  return true.
 223          */
 224         virtual bool disconnectOnApply() const { return false; }
 225
 226         /** \return true if Dialog::View::show() should not display the dialog
 227          *   after running update. Currently, only ControlSpellchecker
 228          *   makes use of that.
 229         */
 230         virtual bool exitEarly() const { return false; }
 231         //@}
 232 public:
 233         /** \name Controller Access
 234          *  Enable the derived classes to access the other parts of the whole.
 235          */
 236         //@{
 237         Dialog & dialog() { return parent_; }
 238         Dialog const & dialog() const { return parent_; }
 239         //@}
 240
 241         /** \c Kernel part: a wrapper making the LyX kernel available to the dialog.
 242          * (Ie, it provides an interface to the Model part of the Model-Controller-
 243          *  View split.
 244          *  In an ideal world, it will shrink as more info is passed to the
 245          *  Dialog::show() and Dialog::update() methods.
 246          */
 247
 248
 249         /** This method is the primary purpose of the class. It provides
 250          *  the "gateway" by which the dialog can send a request (of a
 251          *  change in the data, for more information) to the kernel.
 252          *  \param fr is the encoding of the request.
 253          */
 254         void dispatch(FuncRequest const & fr) const;
 255
 256         /** The dialog has received a request from the user
 257          *  (who pressed the "Restore" button) to update contents.
 258          *  It must, therefore, ask the kernel to provide this information.
 259          *  \param name is used to identify the dialog to the kernel.
 260          */
 261         void updateDialog(std::string const & name) const;
 262
 263         /** A request from the Controller that future changes to the data
 264          *  stored by the dialog are not applied to the inset currently
 265          *  connected to the dialog. Instead, they will be used to generate
 266          *  a new inset at the cursor position.
 267          *  \param name is used to identify the dialog to the kernel.
 268          */
 269         void disconnect(std::string const & name) const;
 270
 271         /** \name Kernel Wrappers
 272          *  Simple wrapper functions to Buffer methods.
 273          */
 274         //@{
 275         bool isBufferAvailable() const;
 276         bool isBufferReadonly() const;
 277         std::string const bufferFilepath() const;
 278         //@}
 279
 280         /// The type of the current buffer.
 281         KernelDocType docType() const;
 282
 283         /** \name Kernel Nasties
 284          *  Unpleasantly public internals of the LyX kernel.
 285          *  We should aim to reduce/remove these from the interface.
 286          */
 287         //@{
 288         LyXView & lyxview() { return *lyxview_; }
 289         LyXView const & lyxview() const { return *lyxview_; }
 290
 291         Buffer & buffer();
 292         Buffer const & buffer() const;
 293
 294         BufferView * bufferview();
 295         BufferView const * bufferview() const;
 296         //@}
 297
 298 private:
 299         /// intentionally unimplemented, therefore uncopiable
 300         Controller(Controller const &);
 301         void operator=(Controller const &);
 302
 303 private:
 304         Dialog & parent_;
 305         LyXView * lyxview_;
 306 };
 307
 308
 309 } // namespace frontend
 310 } // namespace lyx
 311
 312 #endif // DIALOG_H