| 1 | /**
|
| 2 | * A sizer object for use with the box engine layout functions.
|
| 3 | *
|
| 4 | * #### Notes
|
| 5 | * A box sizer holds the geometry information for an object along an
|
| 6 | * arbitrary layout orientation.
|
| 7 | *
|
| 8 | * For best performance, this class should be treated as a raw data
|
| 9 | * struct. It should not typically be subclassed.
|
| 10 | */
|
| 11 | export declare class BoxSizer {
|
| 12 | /**
|
| 13 | * The preferred size for the sizer.
|
| 14 | *
|
| 15 | * #### Notes
|
| 16 | * The sizer will be given this initial size subject to its size
|
| 17 | * bounds. The sizer will not deviate from this size unless such
|
| 18 | * deviation is required to fit into the available layout space.
|
| 19 | *
|
| 20 | * There is no limit to this value, but it will be clamped to the
|
| 21 | * bounds defined by [[minSize]] and [[maxSize]].
|
| 22 | *
|
| 23 | * The default value is `0`.
|
| 24 | */
|
| 25 | sizeHint: number;
|
| 26 | /**
|
| 27 | * The minimum size of the sizer.
|
| 28 | *
|
| 29 | * #### Notes
|
| 30 | * The sizer will never be sized less than this value, even if
|
| 31 | * it means the sizer will overflow the available layout space.
|
| 32 | *
|
| 33 | * It is assumed that this value lies in the range `[0, Infinity)`
|
| 34 | * and that it is `<=` to [[maxSize]]. Failure to adhere to this
|
| 35 | * constraint will yield undefined results.
|
| 36 | *
|
| 37 | * The default value is `0`.
|
| 38 | */
|
| 39 | minSize: number;
|
| 40 | /**
|
| 41 | * The maximum size of the sizer.
|
| 42 | *
|
| 43 | * #### Notes
|
| 44 | * The sizer will never be sized greater than this value, even if
|
| 45 | * it means the sizer will underflow the available layout space.
|
| 46 | *
|
| 47 | * It is assumed that this value lies in the range `[0, Infinity]`
|
| 48 | * and that it is `>=` to [[minSize]]. Failure to adhere to this
|
| 49 | * constraint will yield undefined results.
|
| 50 | *
|
| 51 | * The default value is `Infinity`.
|
| 52 | */
|
| 53 | maxSize: number;
|
| 54 | /**
|
| 55 | * The stretch factor for the sizer.
|
| 56 | *
|
| 57 | * #### Notes
|
| 58 | * This controls how much the sizer stretches relative to its sibling
|
| 59 | * sizers when layout space is distributed. A stretch factor of zero
|
| 60 | * is special and will cause the sizer to only be resized after all
|
| 61 | * other sizers with a stretch factor greater than zero have been
|
| 62 | * resized to their limits.
|
| 63 | *
|
| 64 | * It is assumed that this value is an integer that lies in the range
|
| 65 | * `[0, Infinity)`. Failure to adhere to this constraint will yield
|
| 66 | * undefined results.
|
| 67 | *
|
| 68 | * The default value is `1`.
|
| 69 | */
|
| 70 | stretch: number;
|
| 71 | /**
|
| 72 | * The computed size of the sizer.
|
| 73 | *
|
| 74 | * #### Notes
|
| 75 | * This value is the output of a call to [[boxCalc]]. It represents
|
| 76 | * the computed size for the object along the layout orientation,
|
| 77 | * and will always lie in the range `[minSize, maxSize]`.
|
| 78 | *
|
| 79 | * This value is output only.
|
| 80 | *
|
| 81 | * Changing this value will have no effect.
|
| 82 | */
|
| 83 | size: number;
|
| 84 | /**
|
| 85 | * An internal storage property for the layout algorithm.
|
| 86 | *
|
| 87 | * #### Notes
|
| 88 | * This value is used as temporary storage by the layout algorithm.
|
| 89 | *
|
| 90 | * Changing this value will have no effect.
|
| 91 | */
|
| 92 | done: boolean;
|
| 93 | }
|
| 94 | /**
|
| 95 | * The namespace for the box engine layout functions.
|
| 96 | */
|
| 97 | export declare namespace BoxEngine {
|
| 98 | /**
|
| 99 | * Calculate the optimal layout sizes for a sequence of box sizers.
|
| 100 | *
|
| 101 | * This distributes the available layout space among the box sizers
|
| 102 | * according to the following algorithm:
|
| 103 | *
|
| 104 | * 1. Initialize the sizers's size to its size hint and compute the
|
| 105 | * sums for each of size hint, min size, and max size.
|
| 106 | *
|
| 107 | * 2. If the total size hint equals the available space, return.
|
| 108 | *
|
| 109 | * 3. If the available space is less than the total min size, set all
|
| 110 | * sizers to their min size and return.
|
| 111 | *
|
| 112 | * 4. If the available space is greater than the total max size, set
|
| 113 | * all sizers to their max size and return.
|
| 114 | *
|
| 115 | * 5. If the layout space is less than the total size hint, distribute
|
| 116 | * the negative delta as follows:
|
| 117 | *
|
| 118 | * a. Shrink each sizer with a stretch factor greater than zero by
|
| 119 | * an amount proportional to the negative space and the sum of
|
| 120 | * stretch factors. If the sizer reaches its min size, remove
|
| 121 | * it and its stretch factor from the computation.
|
| 122 | *
|
| 123 | * b. If after adjusting all stretch sizers there remains negative
|
| 124 | * space, distribute the space equally among the sizers with a
|
| 125 | * stretch factor of zero. If a sizer reaches its min size,
|
| 126 | * remove it from the computation.
|
| 127 | *
|
| 128 | * 6. If the layout space is greater than the total size hint,
|
| 129 | * distribute the positive delta as follows:
|
| 130 | *
|
| 131 | * a. Expand each sizer with a stretch factor greater than zero by
|
| 132 | * an amount proportional to the postive space and the sum of
|
| 133 | * stretch factors. If the sizer reaches its max size, remove
|
| 134 | * it and its stretch factor from the computation.
|
| 135 | *
|
| 136 | * b. If after adjusting all stretch sizers there remains positive
|
| 137 | * space, distribute the space equally among the sizers with a
|
| 138 | * stretch factor of zero. If a sizer reaches its max size,
|
| 139 | * remove it from the computation.
|
| 140 | *
|
| 141 | * 7. return
|
| 142 | *
|
| 143 | * @param sizers - The sizers for a particular layout line.
|
| 144 | *
|
| 145 | * @param space - The available layout space for the sizers.
|
| 146 | *
|
| 147 | * @returns The delta between the provided available space and the
|
| 148 | * actual consumed space. This value will be zero if the sizers
|
| 149 | * can be adjusted to fit, negative if the available space is too
|
| 150 | * small, and positive if the available space is too large.
|
| 151 | *
|
| 152 | * #### Notes
|
| 153 | * The [[size]] of each sizer is updated with the computed size.
|
| 154 | *
|
| 155 | * This function can be called at any time to recompute the layout for
|
| 156 | * an existing sequence of sizers. The previously computed results will
|
| 157 | * have no effect on the new output. It is therefore not necessary to
|
| 158 | * create new sizer objects on each resize event.
|
| 159 | */
|
| 160 | function calc(sizers: ArrayLike<BoxSizer>, space: number): number;
|
| 161 | /**
|
| 162 | * Adjust a sizer by a delta and update its neighbors accordingly.
|
| 163 | *
|
| 164 | * @param sizers - The sizers which should be adjusted.
|
| 165 | *
|
| 166 | * @param index - The index of the sizer to grow.
|
| 167 | *
|
| 168 | * @param delta - The amount to adjust the sizer, positive or negative.
|
| 169 | *
|
| 170 | * #### Notes
|
| 171 | * This will adjust the indicated sizer by the specified amount, along
|
| 172 | * with the sizes of the appropriate neighbors, subject to the limits
|
| 173 | * specified by each of the sizers.
|
| 174 | *
|
| 175 | * This is useful when implementing box layouts where the boundaries
|
| 176 | * between the sizers are interactively adjustable by the user.
|
| 177 | */
|
| 178 | function adjust(sizers: ArrayLike<BoxSizer>, index: number, delta: number): void;
|
| 179 | }
|