Ubuntu.Components.Action

Describe an action that can be re-used and shared between different components. More...

• Obsolete members

Properties

• checkable : bool
• checked : bool
• description : string
• enabled : bool
• exclusiveGroup : ExclusiveGroup
• iconName : string
• iconSource : url
• keywords : string
• name : string
• parameterType : enum
• shortcut : var
• text : string
• visible : bool

Signals

• toggled(bool value)
• triggered(var value)

Methods

• trigger(var value)

Detailed Description

Actions can be used to define a specific task to be executed in different contexts using different components. The same action can be assigned to a Button, a Checkbox or even a TextField. The triggered signal is emitted depending on the component. Button and CheckBox for instance emits the signal when clicked, whereas TextField emits the signal when its accepted signal is triggered.

If the parameterType property is set, the Action is said to be parameterised. This means that when it is bound to a menu or button, the action expects a typed input parameter. The type affects the allowed value of the QVariant that must be passed to the trigger and triggered.

Action {
id: action
parameterType: Action.Integer
text: "Int value"
onTriggered: {
// the value will be undefined
console.log("value is", value);
}
Component.onCompleted: trigger("Hello World!")
}

When an Action is assigned to a component, the component takes the values from the action itself. Therefore assigning the action to a Button is enough to set up the label and the icon to be shown by the button.

Action {
id: stock
iconName: "call"
text: "Call"
}
Button {
// this binding will set the Button's text, iconName and
// iconSource properties.
action: stock
}

Actions are used to populate different Popovers like ActionSelectionPopover as well as to define actions for pages, or when defining options in ListItemOptions.

Examples: See Page

Mnemonics

Since Ubuntu.Components 1.3 Action supports mnemonics. Mnemonics are shortcuts defined in the text property, prefixed the shortcut letter with &. For instance "\&Call" will bint the "Alt-C" shortcut to the action. When a mnemonic is detected on the Action and a keyboard is attached to the device, the text property will provide a formatted text having the mnemonic letter underscored.

Action {
id: call
iconName: "call"
text: "&Call"
}

Checkable property

Since Ubuntu.Components 1.3 Action supports the checkable/checked properties.

Button {
action: Action {
checkable: true
checked: false
}
color: action.checked ? UbuntuColor.green : UbuntuColor.red
}

Property Documentation

Whether the action can be checked. Defaults to false.

This QML property was introduced in Ubuntu.Components 1.3.

See also Action::checked, Action::toggled, and ExclusiveGroup.

If the action is checkable, this property reflects its checked state. Defaults to false. Its value is also false while checkable is false.

This QML property was introduced in Ubuntu.Components 1.3.

See also Action::checkable, Action::toggled, and ExclusiveGroup.

User visible secondary description for the action. Description is more verbose than the text and should describe the Action with couple of words.

If set to false the action can not be triggered. Components visualizing the action migth either hide the action or make it insensitive. However visibility can be controlled separately using the visible property.

The ExclusiveGroup associated with this action. An exclusive group allows the checked property to belinked to other actions, as in radio controls.

Column {
ExclusiveGroup {
Action {
id: action1
checkable: true
checked: true
}
Action {
id: action2
checkable: true
}
Action {
id: action3
checkable: true
}
}
Button {
action: action1
color: action.checked ? UbuntuColor.green : UbuntuColor.red
}
Button {
action: action2
color: action.checked ? UbuntuColor.green : UbuntuColor.red
}
Button {
action: action3
color: action.checked ? UbuntuColor.green : UbuntuColor.grey
}
}

This QML property was introduced in Ubuntu.Components 1.3.

The icon associated with the action. If both iconName and iconSource are defined, iconName will be ignored by the components.

Note: The complete list of icons available in Ubuntu is not published yet. For now please refer to the folder where the icon theme is installed:

• Ubuntu Touch: /usr/share/icons/suru

This is a URL to any image file. In order to use an icon from the Ubuntu theme, use the iconName property instead.

Additional user visible keywords for the action. The format of the keywords string is "Keyword 1;Keyword 2;Keyword 3" to allow translators to define different number of keywords per language. The keywords are separated by ; and they may contain spaces.

Action {
text: i18n.tr("Crop")
description: i18n.tr("Crop the image")
keywords: i18n.tr("Trim;Cut")
}

The name of the action. By default an action gets it's name generated automatically if not overridden with later. If name is set to "" then the action restores it's autogenerated name. The name is not user visible.

Type of the parameter passed to trigger and triggered. Type is an enumeration:

• Action.None: No paramater. (default)
• Action.String: String parameter.
• Action.Integer: Integer parameter.
• Action.Bool: Boolean parameter.
• Action.Real: Single precision floating point parameter.
• Action.Object: The parameter is an object.

Action {
id: action
parameterType: Action.String
onTriggered: {
// value arguments now contain strings
console.log(value);
}
Component.onCompleted: action.trigger("Hello World")
}

The keyboard shortcut that can be used to trigger the action. StandardKey values such as StandardKey.Copy as well as strings in the form "Ctrl+C" are accepted values.

This QML property was introduced in Qt 1.3.

The user visible primary label of the action.

Mnemonics are shortcuts prefixed in the text with &. If the text has multiple occurences of the & character, the first one will be considered for the shortcut. However && can be used for a single & in the text, not as a mnemonic. The & character cannot be used as shortcut.

Specifies whether the action is visible to the user. Defaults to true.

Signal Documentation

Signal called when the action's checked property changes.

Note: The toggled signal should be used for checkable actions rather than the triggered signal.

See also Action::checkable, Action::checked, and ExclusiveGroup.

Signal called when the action is triggered. The user visible primary label of the action when emitted by components. Custom implementations must make sure this rule is followed, therefore instead of emitting the signal the trigger function should be called.

Method Documentation

Checks the value against the action parameterType and triggers the action. If parameterType is Action.None, it will trigger as

action.trigger()