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 bounding rectangle of the selection */
 223     NRRect *bounds(NRRect *dest) const;
 224     /** @brief Returns the bounding rectangle of the selection */
 225     ::NR::Rect bounds() const;
 226
 227     /**
 228      * @brief Returns the bounding rectangle of the selection
 229      *
 230      * \todo how is this different from bounds()?
 231      */
 232     NRRect *boundsInDocument(NRRect *dest) const;
 233
 234     /**
 235      * @brief Returns the bounding rectangle of the selection
 236      *
 237      * \todo how is this different from bounds()?
 238      */
 239     ::NR::Rect boundsInDocument() const;
 240
 241     /**
 242      * @brief Gets the selection's snap points.
 243      * @return Selection's snap points
 244      */
 245     std::vector<NR::Point> getSnapPoints() const;
 246
 247     /**
 248      * @brief Gets the snap points of a selection that form a convex hull.
 249      * @return Selection's convex hull points
 250      */
 251     std::vector<NR::Point> getSnapPointsConvexHull() const;
 252
 253     /**
 254      * @return A vector containing the top-left and bottom-right
 255      * corners of each selected object's bounding box.
 256      */
 257     std::vector<NR::Point> getBBoxPoints() const;
 258
 259     /**
 260      * @brief Connects a slot to be notified of selection changes
 261      *
 262      * This method connects the given slot such that it will
 263      * be called upon any change in the set of selected objects.
 264      *
 265      * @param slot the slot to connect
 266      *
 267      * @return the resulting connection
 268      */
 269     sigc::connection connectChanged(sigc::slot<void, Selection *> const &slot) {
 270         return _changed_signal.connect(slot);
 271     }
 272
 273     /**
 274      * @brief Connects a slot to be notified of selected
 275      *        object modifications
 276      *
 277      * This method connects the given slot such that it will
 278      * receive notifications whenever any selected item is
 279      * modified.
 280      *
 281      * @param slot the slot to connect
 282      *
 283      * @return the resulting connection
 284      *
 285      */
 286     sigc::connection connectModified(sigc::slot<void, Selection *, guint> const &slot)
 287     {
 288         return _modified_signal.connect(slot);
 289     }
 290
 291 private:
 292     /** @brief no copy */
 293     Selection(Selection const &);
 294     /** @brief no assign */
 295     void operator=(Selection const &);
 296
 297     /** @brief Issues modification notification signals */
 298     static gboolean _emit_modified(Selection *selection);
 299     /** @brief Schedules an item modification signal to be sent */
 300     static void _schedule_modified(SPObject *obj, guint flags, Selection *selection);
 301     /** @brief Releases a selected object that is being removed */
 302     static void _release(SPObject *obj, Selection *selection);
 303
 304     /** @brief Issues modified selection signal */
 305     void _emitModified(guint flags);
 306     /** @brief Issues changed selection signal */
 307     void _emitChanged();
 308
 309     void _invalidateCachedLists();
 310
 311     /** @brief unselect all descendants of the given item */
 312     void _removeObjectDescendants(SPObject *obj);
 313     /** @brief unselect all ancestors of the given item */
 314     void _removeObjectAncestors(SPObject *obj);
 315     /** @brief clears the selection (without issuing a notification) */
 316     void _clear();
 317     /** @brief adds an object (without issuing a notification) */
 318     void _add(SPObject *obj);
 319     /** @brief removes an object (without issuing a notification) */
 320     void _remove(SPObject *obj);
 321     /** @brief returns the SPObject corresponding to an xml node (if any) */
 322     SPObject *_objectForXMLNode(XML::Node *repr) const;
 323
 324     mutable GSList *_objs;
 325     mutable GSList *_reprs;
 326     mutable GSList *_items;
 327
 328     GC::soft_ptr<SPDesktop> _desktop;
 329     guint _flags;
 330     guint _idle;
 331
 332     sigc::signal<void, Selection *> _changed_signal;
 333     sigc::signal<void, Selection *, guint> _modified_signal;
 334 };
 335
 336 }
 337
 338 #endif
 339 /*
 340   Local Variables:
 341   mode:c++
 342   c-file-style:"stroustrup"
 343   c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
 344   indent-tabs-mode:nil
 345   fill-column:99
 346   End:
 347 */
 348 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:encoding=utf-8:textwidth=99 :