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 119 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
130 | 130 |
131 | 131 |
132 | 132 |
133 Selectors | 133 Selectors |
134 --------- | 134 --------- |
135 | 135 |
136 Sky Style uses whatever SelectorQuery. Maybe one day we'll make | 136 Sky Style uses whatever SelectorQuery. Maybe one day we'll make |
137 SelectorQuery support being extended to support arbitrary selectors, | 137 SelectorQuery support being extended to support arbitrary selectors, |
138 but for now, it supports: | 138 but for now, it supports: |
139 | 139 |
140 tagname | 140 ```css |
141 #id | 141 tagname |
142 .class | 142 #id |
143 [attrname] | 143 .class |
144 [attrname=value] | 144 [attrname] |
145 :host ("host" string is fixed) | 145 [attrname=value] |
146 ::pseudo-element | 146 :host ("host" string is fixed) |
| 147 ::pseudo-element |
| 148 ``` |
147 | 149 |
148 These can be combined (without whitespace), with at most one tagname | 150 These can be combined (without whitespace), with at most one tagname |
149 (must be first) and at most one pseudo-element (must be last) as in: | 151 (must be first) and at most one pseudo-element (must be last) as in: |
150 | 152 |
151 tagname[attrname]#id:host.class.class[attrname=value]::foo | 153 ```css |
| 154 tagname[attrname]#id:host.class.class[attrname=value]::foo |
| 155 ``` |
152 | 156 |
153 In debug mode, giving two IDs, or the same selector twice (e.g. the | 157 In debug mode, giving two IDs, or the same selector twice (e.g. the |
154 same classname), or specifying other redundant or conflicting | 158 same classname), or specifying other redundant or conflicting |
155 selectors (e.g. [foo][foo=bar], or [foo=bar][foo=baz]) will be | 159 selectors (e.g. [foo][foo=bar], or [foo=bar][foo=baz]) will be |
156 flagged. | 160 flagged. |
157 | 161 |
158 Alternatively, a selector can be the special value "@document", | 162 Alternatively, a selector can be the special value "@document", |
159 optionally followed by a pseudo-element, as in: | 163 optionally followed by a pseudo-element, as in: |
160 | 164 |
161 @document::bar | 165 ```css |
| 166 @document::bar |
| 167 ``` |
162 | 168 |
163 | 169 |
164 Value Parser | 170 Value Parser |
165 ------------ | 171 ------------ |
166 | 172 |
167 class StyleToken { | 173 ```javascript |
168 constructor (String king, String value); | 174 class StyleToken { |
169 readonly attribute String kind; | 175 constructor (String king, String value); |
170 // string | 176 readonly attribute String kind; |
171 // identifier | 177 // string |
172 // function (identifier + '(') | 178 // identifier |
173 // number | 179 // function (identifier + '(') |
174 // symbol (one of @#$%& if not immediately following numeric or preceding
alphanumeric, or one of *^!?,/<[)>]+ or, if not followed by a digit, -) | 180 // number |
175 // dimension (number + identifier or number + one of @#$%&) | 181 // symbol (one of @#$%& if not immediately following numeric or preceding a
lphanumeric, or one of *^!?,/<[)>]+ or, if not followed by a digit, -) |
176 // literal (one of @#$%& + alphanumeric) | 182 // dimension (number + identifier or number + one of @#$%&) |
177 readonly attribute String value; | 183 // literal (one of @#$%& + alphanumeric) |
178 readonly attribute String unit; // for 'dimension' type, this is the punctua
tion or identifier that follows the number, for 'literal' type, this is the punc
tuation that precedes it | 184 readonly attribute String value; |
179 } | 185 readonly attribute String unit; // for 'dimension' type, this is the punctuati
on or identifier that follows the number, for 'literal' type, this is the punctu
ation that precedes it |
| 186 } |
180 | 187 |
181 class TokenSource { | 188 class TokenSource { |
182 constructor (Array<StyleToken> tokens); | 189 constructor (Array<StyleToken> tokens); |
183 IteratorResult next(); | 190 IteratorResult next(); |
184 TokenSourceBookmark getBookmark(); | 191 TokenSourceBookmark getBookmark(); |
185 void rewind(TokenSourceBookmark bookmark); | 192 void rewind(TokenSourceBookmark bookmark); |
186 } | 193 } |
187 class TokenSourceBookmark { | 194 class TokenSourceBookmark { |
188 constructor (); | 195 constructor (); |
189 // TokenSource stores unforgeable state on this object using symbols or a we
akmap or some such | 196 // TokenSource stores unforgeable state on this object using symbols or a weak
map or some such |
190 } | 197 } |
191 | 198 |
192 dictionary ParsedValue { | 199 dictionary ParsedValue { |
193 any value = null; | 200 any value = null; |
194 ValueResolver? resolver = null; | 201 ValueResolver? resolver = null; |
195 Boolean relativeDimension = false; // if true, e.g. for % lengths, the callb
ack will be called again if an ancestor's dimensions change | 202 Boolean relativeDimension = false; // if true, e.g. for % lengths, the callbac
k will be called again if an ancestor's dimensions change |
196 Painter? painter = null; | 203 Painter? painter = null; |
197 } | 204 } |
198 | 205 |
199 // best practice convention: if you're creating a property with needsPaint, yo
u should | 206 // best practice convention: if you're creating a property with needsPaint, you
should |
200 // create a new style value type for it so that it can set the paint callback
right; | 207 // create a new style value type for it so that it can set the paint callback ri
ght; |
201 // you should never use such a style type when parsing another property | 208 // you should never use such a style type when parsing another property |
202 | 209 |
203 callback any ParserCallback (TokenSource tokens); | 210 callback any ParserCallback (TokenSource tokens); |
204 | 211 |
205 class StyleValueType { | 212 class StyleValueType { |
206 constructor (); | 213 constructor (); |
207 void addParser(ParserCallback parser); | 214 void addParser(ParserCallback parser); |
208 any parse(TokenSource tokens, Boolean root = false); | 215 any parse(TokenSource tokens, Boolean root = false); |
209 // for each parser callback that was registered, in reverse | 216 // for each parser callback that was registered, in reverse |
210 // order (most recently registered first), run these steps: | 217 // order (most recently registered first), run these steps: |
211 // let bookmark = tokens.getBookmark(); | 218 // let bookmark = tokens.getBookmark(); |
212 // try { | 219 // try { |
213 // let result = parser(tokens); | 220 // let result = parser(tokens); |
214 // if (root) { | 221 // if (root) { |
215 // if (!tokens.next().done) | 222 // if (!tokens.next().done) |
216 // throw new Error(); | 223 // throw new Error(); |
217 // } | 224 // } |
218 // } except { | 225 // } except { |
219 // tokens.rewind(bookmark); | 226 // tokens.rewind(bookmark); |
220 // } | 227 // } |
221 // (root is set when you need to parse the entire token stream to be valid) | 228 // (root is set when you need to parse the entire token stream to be valid) |
222 } | 229 } |
223 | 230 |
224 // note: if you define a style value type that uses other style value types, e
.g. a "length pair" that accepts two lengths, then | 231 // note: if you define a style value type that uses other style value types, e.g
. a "length pair" that accepts two lengths, then |
225 // if any of the subtypes have a resolver, you need to make sure you have a re
solver that calls them to compute the final value | 232 // if any of the subtypes have a resolver, you need to make sure you have a reso
lver that calls them to compute the final value |
226 | 233 |
227 dictionary PropertySettings { | 234 dictionary PropertySettings { |
228 String name; | 235 String name; |
229 StyleValueType type; // the output from the parser is coerced to a ParsedVal
ue | 236 StyleValueType type; // the output from the parser is coerced to a ParsedValue |
230 Boolean inherits = false; | 237 Boolean inherits = false; |
231 any initialValue = null; | 238 any initialValue = null; |
232 Boolean needsLayout = false; | 239 Boolean needsLayout = false; |
233 Boolean needsPaint = false; | 240 Boolean needsPaint = false; |
234 } | 241 } |
235 | 242 |
236 void registerProperty(PropertySettings propertySettings); | 243 void registerProperty(PropertySettings propertySettings); |
237 // when you register a new property, document the format that is expected to
be cascaded | 244 // when you register a new property, document the format that is expected to b
e cascaded |
238 // (the output from the propertySettings.type parser's ParsedValue.value fie
ld after the resolver, if any, has been called) | 245 // (the output from the propertySettings.type parser's ParsedValue.value field
after the resolver, if any, has been called) |
239 | 246 |
240 // sky:core exports a bunch of style value types so that people can | 247 // sky:core exports a bunch of style value types so that people can |
241 // extend them | 248 // extend them |
242 attribute StyleValueType PositiveLengthOrInfinityStyleValueType; | 249 attribute StyleValueType PositiveLengthOrInfinityStyleValueType; |
243 attribute StyleValueType PositiveLengthOrAutoStyleValueType; | 250 attribute StyleValueType PositiveLengthOrAutoStyleValueType; |
244 attribute StyleValueType PositiveLengthStyleValueType; | 251 attribute StyleValueType PositiveLengthStyleValueType; |
245 attribute StyleValueType DisplayStyleValueType; | 252 attribute StyleValueType DisplayStyleValueType; |
246 | 253 ``` |
247 | 254 |
248 Inline Styles | 255 Inline Styles |
249 ------------- | 256 ------------- |
250 | 257 |
| 258 ```javascript |
251 partial class Element { | 259 partial class Element { |
252 readonly attribute StyleDeclarationList style; | 260 readonly attribute StyleDeclarationList style; |
253 } | 261 } |
254 | 262 |
255 class StyleDeclarationList { | 263 class StyleDeclarationList { |
256 constructor (); | 264 constructor (); |
257 void add(StyleDeclaration styles, String? pseudoElement = null); // O(1) // in
debug mode, throws if the dictionary has any properties that aren't registered | 265 void add(StyleDeclaration styles, String? pseudoElement = null); // O(1) // in
debug mode, throws if the dictionary has any properties that aren't registered |
258 void remove(StyleDeclaration styles, String? pseudoElement = null); // O(N) in
number of declarations | 266 void remove(StyleDeclaration styles, String? pseudoElement = null); // O(N) in
number of declarations |
259 // TODO(ianh): Need to support inserting rules preserving order somehow | 267 // TODO(ianh): Need to support inserting rules preserving order somehow |
260 Array<StyleDeclaration> getDeclarations(String? pseudoElement = null); // O(N)
in number of declarations | 268 Array<StyleDeclaration> getDeclarations(String? pseudoElement = null); // O(N)
in number of declarations |
261 } | 269 } |
262 | 270 |
263 typedef StyleDeclaration Dictionary<ParsedValue>; | 271 typedef StyleDeclaration Dictionary<ParsedValue>; |
264 | 272 ``` |
265 | 273 |
266 Rule Matching | 274 Rule Matching |
267 ------------- | 275 ------------- |
268 | 276 |
| 277 ```javascript |
269 partial class StyleElement { | 278 partial class StyleElement { |
270 Array<Rule> getRules(); // O(N) in rules | 279 Array<Rule> getRules(); // O(N) in rules |
271 } | 280 } |
272 | 281 |
273 class Rule { | 282 class Rule { |
274 constructor (); | 283 constructor (); |
275 attribute SelectorQuery selector; // O(1) | 284 attribute SelectorQuery selector; // O(1) |
276 attribute String? pseudoElement; // O(1) | 285 attribute String? pseudoElement; // O(1) |
277 attribute StyleDeclaration styles; // O(1) | 286 attribute StyleDeclaration styles; // O(1) |
278 } | 287 } |
| 288 ``` |
279 | 289 |
280 Each frame, at some defined point relative to requestAnimationFrame(): | 290 Each frame, at some defined point relative to requestAnimationFrame(): |
281 - If a rule starts applying to an element, sky:core calls thatElement.style.add
(rule.styles, rule.pseudoElement); | 291 - If a rule starts applying to an element, sky:core calls thatElement.style.add
(rule.styles, rule.pseudoElement); |
282 - If a rule stops applying to an element, sky:core calls thatElement.style.remo
ve(rule.styles, rule.pseudoElement); | 292 - If a rule stops applying to an element, sky:core calls thatElement.style.remo
ve(rule.styles, rule.pseudoElement); |
283 | 293 |
284 TODO(ianh): fix the above so that rule order is maintained | 294 TODO(ianh): fix the above so that rule order is maintained |
285 | 295 |
286 | 296 |
287 Cascade | 297 Cascade |
288 ------- | 298 ------- |
289 | 299 |
290 For each Element, the StyleDeclarationList is conceptually flattened | 300 For each Element, the StyleDeclarationList is conceptually flattened |
291 so that only the last declaration mentioning a property is left. | 301 so that only the last declaration mentioning a property is left. |
292 | 302 |
293 Create the flattened render tree as a tree of StyleNode objects | 303 Create the flattened render tree as a tree of StyleNode objects |
294 (described below). For each one, run the equivalent of the following | 304 (described below). For each one, run the equivalent of the following |
295 code: | 305 code: |
296 | 306 |
297 var display = node.getProperty('display'); | 307 ```javascript |
298 if (display) { | 308 var display = node.getProperty('display'); |
299 node.layoutManager = new display(node, ownerManager); | 309 if (display) { |
300 return true; | 310 node.layoutManager = new display(node, ownerManager); |
301 } | 311 return true; |
302 return false; | 312 } |
| 313 return false; |
| 314 ``` |
303 | 315 |
304 If that code returns false, then that node an all its descendants must | 316 If that code returns false, then that node an all its descendants must |
305 be dropped from the render tree. | 317 be dropped from the render tree. |
306 | 318 |
307 If any node is removed in this pass relative to the previous pass, and | 319 If any node is removed in this pass relative to the previous pass, and |
308 it has an ownerLayoutManager, then call | 320 it has an ownerLayoutManager, then call |
309 ``node.ownerLayoutManager.release(node)`` | 321 |
| 322 ```node.ownerLayoutManager.release(node)``` |
| 323 |
310 ...to notify the layout manager that the node went away, then set the | 324 ...to notify the layout manager that the node went away, then set the |
311 node's layoutManager and ownerLayoutManager attributes to null. | 325 node's layoutManager and ownerLayoutManager attributes to null. |
312 | 326 |
313 callback any ValueResolver (any value, String propertyName, StyleNode node, Fl
oat containerWidth, Float containerHeight); | 327 ```javascript |
| 328 callback any ValueResolver (any value, String propertyName, StyleNode node, Floa
t containerWidth, Float containerHeight); |
314 | 329 |
315 class StyleNode { | 330 class StyleNode { |
316 // this is generated before layout | 331 // this is generated before layout |
317 readonly attribute String text; | 332 readonly attribute String text; |
318 readonly attribute Node? parentNode; | 333 readonly attribute Node? parentNode; |
319 readonly attribute Node? firstChild; | 334 readonly attribute Node? firstChild; |
320 readonly attribute Node? nextSibling; | 335 readonly attribute Node? nextSibling; |
321 | 336 |
322 // access to the results of the cascade | 337 // access to the results of the cascade |
323 any getProperty(String name, String? pseudoElement = null); | 338 any getProperty(String name, String? pseudoElement = null); |
324 // looking at the declarations for the given pseudoElement: | 339 // looking at the declarations for the given pseudoElement: |
325 // if there's a cached value, return it | 340 // if there's a cached value, return it |
326 // otherwise, if there's an applicable ParsedValue, then | 341 // otherwise, if there's an applicable ParsedValue, then |
327 // if it has a resolver: | 342 // if it has a resolver: |
328 // call it | 343 // call it |
329 // cache the value | 344 // cache the value |
330 // if relativeDimension is true, then mark the value as provisional | 345 // if relativeDimension is true, then mark the value as provisional |
331 // return the value | 346 // return the value |
332 // otherwise use the ParsedValue's value; cache it; return it | 347 // otherwise use the ParsedValue's value; cache it; return it |
333 // otherwise, if a pseudo-element was specified, try again without one | 348 // otherwise, if a pseudo-element was specified, try again without one |
334 // otherwise, if the property is inherited and there's a parent: | 349 // otherwise, if the property is inherited and there's a parent: |
335 // get it from the parent (without pseudo); cache it; return it | 350 // get it from the parent (without pseudo); cache it; return it |
336 // otherwise, get the default value; cache it; return it | 351 // otherwise, get the default value; cache it; return it |
337 | 352 |
338 readonly attribute Boolean needsLayout; // means that a property with needsL
ayout:true has changed on this node or one of its descendants | 353 readonly attribute Boolean needsLayout; // means that a property with needsLay
out:true has changed on this node or one of its descendants |
339 readonly attribute LayoutManager layoutManager; | 354 readonly attribute LayoutManager layoutManager; |
340 | 355 |
341 readonly attribute LayoutManager ownerLayoutManager; // defaults to the pare
ntNode.layoutManager | 356 readonly attribute LayoutManager ownerLayoutManager; // defaults to the parent
Node.layoutManager |
342 // if you are not the ownerLayoutManager, then ignore this StyleNode in la
yout() and paintChildren() | 357 // if you are not the ownerLayoutManager, then ignore this StyleNode in layo
ut() and paintChildren() |
343 // using walkChildren() does this for you | 358 // using walkChildren() does this for you |
344 | 359 |
345 readonly attribute Boolean needsPaint; // means that either needsLayout is t
rue or a property with needsPaint:true has changed on this node or one of its de
scendants | 360 readonly attribute Boolean needsPaint; // means that either needsLayout is tru
e or a property with needsPaint:true has changed on this node or one of its desc
endants |
346 // needsPaint is set to false by the ownerLayoutManager's default paint()
method | 361 // needsPaint is set to false by the ownerLayoutManager's default paint() me
thod |
347 | 362 |
348 // only the ownerLayoutManager can change these | 363 // only the ownerLayoutManager can change these |
349 readonly attribute Float x; // relative to left edge of ownerLayoutManager | 364 readonly attribute Float x; // relative to left edge of ownerLayoutManager |
350 readonly attribute Float y; // relative to top edge of ownerLayoutManager | 365 readonly attribute Float y; // relative to top edge of ownerLayoutManager |
351 readonly attribute Float width; | 366 readonly attribute Float width; |
352 readonly attribute Float height; | 367 readonly attribute Float height; |
353 } | 368 } |
| 369 ``` |
354 | 370 |
355 The flattened tree is represented as a hierarchy of Node objects. For | 371 The flattened tree is represented as a hierarchy of Node objects. For |
356 any element that only contains text node children, the "text" property | 372 any element that only contains text node children, the "text" property |
357 is set accordingly. For elements with mixed text node and non-text | 373 is set accordingly. For elements with mixed text node and non-text |
358 node children, each run of text nodes is represented as a separate | 374 node children, each run of text nodes is represented as a separate |
359 Node with the "text" property set accordingly and the styles set as if | 375 Node with the "text" property set accordingly and the styles set as if |
360 the Node inherited everything inheritable from its parent. | 376 the Node inherited everything inheritable from its parent. |
361 | 377 |
362 | 378 |
363 Layout | 379 Layout |
364 ------ | 380 ------ |
365 | 381 |
366 sky:core registers 'display' as follows: | 382 sky:core registers 'display' as follows: |
367 | 383 |
| 384 ```javascript |
368 { | 385 { |
369 name: 'display', | 386 name: 'display', |
370 type: sky.DisplayStyleValueType, | 387 type: sky.DisplayStyleValueType, |
371 inherits: false, | 388 inherits: false, |
372 initialValue: sky.BlockLayoutManager, | 389 initialValue: sky.BlockLayoutManager, |
373 needsLayout: true, | 390 needsLayout: true, |
374 } | 391 } |
| 392 ``` |
375 | 393 |
376 The following API is then used to add new layout manager types to 'display': | 394 The following API is then used to add new layout manager types to 'display': |
377 | 395 |
378 void registerLayoutManager(String displayValue, LayoutManagerConstructor? layo
utManager); | 396 ```javascript |
| 397 void registerLayoutManager(String displayValue, LayoutManagerConstructor? layout
Manager); |
| 398 ``` |
379 | 399 |
380 sky:core by default registers: | 400 sky:core by default registers: |
381 | 401 |
382 'block': sky.BlockLayoutManager | 402 - 'block': sky.BlockLayoutManager |
383 'paragraph': sky.ParagraphLayoutManager | 403 - 'paragraph': sky.ParagraphLayoutManager |
384 'inline': sky.InlineLayoutManager | 404 - 'inline': sky.InlineLayoutManager |
385 'none': null | 405 - 'none': null |
386 | 406 |
387 | 407 |
388 Layout managers inherit from the following API: | 408 Layout managers inherit from the following API: |
389 | 409 |
390 class LayoutManager { | 410 ``` |
391 readonly attribute StyleNode node; | 411 class LayoutManager { |
392 constructor LayoutManager(StyleNode node); | 412 readonly attribute StyleNode node; |
| 413 constructor LayoutManager(StyleNode node); |
393 | 414 |
394 void take(StyleNode victim); // sets victim.ownerLayoutManager = this; | 415 void take(StyleNode victim); // sets victim.ownerLayoutManager = this; |
395 // assert: victim hasn't been take()n yet during this layout | 416 // assert: victim hasn't been take()n yet during this layout |
396 // assert: victim.needsLayout == true | 417 // assert: victim.needsLayout == true |
397 // assert: an ancestor of victim has needsLayout == this (aka, victim is a
descendant of this.node) | 418 // assert: an ancestor of victim has needsLayout == this (aka, victim is a d
escendant of this.node) |
398 | 419 |
399 virtual void release(StyleNode victim); | 420 virtual void release(StyleNode victim); |
400 // called when the StyleNode was removed from the tree | 421 // called when the StyleNode was removed from the tree |
401 | 422 |
402 void setChildPosition(child, x, y); // sets child.x, child.y | 423 void setChildPosition(child, x, y); // sets child.x, child.y |
403 void setChildX(child, y); // sets child.x | 424 void setChildX(child, y); // sets child.x |
404 void setChildY(child, y); // sets child.y | 425 void setChildY(child, y); // sets child.y |
405 void setChildSize(child, width, height); // sets child.width, child.height | 426 void setChildSize(child, width, height); // sets child.width, child.height |
406 void setChildWidth(child, width); // sets child.width | 427 void setChildWidth(child, width); // sets child.width |
407 void setChildHeight(child, height); // sets child.height | 428 void setChildHeight(child, height); // sets child.height |
408 // these set needsPaint on the node and on any node impacted by this (?) | 429 // these set needsPaint on the node and on any node impacted by this (?) |
409 // for setChildSize/Width/Height: if the new dimension is different than t
he last assumed dimensions, and | 430 // for setChildSize/Width/Height: if the new dimension is different than the
last assumed dimensions, and |
410 // any StyleNodes with an ownerLayoutManager==this have cached values for
getProperty() that are marked | 431 // any StyleNodes with an ownerLayoutManager==this have cached values for ge
tProperty() that are marked |
411 // as provisional, clear them | 432 // as provisional, clear them |
412 | 433 |
413 Generator<StyleNode> walkChildren(); | 434 Generator<StyleNode> walkChildren(); |
414 // returns a generator that iterates over the children, skipping any whose
ownerLayoutManager is not |this| | 435 // returns a generator that iterates over the children, skipping any whose o
wnerLayoutManager is not |this| |
415 | 436 |
416 Generator<StyleNode> walkChildrenBackwards(); | 437 Generator<StyleNode> walkChildrenBackwards(); |
417 // returns a generator that iterates over the children backwards, skipping
any whose ownerLayoutManager is not |this| | 438 // returns a generator that iterates over the children backwards, skipping a
ny whose ownerLayoutManager is not |this| |
418 | 439 |
419 void assumeDimensions(Float width, Float height); | 440 void assumeDimensions(Float width, Float height); |
420 // sets the assumed dimensions for calls to getProperty() on StyleNodes th
at have this as an ownerLayoutManager | 441 // sets the assumed dimensions for calls to getProperty() on StyleNodes that
have this as an ownerLayoutManager |
421 // if the new dimension is different than the last assumed dimensions, and
any StyleNodes with an | 442 // if the new dimension is different than the last assumed dimensions, and a
ny StyleNodes with an |
422 // ownerLayoutManager==this have cached values for getProperty() that are
marked as provisional, clear them | 443 // ownerLayoutManager==this have cached values for getProperty() that are ma
rked as provisional, clear them |
423 // TODO(ianh): should we force this to match the input to layout(), when c
alled from inside layout() and when | 444 // TODO(ianh): should we force this to match the input to layout(), when cal
led from inside layout() and when |
424 // layout() has a forced width and/or height? | 445 // layout() has a forced width and/or height? |
425 | 446 |
426 virtual LayoutValueRange getIntrinsicWidth(Float? defaultWidth = null); | 447 virtual LayoutValueRange getIntrinsicWidth(Float? defaultWidth = null); |
427 // returns min-width, width, and max-width, normalised, defaulting to valu
es given in LayoutValueRange | 448 // returns min-width, width, and max-width, normalised, defaulting to values
given in LayoutValueRange |
428 // if argument is provided, it overrides width | 449 // if argument is provided, it overrides width |
429 | 450 |
430 virtual LayoutValueRange getIntrinsicHeight(Float? defaultHeight = null); | 451 virtual LayoutValueRange getIntrinsicHeight(Float? defaultHeight = null); |
431 // returns min-height, height, and max-height, normalised, defaulting to v
alues given in LayoutValueRange | 452 // returns min-height, height, and max-height, normalised, defaulting to val
ues given in LayoutValueRange |
432 // if argument is provided, it overrides height | 453 // if argument is provided, it overrides height |
433 | 454 |
434 virtual Dimensions layout(Number? width, Number? height); | 455 virtual Dimensions layout(Number? width, Number? height); |
435 // returns { } | 456 // returns { } |
436 // the return value should include the final value for whichever of the wi
dth and height arguments that is null | 457 // the return value should include the final value for whichever of the widt
h and height arguments that is null |
437 // TODO(ianh): should we just grab the width and height from assumeDimensi
ons()? | 458 // TODO(ianh): should we just grab the width and height from assumeDimension
s()? |
438 | 459 |
439 void markAsPainted(); // sets this.node.needsPaint to false | 460 void markAsPainted(); // sets this.node.needsPaint to false |
440 virtual void paint(RenderingSurface canvas); | 461 virtual void paint(RenderingSurface canvas); |
441 // set a clip rect on the canvas for rect(0,0,this.width,this.height) | 462 // set a clip rect on the canvas for rect(0,0,this.width,this.height) |
442 // call the painter of each property, in order they were registered, which
on this element has a painter | 463 // call the painter of each property, in order they were registered, which o
n this element has a painter |
443 // call this.paintChildren() | 464 // call this.paintChildren() |
444 // unset the clip | 465 // unset the clip |
445 // call markAsPainted() | 466 // call markAsPainted() |
446 | 467 |
447 virtual void paintChildren(RenderingSurface canvas); | 468 virtual void paintChildren(RenderingSurface canvas); |
448 // just calls paint() for each child returned by walkChildren() whose need
sPaint is true, | 469 // just calls paint() for each child returned by walkChildren() whose needsP
aint is true, |
449 // after transforming the coordinate space by translate(child.x,child.y) | 470 // after transforming the coordinate space by translate(child.x,child.y) |
450 // you should skip children that will be clipped out of yourself because t
hey're outside your bounds | 471 // you should skip children that will be clipped out of yourself because the
y're outside your bounds |
451 | 472 |
452 virtual Node hitTest(Float x, Float y); | 473 virtual Node hitTest(Float x, Float y); |
453 // default implementation uses the node's children nodes' x, y, | 474 // default implementation uses the node's children nodes' x, y, |
454 // width, and height, skipping any that have width=0 or height=0, or | 475 // width, and height, skipping any that have width=0 or height=0, or |
455 // whose ownerLayoutManager is not |this| | 476 // whose ownerLayoutManager is not |this| |
456 // default implementation walks the tree backwards from its built-in order | 477 // default implementation walks the tree backwards from its built-in order |
457 // if no child is hit, then return this.node | 478 // if no child is hit, then return this.node |
458 // override this if you changed your children's z-order, or if you used ta
ke() to | 479 // override this if you changed your children's z-order, or if you used take
() to |
459 // hoist some descendants up to be your responsibility, or if your childre
n aren't | 480 // hoist some descendants up to be your responsibility, or if your children
aren't |
460 // rectangular (e.g. you lay them out in a hex grid) | 481 // rectangular (e.g. you lay them out in a hex grid) |
461 // make sure to offset the value you pass your children: child.layoutManag
er.hitTest(x-child.x, y-child.y) | 482 // make sure to offset the value you pass your children: child.layoutManager
.hitTest(x-child.x, y-child.y) |
462 | 483 |
463 } | 484 } |
464 | 485 |
465 dictionary LayoutValueRange { | 486 dictionary LayoutValueRange { |
466 // negative values here should be treated as zero | 487 // negative values here should be treated as zero |
467 Float minimum = 0; | 488 Float minimum = 0; |
468 Float value = 0; // ideal desired width; if it's not in the range minimum ..
maximum then it overrides minimum and maximum | 489 Float value = 0; // ideal desired width; if it's not in the range minimum .. m
aximum then it overrides minimum and maximum |
469 (Float or Infinity) maximum = Infinity; | 490 (Float or Infinity) maximum = Infinity; |
470 } | 491 } |
471 | 492 |
472 dictionary Dimensions { | 493 dictionary Dimensions { |
473 Float width = 0; | 494 Float width = 0; |
474 Float height = 0; | 495 Float height = 0; |
475 } | 496 } |
476 | 497 ``` |
477 | 498 |
478 Given a tree of StyleNode objects rooted at /node/, the application is | 499 Given a tree of StyleNode objects rooted at /node/, the application is |
479 rendered as follows: | 500 rendered as follows: |
480 | 501 |
481 node.layoutManager.layout(screen.width, screen.height); | 502 ```javascript |
482 node.layoutManager.paint(); | 503 node.layoutManager.layout(screen.width, screen.height); |
483 | 504 node.layoutManager.paint(); |
| 505 ``` |
484 | 506 |
485 | 507 |
486 Paint | 508 Paint |
487 ----- | 509 ----- |
488 | 510 |
489 callback void Painter (StyleNode node, RenderingSurface canvas); | 511 ```javascript |
| 512 callback void Painter (StyleNode node, RenderingSurface canvas); |
490 | 513 |
491 class RenderingSurface { | 514 class RenderingSurface { |
492 // ... | 515 // ... |
493 } | 516 } |
| 517 ``` |
494 | 518 |
495 The convention is that the layout manager who calls your paint will | 519 The convention is that the layout manager who calls your paint will |
496 have transformed the coordinate space so that you should assume that | 520 have transformed the coordinate space so that you should assume that |
497 your top-left pixel is at 0,0. | 521 your top-left pixel is at 0,0. |
498 | 522 |
499 | 523 |
500 Default Styles | 524 Default Styles |
501 -------------- | 525 -------------- |
502 | 526 |
503 In the constructors for the default elements, they add to themselves | 527 In the constructors for the default elements, they add to themselves |
(...skipping 28 matching lines...) Expand all Loading... |
532 * ``error`` | 556 * ``error`` |
533 This adds to itself the declaration with value: | 557 This adds to itself the declaration with value: |
534 ``{ display: { value: sky.ErrorLayoutManager } }`` | 558 ``{ display: { value: sky.ErrorLayoutManager } }`` |
535 | 559 |
536 The ``div`` element doesn't have any default styles. | 560 The ``div`` element doesn't have any default styles. |
537 | 561 |
538 These declarations are all shared between all the elements (so e.g. if | 562 These declarations are all shared between all the elements (so e.g. if |
539 you reach in and change the declaration that was added to a ``title`` | 563 you reach in and change the declaration that was added to a ``title`` |
540 element, you're going to change the styles of all the other | 564 element, you're going to change the styles of all the other |
541 default-hidden elements). | 565 default-hidden elements). |
OLD | NEW |