# Action QML Type

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

Import Statement: | import Lomiri.Components 1.3

- List of all members, including inherited members
- 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 Lomiri.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 Lomiri.Components 1.3 Action supports the checkable/checked properties.

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

## Property Documentation

checkable : bool

Whether the action can be checked. Defaults to false.

This property was introduced in Lomiri.Components 1.3.

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

checked : bool

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

This property was introduced in Lomiri.Components 1.3.

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

description : string

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

enabled : bool

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.

exclusiveGroup : ExclusiveGroup

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 ? LomiriColor.green : LomiriColor.red
        }
        Button {
            action: action2
            color: action.checked ? LomiriColor.green : LomiriColor.red
        }
        Button {
            action: action3
            color: action.checked ? LomiriColor.green : LomiriColor.grey
        }
    }

This property was introduced in Lomiri.Components 1.3.

iconName : string

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 Lomiri is not published yet. For now please refer to the folder where the icon theme is installed:

- Lomiri Touch: /usr/share/icons/suru

iconSource : url

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

keywords : string

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")
    }

name : string

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.

parameterType : enum

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")
    }

shortcut : var

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 property was introduced in Qt 1.3.

text : string

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.

visible : bool

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

## Signal Documentation

toggled(bool value)

Signal called when the action's checked property changes.

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

Note: The corresponding handler is `onToggled`.

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

triggered(var value)

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.

Note: The corresponding handler is `onTriggered`.

## Method Documentation

trigger(var value)

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

    action.trigger()