1 | # Specification
|
2 |
|
3 |
|
4 |
|
5 | ## Terminology
|
6 |
|
7 | `main-axis`:: The axis which is parallel with the side of the `target` that the `popover` is laid out upon. If the `popover` is left _or_ right of the `target` then the `main-axis` is horizontal. If the `popover` is above _or_ below the `target` then the `main-axis` is vertical.
|
8 |
|
9 | `cross-axis`:: The axis which is counter to the `main-axis`.
|
10 |
|
11 | `zone`:: The maximum-sized rectangle in a particular direction between one side of the `target` and the `window bounds`. There are four possible `zones` therefore: `top` `right` `bottom` `left`.
|
12 |
|
13 | `target`:: The element that the `popover` calculates its position relative to.
|
14 |
|
15 | `docking edge`:: The edge of `body` that is closest to `target` or vice-versa.
|
16 |
|
17 |
|
18 |
|
19 | ## Requirements
|
20 |
|
21 | . The `popover` MUST reference a **target**.
|
22 |
|
23 | . The `popover` MUST have a **body** whose contents may be any view.
|
24 |
|
25 | .. The `body` should autosize to the dimensions of its contents.
|
26 |
|
27 | .. `body bounds` MUSNT exceed `window bounds`.
|
28 |
|
29 | .. There SHOULD be a small visual gap between the respective boundaries of `body` and `window`.
|
30 |
|
31 | .. The `body` MUST bias toward **cross-axis** centre-alignment with the `target`'s centre `registration point` up until such movement would break requirement `2.ii`.
|
32 |
|
33 | .. The `docking edge` of the `body` must be sufficiently spaced from `target` to fit `tip`.
|
34 |
|
35 | . The `popover` MUST automatically choose to layout in one of the four **zones**. The selected `zone` MUST be the one with the largest area.
|
36 |
|
37 | .. A `zone` preference MAY be given so that if multiple `zone` areas can wholly fit the `popover` one can be chosen over others even if it is of a lesser area.
|
38 |
|
39 | . The `popover` MUST have a **tip** that is connected to the `body` and points to the centre **registration point** of the `target`'s `docking edge`.
|
40 |
|
41 | .. The `tip` should automatically position itself on the `body`'s `docking edge`.
|
42 |
|
43 | .. The `tip` should bias toward centre-alignment of itself on the `cross-axis` up to such a point that it does not exceed the `body bounds`.
|
44 |
|
45 | .. If the `body bounds` have reached `window bounds` then the `tip` should slide along its own `cross-axis` until it reaches either centre-alignment with `target` or `body` bounds first.
|
46 |
|
47 | .. The `tip` SHOULD be an equilateral triangle shape until doing so would no longer allow it to fit within `body bounds`. At that point it MUST be a right-angle triangle with the hypotenuse oriented toward the opposite `cross-axis` end of `body`.
|
48 |
|
49 | . When the `target position` or `target bounds` or `window bounds` change the `popover` should recalculate its `body` and `tip` layout.
|
50 |
|
51 | . When the `window bounds` change the `popover` should recalculate its `body` and `tip` position.
|
52 |
|
53 |
|
54 |
|
55 | ## Limitations of this specification
|
56 |
|
57 | . Behaviour of what to do when `target` exits `window bounds` is undefined.
|
58 |
|
59 | . A `zone` preference is only eligible when multiple `zones` wholly fit the `body`. A more sophisticated algorithm could account for percentage-fit such that a `zone` would be used even if it did not wholly fit `body` and even while other `zones` do.
|
60 |
|
61 | . Layout thrashing of `body` changing zones can be mitigated by hysteresis and/or throttling techniques but is not specified here.
|
62 |
|
63 | . Only behaviour for rectangular `target` and `popovers` are specified.
|