1 /**
  2  * Constructs a new rule with default properties. Rules 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 horizontal or vertical rule. Rules are frequently used
  7  * for axes and grid lines. For example, specifying only the bottom property
  8  * draws horizontal rules, while specifying only the left draws vertical
  9  * rules. Rules can also be used as thin bars. The visual style is controlled in
 10  * the same manner as lines.
 11  *
 12  * <p>Rules are positioned exclusively the standard box model properties. The
 13  * following combinations of properties are supported:
 14  *
 15  * <table>
 16  * <thead><th style="width:12em;">Properties</th><th>Orientation</th></thead>
 17  * <tbody>
 18  * <tr><td>left</td><td>vertical</td></tr>
 19  * <tr><td>right</td><td>vertical</td></tr>
 20  * <tr><td>left, bottom, top</td><td>vertical</td></tr>
 21  * <tr><td>right, bottom, top</td><td>vertical</td></tr>
 22  * <tr><td>top</td><td>horizontal</td></tr>
 23  * <tr><td>bottom</td><td>horizontal</td></tr>
 24  * <tr><td>top, left, right</td><td>horizontal</td></tr>
 25  * <tr><td>bottom, left, right</td><td>horizontal</td></tr>
 26  * <tr><td>left, top, height</td><td>vertical</td></tr>
 27  * <tr><td>left, bottom, height</td><td>vertical</td></tr>
 28  * <tr><td>right, top, height</td><td>vertical</td></tr>
 29  * <tr><td>right, bottom, height</td><td>vertical</td></tr>
 30  * <tr><td>left, top, width</td><td>horizontal</td></tr>
 31  * <tr><td>left, bottom, width</td><td>horizontal</td></tr>
 32  * <tr><td>right, top, width</td><td>horizontal</td></tr>
 33  * <tr><td>right, bottom, width</td><td>horizontal</td></tr>
 34  * </tbody>
 35  * </table>
 36  *
 37  * <p>Small rules can be used as tick marks; alternatively, a {@link Dot} with
 38  * the "tick" shape can be used.
 39  *
 40  * <p>See also the <a href="../../api/Rule.html">Rule guide</a>.
 41  *
 42  * @see pv.Line
 43  * @extends pv.Mark
 44  */
 45 pv.Rule = function() {
 46   pv.Mark.call(this);
 47 };
 48 
 49 pv.Rule.prototype = pv.extend(pv.Mark)
 50     .property("width", Number)
 51     .property("height", Number)
 52     .property("lineWidth", Number)
 53     .property("strokeStyle", pv.color);
 54 
 55 pv.Rule.prototype.type = "rule";
 56 
 57 /**
 58  * The width of the rule, in pixels. If the left position is specified, the rule
 59  * extends rightward from the left edge; if the right position is specified, the
 60  * rule extends leftward from the right edge.
 61  *
 62  * @type number
 63  * @name pv.Rule.prototype.width
 64  */
 65 
 66 /**
 67  * The height of the rule, in pixels. If the bottom position is specified, the
 68  * rule extends upward from the bottom edge; if the top position is specified,
 69  * the rule extends downward from the top edge.
 70  *
 71  * @type number
 72  * @name pv.Rule.prototype.height
 73  */
 74 
 75 /**
 76  * The width of stroked lines, in pixels; used in conjunction with
 77  * <tt>strokeStyle</tt> to stroke the rule. The default value is 1 pixel.
 78  *
 79  * @type number
 80  * @name pv.Rule.prototype.lineWidth
 81  */
 82 
 83 /**
 84  * The style of stroked lines; used in conjunction with <tt>lineWidth</tt> to
 85  * stroke the rule. The default value of this property is black.
 86  *
 87  * @type string
 88  * @name pv.Rule.prototype.strokeStyle
 89  * @see pv.color
 90  */
 91 
 92 /**
 93  * Default properties for rules. By default, a single-pixel black line is
 94  * stroked.
 95  *
 96  * @type pv.Rule
 97  */
 98 pv.Rule.prototype.defaults = new pv.Rule()
 99     .extend(pv.Mark.prototype.defaults)
100     .lineWidth(1)
101     .strokeStyle("black")
102     .antialias(false);
103 
104 /**
105  * Constructs a new rule anchor with default properties. Rules support five
106  * different anchors:<ul>
107  *
108  * <li>top
109  * <li>left
110  * <li>center
111  * <li>bottom
112  * <li>right
113  *
114  * </ul>In addition to positioning properties (left, right, top bottom), the
115  * anchors support text rendering properties (text-align, text-baseline). Text is
116  * rendered to appear outside the rule. Note that this behavior is different
117  * from other mark anchors, which default to rendering text <i>inside</i> the
118  * mark.
119  *
120  * <p>For consistency with the other mark types, the anchor positions are
121  * defined in terms of their opposite edge. For example, the top anchor defines
122  * the bottom property, such that a bar added to the top anchor grows upward.
123  *
124  * @param {string} name the anchor name; either a string or a property function.
125  * @returns {pv.Anchor}
126  */
127 pv.Rule.prototype.anchor = pv.Line.prototype.anchor;
128 
129 /** @private Sets width or height based on orientation. */
130 pv.Rule.prototype.buildImplied = function(s) {
131   var l = s.left, r = s.right, t = s.top, b = s.bottom;
132 
133   /* Determine horizontal or vertical orientation. */
134   if ((s.width != null)
135       || ((l == null) && (r == null))
136       || ((r != null) && (l != null))) {
137     s.height = 0;
138   } else {
139     s.width = 0;
140   }
141 
142   pv.Mark.prototype.buildImplied.call(this, s);
143 };
144