4 * This file is part of LyX, the document processor.
5 * Licence details can be found in the file COPYING.
7 * \author Alejandro Aguilar Sierra
9 * \author Lars Gullik Bjønnes
10 * \author Matthias Ettrich
12 * Full author contact details are available in file CREDITS.
18 #include "ColorCode.h"
19 #include "InsetCode.h"
21 #include "OutputEnums.h"
23 #include "support/strfwd.h"
24 #include "support/types.h"
40 class InsetCollapsable;
54 class ParConstIterator;
60 namespace graphics { class PreviewLoader; }
63 /** returns the InsetCode corresponding to the \c name.
64 * Eg, insetCode("branch") == BRANCH_CODE
65 * Implemented in 'Inset.cpp'.
67 InsetCode insetCode(std::string const & name);
69 std::string insetName(InsetCode);
71 /// Common base class to all insets
73 // Do not add _any_ (non-static) data members as this would inflate
74 // everything storing large quantities of insets. Mathed e.g. would
81 ENTRY_DIRECTION_IGNORE,
82 ENTRY_DIRECTION_RIGHT,
86 typedef ptrdiff_t difference_type;
87 /// short of anything else reasonable
88 typedef size_t size_type;
89 /// type for cell indices
90 typedef size_t idx_type;
91 /// type for cursor positions
92 typedef ptrdiff_t pos_type;
93 /// type for row numbers
94 typedef size_t row_type;
95 /// type for column numbers
96 typedef size_t col_type;
98 /// virtual base class destructor
101 /// change associated Buffer
102 virtual void setBuffer(Buffer & buffer);
103 /// remove the buffer reference
104 void resetBuffer() { setBuffer( *static_cast<Buffer *>(0)); }
105 /// retrieve associated Buffer
106 virtual Buffer & buffer();
107 virtual Buffer const & buffer() const;
108 /// This checks whether the Buffer * actually points to an open
109 /// Buffer. It might not if that Buffer has been closed.
110 bool isBufferValid() const;
112 /// initialize view for this inset.
114 * This is typically used after this inset is created interactively.
115 * Intented purpose is to sanitize internal state with regard to current
116 * Buffer. The default implementation calls buffer().updateLabels() if
117 * the inset is labeled.
121 virtual void initView();
122 /// \return true if this inset is labeled.
123 virtual bool isLabeled() const { return false; }
125 /// identification as math inset
126 virtual InsetMath * asInsetMath() { return 0; }
127 /// identification as math inset
128 virtual InsetMath const * asInsetMath() const { return 0; }
129 /// true for 'math' math inset, but not for e.g. mbox
130 virtual bool inMathed() const { return false; }
131 /// is this inset based on the InsetText class?
132 virtual InsetText * asInsetText() { return 0; }
133 /// is this inset based on the InsetText class?
134 virtual InsetText const * asInsetText() const { return 0; }
135 /// is this inset based on the InsetCollapsable class?
136 virtual InsetCollapsable * asInsetCollapsable() { return 0; }
137 /// is this inset based on the InsetCollapsable class?
138 virtual InsetCollapsable const * asInsetCollapsable() const { return 0; }
139 /// is this inset based on the InsetTabular class?
140 virtual InsetTabular * asInsetTabular() { return 0; }
141 /// is this inset based on the InsetTabular class?
142 virtual InsetTabular const * asInsetTabular() const { return 0; }
143 /// is this inset based on the InsetCommand class?
144 virtual InsetCommand * asInsetCommand() { return 0; }
145 /// is this inset based on the InsetCommand class?
146 virtual InsetCommand const * asInsetCommand() const { return 0; }
148 /// the real dispatcher
149 void dispatch(Cursor & cur, FuncRequest & cmd);
151 * \returns true if this function made a definitive decision on
152 * whether the inset wants to handle the request \p cmd or not.
153 * The result of this decision is put into \p status.
155 * Every request that is enabled in this method needs to be handled
156 * in doDispatch(). Normally we have a 1:1 relationship between the
157 * requests handled in getStatus() and doDispatch(), but there are
159 * - A request that is disabled in getStatus() does not need to
160 * appear in doDispatch(). It is guaranteed that doDispatch()
161 * is never called with this request.
162 * - A few requests are en- or disabled in Inset::getStatus().
163 * These need to be handled in the doDispatch() methods of the
164 * derived insets, since Inset::doDispatch() has not enough
165 * information to handle them.
166 * - LFUN_MOUSE_* need not to be handled in getStatus(), because these
167 * are dispatched directly
169 virtual bool getStatus(Cursor & cur, FuncRequest const & cmd,
170 FuncStatus & status) const;
173 virtual void edit(Cursor & cur, bool front,
174 EntryDirection entry_from = ENTRY_DIRECTION_IGNORE);
176 virtual Inset * editXY(Cursor & cur, int x, int y);
178 /// compute the size of the object returned in dim
179 /// \retval true if metrics changed.
180 virtual void metrics(MetricsInfo & mi, Dimension & dim) const = 0;
181 /// draw inset and update (xo, yo)-cache
182 virtual void draw(PainterInfo & pi, int x, int y) const = 0;
183 /// draw inset selection if necessary
184 virtual void drawSelection(PainterInfo &, int, int) const {}
185 /// draw inset background if the inset has an own background and a
186 /// selection is drawn by drawSelection.
187 virtual void drawBackground(PainterInfo &, int, int) const {}
189 virtual bool editing(BufferView const * bv) const;
191 virtual bool showInsetDialog(BufferView *) const { return false; }
193 /// draw inset decoration if necessary.
194 /// This can use \c drawMarkers() for example.
195 virtual void drawDecoration(PainterInfo &, int, int) const {}
196 /// draw four angular markers
197 void drawMarkers(PainterInfo & pi, int x, int y) const;
198 /// draw two angular markers
199 void drawMarkers2(PainterInfo & pi, int x, int y) const;
200 /// add space for markers
201 void metricsMarkers(Dimension & dim, int framesize = 1) const;
202 /// add space for markers
203 void metricsMarkers2(Dimension & dim, int framesize = 1) const;
204 /// last drawn position for 'important' insets
205 int xo(BufferView const & bv) const;
206 /// last drawn position for 'important' insets
207 int yo(BufferView const & bv) const;
208 /// set x/y drawing position cache if available
209 virtual void setPosCache(PainterInfo const &, int, int) const;
211 void setDimCache(MetricsInfo const &, Dimension const &) const;
212 /// do we cover screen position x/y?
213 virtual bool covers(BufferView const & bv, int x, int y) const;
214 /// get the screen positions of the cursor (see note in Cursor.cpp)
215 virtual void cursorPos(BufferView const & bv,
216 CursorSlice const & sl, bool boundary, int & x, int & y) const;
218 /// Allow multiple blanks
219 virtual bool isFreeSpacing() const;
220 /// Don't eliminate empty paragraphs
221 virtual bool allowEmpty() const;
222 /// Force inset into LTR environment if surroundings are RTL?
223 virtual bool forceLTR() const;
225 /// Where should we go when we press the up or down cursor key?
226 virtual bool idxUpDown(Cursor & cur, bool up) const;
227 /// Move one cell backwards
228 virtual bool idxBackward(Cursor &) const { return false; }
229 /// Move one cell forward
230 virtual bool idxForward(Cursor &) const { return false; }
232 /// Move to the next cell
233 virtual bool idxNext(Cursor &) const { return false; }
234 /// Move to the previous cell
235 virtual bool idxPrev(Cursor &) const { return false; }
237 /// Target pos when we enter the inset while moving forward
238 virtual bool idxFirst(Cursor &) const { return false; }
239 /// Target pos when we enter the inset while moving backwards
240 virtual bool idxLast(Cursor &) const { return false; }
242 /// Delete a cell and move cursor
243 virtual bool idxDelete(idx_type &) { return false; }
244 /// pulls cell after pressing erase
245 virtual void idxGlue(idx_type) {}
246 /// returns list of cell indices that are "between" from and to for
247 /// selection purposes
248 virtual bool idxBetween(idx_type idx, idx_type from, idx_type to) const;
250 /// to which column belongs a cell with a given index?
251 virtual col_type col(idx_type) const { return 0; }
252 /// to which row belongs a cell with a given index?
253 virtual row_type row(idx_type) const { return 0; }
254 /// cell index corresponding to row and column;
255 virtual idx_type index(row_type row, col_type col) const;
256 /// any additional x-offset when drawing a cell?
257 virtual int cellXOffset(idx_type) const { return 0; }
258 /// any additional y-offset when drawing a cell?
259 virtual int cellYOffset(idx_type) const { return 0; }
260 /// number of embedded cells
261 virtual size_t nargs() const { return 0; }
262 /// number of rows in gridlike structures
263 virtual size_t nrows() const { return 0; }
264 /// number of columns in gridlike structures
265 virtual size_t ncols() const { return 0; }
266 /// Is called when the cursor leaves this inset.
267 /// Returns true if cursor is now invalid, e.g. if former
268 /// insets in higher cursor slices of \c old do not exist
270 /// \c old is the old cursor, the last slice points to this.
271 /// \c cur is the new cursor. Use the update flags to cause a redraw.
272 virtual bool notifyCursorLeaves(Cursor const & /*old*/, Cursor & /*cur*/)
274 /// Is called when the cursor enters this inset.
275 /// Returns true if cursor is now invalid, e.g. if former
276 /// insets in higher cursor slices of \c old do not exist
278 /// \c cur is the new cursor, some slice points to this. Use the update flags to cause a redraw.
279 virtual bool notifyCursorEnters(Cursor & /*cur*/)
281 /// is called when the mouse enter or leave this inset
282 /// return true if this inset needs repaint
283 virtual bool setMouseHover(bool) { return false; }
284 /// return true if this inset is hovered (under mouse)
285 /// This is by now only used by mathed to draw corners
286 /// (Inset::drawMarkers() and Inset::drawMarkers2()).
287 /// Other insets do not have to redefine this function to
288 /// return the correct status of mouseHovered.
289 virtual bool mouseHovered() const { return false; }
291 /// request "external features"
292 virtual void validate(LaTeXFeatures &) const {}
294 /// describe content if cursor inside
295 virtual void infoize(odocstream &) const {}
296 /// describe content if cursor behind
297 virtual void infoize2(odocstream &) const {}
299 enum { PLAINTEXT_NEWLINE = 10000 };
301 /// plain text output in ucs4 encoding
302 /// return the number of characters; in case of multiple lines of
303 /// output, add PLAINTEXT_NEWLINE to the number of chars in the last line
304 virtual int plaintext(odocstream &, OutputParams const &) const = 0;
306 virtual int docbook(odocstream & os, OutputParams const &) const;
308 /// the inset is expected to write XHTML to the XHTMLStream
309 /// \return any "deferred" material that should be written outside the
310 /// normal stream, and which will in fact be written after the current
311 /// paragraph closes. this is appropriate e.g. for floats.
312 virtual docstring xhtml(XHTMLStream & xs, OutputParams const &) const;
313 /// the string that is passed to the TOC
314 virtual void tocString(odocstream &) const {}
316 /// can the contents of the inset be edited on screen ?
317 // true for InsetCollapsables (not ButtonOnly) (not InsetInfo), InsetText
318 virtual bool editable() const;
319 /// has the Inset settings that can be modified in a dialog ?
320 virtual bool hasSettings() const;
321 /// can we go further down on mouse click?
322 // true for InsetCaption, InsetCollapsables (not ButtonOnly), InsetTabular
323 virtual bool descendable(BufferView const &) const { return false; }
324 /// is this an inset that can be moved into?
325 /// FIXME: merge with editable()
326 // true for InsetTabular & InsetText
327 virtual bool isActive() const { return nargs() > 0; }
329 /// does this contain text that can be change track marked in DVI?
330 virtual bool canTrackChanges() const { return false; }
331 /// return true if the inset should be removed automatically
332 virtual bool autoDelete() const;
334 /// Returns true if the inset supports completions.
335 virtual bool completionSupported(Cursor const &) const { return false; }
336 /// Returns true if the inset supports inline completions at the
337 /// cursor position. In this case the completion might be stored
338 /// in the BufferView's inlineCompletion property.
339 virtual bool inlineCompletionSupported(Cursor const & /*cur*/) const
341 /// Return true if the inline completion should be automatic.
342 virtual bool automaticInlineCompletion() const { return true; }
343 /// Return true if the popup completion should be automatic.
344 virtual bool automaticPopupCompletion() const { return true; }
345 /// Return true if the cursor should indicate a completion.
346 virtual bool showCompletionCursor() const { return true; }
347 /// Returns completion suggestions at cursor position. Return an
348 /// null pointer if no completion is a available or possible.
349 /// The caller is responsible to free the returned object!
350 virtual CompletionList const * createCompletionList(Cursor const &) const
352 /// Returns the completion prefix to filter the suggestions for completion.
353 /// This is only called if completionList returned a non-null list.
354 virtual docstring completionPrefix(Cursor const &) const;
355 /// Do a completion at the cursor position. Return true on success.
356 /// The completion does not contain the prefix. If finished is true, the
357 /// completion is final. If finished is false, completion might only be
358 /// a partial completion.
359 virtual bool insertCompletion(Cursor & /*cur*/,
360 docstring const & /*completion*/, bool /*finished*/)
362 /// Get the completion inset position and size
363 virtual void completionPosAndDim(Cursor const &, int & /*x*/, int & /*y*/,
364 Dimension & /*dim*/) const {}
366 /// returns true if the inset can hold an inset of given type
367 virtual bool insetAllowed(InsetCode) const { return false; }
368 /// should this inset use the empty layout by default rather than
369 /// the standard layout? (default: only if that is forced.)
370 virtual bool usePlainLayout() const { return forcePlainLayout(); }
371 /// if this inset has paragraphs should they be forced to use the
373 virtual bool forcePlainLayout(idx_type = 0) const { return false; }
374 /// if this inset has paragraphs should the user be allowed to
375 /// customize alignment, etc?
376 virtual bool allowParagraphCustomization(idx_type = 0) const { return true; }
377 /// Is the width forced to some value?
378 virtual bool hasFixedWidth() const { return false; }
380 /// Is the content of this inset part of the output document?
381 virtual bool producesOutput() const { return true; }
383 /// \return Tool tip for this inset.
384 /// This default implementation returns an empty string.
385 virtual docstring toolTip(BufferView const & bv, int x, int y) const;
387 /// \return Context menu identifier for this inset.
388 /// This default implementation returns an empty string.
389 virtual docstring contextMenu(BufferView const & bv, int x, int y) const;
391 // FIXME This should really disappear in favor of
392 // docstring name() const { return from_ascii(insetName(lyxCode()))); }
393 // There's no reason to be using different names in different places.
394 // But to do this we would need to change the file format, since the names
395 // used there don't correspond to what is used here.
397 virtual docstring name() const;
399 virtual InsetLayout const & getLayout() const;
400 /// Is this inset's layout defined in the document's textclass?
401 bool undefined() const;
402 /// used to toggle insets
403 /// is the inset open?
404 /// should this inset be handled like a normal charater
405 virtual bool isChar() const { return false; }
406 /// is this equivalent to a letter?
407 virtual bool isLetter() const { return false; }
408 /// is this equivalent to a space (which is BTW different from
409 /// a line separator)?
410 virtual bool isSpace() const { return false; }
411 /// is this an expandible space (rubber length)?
412 virtual bool isStretchableSpace() const { return false; }
421 /// should we have a non-filled line before this inset?
422 virtual DisplayType display() const { return Inline; }
424 virtual LyXAlignment contentAlignment() const { return LYX_ALIGN_NONE; }
425 /// should we break lines after this inset?
426 virtual bool isLineSeparator() const { return false; }
427 /// should paragraph indendation be ommitted in any case?
428 virtual bool neverIndent() const { return false; }
429 /// dumps content to lyxerr
430 virtual void dump() const;
431 /// write inset in .lyx format
432 virtual void write(std::ostream &) const {}
433 /// read inset in .lyx format
434 virtual void read(Lexer &) {}
435 /** Export the inset to LaTeX.
436 * Don't use a temporary stringstream if the final output is
437 * supposed to go to a file.
438 * \sa Buffer::writeLaTeXSource for the reason.
439 * \return the number of rows (\n's) of generated LaTeX code.
441 virtual int latex(odocstream &, OutputParams const &) const { return 0; }
442 /// returns true to override begin and end inset in file
443 virtual bool directWrite() const;
445 virtual bool allowSpellCheck() const { return false; }
447 /// if this insets owns text cells (e.g. InsetText) return cell num
448 virtual Text * getText(int /*num*/) const { return 0; }
450 /** Adds a LaTeX snippet to the Preview Loader for transformation
451 * into a bitmap image. Does not start the laoding process.
453 * Most insets have no interest in this capability, so the method
456 virtual void addPreview(DocIterator const &,
457 graphics::PreviewLoader &) const {}
459 /** Classifies the unicode characters appearing in a math inset
460 * depending on whether they are to be translated as latex
461 * math/text commands or used as math symbols without translation.
463 * Only math insets have interest in this classification, so the
464 * method defaults to empty.
466 virtual void initUnicodeMath() const {}
468 /// Add an entry to the TocList
469 /// pit is the ParConstIterator of the paragraph containing the inset
470 virtual void addToToc(DocIterator const &) {}
471 /// Fill keys with BibTeX information
472 virtual void fillWithBibKeys(BiblioInfo &, InsetIterator const &) const {}
473 /// Update the counters of this inset and of its contents.
474 /// The boolean indicates whether we are preparing for output, e.g.,
476 virtual void updateLabels(ParIterator const &, UpdateType) {}
478 /// Updates the inset's dialog
479 virtual Buffer const * updateFrontend() const;
482 /// returns LyX code associated with the inset. Used for TOC, ...)
483 virtual InsetCode lyxCode() const { return NO_CODE; }
485 /// -1: text mode, 1: math mode, 0 undecided
486 enum mode_type {UNDECIDED_MODE, TEXT_MODE, MATH_MODE};
487 /// return text or mathmode if that is possible to determine
488 virtual mode_type currentMode() const { return UNDECIDED_MODE; }
489 /// returns whether changing mode during latex export is forbidden
490 virtual bool lockedMode() const { return false; }
491 /// returns whether this inset is allowed in other insets of given mode
492 virtual bool allowedIn(mode_type) const { return true; }
494 * Is this inset allowed within a font change?
496 * FIXME: noFontChange means currently that the font change is closed
497 * in LaTeX before the inset, and that the contents of the inset
498 * will be in default font. This should be changed so that the inset
499 * changes the font again.
501 virtual bool noFontChange() const { return false; }
503 /// set the change for the entire inset
504 virtual void setChange(Change const &) {}
505 /// accept the changes within the inset
506 virtual void acceptChanges() {}
507 /// reject the changes within the inset
508 virtual void rejectChanges() {}
511 virtual Dimension const dimension(BufferView const &) const;
513 int scroll() const { return 0; }
515 virtual ColorCode backgroundColor(PainterInfo const &) const;
517 virtual ColorCode labelColor() const;
519 enum { TEXT_TO_INSET_OFFSET = 4 };
523 Inset(Buffer * buf) : buffer_(buf) {}
524 Inset(Inset const &) : buffer_(0) {}
526 /// replicate ourselves
527 friend class InsetList;
528 friend class MathAtom;
529 virtual Inset * clone() const = 0;
531 /** The real dispatcher.
532 * Gets normally called from Cursor::dispatch(). Cursor::dispatch()
533 * assumes the common case of 'LFUN handled, need update'.
534 * This has to be overriden by calling Cursor::undispatched() or
535 * Cursor::noUpdate() if appropriate.
536 * If you need to call the dispatch method of some inset directly
537 * you may have to explicitly request an update at that place. Don't
538 * do it in doDispatch(), since that causes nested updates when
539 * called from Cursor::dispatch(), and these can lead to crashes.
542 virtual void doDispatch(Cursor & cur, FuncRequest & cmd);