Uploaded image for project: 'Qt Quick Components (Deprecated, use QTBUG)'
  1. Qt Quick Components (Deprecated, use QTBUG)
  2. QTCOMPONENTS-200

Define a baseline Item set as common API between different component style implementations

    XMLWordPrintable

    Details

    • Type: Epic
    • Status: Closed
    • Priority: P1: Critical
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: Alpha
    • Component/s: components
    • Labels:

      Description

      Define QML Item's that expose properties and other metaobject information, which form the common API that Qt Quick component styles should implement. For these common APIs on the first phase we are not focusing on styling neither on layouting parts, as these will be provided by the respective style implementations.

      1st Priority Common API Task API Plan
      Button QTCOMPONENTS-75 2010w48
      CheckBox QTCOMPONENTS-76 2010w48
      Slider QTCOMPONENTS-80 2010w48
      ProgressBar QTCOMPONENTS-81 2010w48
      ScrollDecorator QTCOMPONENTS-83 2010w48
      TextField QTCOMPONENTS-296 2010w50
      TextArea QTCOMPONENTS-297 2010w50
      RadioButton QTCOMPONENTS-386 2011w02
      Dialog Framework QTCOMPONENTS-315 2011w04
      SelectionDialog QTCOMPONENTS-423 Alpha
      QueryDialog QTCOMPONENTS-443 Alpha
      ButtonRow/Column QTCOMPONENTS-330 2011w04
      Page and PageStack QTCOMPONENTS-373 Alpha
      Window QTCOMPONENTS-378 Alpha
      ApplicationWindow QTCOMPONENTS-465 Alpha
      StatusBar QTCOMPONENTS-306 Beta
      Menu QTCOMPONENTS-356 Alpha
      ContextMenu QTCOMPONENTS-431 Beta?
      ToolBar QTCOMPONENTS-369 Beta
      Switch QTCOMPONENTS-421 Alpha
      SectionScroller QTCOMPONENTS-426 Alpha
      BusyIndicator QTCOMPONENTS-424 Alpha
      Priority, candidate for common API    
      TabGroup QTCOMPONENTS-412 Beta
      Screen QTCOMPONENTS-521 Beta?
      ToolButton / ToolIcon QTCOMPONENTS-599 Beta
      Convenience extras    
      CountBubble    
      DatePickerDialog    
      MoreIndicator    
      PageIndicator    
      InfoBanner QTCOMPONENTS-199  
      TimePicker    
      TumblerDialog    

      API

      The initial API design assumes only non-visible properties. Visual aspects of the widgets will be encapsulated in the Style. Platform-specific components like IconButton, SwitchButton and so forth should be possible to build on top of this but is not part of the common API - but should be based on a common abstract button. They should be exposed under a platform-specific import.

      import com.meego 1.0 // for Meego components
      import com.nokia.symbian 1.0 // for Symbian components
      import Qt.labs.components.native 1.0 // RnD: use currently installed components (Meego or Symbian)
      

      Button

      Expose only bare minimum from the MouseArea that will be inside a Button implementation.

      Button.qml:

      Item {
         // toggled via clicked()
         property bool checked
         property bool checkable
         property bool pressed
      
         signal clicked
      
        // label visibility depends on string presence
         property string text
         // icon visibility depends on iconSource presence
         // state-dependent resources should be assigned by ternary operators comparing e.g. checked state
         property url iconSource
      
         property QFont font // alias type to font property of the QML Text element
      }
      

      CheckBox and RadioButton share the same API

      CheckBox.qml:

      Item {
         property bool checked
         property bool pressed
      
         signal clicked
      
         // currently, only intended to support a single-line text description
         // text area is also clickable
      
         // ### note we need a way to define a standard label next to a checkbox
         // currently we are not sure if we will use a separate Label component for that
         // property string text
         // property url iconSource
      }
      

      obs: tri-state is not a common feature on the mobile, so will not be added now (could be added
      later for the desktop use case). switchbutton has a similar behavior as checkbox, but is a separate component.

      Slider

      Slider.qml:

      Item {
         property real stepSize // default is 0.0 - continuous 
         property real minimumValue // default = 0.0
         property real maximumValue // default = 1.0
         property real value // default = 0.0
         property int orientation // Qt.Horizontal (default) | Qt.Vertical
         property bool inverted // default = false
      
         property bool pressed // this activates in all the slider area
         property bool valueIndicatorVisible // default = false
         property string valueIndicatorText // to override the default formating provided by the style
      }
      

      obs: stepSize represents valid values for the widget (onValueChanged will be emitted only on 'stepSize' offsets),
      snapping behavior is up to the slider style implementation. Leaving the progress feature out from the components.
      we changed the type to float because it is more generic. Integer is a subcase of float (can be achieved by using a stepSize == 1.0).
      another argument is that if we want to show float types in the slider label (or for the minimum/maximum values), we need to be able to set those float values through the api.

      Avoid changing the 'value' of the Slider while dragging (behavior in this case is undefined).

      ProgressBar

      ProgressBar.qml:

      Item {
         property real minimumValue // default = 0.0
         property real maximumValue // default = 1.0
         property real value // default = 0.0
         property bool indeterminate // default = false, this doest not influence the value of progress
      }
      
      

      obs: the behavior on how to switch from indeterminate to determinate is style dependent.

      BusyIndicator

      BusyIndicator.qml:

      Item {
          property bool running // default = false
      }
      

      obs: spinner name was wrong, spinner is a spinbox in android, sencha and jquery.

      ScrollDecorator

      For use around a Flickable (which is the QML equivalent of a ScrollArea)

      ScrollDecorator.qml:

      Item {
          property Flickable flickableItem
      }
      

      usage pattern:

      Item {
          // Do your anchoring/geometry setting here
          ListView { 
              id: list
              anchors.fill: parent
          }
          ScrollDecorator { flickableItem: list }
      }
      

      obs: there should be a separate component for an interactive scrollbar.
      obs 2: see comment for explanation

      TextField

      Item {
          property bool errorHighlight
          property string placeholderText
          property int inputMethodHints
          property font font // alias to textInput.font
      
          property int cursorPosition
          property bool readOnly // defaults to false
          property int echoMode // Supports TextInput.Normal,TextInput.Password, TextInput.NoEcho, TextInput.PasswordEchoOnEdit
          property bool acceptableInput // this is a read-only property
          property string inputMask
          property Validator validator
          property string selectedText // read-only
          property int selectionEnd // read-only
          property int selectionStart // read-only
          property string text    
          property int maximumLength // alias to textInput.maximumLength
      
          // functions
          copy
          paste
          cut
          select(int start, int end)
          selectAll
          selectWord
          positionAt(int x)
          positionToRectangle(int pos)
      }
      

      TextArea

      // uses a TextEdit in the implementation, but provides styling frame and default fonts,
      Item {
          property font font // alias to textEdit.font    
          property int inputMethodHints
          property bool errorHighlight
          property int cursorPosition
          property int horizontalAlignment // enumeration
          property int verticalAlignment // enumeration
          property bool readOnly // defaults to false
          property string selectedText // read-only
          property int selectionEnd // read-only
          property int selectionStart // read-only
          property string text
          property int textFormat // enumeration
          property int wrapMode // enumeration
          property string placeholderText
      
          // functions
          copy
          paste
          cut
          select(int start, int end)
          selectAll
          selectWord
          positionAt(int x, int y)
          positionToRectangle (int pos)
      }
      

      ButtonRow and ButtonColumn

      Arranges buttons in a row or a column. Adds mutual exclusion for RadioButtons and checkable Buttons.

      When using Buttons, these will be stylized as parts of a 'segmented button'.

      Any item with the checked property is supported.

      Row // or Column
      {
          property bool exclusive: true // when true, forces all its children to be checkable
          property Item checkedButton // the last button checked
      }
      

      When the exclusive property is set to true, the following algorithm is used to determine which button will be checked from start.

      1. If checkedButton is set, this will be the one. All the other buttons will be unchecked.
      2. Else, if any button's checked property is set to true, the first one will be the one, and all the others will be unchecked.
      3. Else, if no button has its checked property set to true, the first button will be the one.

      When adding, removing, hiding, or showing buttons in ButtonRow, ButtonColumn, the same algorithm as above applies. If checkedButton is now hidden or has been removed, then it stands as undefined.

      The checkedButton property is read-write. Setting it during runtime is equivalent to clicking on that button.

      Although it's not a use-case we would encourage, changing the exclusive property during runtime is defined, too. When changing from true to false, the currently checked button remains checked. When changing from false to true, the checkedButton value is preserved as much as possible, or as much as it makes sense.

      Examples:

      ButtonRow {
          // exclusive is true (by default), so all the Buttons below will be checkable
          Button { text: "POP" }
          Button { text: "IMAP" }
          Button { text: "Exchange" }
      }
      
      ButtonColumn {
          RadioButton { Text { text: "AM"; anchors.left: parent.right } }
          RadioButton { Text { text: "FM"; anchors.left: parent.right } }
          RadioButton { Text { text: "DAB"; anchors.left: parent.right } }
      }
      
      ButtonColumn {
          exclusive: false
          CheckBox { Text { text: "olives"; anchors.left: parent.right } }
          CheckBox { Text { text: "anchovies"; anchors.left: parent.right } }
          CheckBox { Text { text: "capers"; anchors.left: parent.right } }
      }
      

      obs: should this be used in the toolbar? are there relevant cases for button row in other contexts?

      Remaining API's should be discussed in each detail task as linked to above

        Attachments

          Issue Links

          No reviews matched the request. Check your Options in the drop-down menu of this sections header.

            Activity

              People

              • Assignee:
                lscunha Leonardo Sobral Cunha (Inactive)
                Reporter:
                hhartz Henrik Hartz (closed Nokia identity) (Inactive)
              • Votes:
                9 Vote for this issue
                Watchers:
                28 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:

                  Time Tracking

                  Estimated:
                  Original Estimate - 4 weeks, 1 day
                  4w 1d
                  Remaining:
                  Time Spent - 4 days, 6 hours Remaining Estimate - 3 weeks, 1 day, 2 hours
                  3w 1d 2h
                  Logged:
                  Time Spent - 4 days, 6 hours Remaining Estimate - 3 weeks, 1 day, 2 hours
                  4d 6h

                    Gerrit Reviews

                    There are no open Gerrit changes