third_party/WebKit/Source/core/editing/VisiblePosition.h

   1 /*
   2  * Copyright (C) 2004, 2008 Apple Inc. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
  14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
  17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #ifndef VisiblePosition_h
  27 #define VisiblePosition_h
  28
  29 #include "core/CoreExport.h"
  30 #include "core/editing/PositionWithAffinity.h"
  31 #include "core/editing/TextAffinity.h"
  32 #include "platform/heap/Handle.h"
  33
  34 namespace blink {
  35
  36 // VisiblePosition default affinity is downstream because
  37 // the callers do not really care (they just want the
  38 // deep position without regard to line position), and this
  39 // is cheaper than UPSTREAM
  40 #define VP_DEFAULT_AFFINITY TextAffinity::Downstream
  41
  42 // Callers who do not know where on the line the position is,
  43 // but would like UPSTREAM if at a line break or DOWNSTREAM
  44 // otherwise, need a clear way to specify that.  The
  45 // constructors auto-correct UPSTREAM to DOWNSTREAM if the
  46 // position is not at a line break.
  47 #define VP_UPSTREAM_IF_POSSIBLE TextAffinity::Upstream
  48
  49 class InlineBox;
  50 class Range;
  51
  52 // |VisiblePosition| is an immutable object representing "canonical position"
  53 // with affinity.
  54 //
  55 // "canonical position" is roughly equivalent to a position where we can place
  56 // caret, see |canonicalPosition()| for actual definition.
  57 //
  58 // "affinity" represents a place of caret at wrapped line. UPSTREAM affinity
  59 // means caret is placed at end of line. DOWNSTREAM affinity means caret is
  60 // placed at start of line.
  61 //
  62 // Example of affinity:
  63 //    abc^def where "^" represent |Position|
  64 // When above text line wrapped after "abc"
  65 //    abc|  UPSTREAM |VisiblePosition|
  66 //    |def  DOWNSTREAM |VisiblePosition|
  67 //
  68 // NOTE: UPSTREAM affinity will be used only if pos is at end of a wrapped line,
  69 // otherwise it will be converted to DOWNSTREAM.
  70 template <typename Strategy>
  71 class CORE_TEMPLATE_CLASS_EXPORT VisiblePositionTemplate final {
  72     DISALLOW_ALLOCATION();
  73 public:
  74     VisiblePositionTemplate();
  75
  76     // Node: Other than |createVisiblePosition()|, we should not use
  77     // |create()|.
  78     static VisiblePositionTemplate create(const PositionWithAffinityTemplate<Strategy>&);
  79
  80     // Intentionally delete |operator==()| and |operator!=()| for reducing
  81     // compilation error message.
  82     // TODO(yosin) We'll have |equals()| when we have use cases of checking
  83     // equality of both position and affinity.
  84     bool operator==(const VisiblePositionTemplate&) const = delete;
  85     bool operator!=(const VisiblePositionTemplate&) const = delete;
  86
  87     bool isNull() const { return m_positionWithAffinity.isNull(); }
  88     bool isNotNull() const { return m_positionWithAffinity.isNotNull(); }
  89     bool isOrphan() const { return deepEquivalent().isOrphan(); }
  90
  91     PositionAlgorithm<Strategy> deepEquivalent() const { return m_positionWithAffinity.position(); }
  92     PositionAlgorithm<Strategy> toParentAnchoredPosition() const { return deepEquivalent().parentAnchoredEquivalent(); }
  93     PositionWithAffinityTemplate<Strategy> toPositionWithAffinity() const { return m_positionWithAffinity; }
  94     TextAffinity affinity() const { return m_positionWithAffinity.affinity(); }
  95
  96     DEFINE_INLINE_TRACE()
  97     {
  98         visitor->trace(m_positionWithAffinity);
  99     }
 100
 101 #ifndef NDEBUG
 102     void debugPosition(const char* msg = "") const;
 103     void formatForDebugger(char* buffer, unsigned length) const;
 104     void showTreeForThis() const;
 105 #endif
 106
 107 private:
 108     explicit VisiblePositionTemplate(const PositionWithAffinityTemplate<Strategy>&);
 109
 110     PositionWithAffinityTemplate<Strategy> m_positionWithAffinity;
 111 };
 112
 113 extern template class CORE_EXTERN_TEMPLATE_EXPORT VisiblePositionTemplate<EditingStrategy>;
 114 extern template class CORE_EXTERN_TEMPLATE_EXPORT VisiblePositionTemplate<EditingInComposedTreeStrategy>;
 115
 116 using VisiblePosition = VisiblePositionTemplate<EditingStrategy>;
 117 using VisiblePositionInComposedTree = VisiblePositionTemplate<EditingInComposedTreeStrategy>;
 118
 119 CORE_EXPORT VisiblePosition createVisiblePosition(const Position&, TextAffinity = VP_DEFAULT_AFFINITY);
 120 CORE_EXPORT VisiblePosition createVisiblePosition(const PositionWithAffinity&);
 121 CORE_EXPORT VisiblePositionInComposedTree createVisiblePosition(const PositionInComposedTree&, TextAffinity = VP_DEFAULT_AFFINITY);
 122 CORE_EXPORT VisiblePositionInComposedTree createVisiblePosition(const PositionInComposedTreeWithAffinity&);
 123
 124 // TODO(yosin) Once we have composed tree version of VisibleUnits, we should not
 125 // use |createVisiblePositionInDOMTree()|.
 126 VisiblePosition createVisiblePositionInDOMTree(const Position&, TextAffinity = VP_DEFAULT_AFFINITY);
 127 VisiblePosition createVisiblePositionInDOMTree(const PositionInComposedTree&, TextAffinity = VP_DEFAULT_AFFINITY);
 128
 129 } // namespace blink
 130
 131 #ifndef NDEBUG
 132 // Outside the WebCore namespace for ease of invocation from gdb.
 133 void showTree(const blink::VisiblePosition*);
 134 void showTree(const blink::VisiblePosition&);
 135 #endif
 136
 137 #endif // VisiblePosition_h