- Qt 5.0
- QFeedbackEffect
- Qt 5.0.0 Reference Documentation

# QFeedbackEffect Class

The QFeedbackEffect class is the abstract base class for feedback effects. More...

Header: | #include <QFeedbackEffect>
Inherited By: | QFeedbackHapticsEffect

- List of all members, including inherited members

## Public Types

enum | Duration { Infinite }
enum | Effect { Effect.Undefined, Effect.Press, Effect.Release, Effect.PressWeak, Effect.ReleaseWeak, …, UserEffect }
enum | ErrorType { UnknownError, DeviceBusy }
enum | State { Stopped, Paused, Running, Loading }

## Properties

- duration : const int
- state : const State

## Public Functions

| QFeedbackEffect(QObject *parent = Q_NULLPTR)
virtual int | duration() const = 0
virtual State | state() const = 0

## Public Slots

void | pause()
void | start()
void | stop()

## Signals

void | error(QFeedbackEffect::ErrorType error) const
void | stateChanged()

## Static Public Members

bool | playThemeEffect(Effect effect)
bool | supportsThemeEffect()

## Protected Functions

virtual void | setState(State state) = 0

## Detailed Description

It represents an effect to provide feedback to a person (i.e., an effect that affect human senses). The technology available today usually only provides haptic effects, which deal with the sense of touch, and audio effects. The QFeedbackHapticsEffect and QFeedbackFileEffect are implementations of haptic effects and can be used to control a mobile device's vibrator. In addition, the QFeedbackFileEffect can also be used to play audio feedback.

Feedback effects have a duration, which is measured in milliseconds. Subclasses reimplement duration() to inform how long the effect lasts. The duration is the total time the effect will last, and thus includes any envelope modifiers (attack and fade).

At any given time, a feedback effect is in one of four states: Loading, Stopped, Running, or Paused. See the State enum documentation for further details. Subclasses must reimplement state() to report which state an effect is in, and setState() to receive state change requests. The start(), pause(), and stop() slots calls setState() with the corresponding new State. Changes in state are reported through the stateChanged() signal and may happen asynchronously some time after the state change request.

A system often has a set of standard feedback effects for user interface interaction (e.g., button clicks). The Effect describes the standard effects that QFeedbackEffect supports. It is named so because the effects often depend on the theme of the user interface. You can play these effects using the playThemeEffect() function.

     QFeedbackEffect::playThemeEffect(QFeedbackEffect::Press);

The playThemeEffect() function returns true if the effect was played successfully. An effect may not be played if the system does not support it or if an error occurred.

## Member Type Documentation

### enum QFeedbackEffect::Duration

This enum describes the possible effect predefined duration types. Generally a specific milliseconds value can be supplied instead of one of these values.

Constant | Value | Description
--- | --- | ---
`QFeedbackEffect::Infinite` | `-1` | Infinite effect duration

### enum QFeedbackEffect::Effect

This enum describes all possible effect types. Effects might be tactile, or audio or visual.

Not all platforms and devices have distinct effects for each type.

Constant | Value | Description
--- | --- | ---
`QFeedbackEffect::Effect.Undefined` | ? | - Undefined feedback. No feedback is given.
`QFeedbackEffect::Effect.Press` | ? | - Feedback for when the screen is pressed.
`QFeedbackEffect::Effect.Release` | ? | - Feedback for touch release.
`QFeedbackEffect::Effect.PressWeak` | ? | - A weak feedback for press.
`QFeedbackEffect::Effect.ReleaseWeak` | ? | - A weak feedback for release.
`QFeedbackEffect::Effect.PressStrong` | ? | - A strong feedback for press.
`QFeedbackEffect::Effect.ReleaseStrong` | ? | - A strong feedback for release.
`QFeedbackEffect::Effect.DragStart` | ? | - Feedback for when dragging starts.
`QFeedbackEffect::Effect.DragDropInZone` | ? | - Feedback for when dragging ends and touch is released inside a drop zone.
`QFeedbackEffect::Effect.DragDropOutOfZone` | ? | - Feedback for when dragging ends and touch is released outside a drop zone.
`QFeedbackEffect::Effect.DragCrossBoundary` | ? | - Feedback for when crossing a boundary while dragging.
`QFeedbackEffect::Effect.Appear` | ? | - Feedback for when an item is shown.
`QFeedbackEffect::Effect.Disappear` | ? | - Feedback for when an item is closed.
`QFeedbackEffect::Effect.Move` | ? | - Feedback for dragging on screen.
`QFeedbackEffect::NumberOfEffects` | `13` | The number of built-in effects.
`QFeedbackEffect::UserEffect` | `65535` | The starting point for any user defined effects, where supported.

### enum QFeedbackEffect::ErrorType

This enum describes the possible errors happening on the effect.

Constant | Value | Description
--- | --- | ---
`QFeedbackEffect::UnknownError` | `0` | An unknown error occurred.
`QFeedbackEffect::DeviceBusy` | `1` | The feedback could not start because the device is busy.

See also error().

### enum QFeedbackEffect::State

This enum describes the state of the effect. An effect will be in one of these states.

Constant | Value | Description
--- | --- | ---
`QFeedbackEffect::Stopped` | `0` | The effect is not running. This is the initial state. The state changes to either Loading when loading an effect or to Running when the effect is started by calling start(). When an effect has finished playing, it will enter the Stopped state again.
`QFeedbackEffect::Paused` | `1` | The effect is paused. Calling start() will resume it.
`QFeedbackEffect::Running` | `2` | The effect is running. You can control the current state by calling the stop() or pause() functions.
`QFeedbackEffect::Loading` | `3` | The effect is loading. That can happen when loading is done asynchronously. When the effect has loaded, the state will change to either Running (if start() has been called) or Stopped.

See also state().

## Property Documentation

### duration : const int

duration of the feedback effect, in milliseconds.

In some cases the duration will be unknown, which will be reported as 0. If the duration is infinite, QFeedbackEffect::Infinite will be returned. Some subclasses may have more than one type of duration (for example, QFeedbackHapticsEffect), and this property will return the total duration of the effect.

Access functions:

virtual int | duration() const = 0

### state : const State

state of the feedback effect.

This returns the state of the feedback effect. The State enumeration reports the possible states.

Access functions:

virtual State | state() const = 0

Notifier signal:

void | stateChanged()

## Member Function Documentation

### QFeedbackEffect::QFeedbackEffect(QObject *parent = Q_NULLPTR)

Constructs the QFeedbackEffect base class, and passes parent to QObject's constructor. This is called by the classes that inherit from this class.

### `[signal]` void QFeedbackEffect::error(QFeedbackEffect::ErrorType error) const

This signal is emitted by subclasses if an error occurred during playback of an effect. The ErrorType enum describes the errors that can be reported.

### `[slot]` void QFeedbackEffect::pause()

Pauses a playing effect. If an error occurs the error() signal will be emitted. Not all systems support pausing an effect during playback.

### `[slot]` void QFeedbackEffect::start()

Starts playing the effect. If an error occurs the error() signal will be emitted.

See also stop().

### `[signal]` void QFeedbackEffect::stateChanged()

This signal is emitted by subclasses when the State of the effect changes.

Note: Notifier signal for property state.

See also state().

### `[slot]` void QFeedbackEffect::stop()

Stops a playing effect. If an error occurs the error() signal will be emitted.

See also start(), pause(), and setState().

### `[static]` bool QFeedbackEffect::playThemeEffect(Effect effect)

This function plays effect instantly and returns true if the effect could be played; otherwise, returns false.

### `[pure virtual protected]` void QFeedbackEffect::setState(State state)

Requests the effect to change its State to change to the specified state.

Subclasses reimplement this function to handle state change requests for the effect.

See also state().

### `[static]` bool QFeedbackEffect::supportsThemeEffect()

Returns true if playing themed feedback is available.