Paramètres et fonctions de la classe de base

La classe ibm_ilog.graphlayout.GraphLayout définit un nombre de paramètres et fonctions génériques. Ces paramètres et fonctions peuvent être utilisés pour personnaliser les algorithmes d'agencement.
Bien que la classe GraphLayout définisse les paramètres génériques, elle ne contrôle pas la façon dont ils sont utilisés par ses sous-classes. Chaque algorithme d'agencement (autrement dit, chaque sous-classe de GraphLayout) prend en charge un sous-ensemble des fonctions génériques et détermine la façon dont il utilise les paramètres génériques. Lorsque vous créez votre propre algorithme d'agencement à l'aide de sous-classes de GraphLayout, vous décidez si vous souhaitez utiliser les fonctions et la façon dont vous allez les utiliser.
La classe GraphLayout définit les fonctions génériques suivantes :
Prise en charge de paramètres et fonctions génériques par des algorithmes récapitule les paramètres génériques pris en charge par chaque algorithme d'agencement. Si vous utilisez l'une des sous-classes fournies avec l'API d'agencement de graphe, vérifiez la documentation relative à cette sous-classe pour savoir si elle prend en charge un paramètre spécifique et comment elle interprète ce paramètre.

Temps imparti

Plusieurs algorithmes d'agencement peuvent être désignés pour arrêter le calcul lorsqu'une spécification de temps définie par l'utilisateur est dépassée. Cette action peut être envisagée comme une mesure de sécurité visant à éviter un temps de calcul prolongé sur des graphes de grande taille, ou comme une limite supérieure pour des algorithmes qui améliorent de manière itérative une solution en cours et qui ne disposent d'aucun autre critère pour arrêter le calcul.
Exemple de spécification du temps imparti
Pour spécifier la valeur de départ :
Appelez :
layout.setAllowedTime(60000); 
Le temps imparti est exprimé en millisecondes. La valeur par défaut est 32 000 (32 secondes).
Si vous faites appel à une sous-classe de ibm_ilog.graphlayout.GraphLayout, utilisez la méthode suivante pour savoir si le temps imparti spécifié a été dépassé :
layout.isLayoutTimeElapsed();
Pour indiquer si une sous-classe de GraphLayout prend en charge ce mécanisme, utilisez la méthode suivante :
layout.supportsAllowedTime();
L'implémentation par défaut renvoie la valeur false. Une sous-classe peut écraser cette méthode pour renvoyer la valeur true afin d'indiquer que ce mécanisme est pris en charge.

Agencement des composants connectés

La classe de base ibm_ilog.graphlayout.GraphLayout fournit une prise en charge générique de l'agencement d'un graphe déconnecté (constitué de composants connectés).
Exemple d'agencement
Pour activer le positionnement de graphes déconnectés :
Appelez :
layout.setLayoutOfConnectedComponentsEnabled(true);
Note
Certaines des classes d'agencement (HierarchicalLayout, CircularLayout) sont dotées d'un algorithme intégré permettant de positionner les composants connectés. Cet algorithme est activé par défaut et compatible avec la plupart des situations les plus courantes. Pour cette classe d'agencement, le mécanisme générique fourni par la classe de base GraphLayout est désactivé par défaut.
Lorsqu'il est activé, une instance par défaut de la classe ibm_ilog.graphlayout.grid.GridLayout est utilisée de façon interne pour positionner les graphes déconnectés. Le cas échéant, vous pouvez personnaliser cet agencement.
Exemple de personnalisation d'agencement
Pour personnaliser cet agencement :
Appelez :
var gridLayout = new ibm_ilog.graphlayout.grid.GridLayout();
gridLayout.setLayoutMode(ibm_ilog.graphlayout.grid.GridLayout.TILE_TO_ROWS);
gridLayout.setTopMargin(20);
layout.setLayoutOfConnectedComponents(gridLayout);

Exemple destiné aux experts
Les diverses fonctions de la classe ibm_ilog.graphlayout.grid.GridLayout permettent la prise en charge de la plupart des besoins en matière de positionnement des graphes déconnectés. Le cas échéant, vous pouvez écrire votre propre sous-classe de ibm_ilog.graphlayout.GraphLayout pour positionner des graphes déconnectés et vous pouvez la spécifier à la place de GridLayout :
Appelez :
var myGridLayout = new MyGridLayout();
// settings for myGridLayout, if necessary
layout.setLayoutOfConnectedComponents(myGridLayout);
Pour indiquer si une sous-classe de GraphLayout prend en charge ce mécanisme, utilisez la méthode suivante :
layout.supportsLayoutOfConnectedComponents();
L'implémentation par défaut renvoie la valeur false. Vous pouvez écrire une sous-classe pour remplacer ce comportement.

Région d'agencement

Certains algorithmes d'agencement peuvent contrôler la taille du tracé de graphe et prendre en compte un layout region défini par l'utilisateur.
Exemple de spécification d'une région d'agencement
Pour spécifier une région de 100 par 100 :
layout.setLayoutRegion({x:0, y:0, width:100, height:100});
Pour accéder à la région d'agencement, utilisez la méthode suivante :
var rect = layout.getSpecLayoutRegion();  
Cette méthode renvoie une copie du rectangle qui définit la région d'agencement spécifiée.
Les algorithmes d'agencement appellent un autre méthode :
var rect = layout.getCalcLayoutRegion();  
Cette méthode tente d'abord d'utiliser la spécification de région d'agencement en appelant la méthode ibm_ilog.graphlayout.GraphLayout.getSpecLayoutRegion. Si cette méthode renvoie un rectangle non null, celui-ci est renvoyé. Sinon, la méthode tente d'estimer une région d'agencement appropriée en fonction du nombre et de la taille des noeuds dans le graphe attaché. Si aucun graphe n'est attaché, ou si le graphe attaché est vide, un rectangle par défaut {x:0, y:0, width:1000, height:1000} est renvoyé.
Pour indiquer si une sous-classe de GraphLayout prend en charge le mécanisme de région d'agencement, utilisez la méthode suivante :
layout.supportsLayoutRegion(); 
L'implémentation par défaut renvoie la valeur false. Une sous-classe peut remplacer cette méthode afin de renvoyer true pour indiquer que ce mécanisme est pris en charge.
Note
L'implémentation de la méthode ibm_ilog.graphlayout.GraphLayout.layout() sert uniquement à contrôler si la région d'avancement est prise en compte lors du calcul de l'agencement, et de quelle manière. Pour plus d'informations, voir la documentation sur les algorithmes d'agencement.

Link connection box

Si un algorithme d'agencement calcule des points de connexion spécifiques, il positionne les points de connexion des liens par défaut sur le bord du cadre de délimitation des noeuds, de façon symétrique par rapport au milieu de chaque côté. Il peut parfois être nécessaire de positionner les points de connexion sur un rectangle plus petit ou plus grand que le cadre de délimitation, de préférence de façon asymétrique. Par exemple, des points de connexion peuvent être positionnés de façon asymétrique lorsque des libellés sont affichés au-dessus ou au-dessous des noeuds. Voir Effet de l'interface link connection box. Pour ce faire, vous pouvez indiquer une interface link connection box. L'interface link connection box vous permet d'indiquer, pour chaque noeud, un cadre de noeud différent du cadre de délimitation qui est utilisé pour la connexion entre les liens et le noeud.
Exemple d'interface link connection box
Pour configurer une interface de cadre de connexion de liens, appelez :
layout.setLinkConnectionBoxInterface(provider);
Vous implémentez l'interface de cadre de connexion de liens en définissant une classe qui indique ibm_ilog.graphlayout.ILinkConnectionBoxProvider. Cette interface définit la méthode suivante :
getBox(graphModel, node)    
Cette méthode vous permet de renvoyer le rectangle sur lequel les points de connexion des liens sont effectivement positionnés.
Une autre méthode définie dans l'interface autorise le décalage indirect des points de connexion, d'une façon différente pour chaque côté de chaque noeud :
getTangentialOffset(graphModel, node, nodeSide)  
Le mode d'utilisation des interfaces et les points de connexion renvoyés comme résultat final sont spécifiques à chaque algorithme d'agencement.
L'agencement hiérarchique, l'agencement arborescent et les agencements avec liens courts et avec liens longs utilisent l'interface link connection box pour définir le cadre de délimitation du noeud où les liens doivent être attachés.
La figure ci-après illustre les effets de la personnalisation du cadre de connexion. Le résultat sans l'interface link connection box est affiché sur la gauche. L'effet obtenu lorsque l'interface link connection box renvoie le rectangle discontinu pour le noeud bleu est affiché sur la droite.
Deux graphes, l'un à gauche et l'autre à droite, qui illustrent l'effet du cadre de connexion de liens ou de l'interface de fournisseur de cadre de connexion de liens.
Effet de l'interface link connection box
L'agencement circulaire, l'agencement aléatoire et l'agencement Force-directed n'étendent pas les liens vers le bord du noeud, mais peuvent les router vers un point situé au centre du noeud.
Si la forme d'un noeud est irrégulière, parfois, les liens ne doivent pas pointer vers le centre du cadre de délimitation du noeud, mais vers un centre virtuel au sein du noeud. L'interface link connection box peut être utilisée pour définir le centre de noeud virtuel. La figure ci-après illustre un exemple de l'effet obtenu.
Illustration représentant l'effet de l'utilisation conjointe du cadre de connexion de liens et du recadrage de liens
Effet combiné de l'interface de recadrage de liens et du link connection box
Si les liens sont découpés au niveau du noeud d'étoile vert irrégulier situé sur la gauche de la figure, ils ne pointeront pas vers le centre de l'étoile, mais vers le centre du cadre de délimitation du noeud. Vous pouvez corriger cet effet en indiquant une interface link connection box qui renvoie un cadre de noeud plus petit que le cadre de délimitation, tel que celui présenté sur la droite de la figure. Sinon, vous pouvez corriger le problème en indiquant une interface link connection box qui renvoie le cadre de délimitation en tant que cadre de noeud, mais avec des décalages indirects supplémentaires qui décalent le centre virtuel du noeud.
Par exemple, pour définir une interface de cadre de connexion de liens qui renvoie un rectangle de connexion de liens plus petit que le cadre de délimitation pour tous les noeuds de type MyNode et qui décale les points de connexion à gauche et à droite de tous les noeuds, appelez :
dojo.declare('MyLinkConnectionBoxProvider', 
 ibm_ilog.graphlayout.ILinkConnectionBoxProvider,
{
 getBox: function(graphModel, node)
 {
  var rect:Rectangle = graphModel.getBounds(node);
  if (node is MyNode) {
     // for example, the size of the bounding box is reduced:
     rect.x += 4;
     rect.y += 4;
     rect.width -= 8;
     rect.height -= 8;
    }
    return rect;
   }
   getTangentialOffset: function(graphModel, node, side)
   {
     switch (side) {
      case ibm_ilog.graphlayout.Direction.LEFT:
      case ibm_ilog.graphlayout.Direction.RIGHT:
       return -10; // shift up with 10 for both left and right side
      case ibm_ilog.graphlayout.Direction.TOP:
      case ibm_ilog.graphlayout.Direction.BOTTOM:
      default:
       return 0; // no shift for top and bottom side
     }
    }
});
layout.setLinkConnectionBoxProvider(new MyLinkConnectionBoxProvider());

Pour indiquer qu'une sous-classe de ibm_ilog.graphlayout.GraphLayout prend en charge l'interface de fournisseur de cadre de connexion de liens, utilisez la méthode ibm_ilog.graphlayout.GraphLayout.supportsLinkConnectionBox().
L'implémentation par défaut renvoie la valeur false. Vous pouvez écrire une sous-classe pour remplacer cette méthode afin de renvoyer la valeur true pour indiquer que ce mécanisme est pris en charge.

Calcul de pourcentage d'achèvement

Certains algorithme d'agencement peuvent fournir une estimation du pourcentage d'agencement réalisé. Cette estimation est disponible sous la forme d'une valeur de pourcentage qui est stockée dans le rapport d'agencement de graphe. Lorsque l'algorithme débute, la valeur de pourcentage est 0. L'algorithme d'agencement appelle la méthode suivante de temps en temps pour augmenter la valeur de pourcentage par étapes jusqu'à ce qu'elle atteigne 100 :
layout.increasePercentageComplete(newPercentage);  
La valeur de pourcentage est accessible à partir du rapport d'agencement à l'aide de la méthode suivante :
var percentage = layoutReport.getPercentageComplete(); 
Pour indiquer si une sous-classe de ibm_ilog.graphlayout.GraphLayout prend en charge ce mécanisme, utilisez la méthode suivante :
layout.supportsPercentageComplete(); 
L'implémentation par défaut renvoie la valeur false. Une sous-classe peut écraser cette méthode pour renvoyer la valeur true afin d'indiquer que ce mécanisme est pris en charge.

Conserver les liens fixes

Parfois, vous pouvez souhaiter que certains liens du graphe soient "verrouillés" (autrement dit, ils conservent leur forme actuelle pendant l'exécution de l'agencement). Vous souhaitez trouver un moyen d'indiquer les liens que l'algorithme d'agencement ne peut pas remodeler. Cela semble approprié lorsque vous utilisez un agencement semi-automatique (méthode qui permet à l'utilisateur d'affiner manuellement l'agencement une fois que celui-ci est terminé) ou un agencement incrémentiel (méthode au cours de laquelle le graphe est modifié et/ou les liens sont remodelés après l'exécution de l'agencement et où l'agencement est de nouveau exécuté).
Exemple de spécification de liens fixes
Pour spécifier qu'un lien est fixe :
Utilisez la méthode suivante :
layout.setFixed(link, fixed);  
Si le paramètre fixed a pour valeur true, cela signifie que le lien est fixe. Pour obtenir le paramétrage actuel d'un lien :
layout.isFixed(link);  
La valeur par défaut est false.
Pour supprimer l'attribut fixe de tous les liens dans le graphe, utilisez la méthode suivante :
layout.unfixAllLinks();   
Les attributs fixes sur des liens sont pris en compte uniquement si vous appelez également l'instruction suivante :
layout.setPreserveFixedLinks(true);
Pour indiquer si une sous-classe de GraphLayout prend en charge ce mécanisme, utilisez la méthode suivante :
layout.supportsPreserveFixedLinks(); 
L'implémentation par défaut renvoie la valeur false. Une sous-classe peut écraser cette méthode pour renvoyer la valeur true afin d'indiquer que ce mécanisme est pris en charge.

Conserver les noeuds fixes

Parfois, vous pouvez souhaiter que certains noeuds du graphe soient "verrouillés" (autrement dit, ils restent à leur position actuelle pendant l'exécution de l'agencement). Vous souhaitez trouver un moyen d'indiquer les noeuds que l'algorithme d'agencement ne peut pas déplacer. Cela semble approprié lorsque vous utilisez un agencement semi-automatique (méthode qui permet à l'utilisateur d'affiner manuellement l'agencement une fois que celui-ci est terminé) ou un agencement incrémentiel (méthode au cours de laquelle le graphe et/ou la position des noeuds sont modifiés après l'exécution de l'agencement et où l'agencement est de nouveau exécuté).
Exemple de spécification de noeuds fixes
Pour spécifier qu'un noeud est fixe :
Utilisez la méthode suivante :
layout.setFixed(node, fixed); 
Si le paramètre fixed a pour valeur true, cela signifie que le noeud est fixe. Pour obtenir le paramétrage actuel d'un noeud :
layout.isFixed(node); 
La valeur par défaut est false.
Pour supprimer l'attribut fixe de tous les noeuds dans le graphe, utilisez la méthode suivante :
layout.unfixAllNodes();  
Les attributs fixes sur des noeuds sont pris en compte uniquement si vous appelez également :
layout.setPreserveFixedNodes(true);
Pour indiquer si une sous-classe de GraphLayout prend en charge ce mécanisme, utilisez la méthode suivante :
layout.supportsPreserveFixedNodes(); 
L'implémentation par défaut renvoie la valeur false. Une sous-classe peut écraser cette méthode pour renvoyer la valeur true afin d'indiquer que ce mécanisme est pris en charge.

S'arrêter immédiatement

Plusieurs algorithmes d'agencement peuvent arrêter le calcul lorsqu'un événement externe se produit, par exemple, si l'utilisateur appuie sur un bouton d'arrêt.
Pour arrêter l'agencement, vous pouvez appeler :
layout.stopImmediately();  
La méthode renvoie la valeur true si l'arrêt a été initié et la valeur false si l'algorithme ne peut pas s'arrêter. La méthode renvoie une valeur immédiatement, mais l'unité d'exécution d'agencement a généralement besoin d'un peu plus de temps après que l'arrêt a été initié pour nettoyer les structures de données.
Les conséquences de l'arrêt d'un processus d'agencement varient en fonction de l'algorithme d'agencement. Certains algorithmes d'agencement sont itératifs par nature. Lorsque le processus d'itération est arrêté, une légère baisse de la qualité du tracé est observée, mais l'agencement est toujours considéré comme valide. D'autres algorithmes d'agencement sont séquentiels par nature. Lorsque la séquence des étapes d'agencement est interrompue, l'agencement obtenu peut ne plus être valide. En général, ces algorithmes rétablissent la situation avant que le processus d'agencement ne démarre.
Pour indiquer si une sous-classe de GraphLayout prend en charge ce mécanisme, utilisez la méthode suivante :
layout.supportsStopImmediately(); 
L'implémentation par défaut renvoie la valeur false. Vous pouvez écrire une sous-classe pour remplacer cette méthode afin de renvoyer true pour indiquer que ce mécanisme est pris en charge.