| 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.
|