2 Copyright (C) 2011-2013 Paul Davis
3 Author: Carl Hetherington <cth@carlh.net>
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.
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.
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.
20 /** @file canvas/canvas.h
21 * @brief Declaration of the main canvas classes.
24 #ifndef __CANVAS_CANVAS_H__
25 #define __CANVAS_CANVAS_H__
29 #include <gdkmm/window.h>
30 #include <gtkmm/eventbox.h>
31 #include <gtkmm/alignment.h>
32 #include <cairomm/surface.h>
33 #include <cairomm/context.h>
35 #include "pbd/signals.h"
37 #include "canvas/visibility.h"
39 #include "canvas/root_group.h"
50 namespace ArdourCanvas
57 /** The base class for our different types of canvas.
59 * A canvas is an area which holds a collection of canvas items, which in
60 * turn represent shapes, text, etc.
62 * The canvas has an arbitrarily large area, and is addressed in coordinates
63 * of screen pixels, with an origin of (0, 0) at the top left. x increases
64 * rightwards and y increases downwards.
67 class LIBCANVAS_API Canvas
73 /** called to request a redraw of an area of the canvas in WINDOW coordinates */
74 virtual void request_redraw (Rect const &) = 0;
75 /** called to ask the canvas to request a particular size from its host */
76 virtual void request_size (Duple) = 0;
77 /** called to ask the canvas' host to `grab' an item */
78 virtual void grab (Item *) = 0;
79 /** called to ask the canvas' host to `ungrab' any grabbed item */
80 virtual void ungrab () = 0;
82 /** called to ask the canvas' host to keyboard focus on an item */
83 virtual void focus (Item *) = 0;
84 /** called to ask the canvas' host to drop keyboard focus on an item */
85 virtual void unfocus (Item*) = 0;
87 void render (Rect const &, Cairo::RefPtr<Cairo::Context> const &) const;
89 /** @return root group */
94 void set_background_color (ArdourCanvas::Color);
95 ArdourCanvas::Color background_color() const { return _bg_color; }
97 /** Called when an item is being destroyed */
98 virtual void item_going_away (Item *, Rect) {}
99 void item_shown_or_hidden (Item *);
100 void item_visual_property_changed (Item*);
101 void item_changed (Item *, Rect);
102 void item_moved (Item *, Rect);
104 Duple canvas_to_window (Duple const&, bool rounded = true) const;
105 Duple window_to_canvas (Duple const&) const;
107 void canvas_to_window (Coord cx, Coord cy, Coord& wx, Coord& wy) {
108 Duple d = canvas_to_window (Duple (cx, cy));
113 void window_to_canvas (Coord wx, Coord wy, Coord& cx, Coord& cy) {
114 Duple d = window_to_canvas (Duple (wx, wy));
119 void scroll_to (Coord x, Coord y);
120 void add_scroller (ScrollGroup& i);
122 virtual Rect visible_area () const = 0;
123 virtual Coord width () const = 0;
124 virtual Coord height () const = 0;
126 /** Store the coordinates of the mouse pointer in window coordinates in
127 @param winpos. Return true if the position was within the window,
130 virtual bool get_mouse_position (Duple& winpos) const = 0;
132 /** Signal to be used by items that need to track the mouse position
135 sigc::signal<void,Duple const&> MouseMotion;
137 /** Ensures that the position given by @param winpos (in window
138 coordinates) is within the current window area, possibly reduced by
141 Duple clamp_to_window (Duple const& winpos, Duple border = Duple());
145 std::string indent() const;
146 std::string render_indent() const;
147 void dump (std::ostream&) const;
149 /** Ask the canvas to pick the current item again, and generate
150 an enter event for it.
152 virtual void re_enter () = 0;
154 virtual void start_tooltip_timeout (Item*) {}
155 virtual void stop_tooltip_timeout () {}
157 /** Set the timeout used to display tooltips, in milliseconds
159 static void set_tooltip_timeout (uint32_t msecs);
161 virtual Glib::RefPtr<Pango::Context> get_pango_context() = 0;
167 static uint32_t tooltip_timeout_msecs;
169 void queue_draw_item_area (Item *, Rect);
170 virtual void pick_current_item (int state) = 0;
171 virtual void pick_current_item (Duple const &, int state) = 0;
173 std::list<ScrollGroup*> scrollers;
176 /** A canvas which renders onto a GTK EventBox */
177 class LIBCANVAS_API GtkCanvas : public Canvas, public Gtk::EventBox
181 ~GtkCanvas () { _in_dtor = true ; }
183 void request_redraw (Rect const &);
184 void request_size (Duple);
188 void unfocus (Item*);
190 Rect visible_area () const;
192 Coord height() const;
194 bool get_mouse_position (Duple& winpos) const;
196 void set_single_exposure (bool s) { _single_exposure = s; }
197 bool single_exposure () { return _single_exposure; }
201 void start_tooltip_timeout (Item*);
202 void stop_tooltip_timeout ();
204 Glib::RefPtr<Pango::Context> get_pango_context();
207 void on_size_allocate (Gtk::Allocation&);
208 bool on_scroll_event (GdkEventScroll *);
209 bool on_expose_event (GdkEventExpose *);
210 bool on_key_press_event (GdkEventKey *);
211 bool on_key_release_event (GdkEventKey *);
212 bool on_button_press_event (GdkEventButton *);
213 bool on_button_release_event (GdkEventButton* event);
214 bool on_motion_notify_event (GdkEventMotion *);
215 bool on_enter_notify_event (GdkEventCrossing*);
216 bool on_leave_notify_event (GdkEventCrossing*);
218 bool button_handler (GdkEventButton *);
219 bool motion_notify_handler (GdkEventMotion *);
220 bool deliver_event (GdkEvent *);
221 void deliver_enter_leave (Duple const & point, int state);
223 void pick_current_item (int state);
224 void pick_current_item (Duple const &, int state);
227 void item_going_away (Item *, Rect);
228 bool send_leave_event (Item const *, double, double) const;
230 Cairo::RefPtr<Cairo::Surface> canvas_image;
232 /** Item currently chosen for event delivery based on pointer position */
233 Item * _current_item;
234 /** Item pending as _current_item */
235 Item * _new_current_item;
236 /** the item that is currently grabbed, or 0 */
237 Item * _grabbed_item;
238 /** the item that currently has key focus or 0 */
239 Item * _focused_item;
241 bool _single_exposure;
243 sigc::connection tooltip_timeout_connection;
244 Item* current_tooltip_item;
245 Gtk::Window* tooltip_window;
246 Gtk::Label* tooltip_label;
247 bool show_tooltip ();
248 void hide_tooltip ();
249 bool really_start_tooltip_timeout ();
254 /** A GTK::Alignment with a GtkCanvas inside it plus some Gtk::Adjustments for
257 * This provides a GtkCanvas that can be scrolled. It does NOT implement the
258 * Gtk::Scrollable interface.
260 class LIBCANVAS_API GtkCanvasViewport : public Gtk::Alignment
263 GtkCanvasViewport (Gtk::Adjustment &, Gtk::Adjustment &);
265 /** @return our GtkCanvas */
266 GtkCanvas* canvas () {
271 void on_size_request (Gtk::Requisition *);
276 Gtk::Adjustment& hadjustment;
277 Gtk::Adjustment& vadjustment;
284 std::ostream& operator<< (std::ostream&, const ArdourCanvas::Canvas&);