DTK 用于指定控件颜色的统一取色辅助器. 更多...

详细描述

DTK 用于指定控件颜色的统一取色辅助器.

\keyword DQuickControlColorSelector

取色器作为一个能够自动获取控件不同状态，并根据该状态选择合适的颜色的角色而存在。目的是用于
简便控件状态的使用，自动并高效的指定控件颜色。使用取色器作用在控件上时，处理颜色的过程更加
简单，只需要在控件中指定对应属性的调色板信息，在需要使用的地方，使用取色器直接使用就能达到
跟随状态自动改变的效果。

由于需要在控件中指定不同的调色板颜色属性，因此外部可以通过更改该属性而达到修改取色器颜色值
进行颜色替换的效果，每个控件中都具备相同类型的属性，如 “backgroundColor” 背景颜色属性，
“textColor” 文字颜色属性等等。除此之外，取色器能够高级的只监听某一种控件状态，如
“Button” 的 “hovered” 或 “Pressed” 状态。同时取色器能够根据系统主题信息，自动选择
对应主题下的调色板属性。

颜色控制系统可以分为三个层次：调色板、控件属性和取色器。取色器作为监听者，能够监听这二者的变
化，除此之外，取色器会根据当前绑定的控件状态、控件对象等等信息自动更改颜色。下面给出一个简单
的示例代码：

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 500
    height: 50
 
    property Palette backgroundColor: Palette {
        normal: "black"
    }
    property Palette textColor: Palette {
        normal: "white"
    }
 
    contentItem: Text {
        text: "Test......."
        color: control.ColorSelector.textColor
        horizontalAlignment: Qt.AlignHCenter
        verticalAlignment: Qt.AlignVCenter
    }
 
    background: Rectangle {
        width: 250
        height: 50
        color: control.ColorSelector.backgroundColor
    }
}

\note 当控件类型继承于 Control 或者控件存在调色板数据时，该控件的 ColorSelector 附加属性才会被创建。
\note 如果当前控件非继承于 Control类型，且具备创建 ColorSelector 的条件，该 ColorSelector 将寻找其最
    上层父类的 Control 控件，并进行调色板和控件状态的更新绑定。
\note ColorSelector 仅会监听当前控件和离它最近的父类 Control控件的调色板属性。其中间父类不论是否存在
    ColorSelector 对象，都不会读取和绑定。

ColorSelector 在下述变化的场景中，同样能够跟随控件发生变化。
\section2 ColorSelector 可跟随控件状态发生变化
当 Control 开启 hoverEnabled 属性后，ColorSelector 能够监听控件状态的变化过程，并跟随发生属性的颜色变化

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 50
    height: 50
    hoverEnabled: true
    property Palette backgroundColor: Palette {
        normal: "red"
        hovered: "green"
    }
 
    background: Rectangle {
        anchors.fill: parent
        color: control.ColorSelector.backgroundColor
    }
}

\section1 ColorSelector 的颜色属性
\section2 ColorSelector 跟随手动修改后的调色板颜色而变化
可通过直接修改调色板的在某个状态额颜色值，而直接更新 ColorSelecotor 读取出来的调色板
属性颜色，如下述代码所示：

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 50
    height: 50
    hoverEnabled: true
 
    background: Rectangle {
        id: rect
        property Palette backgroundColor: Palette {
            normal: "red"
            hovered: "green"
        }
        color: ColorSelector.backgroundColor
        anchors.fill: parent
 
        MouseArea {
            anchors.fill: parent
            onClicked: {
                rect.backgroundColor.hovered = "yellow"
            }
        }
    }
}

可通过直接赋值的方式，替换 ColorSelector 记录的整个调色板数据，如下述代码所示：

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 50
    height: 50
    hoverEnabled: true
 
    background: Rectangle {
        id: rect
        property Palette backgroundColor: Palette {
            normal: "red"
            hovered: "green"
        }
        anchors.fill: parent
        color: ColorSelector.backgroundColor
 
        MouseArea {
            Palette {
                id: otherPalette
                normal: "black"
                hovered: "gray"
            }
            anchors.fill: parent
            onClicked: {
                rect.backgroundColor = otherPalette
            }
        }
    }
}

\section2 ColorSelector 响应自身属性值的变化
上述替换调色板属性，同样也可通过 ColorSelector 进行替换。如下述代码所示：

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 50
    height: 50
    hoverEnabled: true
 
    background: Rectangle {
        id: rect
        property Palette backgroundColor: Palette {
            normal: "red"
            hovered: "green"
        }
        anchors.fill: parent
        color: ColorSelector.backgroundColor
 
        MouseArea {
            anchors.fill: parent
            onClicked: {
                Palette {
                    id: otherOPalette
                    normal: "black"
                    hovered: "gray"
                }
                rect.ColorSelector.backgroundColor = otherPalette
            }
        }
    }
}

替换后的属性值，可通过赋值为 undefined 进行复原，如下述代码所示：

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 50
    height: 50
    hoverEnabled: true
 
    background: Rectangle {
        id: rect
        property Palette backgroundColor: Palette {
            normal: "red"
            hovered: "green"
        }
        anchors.fill: parent
        color: ColorSelector.backgroundColor
 
        MouseArea {
            anchors.fill: parent
            onClicked: {
                Palette {
                    id: otherPalette
                    normal: "black"
                    hovered: "gray"
                }
                rect.ColorSelector.backgroundColor = otherPalette
            }
            onDoubleClicked: {
                // 复原
                rect.ColorSelector.backgroundColor = undefined
            }
        }
    }
}

\section2 ColorSelector 对于自身没有的调色板属性，会从上层 Control 寻找
ColorSelector 属性能够获取其自身对象以及其最近的 Control 控件的调色板属性，并监听 Control 控件的状态变化，
进行颜色属性的自动更新。如下述代码所示：

import org.deepin.dtk 1.0
 
Control {
    id: control
    width: 200
    height: 200
    hoverEnabled: true
    property Palette backgroundColor: Palette {
        normal: "red"
        hovered: "green"
    }
 
    background: Rectangle {
        property Palette borderColor: Palette {
            normal: "blue"
            hovered: "yellow"
        }
        // 获取 Control 类中的 backgroundColor 调色板属性
        color: ColorSelector.backgroundColor
        border.width: 2
        // 获取自身的 borderColor 调色板属性
        border.color: ColorSelector.borderColor
    }
}

警告: 需要注意的是， Control 控件的子控件，如果其自身不存在任何调色板属性，将不会为它创建 ColorSelector 对象。因此上述方式只能作用于子控件存在调色板属性的场景。

该类的文档由以下文件生成:

docs/qml/noqml/dquickcontrolpalette.zh_CN.dox