libs/canvas/canvas/canvas.h

   1 /*
   2     Copyright (C) 2011-2013 Paul Davis
   3     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 /** @file  canvas/canvas.h
  21  *  @brief Declaration of the main canvas classes.
  22  */
  23
  24 #ifndef __CANVAS_CANVAS_H__
  25 #define __CANVAS_CANVAS_H__
  26
  27 #include <set>
  28
  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>
  34
  35 #include "pbd/signals.h"
  36
  37 #include "canvas/visibility.h"
  38
  39 #include "canvas/root_group.h"
  40
  41 namespace Gtk {
  42         class Window;
  43         class Label;
  44 }
  45
  46 namespace ArdourCanvas
  47 {
  48 struct Rect;
  49
  50 class Item;
  51 class ScrollGroup;
  52
  53 /** The base class for our different types of canvas.
  54  *
  55  *  A canvas is an area which holds a collection of canvas items, which in
  56  *  turn represent shapes, text, etc.
  57  *
  58  *  The canvas has an arbitrarily large area, and is addressed in coordinates
  59  *  of screen pixels, with an origin of (0, 0) at the top left.  x increases
  60  *  rightwards and y increases downwards.
  61  */
  62
  63 class LIBCANVAS_API Canvas
  64 {
  65 public:
  66         Canvas ();
  67         virtual ~Canvas () {}
  68
  69         /** called to request a redraw of an area of the canvas in WINDOW coordinates */
  70         virtual void request_redraw (Rect const &) = 0;
  71         /** called to ask the canvas to request a particular size from its host */
  72         virtual void request_size (Duple) = 0;
  73         /** called to ask the canvas' host to `grab' an item */
  74         virtual void grab (Item *) = 0;
  75         /** called to ask the canvas' host to `ungrab' any grabbed item */
  76         virtual void ungrab () = 0;
  77
  78         /** called to ask the canvas' host to keyboard focus on an item */
  79         virtual void focus (Item *) = 0;
  80         /** called to ask the canvas' host to drop keyboard focus on an item */
  81         virtual void unfocus (Item*) = 0;
  82
  83         void render (Rect const &, Cairo::RefPtr<Cairo::Context> const &) const;
  84
  85         /** @return root group */
  86         Item* root () {
  87                 return &_root;
  88         }
  89
  90         /** Called when an item is being destroyed */
  91         virtual void item_going_away (Item *, boost::optional<Rect>) {}
  92         void item_shown_or_hidden (Item *);
  93         void item_visual_property_changed (Item*);
  94         void item_changed (Item *, boost::optional<Rect>);
  95         void item_moved (Item *, boost::optional<Rect>);
  96
  97         Duple canvas_to_window (Duple const&, bool rounded = true) const;
  98         Duple window_to_canvas (Duple const&) const;
  99
 100         void canvas_to_window (Coord cx, Coord cy, Coord& wx, Coord& wy) {
 101                 Duple d = canvas_to_window (Duple (cx, cy));
 102                 wx = d.x;
 103                 wy = d.y;
 104         }
 105
 106         void window_to_canvas (Coord wx, Coord wy, Coord& cx, Coord& cy) {
 107                 Duple d = window_to_canvas (Duple (wx, wy));
 108                 cx = d.x;
 109                 cy = d.y;
 110         }
 111
 112         void scroll_to (Coord x, Coord y);
 113         void add_scroller (ScrollGroup& i);
 114
 115         virtual Rect  visible_area () const = 0;
 116         virtual Coord width () const = 0;
 117         virtual Coord height () const = 0;
 118
 119         /** Store the coordinates of the mouse pointer in window coordinates in
 120            @param winpos. Return true if the position was within the window,
 121            false otherwise.
 122         */
 123         virtual bool get_mouse_position (Duple& winpos) const = 0;
 124
 125         /** Signal to be used by items that need to track the mouse position
 126            within the window.
 127         */
 128         sigc::signal<void,Duple const&> MouseMotion;
 129
 130         /** Ensures that the position given by @param winpos (in window
 131             coordinates) is within the current window area, possibly reduced by
 132             @param border.
 133         */
 134         Duple clamp_to_window (Duple const& winpos, Duple border = Duple());
 135
 136         void zoomed();
 137
 138         std::string indent() const;
 139         std::string render_indent() const;
 140         void dump (std::ostream&) const;
 141
 142         /** Ask the canvas to pick the current item again, and generate
 143             an enter event for it.
 144         */
 145         virtual void re_enter () = 0;
 146
 147         virtual void start_tooltip_timeout (Item*) {}
 148         virtual void stop_tooltip_timeout () {}
 149
 150         /** Set the timeout used to display tooltips, in milliseconds
 151          */
 152         static void set_tooltip_timeout (uint32_t msecs);
 153
 154 protected:
 155         void queue_draw_item_area (Item *, Rect);
 156
 157         /** our root item */
 158         Root _root;
 159
 160         static uint32_t tooltip_timeout_msecs;
 161
 162         virtual void pick_current_item (int state) = 0;
 163         virtual void pick_current_item (Duple const &, int state) = 0;
 164
 165         std::list<ScrollGroup*> scrollers;
 166 };
 167
 168 /** A canvas which renders onto a GTK EventBox */
 169 class LIBCANVAS_API GtkCanvas : public Canvas, public Gtk::EventBox
 170 {
 171 public:
 172         GtkCanvas ();
 173
 174         void request_redraw (Rect const &);
 175         void request_size (Duple);
 176         void grab (Item *);
 177         void ungrab ();
 178         void focus (Item *);
 179         void unfocus (Item*);
 180
 181         Rect visible_area () const;
 182         Coord width() const;
 183         Coord height() const;
 184
 185         bool get_mouse_position (Duple& winpos) const;
 186
 187         void re_enter ();
 188
 189         void start_tooltip_timeout (Item*);
 190         void stop_tooltip_timeout ();
 191
 192 protected:
 193         void on_size_allocate (Gtk::Allocation&);
 194         bool on_scroll_event (GdkEventScroll *);
 195         bool on_expose_event (GdkEventExpose *);
 196         bool on_button_press_event (GdkEventButton *);
 197         bool on_button_release_event (GdkEventButton* event);
 198         bool on_motion_notify_event (GdkEventMotion *);
 199         bool on_enter_notify_event (GdkEventCrossing*);
 200         bool on_leave_notify_event (GdkEventCrossing*);
 201
 202         bool button_handler (GdkEventButton *);
 203         bool motion_notify_handler (GdkEventMotion *);
 204         bool deliver_event (GdkEvent *);
 205         void deliver_enter_leave (Duple const & point, int state);
 206
 207         void pick_current_item (int state);
 208         void pick_current_item (Duple const &, int state);
 209
 210 private:
 211         void item_going_away (Item *, boost::optional<Rect>);
 212         bool send_leave_event (Item const *, double, double) const;
 213
 214         Cairo::RefPtr<Cairo::Surface> canvas_image;
 215
 216         /** Item currently chosen for event delivery based on pointer position */
 217         Item * _current_item;
 218         /** Item pending as _current_item */
 219         Item * _new_current_item;
 220         /** the item that is currently grabbed, or 0 */
 221         Item * _grabbed_item;
 222         /** the item that currently has key focus or 0 */
 223         Item * _focused_item;
 224
 225         sigc::connection tooltip_timeout_connection;
 226         Item* current_tooltip_item;
 227         Gtk::Window* tooltip_window;
 228         Gtk::Label* tooltip_label;
 229         bool show_tooltip ();
 230         void hide_tooltip ();
 231         bool really_start_tooltip_timeout ();
 232 };
 233
 234 /** A GTK::Alignment with a GtkCanvas inside it plus some Gtk::Adjustments for
 235  *   scrolling.
 236  *
 237  * This provides a GtkCanvas that can be scrolled. It does NOT implement the
 238  * Gtk::Scrollable interface.
 239  */
 240 class LIBCANVAS_API GtkCanvasViewport : public Gtk::Alignment
 241 {
 242 public:
 243         GtkCanvasViewport (Gtk::Adjustment &, Gtk::Adjustment &);
 244
 245         /** @return our GtkCanvas */
 246         GtkCanvas* canvas () {
 247                 return &_canvas;
 248         }
 249
 250 protected:
 251         void on_size_request (Gtk::Requisition *);
 252
 253 private:
 254         /** our GtkCanvas */
 255         GtkCanvas _canvas;
 256         Gtk::Adjustment& hadjustment;
 257         Gtk::Adjustment& vadjustment;
 258
 259         void scrolled ();
 260 };
 261
 262 }
 263
 264 std::ostream& operator<< (std::ostream&, const ArdourCanvas::Canvas&);
 265
 266 #endif