DockPanel

Remarks

⚠ A panel is created once and moved thereafter, never rebuilt. That is what UiDocument.Reparent exists for and it is the whole reason docking is hard: a panel torn out of one group and dropped into another has to keep its scroll position, its selection, its focus and whatever the user has half-typed into it. A host that rebuilt the panel would pass every structural test and lose the user's work.

⚠ It scrolls vertically by default, and it does so itself rather than by holding a ScrollView. This is the same judgement DockGroupView records for its tab strip, one axis over: overflow: hidden in the theme is the draw list's clip stack, OffsetY is a post-layout translation, and between them that is the whole of scrolling. What a ScrollView would add here is a box — and a box is the thing this must not add. Every panel's content is laid out against the panel today, so height: 34% on a profiler's grid, height: 49% on a quad viewport and width: 100% on a GPU timeline's lanes all resolve against it. Interposing scroll-content — which is align-self: flex-start with a shrink-to-fit height — re-parents every one of those percentages onto a box whose size is what the content wanted, which is circular. That is not a hypothetical: StandardFrameView carries a written post-mortem of exactly that failure, measured on device three times.

⚠ The second reason is that a wrapper could not have been transparent anyway. A panel's whole compatibility surface is Action<DockPanel> and every builder fills it with panel.Add<T>() — which is Add``1, not virtual, straight to UiDocument.Create. Worse, a couple of dozen asset editors are handed the panel typed as a bare UiElement through IAssetEditorFactory.CreateView, so even an override on this type would be bypassed by every one of them. A redirect could not be made transparent; it could only be made inconsistently transparent, which is worse than not doing it. Nothing here moves a builder's children: Children means exactly what it always meant.

The price, said out loud. Once a panel has overflowed it grows one extra child, the ScrollBar, appended after the content and absolutely positioned by the theme. It is created on first overflow rather than at construction so that a panel whose content fits — and a panel that has opted out — has children that are content and nothing else. Code that walks a panel's children should skip anything it did not put there, which is the rule Control.Part already states for every other control in the set.

Vertical only. Horizontal scrolling is a thing a panel asks for by putting something horizontally scrollable in itself; a panel that grew a second bar because one label was too long would spend a row of chrome on a problem wrapping already solves.

Fields and properties (14)

• protected override string TagName

  The element name this type answers to when a caller does not choose one.

• protected override bool AcceptsFocus

  Whether the focus can rest on this kind of control at all.

• protected override AccessibleRole NativeRole
• public string Id

  What identifies it in a saved layout.

• public string? Title
• public bool CanClose
• public bool Scrolls
• public float ScrollTop

  How far down the content the panel is, in pixels.

• public float MaximumScroll

  How far down it can go.

• public bool Overflows

  Whether there is more content than the panel is showing.

• public ScrollBar? Bar

  The bar down the right, once there has been something to scroll.

• public static readonly UiPropertyKey TitleProperty

  Identity for Title.

• public static readonly UiPropertyKey CanCloseProperty

  Identity for CanClose.

• public static readonly UiPropertyKey ScrollsProperty

  Identity for Scrolls.

Methods (11)

• protected override void OnCreated()

  Builds whatever this element is made of, once, as it joins a document.

• protected override void OnRemoved()
• public static bool Fills(UiElement element)

  Says that an element fills its panel, so the panel must not scroll.

• public void WhenPressedIn(Action claim)

  Runs something when a pointer press lands anywhere in this panel.

• public void Scroll(float delta)

  Scrolls by a distance, clamped to what there is.

• public void ScrollTo(float offset)

  Scrolls to a position, clamped to what there is.

• public void Reveal(UiElement element)

  Scrolls until an element inside the panel is visible, if it is not already.

• public void Refresh()

  Brings the bar and the offset up to date with the content's size.

• public void ClearTitle()

  Unsets Title, so it takes its default or its ancestor's value again.

• public void ClearCanClose()

  Unsets CanClose, so it takes its default or its ancestor's value again.

• public void ClearScrolls()

  Unsets Scrolls, so it takes its default or its ancestor's value again.

Used by (72, showing 40)

• ShellHelloUi
• EditorShellSceneVixen.Benchmarks.Ui
• AccessibilityTreeTestsVixen.Ui.Controls.Advanced.Tests
• AccessibleNameLocalisationTestsVixen.Ui.Controls.Advanced.Tests
• AmbientAcrossDockingTestsVixen.Ui.Controls.Advanced.Tests
• DockPanelPressTestsVixen.Ui.Controls.Advanced.Tests
• DockPanelScrollTestsVixen.Ui.Controls.Advanced.Tests
• DockingHostVixen.Ui.Controls.Advanced
• DockingTestsVixen.Ui.Controls.Advanced.Tests
• DockingWindowTestsVixen.Ui.Controls.Advanced.Tests
• NestedTagTestsVixen.Ui.Controls.Advanced.Tests
• AgentDebuggerPanelTestsVixen.Editor.App.Tests
• AnimationClipEditorFactoryVixen.Editor.AssetEditors
• AnimationGraphEditorFactoryVixen.Editor.AssetEditors
• AudioMixerEditorFactoryVixen.Editor.AssetEditors
• BehaviorTreeEditorFactoryVixen.Editor.AssetEditors
• BlockoutModuleVixen.Editor.Blockout
• BuildSettingsTestsVixen.Editor.App.Tests
• ChromeFixtureVixen.Editor.Ui.Tests
• DiagnosticsModuleVixen.Editor.Diagnostics
• DiagnosticsPanelTestsVixen.Editor.App.Tests
• DockingWorkspaceVixen.Editor.Ui
• DropIntoSceneTestsVixen.Editor.App.Tests
• EditorAffordanceTestsVixen.Editor.App.Tests
• EditorApplicationVixen.Editor.App
• EditorModeTestsVixen.Editor.App.Tests
• EditorSessionVixen.Editor.Testing
• EditorShellVixen.Editor.Ui
• GridViewTestsVixen.Editor.App.Tests
• ImageViewBarWiringTestsVixen.Editor.Texturing.Tests
• InputDebugPanelTestsVixen.Editor.App.Tests
• LayerRowKeyTestsVixen.Editor.Texturing.Tests
• LayerStackBindingTestsVixen.Editor.Texturing.Tests
• LayerStackEditingTestsVixen.Editor.Texturing.Tests
• LayerStackKnobWidthTestsVixen.Editor.Texturing.Tests
• LayerStackPanelDeviceTestsVixen.Editor.Texturing.Tests
• LayerStackPanelTestsVixen.Editor.Texturing.Tests
• LayerStackThemeTestsVixen.Editor.Texturing.Tests
• LayerStackViewVixen.Editor.Texturing
• MarkupEditorFactoryVixen.Editor.AssetEditors