tooltip.js 8.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  1. /**
  2. * @license
  3. * Visual Blocks Editor
  4. *
  5. * Copyright 2011 Google Inc.
  6. * https://developers.google.com/blockly/
  7. *
  8. * Licensed under the Apache License, Version 2.0 (the "License");
  9. * you may not use this file except in compliance with the License.
  10. * You may obtain a copy of the License at
  11. *
  12. * http://www.apache.org/licenses/LICENSE-2.0
  13. *
  14. * Unless required by applicable law or agreed to in writing, software
  15. * distributed under the License is distributed on an "AS IS" BASIS,
  16. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17. * See the License for the specific language governing permissions and
  18. * limitations under the License.
  19. */
  20. /**
  21. * @fileoverview Library to create tooltips for Blockly.
  22. * First, call Blockly.Tooltip.init() after onload.
  23. * Second, set the 'tooltip' property on any SVG element that needs a tooltip.
  24. * If the tooltip is a string, then that message will be displayed.
  25. * If the tooltip is an SVG element, then that object's tooltip will be used.
  26. * Third, call Blockly.Tooltip.bindMouseEvents(e) passing the SVG element.
  27. * @author fraser@google.com (Neil Fraser)
  28. */
  29. 'use strict';
  30. goog.provide('Blockly.Tooltip');
  31. goog.require('goog.dom');
  32. goog.require('goog.dom.TagName');
  33. /**
  34. * Is a tooltip currently showing?
  35. */
  36. Blockly.Tooltip.visible = false;
  37. /**
  38. * Maximum width (in characters) of a tooltip.
  39. */
  40. Blockly.Tooltip.LIMIT = 50;
  41. /**
  42. * PID of suspended thread to clear tooltip on mouse out.
  43. * @private
  44. */
  45. Blockly.Tooltip.mouseOutPid_ = 0;
  46. /**
  47. * PID of suspended thread to show the tooltip.
  48. * @private
  49. */
  50. Blockly.Tooltip.showPid_ = 0;
  51. /**
  52. * Last observed X location of the mouse pointer (freezes when tooltip appears).
  53. * @private
  54. */
  55. Blockly.Tooltip.lastX_ = 0;
  56. /**
  57. * Last observed Y location of the mouse pointer (freezes when tooltip appears).
  58. * @private
  59. */
  60. Blockly.Tooltip.lastY_ = 0;
  61. /**
  62. * Current element being pointed at.
  63. * @private
  64. */
  65. Blockly.Tooltip.element_ = null;
  66. /**
  67. * Once a tooltip has opened for an element, that element is 'poisoned' and
  68. * cannot respawn a tooltip until the pointer moves over a different element.
  69. * @private
  70. */
  71. Blockly.Tooltip.poisonedElement_ = null;
  72. /**
  73. * Horizontal offset between mouse cursor and tooltip.
  74. */
  75. Blockly.Tooltip.OFFSET_X = 0;
  76. /**
  77. * Vertical offset between mouse cursor and tooltip.
  78. */
  79. Blockly.Tooltip.OFFSET_Y = 10;
  80. /**
  81. * Radius mouse can move before killing tooltip.
  82. */
  83. Blockly.Tooltip.RADIUS_OK = 10;
  84. /**
  85. * Delay before tooltip appears.
  86. */
  87. Blockly.Tooltip.HOVER_MS = 750;
  88. /**
  89. * Horizontal padding between tooltip and screen edge.
  90. */
  91. Blockly.Tooltip.MARGINS = 5;
  92. /**
  93. * The HTML container. Set once by Blockly.Tooltip.createDom.
  94. * @type {Element}
  95. */
  96. Blockly.Tooltip.DIV = null;
  97. /**
  98. * Create the tooltip div and inject it onto the page.
  99. */
  100. Blockly.Tooltip.createDom = function() {
  101. if (Blockly.Tooltip.DIV) {
  102. return; // Already created.
  103. }
  104. // Create an HTML container for popup overlays (e.g. editor widgets).
  105. Blockly.Tooltip.DIV =
  106. goog.dom.createDom(goog.dom.TagName.DIV, 'blocklyTooltipDiv');
  107. document.body.appendChild(Blockly.Tooltip.DIV);
  108. };
  109. /**
  110. * Binds the required mouse events onto an SVG element.
  111. * @param {!Element} element SVG element onto which tooltip is to be bound.
  112. */
  113. Blockly.Tooltip.bindMouseEvents = function(element) {
  114. Blockly.bindEvent_(element, 'mouseover', null,
  115. Blockly.Tooltip.onMouseOver_);
  116. Blockly.bindEvent_(element, 'mouseout', null,
  117. Blockly.Tooltip.onMouseOut_);
  118. // Don't use bindEvent_ for mousemove since that would create a
  119. // corresponding touch handler, even though this only makes sense in the
  120. // context of a mouseover/mouseout.
  121. element.addEventListener('mousemove', Blockly.Tooltip.onMouseMove_, false);
  122. };
  123. /**
  124. * Hide the tooltip if the mouse is over a different object.
  125. * Initialize the tooltip to potentially appear for this object.
  126. * @param {!Event} e Mouse event.
  127. * @private
  128. */
  129. Blockly.Tooltip.onMouseOver_ = function(e) {
  130. // If the tooltip is an object, treat it as a pointer to the next object in
  131. // the chain to look at. Terminate when a string or function is found.
  132. var element = e.target;
  133. while (!goog.isString(element.tooltip) && !goog.isFunction(element.tooltip)) {
  134. element = element.tooltip;
  135. }
  136. if (Blockly.Tooltip.element_ != element) {
  137. Blockly.Tooltip.hide();
  138. Blockly.Tooltip.poisonedElement_ = null;
  139. Blockly.Tooltip.element_ = element;
  140. }
  141. // Forget about any immediately preceeding mouseOut event.
  142. clearTimeout(Blockly.Tooltip.mouseOutPid_);
  143. };
  144. /**
  145. * Hide the tooltip if the mouse leaves the object and enters the workspace.
  146. * @param {!Event} e Mouse event.
  147. * @private
  148. */
  149. Blockly.Tooltip.onMouseOut_ = function(e) {
  150. // Moving from one element to another (overlapping or with no gap) generates
  151. // a mouseOut followed instantly by a mouseOver. Fork off the mouseOut
  152. // event and kill it if a mouseOver is received immediately.
  153. // This way the task only fully executes if mousing into the void.
  154. Blockly.Tooltip.mouseOutPid_ = setTimeout(function() {
  155. Blockly.Tooltip.element_ = null;
  156. Blockly.Tooltip.poisonedElement_ = null;
  157. Blockly.Tooltip.hide();
  158. }, 1);
  159. clearTimeout(Blockly.Tooltip.showPid_);
  160. };
  161. /**
  162. * When hovering over an element, schedule a tooltip to be shown. If a tooltip
  163. * is already visible, hide it if the mouse strays out of a certain radius.
  164. * @param {!Event} e Mouse event.
  165. * @private
  166. */
  167. Blockly.Tooltip.onMouseMove_ = function(e) {
  168. if (!Blockly.Tooltip.element_ || !Blockly.Tooltip.element_.tooltip) {
  169. // No tooltip here to show.
  170. return;
  171. } else if (Blockly.dragMode_ != Blockly.DRAG_NONE) {
  172. // Don't display a tooltip during a drag.
  173. return;
  174. } else if (Blockly.WidgetDiv.isVisible()) {
  175. // Don't display a tooltip if a widget is open (tooltip would be under it).
  176. return;
  177. }
  178. if (Blockly.Tooltip.visible) {
  179. // Compute the distance between the mouse position when the tooltip was
  180. // shown and the current mouse position. Pythagorean theorem.
  181. var dx = Blockly.Tooltip.lastX_ - e.pageX;
  182. var dy = Blockly.Tooltip.lastY_ - e.pageY;
  183. if (Math.sqrt(dx * dx + dy * dy) > Blockly.Tooltip.RADIUS_OK) {
  184. Blockly.Tooltip.hide();
  185. }
  186. } else if (Blockly.Tooltip.poisonedElement_ != Blockly.Tooltip.element_) {
  187. // The mouse moved, clear any previously scheduled tooltip.
  188. clearTimeout(Blockly.Tooltip.showPid_);
  189. // Maybe this time the mouse will stay put. Schedule showing of tooltip.
  190. Blockly.Tooltip.lastX_ = e.pageX;
  191. Blockly.Tooltip.lastY_ = e.pageY;
  192. Blockly.Tooltip.showPid_ =
  193. setTimeout(Blockly.Tooltip.show_, Blockly.Tooltip.HOVER_MS);
  194. }
  195. };
  196. /**
  197. * Hide the tooltip.
  198. */
  199. Blockly.Tooltip.hide = function() {
  200. if (Blockly.Tooltip.visible) {
  201. Blockly.Tooltip.visible = false;
  202. if (Blockly.Tooltip.DIV) {
  203. Blockly.Tooltip.DIV.style.display = 'none';
  204. }
  205. }
  206. clearTimeout(Blockly.Tooltip.showPid_);
  207. };
  208. /**
  209. * Create the tooltip and show it.
  210. * @private
  211. */
  212. Blockly.Tooltip.show_ = function() {
  213. Blockly.Tooltip.poisonedElement_ = Blockly.Tooltip.element_;
  214. if (!Blockly.Tooltip.DIV) {
  215. return;
  216. }
  217. // Erase all existing text.
  218. goog.dom.removeChildren(/** @type {!Element} */ (Blockly.Tooltip.DIV));
  219. // Get the new text.
  220. var tip = Blockly.Tooltip.element_.tooltip;
  221. while (goog.isFunction(tip)) {
  222. tip = tip();
  223. }
  224. tip = Blockly.utils.wrap(tip, Blockly.Tooltip.LIMIT);
  225. // Create new text, line by line.
  226. var lines = tip.split('\n');
  227. for (var i = 0; i < lines.length; i++) {
  228. var div = document.createElement('div');
  229. div.appendChild(document.createTextNode(lines[i]));
  230. Blockly.Tooltip.DIV.appendChild(div);
  231. }
  232. var rtl = Blockly.Tooltip.element_.RTL;
  233. var windowSize = goog.dom.getViewportSize();
  234. // Display the tooltip.
  235. Blockly.Tooltip.DIV.style.direction = rtl ? 'rtl' : 'ltr';
  236. Blockly.Tooltip.DIV.style.display = 'block';
  237. Blockly.Tooltip.visible = true;
  238. // Move the tooltip to just below the cursor.
  239. var anchorX = Blockly.Tooltip.lastX_;
  240. if (rtl) {
  241. anchorX -= Blockly.Tooltip.OFFSET_X + Blockly.Tooltip.DIV.offsetWidth;
  242. } else {
  243. anchorX += Blockly.Tooltip.OFFSET_X;
  244. }
  245. var anchorY = Blockly.Tooltip.lastY_ + Blockly.Tooltip.OFFSET_Y;
  246. if (anchorY + Blockly.Tooltip.DIV.offsetHeight >
  247. windowSize.height + window.scrollY) {
  248. // Falling off the bottom of the screen; shift the tooltip up.
  249. anchorY -= Blockly.Tooltip.DIV.offsetHeight + 2 * Blockly.Tooltip.OFFSET_Y;
  250. }
  251. if (rtl) {
  252. // Prevent falling off left edge in RTL mode.
  253. anchorX = Math.max(Blockly.Tooltip.MARGINS - window.scrollX, anchorX);
  254. } else {
  255. if (anchorX + Blockly.Tooltip.DIV.offsetWidth >
  256. windowSize.width + window.scrollX - 2 * Blockly.Tooltip.MARGINS) {
  257. // Falling off the right edge of the screen;
  258. // clamp the tooltip on the edge.
  259. anchorX = windowSize.width - Blockly.Tooltip.DIV.offsetWidth -
  260. 2 * Blockly.Tooltip.MARGINS;
  261. }
  262. }
  263. Blockly.Tooltip.DIV.style.top = anchorY + 'px';
  264. Blockly.Tooltip.DIV.style.left = anchorX + 'px';
  265. };