1 /** 2 * Constructs a new label mark with default properties. Labels are not typically 3 * constructed directly, but by adding to a panel or an existing mark via 4 * {@link pv.Mark#add}. 5 * 6 * @class Represents a text label, allowing textual annotation of other marks or 7 * arbitrary text within the visualization. The character data must be plain 8 * text (unicode), though the text can be styled using the {@link #font} 9 * property. If rich text is needed, external HTML elements can be overlaid on 10 * the canvas by hand. 11 * 12 * <p>Labels are positioned using the box model, similarly to {@link Dot}. Thus, 13 * a label has no width or height, but merely a text anchor location. The text 14 * is positioned relative to this anchor location based on the 15 * {@link #textAlign}, {@link #textBaseline} and {@link #textMargin} properties. 16 * Furthermore, the text may be rotated using {@link #textAngle}. 17 * 18 * <p>Labels ignore events, so as to not interfere with event handlers on 19 * underlying marks, such as bars. In the future, we may support event handlers 20 * on labels. 21 * 22 * <p>See also the <a href="../../api/Label.html">Label guide</a>. 23 * 24 * @extends pv.Mark 25 */ 26 pv.Label = function() { 27 pv.Mark.call(this); 28 }; 29 30 pv.Label.prototype = pv.extend(pv.Mark) 31 .property("text", String) 32 .property("font", String) 33 .property("textAngle", Number) 34 .property("textStyle", pv.color) 35 .property("textAlign", String) 36 .property("textBaseline", String) 37 .property("textMargin", Number) 38 .property("textDecoration", String) 39 .property("textShadow", String); 40 41 pv.Label.prototype.type = "label"; 42 43 /** 44 * The character data to render; a string. The default value of the text 45 * property is the identity function, meaning the label's associated datum will 46 * be rendered using its <tt>toString</tt>. 47 * 48 * @type string 49 * @name pv.Label.prototype.text 50 */ 51 52 /** 53 * The font format, per the CSS Level 2 specification. The default font is "10px 54 * sans-serif", for consistency with the HTML 5 canvas element specification. 55 * Note that since text is not wrapped, any line-height property will be 56 * ignored. The other font-style, font-variant, font-weight, font-size and 57 * font-family properties are supported. 58 * 59 * @see <a href="http://www.w3.org/TR/CSS2/fonts.html#font-shorthand">CSS2 fonts</a> 60 * @type string 61 * @name pv.Label.prototype.font 62 */ 63 64 /** 65 * The rotation angle, in radians. Text is rotated clockwise relative to the 66 * anchor location. For example, with the default left alignment, an angle of 67 * Math.PI / 2 causes text to proceed downwards. The default angle is zero. 68 * 69 * @type number 70 * @name pv.Label.prototype.textAngle 71 */ 72 73 /** 74 * The text color. The name "textStyle" is used for consistency with "fillStyle" 75 * and "strokeStyle", although it might be better to rename this property (and 76 * perhaps use the same name as "strokeStyle"). The default color is black. 77 * 78 * @type string 79 * @name pv.Label.prototype.textStyle 80 * @see pv.color 81 */ 82 83 /** 84 * The horizontal text alignment. One of:<ul> 85 * 86 * <li>left 87 * <li>center 88 * <li>right 89 * 90 * </ul>The default horizontal alignment is left. 91 * 92 * @type string 93 * @name pv.Label.prototype.textAlign 94 */ 95 96 /** 97 * The vertical text alignment. One of:<ul> 98 * 99 * <li>top 100 * <li>middle 101 * <li>bottom 102 * 103 * </ul>The default vertical alignment is bottom. 104 * 105 * @type string 106 * @name pv.Label.prototype.textBaseline 107 */ 108 109 /** 110 * The text margin; may be specified in pixels, or in font-dependent units (such 111 * as ".1ex"). The margin can be used to pad text away from its anchor location, 112 * in a direction dependent on the horizontal and vertical alignment 113 * properties. For example, if the text is left- and middle-aligned, the margin 114 * shifts the text to the right. The default margin is 3 pixels. 115 * 116 * @type number 117 * @name pv.Label.prototype.textMargin 118 */ 119 120 /** 121 * A list of shadow effects to be applied to text, per the CSS Text Level 3 122 * text-shadow property. An example specification is "0.1em 0.1em 0.1em 123 * rgba(0,0,0,.5)"; the first length is the horizontal offset, the second the 124 * vertical offset, and the third the blur radius. 125 * 126 * @see <a href="http://www.w3.org/TR/css3-text/#text-shadow">CSS3 text</a> 127 * @type string 128 * @name pv.Label.prototype.textShadow 129 */ 130 131 /** 132 * A list of decoration to be applied to text, per the CSS Text Level 3 133 * text-decoration property. An example specification is "underline". 134 * 135 * @see <a href="http://www.w3.org/TR/css3-text/#text-decoration">CSS3 text</a> 136 * @type string 137 * @name pv.Label.prototype.textDecoration 138 */ 139 140 /** 141 * Default properties for labels. See the individual properties for the default 142 * values. 143 * 144 * @type pv.Label 145 */ 146 pv.Label.prototype.defaults = new pv.Label() 147 .extend(pv.Mark.prototype.defaults) 148 .events("none") 149 .text(pv.identity) 150 .font("10px sans-serif") 151 .textAngle(0) 152 .textStyle("black") 153 .textAlign("left") 154 .textBaseline("bottom") 155 .textMargin(3); 156