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