Introduce Selection class

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

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef Selection_h
+#define Selection_h
+
+#include "base/macros.h"
+#include "core/CoreExport.h"
+#include "core/editing/EphemeralRange.h"
+#include "core/editing/Position.h"
+#include "core/editing/PositionWithAffinity.h"
+#include "core/editing/TextAffinity.h"
+#include "core/editing/TextGranularity.h"
+#include "wtf/Allocator.h"
+#include <iosfwd>
+
+namespace blink {
+
+// SelectionTemplate represents selection for using constructing
+// |VisibleSeleciton| and parameter/return value. |SelectionTemplate| is
+// pseudo immutable object, you can't change members.

[Xiaocheng, 2016/10/06 08:02:33]

I can't understand the first sentence... Please rephrase.

Besides, I think just saying it's immutable is good enough, as
"pseudo-immutable" is confusing.

[yosin_UTC9, 2016/10/07 08:46:57]

Done.

+//
+// To construct |SelectionTemplate| object, please use |Builder| class.
+template <typename Strategy>
+class CORE_EXPORT SelectionTemplate final {
+  DISALLOW_NEW();
+
+ public:
+  // |Builder| is a helper class for constructing |SelectionTemplate| object.

[yoichio, 2016/10/06 08:52:17]

Who use this class and how does?

[yosin_UTC9, 2016/10/07 08:46:57]

We'll use |Builder| class everywhere we construct |Selection| object.
"SelectionTest.cpp" and http://crrev.com/1958093002 have usage samples.

+  class CORE_EXPORT Builder final {
+    DISALLOW_NEW();
+
+   public:
+    explicit Builder(const SelectionTemplate&);
+    Builder();
+
+    SelectionTemplate build() const;
+
+    // Move selection to |base|. |base| can't be null.

[yoichio, 2016/10/07 04:30:40]

How about naming |setBase| and |setExtent| so that
 Builder is a builder rather than Selection API.

[yosin_UTC9, 2016/10/07 08:46:57]

No, we don't want to have base=null, extent=non-null case.
Clients of |Builder| class should use:
 - collapse(base).extend(extent)
 - setBaseAndExtent(base, extent)
 - setBaseAndExtent(range)
 - setBaseAndExtentDeprecated(base, extent); for execCommand

[yoichio, 2016/10/07 09:32:13]

setBase(base).setExtent(extent) doesn't work?
We can assert when |base=null, extent=non-null| in setExtent()
 or build().
I don't think builder behaves as real Selection class.
It should be just a container.

+    Builder& collapse(const PositionTemplate<Strategy>& base);
+    Builder& collapse(const PositionWithAffinityTemplate<Strategy>& base);
+
+    // Extend selection to |extent|. It is error if selection is none.
+    Builder& extend(const PositionTemplate<Strategy>& extent);
+
+    Builder& setBaseAndExtent(const EphemeralRangeTemplate<Strategy>&);
+
+    // |extent| can not be null if |base| isn't null.
+    Builder& setBaseAndExtent(const PositionTemplate<Strategy>& base,
+                              const PositionTemplate<Strategy>& extent);
+
+    // Both |base| and |extent| can be null.

[Xiaocheng, 2016/10/06 08:02:33]

I would prefer changing the comment to "|extent| can be non-null while |base| is
null, which is undesired." to emphasize what is wrong with the deprecated
version.

[yosin_UTC9, 2016/10/07 08:46:57]

Done.

+    Builder& setBaseAndExtentDeprecated(
+        const PositionTemplate<Strategy>& base,
+        const PositionTemplate<Strategy>& extent);
+
+    Builder& setAffinity(TextAffinity);
+    Builder& setGranularity(TextGranularity);
+    Builder& setHasTrailingWhitespace(bool);
+    Builder& setIsDirectional(bool);
+
+   private:
+    SelectionTemplate m_selection;
+
+    DISALLOW_COPY_AND_ASSIGN(Builder);
+  };
+
+  SelectionTemplate(const SelectionTemplate& other);
+  SelectionTemplate();
+
+  SelectionTemplate& operator=(const SelectionTemplate&) = default;
+
+  bool operator==(const SelectionTemplate&) const;
+  bool operator!=(const SelectionTemplate&) const;
+
+  const PositionTemplate<Strategy>& base() const;
+  const PositionTemplate<Strategy>& extent() const;
+  TextAffinity affinity() const { return m_affinity; }
+  TextGranularity granularity() const { return m_granularity; }
+  bool hasTrailingWhitespace() const { return m_hasTrailingWhitespace; }
+  bool isDirectional() const { return m_isDirectional; }
+  bool isNone() const { return m_base.isNull(); }
+
+  void assertValid() const;
+  void assertValidFor(const Document&) const;
+
+  DEFINE_INLINE_TRACE() {
+    visitor->trace(m_base);
+    visitor->trace(m_extent);
+  }
+
+  void printTo(std::ostream*, const char* type) const;
+
+ private:
+  friend class SelectionEditor;
+
+  Document* document() const;
+
+  PositionTemplate<Strategy> m_base;
+  PositionTemplate<Strategy> m_extent;
+  TextAffinity m_affinity = TextAffinity::Downstream;
+  TextGranularity m_granularity = CharacterGranularity;
+  bool m_hasTrailingWhitespace = false;
+  bool m_isDirectional = false;
+#if ENABLE(ASSERT)

[tkent, 2016/10/07 00:13:27]

ENABLE(ASSERT) -> DCHECK_IS_ON()

[yosin_UTC9, 2016/10/07 08:46:57]

Done.

+  uint64_t m_domTreeVersion;
+#endif
+};
+
+extern template class CORE_EXTERN_TEMPLATE_EXPORT
+    SelectionTemplate<EditingStrategy>;
+extern template class CORE_EXTERN_TEMPLATE_EXPORT
+    SelectionTemplate<EditingInFlatTreeStrategy>;
+
+using Selection = SelectionTemplate<EditingStrategy>;
+using SelectionInFlatTree = SelectionTemplate<EditingInFlatTreeStrategy>;
+
+CORE_EXPORT std::ostream& operator<<(std::ostream&, const Selection&);
+CORE_EXPORT std::ostream& operator<<(std::ostream&, const SelectionInFlatTree&);
+
+}  // namespace blink
+
+#endif  // Selection_h