From 9c07ca6fa6d1f672d40c8c11a907c6bbc3592a6f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Krzysztof=20Kosi=C5=84ski?= Date: Wed, 13 Jan 2010 01:04:25 +0100 Subject: [PATCH] Some additional docs --- src/ui/tool/node.cpp | 24 ++++++++++++++++-------- src/ui/tool/node.h | 24 ++++++++++++++++++++++++ src/ui/tool/transform-handle-set.cpp | 15 +++------------ 3 files changed, 43 insertions(+), 20 deletions(-) diff --git a/src/ui/tool/node.cpp b/src/ui/tool/node.cpp index adef8e5a7..889f4a793 100644 --- a/src/ui/tool/node.cpp +++ b/src/ui/tool/node.cpp @@ -71,7 +71,10 @@ static Geom::Point direction(Geom::Point const &first, Geom::Point const &second /** * @class Handle - * Represents a control point of a cubic Bezier curve in a path. + * @brief Control point of a cubic Bezier curve in a path. + * + * Handle keeps the node type invariant only for the opposite handle of the same node. + * Keeping the invariant on node moves is left to the %Node class. */ double Handle::_saved_length = 0.0; @@ -320,7 +323,9 @@ Glib::ustring Handle::_getDragTip(GdkEventMotion *event) /** * @class Node - * Represents a curve endpoint in an editable path. + * @brief Curve endpoint in an editable path. + * + * The method move() keeps node type invariants during translations. */ Node::Node(NodeSharedData const &data, Geom::Point const &initial_pos) @@ -554,6 +559,8 @@ void Node::setType(NodeType type, bool update_handles) updateState(); } +/** Pick the best type for this node, based on the position of its handles. + * This is what assigns types to nodes created using the pen tool. */ void Node::pickBestType() { _type = NODE_CUSP; @@ -652,7 +659,7 @@ bool Node::_eventHandler(GdkEvent *event) return ControlPoint::_eventHandler(event); } -// TODO Move this to 2Geom +// TODO Move this to 2Geom! static double bezier_length (Geom::Point a0, Geom::Point a1, Geom::Point a2, Geom::Point a3) { double lower = Geom::distance(a0, a3); @@ -844,11 +851,12 @@ void Node::_draggedHandler(Geom::Point &new_pos, GdkEventMotion *event) bool snap = sm.someSnapperMightSnap(); std::vector< std::pair > unselected; if (snap) { - // setup - // TODO we are doing this every time a snap happens. It should once be done only once - // per drag - maybe in the grabbed handler? - // TODO "unselected" must be valid during the snap run, because it is not copied. - // Fix this in snap.h and snap.cpp, then the above. + /* setup + * TODO We are doing this every time a snap happens. It should once be done only once + * per drag - maybe in the grabbed handler? + * TODO Unselected nodes vector must be valid during the snap run, because it is not + * copied. Fix this in snap.h and snap.cpp, then the above. + * TODO Snapping to unselected segments of selected paths doesn't work. */ // Build the list of unselected nodes. typedef ControlPointSelection::Set Set; diff --git a/src/ui/tool/node.h b/src/ui/tool/node.h index a85877d5c..d822d854f 100644 --- a/src/ui/tool/node.h +++ b/src/ui/tool/node.h @@ -171,6 +171,28 @@ private: friend class NodeIterator; }; +/// Iterator for editable nodes +/** Use this class for all operations that require some knowledge about the node's + * neighbors. It works like a bidirectional iterator. + * + * Because paths can be cyclic, node iterators have two different ways to + * increment and decrement them. Nodes can be iterated over either in the + * sequence order, which always has a beginning and an end, or in the path order, + * which can be cyclic (moving to the next node never yields the end iterator). + * + * When @a i is a node iterator, then: + * - ++i moves the iterator to the next node in sequence order; + * - --i moves the iterator to the previous node in sequence order; + * - i.next() returns the next node with wrap-around if the path is cyclic; + * - i.prev() returns the previous node with wrap-around if the path is cyclic. + * + * next() and prev() do not change their iterator. They can return the end iterator + * if the path is open. + * + * Unlike most other iterators, you can check whether a node iterator is invalid + * (is an end iterator) without having access to the iterator's container. + * Simply use if (i) { ... + * */ template class NodeIterator : public boost::bidirectional_iterator_helper, N, std::ptrdiff_t, @@ -194,7 +216,9 @@ public: bool operator==(self const &other) const { return _node == other._node; } N &operator*() const { return *static_cast(_node); } inline operator bool() const; // define after NodeList + /// Get a pointer to the underlying node. Equivalent to &*i. N *get_pointer() const { return static_cast(_node); } + /// @see get_pointer() N *ptr() const { return static_cast(_node); } self next() const; diff --git a/src/ui/tool/transform-handle-set.cpp b/src/ui/tool/transform-handle-set.cpp index d6181dbf4..cf8907299 100644 --- a/src/ui/tool/transform-handle-set.cpp +++ b/src/ui/tool/transform-handle-set.cpp @@ -171,7 +171,7 @@ protected: double ScaleHandle::_last_scale_x = 1.0; double ScaleHandle::_last_scale_y = 1.0; -/** Corner scaling handle for node transforms */ +/// Corner scaling handle for node transforms class ScaleCornerHandle : public ScaleHandle { public: ScaleCornerHandle(TransformHandleSet &th, unsigned corner) @@ -225,7 +225,7 @@ private: unsigned _corner; }; -/** Side scaling handle for node transforms */ +/// Side scaling handle for node transforms class ScaleSideHandle : public ScaleHandle { public: ScaleSideHandle(TransformHandleSet &th, unsigned side) @@ -281,7 +281,7 @@ private: unsigned _side; }; -/** Rotation handle for nodes */ +/// Rotation handle for node transforms class RotateHandle : public TransformHandle { public: RotateHandle(TransformHandleSet &th, unsigned corner) @@ -339,15 +339,6 @@ private: default: return Glib::wrap(handles[4], true); } } - /* - static Geom::Point _corner_to_offset_unit(unsigned c) { - switch (c % 4) { - case 0: return Geom::Point(-1, 1); - case 1: return Geom::Point(1, 1); - case 2: return Geom::Point(1, -1); - default: return Geom::Point(-1, -1); - } - }*/ Geom::Point _rot_center; Geom::Point _rot_opposite; unsigned _corner; -- 2.30.2