pv.Layout.treemap.html 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  4. <head>
  5. <meta http-equiv="content-type" content="text/html; charset=utf-8" />
  6. <meta name="generator" content="JsDoc Toolkit" />
  7. <title>JsDoc Reference - pv.Layout.treemap</title>
  8. <style type="text/css">
  9. /* default.css */
  10. body
  11. {
  12. font: 12px "Lucida Grande", Tahoma, Arial, Helvetica, sans-serif;
  13. width: 800px;
  14. }
  15. .header
  16. {
  17. clear: both;
  18. background-color: #ccc;
  19. padding: 8px;
  20. }
  21. h1
  22. {
  23. font-size: 150%;
  24. font-weight: bold;
  25. padding: 0;
  26. margin: 1em 0 0 .3em;
  27. }
  28. hr
  29. {
  30. border: none 0;
  31. border-top: 1px solid #7F8FB1;
  32. height: 1px;
  33. }
  34. pre.code
  35. {
  36. display: block;
  37. padding: 8px;
  38. border: 1px dashed #ccc;
  39. }
  40. #index
  41. {
  42. margin-top: 24px;
  43. float: left;
  44. width: 160px;
  45. position: absolute;
  46. left: 8px;
  47. background-color: #F3F3F3;
  48. padding: 8px;
  49. }
  50. #content
  51. {
  52. margin-left: 190px;
  53. width: 600px;
  54. }
  55. .classList
  56. {
  57. list-style-type: none;
  58. padding: 0;
  59. margin: 0 0 0 8px;
  60. font-family: arial, sans-serif;
  61. font-size: 1em;
  62. overflow: auto;
  63. }
  64. .classList li
  65. {
  66. padding: 0;
  67. margin: 0 0 8px 0;
  68. }
  69. .summaryTable { width: 100%; }
  70. h1.classTitle
  71. {
  72. font-size:170%;
  73. line-height:130%;
  74. }
  75. h2 { font-size: 110%; }
  76. caption, div.sectionTitle
  77. {
  78. background-color: #7F8FB1;
  79. color: #fff;
  80. font-size:130%;
  81. text-align: left;
  82. padding: 2px 6px 2px 6px;
  83. border: 1px #7F8FB1 solid;
  84. }
  85. div.sectionTitle { margin-bottom: 8px; }
  86. .summaryTable thead { display: none; }
  87. .summaryTable td
  88. {
  89. vertical-align: top;
  90. padding: 4px;
  91. border-bottom: 1px #7F8FB1 solid;
  92. border-right: 1px #7F8FB1 solid;
  93. }
  94. /*col#summaryAttributes {}*/
  95. .summaryTable td.attributes
  96. {
  97. border-left: 1px #7F8FB1 solid;
  98. width: 140px;
  99. text-align: right;
  100. }
  101. td.attributes, .fixedFont
  102. {
  103. line-height: 15px;
  104. color: #002EBE;
  105. font-family: "Courier New",Courier,monospace;
  106. font-size: 13px;
  107. }
  108. .summaryTable td.nameDescription
  109. {
  110. text-align: left;
  111. font-size: 13px;
  112. line-height: 15px;
  113. }
  114. .summaryTable td.nameDescription, .description
  115. {
  116. line-height: 15px;
  117. padding: 4px;
  118. padding-left: 4px;
  119. }
  120. pre
  121. {
  122. border-left: solid 10px #ddd;
  123. padding-left: 1.5em;
  124. }
  125. .summaryTable { margin-bottom: 8px; }
  126. ul.inheritsList
  127. {
  128. list-style: square;
  129. margin-left: 20px;
  130. padding-left: 0;
  131. }
  132. .detailList {
  133. margin-left: 20px;
  134. line-height: 15px;
  135. }
  136. .detailList dt { margin-left: 20px; }
  137. .detailList .heading
  138. {
  139. font-weight: bold;
  140. padding-bottom: 6px;
  141. margin-left: 0;
  142. }
  143. .light, td.attributes, .light a:link, .light a:visited
  144. {
  145. color: #777;
  146. font-style: italic;
  147. }
  148. .fineprint
  149. {
  150. text-align: right;
  151. font-size: 10px;
  152. }
  153. </style>
  154. </head>
  155. <body>
  156. <!-- ============================== header ================================= -->
  157. <!-- begin static/header.html -->
  158. <div id="header">
  159. </div>
  160. <!-- end static/header.html -->
  161. <!-- ============================== classes index ============================ -->
  162. <div id="index">
  163. <!-- begin publish.classesIndex -->
  164. <div align="center"><a href="../index.html">Class Index</a>
  165. | <a href="../files.html">File Index</a></div>
  166. <hr />
  167. <h2>Classes</h2>
  168. <ul class="classList">
  169. <li><i><a href="../symbols/_global_.html">_global_</a></i></li>
  170. <li><a href="../symbols/Array.html">Array</a></li>
  171. <li><a href="../symbols/Date.html">Date</a></li>
  172. <li><a href="../symbols/pv.html">pv</a></li>
  173. <li><a href="../symbols/pv.Anchor.html">pv.Anchor</a></li>
  174. <li><a href="../symbols/pv.Area.html">pv.Area</a></li>
  175. <li><a href="../symbols/pv.Bar.html">pv.Bar</a></li>
  176. <li><a href="../symbols/pv.Color.html">pv.Color</a></li>
  177. <li><a href="../symbols/pv.Color.Hsl.html">pv.Color.Hsl</a></li>
  178. <li><a href="../symbols/pv.Color.Rgb.html">pv.Color.Rgb</a></li>
  179. <li><a href="../symbols/pv.Colors.html">pv.Colors</a></li>
  180. <li><a href="../symbols/pv.Dot.html">pv.Dot</a></li>
  181. <li><a href="../symbols/pv.Flatten.html">pv.Flatten</a></li>
  182. <li><a href="../symbols/pv.Image.html">pv.Image</a></li>
  183. <li><a href="../symbols/pv.Label.html">pv.Label</a></li>
  184. <li><a href="../symbols/pv.Layout.grid.html">pv.Layout.grid</a></li>
  185. <li><a href="../symbols/pv.Layout.icicle.html">pv.Layout.icicle</a></li>
  186. <li><a href="../symbols/pv.Layout.stack.html">pv.Layout.stack</a></li>
  187. <li><a href="../symbols/pv.Layout.sunburst.html">pv.Layout.sunburst</a></li>
  188. <li><a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a></li>
  189. <li><a href="../symbols/pv.Line.html">pv.Line</a></li>
  190. <li><a href="../symbols/pv.Mark.html">pv.Mark</a></li>
  191. <li><a href="../symbols/pv.Nest.html">pv.Nest</a></li>
  192. <li><a href="../symbols/pv.ns.html">pv.ns</a></li>
  193. <li><a href="../symbols/pv.Panel.html">pv.Panel</a></li>
  194. <li><a href="../symbols/pv.Rule.html">pv.Rule</a></li>
  195. <li><a href="../symbols/pv.Scale.linear.html">pv.Scale.linear</a></li>
  196. <li><a href="../symbols/pv.Scale.log.html">pv.Scale.log</a></li>
  197. <li><a href="../symbols/pv.Scale.ordinal.html">pv.Scale.ordinal</a></li>
  198. <li><a href="../symbols/pv.Tree.html">pv.Tree</a></li>
  199. <li><a href="../symbols/pv.Vector.html">pv.Vector</a></li>
  200. <li><a href="../symbols/pv.version.html">pv.version</a></li>
  201. <li><a href="../symbols/pv.Wedge.html">pv.Wedge</a></li>
  202. </ul>
  203. <hr />
  204. <!-- end publish.classesIndex -->
  205. </div>
  206. <div id="content">
  207. <!-- ============================== class title ============================ -->
  208. <h1 class="classTitle">
  209. Class pv.Layout.treemap
  210. </h1>
  211. <!-- ============================== class summary ========================== -->
  212. <p class="description">
  213. A tree layout in the form of an treemap. <img
  214. src="../treemap.png" width="160" height="160" align="right"> Treemaps
  215. are a form of space-filling layout that represents nodes as boxes, with child
  216. nodes placed within parent boxes. The size of each box is proportional to the
  217. size of the node in the tree.
  218. <p>This particular algorithm is taken from Bruls, D.M., C. Huizing, and
  219. J.J. van Wijk, <a href="http://www.win.tue.nl/~vanwijk/stm.pdf">"Squarified
  220. Treemaps"</a> in <i>Data Visualization 2000, Proceedings of the Joint
  221. Eurographics and IEEE TCVG Sumposium on Visualization</i>, 2000,
  222. pp. 33-42.
  223. <p>This tree layout is intended to be extended (see <a href="../symbols/pv.Mark.html#extend">pv.Mark#extend</a>)
  224. by a <a href="../symbols/pv.Bar.html">pv.Bar</a>. The data property returns an array of nodes for use by
  225. other property functions. The following node attributes are supported:
  226. <ul>
  227. <li><tt>left</tt> - the cell left position.
  228. <li><tt>top</tt> - the cell top position.
  229. <li><tt>width</tt> - the cell width.
  230. <li><tt>height</tt> - the cell height.
  231. <li><tt>depth</tt> - the node depth (tier; the root is 0).
  232. <li><tt>keys</tt> - an array of string keys for the node.
  233. <li><tt>size</tt> - the aggregate node size.
  234. <li><tt>children</tt> - child nodes, if any.
  235. <li><tt>data</tt> - the associated tree element, for leaf nodes.
  236. </ul>
  237. To produce a default treemap layout, say:
  238. <pre>.add(pv.Bar)
  239. .extend(pv.Layout.treemap(tree))</pre>
  240. To display internal nodes, and color by depth, say:
  241. <pre>.add(pv.Bar)
  242. .extend(pv.Layout.treemap(tree).inset(10))
  243. .fillStyle(pv.Colors.category19().by(function(n) n.depth))</pre>
  244. The format of the <tt>tree</tt> argument is a hierarchical object whose leaf
  245. nodes are numbers corresponding to their size. For an example, and
  246. information on how to convert tabular data into such a tree, see
  247. <a href="../symbols/pv.Tree.html">pv.Tree</a>. If the leaf nodes are not numbers, a <a href="#size">#size</a> function
  248. can be specified to override how the tree is interpreted. This size function
  249. can also be used to transform the data.
  250. <p>By default, the treemap fills the full width and height of the parent
  251. panel, and only leaf nodes are rendered. If an <a href="#inset">#inset</a> is specified,
  252. internal nodes will be rendered, each inset from their parent by the
  253. specified margins. Rounding can be enabled using <a href="#round">#round</a>. Finally, an
  254. optional root key can be specified using <a href="#root">#root</a> for convenience.
  255. <br /><i>Defined in: </i> <a href="../symbols/src/layout_Treemap.js.html">Treemap.js</a>.
  256. </p>
  257. <!-- ============================== constructor summary ==================== -->
  258. <table class="summaryTable" cellspacing="0" summary="A summary of the constructor documented in the class pv.Layout.treemap.">
  259. <caption>Class Summary</caption>
  260. <thead>
  261. <tr>
  262. <th scope="col">Constructor Attributes</th>
  263. <th scope="col">Constructor Name and Description</th>
  264. </tr>
  265. </thead>
  266. <tbody>
  267. <tr>
  268. <td class="attributes">&nbsp;</td>
  269. <td class="nameDescription" >
  270. <div class="fixedFont">
  271. <b><a href="../symbols/pv.Layout.treemap.html#constructor">pv.Layout.treemap</a></b>(tree)
  272. </div>
  273. <div class="description">Returns a new treemap tree layout.</div>
  274. </td>
  275. </tr>
  276. </tbody>
  277. </table>
  278. <!-- ============================== properties summary ===================== -->
  279. <!-- ============================== methods summary ======================== -->
  280. <table class="summaryTable" cellspacing="0" summary="A summary of the methods documented in the class pv.Layout.treemap.">
  281. <caption>Method Summary</caption>
  282. <thead>
  283. <tr>
  284. <th scope="col">Method Attributes</th>
  285. <th scope="col">Method Name and Description</th>
  286. </tr>
  287. </thead>
  288. <tbody>
  289. <tr>
  290. <td class="attributes">&nbsp;</td>
  291. <td class="nameDescription">
  292. <div class="fixedFont"><b><a href="../symbols/pv.Layout.treemap.html#inset">inset</a></b>(top, right, bottom, left)
  293. </div>
  294. <div class="description">Specifies the margins to inset child nodes from their parents; as a side
  295. effect, this also enables the display of internal nodes, which are hidden
  296. by default.</div>
  297. </td>
  298. </tr>
  299. <tr>
  300. <td class="attributes">&nbsp;</td>
  301. <td class="nameDescription">
  302. <div class="fixedFont"><b><a href="../symbols/pv.Layout.treemap.html#root">root</a></b>(v)
  303. </div>
  304. <div class="description">Specifies the root key; optional.</div>
  305. </td>
  306. </tr>
  307. <tr>
  308. <td class="attributes">&nbsp;</td>
  309. <td class="nameDescription">
  310. <div class="fixedFont"><b><a href="../symbols/pv.Layout.treemap.html#round">round</a></b>(v)
  311. </div>
  312. <div class="description">Enables or disables rounding.</div>
  313. </td>
  314. </tr>
  315. <tr>
  316. <td class="attributes">&nbsp;</td>
  317. <td class="nameDescription">
  318. <div class="fixedFont"><b><a href="../symbols/pv.Layout.treemap.html#size">size</a></b>(f)
  319. </div>
  320. <div class="description">Specifies the sizing function.</div>
  321. </td>
  322. </tr>
  323. </tbody>
  324. </table>
  325. <!-- ============================== events summary ======================== -->
  326. <!-- ============================== constructor details ==================== -->
  327. <div class="details"><a name="constructor"> </a>
  328. <div class="sectionTitle">
  329. Class Detail
  330. </div>
  331. <div class="fixedFont">
  332. <b>pv.Layout.treemap</b>(tree)
  333. </div>
  334. <div class="description">
  335. Returns a new treemap tree layout.
  336. </div>
  337. <dl class="detailList">
  338. <dt class="heading">Parameters:</dt>
  339. <dt>
  340. <b>tree</b>
  341. </dt>
  342. <dd>a tree (an object) who leaf attributes have sizes.</dd>
  343. </dl>
  344. <dl class="detailList">
  345. <dt class="heading">Returns:</dt>
  346. <dd><span class="light fixedFont">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span> a tree layout.</dd>
  347. </dl>
  348. </div>
  349. <!-- ============================== field details ========================== -->
  350. <!-- ============================== method details ========================= -->
  351. <div class="sectionTitle">
  352. Method Detail
  353. </div>
  354. <a name="inset"> </a>
  355. <div class="fixedFont">
  356. <span class="light">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span>
  357. <b>inset</b>(top, right, bottom, left)
  358. </div>
  359. <div class="description">
  360. Specifies the margins to inset child nodes from their parents; as a side
  361. effect, this also enables the display of internal nodes, which are hidden
  362. by default. If only a single argument is specified, this value is used to
  363. inset all four sides.
  364. </div>
  365. <dl class="detailList">
  366. <dt class="heading">Parameters:</dt>
  367. <dt>
  368. <span class="light fixedFont">{number}</span> <b>top</b>
  369. </dt>
  370. <dd>the top margin.</dd>
  371. <dt>
  372. <span class="light fixedFont">{number}</span> <b>right</b>
  373. <i>Optional</i>
  374. </dt>
  375. <dd>the right margin.</dd>
  376. <dt>
  377. <span class="light fixedFont">{number}</span> <b>bottom</b>
  378. <i>Optional</i>
  379. </dt>
  380. <dd>the bottom margin.</dd>
  381. <dt>
  382. <span class="light fixedFont">{number}</span> <b>left</b>
  383. <i>Optional</i>
  384. </dt>
  385. <dd>the left margin.</dd>
  386. </dl>
  387. <dl class="detailList">
  388. <dt class="heading">Returns:</dt>
  389. <dd><span class="light fixedFont">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span> this.</dd>
  390. </dl>
  391. <hr />
  392. <a name="root"> </a>
  393. <div class="fixedFont">
  394. <span class="light">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span>
  395. <b>root</b>(v)
  396. </div>
  397. <div class="description">
  398. Specifies the root key; optional. The root key is prepended to the
  399. <tt>keys</tt> attribute for all generated nodes. This method is provided
  400. for convenience and does not affect layout.
  401. </div>
  402. <dl class="detailList">
  403. <dt class="heading">Parameters:</dt>
  404. <dt>
  405. <span class="light fixedFont">{string}</span> <b>v</b>
  406. </dt>
  407. <dd>the root key.</dd>
  408. </dl>
  409. <dl class="detailList">
  410. <dt class="heading">Returns:</dt>
  411. <dd><span class="light fixedFont">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span> this.</dd>
  412. </dl>
  413. <hr />
  414. <a name="round"> </a>
  415. <div class="fixedFont">
  416. <span class="light">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span>
  417. <b>round</b>(v)
  418. </div>
  419. <div class="description">
  420. Enables or disables rounding. When rounding is enabled, the left, top,
  421. width and height properties will be rounded to integer pixel values. The
  422. rounding algorithm uses error accumulation to ensure an exact fit.
  423. </div>
  424. <dl class="detailList">
  425. <dt class="heading">Parameters:</dt>
  426. <dt>
  427. <span class="light fixedFont">{boolean}</span> <b>v</b>
  428. </dt>
  429. <dd>whether rounding should be enabled.</dd>
  430. </dl>
  431. <dl class="detailList">
  432. <dt class="heading">Returns:</dt>
  433. <dd><span class="light fixedFont">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span> this.</dd>
  434. </dl>
  435. <hr />
  436. <a name="size"> </a>
  437. <div class="fixedFont">
  438. <span class="light">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span>
  439. <b>size</b>(f)
  440. </div>
  441. <div class="description">
  442. Specifies the sizing function. By default, the sizing function is
  443. <tt>Number</tt>. The sizing function is invoked for each node in the tree
  444. (passed to the constructor): the sizing function must return
  445. <tt>undefined</tt> or <tt>NaN</tt> for internal nodes, and a number for
  446. leaf nodes. The aggregate sizes of internal nodes will be automatically
  447. computed by the layout.
  448. <p>For example, if the tree data structure represents a file system, with
  449. files as leaf nodes, and each file has a <tt>bytes</tt> attribute, you can
  450. specify a size function as:
  451. <pre>.size(function(d) d.bytes)</pre>
  452. This function will return <tt>undefined</tt> for internal nodes (since
  453. these do not have a <tt>bytes</tt> attribute), and a number for leaf nodes.
  454. <p>Note that the built-in <tt>Math.sqrt</tt> and <tt>Math.log</tt> methods
  455. can be used as sizing functions. These function similarly to
  456. <tt>Number</tt>, except perform a root and log scale, respectively.
  457. </div>
  458. <dl class="detailList">
  459. <dt class="heading">Parameters:</dt>
  460. <dt>
  461. <span class="light fixedFont">{function}</span> <b>f</b>
  462. </dt>
  463. <dd>the new sizing function.</dd>
  464. </dl>
  465. <dl class="detailList">
  466. <dt class="heading">Returns:</dt>
  467. <dd><span class="light fixedFont">{<a href="../symbols/pv.Layout.treemap.html">pv.Layout.treemap</a>}</span> this.</dd>
  468. </dl>
  469. <!-- ============================== event details ========================= -->
  470. <hr />
  471. </div>
  472. <!-- ============================== footer ================================= -->
  473. <div class="fineprint" style="clear:both">
  474. Documentation generated by <a href="http://code.google.com/p/jsdoc-toolkit/" target="_blank">JsDoc Toolkit</a> 2.3.0 on Tue Oct 06 2009 09:59:02 GMT-0700 (PDT)
  475. </div>
  476. </body>
  477. </html>