Verified Commit 12b8ada7 authored by Carl Schwan's avatar Carl Schwan 🚴
Browse files

Improve documentation

Improve wording consistency, fix types, add more information about
default value, ...

Following component were reworked during this batch:

* AbstractItemViewHeader.qml
* Action.qml
* ActionTextField.qml
* ActionToolBar.qml
* ApplicationItem.qml
* ApplicationWindow.qml
* Avatar.qml
* BasicListItem.qml
* Card.qml
* CardsGridView.qml
* CardsLayout.qml
parent 8ba168cf
Pipeline #90895 passed with stage
in 54 seconds
......@@ -17,9 +17,21 @@ import org.kde.kirigami 2.4 as Kirigami
* @inherit QtQuick.Controls.Control
*/
T2.Control {
/**
* This property holds the minimum height of the AbstractItemViewHeader.
*/
property int minimumHeight: Kirigami.Units.gridUnit * 2 + Kirigami.Units.smallSpacing * 2
/**
* This property holds the maximum height of the AbstractItemViewHeader.
*/
property int maximumHeight: Kirigami.Units.gridUnit * 6
/**
* This property holds the ListView for which this item is the header.
*
* By default automatically set to the attached property: `ListView.view`.
*/
property ListView view: ListView.view
width: view.width
......
......@@ -19,64 +19,66 @@ Controls.Action {
id: root
/**
* True (default) when the graphic representation of the action
* @brief This property holds whether the graphic representation of the action
* is supposed to be visible.
*
* It's up to the action representation to honor this property.
*
* By default the action is visible.
*/
property bool visible: true
/**
* \property string Action::iconName
* Sets the icon name for the action. This will pick the icon with the given name from the current theme.
* @brief This property holds the icon name for the action. This will pick the icon with the given name from the current theme.
*
* @property string Action::iconName
* @deprecated Use icon.name instead.
*/
property alias iconName: root.icon.name
/**
* \property string Action::iconSource
* Sets the icon file or resource url for the action. Defaults to the empty URL. Use this if you want a specific file rather than an icon from the theme
* @brief This property holds an url to an icon file or resource url for the action.
*
* Defaults to the empty URL. Use this if you want a specific file rather than an icon from the theme
*
* @property url Action::iconSource
* @deprecated Use icon.name instead.
*/
property alias iconSource: root.icon.source
/**
* A tooltip text to be shown when hovering the control bound to this action. Not all controls support tooltips on all platforms
*/
property string tooltip
/**
* \property list<Action> Action::children
* A list of children actions.
* Useful for tree-like menus
* @code
* Action {
* text: "Tools"
* Action {
* text: "Action1"
* }
* Action {
* text: "Action2"
* }
* }
* @endcode
* This property holds a tooltip text to be shown when hovering the control bound to this
* action. Not all controls support tooltips on all platforms
*/
property string tooltip
/**
* Whether the action is is a separator action; defaults to false.
* This property holds whether the action is a separator action.
*
* By default the action isn't a separator.
*/
property bool separator: false
/**
* When true, actions in globalDrawers and contextDrawers will become titles displaying the child actions as sub items
* This property hols whether the actions in globalDrawers and contextDrawers will
* become titles displaying the child actions as sub items.
*
* By default the action is not expandible.
* @since 2.6
*/
property bool expandible: false
/**
* This property holds the parent action of this parent.
*/
property Controls.Action parent
/**
* A combination of values from the Action.DisplayHint enum. These are provided to implementations to indicate
* a preference for certain display styles. The default is DisplayHint.NoPreference.
* This property holds a combination of values from the Action.DisplayHint enum.
* These are provided to implementations to indicate a preference for certain display
* styles. The default is DisplayHint.NoPreference.
*
* Note that these are only preferences, implementations may choose to disregard them.
* @note This property contains only preferences, implementations may choose to disregard them.
*
* @since 2.12
*/
......@@ -93,7 +95,7 @@ Controls.Action {
*
* @since 2.12
*
* \deprecated since 2.14, Use DisplayHint.displayHintSet(action, hint) instead.
* @deprecated since 2.14, Use DisplayHint.displayHintSet(action, hint) instead.
*/
function displayHintSet(hint) {
print("Action::displayHintSet is deprecated, use DisplayHint.displayHintSet(action, hint)")
......@@ -101,14 +103,36 @@ Controls.Action {
}
/**
* A Component that should be preferred when displaying this Action.
* This property holds a component that should be preferred when displaying this Action.
*
* This can be used to display custom components in the toolbar.
*
* @since 5.65
* @since 2.12
*/
property Component displayComponent: null
/**
* This action holds a list of children actions.
*
* This is useful for tree-like menus. For example for the GlobalDrawer.
*
* @code
* Action {
* text: "Tools"
* Action {
* text: "Action1"
* }
* Action {
* text: "Action2"
* }
* }
* @endcode
* @property list<Action> Action::children
*/
default property alias children: root.__children
/** @internal */
property list<QtObject> __children
onChildrenChanged: {
......@@ -122,16 +146,16 @@ Controls.Action {
}
/**
* \property list<Action> Action::visibleChildren
* All child actions that are visible
* This property holds the visible children actions that are visible.
*
* @property list<Action> Action::visibleChildren
*/
readonly property var visibleChildren: {
var visible = [];
var child;
for (var i in children) {
child = children[i];
let visible = [];
for (let i in children) {
const child = children[i];
if (!child.hasOwnProperty("visible") || child.visible) {
visible.push(child)
visible.push(child);
}
}
return visible;
......
......@@ -46,21 +46,18 @@ Controls.TextField
id: root
/**
* focusSequence: keysequence
* This property hold the a list of shortcut sequence that put the text
* field into focus.
*/
property string focusSequence
/**
* leftActions: list<QtObject>
* This property hold the action that is left in the field. By default this
* list is empty.
*/
property list<QtObject> leftActions
/**
* rightActions: list<QtObject>
* This property hold the action that is right in the field. By default this
* list is empty.
*/
......
......@@ -11,9 +11,11 @@ import org.kde.kirigami 2.14 as Kirigami
import "private"
/**
* This is a simple toolbar built out of a list of actions
* each action is represented by a ToolButton, those that won't fit
* the size will go in a menu under a button with the overflow ... icon
* @brief This is a simple toolbar built out of a list of actions.
*
* In the ActionToolBar, each action is represented by a QtQuick.Controls.ToolButton.
* The ActionToolBar component will try to display has many actions as possible but
* those that won't fit will go in a an overflow manu.
*
* @inherit QtQuick.Controls.Control
* @since 2.5
......@@ -21,74 +23,98 @@ import "private"
Controls.Control {
id: root
/**
* @property list<Action> ActionToolBar::actions
* if the card should provide clickable actions, put them in this property,
* they will be put in the footer as a list of ToolButtons plus an optional
* overflow menu, when not all of them will fit in the available Card width.
*/
* @brief This property holds a list of action that will appear in the ActionToolBar.
* The ActionToolBar component will try to display has many of these actions as possible
* as a list of ToolButton but those that won't fit will go in a an overflow manu.
*
* @property list<Action> ActionToolBar::actions
*/
property alias actions: layout.actions
/**
* @property list<Action> ActionToolBar::hiddenActions
* This list of actions is for those you always want in the menu, even if there
* is enough space.
* @since 2.6
* @deprecated since 2.14, use the AlwaysHide hint on actions instead.
*/
* This property holds a list of actions that will always be displayed in the overflow
* menu even if there is enough place.
*
* @since 2.6
* @property list<Action> ActionToolBar::hiddenActions
* @deprecated since 2.14, use the AlwaysHide hint on actions instead.
*/
property list<QtObject> hiddenActions
onHiddenActionsChanged: print("ActionToolBar::hiddenActions is deprecated, use the AlwaysHide hint on your actions instead")
/**
* Whether we want our buttons to have a flat appearance. Default: true
* This property holds whether we want our buttons to have a flat appearance.
*
* By default action will be using flat QtQuick.Controls.ToolButton.
*/
property bool flat: true
/**
* display: enum
* This controls the label position regarding the icon, is the same value to control individual Button components,
* permitted values are:
* * Button.IconOnly
* * Button.TextOnly
* * Button.TextBesideIcon
* * Button.TextUnderIcon
* This property holds the controls the label position regarding the icon.
*
* It is the same value to control individual Button components, permitted values are:
*
* * `Button.IconOnly`
* * `Button.TextOnly`
* * `Button.TextBesideIcon`
* * `Button.TextUnderIcon`
*/
property int display: Controls.Button.TextBesideIcon
/**
* This property holds the alignment of the buttons.
*
* When there is more space available than required by the visible delegates,
* we need to determine how to place the delegates. This property determines
* how to do that.
*
* @property Qt::Alignment alignment
*/
property alias alignment: layout.alignment
/**
* position enum
* This property holds the position of the toolbar.
* if this ActionToolBar is the contentItem of a QQC2 Toolbar, the position is binded to the ToolBar's position
*
* permitted values are:
* *ToolBar.Header: The toolbar is at the top, as a window or page header.
* *ToolBar.Footer: The toolbar is at the bottom, as a window or page footer.
* If this ActionToolBar is the contentItem of a QQC2 Toolbar, the position is binded to the ToolBar's position
*
* Permitted values are:
*
* * ToolBar.Header: The toolbar is at the top, as a window or page header.
* * ToolBar.Footer: The toolbar is at the bottom, as a window or page footer.
*/
property int position: parent && parent.hasOwnProperty("position")
? parent.position
: Controls.ToolBar.Header
/**
* The maximum width of the contents of this ToolBar. If the toolbar's width is larger than this value, empty space will
* This property holds the maximum with of the content of this ToolBar.
*
* If the toolbar's width is larger than this value, empty space will
* be added on the sides, according to the Alignment property.
*
* The value of this property is derived from the ToolBar's actions and their properties.
*
* @property int maximumContentWidth
*/
readonly property alias maximumContentWidth: layout.implicitWidth
/**
* The name of the icon to use for the overflow menu button.
* This property holds the name of the icon to use for the overflow menu button.
*
* @since 5.65
* @since 2.12
*/
property string overflowIconName: "overflow-menu"
/**
* This property holds the combined width of the visible delegates.
*
* @property int visibleWidth
*/
property alias visibleWidth: layout.visibleWidth
/**
* Exposes heightMode of the internal layout.
* This property exposes the heightMode of the internal layout.
*
* \sa ToolBarLayout::heightMode
*/
......
......@@ -81,17 +81,20 @@ AbstractApplicationItem {
/**
* @property QtQuick.StackView ApplicationItem::pageStack
* Readonly.
* The stack used to allocate the pages and to manage the transitions
* between them.
*
* @brief This property holds the stack used to allocate the pages and to
* manage the transitions between them.
*
* It's using a PageRow, while having the same API as PageStack,
* it positions the pages as adjacent columns, with as many columns
* as can fit in the screen. An handheld device would usually have a single
* fullscreen column, a tablet device would have many tiled columns.
*
* @warning This property is readonly.
*/
property alias pageStack: __pageStack
property alias pageStack: __pageStack // TODO KF6 make readonly
//redefines here as here we can know a pointer to PageRow
// Redefines here as here we can know a pointer to PageRow
wideScreen: width >= applicationWindow().pageStack.defaultColumnWidth*2
Component.onCompleted: {
......
......@@ -90,19 +90,22 @@ AbstractApplicationWindow {
id: root
/**
* @var PageRow pageStack
* Readonly.
* The stack used to allocate the pages and to manage the transitions
* between them.
* @property QtQuick.StackView ApplicationItem::pageStack
*
* @brief This property holds the stack used to allocate the pages and to
* manage the transitions between them.
*
* It's using a PageRow, while having the same API as PageStack,
* it positions the pages as adjacent columns, with as many columns
* as can fit in the screen. An handheld device would usually have a single
* fullscreen column, a tablet device would have many tiled columns.
*
* @warning This property is readonly.
*/
property alias pageStack: __pageStack
//redefines here as here we can know a pointer to PageRow
property alias pageStack: __pageStack // TODO KF6 make readonly
// we negate the canBeEnabled check because we don't want to factor in the automatic drawer provided by Kirigami for page actions for our calculations
// Redefines here as here we can know a pointer to PageRow.
// We negate the canBeEnabled check because we don't want to factor in the automatic drawer provided by Kirigami for page actions for our calculations
wideScreen: width >= (root.pageStack.defaultColumnWidth) + ((contextDrawer && !(contextDrawer instanceof Kirigami.ContextDrawer)) ? contextDrawer.width : 0) + (globalDrawer ? globalDrawer.width : 0)
Component.onCompleted: {
......
......@@ -14,6 +14,7 @@ import "templates/private" as P
/**
* An element that represents a user, either with initials, an icon, or a profile image.
*
* @inherit QtQuick.Controls.Control
*/
QQC2.Control {
......@@ -30,74 +31,96 @@ QQC2.Control {
}
/**
* The given name of a user.
*
* The user's name will be used for generating initials and to provide the
* accessible name for assistive technology.
*/
* This property holds the given name of a user.
*
* The user's name will be used for generating initials and to provide the
* accessible name for assistive technology.
*/
property string name
/**
* The source of the user's profile picture; an image.
*/
* This property holds the source of the user's profile picture; an image.
*/
property alias source: avatarImage.source
/**
* How the button should represent the user when there is no image available.
* * `UseInitials` - Use initials when the image is not available
* * `UseIcon` - Use an icon of a user when the image is not available
*/
* This property holds how the button should represent the user when there is no image available.
*
* Possible values are:
* * `Avatar.InitialsMode.UseInitials` - Use initials when the image is not available
* * `Avatar.InitialsMode.UseIcon` - Use an icon of a user when the image is not available
*/
property int initialsMode: Kirigami.Avatar.InitialsMode.UseInitials
/**
* Whether the button should always show the image; show the image if one is
* available and show initials when it is not; or always show initials.
* * `AlwaysShowImage` - Always show the image; even if is not value
* * `AdaptiveImageOrInitals` - Show the image if it is valid; or show initials if it is not
* * `AlwaysShowInitials` - Always show initials
*/
* This property holds whether the button should always show the image; show the image if one is
* available and show initials when it is not; or always show initials.
*
* Possible values are:
* * `Avatar.ImageMode.AlwaysShowImage` - Always show the image; even if is not value
* * `Avatar.ImageMode.AdaptiveImageOrInitals` - Show the image if it is valid; or show initials if it is not
* * `Avatar.ImageMode.AlwaysShowInitials` - Always show initials
*/
property int imageMode: Kirigami.Avatar.ImageMode.AdaptiveImageOrInitals
/**
* Whether or not the image loaded from the provided source should be cached.
/**
* This property holds whether or not the image loaded from the provided source should be cached.
*
* @property bool sourceSize
*/
property alias cache: avatarImage.cache
property alias cache: avatarImage.cache
/**
* The source size of the user's profile picture.
*/
* This property holds the source size of the user's profile picture.
*
* @property int sourceSize
*/
property alias sourceSize: avatarImage.sourceSize
/**
* Whether or not the image loaded from the provided source should be smoothed.
*/
* This property holds whether or not the image loaded from the provided source should be smoothed.
*/
property alias smooth: avatarImage.smooth
/**
* This property holds the color to use for this avatar.
*
*/
/**
* color: color
* If not explicitly set, this defaults to generating a colour from the name.
*
* The color to use for this avatar. If not explicitly set, this defaults to generating a colour from the name.
* @property color color
*/
property var color: Kirigami.NameUtils.colorsFromString(name)
// We use a var instead of a color here to allow setting the colour
// as undefined, which will result in a generated colour being used.
/**
* actions.main: Kirigami.Action
* actions.secondary: Kirigami.Action
* This property holds the main and secondary actions associated
* with this avatar.
*
* @code
* Kirigami.Avatar {
* actions.main: Kirigami.Action {}
* actions.secondary: Kirigami.Action {}
* }
* @endcode
*
* Actions associated with this avatar.
*
* Note that the secondary action should only be used for shortcuts of actions
* @note The secondary action should only be used for shortcuts of actions
* elsewhere in your application's UI, and cannot be accessed on mobile platforms.
*/
property AvatarGroup actions: AvatarGroup {}
/**
* This property holds the border properties.
*
* @code
* Kirigami.Avatar {
* border.width: 10
* border.color: 'red'
* }
* @endcode
*/
property P.BorderPropertiesGroup border: P.BorderPropertiesGroup {
width: 0
color: Qt.rgba(0,0,0,0.2)
......
......@@ -19,18 +19,17 @@ AbstractListItem {
id: listItem
/**
* label: string
* @brief This property holds label of this list item.
*
* The label of this list item. If a subtitle is provided, the label will
* behave as a title and will have a bold font. Every list item should have
* a label.
* If a subtitle is provided, the label will behave as a title and will have a
* bold font. Every list item should have a label.
*
* @property string label
*/
property alias label: listItem.text
/**
* subtitle: string
*
* An optional subtitle that can appear under the label.
* @brief This property holds an optional subtitle that can appear under the label.
*
* @since 5.70
* @since org.kde.kirigami 2.12
......@@ -38,9 +37,7 @@ AbstractListItem {
property alias subtitle: subtitleItem.text
/**
* leading: Item
*
* An item that will be displayed before the title and subtitle. Note that the
* This property holds an item that will be displayed before the title and subtitle. Note that the
* leading item is allowed to expand infinitely horizontally, and should be bounded by the user.
*
* @since org.kde.kirigami 2.15
......@@ -62,9 +59,7 @@ AbstractListItem {
}
/**
* leadingPadding: real
*
* Padding after the leading item.
* This property holds a the padding after the leading item.
*
* @since org.kde.kirigami 2.15
*/
......@@ -86,9 +81,7 @@ AbstractListItem {
property bool leadingFillVertically: true
/**
* trailing: Item
*
* An item that will be displayed after the title and subtitle. Note that the
* This property holds an item that will be displayed after the title and subtitle. Note that the
* trailing item is allowed to expand infinitely horizontally, and should be bounded by the user.
*
* @since org.kde.kirigami 2.15
......@@ -111,9 +104,7 @@ AbstractListItem {
}
/**
* trailingPadding: real
*
* Padding before the trailing item.
* This property holds the padding before the trailing item.
*
* @since org.kde.kirigami 2.15
*/
......@@ -135,9 +126,7 @@ AbstractListItem {
property bool trailingFillVertically: true
/**
* bold: bool
*
* Whether the list item's text (both label and subtitle, if provided) should
* This property holds whether the list item's text (both label and subtitle, if provided) should
* render in bold.
*
* @since 5.71
......@@ -146,8 +135,6 @@ AbstractListItem {
property bool bold: false
/**
* icon: var
*
* @code ts
* interface IconGroup {
* name: string,
......@@ -182,80 +169,74 @@ AbstractListItem {
property var icon
/**
* iconSize: int
*
* The size at which the icon will render at. This will not affect icon lookup,
* This property holds the size at which the icon will render at. This will not affect icon lookup,
* unlike the icon group's width and height propert