GI.GstVideo.Interfaces.Navigation

The Navigation interface is used for creating and injecting navigation related events such as mouse button presses, cursor motion and key presses. The associated library also provides methods for parsing received events, and for sending and receiving navigation related bus events. One main usecase is DVD menu navigation.

The main parts of the API are:

• The GstNavigation interface, implemented by elements which provide an application with the ability to create and inject navigation events into the pipeline.
• GstNavigation event handling API. GstNavigation events are created in response to calls on a GstNavigation interface implementation, and sent in the pipeline. Upstream elements can use the navigation event API functions to parse the contents of received messages.
• GstNavigation message handling API. GstNavigation messages may be sent on the message bus to inform applications of navigation related changes in the pipeline, such as the mouse moving over a clickable region, or the set of available angles changing.

The GstNavigation message functions provide functions for creating and parsing custom bus messages for signaling GstNavigation changes.

Exported types

newtype Navigation

Memory-managed wrapper type.

Constructors

Navigation (ManagedPtr Navigation)

Instances

Eq Navigation

Defined in GI.GstVideo.Interfaces.Navigation

Methods

(==) :: Navigation -> Navigation -> Bool

(/=) :: Navigation -> Navigation -> Bool

BoxedPtr Navigation

Defined in GI.GstVideo.Interfaces.Navigation

Methods

boxedPtrCopy :: Navigation -> IO Navigation

boxedPtrFree :: Navigation -> IO ()

ManagedPtrNewtype Navigation

Defined in GI.GstVideo.Interfaces.Navigation

Methods

toManagedPtr :: Navigation -> ManagedPtr Navigation

class (ManagedPtrNewtype o, IsDescendantOf Navigation o) => IsNavigation o

Type class for types which implement Navigation.

Instances

(ManagedPtrNewtype o, IsDescendantOf Navigation o) => IsNavigation o

Defined in GI.GstVideo.Interfaces.Navigation

Methods

Click to display all available methods, including inherited ones

Methods

sendCommand, sendEvent, sendEventSimple, sendKeyEvent, sendMouseEvent, sendMouseScrollEvent.

Getters

None.

Setters

None.

eventGetCoordinates

navigationEventGetCoordinates

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: The Event to inspect.

-> m (Bool, Double, Double)

Returns: A boolean indicating success.

Try to retrieve x and y coordinates of a Navigation event.

Since: 1.22

eventGetType

navigationEventGetType

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m NavigationEventType

Inspect a Event and return the NavigationEventType of the event, or GST_NAVIGATION_EVENT_INVALID if the event is not a Navigation event.

eventNewCommand

navigationEventNewCommand

Arguments

:: (HasCallStack, MonadIO m)

=> NavigationCommand

command: The navigation command to use.

-> m Event

Returns: a new Event

Create a new navigation event given navigation command..

Since: 1.22

eventNewKeyPress

navigationEventNewKeyPress

Arguments

:: (HasCallStack, MonadIO m)

=> Text

key: A string identifying the key press.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for the given key press.

Since: 1.22

eventNewKeyRelease

navigationEventNewKeyRelease

Arguments

:: (HasCallStack, MonadIO m)

=> Text

key: A string identifying the released key.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for the given key release.

Since: 1.22

eventNewMouseButtonPress

navigationEventNewMouseButtonPress

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

button: The number of the pressed mouse button.

-> Double

x: The x coordinate of the mouse cursor.

-> Double

y: The y coordinate of the mouse cursor.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for the given key mouse button press.

Since: 1.22

eventNewMouseButtonRelease

navigationEventNewMouseButtonRelease

Arguments

:: (HasCallStack, MonadIO m)

=> Int32

button: The number of the released mouse button.

-> Double

x: The x coordinate of the mouse cursor.

-> Double

y: The y coordinate of the mouse cursor.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for the given key mouse button release.

Since: 1.22

eventNewMouseMove

navigationEventNewMouseMove

Arguments

:: (HasCallStack, MonadIO m)

=> Double

x: The x coordinate of the mouse cursor.

-> Double

y: The y coordinate of the mouse cursor.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for the new mouse location.

Since: 1.22

eventNewMouseScroll

navigationEventNewMouseScroll

Arguments

:: (HasCallStack, MonadIO m)

=> Double

x: The x coordinate of the mouse cursor.

-> Double

y: The y coordinate of the mouse cursor.

-> Double

deltaX: The x component of the scroll movement.

-> Double

deltaY: The y component of the scroll movement.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for the mouse scroll.

Since: 1.22

eventNewTouchCancel

navigationEventNewTouchCancel

Arguments

:: (HasCallStack, MonadIO m)

=> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event signalling that all currently active touch points are cancelled and should be discarded. For example, under Wayland this event might be sent when a swipe passes the threshold to be recognized as a gesture by the compositor.

Since: 1.22

eventNewTouchDown

navigationEventNewTouchDown

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

identifier: A number uniquely identifying this touch point. It must stay unique to this touch point at least until an up event is sent for the same identifier, or all touch points are cancelled.

-> Double

x: The x coordinate of the new touch point.

-> Double

y: The y coordinate of the new touch point.

-> Double

pressure: Pressure data of the touch point, from 0.0 to 1.0, or NaN if no data is available.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for an added touch point.

Since: 1.22

eventNewTouchFrame

navigationEventNewTouchFrame

Arguments

:: (HasCallStack, MonadIO m)

=> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event signalling the end of a touch frame. Touch frames signal that all previous down, motion and up events not followed by another touch frame event already should be considered simultaneous.

Since: 1.22

eventNewTouchMotion

navigationEventNewTouchMotion

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

identifier: A number uniquely identifying this touch point. It must correlate to exactly one previous touch_start event.

-> Double

x: The x coordinate of the touch point.

-> Double

y: The y coordinate of the touch point.

-> Double

pressure: Pressure data of the touch point, from 0.0 to 1.0, or NaN if no data is available.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for a moved touch point.

Since: 1.22

eventNewTouchUp

navigationEventNewTouchUp

Arguments

:: (HasCallStack, MonadIO m)

=> Word32

identifier: A number uniquely identifying this touch point. It must correlate to exactly one previous down event, but can be reused after sending this event.

-> Double

x: The x coordinate of the touch point.

-> Double

y: The y coordinate of the touch point.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Event

Returns: a new Event

Create a new navigation event for a removed touch point.

Since: 1.22

eventParseCommand

navigationEventParseCommand

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, NavigationCommand)

Returns: TRUE if the navigation command could be extracted, otherwise FALSE.

Inspect a Navigation command event and retrieve the enum value of the associated command.

eventParseKeyEvent

navigationEventParseKeyEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, Text)

Note: Modifier keys (as defined in NavigationModifierType) press and release events are generated even if those states are present on all other related events

eventParseModifierState

navigationEventParseModifierState

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: The Event to modify.

-> [NavigationModifierType]

state: a bit-mask representing the state of the modifier keys (e.g. Control, Shift and Alt).

-> m Bool

Returns: TRUE if the event is a Navigation event with associated modifiers state, otherwise FALSE.

No description available in the introspection data.

Since: 1.22

eventParseMouseButtonEvent

navigationEventParseMouseButtonEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, Int32, Double, Double)

Returns: TRUE if the button number and both coordinates could be extracted, otherwise FALSE.

Retrieve the details of either a Navigation mouse button press event or a mouse button release event. Determine which type the event is using navigationEventGetType to retrieve the NavigationEventType.

eventParseMouseMoveEvent

navigationEventParseMouseMoveEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, Double, Double)

Returns: TRUE if both coordinates could be extracted, otherwise FALSE.

Inspect a Navigation mouse movement event and extract the coordinates of the event.

eventParseMouseScrollEvent

navigationEventParseMouseScrollEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, Double, Double, Double, Double)

Returns: TRUE if all coordinates could be extracted, otherwise FALSE.

Inspect a Navigation mouse scroll event and extract the coordinates of the event.

Since: 1.18

eventParseTouchEvent

navigationEventParseTouchEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, Word32, Double, Double, Double)

Returns: TRUE if all details could be extracted, otherwise FALSE.

Retrieve the details of a Navigation touch-down or touch-motion event. Determine which type the event is using navigationEventGetType to retrieve the NavigationEventType.

Since: 1.22

eventParseTouchUpEvent

navigationEventParseTouchUpEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: A Event to inspect.

-> m (Bool, Word32, Double, Double)

Returns: TRUE if all details could be extracted, otherwise FALSE.

Retrieve the details of a Navigation touch-up event.

Since: 1.22

eventSetCoordinates

navigationEventSetCoordinates

Arguments

:: (HasCallStack, MonadIO m)

=> Event

event: The Event to modify.

-> Double

x: The x coordinate to set.

-> Double

y: The y coordinate to set.

-> m Bool

Returns: A boolean indicating success.

Try to set x and y coordinates on a Navigation event. The event must be writable.

Since: 1.22

messageGetType

navigationMessageGetType

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A Message to inspect.

-> m NavigationMessageType

Returns: The type of the Message, or GST_NAVIGATION_MESSAGE_INVALID if the message is not a Navigation notification.

Check a bus message to see if it is a Navigation event, and return the NavigationMessageType identifying the type of the message if so.

messageNewAnglesChanged

navigationMessageNewAnglesChanged

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: A Object to set as source of the new message.

-> Word32

curAngle: The currently selected angle.

-> Word32

nAngles: The number of viewing angles now available.

-> m Message

Returns: The new Message.

Creates a new Navigation message with type GST_NAVIGATION_MESSAGE_ANGLES_CHANGED for notifying an application that the current angle, or current number of angles available in a multiangle video has changed.

messageNewCommandsChanged

navigationMessageNewCommandsChanged

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: A Object to set as source of the new message.

-> m Message

Returns: The new Message.

Creates a new Navigation message with type GST_NAVIGATION_MESSAGE_COMMANDS_CHANGED

messageNewEvent

navigationMessageNewEvent

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: A Object to set as source of the new message.

-> Event

event: A navigation Event

-> m Message

Returns: The new Message.

Creates a new Navigation message with type GST_NAVIGATION_MESSAGE_EVENT.

Since: 1.6

messageNewMouseOver

navigationMessageNewMouseOver

Arguments

:: (HasCallStack, MonadIO m, IsObject a)

=> a

src: A Object to set as source of the new message.

-> Bool

active: True if the mouse has entered a clickable area of the display. False if it over a non-clickable area.

-> m Message

Returns: The new Message.

Creates a new Navigation message with type GST_NAVIGATION_MESSAGE_MOUSE_OVER.

messageParseAnglesChanged

navigationMessageParseAnglesChanged

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A Message to inspect.

-> m (Bool, Word32, Word32)

Returns: True if the message could be successfully parsed. False if not.

Parse a Navigation message of type GST_NAVIGATION_MESSAGE_ANGLES_CHANGED and extract the curAngle and nAngles parameters.

messageParseEvent

navigationMessageParseEvent

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A Message to inspect.

-> m (Bool, Event)

Returns: True if the message could be successfully parsed. False if not.

Parse a Navigation message of type GST_NAVIGATION_MESSAGE_EVENT and extract contained Event. The caller must unref the event when done with it.

Since: 1.6

messageParseMouseOver

navigationMessageParseMouseOver

Arguments

:: (HasCallStack, MonadIO m)

=> Message

message: A Message to inspect.

-> m (Bool, Bool)

Returns: True if the message could be successfully parsed. False if not.

Parse a Navigation message of type GST_NAVIGATION_MESSAGE_MOUSE_OVER and extract the active/inactive flag. If the mouse over event is marked active, it indicates that the mouse is over a clickable area.

queryGetType

navigationQueryGetType

Arguments

:: (HasCallStack, MonadIO m)

=> Query

query: The query to inspect

-> m NavigationQueryType

Returns: The NavigationQueryType of the query, or GST_NAVIGATION_QUERY_INVALID

Inspect a Query and return the NavigationQueryType associated with it if it is a Navigation query.

queryNewAngles

navigationQueryNewAngles

Arguments

:: (HasCallStack, MonadIO m)

=> m Query

Returns: The new query.

Create a new Navigation angles query. When executed, it will query the pipeline for the set of currently available angles, which may be greater than one in a multiangle video.

queryNewCommands

navigationQueryNewCommands

Arguments

:: (HasCallStack, MonadIO m)

=> m Query

Returns: The new query.

Create a new Navigation commands query. When executed, it will query the pipeline for the set of currently available commands.

queryParseAngles

navigationQueryParseAngles

Arguments

:: (HasCallStack, MonadIO m)

=> Query

query: a Query

-> m (Bool, Word32, Word32)

Returns: True if the query could be successfully parsed. False if not.

Parse the current angle number in the Navigation angles query into the guint pointed to by the curAngle variable, and the number of available angles into the guint pointed to by the nAngles variable.

queryParseCommandsLength

navigationQueryParseCommandsLength

Arguments

:: (HasCallStack, MonadIO m)

=> Query

query: a Query

-> m (Bool, Word32)

Returns: True if the query could be successfully parsed. False if not.

Parse the number of commands in the Navigation commands query.

queryParseCommandsNth

navigationQueryParseCommandsNth

Arguments

:: (HasCallStack, MonadIO m)

=> Query

query: a Query

-> Word32

nth: the nth command to retrieve.

-> m (Bool, NavigationCommand)

Returns: True if the query could be successfully parsed. False if not.

Parse the Navigation command query and retrieve the nth command from it into cmd. If the list contains less elements than nth, cmd will be set to GST_NAVIGATION_COMMAND_INVALID.

querySetAngles

navigationQuerySetAngles

Arguments

:: (HasCallStack, MonadIO m)

=> Query

query: a Query

-> Word32

curAngle: the current viewing angle to set.

-> Word32

nAngles: the number of viewing angles to set.

-> m ()

Set the Navigation angles query result field in query.

querySetCommandsv

navigationQuerySetCommandsv

Arguments

:: (HasCallStack, MonadIO m)

=> Query

query: a Query

-> [NavigationCommand]

cmds: An array containing nCmds gstNavigationCommand values.

-> m ()

Set the Navigation command query result fields in query. The number of commands passed must be equal to nCommands.

sendCommand

navigationSendCommand

Arguments

:: (HasCallStack, MonadIO m, IsNavigation a)

=> a

navigation: The navigation interface instance

-> NavigationCommand

command: The command to issue

-> m ()

Sends the indicated command to the navigation interface.

sendEvent

navigationSendEvent :: (HasCallStack, MonadIO m, IsNavigation a) => a -> Structure -> m ()

No description available in the introspection data.

sendEventSimple

navigationSendEventSimple

Arguments

:: (HasCallStack, MonadIO m, IsNavigation a)

=> a

navigation: The navigation interface instance

-> Event

event: The event to send

-> m ()

Sends an event to the navigation interface.

Since: 1.22

sendKeyEvent

navigationSendKeyEvent

Arguments

:: (HasCallStack, MonadIO m, IsNavigation a)

=> a

navigation: The navigation interface instance

-> Text

event: The type of the key event. Recognised values are "key-press" and "key-release"

-> Text

key: Character representation of the key. This is typically as produced by XKeysymToString.

-> m ()

No description available in the introspection data.

sendMouseEvent

navigationSendMouseEvent

Arguments

:: (HasCallStack, MonadIO m, IsNavigation a)

=> a

navigation: The navigation interface instance

-> Text

event: The type of mouse event, as a text string. Recognised values are "mouse-button-press", "mouse-button-release" and "mouse-move".

-> Int32

button: The button number of the button being pressed or released. Pass 0 for mouse-move events.

-> Double

x: The x coordinate of the mouse event.

-> Double

y: The y coordinate of the mouse event.

-> m ()

Sends a mouse event to the navigation interface. Mouse event coordinates are sent relative to the display space of the related output area. This is usually the size in pixels of the window associated with the element implementing the Navigation interface.

sendMouseScrollEvent

navigationSendMouseScrollEvent

Arguments

:: (HasCallStack, MonadIO m, IsNavigation a)

=> a

navigation: The navigation interface instance

-> Double

x: The x coordinate of the mouse event.

-> Double

y: The y coordinate of the mouse event.

-> Double

deltaX: The delta_x coordinate of the mouse event.

-> Double

deltaY: The delta_y coordinate of the mouse event.

-> m ()

Sends a mouse scroll event to the navigation interface. Mouse event coordinates are sent relative to the display space of the related output area. This is usually the size in pixels of the window associated with the element implementing the Navigation interface.

Since: 1.18