MediaKeyWatcher

Since: BlackBerry 10.0.0

#include <bb/multimedia/MediaKeyWatcher>

To link against this class, add the following line to your .pro file: LIBS += -lbbmultimedia

Represents a hardware media key and provides notification.

If two MediaKeyWatcher objects reference the same MediaKey then the last one to connect the signal will receive the notification until all the slots are disconnected from that signal. A short press is defined as being less than 600ms in duration and a long press is 600ms or greater in duration.

There are two different notification types for this media key watcher. MediaKeyNotification::Clicked is the default and results in the respective press signals to be called when the hardware media key is released. MediaKeyNotification::Threshold causes a press to be signaled once the earliest connected signal threshold is reached (0ms for shortPress() and 600ms for longPress()). If both shortPress() and longPress() are connected, only the shortPress() signal will be emitted.

When all slots are disconnected from a signal, notification is returned to the last MediaKeyWatcher object that is connected to the signal of the same media key. Otherwise the default action from now playing is triggered. QML users can use a ComponentDefinition to dynamically allocate a MediaKeyWatcher when needed and destroy it when the button no longer needs to be watched. It is up to the developer to ensure a key is only watched when needed otherwise, as is the case with volume keys, core functionality could be affected for other applications.

C++ example:

       MediaKeyWatcher keyWatcher(MediaKey::VolumeUp);
       ...
       QObject::connect(&keyWatcher, SIGNAL(longPress(bb::multimedia::MediaKey::Type)), this, SLOT(onLongPress()));
       QObject::connect(&keyWatcher, SIGNAL(shortPress(bb::multimedia::MediaKey::Type)), this, SLOT(onShortPress()));

QML example:

    import bb.multimedia 1.0
    ...
    attachedObjects: [
      MediaKeyWatcher {
          id: keyWatcher
          key: MediaKey.VolumeUp

          onLongPress: {
            // do something
          }

          onShortPress: {
            // do something
          }
      }
    ]


Overview

Public Functions Index

MediaKeyWatcher (bb::multimedia::MediaKey::Type key, QObject *parent=0)
MediaKeyWatcher (QObject *parent=0)
virtual ~MediaKeyWatcher ()
bb::multimedia::MediaKey::Typekey () const
bb::multimedia::MediaKeyNotification::Typenotification () const

Public Slots Index

voidsetNotification (bb::multimedia::MediaKeyNotification::Type notification)

Signals Index

voidlongPress (bb::multimedia::MediaKey::Type key)
voidnotificationChanged (bb::multimedia::MediaKeyNotification::Type notification)
voidshortPress (bb::multimedia::MediaKey::Type key)

Properties

bb::multimedia::MediaKey::Type key[read-only]

Represents any of the media button types.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaKeyNotification::Type notification

Represents a media key notification for this media key watcher.

Since:

BlackBerry 10.1.0

Public Functions

MediaKeyWatcher (

Constructs a MediaKey object.

Create and associates a MediaKey with a specific media button.

Parameters
key

The MediaKey::Type to watch.

parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.0.0

MediaKeyWatcher (

Constructs a MediaKey object.

Create and associates a MediaKey with MediaKey::None.

Parameters
parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.0.0

virtual~MediaKeyWatcher ()

Destructor.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaKey::Type key ()

Provides the MediaKey associated with this watcher.

Return:

The media type that's providing notifications.

Since:

BlackBerry 10.0.0

bb::multimedia::MediaKeyNotification::Type notification ()

Provides the MediaKeyNotification associated with this key watcher.

Return:

The media key notification type.

Since:

BlackBerry 10.1.0

Public Slots

void setNotification (

Used to set the media key notification type.

When the notification type MediaKeyNotification::Clicked is set, the media key signals will not be emitted until the hardware key has been released. For MediaKeyWatcher::Threshold, the media key signal will be emitted as soon as the press threshold has been reached for the given length. In this case, the press signal will only occur for the earliest connected signal.

Parameters
notification

The media key notification type to use.

Since:

BlackBerry 10.1.0

Signals

void longPress (

Emitted for a media key long press.

This signal is emitted when the associated media button has been pressed for more than 600ms.

Parameters
key

The media key that was long pressed.

Since:

BlackBerry 10.0.0

void notificationChanged (

Emitted when the notification type has changed.

Parameters
notification

The new notification type.

Since:

BlackBerry 10.1.0

void shortPress (

Emitted for a media key short press.

This signal is emitted when the associated media button is pressed for less than 600ms.

Parameters
key

The media key that was short pressed.

Since:

BlackBerry 10.1.0

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus