Skip to main content
Version: 🚧 Nightly

Class f3d::interactor

Definition: interactor.h (line 68)

Class used to control interaction and animation.

A class to control interaction with the window as well as animation. It also provide a timer callback if needed and can record/play interaction file.

Inner classes​

Members​

Bindings​

Enumeration type BindingType​

Definition: interactor.h (line 130)

enum BindingType {
  CYCLIC = 0,
  NUMERICAL = 1,
  TOGGLE = 2,
  OTHER = 3
}

Enumeration of binding types. Duplication present in vtkext/private/module/vtkF3DUIActor.h.

Enumerator CYCLIC​

Enumerator NUMERICAL​

Enumerator TOGGLE​

Enumerator OTHER​

Typedef documentation_callback_t​

Definition: interactor.h (line 124)

using f3d::interactor::documentation_callback_t =  std::function<std::pair<std::string, std::string>()>

Enumeration of binding types. Duplication present in vtkext/private/module/vtkF3DUIActor.h.

Return type: std::function< std::pair< std::string, std::string >()>

Function initBindings​

virtual interactor & f3d::interactor::initBindings()=0

Remove all existing interaction commands and add all default bindings see INTERACTIONS.md for details.

Return type: interactor &

Function addBinding​

virtual interactor & f3d::interactor::addBinding(const interaction_bind_t &bind, std::vector< std::string > commands, std::string group={}, documentation_callback_t documentationCallback=nullptr, BindingType type=BindingType::OTHER)=0

Use this method to add binding, in order to trigger commands for a specific bind

Bind modifiers is a binary flag from the dedicated enum that represent KeyModifiers. Bind interaction can be a pressed key symbol, eg: "C", or a dedicated key symbol for special keys: "Left", "Right", "Up", "Down", "Space", "Enter", "Escape", "Question".

group is an optional arg to group bindings together for better display of the documentation. Groups are kept in order of addition when recovered using getBindGroups(). Bindings are kept in order of addition when recovered using getBindsForGroup().

documentationCallback is an optional function that returns a pair of string, the first is the doc itself, the second is the current value as a string, if any. Use getBindingDocumentation() to access this doc.

type is an optional type of binding to provide, it can be used for presenting the binding in a coherent way in logs and cheatsheet.

When the corresponding bind happens, the provided commands will be triggered using triggerCommand. Considering checking if an interaction exists or removing it before adding it to avoid potential conflicts.

ANY modifier interactions will only be triggered if no other interaction bind with modifier is found.

Adding commands for an existing bind will throw a interactor::already_exists_exception.

Parameters:

Return type: interactor &

Function addBinding​

virtual interactor & f3d::interactor::addBinding(const interaction_bind_t &bind, std::string command, std::string group={}, documentation_callback_t documentationCallback=nullptr, BindingType type=BindingType::OTHER)=0

See addBinding Convenience method to add a single command for an interaction, similar as addBinding(bind, {command}).

Adding command for an existing bind will throw a interactor::already_exists_exception.

Parameters:

Return type: interactor &

Function addBinding​

interactor & f3d::interactor::addBinding(const interaction_bind_t &bind, std::initializer_list< std::string > list, std::string group={}, documentation_callback_t documentationCallback=nullptr, BindingType type=BindingType::OTHER)

Convenience initializer list signature for add binding method

Parameters:

Return type: interactor &

Function removeBinding​

virtual interactor & f3d::interactor::removeBinding(const interaction_bind_t &bind)=0

Remove binding corresponding to provided bind. Does not do anything if the provided bind does not exists.

Parameters:

Return type: interactor &

Function getBindGroups​

virtual std::vector< std::string > f3d::interactor::getBindGroups() const =0

Return a vector of available bind groups, in order of addition

Return type: std::vector< std::string >

Function getBindsForGroup​

virtual std::vector< interaction_bind_t > f3d::interactor::getBindsForGroup(std::string group) const =0

Return a vector of bind for the specified group, in order of addition

Getting binds for a group that does not exists will throw a does_not_exists_exception.

Parameters:

  • std::string group

Return type: std::vector< interaction_bind_t >

Function getBinds​

virtual std::vector< interaction_bind_t > f3d::interactor::getBinds() const =0

Return a vector of all binds, in order of addition

Return type: std::vector< interaction_bind_t >

Function getBindingDocumentation​

virtual std::pair< std::string, std::string > f3d::interactor::getBindingDocumentation(const interaction_bind_t &bind) const =0

Get a pair of string documenting a binding. The first string is the documentation of the binding, eg: "Toggle anti aliasing", "Print scene descr to terminal", "Decrease light intensity"

The second string is the current value of the binding, eg: "OFF", "" if there is no value or "1.12".

If a binding was not documented on addition, the provided strings will be empty. The possible string can depends on the bindings but boolean value are expected to be "ON", "OFF", "N/A" (for optional values).

Getting documentation for a bind that does not exists will throw a does_not_exists_exception.

Parameters:

Return type: std::pair< std::string, std::string >

Function getBindingType​

virtual BindingType f3d::interactor::getBindingType(const interaction_bind_t &bind) const =0

Get the type of a binding.

Getting type for a bind that does not exists will throw a does_not_exists_exception.

Parameters:

Return type: BindingType

Forwarding input events​

Enumeration type MouseButton​

Definition: interactor.h (line 269)

enum MouseButton {
  LEFT,
  RIGHT,
  MIDDLE
}

Enumeration of supported mouse buttons.

Enumerator LEFT​

Enumerator RIGHT​

Enumerator MIDDLE​

Enumeration type WheelDirection​

Definition: interactor.h (line 279)

enum WheelDirection {
  FORWARD,
  BACKWARD,
  LEFT,
  RIGHT
}

Enumeration of supported mouse wheel directions.

Enumerator FORWARD​

Enumerator BACKWARD​

Enumerator LEFT​

Enumerator RIGHT​

Enumeration type InputAction​

Definition: interactor.h (line 290)

enum InputAction {
  PRESS,
  RELEASE
}

Enumeration of supported input actions.

Enumerator PRESS​

Enumerator RELEASE​

Enumeration type InputModifier​

Definition: interactor.h (line 299)

enum InputModifier {
  NONE,
  CTRL,
  SHIFT,
  CTRL_SHIFT
}

Enumeration of supported input modifiers.

Enumerator NONE​

Enumerator CTRL​

Enumerator SHIFT​

Enumerator CTRL_SHIFT​

Function triggerModUpdate​

virtual interactor & f3d::interactor::triggerModUpdate(InputModifier mod)=0

Trigger a modifier update. This will update the internal modifier state of the interactor to match the provided one.

Parameters:

Return type: interactor &

Function triggerMouseButton​

virtual interactor & f3d::interactor::triggerMouseButton(InputAction action, MouseButton button)=0

Trigger a mouse button event. This will trigger the corresponding mouse button press or release event.

Parameters:

Return type: interactor &

Function triggerMousePosition​

virtual interactor & f3d::interactor::triggerMousePosition(double xpos, double ypos)=0

Trigger a mouse new position event. Positions are in window coordinates, with (0, 0) being the top-left corner. The coordinates are expressed in pixels.

Parameters:

  • double xpos
  • double ypos

Return type: interactor &

Function triggerMouseWheel​

virtual interactor & f3d::interactor::triggerMouseWheel(WheelDirection direction)=0

Trigger a mouse wheel event. At the moment, only vertical wheel events are observed, but it can change in the future.

Parameters:

Return type: interactor &

Function triggerKeyboardKey​

virtual interactor & f3d::interactor::triggerKeyboardKey(InputAction action, std::string_view keySym)=0

Trigger a keyboard key event. This is based on X11 key symbols, it's hard to list all of them, but here are a few:

  • "A", "B", "C", ..., "Z" for letters

  • "0", "1", "2", ..., "9" for numbers

  • "Left", "Right", "Up", "Down" for arrow keys

  • "Space", "Return", "Escape", "Tab", "BackSpace" for common keys

  • "F1", "F2", ..., "F25" for function keys

  • "KP_0", "KP_1", ..., "KP_9" for numpad keys

It's possible to run F3D application in verbose mode and press keys to print their symbols.

Parameters:

Return type: interactor &

Function triggerTextCharacter​

virtual interactor & f3d::interactor::triggerTextCharacter(unsigned int codepoint)=0

Trigger a text character input event. This will trigger the corresponding character input event, with the codepoint being the Unicode codepoint of the character. It's used for text input, like when typing in a the console input field.

Parameters:

  • unsigned int codepoint

Return type: interactor &

Command​

Typedef command_documentation_t​

Definition: interactor.h (line 72)

using f3d::interactor::command_documentation_t =  std::pair<std::string, std::string>

Remove all existing commands and add all default commands, see COMMANDS.md for details.

Return type: std::pair< std::string, std::string >

Function initCommands​

virtual interactor & f3d::interactor::initCommands()=0

Remove all existing commands and add all default commands, see COMMANDS.md for details.

Return type: interactor &

Function addCommand​

virtual interactor & f3d::interactor::addCommand(const std::string &action, std::function< void(const std::vector< std::string > &)> callback, std::optional< command_documentation_t > doc=std::nullopt, std::function< std::vector< std::string >(const std::vector< std::string > &)> completionCallback=nullptr)=0

Use this method to add a command to be called using triggerCommand. Adding a command with an already existing action throw a interactor::already_exists_exception.

Considering namespacing dedicated action to avoid conflicts with default action, eg: my_app::action

Parameters:

  • const std::string & action
  • std::function< void(const std::vector< std::string > &)> callback
  • std::optional< command_documentation_t > doc = std::nullopt
  • std::function< std::vector< std::string >(const std::vector< std::string > &)> completionCallback = nullptr

Return type: interactor &

Function removeCommand​

virtual interactor & f3d::interactor::removeCommand(const std::string &action)=0

Remove a command for provided action, does not do anything if it does not exists.

Parameters:

  • const std::string & action

Return type: interactor &

Function getCommandActions​

virtual std::vector< std::string > f3d::interactor::getCommandActions() const =0

Return a string vector containing all currently defined actions of commands

Return type: std::vector< std::string >

Function triggerCommand​

virtual bool f3d::interactor::triggerCommand(std::string_view command, bool keepComments=true)=0

Trigger provided command, see COMMANDS.md for details about supported commands and syntax.

If the command fails, it prints a debug log explaining why.

When keepComments argument is true, comments are supported with #, any characters after are ignored otherwise # and any characters after will be handled as standard character

Return true if the command succeeded, false otherwise. Throw an interactor::command_runtime_exception if the command callback throw an unrecognized exception.

Note that default commands will never throw this exception, but adding commands without exception catching may trigger this behavior.

Parameters:

  • std::string_view command
  • bool keepComments = true

Return type: bool

Animation​

Function toggleAnimation​

virtual interactor & f3d::interactor::toggleAnimation()=0

Control the animation.

Return type: interactor &

Function startAnimation​

virtual interactor & f3d::interactor::startAnimation()=0

Control the animation.

Return type: interactor &

Function stopAnimation​

virtual interactor & f3d::interactor::stopAnimation()=0

Control the animation.

Return type: interactor &

Function isPlayingAnimation​

virtual bool f3d::interactor::isPlayingAnimation()=0

Control the animation.

Return type: bool

Movement​

Function enableCameraMovement​

virtual interactor & f3d::interactor::enableCameraMovement()=0

Control if camera movements are enabled, which they are by default.

Return type: interactor &

Function disableCameraMovement​

virtual interactor & f3d::interactor::disableCameraMovement()=0

Control if camera movements are enabled, which they are by default.

Return type: interactor &

Public functions​

Function playInteraction​

virtual bool f3d::interactor::playInteraction(const std::filesystem::path &file, double deltaTime=1.0/30, std::function< void()> userCallBack=nullptr)=0

Play a VTK interaction file. Provided file path is used as is and file existence will be checked. The event loop will be triggered every deltaTime in seconds, and userCallBack will be called at the start of the event loop.

Parameters:

  • const std::filesystem::path & file
  • double deltaTime = 1.0/30
  • std::function< void()> userCallBack = nullptr

Return type: bool

Function recordInteraction​

virtual bool f3d::interactor::recordInteraction(const std::filesystem::path &file)=0

Start interaction and record it all in a VTK interaction file. Provided file path will be used as is and the parent directories of the file will be created.

Parameters:

  • const std::filesystem::path & file

Return type: bool

Function start​

virtual interactor & f3d::interactor::start(double deltaTime=1.0/30, std::function< void()> userCallBack=nullptr)=0

Start the interactor event loop. The event loop will be triggered every deltaTime in seconds, and userCallBack will be called at the start of the event loop.

Parameters:

  • double deltaTime = 1.0/30
  • std::function< void()> userCallBack = nullptr

Return type: interactor &

Function stop​

virtual interactor & f3d::interactor::stop()=0

Stop the interactor.

Return type: interactor &

Function requestRender​

virtual interactor & f3d::interactor::requestRender()=0

Request a render to be done on the next event loop. Safe to call in a multithreaded environment.

Return type: interactor &