import QtQuick.Controls 2.5

ComboBox 是按钮和弹出列表的组合。它提供了一种以占用最少屏幕空间量的方式向用户显示选项列表的方法。

ComboBox 填充了数据模型。数据模型通常是 JavaScript 数组，ListModel 或 整数，但也支持其他类型的数据模型。

ComboBox 可以编辑。可编辑的组合框根据模型中可用的内容自动完成其文本。

以下示例演示了通过对接受的信号作出反应，将内容附加到可编辑的组合框。

ComboBox {
    editable: true
    model: ListModel {
        id: model
        ListElement { text: "Banana" }
        ListElement { text: "Apple" }
        ListElement { text: "Coconut" }
    }
    onAccepted: {
        if (find(editText) === -1)
            model.append({text: editText})
    }
}

ComboBox 能够可视化提供 modelData 角色的标准数据模型：

• 只有一个角色的模型
• 没有命名角色的模型（JavaScript 数组，整数）

当使用具有多个命名角色的模型时，为了显示其文本和代理实例，必须使用特定的 textRole 配置 ComboBox。

ComboBox {
    textRole: "key"
    model: ListModel {
        ListElement { key: "First"; value: 123 }
        ListElement { key: "Second"; value: 456 }
        ListElement { key: "Third"; value: 789 }
    }
}

注意：如果为 ComboBox 分配了一个具有多个命名角色的数据模型，但未定义 textRole，则ComboBox 无法将其可视化并抛出 ReferenceError: modelData is not defined。

属性

• acceptableInput：（bool）
  此属性控制组合框是否包含可编辑文本字段中的可接受文本。
  如果已设置验证程序，则仅当验证程序接受当前文本作为最终字符串（而不是中间字符串）时，该值才为 true。

• count：（int）组合框中的项目数

• currentIndex：（int，默认为 0；当 count 为 0 时为 -1）此属性保存组合框中当前项的索引。

• currentText：（string）组合框中当前项的文本。

• delegate：（Component）
  此属性包含一个委托，该委托在组合框弹出窗口中显示项目。
  建议使用 ItemDelegate（或任何其他AbstractButton衍生物）作为委托。这可确保交互按预期工作，并且弹出窗口将在适当时自动关闭。当其他类型用作委托时，必须手动关闭弹出窗口。例如，如果使用 MouseArea：

  delegate: Rectangle {
      // ...
      MouseArea {
          // ...
          onClicked: comboBox.popup.close()
      }
  }
  

• displayText：（string）
  此属性保存组合框按钮上显示的文本。
  默认情况下，显示文本显示当前选择。也就是说，它遵循当前项目的文本。但是，可以使用自定义值覆盖默认显示文本。

• down（bool）
  此属性保存组合框按钮是否在视觉上向下。
  除非明确设置，否则当 pressed 或 popup.visible 为 true 时，此属性为 true。要返回默认值，请将此属性设置为 undefined。

• editText：（string）
  此属性将文本保存在可编辑组合框的文本字段中。

• editable：（bool，默认为 false）
  此属性控制组合框是否可编辑。

• flat：（bool，默认为 false）
  此属性控制组合框按钮是否平坦。
  除非与之交互，否则平面组合框按钮不会绘制背景。与普通组合框相比，平面组合框提供的外观使其与UI的其余部分相比更加突出。
  例如，当将组合框放入工具栏时，可能需要使组合框平坦，以使其与工具按钮的平面外观更好地匹配。

• highlightedIndex：（int）
  此属性表示组合框弹出列表中突出显示项的索引。
  当高亮项目 activated 时，将关闭弹出窗口，将 currentIndex 设置为 highlightedIndex，并将此属性的值重置为 -1，因为不再有突出显示的项目。

• implicitIndicatorHeight：（real）
  此属性保存隐式指标高度。
  该值等于 indicator ? indicator.implicitHeight : 0。这通常与 implicitContentHeight 和 implicitBackgroundHeight 一起用于计算 implicitHeight。

• implicitIndicatorWidth：（real）
  此属性包含隐式指示符宽度。
  该值等于 indicator ? indicator.implicitWidth : 0。通常使用它与 implicitContentWidth 和 implicitBackgroundWidth 一起计算 implicitWidth。

• indicator：（Item）
  此属性包含拖放指示器项。

• inputMethodComposing：（bool）
  此属性表示可编辑组合框中是否具有部分文本输入采用某种输入方法。
  在编写时，输入方法可能依赖于组合框中的鼠标或键事件来编辑或提交部分文本。此属性可用于确定何时禁用可能干扰输入方法的正确操作的事件处理程序。

• inputMethodHints：（flags，默认值为Qt.ImhNoPredictiveText）
  为输入法提供有关组合框的预期内容及其操作方式的提示。
  如果没有设置提示，则该值是标志的逐位组合或 Qt.ImhNone。

  • 改变行为的标志有：
    • Qt.ImhHiddenText - 字符应该被隐藏，就像输入密码时通常使用的那样。
    • Qt.ImhSensitiveData - 活动输入法不应将类型文本存储在任何持久存储中，如预测用户字典。
    • Qt.ImhNoAutoUppercase - 当句子结束时，输入法不应尝试自动切换到大写。
    • Qt.ImhPreferNumbers - 数字是首选（但不是必需的）。
    • Qt.ImhPreferUppercase - 首选大写字母（但不是必需的）。
    • Qt.ImhPreferLowercase - 首选小写字母（但不是必需的）。
    • Qt.ImhNoPredictiveText - 输入时不要使用预测文本（即字典查找）。
    • Qt.ImhDate - 文本编辑器用作日期字段。
    • Qt.ImhTime - 文本编辑器用作时间字段。
  • 限制输入的标志（独占标志）有：
    • Qt.ImhDigitsOnly - 仅允许数字。
    • Qt.ImhFormattedNumbersOnly - 仅允许输入数字。这包括小数点和减号。
    • Qt.ImhUppercaseOnly - 仅允许大写字母输入。
    • Qt.ImhLowercaseOnly - 仅允许小写字母输入。
    • Qt.ImhDialableCharactersOnly - 仅允许适合电话拨号的字符。
    • Qt.ImhEmailCharactersOnly - 仅允许适用于电子邮件地址的字符。
    • Qt.ImhUrlCharactersOnly - 仅允许适合URL的字符。
  • 掩码：
    • Qt.ImhExclusiveInputMask - 如果使用任何独占标志，则此掩码会产生非零值。

• model：model
  此属性控制着为组合框提供数据的模型。

  ComboBox {
      textRole: "key"
      model: ListModel {
          ListElement { key: "First"; value: 123 }
          ListElement { key: "Second"; value: 456 }
          ListElement { key: "Third"; value: 789 }
      }
  }
  

• popup：（Popup）
  此属性包含弹出窗口。
  如有必要，可以手动打开或关闭弹出窗口：
  onSpecialEvent: comboBox.popup.close()

• pressed：（bool）
  此属性代表组合框按钮是否以物理的方式按下。触摸或按键事件可以按下按钮。

• textRole（string）
  此属性表示用于填充组合框的模型角色。
  当模型具有多个角色时，可以设置textRole以确定应显示哪个角色。

• validator：Validator
  此属性包含可编辑组合框的输入文本验证程序。
  设置验证程序时，文本字段仅接受使 text 属性处于中间状态的输入。只有在按下 Return 或 Enter 键时文本处于可接受状态时，才会发出 accepted 信号。
  The currently supported validators are IntValidator, DoubleValidator, and RegExpValidator. 下面显示了使用验证器的示例，它允许在文本字段中输入0到10之间的整数：

  ComboBox {
      model: 10
      editable: true
      validator: IntValidator {
          top: 9
          bottom: 0
      }
  }
  

信号

• void accepted()
  在可编辑的组合框上按下 Return 或 Enter 键时会发出此信号。
  如果确认的字符串当前不在模型中，则将 currentIndex 设置为 -1，并且 currentText 将相应地更新。
  注意：如果组合框上设置了 validator，则只有在输入处于 acceptable 状态时才会发出信号。

• void activated(int index)
  当用户激活索引处的项目时，将发出此信号。
  在弹出窗口打开时选择项目时会激活项目，导致弹出窗口关闭（和currentIndex 更改），或者弹出窗口关闭并且组合框通过键盘导航，导致currentIndex 更改。 currentIndex 属性设置为 index。

• void highlighted(int index)
  当弹出列表中索引处的项目被用户高亮时，将发出此信号。
  高亮信号仅在弹出窗口打开且项目高亮时发出，但不一定激活。

方法

• void decrementCurrentIndex()
  如果弹出列表可见，则递减组合框的当前索引或突出显示的索引。

• int find(string text, flags = Qt.MatchExactly)
  返回指定文本的索引，如果未找到匹配项，则返回 -1。
  执行搜索的方式由指定的匹配标志定义。
  默认情况下，组合框执行区分大小写的完全匹配（Qt.MatchExactly）。
  其余匹配类型除非指定了 Qt.MatchCaseSensitive，不然都不区分大小写。

  • 匹配标志定义
    • Qt.MatchExactly：搜索词完全匹配（默认）。
    • Qt.MatchRegExp：搜索词匹配为正则表达式。
    • Qt.MatchWildcard：搜索词匹配使用通配符。
    • Qt.MatchFixedString：搜索词匹配为固定字符串。
    • Qt.MatchStartsWith：搜索词匹配项的开头。
    • Qt.MatchEndsWidth：搜索词匹配项目的结尾。
    • Qt.MatchContains：搜索词包含在项目中。
    • Qt.MatchCaseSensitive：搜索区分大小写。

• void incrementCurrentIndex()
  如果弹出列表可见，则增加组合框的当前索引或高亮索引。

• void selectAll()
  选择组合框的可编辑文本字段中的所有文本

• string textAt(int index)
  返回指定索引的文本，如果索引超出范围，则返回空字符串。