Add ConstrainedBox and Attached Shadow docs #567
Conversation
michael-hawker
force-pushed
the
new-controls-7dot1
branch
from
b9bb8e4 to
5c6b70e
Compare
|
Docs Build status updates of commit b9bb8e4: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
Docs Build status updates of commit 5c6b70e: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
Docs Build status updates of commit 27d0677:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/helpers/AttachedShadows.md | View | Details | |
| docs/.template.md | ✅Succeeded | ||
| docs/controls/ConstrainedBox.md | ✅Succeeded | View | |
| docs/controls/DropShadowPanel.md | ✅Succeeded | View | |
| docs/toc.md | ✅Succeeded | View |
docs/helpers/AttachedShadows.md
- Line 64, Column 1: [Warning-file-not-found]
Invalid file link: '../resources/images/filename.png'. - Line 69, Column 1: [Warning-file-not-found]
Invalid file link: 'sample-page-link'. - Line 73, Column 3: [Warning-file-not-found]
Invalid file link: 'source-code-link'. - Line 79, Column 3: [Warning-file-not-found]
Invalid file link: 'link'. - Line 80, Column 3: [Warning-file-not-found]
Invalid file link: 'link'.
For more details, please refer to the build report.
If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.
Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.
Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the docs.microsoft.com contributor guides
- Post your question in the Docs support channel
michael-hawker
force-pushed
the
new-controls-7dot1
branch
from
27d0677 to
4e01c16
Compare
|
Docs Build status updates of commit 4e01c16:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/helpers/AttachedShadows.md | View | Details | |
| docs/.template.md | ✅Succeeded | ||
| docs/controls/ConstrainedBox.md | ✅Succeeded | View | |
| docs/controls/DropShadowPanel.md | ✅Succeeded | View | |
| docs/toc.md | ✅Succeeded | View |
docs/helpers/AttachedShadows.md
- Line 66, Column 1: [Warning-file-not-found]
Invalid file link: '../resources/images/filename.png'. - Line 70, Column 1: [Warning-file-not-found]
Invalid file link: 'sample-page-link'. - Line 74, Column 3: [Warning-file-not-found]
Invalid file link: 'source-code-link'. - Line 78, Column 3: [Warning-file-not-found]
Invalid file link: 'link'. - Line 79, Column 3: [Warning-file-not-found]
Invalid file link: 'link'.
For more details, please refer to the build report.
If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.
Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.
Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the docs.microsoft.com contributor guides
- Post your question in the Docs support channel
michael-hawker
force-pushed
the
new-controls-7dot1
branch
from
4e01c16 to
22b0a75
Compare
|
Docs Build status updates of commit 22b0a75:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| docs/helpers/AttachedShadows.md | View | Details | |
| docs/.template.md | ✅Succeeded | ||
| docs/controls/ConstrainedBox.md | ✅Succeeded | View | |
| docs/controls/DropShadowPanel.md | ✅Succeeded | View | |
| docs/toc.md | ✅Succeeded | View |
docs/helpers/AttachedShadows.md
- Line 66, Column 1: [Warning-file-not-found]
Invalid file link: '../resources/images/filename.png'. - Line 70, Column 1: [Warning-file-not-found]
Invalid file link: 'sample-page-link'. - Line 74, Column 3: [Warning-file-not-found]
Invalid file link: 'source-code-link'. - Line 78, Column 3: [Warning-file-not-found]
Invalid file link: 'link'. - Line 79, Column 3: [Warning-file-not-found]
Invalid file link: 'link'.
For more details, please refer to the build report.
If you see build warnings/errors with permission issues, it might be due to single sign-on (SSO) enabled on Microsoft's GitHub organizations. Please follow instructions here to re-authorize your GitHub account to Docs Build.
Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report.
Note: Your PR may contain errors or warnings unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
For any questions, please:
- Try searching the docs.microsoft.com contributor guides
- Post your question in the Docs support channel
michael-hawker
force-pushed
the
new-controls-7dot1
branch
from
22b0a75 to
d5ebc03
Compare
michael-hawker
force-pushed
the
new-controls-7dot1
branch
from
d5ebc03 to
cad8e6b
Compare
|
Docs Build status updates of commit d5ebc03: ✅ Validation status: passed
docs/helpers/AttachedShadows.md
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
michael-hawker
changed the title
|
Docs Build status updates of commit cad8e6b: ✅ Validation status: passed
docs/helpers/AttachedShadows.md
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
|
Docs Build status updates of commit 1d607d8: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
docs/controls/ConstrainedBox.md
Outdated
|
|
||
| # ConstrainedBox | ||
|
|
||
| The [ConstrainedBox](/dotnet/api/microsoft.toolkit.uwp.ui.controls.constrianedbox) is a simple `FrameworkElement` content decorator control which allows the developer to constrain its child content one or more various properties including aspect ratio, scale, and aligning to a multiple. |
There was a problem hiding this comment.
Also, " ... control which allows the developer to constrain its child content to one or more various properties ..."
docs/controls/ConstrainedBox.md
Outdated
| > [!NOTE] | ||
| > For technical reasons this control inherits from `ContentPresenter`; however, it should be treated as a `FrameworkElement` and its border and template properties should not be used for compatibility in the future when it can inherit from FrameworkElement directly. | ||
|
|
||
| > **Platform APIs:** [`ConstrainedBox`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.constrianedbox), [`AspectRatio`](/dotnet/api/microsoft.toolkit.uwp.ui.controls.aspectratio) |
docs/controls/ConstrainedBox.md
Outdated
|
|
||
| 2. `MultipleX`/`MultipleY`: The multiple values allow a developer to snap the layout size of the child to a specific multiple value. For instance, by providing a value of 4, you would ensure the child element is closest to the size of 16, 20, 24, etc... The floor is taken so the child element is always smaller within the bounds of its parent. By default this value is not set so that no extra layout rounding occurs. | ||
|
|
||
| 3. `AspectRatio`: The aspect ratio can be provided by a double value or a colon separated aspect, e.g. "16:9" and will restrict the layout of the child element to that available space. Therefore if you stretch your child element you can ensure it maintains the desired aspect ratio. By default, no aspect ratio constraint is applied. |
There was a problem hiding this comment.
Need to either surround the whole e.g. with parenthesis, or else put a comma after the e.g. example (... e.g. "16:9", in this case)
docs/controls/ConstrainedBox.md
Outdated
|
|
||
| 3. `AspectRatio`: The aspect ratio can be provided by a double value or a colon separated aspect, e.g. "16:9" and will restrict the layout of the child element to that available space. Therefore if you stretch your child element you can ensure it maintains the desired aspect ratio. By default, no aspect ratio constraint is applied. | ||
|
|
||
| If a `ConstrainedBox` is placed in a container which doesn't restrict its size in both the horizontal and vertical directions, it will try and determine its constraints based on the desired size of its child element. If only one direction has infinite size, the control will attempt to use the fixed dimension to measure all constraints against. |
There was a problem hiding this comment.
... try to determine its constraints ..., unless your audience is predominately British, in which case and is acceptable
docs/helpers/AttachedShadows.md
Outdated
|
|
||
| ## Introduction | ||
|
|
||
| There are two types of attached shadows available today, the `AttachedCardShadow` and the `AttachedDropShadow`. It is recommended to use the `AttachedCardShadow` where possible, if you don't mind the dependency on Win2D. The `AttachedCardShadow` provides an easier to use experience that is more performant and easier to apply across an entire set of elements, assuming those elements are rounded-rectangular in shape. Whereas, the `AttachedDropShadow` provides masking support and can be leveraged in any UWP app without adding an extra dependency. |
There was a problem hiding this comment.
Suggest dropping the 'Whereas' in " ... Whereas, the AttachedDropShadow provides masking support ..."
docs/helpers/AttachedShadows.md
Outdated
| > [!div class="nextstepaction"] | ||
| > [Try it in the sample app](uwpct://controls?sample=attachedcardshadow%20%28win2d%29) | ||
|
|
||
| The great benefit to the `AttachedCardShadow` is that no extra surface or element is required to add the shadow. This reduces the complexity required on development and allows shadows to easily be added at any point in the development process. It also supports elements which are transparent without seeing the shadow behind them! |
There was a problem hiding this comment.
Replace the on with in, as in "... This reduces the complexity required in development and ...,"
There was a problem hiding this comment.
Also, for the last sentence in this paragraph, something more like "It also supports transparent elements, which won't see a shadow behind them!"
docs/helpers/AttachedShadows.md
Outdated
|
|
||
| ### Remarks | ||
|
|
||
| While `DropShadowPanel` encapsulated the complexities of adding a shadow, it added a lot of depth and complexity to the visual tree. `AttachedDropShadow` instead requires that you provide the surface where the shadows should be cast, such as a common backdrop element. This means that each shadow can use the same shared surface rather than creating its own backdrop element for each shadow (like `DropShadowPanel` did). This slight trade-off for ease-of-use is gained in performance. However, it does mean it may not be as flexible for certain use cases with manipulation of an element. In those cases we recommend to try and use `AttachedCardShadow` instead or wrapping an element and its backdrop in a custom control. |
There was a problem hiding this comment.
... This slight trade-off for ease-of-use is a gain in performance. ...
docs/helpers/AttachedShadows.md
Outdated
| > **Platform APIs:** [`BlurRadiusDropShadowAnimation`](/dotnet.api/microsoft.toolkit.uwp.ui.animations.blurradiusdropshadowanimation), [`ColorDropShadowAnimation`](/dotnet.api/microsoft.toolkit.uwp.ui.animations.colordropshadowanimation), [`OffsetDropShadowAnimation`](/dotnet.api/microsoft.toolkit.uwp.ui.animations.offsetdropshadowanimation), [`OpacityDropShadowAnimation`](/dotnet.api/microsoft.toolkit.uwp.ui.animations.opacitydropshadowanimation) | ||
|
|
||
| > [!NOTE] | ||
| > `AttachedCardShadow` has better support for animations which involve translation of the element with the shadow. If animating an `AttachedDropShadow` it is best to only animate the shadow itself vs. moving the element it is attached to. This can cause the shadow and element to be desynchronized. |
There was a problem hiding this comment.
Suggest "... support for animations which involve translation of the element along with the shadow ..."
- or -
"... support for animations which involve translation of both the element and the shadow combined ..."
|
Docs Build status updates of commit 4eea85f: ✅ Validation status: passed
For more details, please refer to the build report. Note: Broken links written as relative paths are included in the above build report. For broken links written as absolute paths or external URLs, see the broken link report. For any questions, please:
|
Docs for Toolkit PR #4104 and #4179
What changes to the docs does this PR provide?
Adds new docs for the
ConstrainedBox,AttachedCardShadow, andAttachedDropShadowcontrols.PR Checklist
Please check if your PR fulfills the following requirements:
devfor new features,masterfor typos/improvements)Other information