src/selection.h

   1 #ifndef SEEN_INKSCAPE_SELECTION_H
   2 #define SEEN_INKSCAPE_SELECTION_H
   3
   4 /** \file
   5  * Inkscape::Selection: per-desktop selection container
   6  *
   7  * Authors:
   8  *   Lauris Kaplinski <lauris@kaplinski.com>
   9  *   MenTaLguY <mental@rydia.net>
  10  *   bulia byak <buliabyak@users.sf.net>
  11  *
  12  * Copyright (C) 2004-2005 MenTaLguY
  13  * Copyright (C) 1999-2002 Lauris Kaplinski
  14  * Copyright (C) 2001-2002 Ximian, Inc.
  15  *
  16  * Released under GNU GPL, read the file 'COPYING' for more information
  17  */
  18
  19 #include <vector>
  20 #include <sigc++/sigc++.h>
  21
  22 #include "libnr/nr-rect.h"
  23 #include "libnr/nr-convex-hull.h"
  24 #include "forward.h"
  25 #include "gc-managed.h"
  26 #include "gc-finalized.h"
  27 #include "gc-anchored.h"
  28 #include "gc-soft-ptr.h"
  29 #include "util/list.h"
  30
  31 class SPItem;
  32
  33 namespace Inkscape {
  34 namespace XML {
  35 class Node;
  36 }
  37 }
  38
  39 namespace Inkscape {
  40
  41 /**
  42  * @brief The set of selected SPObjects for a given desktop.
  43  *
  44  * This class represents the set of selected SPItems for a given
  45  * SPDesktop.
  46  *
  47  * An SPObject and its parent cannot be simultaneously selected;
  48  * selecting an SPObjects has the side-effect of unselecting any of
  49  * its children which might have been selected.
  50  *
  51  * This is a per-desktop object that keeps the list of selected objects
  52  * at the given desktop. Both SPItem and SPRepr lists can be retrieved
  53  * from the selection. Many actions operate on the selection, so it is
  54  * widely used throughout the code.
  55  * It also implements its own asynchronous notification signals that
  56  * UI elements can listen to.
  57  */
  58 class Selection : public Inkscape::GC::Managed<>,
  59                   public Inkscape::GC::Finalized,
  60                   public Inkscape::GC::Anchored
  61 {
  62 public:
  63     /**
  64      * Constructs an selection object, bound to a particular
  65      * SPDesktop
  66      *
  67      * @param desktop the desktop in question
  68      */
  69     Selection(SPDesktop *desktop);
  70     ~Selection();
  71
  72     /**
  73      * @brief Returns the desktop the seoection is bound to
  74      *
  75      * @return the desktop the selection is bound to
  76      */
  77     SPDesktop *desktop() { return _desktop; }
  78
  79     /**
  80      * @brief Add an SPObject to the set of selected objects
  81      *
  82      * @param obj the SPObject to add
  83      */
  84     void add(SPObject *obj);
  85
  86     /**
  87      * @brief Add an XML node's SPObject to the set of selected objects
  88      *
  89      * @param the xml node of the item to add
  90      */
  91     void add(XML::Node *repr) { add(_objectForXMLNode(repr)); }
  92
  93     /**
  94      * @brief Set the selection to a single specific object
  95      *
  96      * @param obj the object to select
  97      */
  98     void set(SPObject *obj);
  99
 100     /**
 101      * @brief Set the selection to an XML node's SPObject
 102      *
 103      * @param repr the xml node of the item to select
 104      */
 105     void set(XML::Node *repr) { set(_objectForXMLNode(repr)); }
 106
 107     /**
 108      * @brief Removes an item from the set of selected objects
 109      *
 110      * It is ok to call this method for an unselected item.
 111      *
 112      * @param item the item to unselect
 113      */
 114     void remove(SPObject *obj);
 115
 116     /**
 117      * @brief Removes an item if selected, adds otherwise
 118      *
 119      * @param item the item to unselect
 120      */
 121     void toggle(SPObject *obj);
 122
 123     /**
 124      * @brief Removes an item from the set of selected objects
 125      *
 126      * It is ok to call this method for an unselected item.
 127      *
 128      * @param repr the xml node of the item to remove
 129      */
 130     void remove(XML::Node *repr) { remove(_objectForXMLNode(repr)); }
 131
 132     /**
 133      * @brief Selects exactly the specified objects
 134      *
 135      * @param objs the objects to select
 136      */
 137     void setList(GSList const *objs);
 138
 139     /**
 140      * @brief Adds the specified objects to selection, without deselecting first
 141      *
 142      * @param objs the objects to select
 143      */
 144     void addList(GSList const *objs);
 145
 146     /**
 147      * @brief Clears the selection and selects the specified objects
 148      *
 149      * @param repr a list of xml nodes for the items to select
 150      */
 151     void setReprList(GSList const *reprs);
 152
 153     /** \brief  Add items from an STL iterator range to the selection
 154      *  \param  from the begin iterator
 155      *  \param  to   the end iterator
 156      */
 157     template <typename InputIterator>
 158     void add(InputIterator from, InputIterator to) {
 159         _invalidateCachedLists();
 160         while ( from != to ) {
 161             _add(*from);
 162             ++from;
 163         }
 164         _emitChanged();
 165     }
 166
 167     /**
 168      * @brief Unselects all selected objects.
 169      */
 170     void clear();
 171
 172     /**
 173      * @brief Returns true if no items are selected
 174      */
 175     bool isEmpty() const { return _objs == NULL; }
 176
 177     /**
 178      * @brief Returns true if the given object is selected
 179      */
 180     bool includes(SPObject *obj) const;
 181
 182     /**
 183      * @brief Returns true if the given item is selected
 184      */
 185     bool includes(XML::Node *repr) const {
 186         return includes(_objectForXMLNode(repr));
 187     }
 188
 189     /**
 190      * @brief Returns a single selected object
 191      *
 192      * @return NULL unless exactly one object is selected
 193      */
 194     SPObject *single();
 195
 196     /**
 197      * @brief Returns a single selected item
 198      *
 199      * @return NULL unless exactly one object is selected
 200      */
 201     SPItem *singleItem();
 202
 203     /**
 204      * @brief Returns a single selected object's xml node
 205      *
 206      * @return NULL unless exactly one object is selected
 207      */
 208     XML::Node *singleRepr();
 209
 210     /** @brief Returns the list of selected objects */
 211     GSList const *list();
 212     /** @brief Returns the list of selected SPItems */
 213     GSList const *itemList();
 214     /** @brief Returns a list of the xml nodes of all selected objects */
 215     /// \todo only returns reprs of SPItems currently; need a separate
 216     ///      method for that
 217     GSList const *reprList();
 218
 219     /** @brief Returns the number of layers in which there are selected objects */
 220     guint numberOfLayers();
 221
 222     /** @brief Returns the number of parents to which the selected objects belong */
 223     guint numberOfParents();
 224
 225     /** @brief Returns the bounding rectangle of the selection */
 226     NRRect *bounds(NRRect *dest) const;
 227     /** @brief Returns the bounding rectangle of the selection */
 228     ::NR::Rect bounds() const;
 229
 230     /**
 231      * @brief Returns the bounding rectangle of the selection
 232      *
 233      * \todo how is this different from bounds()?
 234      */
 235     NRRect *boundsInDocument(NRRect *dest) const;
 236
 237     /**
 238      * @brief Returns the bounding rectangle of the selection
 239      *
 240      * \todo how is this different from bounds()?
 241      */
 242     ::NR::Rect boundsInDocument() const;
 243
 244     /**
 245      * @brief Returns the rotation/skew center of the selection
 246      */
 247     ::NR::Point center() const;
 248
 249     /**
 250      * @brief Gets the selection's snap points.
 251      * @return Selection's snap points
 252      */
 253     std::vector<NR::Point> getSnapPoints() const;
 254
 255     /**
 256      * @brief Gets the snap points of a selection that form a convex hull.
 257      * @return Selection's convex hull points
 258      */
 259     std::vector<NR::Point> getSnapPointsConvexHull() const;
 260
 261     /**
 262      * @return A vector containing the top-left and bottom-right
 263      * corners of each selected object's bounding box.
 264      */
 265     std::vector<NR::Point> getBBoxPoints() const;
 266
 267     /**
 268      * @brief Connects a slot to be notified of selection changes
 269      *
 270      * This method connects the given slot such that it will
 271      * be called upon any change in the set of selected objects.
 272      *
 273      * @param slot the slot to connect
 274      *
 275      * @return the resulting connection
 276      */
 277     sigc::connection connectChanged(sigc::slot<void, Selection *> const &slot) {
 278         return _changed_signal.connect(slot);
 279     }
 280
 281     /**
 282      * @brief Connects a slot to be notified of selected
 283      *        object modifications
 284      *
 285      * This method connects the given slot such that it will
 286      * receive notifications whenever any selected item is
 287      * modified.
 288      *
 289      * @param slot the slot to connect
 290      *
 291      * @return the resulting connection
 292      *
 293      */
 294     sigc::connection connectModified(sigc::slot<void, Selection *, guint> const &slot)
 295     {
 296         return _modified_signal.connect(slot);
 297     }
 298
 299 private:
 300     /** @brief no copy */
 301     Selection(Selection const &);
 302     /** @brief no assign */
 303     void operator=(Selection const &);
 304
 305     /** @brief Issues modification notification signals */
 306     static gboolean _emit_modified(Selection *selection);
 307     /** @brief Schedules an item modification signal to be sent */
 308     static void _schedule_modified(SPObject *obj, guint flags, Selection *selection);
 309     /** @brief Releases a selected object that is being removed */
 310     static void _release(SPObject *obj, Selection *selection);
 311
 312     /** @brief Issues modified selection signal */
 313     void _emitModified(guint flags);
 314     /** @brief Issues changed selection signal */
 315     void _emitChanged();
 316
 317     void _invalidateCachedLists();
 318
 319     /** @brief unselect all descendants of the given item */
 320     void _removeObjectDescendants(SPObject *obj);
 321     /** @brief unselect all ancestors of the given item */
 322     void _removeObjectAncestors(SPObject *obj);
 323     /** @brief clears the selection (without issuing a notification) */
 324     void _clear();
 325     /** @brief adds an object (without issuing a notification) */
 326     void _add(SPObject *obj);
 327     /** @brief removes an object (without issuing a notification) */
 328     void _remove(SPObject *obj);
 329     /** @brief returns the SPObject corresponding to an xml node (if any) */
 330     SPObject *_objectForXMLNode(XML::Node *repr) const;
 331
 332     mutable GSList *_objs;
 333     mutable GSList *_reprs;
 334     mutable GSList *_items;
 335
 336     GC::soft_ptr<SPDesktop> _desktop;
 337     guint _flags;
 338     guint _idle;
 339
 340     sigc::signal<void, Selection *> _changed_signal;
 341     sigc::signal<void, Selection *, guint> _modified_signal;
 342 };
 343
 344 }
 345
 346 #endif
 347 /*
 348   Local Variables:
 349   mode:c++
 350   c-file-style:"stroustrup"
 351   c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
 352   indent-tabs-mode:nil
 353   fill-column:99
 354   End:
 355 */
 356 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :