VisuPairLink

VisuPairLink — V_Sim can draw link between nodes. This part defines a pair object and interface to draw pairs.

Synopsis

#define             VISU_PAIR_DISTANCE_MAX
#define             VISU_PAIR_DISTANCE_MIN
                    VisuPair;
struct              VisuPairDistribution;
void                (*VisuPairForeachFunc)              (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         VisuPairLink *data,
                                                         gpointer user_data);
struct              VisuPairLink;
struct              VisuPairLinkClass;
gboolean            visu_pair_distribution_getNextPick  (VisuPairDistribution *dd,
                                                         guint startStopId[2],
                                                         guint *integral,
                                                         guint *max,
                                                         guint *posMax);
void                visu_pair_foreach                   (VisuPairForeachFunc whatToDo,
                                                         gpointer user_data);
VisuPairDistribution * visu_pair_getDistanceDistribution
                                                        (VisuPair *pair,
                                                         VisuData *dataObj,
                                                         float step,
                                                         float min,
                                                         float max);
void                visu_pair_getElements               (const VisuPair *pair,
                                                         VisuElement **ele1,
                                                         VisuElement **ele2);
VisuPair *          visu_pair_getPair                   (VisuElement *ele1,
                                                         VisuElement *ele2);
gpointer            visu_pair_getProperty               (VisuPair *pair,
                                                         const gchar *key);
GList *             visu_pair_link_getAll               (VisuElement *ele1,
                                                         VisuElement *ele2);
ToolColor *         visu_pair_link_getColor             (const VisuPairLink *data);
float               visu_pair_link_getDistance          (const VisuPairLink *data,
                                                         int minOrMax);
gboolean            visu_pair_link_getDrawn             (const VisuPairLink *data);
VisuPairLink *      visu_pair_link_getFromId            (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         guint pos);
VisuPair *          visu_pair_link_getPair              (const VisuPairLink *data);
gboolean            visu_pair_link_getPrintLength       (const VisuPairLink *data);
gboolean            visu_pair_link_isDrawn              (const VisuPairLink *data);
VisuPairLink *      visu_pair_link_new                  (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         float minMax[2]);
gboolean            visu_pair_link_setColor             (VisuPairLink *data,
                                                         ToolColor *destColor);
gboolean            visu_pair_link_setDistance          (VisuPairLink *data,
                                                         float val,
                                                         int minOrMax);
gboolean            visu_pair_link_setDrawn             (VisuPairLink *data,
                                                         gboolean drawn);
gboolean            visu_pair_link_setPrintLength       (VisuPairLink *data,
                                                         gboolean status);
gboolean            visu_pair_readLinkFromTokens        (gchar **tokens,
                                                         int *index,
                                                         VisuPairLink **data,
                                                         int position,
                                                         GError **error);
gboolean            visu_pair_removePairLink            (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         VisuPairLink *data);
void                visu_pair_setProperty               (VisuPair *pair,
                                                         const gchar *key,
                                                         gpointer value,
                                                         GDestroyNotify freeFunc);

Object Hierarchy

  GObject
   +----VisuPairLink

Signals

  "ParameterChanged"                               : No Recursion

Description

The visu_pairs.c defines only general methods to draw pairs. It introduces a new object called VisuPairLink. This stores some characteristics on links between two VisuElement. The main characteristic is that pairs are drawn only if the length between two nodes is in a specific range. Use visu_pair_link_setDistance() and visu_pair_link_getDistance() to tune this range.

This file does not draw any pairs. But it gives some interface to create rendering capabilities. To create a new pair rendering module, called VisuPairExtension, use visu_pair_extension_new(). Basically, a VisuPairExtension is characterized by it drawing method. But it can have other methods that are called in different cases. See main() and startStop() prototypes to have more informations.

Details

VISU_PAIR_DISTANCE_MAX

#define VISU_PAIR_DISTANCE_MAX 1

Flag used to define the maximum length to draw pair. This is useful with the visu_pair_link_getDistance() and the visu_pair_link_setDistance() methods.


VISU_PAIR_DISTANCE_MIN

#define VISU_PAIR_DISTANCE_MIN 0

Flag used to define the minimum length to draw pair. This is useful with the visu_pair_link_getDistance() and the visu_pair_link_setDistance() methods.


VisuPair

typedef struct _VisuPair VisuPair;

An opaque structure to define links (i.e. several VisuPairLink) between elements.


struct VisuPairDistribution

struct VisuPairDistribution {
  VisuElement *ele1, *ele2;
  guint *histo;
  guint nValues;
  float initValue, stepValue;
  guint nNodesEle1, nNodesEle2;
};

This structure stores for a given pair, the distance distribution on a given range [initValue;nValues * stepValue[.

VisuElement *ele1;

one VisuElement.

VisuElement *ele2;

one VisuElement.

guint *histo;

an array containing the distribution ;

guint nValues;

the size of the array ;

float initValue;

the initial distance value (usualy 0) ;

float stepValue;

the step increase in distance at each value ;

guint nNodesEle1;

the number of nodes used during the computation ;

guint nNodesEle2;

idem for VisuElement 2.

VisuPairForeachFunc ()

void                (*VisuPairForeachFunc)              (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         VisuPairLink *data,
                                                         gpointer user_data);

Prototype of functions called with the foreach method apply to each pairs.

ele1 :

a VisuElement object ;

ele2 :

a VisuElement object ;

data :

a VisuPairLink object ;

user_data :

some user defined data.

struct VisuPairLink

struct VisuPairLink;

An opaque structure.


struct VisuPairLinkClass

struct VisuPairLinkClass {
  GObjectClass parent;
};

A short way to identify _VisuPairLinkClass structure.

GObjectClass parent;

the parent class;

visu_pair_distribution_getNextPick ()

gboolean            visu_pair_distribution_getNextPick  (VisuPairDistribution *dd,
                                                         guint startStopId[2],
                                                         guint *integral,
                                                         guint *max,
                                                         guint *posMax);

Try to find the next pick in the distribution. A pick is a group of consecutive non-null values, with a significant integral. On enter, startStopId contains the span to look into for the pick, and on output, it contains the span of the pick itself.

dd :

a VisuPairDistribution object.

startStopId :

two ids.

integral :

a location for a guint value, can be NULL.

max :

a location to store the value ;

posMax :

a location to store the position of the pick.

Returns :

TRUE if a pick is found.

Since 3.6


visu_pair_foreach ()

void                visu_pair_foreach                   (VisuPairForeachFunc whatToDo,
                                                         gpointer user_data);

The way VisuPairLink are stored in V_Sim is private and could changed between version. This method is used to apply some method each pairs.

whatToDo :

a VisuPairForeachFunc() method ;. [scope call]

user_data :

some user defined data.

visu_pair_getDistanceDistribution ()

VisuPairDistribution * visu_pair_getDistanceDistribution
                                                        (VisuPair *pair,
                                                         VisuData *dataObj,
                                                         float step,
                                                         float min,
                                                         float max);

This will compute the distnace distribution of nodes for the given pair.

pair :

a VisuPair ;

dataObj :

a VisuData ;

step :

a float for the distance mesh (negative value to use built-in default) ;

min :

a float for the minimum scanning value (negative value to use built-in default).

max :

a float for the maximum scanning value (negative value to use built-in default).

Returns :

a structure defining the distance distribution. This structure is private and should not be freed.

visu_pair_getElements ()

void                visu_pair_getElements               (const VisuPair *pair,
                                                         VisuElement **ele1,
                                                         VisuElement **ele2);

Retrieve the VisuElement constituting the pair.

pair :

a VisuPair object.

ele1 :

a location to store a VisuElement object pointer. [out][allow-none][transfer none]

ele2 :

a location to store a VisuElement object pointer. [out][allow-none][transfer none]

Since 3.7


visu_pair_getPair ()

VisuPair *          visu_pair_getPair                   (VisuElement *ele1,
                                                         VisuElement *ele2);

The object VisuPair is used to characterized links between two elements.

ele1 :

a VisuElement object ;

ele2 :

a VisuElement object.

Returns :

the VisuPair object associated to the given two elements. If none exists it is created. The returned value should not be freed. [transfer none]

visu_pair_getProperty ()

gpointer            visu_pair_getProperty               (VisuPair *pair,
                                                         const gchar *key);

Retrieve the property associated to the key or NULL if none exist.

pair :

a VisuPair object ;

key :

a string.

Returns :

the associated data. [transfer none]

visu_pair_link_getAll ()

GList *             visu_pair_link_getAll               (VisuElement *ele1,
                                                         VisuElement *ele2);

There can be one or several links between elements, retrieve them with this routine.

ele1 :

a VisuElement object ;

ele2 :

a VisuElement object.

Returns :

a list of VisuPairLink. The list is owned by V_Sim and should not be freed. [element-type VisuPairLink*][transfer none]

visu_pair_link_getColor ()

ToolColor *         visu_pair_link_getColor             (const VisuPairLink *data);

Look for the properties of the pair data to find if a colour has been defined. If none, the default colour is returned instead.

data :

a VisuPairLink object.

Returns :

a colour (don't free it). [transfer none]

visu_pair_link_getDistance ()

float               visu_pair_link_getDistance          (const VisuPairLink *data,
                                                         int minOrMax);

A pair between ele1 and ele2 is drawn only if its length is between a minimum and a maximum value. This method can get these values.

data :

a VisuPairLink object ;

minOrMax :

VISU_PAIR_DISTANCE_MIN or VISU_PAIR_DISTANCE_MAX.

Returns :

the minimum or the maximum value for the pair between ele1 and ele2.

visu_pair_link_getDrawn ()

gboolean            visu_pair_link_getDrawn             (const VisuPairLink *data);

A pair can or cannot be drawn, use this method to retrieve its state.

data :

a VisuPairLink object ;

Returns :

TRUE if pairs can be drawn.

visu_pair_link_getFromId ()

VisuPairLink *      visu_pair_link_getFromId            (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         guint pos);

A link can also be retrieved by its position.

ele1 :

a VisuElement object ;

ele2 :

a VisuElement object ;

pos :

the position in the list of links.

Returns :

the VisuPairLink object associated to the given two elements and distances. If none exists NULL is returned. [transfer none]

visu_pair_link_getPair ()

VisuPair *          visu_pair_link_getPair              (const VisuPairLink *data);

A link object is always associated to a VisuPair.

data :

a VisuPairLink object.

Returns :

the VisuPair this link is related to. [transfer none]

Since 3.7


visu_pair_link_getPrintLength ()

gboolean            visu_pair_link_getPrintLength       (const VisuPairLink *data);

Get the print length parameter of a pair. This parameter is used to tell if length should be drawn near pairs of this kind.

data :

a VisuPairLink object.

Returns :

TRUE if length are printed.

visu_pair_link_isDrawn ()

gboolean            visu_pair_link_isDrawn              (const VisuPairLink *data);

A link is used or not depending on a distance criterion and a flag, see visu_pair_link_setDrawn() and visu_pair_link_setDistance().

data :

a VisuPairLink object.

Returns :

TRUE if the data is indeed drawn or not.

Since 3.7


visu_pair_link_new ()

VisuPairLink *      visu_pair_link_new                  (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         float minMax[2]);

A link between two elements is characterized by its boundary distances.

ele1 :

a VisuElement object ;

ele2 :

a VisuElement object ;

minMax :

the two min and max distances. [array fixed-size=2]

Returns :

the VisuPairLink object associated to the given two elements and distances. If none exists it is created. The returned value should not be freed. [transfer none]

visu_pair_link_setColor ()

gboolean            visu_pair_link_setColor             (VisuPairLink *data,
                                                         ToolColor *destColor);

Set the color of the given pair.

data :

a VisuPairLink object ;

destColor :

a ToolColor object.

Returns :

TRUE if parameter has been changed.

visu_pair_link_setDistance ()

gboolean            visu_pair_link_setDistance          (VisuPairLink *data,
                                                         float val,
                                                         int minOrMax);

Set the minimum or the maximum length for the given pair.

val :

a floating point value ;

data :

a VisuPairLink object ;

minOrMax :

VISU_PAIR_DISTANCE_MAX or VISU_PAIR_DISTANCE_MIN.

Returns :

TRUE if parameter has been changed.

visu_pair_link_setDrawn ()

gboolean            visu_pair_link_setDrawn             (VisuPairLink *data,
                                                         gboolean drawn);

A pair can or cannot be drawn, use this method to tune it.

data :

a VisuPairLink object ;

drawn :

a boolean.

Returns :

TRUE if parameter has been changed.

visu_pair_link_setPrintLength ()

gboolean            visu_pair_link_setPrintLength       (VisuPairLink *data,
                                                         gboolean status);

Set the attribute that controls if the length of pairs are drawn near pairs.

data :

a VisuPairLink object ;

status :

TRUE to print length near pairs.

Returns :

TRUE if parameter has been changed.

visu_pair_readLinkFromTokens ()

gboolean            visu_pair_readLinkFromTokens        (gchar **tokens,
                                                         int *index,
                                                         VisuPairLink **data,
                                                         int position,
                                                         GError **error);

This routine is used to read the resource file. Given tokens, it associate a link object by reading the two elements and the two distances that characterised this link.

tokens :

array of tokens resulting from a call to g_strsplit() with " " as separator ;

index :

IN, the position of the beginning in tokens ; OUT, one token after the last read ;

data :

a pointer to return an allocated link object ;

position :

the number of the line of the config file which the line argument is taken from ;

error :

a location to store a possible reading error.

Returns :

TRUE if succeed.

visu_pair_removePairLink ()

gboolean            visu_pair_removePairLink            (VisuElement *ele1,
                                                         VisuElement *ele2,
                                                         VisuPairLink *data);

Delete the given link.

ele1 :

a VisuElement object ;

ele2 :

a VisuElement object ;

data :

a link object.

Returns :

TRUE if the link exists and has been successfully removed.

visu_pair_setProperty ()

void                visu_pair_setProperty               (VisuPair *pair,
                                                         const gchar *key,
                                                         gpointer value,
                                                         GDestroyNotify freeFunc);

Each element/element can have associated data.

pair :

a VisuPair object ;

key :

a static string ;

value :

a pointer to some allocated data ;

freeFunc :

a destroying method (can be NULL).

Signal Details

The "ParameterChanged" signal

void                user_function                      (VisuPairLink *data,
                                                        gpointer      user_data)      : No Recursion

Gets emitted when some rendering parameter of data has been changed.

data :

the object which received the signal ;

user_data :

user data set when the signal handler was connected.

Since 3.7