# ComboButton QML Type

Lomiri button providing a drop-down panel visualizing custom options. More...

Import Statement: | import Lomiri.Components 1.3
Inherits: | AbstractButton

- List of all members, including inherited members
- Obsolete members

## Properties

- collapsedHeight : real
- comboList : list<Item>
- comboListHeight : real
- expanded : bool
- expandedHeight : real
- font : font
- iconPosition : string

## Detailed Description

The component is composed of three main blocks: main button, dropdown and combo list.

The main button holds the main functionailty of the component, and it is located at the left-top side of the expanded button. The clicked() signal is triggered only when this button is pressed.

The dropdown is a button located on the right of the main button. Its functionality is to drive the component's expanded state.

The combo list is a panel showing the content specified in comboList property when expanded. The content is stretched horizontally to the component's width, and its height is controlled by the expandedHeight property as follows:

- If the content height is smaller than the value of expandedHeight, the combo list will be expanded only to the height of the content.

      import QtQuick 2.4
      import Lomiri.Components 1.3
      ComboButton {
          text: "smaller content"
          Rectangle {
              height: units.gu(5) // smaller than the default expandedHeight
              color: "blue"
          }
      }

- If the content height is greater than expandedHeight, the combo list will expand till the height specified by the property and the content will be scrolled; in case the combo list content is one single Flickable, ListView, GridView or PathView, the content scrolling will be provided by the content itself.

      import QtQuick 2.4
      import Lomiri.Components 1.3
      ComboButton {
          text: "long scrolled content"
          Column {
              Repeater {
                  model: 5
                  spacing: units.gu(1)
                  Rectangle {
                      height: units.gu(5)
                      color: "blue"
                  }
              }
          }
      }

- In case the content is a single Flickable, ListView, GridView or PathView, the content will be filling the entire combo list area defined.

      import QtQuick 2.4
      import Lomiri.Components 1.3
      import Lomiri.Components.ListItems 1.3
      ComboButton {
          text: "listview"
          ListView {
              model: 10
              delegate: Standard {
                  text: "Item #" + modelData
              }
          }
      }

- Vertical anchoring of combo list content to its parent is not possible as the expansion calculation is done based on the combo list content height. If the content wants to take the size of the entire combo list, it should bind its height to the comboListHeight property.

      import QtQuick 2.4
      import Lomiri.Components 1.3
      ComboButton {
          id: combo
          text: "smaller content"
          Rectangle {
              height: combo.comboListHeight
              color: "blue"
          }
      }

- In case the expansion needs to be the size of the combo list content, the expandedHeight should be set to -1.

      import QtQuick 2.4
      import Lomiri.Components 1.3
      ComboButton {
          text: "auto-sized content"
          expandedHeight: -1
          Column {
              Repeater {
                  model: 5
                  spacing: units.gu(1)
                  Button {
                      text: "Button #" + modelData
                  }
              }
          }
      }

The combo list can be expanded/collapsed either through the expanded property or by clicking on the dropdown button. It is not collapsed when pressing the main button or clicking on the combo list. In order to do an auto-collapsing button you must reset the expanded property (set it to false) when the main button is clicked or when a selection is taken from the combo list content. The following example illustrates a possible implementation.

    import QtQuick 2.4
    import Lomiri.Components 1.3

    ComboButton {
        id: combo
        text: "Auto closing"
        expanded: true
        expandedHeight: units.gu(30)
        onClicked: expanded = false
        LomiriListView {
            width: parent.width
            height: combo.comboListHeight
            model: 20
            delegate: Standard {
                text: "Action #" + modelData
                onClicked: {
                    combo.text = text;
                    combo.expanded = false;
                }
            }
        }
    }

### Styling

The style of the component is defined in ComboButtonStyle.

## Property Documentation

collapsedHeight : real

The property holds the height of the component when collapsed. By default the value is the implicit height of the component.

[default] comboList : list<Item>

Property holding the list of items to be shown in the combo list. Being a default property children items declared will land in the combo list.

Note: The component is not responsible for layouting the content. It only provides scrolling abilities for the case the content exceeds the defined expanded height.

[read-only] comboListHeight : real

The property holds the maximum combo list height allowed based on the expandedHeight and collapsedHeight values. It is a convenience property that can be used to size the combo list content.

    import QtQuick 2.4
    import Lomiri.Components 1.3
    import Lomiri.Components.ListItems 1.3
    ComboButton {
        id: combo
        text: "Full comboList size"
        ListView {
            anchors {
                left: parent.left
                right: parent.right
            }
            height: combo.comboListHeight
            model: 20
            delegate: Standard {
                text: "Action #" + modelData
            }
        }
    }

See also collapsedHeight and expandedHeight.

expanded : bool

Specifies whether the combo list is expanded or not. The default falue is false.

expandedHeight : real

The property holds the maximum height value the component should expand. When setting the property, remember to take into account the collapsedHeight value. The best practice is to use bind it with collapsedHeight.

    ComboButton {
        text: "altered expandedHeight"
        expandedHeight: collapsedHeight + units.gu(25)
    }

A value of -1 will instruct the component to expand the combo list as much as its content height is.

The default value is collapsedHeight + 19.5 GU, so at least 3 ListItems can fit in the combo list.

See also collapsedHeight.

font : font

The font used for the button's text.

iconPosition : string

The position of the icon relative to the text. Options are "left" and "right". The default value is "left".

If only text or only an icon is defined, this property is ignored and the text or icon is centered horizontally and vertically in the button.

Currently this is a string value. We are waiting for support for enums: https://bugreports.qt-project.org/browse/QTBUG-14861