OLD | NEW |
1 Sky Style Language | 1 Sky Style Language |
2 ================== | 2 ================== |
3 | 3 |
4 Planed changes | 4 Planed changes |
5 -------------- | 5 -------------- |
6 | 6 |
7 Add //-to-end-of-line comments to be consistent with the script | 7 Add //-to-end-of-line comments to be consistent with the script |
8 language. | 8 language. |
9 | 9 |
10 | 10 |
(...skipping 347 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
358 | 358 |
359 readonly attribute Boolean descendantNeedsLayout; | 359 readonly attribute Boolean descendantNeedsLayout; |
360 // means that some child of this node has needsLayout set to true | 360 // means that some child of this node has needsLayout set to true |
361 // descendantNeedsLayout is set to false by the ownerLayoutManager's default
layout() method | 361 // descendantNeedsLayout is set to false by the ownerLayoutManager's default
layout() method |
362 | 362 |
363 readonly attribute LayoutManager layoutManager; | 363 readonly attribute LayoutManager layoutManager; |
364 readonly attribute LayoutManager ownerLayoutManager; // defaults to the parent
Node.layoutManager | 364 readonly attribute LayoutManager ownerLayoutManager; // defaults to the parent
Node.layoutManager |
365 // if you are not the ownerLayoutManager, then ignore this StyleNode in layo
ut() and paintChildren() | 365 // if you are not the ownerLayoutManager, then ignore this StyleNode in layo
ut() and paintChildren() |
366 // using walkChildren() does this for you | 366 // using walkChildren() does this for you |
367 | 367 |
368 readonly attribute Boolean needsPaint; | |
369 // means that either needsLayout is true or a property with needsPaint:true
has changed on this node | |
370 // needsPaint is set to false by the ownerLayoutManager's default paint() me
thod | |
371 | |
372 readonly attribute Boolean descendantNeedsPaint; | |
373 // means that some child of this node has needsPaint set to true | |
374 // descendantNeedsPaint is set to false by the ownerLayoutManager's default
paint() method | |
375 | |
376 // only the ownerLayoutManager can change these | 368 // only the ownerLayoutManager can change these |
377 readonly attribute Float x; // relative to left edge of ownerLayoutManager | 369 readonly attribute Float x; // relative to left edge of ownerLayoutManager |
378 readonly attribute Float y; // relative to top edge of ownerLayoutManager | 370 readonly attribute Float y; // relative to top edge of ownerLayoutManager |
379 readonly attribute Float width; | 371 readonly attribute Float width; |
380 readonly attribute Float height; | 372 readonly attribute Float height; |
381 } | 373 } |
382 ``` | 374 ``` |
383 | 375 |
384 The flattened tree is represented as a hierarchy of Node objects. For | 376 The flattened tree is represented as a hierarchy of Node objects. For |
385 any element that only contains text node children, the "text" property | 377 any element that only contains text node children, the "text" property |
(...skipping 46 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
432 | 424 |
433 virtual void release(StyleNode victim); | 425 virtual void release(StyleNode victim); |
434 // called when the StyleNode was removed from the tree | 426 // called when the StyleNode was removed from the tree |
435 | 427 |
436 void setChildPosition(child, x, y); // sets child.x, child.y | 428 void setChildPosition(child, x, y); // sets child.x, child.y |
437 void setChildX(child, y); // sets child.x | 429 void setChildX(child, y); // sets child.x |
438 void setChildY(child, y); // sets child.y | 430 void setChildY(child, y); // sets child.y |
439 void setChildSize(child, width, height); // sets child.width, child.height | 431 void setChildSize(child, width, height); // sets child.width, child.height |
440 void setChildWidth(child, width); // sets child.width | 432 void setChildWidth(child, width); // sets child.width |
441 void setChildHeight(child, height); // sets child.height | 433 void setChildHeight(child, height); // sets child.height |
442 // these set needsPaint on the node and on any node impacted by this (?) | |
443 // for setChildSize/Width/Height: if the new dimension is different than the
last assumed dimensions, and | 434 // for setChildSize/Width/Height: if the new dimension is different than the
last assumed dimensions, and |
444 // any StyleNodes with an ownerLayoutManager==this have cached values for ge
tProperty() that are marked | 435 // any StyleNodes with an ownerLayoutManager==this have cached values for ge
tProperty() that are marked |
445 // as provisional, clear them | 436 // as provisional, clear them |
446 | 437 |
447 Generator<StyleNode> walkChildren(); | 438 Generator<StyleNode> walkChildren(); |
448 // returns a generator that iterates over the children, skipping any whose o
wnerLayoutManager is not |this| | 439 // returns a generator that iterates over the children, skipping any whose o
wnerLayoutManager is not |this| |
449 | 440 |
450 Generator<StyleNode> walkChildrenBackwards(); | 441 Generator<StyleNode> walkChildrenBackwards(); |
451 // returns a generator that iterates over the children backwards, skipping a
ny whose ownerLayoutManager is not |this| | 442 // returns a generator that iterates over the children backwards, skipping a
ny whose ownerLayoutManager is not |this| |
452 | 443 |
(...skipping 71 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
524 // - this should always call this.markAsLaidOut() to reset needsLayout | 515 // - this should always call this.markAsLaidOut() to reset needsLayout |
525 // - the return value should include the final value for whichever of the wi
dth and height arguments | 516 // - the return value should include the final value for whichever of the wi
dth and height arguments |
526 // that is null | 517 // that is null |
527 // - subclasses that want to make 'auto' values dependent on the children sh
ould override this | 518 // - subclasses that want to make 'auto' values dependent on the children sh
ould override this |
528 // entirely, rather than overriding layoutChildren | 519 // entirely, rather than overriding layoutChildren |
529 | 520 |
530 virtual void layoutChildren(Number width, Number height); | 521 virtual void layoutChildren(Number width, Number height); |
531 // default implementation does nothing | 522 // default implementation does nothing |
532 // - override this if you want to lay out children but not have the children
affect your dimensions | 523 // - override this if you want to lay out children but not have the children
affect your dimensions |
533 | 524 |
534 void markAsPainted(); // sets this.node.needsPaint and this.node.descendantNee
dsPaint to false | |
535 virtual void paint(RenderingSurface canvas); | 525 virtual void paint(RenderingSurface canvas); |
536 // if needsPaint: | 526 // set a clip rect on the canvas for rect(0,0,this.width,this.height) |
537 // set a clip rect on the canvas for rect(0,0,this.width,this.height) | 527 // call the painter of each property, in order they were registered, which o
n this element has a painter |
538 // call the painter of each property, in order they were registered, which
on this element has a painter | |
539 // call this.paintChildren(canvas) | 528 // call this.paintChildren(canvas) |
540 // (the default implementation doesn't paint anything on top of the children
) | 529 // (the default implementation doesn't paint anything on top of the children
) |
541 // unset the clip | 530 // unset the clip |
542 // call markAsPainted() | 531 // - this gets called by the system if: |
| 532 // - you are in your parent's current display list and it's in its parent
's and so on up to the top, and |
| 533 // - you haven't had paint() called since the last time you were dirtied |
| 534 // - the following things make you dirty: |
| 535 // - dimensions of your style node changed |
| 536 // - one of your properties with needsLayout or needsPaint changed |
543 | 537 |
544 virtual void paintChildren(RenderingSurface canvas); | 538 virtual void paintChildren(RenderingSurface canvas); |
545 // if this.needsPaint or this.descendantNeedsPaint: | 539 // for each child returned by walkChildren(): |
546 // for each child returned by walkChildren(): | 540 // if child bounds intersects our bounds: |
547 // call this.paintChild(canvas, child) | 541 // call canvas.paintChild(child); |
548 // - you should skip children that will be clipped out of yourself because t
hey're outside your bounds | 542 // - you should skip children that will be clipped out of yourself because t
hey're outside your bounds |
549 | 543 // - if you transform the canvas, you'll have to implement your own version
of paintChildren() so |
550 virtual void paintChild(RenderingSurface canvas, LayoutManager child); | 544 // that you don't skip the children that are visible in the new coordinate
space but wouldn't be |
551 // if this.needsPaint(): | 545 // without the transform |
552 // insert a "paint this child" instruction in our canvas instruction list
(we should probably make sure we expose that API directly, too) | |
553 // if child.needsPaint or child.descendantNeedsPaint: | |
554 // start a new canvas for the child: | |
555 // transform the coordinate space by translate(child.x, child.y) | |
556 // call child.paint(canvas) | |
557 | 546 |
558 virtual Node hitTest(Float x, Float y); | 547 virtual Node hitTest(Float x, Float y); |
559 // default implementation uses the node's children nodes' x, y, | 548 // default implementation uses the node's children nodes' x, y, |
560 // width, and height, skipping any that have width=0 or height=0, or | 549 // width, and height, skipping any that have width=0 or height=0, or |
561 // whose ownerLayoutManager is not |this| | 550 // whose ownerLayoutManager is not |this| |
562 // default implementation walks the tree backwards from its built-in order | 551 // default implementation walks the tree backwards from its built-in order |
563 // if no child is hit, then return this.node | 552 // if no child is hit, then return this.node |
564 // override this if you changed your children's z-order, or if you used take
() to | 553 // override this if you changed your children's z-order, or if you used take
() to |
565 // hoist some descendants up to be your responsibility, or if your children
aren't | 554 // hoist some descendants up to be your responsibility, or if your children
aren't |
566 // rectangular (e.g. you lay them out in a hex grid) | 555 // rectangular (e.g. you lay them out in a hex grid) |
567 // make sure to offset the value you pass your children: child.layoutManager
.hitTest(x-child.x, y-child.y) | 556 // make sure to offset the value you pass your children: child.layoutManager
.hitTest(x-child.x, y-child.y) |
568 | 557 |
569 } | 558 } |
570 | 559 |
571 dictionary LayoutValueRange { | 560 dictionary LayoutValueRange { |
572 // negative values here should be treated as zero | 561 // negative values here should be treated as zero |
573 Float minimum = 0; | 562 Float minimum = 0; |
574 Float value = 0; // ideal desired width; if it's not in the range minimum .. m
aximum then it overrides minimum and maximum | 563 Float value = 0; // ideal desired width; if it's not in the range minimum .. m
aximum then it overrides minimum and maximum |
575 (Float or Infinity) maximum = Infinity; | 564 (Float or Infinity) maximum = Infinity; |
576 } | 565 } |
577 | 566 |
578 dictionary Dimensions { | 567 dictionary Dimensions { |
579 Float width = 0; | 568 Float width = 0; |
580 Float height = 0; | 569 Float height = 0; |
581 } | 570 } |
582 ``` | 571 ``` |
583 | 572 |
584 Given a tree of StyleNode objects rooted at /node/, the application is | |
585 rendered as follows: | |
586 | |
587 ```javascript | |
588 node.layoutManager.layout(screen.width, screen.height); | |
589 node.layoutManager.paint(); | |
590 ``` | |
591 | |
592 | 573 |
593 Paint | 574 Paint |
594 ----- | 575 ----- |
595 | 576 |
596 ```javascript | 577 ```javascript |
597 callback void Painter (StyleNode node, RenderingSurface canvas); | 578 callback void Painter (StyleNode node, RenderingSurface canvas); |
598 | 579 |
599 class RenderingSurface { | 580 class RenderingSurface { |
600 // ... | 581 |
| 582 // ... (API similar to <canvas>'s 2D API) |
| 583 |
| 584 void paintChild(StyleNode node); |
| 585 // inserts a "paint this child" instruction in this canvas's display list. |
| 586 // the child's display list, transformed by the child's x and y coordinates,
will be inserted into this |
| 587 // display list during painting. |
601 } | 588 } |
602 ``` | 589 ``` |
603 | 590 |
604 The convention is that the layout manager who calls your paint will | |
605 have transformed the coordinate space so that you should assume that | |
606 your top-left pixel is at 0,0. | |
607 | |
608 | 591 |
609 Default Styles | 592 Default Styles |
610 -------------- | 593 -------------- |
611 | 594 |
612 In the constructors for the default elements, they add to themselves | 595 In the constructors for the default elements, they add to themselves |
613 StyleDeclaration objects as follows: | 596 StyleDeclaration objects as follows: |
614 | 597 |
615 * ``import`` | 598 * ``import`` |
616 * ``template`` | 599 * ``template`` |
617 * ``style`` | 600 * ``style`` |
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
653 ```javascript | 636 ```javascript |
654 { display: { value: sky.ErrorLayoutManager } } | 637 { display: { value: sky.ErrorLayoutManager } } |
655 ``` | 638 ``` |
656 | 639 |
657 The ``div`` element doesn't have any default styles. | 640 The ``div`` element doesn't have any default styles. |
658 | 641 |
659 These declarations are all shared between all the elements (so e.g. if | 642 These declarations are all shared between all the elements (so e.g. if |
660 you reach in and change the declaration that was added to a ``title`` | 643 you reach in and change the declaration that was added to a ``title`` |
661 element, you're going to change the styles of all the other | 644 element, you're going to change the styles of all the other |
662 default-hidden elements). | 645 default-hidden elements). |
OLD | NEW |