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