VisuInteractive

VisuInteractive — Gives tools to interact with the rendered area.

Functions

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── ToolDbgObj
        ╰── VisuInteractive

Description

When one wants some interactions on the rendering area (either from the mouse or from the keyboard), one should initialise it using openGLInteractiveInit_session(). Then, during the interactive session, several modes have been implemented:

  • openGLInteractiveBegin_mark(), is a mode where the mouse can select a node and this nodes become highlighted.

  • openGLInteractiveBegin_move(), the mouse is then used to move picked nodes. Moves are possible in the plane of the screen or constrained along axis of the bounding box.

  • openGLInteractiveBegin_observe(), in this mode, the mouse is used to change the position of camera, its orientation and its zoom characteristics.

  • openGLInteractiveBegin_pick(), this mode is the most complex picking mode. It can select atoms up to two references and measure distances and angles.

  • openGLInteractiveBegin_pickAndObserve(), this mode is a simplified mix of obervation and picking.

The observe mode has two different moving algorithms that can be changed using openGLInteractiveSet_preferedObserveMethod(). The first, called 'constrained' (cf. OPENGL_OBSERVE_CONSTRAINED) corresponds to movements along parallels and meridians. When the mouse is moved along x axis, the camera raotates along a parallel. When the camera is moved along y axis, the camera rotate along a meridian. The top is always pointing to the north pole (in fact, omega is always forced to 0 in this mode). This mode has a 'strange' behavior when the observer is near a pole: moving mouse along x axis make the box rotates on itself. It is normal, because movements on x axis is equivalent to movements on parallel and near the poles, parallel are small circle around the z axis. This can be unnatural in some occasion and the other mode, called 'walker' (see OPENGL_OBSERVE_WALKER) can be used instead of the 'constrained' mode. In the former, the moving is done has if the observer was a walking ant on a sphere : moving the mouse along y axis makes the ant go on or forward ; and x axis movements makes the ant goes on its left or on it right. This is a more natural way to move the box but it has the inconvient that it is hard to return in a given position (omega has never the right value).

Functions

visu_interactive_class_setPreferedObserveMethod ()

void
visu_interactive_class_setPreferedObserveMethod
                               (VisuInteractiveMethod method);

There are two methods to move the camera in a pick and observe sesion. These two methods are described in the commentary of the keys OPENGL_OBSERVE_CONSTRAINED an dOPENGL_OBSERVE_WALKER.

Parameters

method

an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags.

 

visu_interactive_class_getPreferedObserveMethod ()

VisuInteractiveMethod
visu_interactive_class_getPreferedObserveMethod
                               ();

There are two methods to move the camera in a pick and observe sesion. These two methods are described in the commentary of the keys OPENGL_OBSERVE_CONSTRAINED an dOPENGL_OBSERVE_WALKER.

Returns

an integer that identify the method, see OPENGL_OBSERVE_CONSTRAINED, and OPENGL_OBSERVE_WALKER flags.


visu_interactive_new ()

VisuInteractive *
visu_interactive_new (VisuInteractiveId type);

Creates a new interactive session of the given type .

Parameters

type

a VisuInteractiveId flag.

 

Returns

a newly created object.

[transfer full]


visu_interactive_setType ()

gboolean
visu_interactive_setType (VisuInteractive *inter,
                          VisuInteractiveId id);

It changes the kind of interactive session.

Parameters

inter

a VisuInteractive object.

 

id

a VisuInteractiveId.

 

Returns

TRUE if indeed changed.


visu_interactive_getType ()

VisuInteractiveId
visu_interactive_getType (VisuInteractive *inter);

It returns the kind of interactive session.

Parameters

inter

a VisuInteractive object.

 

Returns

a VisuInteractiveId value.


visu_interactive_handleEvent ()

void
visu_interactive_handleEvent (VisuInteractive *inter,
                              VisuGlView *view,
                              ToolSimplifiedEvents *ev);

This routine should be called by the rendering window when some event is raised on the rendering surface.

Parameters

inter

a VisuInteractive object ;

 

view

a VisuGlView object the interaction happened on.

 

ev

a simplified event.

 

visu_interactive_getEvent ()

ToolSimplifiedEvents *
visu_interactive_getEvent (VisuInteractive *inter);

This routine can be called in callbacks of inter to get some details about the event that raise signals like VisuInteractive::node-selection.

Parameters

inter

a VisuInteractive object.

 

Returns

a location with details on the last event.

[transfer none]

Since: 3.7


visu_interactive_setNodeList ()

void
visu_interactive_setNodeList (VisuInteractive *inter,
                              VisuGlExtNodes *nodes);

Associate a VisuGlExtNodes object for node selection. This is mandatory for move, pick and mark actions.

Parameters

inter

a VisuInteractive object.

 

nodes

a VisuGlExtNodes object.

[transfer full][allow-none]

Since: 3.7


visu_interactive_setMovingNodes ()

void
visu_interactive_setMovingNodes (VisuInteractive *inter,
                                 GArray *nodeIds);

Defines the nodes that should be moved if inter is a move action session. The list is actually copied.

Parameters

inter

a VisuInteractive object.

 

nodeIds

a list of node ids.

[element-type guint][allow-none]

visu_interactive_setMovingAxe ()

void
visu_interactive_setMovingAxe (VisuInteractive *inter,
                               float axe[3]);

Defines the axe that can be used to move along if inter is a move action session.

Parameters

inter

a VisuInteractive object.

 

axe

a direction.

 

visu_interactive_highlight ()

void
visu_interactive_highlight (VisuInteractive *inter,
                            guint nodeId);

This routine simulates an highlight action on nodeId . This triggers the signal “node-selection”, or “selection-error” if nodeId is invalid.

Parameters

inter

a VisuInteractive object.

 

nodeId

a node id.

 

Since: 3.7


visu_interactive_popSavedCamera ()

VisuGlCamera *
visu_interactive_popSavedCamera (VisuInteractive *inter);

inter object stores camera settings as a ring. This routine goes to the next camera in the ring and returns the current one. The popped camera is not actually removed from the ring.

Parameters

inter

a VisuInteractive object.

 

Returns

a pointer to the previously current VisuGlCamera. It is owned by V_Sim and should not be touched.

Since: 3.6


visu_interactive_pushSavedCamera ()

void
visu_interactive_pushSavedCamera (VisuInteractive *inter,
                                  VisuGlCamera *camera);

inter object stores camera settings as a ring. The given camera is copied in the ring if its values not already exist. The current camera is set to this new one.

Parameters

inter

a VisuInteractive object.

 

camera

a VisuGlCamera object.

 

Since: 3.6


visu_interactive_getSavedCameras ()

void
visu_interactive_getSavedCameras (VisuInteractive *inter,
                                  GList **cameras,
                                  GList **head);

inter object stores camera settings as a ring. One can access the set of saved cameras thanks to cameras or to the current position in the ring thanks to head . cameras or head are not copied and are owned by V_Sim. They should be considered read-only.

Parameters

inter

a VisuInteractive object.

 

cameras

a location to store a list of cameras.

[out][element-type VisuGlCamera*]

head

a location to store a list of cameras.

[out][element-type VisuGlCamera*]

Since: 3.6


visu_interactive_setReferences ()

void
visu_interactive_setReferences (VisuInteractive *inter,
                                VisuInteractive *from);

Copies all node ids used as reference from from to inter .

Parameters

inter

a VisuInteractive object.

 

from

another VisuInteractive object.

 

visu_interactive_class_getNodes2DCoordinates ()

void
visu_interactive_class_getNodes2DCoordinates
                               (VisuData *dataObj,
                                guint *nodeIds,
                                guint nNodes,
                                float *coordinates2D,
                                guint *size);

From nodes ids, compute and store in coordinates2D their 2D coordinates.

[skip]

Parameters

dataObj

a VisuData object ;

 

nodeIds

an array of VisuNode ids ;

 

nNodes

the number of nodes in the array ;

 

coordinates2D

an array of nodes 2D coordinates ;

 

size

the size of the coordinates array.

 

Types and Values

enum VisuInteractiveMethod

Describes the different possible methods for observe moves.

Members

interactive_constrained

the camera is moved keeping the north pole up. The north pole is defined by the Z axis et periodic boundary conditions and by normal to surface in surface conditions.

 

interactive_walker

the camera is moved following the mouse moves, orienting the view as a walker would do along a sphere.

 

enum VisuInteractiveId

These are the possible mouse interaction that are implemented.

Members

interactive_none

no interaction ;

 

interactive_observe

interaction to rotate the view ;

 

interactive_measureAndObserve

interaction to rotate the view and access limited pick action on the right click ;

 

interactive_measure

interaction to pick and measure ;

 

interactive_pick

interaction to select node ;

 

interactive_move

interaction to move nodes ;

 

interactive_mark

interaction to mark nodes ;

 

interactive_drag

interaction to get drag moves of the mouse.

 

enum VisuInteractivePick

Possible significations of a click.

Members

PICK_NONE

click to void ;

 

PICK_SELECTED

click to select one node ;

 

PICK_DISTANCE

click to measure a distance between two nodes ;

 

PICK_ANGLE

click to measure an angle ;

 

PICK_HIGHLIGHT

click to highlight a node ;

 

PICK_REFERENCE_1

click to select a first reference ;

 

PICK_UNREFERENCE_1

click to un-select a first reference ;

 

PICK_REFERENCE_2

click to select a second reference ;

 

PICK_UNREFERENCE_2

click to un-select a second reference ;

 

PICK_INFORMATION

click to measure distances and angles around one node ;

 

PICK_REGION

click to select a list of nodes.

 

enum VisuInteractivePickError

Possible errors to occur when pick or measure.

Members

PICK_ERROR_NONE

no error during click ;

 

PICK_ERROR_NO_SELECTION

click to sleect but nothing selected ;

 

PICK_ERROR_SAME_REF

click to set a reference but reference already exists ;

 

PICK_ERROR_REF1

click to select a first reference but impossible to choose this one ;

 

PICK_ERROR_REF2

the same for second reference.

 

Signal Details

The “menu” signal

void
user_function (VisuInteractive *obj,
               gint             x,
               gint             y,
               VisuNode        *node,
               gpointer         user_data)

This signal is emitted each time a menu key stroke is done.

Parameters

obj

the object emitting the signal.

 

x

the x coordinate.

 

y

the y coordinate.

 

node

a VisuNode.

[type VisuNode*][transfer none][allow-none]

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion

Since: 3.7


The “move” signal

void
user_function (VisuInteractive *obj,
               ToolVector      *delta,
               gpointer         user_data)

This signal is emitted each time a set of nodes are moved. The corresponding movement translation is stored in delta.

Parameters

obj

the object emitting the signal.

 

delta

the delta of applied translation.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.6


The “node-selection” signal

void
user_function (VisuInteractive *obj,
               guint            kind,
               VisuNodeArray   *array,
               VisuNode        *node1,
               VisuNode        *node2,
               VisuNode        *node3,
               gpointer         user_data)

This signal is emitted each time a single node selection succeed, providing the kind in kind (see VisuInteractivePick). The corresponding nodes are stored in node1 , node2 and node3 .

Parameters

obj

the object emitting the signal.

 

kind

a flag, see VisuInteractivePick.

 

array

the VisuNodeArray hosting node1 , node2 and node3 .

[type VisuNodeArray*][transfer none]

node1

the primary node.

[type VisuNode*][transfer none]

node2

the secondary node, if any.

[type VisuNode*][transfer none]

node3

the tertiary node, if any.

[type VisuNode*][transfer none]

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion

Since: 3.6


The “observe” signal

void
user_function (VisuInteractive *obj,
               gboolean         bool,
               gpointer         user_data)

This signal is emitted each time an observe session is start (bool is TRUE) or finished (bool is FALSE).

Parameters

obj

the object emitting the signal.

 

bool

a boolean.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion

Since: 3.6


The “region-selection” signal

void
user_function (VisuInteractive *obj,
               GArray          *nodes,
               gpointer         user_data)

This signal is emitted each time a region selection succeed. The corresponding nodes are stored in nodes .

Parameters

obj

the object emitting the signal.

 

nodes

an array of node ids.

[element-type guint]

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.6


The “selection-error” signal

void
user_function (VisuInteractive *obj,
               guint            err,
               gpointer         user_data)

This signal is emitted each time a selection fails, providing the error in err (see VisuInteractivePickError).

Parameters

obj

the object emitting the signal.

 

err

an error value.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.6


The “start-move” signal

void
user_function (VisuInteractive *obj,
               GArray          *nodes,
               gpointer         user_data)

This signal is emitted each time a set of nodes are clicked to be moved. The corresponding nodes are stored in nodes .

Parameters

obj

the object emitting the signal.

 

nodes

an array of node ids.

[element-type guint]

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.6


The “stop” signal

void
user_function (VisuInteractive *obj,
               gpointer         user_data)

This signal is emitted each time a set of nodes are stopped to be moved.

Parameters

obj

the object emitting the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.6


The “stop-move” signal

void
user_function (VisuInteractive *obj,
               ToolVector      *delta,
               gpointer         user_data)

This signal is emitted when a set of nodes are finished moving. The corresponding movement complete translation is stored in delta.

Parameters

obj

the object emitting the signal.

 

delta

the delta of applied translation.

 

user_data

user data set when the signal handler was connected.

 

Flags: No Hooks

Since: 3.8