From f9685a0a468ece93c862b4c1d1fb8e48b18736ff Mon Sep 17 00:00:00 2001 From: Igor Sirotin Date: Fri, 28 Jul 2023 13:51:41 +0300 Subject: [PATCH] StatusScrollView usage docs (#11422) --- storybook/pages/CommunityTokenViewPage.qml | 2 +- storybook/pages/IntroPanelPage.qml | 4 +- storybook/pages/StatusScrollViewPage.qml | 136 +++++++++++++----- storybook/src/Models/ModelsData.qml | 6 +- .../src/StatusQ/Core/StatusScrollView.qml | 2 +- ui/StatusQ/src/contributing.md | 113 +++++++++++++++ 6 files changed, 217 insertions(+), 46 deletions(-) diff --git a/storybook/pages/CommunityTokenViewPage.qml b/storybook/pages/CommunityTokenViewPage.qml index 14e4173e87..600356d8ff 100644 --- a/storybook/pages/CommunityTokenViewPage.qml +++ b/storybook/pages/CommunityTokenViewPage.qml @@ -262,7 +262,7 @@ SplitView { Layout.fillWidth: true - text: ModelsData.descriptions.medium + text: ModelsData.descriptions.mediumLoremIpsum } Label { diff --git a/storybook/pages/IntroPanelPage.qml b/storybook/pages/IntroPanelPage.qml index d8e35ae196..6a012211b2 100644 --- a/storybook/pages/IntroPanelPage.qml +++ b/storybook/pages/IntroPanelPage.qml @@ -68,7 +68,7 @@ SplitView { id: addRadioButton readonly property string textContent: - ModelsData.descriptions._short_ + ModelsData.descriptions.shortLoremIpsum text: "Short text" checked: true @@ -77,7 +77,7 @@ SplitView { id: updateRadioButton readonly property string textContent: - ModelsData.descriptions.medium + ModelsData.descriptions.mediumLoremIpsum text: "Long text" } diff --git a/storybook/pages/StatusScrollViewPage.qml b/storybook/pages/StatusScrollViewPage.qml index 2bd8098a35..5ba797335b 100644 --- a/storybook/pages/StatusScrollViewPage.qml +++ b/storybook/pages/StatusScrollViewPage.qml @@ -19,8 +19,9 @@ SplitView { QtObject { id: d - property string longText: "facilisis magna etiam tempor orci eu lobortis elementum nibh tellus molestie nunc non blandit massa enim nec dui nunc mattis enim ut tellus elementum sagittis vitae et leo duis ut diam quam nulla porttitor massa id neque aliquam vestibulum morbi blandit cursus risus at ultrices mi tempus imperdiet nulla malesuada pellentesque elit eget gravida cum sociis natoque penatibus et magnis dis parturient montes nascetur ridiculus mus mauris vitae ultricies leo integer malesuada nunc vel risus commodo viverra maecenas accumsan lacus vel facilisis volutpat est velit egestas dui id ornare arcu odio ut sem nulla pharetra diam sit amet nisl suscipit adipiscing bibendum est ultricies integer quis auctor elit sed vulputate mi sit amet mauris commodo quis imperdiet massa tincidunt nunc pulvinar sapien et ligula ullamcorper malesuada proin libero nunc consequat interdum varius sit amet mattis vulputate enim nulla aliquet porttitor lacus luctus accumsan tortor posuere ac ut consequat semper viverra nam libero justo laoreet sit amet cursus sit amet dictum sit amet justo donec enim diam vulputate ut pharetra sit amet aliquam id diam maecenas ultricies mi eget mauris pharetra et ultrices neque ornare aenean euismod elementum nisi quis eleifend quam adipiscing vitae proin sagittis nisl rhoncus mattis rhoncus urna neque viverra justo nec ultrices dui sapien eget mi proin sed libero enim sed faucibus turpis in eu mi bibendum neque egestas congue quisque egestas diam in arcu cursus euismod quis viverra nibh cras pulvinar mattis nunc sed blandit libero volutpat sed cras ornare arcu dui vivamus arcu felis bibendum ut tristique et egestas quis ipsum suspendisse ultrices gravida dictum fusce ut placerat orci nulla pellentesque dignissim enim sit amet venenatis urna cursus eget nunc scelerisque viverra mauris in aliquam sem fringilla ut morbi tincidunt augue interdum velit euismod in pellentesque massa placerat duis ultricies lacus sed turpis tincidunt id aliquet risus feugiat in ante metus dictum at tempor commodo ullamcorper a lacus vestibulum sed arcu non odio euismod lacinia at quis risus sed vulputate odio ut enim blandit volutpat maecenas volutpat blandit aliquam etiam erat velit scelerisque in dictum non consectetur a erat nam at lectus urna duis convallis convallis tellus id interdum velit laoreet id donec ultrices tincidunt arcu non sodales neque sodales ut etiam sit amet nisl purus in mollis nunc sed id semper risus in hendrerit gravida rutrum quisque non tellus orci ac auctor augue mauris augue neque gravida in fermentum et sollicitudin ac orci phasellus" + property string longText: ModelsData.descriptions.longLoremIpsum.repeat(5) readonly property bool isRectangle: contentComboBox.currentValue === "rectangle" + readonly property bool isImage: contentComboBox.currentValue === "image" readonly property bool isText: contentComboBox.currentValue === "text" } @@ -28,41 +29,73 @@ SplitView { orientation: Qt.Vertical SplitView.fillWidth: true - StatusScrollView { - id: scrolView1 + Item { SplitView.fillWidth: true SplitView.fillHeight: true - contentWidth: widthFillCheckBox.checked ? availableWidth : widthSpinBox.value - - visible: d.isRectangle Rectangle { - gradient: Gradient.NightFade - implicitWidth: widthFillCheckBox.checked ? scrolView1.availableWidth : widthSpinBox.value - implicitHeight: heightFillCheckBox.checked ? scrolView1.availableHeight : heightSpinBox.value - } - } + anchors.centerIn: parent + width: 600 + height: 600 - StatusScrollView { - id: scrollView2 - SplitView.fillWidth: true - SplitView.fillHeight: true - contentWidth: widthFillCheckBox.checked ? availableWidth : widthSpinBox.value + border.color: "black" + border.width: 1 - visible: d.isText + StatusScrollView { + id: scrolView1 + anchors.fill: parent + anchors.margins: 1 + contentWidth: widthFillCheckBox.checked ? availableWidth : widthSpinBox.value - Text { - width: widthFillCheckBox.checked ? scrollView2.availableWidth : widthSpinBox.value - wrapMode: Text.WrapAnywhere - text: d.longText + visible: d.isRectangle + + Rectangle { + gradient: Gradient.NightFade + implicitWidth: widthFillCheckBox.checked ? scrolView1.availableWidth : widthSpinBox.value + implicitHeight: heightFillCheckBox.checked ? scrolView1.availableHeight : heightSpinBox.value + } + } + + StatusScrollView { + id: scrollView3 + anchors.fill: parent + anchors.margins: 1 + contentWidth: widthFillCheckBox.checked ? availableWidth : widthSpinBox.value + + visible: d.isImage + + Image { + width: widthFillCheckBox.checked ? scrollView3.availableWidth : widthSpinBox.value + source: "https://placekitten.com/900/900" + } + } + + StatusScrollView { + id: scrollView2 + anchors.fill: parent + anchors.margins: 1 + contentWidth: widthFillCheckBox.checked ? availableWidth : widthSpinBox.value + + visible: d.isText + + Text { + width: widthFillCheckBox.checked ? scrollView2.availableWidth : widthSpinBox.value + wrapMode: Text.WrapAnywhere + text: d.longText + } + } } } StatusModal { id: modal - anchors.centerIn: parent + anchors.centerIn: parent padding: 0 + destroyOnClose: false + + headerSettings.title: "StatusScrollView" + showFooter: false StatusScrollView { id: modalScrollView @@ -83,6 +116,10 @@ SplitView { anchors.centerIn: parent padding: 16 + destroyOnClose: false + + headerSettings.title: "StatusScrollView (detached scrollbars)" + showFooter: false ColumnLayout { anchors.fill: parent @@ -137,23 +174,47 @@ SplitView { logsView.logText: logs.logText - RowLayout { - anchors.centerIn: parent + ColumnLayout { + Layout.fillHeight: true + Layout.fillWidth: true - Button { - Layout.fillHeight: true - text: "StatusModal" - onClicked: { - modal.open() + RowLayout { + Layout.fillWidth: true + + Button { + Layout.fillHeight: true + text: "StatusModal" + onClicked: { + modal.open() + } + } + Button { + Layout.fillHeight: true + text: "StatusModal\n(detached bar)" + onClicked: { + modal2.open() + } } } - Button { - Layout.fillHeight: true - text: "StatusModal\n(detached bar)" - onClicked: { - modal2.open() + + Label { + id: slidesLabel + Layout.fillWidth: true + wrapMode: Text.WordWrap + textFormat: Text.MarkdownText + text: "Please, read our [contributing guide](https://github.com/status-im/status-desktop/blob/master/ui/StatusQ/src/contributing.md#StatusScrollView) (or checkout a [presenation](https://docs.google.com/presentation/d/1ZZeg9j2fZMV-iHreu_Wsl1u6D9POH7SlUO78ZXNj-AI)) about using `StatusScrollView`" + onLinkActivated: (link) => { + Qt.openUrlExternally(link) + } + + MouseArea { + anchors.fill: parent + cursorShape: Qt.PointingHandCursor + visible: !!slidesLabel.hoveredLink + acceptedButtons: Qt.NoButton } } + } } } @@ -174,7 +235,7 @@ SplitView { Layout.columnSpan: 2 Layout.fillWidth: true Layout.bottomMargin: 20 - model: ["rectangle", "text"] + model: ["image", "rectangle", "text"] } Label { @@ -182,7 +243,6 @@ SplitView { } CheckBox { id: widthFillCheckBox - checked: true } Label { @@ -193,7 +253,7 @@ SplitView { enabled: !widthFillCheckBox.checked editable: true height: 30 - value: 500 + value: 900 stepSize: 100 from: 0 to: 1000 @@ -205,7 +265,6 @@ SplitView { CheckBox { id: heightFillCheckBox checked: false - enabled: d.isRectangle } Label { @@ -214,7 +273,6 @@ SplitView { SpinBox { id: heightSpinBox editable: true - enabled: d.isRectangle height: 30 value: 800 stepSize: 100 diff --git a/storybook/src/Models/ModelsData.qml b/storybook/src/Models/ModelsData.qml index e810820ef2..8a798e470c 100644 --- a/storybook/src/Models/ModelsData.qml +++ b/storybook/src/Models/ModelsData.qml @@ -75,9 +75,9 @@ QtObject { } readonly property QtObject descriptions: QtObject { - readonly property string _short_: "Lorem Ipsum is simply dummy text." - readonly property string medium: "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book." - readonly property string _long: "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum." + readonly property string shortLoremIpsum: "Lorem Ipsum is simply dummy text." + readonly property string mediumLoremIpsum: "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book." + readonly property string longLoremIpsum: "Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum." readonly property string ownerTokenInfo: "In order to Mint, Import and Airdrop community tokens, you first need to mint your Owner token which will give you permissions to access the token management features for your community." readonly property string airdropInfo: "You can Airdrop tokens to deserving Community members or to give individuals token-based permissions." } diff --git a/ui/StatusQ/src/StatusQ/Core/StatusScrollView.qml b/ui/StatusQ/src/StatusQ/Core/StatusScrollView.qml index 64521aea5a..ff90e10adc 100644 --- a/ui/StatusQ/src/StatusQ/Core/StatusScrollView.qml +++ b/ui/StatusQ/src/StatusQ/Core/StatusScrollView.qml @@ -88,7 +88,7 @@ import StatusQ.Core.Theme 0.1 2. Apply paddings of the popup and make `StatusScrollView` scroll bars non-attached - Use when `StatusScrollView`/`StatusListView` is not a direct child of `contentItem`, or it's not the only child. + Use when `StatusScrollView`/`StatusListView` is not a direct child of `contentItem`, or it's not the only child. Though this requires more coding and custom wrappers, the result is very neat. All popup contents are aligned to given paddings, but the scroll bar doesn't overlay diff --git a/ui/StatusQ/src/contributing.md b/ui/StatusQ/src/contributing.md index 80844bb216..456c04b506 100644 --- a/ui/StatusQ/src/contributing.md +++ b/ui/StatusQ/src/contributing.md @@ -148,6 +148,119 @@ Popup { } ``` +### StatusScrollView + +> A presenation on using `StatusScrollView` can be found [here](https://docs.google.com/presentation/d/1ZZeg9j2fZMV-iHreu_Wsl1u6D9POH7SlUO78ZXNj-AI). + +#### Basic usage + +```qml +StatusScrollView { + anchors.fill: parent // Give the SceollView some size + + // - No need to specify contentWidth and contentHeight. + // For a single child item it will be calculated automatically from implicit size of the item. + // The item must have implicit size specified. Not width/height. + + Image { + source: "https://placekitten.com/400/600" + } +} +``` + +#### Filling width + +```qml +StatusScrollView { + id: scrollView + anchors.fill: parent + contentWidth: availableWidth // Bind ScrollView.contentWidth to availableWidth + + ColumnLayout { + width: scrollView.availableWidth // Bind content width to availableWidth + } +} +``` + +#### In a popup + +1. Use when `StatusScrollView` is the _only direct child_ of popup's `contentItem`. +2. If you have other items outside the scroll view, you will have to manually apply paddings to them as well. + +```qml +StatusModal { + padding: 0 // Use paddings of StatusScrollView + + StatusScrolLView { + id: scrollView + + anchors.fill: parent + implicitWidth: 400 + contentWidth: availableWidth + padding: 16 // Use padding of StatusScrollView, not StatusModal + + Text { + width: scrollView.availableWidth + wrapMode: Text.WrapAnywhere + text: "long text here" + } + } +} + +``` + +#### Deep in a popup + +1. Use when `StatusScrollView` or `StatusListView` is not a direct child of `contentItem`, or it's not the only child. +2. All popup contents are aligned to given paddings, but the scroll bar doesn't overlay the content and is positioned right inside the padding. + +```qml +StatusModal { + padding: 16 // Use popup paddings + + ColumnLayout { + anchors.fill: parent + + Text { + Layout.fillWidth: true + text: "This header is fixed and not scrollable" + } + + Item { + id: scrollViewWrapper + + Layout.fillWidth: true + Layout.fillHeight: true + implicitWidth: scrollView.implicitWidth + implicitHeight: scrollView.implicitHeight + + StatusScrollView { + id: scrollView + + anchors.fill: parent + contentWidth: availableWidth + padding: 0 // Use popup paddings + + // Detach scrollbar + ScrollBar.vertical: StatusScrollBar { + parent: scrollViewWrapper + anchors.top: scrollView.top + anchors.bottom: scrollView.bottom + anchors.left: scrollView.right + anchors.leftMargin: 1 + } + + Text { + width: scrollView.availableWidth + wrapMode: Text.WrapAnywhere + text: "long scrollable text here" + } + } + } + } +} +``` + ## Testing Test in isolation