libs/canvas/canvas/item.h

   1 /*
   2     Copyright (C) 2011-2013 Paul Davis
   3     Original Author: Carl Hetherington <cth@carlh.net>
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  18 */
  19
  20 #ifndef __CANVAS_ITEM_H__
  21 #define __CANVAS_ITEM_H__
  22
  23 #include <stdint.h>
  24
  25 #include <gdk/gdk.h>
  26
  27 #include <cairomm/context.h>
  28
  29 #include "pbd/signals.h"
  30
  31 #include "canvas/types.h"
  32
  33 namespace ArdourCanvas
  34 {
  35
  36 class Canvas;
  37 class Group;
  38 class Rect;
  39
  40 /** The parent class for anything that goes on the canvas.
  41  *
  42  *  Items have a position, which is expressed in the coordinates of the parent.
  43  *  They also have a bounding box, which describes the area in which they have
  44  *  drawable content, which is expressed in their own coordinates (whose origin
  45  *  is at the item position).
  46  *
  47  *  Any item that is being displayed on a canvas has a pointer to that canvas,
  48  *  and all except the `root group' have a pointer to their parent group.
  49  */
  50
  51 class Item
  52 {
  53 public:
  54         Item (Canvas *);
  55         Item (Group *);
  56         Item (Group *, Duple);
  57         virtual ~Item ();
  58
  59         /** Render this item to a Cairo context.
  60          *  @param area Area to draw in this item's coordinates.
  61          */
  62         virtual void render (Rect const & area, Cairo::RefPtr<Cairo::Context>) const = 0;
  63
  64         virtual void add_items_at_point (Duple, std::vector<Item const *>& items) const {
  65                 items.push_back (this);
  66         }
  67
  68         /** Update _bounding_box and _bounding_box_dirty */
  69         virtual void compute_bounding_box () const = 0;
  70
  71         void grab ();
  72         void ungrab ();
  73
  74         void unparent ();
  75         void reparent (Group *);
  76
  77         /** @return Parent group, or 0 if this is the root group */
  78         Group* parent () const {
  79                 return _parent;
  80         }
  81
  82         void set_position (Duple);
  83         void set_x_position (Coord);
  84         void set_y_position (Coord);
  85         void move (Duple);
  86
  87         /** @return Position of this item in the parent's coordinates */
  88         Duple position () const {
  89                 return _position;
  90         }
  91
  92         boost::optional<Rect> bounding_box () const;
  93         Coord height() const;
  94         Coord width() const;
  95
  96         Duple item_to_parent (Duple const &) const;
  97         Rect item_to_parent (Rect const &) const;
  98         Duple parent_to_item (Duple const &) const;
  99         Rect parent_to_item (Rect const &) const;
 100         /* XXX: it's a pity these aren't the same form as item_to_parent etc.,
 101            but it makes a bit of a mess in the rest of the code if they are not.
 102         */
 103
 104         void canvas_to_item (Coord &, Coord &) const;
 105         Duple canvas_to_item (Duple const &) const;
 106         void item_to_canvas (Coord &, Coord &) const;
 107         Rect item_to_canvas (Rect const &) const;
 108         Duple item_to_canvas (Duple const &) const;
 109
 110         void raise_to_top ();
 111         void raise (int);
 112         void lower_to_bottom ();
 113
 114         void hide ();
 115         void show ();
 116
 117         /** @return true if this item is visible (ie it will be rendered),
 118          *  otherwise false
 119          */
 120         bool visible () const {
 121                 return _visible;
 122         }
 123
 124         /** @return Our canvas, or 0 if we are not attached to one */
 125         Canvas* canvas () const {
 126                 return _canvas;
 127         }
 128
 129         void set_ignore_events (bool);
 130         bool ignore_events () const {
 131                 return _ignore_events;
 132         }
 133
 134         void set_data (std::string const &, void *);
 135         void* get_data (std::string const &) const;
 136
 137         /* This is a sigc++ signal because it is solely
 138            concerned with GUI stuff and is thus single-threaded
 139         */
 140
 141         template <class T>
 142         struct EventAccumulator {
 143                 typedef T result_type;
 144                 template <class U>
 145                 result_type operator () (U first, U last) {
 146                         while (first != last) {
 147                                 if (*first) {
 148                                         return true;
 149                                 }
 150                                 ++first;
 151                         }
 152                         return false;
 153                 }
 154         };
 155
 156         sigc::signal1<bool, GdkEvent*, EventAccumulator<bool> > Event;
 157
 158 #ifdef CANVAS_DEBUG
 159         std::string name;
 160 #endif
 161
 162 #ifdef CANVAS_COMPATIBILITY
 163         void grab_focus ();
 164 #endif
 165
 166         virtual void dump (std::ostream&) const;
 167         std::string whatami() const;
 168
 169 protected:
 170
 171         void begin_change ();
 172         void end_change ();
 173
 174         Canvas* _canvas;
 175         /** parent group; may be 0 if we are the root group or if we have been unparent()ed */
 176         Group* _parent;
 177         /** position of this item in parent coordinates */
 178         Duple _position;
 179         /** true if this item is visible (ie to be drawn), otherwise false */
 180         bool _visible;
 181         /** our bounding box before any change that is currently in progress */
 182         boost::optional<Rect> _pre_change_bounding_box;
 183
 184         /** our bounding box; may be out of date if _bounding_box_dirty is true */
 185         mutable boost::optional<Rect> _bounding_box;
 186         /** true if _bounding_box might be out of date, false if its definitely not */
 187         mutable bool _bounding_box_dirty;
 188
 189         /* XXX: this is a bit grubby */
 190         std::map<std::string, void *> _data;
 191
 192 private:
 193         void init ();
 194
 195         bool _ignore_events;
 196 };
 197
 198 extern std::ostream& operator<< (std::ostream&, const ArdourCanvas::Item&);
 199
 200 }
 201
 202
 203 #endif