UIView: directionalLayoutMargins property
The directionalLayoutMargins property is the view's layout margins: how far content should be from the view's four edges. Left and right are determined by text direction.
Value
An NSDirectionalEdgeInsets, in pt. The fields are top, leading, bottom, and trailing.
- Readable and writable.
- The default is
(8, 8, 8, 8). leadingis the side where text starts, andtrailingis the side where text ends. In English and Chineseleadingis on the left.- It is the same data as
layoutMargins: write one and the other changes accordingly. Prefer this one; the interface then swaps left and right automatically in right-to-left languages. - It doesn't inset subviews automatically. Only two things use it: constraints aligned to
layoutMarginsGuide, and aUIStackViewwithisLayoutMarginsRelativeArrangementturned on. - The value that reads back isn't necessarily the value written: when
insetsLayoutMarginsFromSafeAreaistrue(the default), the system adds the safe area to the edges where the view extends outside the safe area. If you write 16 pt and the top safe area is 68 pt, the top margin reads back as 84 pt. - A view controller's root view has a system-defined minimum margin; values written below the minimum read back as the minimum. Not verified in the simulator. This limit currently can't be turned off.
- On write you can pass an
NSDirectionalEdgeInsetsor a plain object with all four fields present. The fields of the struct that reads back are read-only, and each read returns a new object. See Structs. - No change notification. The system changes it in two cases: the safe area changes, or
preservesSuperviewLayoutMarginsis on and the superview's layout margins change. There is currently no way to find out about either change.
Invalid values
- Not an object: throws
TypeError: directionalLayoutMargins needs an object with all of: top, leading, bottom, trailing. - A field is missing or doesn't convert to a finite number: throws
TypeError: directionalLayoutMargins is missing …, or it is not a finite number, with the missing field name in the middle. - On error the property keeps its previous value. Field values are converted with
Number(), so'10'works.
Examples
js
const box = new UIView();
box.directionalLayoutMargins = new NSDirectionalEdgeInsets(1, 2, 3, 4);
console.log(String(box.layoutMargins));
box.directionalLayoutMargins = { top: 12, leading: 20, bottom: 12, trailing: 20 };
console.log(String(box.directionalLayoutMargins));Result: When the language is left-to-right, prints UIEdgeInsets(1, 2, 3, 4), then NSDirectionalEdgeInsets(12, 20, 12, 20).
Corresponding iOS API
UIView.directionalLayoutMargins. NSDirectionalEdgeInsetsMake(8, 16, 8, 16) is written as new NSDirectionalEdgeInsets(8, 16, 8, 16).