Documentation review

General

• Add more GIFs
  • Make sure the first frame serves as a good screenshot https://codereview.qt-project.org/#/c/175521/
  • Try to match the first frame of the GIF with a snippet next to it
  • Can replace the image tables of controls in different states in many places
• Double the check the brief descriptions.
  • Elaborate on the "A foo control" ones. https://codereview.qt-project.org/#/c/175518/
  • Make them all follow the same format. https://codereview.qt-project.org/#/c/175518/
• Attached properties
  • Users conceive them confusing. Add short examples to give an idea how to use.

ApplicationWindow

• Customizing ApplicationWindow
  • Image or gradient as a background https://codereview.qt-project.org/#/c/172783/
• Detailed description
  • Link to Customizing ApplicationWindow https://codereview.qt-project.org/#/c/172783/
• ApplicationWindow::background
  • Mention that ApplicationWindow::background is only useful for images/gradients etc. Window::color is better for solid colors https://codereview.qt-project.org/#/c/172783/
  • Link to Customizing ApplicationWindow https://codereview.qt-project.org/#/c/172783/
• ApplicationWindow::contentData
  • Elaborate. Copy parts of Window::data? https://codereview.qt-project.org/#/c/172783/
• ApplicationWindow::contentItem
  • What is the purpose, or what is it useful for?
  • Always stacked below the header, footer, and the overlay of course https://codereview.qt-project.org/#/c/172783/
• ApplicationWindow::footer, header
  • Add a snippet containing ToolBar (share with Page?) https://codereview.qt-project.org/#/c/175379/
• ApplicationWindow::overlay
  • Missing pressed() and released() signals https://codereview.qt-project.org/#/c/172783/
  • An example snippet with some “static” / non-popup overlay content
• Attached properties
  • Examples https://codereview.qt-project.org/#/c/175379/

BusyIndicator

• Detailed description
  • Should we have any tips when to use BusyIndicator vs. indeterminate ProgressBar? https://codereview.qt-project.org/#/c/175442/

Button

• Button::autoRepeat
  • Fix pressed(), released() and clicked() to be presented as links https://codereview.qt-project.org/#/c/171373/
• Button::checkable
  • Elaborate. “A checkable button toggles between checked (on) and unchecked (off) when the user...” https://codereview.qt-project.org/#/c/171373/
  • See also CheckBox, Switch? https://codereview.qt-project.org/#/c/171373/
  • Link to AbstractButton::checked https://codereview.qt-project.org/#/c/171373/
• Button::flat & highlighted
  • Screenshots would be nice https://codereview.qt-project.org/#/c/172469/

CheckBox

• Detailed description
  • Replace state images with a GIF https://codereview.qt-project.org/#/c/172517/
  • Could be helpful mention something that basically the whole API is inherited from AbstractButton. https://codereview.qt-project.org/#/c/171365/
  • Mention CheckDelegate, explain the difference between the two, and link to CheckDelegate. https://codereview.qt-project.org/#/c/171365/
• CheckBox::tristate
  • A screenshot of a tri-state checkbox? https://codereview.qt-project.org/#/c/172517/

CheckDelegate

• Detailed description
  • Could be helpful mention something that basically the whole API is inherited from ItemDelegate and AbstractButton. https://codereview.qt-project.org/#/c/171363/
  • Mention CheckBox, explain the difference between the two, and link to CheckBox. https://codereview.qt-project.org/#/c/171363/
• CheckDelegate::tristate
  • A screenshot of a tri-state checkbox? https://codereview.qt-project.org/#/c/173067/

ComboBox

• Detailed description
  • Fix the screenshot to not have elided items https://codereview.qt-project.org/#/c/173244/
• ComboBox::currentIndex
  • Link to highlightedIndex https://codereview.qt-project.org/#/c/173244/
• ComboBox::delegate
  • AbstractButton works out of the box https://codereview.qt-project.org/#/c/173244/
  • With other types, have to close the popup by hand https://codereview.qt-project.org/#/c/173244/
• ComboBox::highlightedIndex
  • It is the highlighted item in the popup, -1 when the popup is closed https://codereview.qt-project.org/#/c/173244/
  • When a highlighted item is activated, it becomes the current index https://codereview.qt-project.org/#/c/173244/
• ComboBox::indicator
  • Link to Customizing ComboBox https://codereview.qt-project.org/#/c/173244/
• ComboBox::popup
  • Mention that it's possible to open or close the popup manually, for instance https://codereview.qt-project.org/#/c/173244/
• ComboBox::pressed
  • Does it stay pressed when the popup is open? I think so, but should be clarified... https://codereview.qt-project.org/#/c/173244/
• ComboBox::textRole
  • When the model has multiple roles, ComboBox needs to know which one to use https://codereview.qt-project.org/#/c/173244/
• ComboBox::activated(int index) & :highlighted(int index)
  • Elaborate. Activating means selecting an item that the popup closes, or selecting an item with up/down arrows while its closed. The current index changes. Highlighting an item doesn't select/activate https://codereview.qt-project.org/#/c/173244/
• ComboBox::incrementCurrentIndex() & decrementCurrentIndex()
  • Typo: "or the highlighted index if the popup list when it is visible." https://codereview.qt-project.org/#/c/173244/

Control

• Detailed description
  • Explain the diagram https://codereview.qt-project.org/#/c/171463/
  • Give a linkable title for the diagram https://codereview.qt-project.org/#/c/171463/
  • Add "Control", "width" and "height" to the diagram https://codereview.qt-project.org/#/c/171463/
• Control::availableWidth, availableHeight
  • Link to the diagram https://codereview.qt-project.org/#/c/171477/
  • Elaborate. The width/height available for content. Horizontal/vertical padding deducted from the total width/height. https://codereview.qt-project.org/#/c/171484
• Control::background
  • Example snippet https://codereview.qt-project.org/#/c/171569/
  • Notice that most controls use the implicit size of the background item to calculate the implicit size of the control itself. If you replace the background with a custom one, you should also consider providing a sensible implicit size for it (unless it's eg. Image that already calculates its implicit size). https://codereview.qt-project.org/#/c/171484/
• Control::contentItem
  • The content item is resized within the paddings.
  • Notice that most controls use the implicit size of the content item to calculate the implicit size of the control itself. If you replace the content item with a custom one, you should also consider providing a sensible implicit size for it (unless it's eg. Text that already calculates its implicit size). https://codereview.qt-project.org/#/c/171484/
  • Example snippet https://codereview.qt-project.org/#/c/171569/
• Control::font
  • Example snippet with font inheritance https://codereview.qt-project.org/#/c/171569/
• Control::padding, topPadding, leftPadding, rightPadding, bottomPadding
  • Link to the diagram https://codereview.qt-project.org/#/c/171477/
  • Elaborate. These are used to control the geometry of the content item. https://codereview.qt-project.org/#/c/171484/
• Control::mirrored
  • But when is the visual layout direction is right-to-left? RTL locale or LayoutMirroring.enabled. https://codereview.qt-project.org/#/c/171484/
• Control::spacing
  • Elaborate. Typically used by controls that have multiple or repetitive building blocks. https://codereview.qt-project.org/#/c/171484
• Control::wheelEnabled
  • Explain that for example a Slider that handles wheel events would conflict with a Flickable handling wheel events. Wheel scrolling the flickable is interrupted at the slider. https://codereview.qt-project.org/#/c/171484/

Container

• Detailed description
  • "Typically the content items are statically declared as children of the container, but Container also provides an API to \l add, \l insert, \l move and \l remove items dynamically." https://codereview.qt-project.org/#/c/171341/

Dial

• Detailed description
  • Missing GIF/screenshot https://codereview.qt-project.org/#/c/175415/
• Dial::angle
  • Document the range https://codereview.qt-project.org/#/c/171340/
• Dial::handle
  • Fix the property type: Item https://codereview.qt-project.org/#/c/171340/
• Dial::pressed
  • Does the example not break left key handling? Mitch: yeah, it's intentional (see the paragraph before the example).
• Dial::stepSize
  • What does the default stepSize 0.0 mean in practice? 0.1 steps? 10% steps? https://codereview.qt-project.org/#/c/171340/
• Dial::wrap
  • The GIFs are hard to follow since you can't see the cursor / touch point QTBUG-56868

Drawer

• Detailed description
  • A GIF would explain a lot https://codereview.qt-project.org/#/c/175414/
  • Split the snippet? First a basic snippet without any content pushing tricks? The content pushing example is based on Drawer::position, so it could be moved there. https://codereview.qt-project.org/#/c/171717/
  • Add to the note about the reserved edges on certain platforms. "For example, the top and bottom edges on Android and iOS". https://codereview.qt-project.org/#/c/175181/
• Drawer::edge
  • The edge of the window, not content item https://codereview.qt-project.org/#/c/175181/
• Drawer::position
  • Would \c 0.0 and \c 1.0 stand out better from the text? https://codereview.qt-project.org/#/c/175181/

Frame

• Detailed description
  • link to Control::contentItem https://codereview.qt-project.org/#/c/171346/

GroupBox

• Brief description
  • Match with Frame and mention title https://codereview.qt-project.org/#/c/171351/
• Detailed description
  • Avoid auto-links to itself? https://codereview.qt-project.org/#/c/171351/
  • link to Control::contentItem https://codereview.qt-project.org/#/c/175183/
  • s/behavior of the groupbox/behavior of the checkbox/ https://codereview.qt-project.org/#/c/171351/
• GroupBox::title
  • Elaborate? Where the title is shown or something? https://codereview.qt-project.org/#/c/171351/

ItemDelegate

• Detailed description
  • Could be helpful mention something that basically the whole API is inherited from AbstractButton. Mitch: this is already mentioned there.
• ItemDelegate::highlighted
  • The mention of the default value seems out of place. Move it before the snippet and the explanation?

Label

• Detailed description
  • link to Text https://codereview.qt-project.org/#/c/175191/

Material

• Attached properties
  • Examples and screenshots of them! https://codereview.qt-project.org/#/c/172286

Menu

• Detailed description
  • "Typically the menu items are statically declared as children of the menu, but Menu also provides an API to \l add, \l insert, \l move and \l remove items dynamically. The items in a menu can be accessed using \l itemAt() or \l contentChildren." https://codereview.qt-project.org/#/c/171690/
  • Mention also that Menu is not limited to MenuItems, but can contain basically any items. https://codereview.qt-project.org/#/c/171690/
• Menu::contentData
  • Elaborate. Borrow something from Container::contentData, Item::data https://codereview.qt-project.org/#/c/171690/
• Menu::contentModel
  • Borrow something from Container::contentModel https://codereview.qt-project.org/#/c/171690/
  • It is a read-only property, so drop the "by default" comment. https://codereview.qt-project.org/#/c/171690/
  • Don't promise an ObjectModel, because we may have to change it to something else in the future to deal with hidden items. https://codereview.qt-project.org/#/c/171690/
• Menu::title
  • Could do some rephrasing... https://codereview.qt-project.org/#/c/171690/
  • Could drop the mention of the default empty string. It's silly and obvious. https://codereview.qt-project.org/#/c/171690/
  • Elaborate. Not used by anything (yet?). What is it for? How can it be used? https://codereview.qt-project.org/#/c/171690/
  • Example snippet? Mitch: left out for now as it wouldn't add much value.
• Menu::addItem(), insertItem(), moveItem(), removeItem()
  • an item or the item? https://codereview.qt-project.org/#/c/171690/

MenuItem

• Detailed description
  • Rephrase. Talks about AbstractButton's "clicked" but provides its own "triggered". https://codereview.qt-project.org/#/c/171692/
• MenuItem::checkable
  • Elaborate. “A checkable menu item toggles between checked (on) and unchecked (off) when the user...” https://codereview.qt-project.org/#/c/171692/
  • Link to AbstractButton::checked https://codereview.qt-project.org/#/c/171692/

Page

• Page::contentChildren, contentData
  • Elaborate. Borrow something from Container::contentChildren, Container::contentData, Item::children, Item::data https://codereview.qt-project.org/#/c/171700/
• Page::title
  • Elaborate. Not used by anything (yet?). What is it for? How can it be used? https://codereview.qt-project.org/#/c/171700/
  • Example snippet https://codereview.qt-project.org/#/c/171700/

PageIndicator

• Detailed description
  • Add eg. StackLayout to the example snippet to show realistic usage/bindings? https://codereview.qt-project.org/#/c/171723/
• PageIndicator::interactive
  • Example snippet with 2-way bindings to SwipeView https://codereview.qt-project.org/#/c/171723/
  • Mention that the indicators are typically relatively small. They can be hard to hit. It may not be obvious to the user that the indicators are interactive. So for these several reasons, this should not be the only/main method of navigation! https://codereview.qt-project.org/#/c/171723/

Pane

• Detailed description
  • link to Control::contentItem https://codereview.qt-project.org/#/c/171733/
• Pane::contentChildren, contentData
  • Elaborate. Borrow something from Container::contentChildren, Container::contentData, Item::children, Item::data https://codereview.qt-project.org/#/c/171733/
• Pane::contentWidth, contentHeight
  • These provide a way to set the implicit size of the content. Any padding or decoration (with Frame & GroupBox) is added to the total implicit size of the whole control. https://codereview.qt-project.org/#/c/171733/

Popup

• Detailed description
  • Add screenshot (ignored, the default style popup is just a plain rectangle...)
  • Add the same diagram than Control has? https://codereview.qt-project.org/#/c/171808/
  • Explain positioning and sizing behavior https://codereview.qt-project.org/#/c/171808/
• Popup::activeFocus
  • \sa focus https://codereview.qt-project.org/#/c/171808/
• Popup::availableWidth, availableHeight
  • Elaborate. The width/height available for content. Horizontal/vertical padding deducted from the total width/height. https://codereview.qt-project.org/#/c/171808/
• Popup::background
  • Example snippet https://codereview.qt-project.org/#/c/171808/
  • Notice that most popups use the implicit size of the background item to calculate the implicit size of the popup itself. If you replace the background with a custom one, you should also consider providing a sensible implicit size for it (unless it's eg. Image that already calculates its implicit size). https://codereview.qt-project.org/#/c/171808/
• Popup::contentChildren, contentData
  • Elaborate. Borrow something from Container::contentChildren, Container::contentData, Item::children, Item::data https://codereview.qt-project.org/#/c/171808/
• Popup::contentItem
  • The content item is resized within the paddings. https://codereview.qt-project.org/#/c/171808/
  • Notice that most popups use the implicit size of the content item to calculate the implicit size of the popup itself. If you replace the content item with a custom one, you should also consider providing a sensible implicit size for it (unless it's eg. Text that already calculates its implicit size). https://codereview.qt-project.org/#/c/171808/
  • Example snippet https://codereview.qt-project.org/#/c/171808/
• Popup:contentWidth, contentHeight
  • These provide a way to set the implicit size of the content. Any padding or decoration (with Frame & GroupBox) is added to the total implicit size of the whole control. https://codereview.qt-project.org/#/c/175317/
• Popup::dim
  • A screenshot would explain a lot
• Popup::enter, exit
  • An example (+ GIF?) https://codereview.qt-project.org/#/c/175317/
• Popup::focus
  • \sa activeFocus https://codereview.qt-project.org/#/c/171808/
  • Has focus or wants focus? https://codereview.qt-project.org/#/c/171808/
• Popup::font
  • Example snippet with font inheritance https://codereview.qt-project.org/#/c/175317/
• Popup::padding, topPadding, leftPadding, rightPadding, bottomPadding
  • Link to the diagram https://codereview.qt-project.org/#/c/171808/
  • Elaborate. These are used to control the geometry of the content item. https://codereview.qt-project.org/#/c/171808/
• Popup::visible
  • \sa open(), close() https://codereview.qt-project.org/#/c/171808/
• Popup::z
  • Popups with the same Z-value -> the last opened at the top. https://codereview.qt-project.org/#/c/171808/
• Popup::open(), close()
  • \sa visible https://codereview.qt-project.org/#/c/171808/

ProgressBar

• Detailed description
  • Should we have any tips when to use indeterminate ProgressBar vs. BusyIndicator? https://codereview.qt-project.org/#/c/175442/
  • Link to Indicator Controls https://codereview.qt-project.org/#/c/173767/

RadioButton

• Detailed description
  • Add GIF? https://codereview.qt-project.org/#/c/173072
  • Could be helpful mention something that basically the whole API is inherited from AbstractButton. https://codereview.qt-project.org/#/c/173093
  • Could continue the auto-exclusive paragraph by mentioning that ButtonGroup can be used to manage RadioButtons that do not share a common parent. https://codereview.qt-project.org/#/c/173093
  • Mention RadioDelegate, explain the difference between the two, and link to RadioDelegate https://codereview.qt-project.org/#/c/173093

RadioDelegate

• Detailed description
  • Could be helpful mention something that basically the whole API is inherited from ItemDelegate and AbstractButton. https://codereview.qt-project.org/#/c/173096/
  • Is it auto-exclusive by default, like RadioButton is? Add the same sentence if so. https://codereview.qt-project.org/#/c/173096/
  • Mention RadioButton, explain the difference between the two, and link to RadioButton https://codereview.qt-project.org/#/c/173096/

RangeSlider

• Detailed description
  • Add another, a bit more complex example snippet. For example, a slider from 1 to 100, first handle at 25, second handle at 75, and explain the values of position and visual position in LTR & RTL https://codereview.qt-project.org/#/c/173777/
• RangeSlider::snapMode
  • GIFs to illustrate the snapModes? https://codereview.qt-project.org/#/c/173777/
• RangeSlider::first/second.increase(), decrease()
  • Is it 0.1 or 10% of the whole range? 0.1, as documented.

RoundButton (5.8 only)

• Guidelines missing from Button Controls https://codereview.qt-project.org/#/c/175545/

ScrollBar

• Detailed description
  • A GIF with some real content? https://codereview.qt-project.org/#/c/173059/
  • Give the attaching section a linkable title and link from ScrollBar.vertical and .horizontal attached properties https://codereview.qt-project.org/#/c/173795/
  • Give the "connecting active-properties of two scrollbars" section a linkable title and link from ScrollBar::active https://codereview.qt-project.org/#/c/173795/
  • Give an example of manual ScrollBar usage. Without the attached property you have full control over size, position & active. https://codereview.qt-project.org/#/c/173795/
• Mention in all properties that are automatically set when using the attached property https://codereview.qt-project.org/#/c/173795/

ScrollIndicator

• Detailed description
  • A GIF with some real content? https://codereview.qt-project.org/#/c/173064/
  • Give the attaching section a linkable title and link from ScrollIndicator.vertical and .horizontal attached properties https://codereview.qt-project.org/#/c/173799/
  • Give the "connecting active-properties of two scrollbars" section a linkable title and link from ScrollIndicator::active https://codereview.qt-project.org/#/c/173799/
  • Give an example of manual ScrollIndicator usage. Without the attached property you have full control over size, position & active. https://codereview.qt-project.org/#/c/173799/
• Mention in all properties that are automatically set when using the attached property https://codereview.qt-project.org/#/c/173799/

Slider

• Detailed description
  • Add another, a bit more complex example snippet. For example, a slider from 1 to 100, handle at != 50, and explain the values of position and visual position in LTR & RTL https://codereview.qt-project.org/#/c/173228/
• Slider::snapMode
  • GIFs to illustrate the snapModes? https://codereview.qt-project.org/#/c/173215/
• Slider::increase(), decrease()
  • Is it 0.1 or 10% of the whole range? 0.1, as documented.

SpinBox

• SpinBox::increase(), decrease()
  • What if stepSize is not defined? 0.1 or 10% like Slider? https://codereview.qt-project.org/#/c/174101/
• valueFromText and textFromValue when it should be implemented and both should be implemented https://codereview.qt-project.org/#/c/174101/

StackView

• Detailed description
  • This is like a book already, but a GIF would be nice https://codereview.qt-project.org/#/c/173909/

SwipeDelegate

• Detailed description
  • Missing an example snippet https://codereview.qt-project.org/#/c/174120/
  • Could be helpful mention something that an important part of the API is inherited from ItemDelegate and AbstractButton. https://codereview.qt-project.org/#/c/174120/
• SwipeDelegate::swipe.pressed, complete
  • Missing read-only notation https://codereview.qt-project.org/#/c/175297/

SwipeView

• Detailed description
  • Add a GIF to make it easier to get an understanding at a glimpse https://codereview.qt-project.org/#/c/175437/
  • "Typically the content items are statically declared as children of the container, but the base type \l Container also provides an API to \l add, \l insert, \l move and \l remove items dynamically." https://codereview.qt-project.org/#/c/127372/
• Attached properties
  • What are they really used for? done in 5.8
  • Example snippets! done in 5.8

Switch

• Detailed description
  • Could be helpful mention something that basically the whole API is inherited from AbstractButton. https://codereview.qt-project.org/#/c/175192/
  • Mention SwitchDelegate, explain the difference between the two, and link to SwitchDelegate. https://codereview.qt-project.org/#/c/175192/

SwitchDelegate

• Detailed description
  • Could be helpful mention something that basically the whole API is inherited from ItemDelegate and AbstractButton. https://codereview.qt-project.org/#/c/175192/
  • Mention Switch, explain the difference between the two, and link to Switch. https://codereview.qt-project.org/#/c/175192/

TabBar

• Brief description
  • Advertises icons but we don't even support icons (yet). https://codereview.qt-project.org/#/c/175196/
• Detailed description
  • Add a GIF to make it easier to get an understanding at a glimpse (ignored, animation hard to follow without some extensive content. there are several screenshots already)
  • "Typically the content items are statically declared as children of the container, but the base type \l Container also provides an API to \l add, \l insert, \l move and \l remove items dynamically." https://codereview.qt-project.org/#/c/175196/
• TabBar::position
  • Inconsistency: ApplicationWindow is a link, Page is not => make both links https://codereview.qt-project.org/#/c/175196/

TabButton

• Brief description
  • found on -> used in? https://codereview.qt-project.org/#/c/173801/
• Detailed description
  • Could be helpful mention something that basically the whole API is inherited from AbstractButton. https://codereview.qt-project.org/#/c/173801/

TextArea

• Detailed description
  • Make the scrollable section linkable with a title, and link from TextArea.flickable attached property instead of duplicating the example? https://codereview.qt-project.org/#/c/175193/
• TextArea::background
  • Share the docs with Control::background (mention implicit size) https://codereview.qt-project.org/#/c/173805/
• TextArea::focusReason
  • Share the docs with Control::focusReason and TextField::focusReason https://codereview.qt-project.org/#/c/173808/

TextField

• TextField::background
  • Share the docs with Control::background (mention implicit size) https://codereview.qt-project.org/#/c/173805/
• TextField::focusReason
  • Share the docs with Control::focusReason and TextArea::focusReason https://codereview.qt-project.org/#/c/173808/

ToolBar

• Brief description
  • ToolBar does not make anything context sensitive, it's up to the user to put there whatever they want https://codereview.qt-project.org/#/c/173810/
• ToolBar::position
  • Inconsistency: ApplicationWindow is a link, Page is not => make both links https://codereview.qt-project.org/#/c/173810/

ToolButton

• Brief description
  • ToolButton: layout -> look https://codereview.qt-project.org/#/c/175389/
• Detailed description
  • The screenshot is not clear at a glimpse that where is the ToolButton there. https://codereview.qt-project.org/#/c/175389/
  • Could be helpful mention something that basically the whole API is inherited from AbstractButton. https://codereview.qt-project.org/#/c/175389/

ToolTip

• Detailed description
  • The first screenshot is missing the tooltip... https://codereview.qt-project.org/#/c/173292/
• Attached properties
  • Examples! https://codereview.qt-project.org/#/c/175265/

Tumbler

• Detailed description
  • Make the GIF more visible, or add another at the top https://codereview.qt-project.org/#/c/173809/
• Tumbler::delegate
  • The correct type is "Component", not "component" https://codereview.qt-project.org/#/c/173809/

Universal

• Attached properties
  • Examples and screenshots of them! https://codereview.qt-project.org/#/c/174621/