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")
 32     .property("font")
 33     .property("textAngle")
 34     .property("textStyle")
 35     .property("textAlign")
 36     .property("textBaseline")
 37     .property("textMargin")
 38     .property("textShadow");
 39 
 40 pv.Label.prototype.type = "label";
 41 
 42 /**
 43  * The character data to render; a string. The default value of the text
 44  * property is the identity function, meaning the label's associated datum will
 45  * be rendered using its <tt>toString</tt>.
 46  *
 47  * @type string
 48  * @name pv.Label.prototype.text
 49  */
 50 
 51 /**
 52  * The font format, per the CSS Level 2 specification. The default font is "10px
 53  * sans-serif", for consistency with the HTML 5 canvas element specification.
 54  * Note that since text is not wrapped, any line-height property will be
 55  * ignored. The other font-style, font-variant, font-weight, font-size and
 56  * font-family properties are supported.
 57  *
 58  * @see <a href="http://www.w3.org/TR/CSS2/fonts.html#font-shorthand">CSS2 fonts</a>
 59  * @type string
 60  * @name pv.Label.prototype.font
 61  */
 62 
 63 /**
 64  * The rotation angle, in radians. Text is rotated clockwise relative to the
 65  * anchor location. For example, with the default left alignment, an angle of
 66  * Math.PI / 2 causes text to proceed downwards. The default angle is zero.
 67  *
 68  * @type number
 69  * @name pv.Label.prototype.textAngle
 70  */
 71 
 72 /**
 73  * The text color. The name "textStyle" is used for consistency with "fillStyle"
 74  * and "strokeStyle", although it might be better to rename this property (and
 75  * perhaps use the same name as "strokeStyle"). The default color is black.
 76  *
 77  * @type string
 78  * @name pv.Label.prototype.textStyle
 79  * @see pv.color
 80  */
 81 
 82 /**
 83  * The horizontal text alignment. One of:<ul>
 84  *
 85  * <li>left
 86  * <li>center
 87  * <li>right
 88  *
 89  * </ul>The default horizontal alignment is left.
 90  *
 91  * @type string
 92  * @name pv.Label.prototype.textAlign
 93  */
 94 
 95 /**
 96  * The vertical text alignment. One of:<ul>
 97  *
 98  * <li>top
 99  * <li>middle
100  * <li>bottom
101  *
102  * </ul>The default vertical alignment is bottom.
103  *
104  * @type string
105  * @name pv.Label.prototype.textBaseline
106  */
107 
108 /**
109  * The text margin; may be specified in pixels, or in font-dependent units (such
110  * as ".1ex"). The margin can be used to pad text away from its anchor location,
111  * in a direction dependent on the horizontal and vertical alignment
112  * properties. For example, if the text is left- and middle-aligned, the margin
113  * shifts the text to the right. The default margin is 3 pixels.
114  *
115  * @type number
116  * @name pv.Label.prototype.textMargin
117  */
118 
119 /**
120  * A list of shadow effects to be applied to text, per the CSS Text Level 3
121  * text-shadow property. An example specification is "0.1em 0.1em 0.1em
122  * rgba(0,0,0,.5)"; the first length is the horizontal offset, the second the
123  * vertical offset, and the third the blur radius.
124  *
125  * @see <a href="http://www.w3.org/TR/css3-text/#text-shadow">CSS3 text</a>
126  * @type string
127  * @name pv.Label.prototype.textShadow
128  */
129 
130 /**
131  * Default properties for labels. See the individual properties for the default
132  * values.
133  *
134  * @type pv.Label
135  */
136 pv.Label.prototype.defaults = new pv.Label()
137     .extend(pv.Mark.prototype.defaults)
138     .text(pv.identity)
139     .font("10px sans-serif")
140     .textAngle(0)
141     .textStyle("black")
142     .textAlign("left")
143     .textBaseline("bottom")
144     .textMargin(3);
145