GdipBeginContainerI()

Resultat.i = GdipBeginContainerI(*graphics, @dstrect.Rect, @srcrect.Rect, unit.i, @*state)

*graphics

[in] Pointeur sur un objet Graphics existant.

dstrect.Rect

[in] Structure Rect (nombres entiers) qui en association avec le paramètre srcrect.Rect spécifie une transformation d'échelle pour le conteneur graphique créé.

srcrect.Rect

[in] Structure Rect (nombres entiers) qui en association avec le paramètre dstrect.Rect spécifie une transformation d'échelle pour le conteneur graphique créé.

unit.i

[in] Elément de l'énumération Unit qui défini l'unité de mesure du conteneur.

*state

[out] *state recevra un pointeur sur un objet GraphicsContainer (conteneur graphique) qui représente l'état du Graphics au moment de l'appel de la fonction.

Cette fonction permet de créer un conteneur graphique. Si un autre conteneur graphique est ouvert, la fonction le ferme en l'enregistrant avec l'état actuel de ses composants.

A chaque création d'un objet GraphicsContainer doit correspondre un appel de la fonction GdipEndContainer() qui permet de libérer les ressources associées à l'objet.

Les conteneurs graphiques conservent l'état des graphiques, tel que les propriétés de transformation, de zone de découpage et de rendu.
Lorsque le conteneur graphique est supprimé avec la fonction GdipEndContainer(), le graphique prend les propriétés du conteneur précédant s'il existe sinon il prend les propriétés initiales du graphique.

Cette fonction spécifie une transformation d'échelle et de translation pour le nouveau conteneur graphique avec les paramètres dstrect et srcrect. L'échelle équivaut à la transformation qui une fois appliquée à srcrect, a pour résultat dstrect.

dstrect est le rectangle de destination qui en association avec le rectangle *srcrect définissent le facteur d'échelle. La translation est calculée avec ces deux rectangles ainsi qu'avec les valeurs X/Y de la forme à dessiner. L'exemple qui suit donne les relations entre ces valeurs pour obtenir les coordonnées finales.
Les deux rectangles srcrect et dstrect ne sont utilisés que pour le calcul des coordonnées finales, les formes ne sont pas dessinés à l'intérieur de ces rectangles.

L'unité utilisée est définie par le paramètre unit.l qui est un élément de l'énumération Unit.

Voici un exemple avec comme figure à dessiner, un rectangle .

Coordonnées rectangle source (srcrect.Rect) :
    src_X = 0 ; src_Y = 0 ; src_largeur = 200 ; src_hauteur = 200

Coordonnées rectangle destination (dstrect.Rect) :
    dest_X = 0 ; dest_Y = 0 ; dest_largeur = 150 ; dest_hauteur = 150

Coordonnées du rectangle à dessiner :
    X = 50 ; Y = 30 ; largeur = 200 ; hauteur = 200

Le conteneur a les 2 facteurs d'échelle suivants :
    Facteur en X : FacteurEchelle_X = dest_largeur / src_largeur soit 150 / 200 = 0,75
    Facteur en Y : FacteurEchelle_Y = dest_hauteur / src_hauteur soit 150 / 200 = 0,75

Toutes les formes dessinées dans le conteneur se verront appliquer ces facteurs d'échelle. Pour l'exemple, le rectangle à dessiner aura la taille réelle suivante :
   largeur_reelle = largeur x Facteur_X soit 200 x 0,75 = 150
   hauteur_reelle = hauteur x Facteur_Y soit 200 x 0,75 = 150

Ce rectangle aura une translation en X et Y qui est fonction des paramètres X et X des coordonnées du rectangle source, du rectangle de destination et du rectangle à dessiner. La relation s'établie comme ceci :
  Valeur_X_reelle = (( X - src_X) * FacteurEchelle_X) + dest_X
  Valeur_Y_reelle = ((Y - src_Y) * FacteurEchelle_Y) + dest_Y

Avec les valeurs de l'exemple, Valeur_X_reelle et Valeur_Y_reelle valent :
  Valeur_X_reelle = (( X - src_X) * FacteurEchelle_X) + dest_X
  Valeur_X_reelle = (( 50 - 0) * 0,75) + 0
  Valeur_X_reelle = 38

  Valeur_Y_reelle = ((Y - src_Y) * FacteurEchelle_Y) + dest_Y
  Valeur_Y_reelle = ((30 - 0) * 0,75) + 0
  Valeur_Y_reelle = 22

Les graphiques sont toujours définis par l'angle supérieur gauche qui a pour coordonnées X=0/Y=0.
Si Valeur_X_reelle ou Valeur_Y_reelle sont négatifs, cela signifie que l'origine du rectangle dessiné se situe en dehors du graphique et n'est donc pas affichée.

L'exemple ci-dessous applique ces valeurs comme valeurs d'origine. Une grille quadrillée est dessinée, 4 curseurs permettent de faire varier les paramètres des rectangles sources et de destination du conteneur, les valeurs s'affichent et un rectangle rempli est dessiné qui correspond au rectangle voulu auquel les facteurs d'échelle et de translation sont appliqués. L'unité utilisée est le pixel.

Note de Microsoft (adapté à la programmation PB) :

Lorsque vous appelez une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2(), un bloc d'informations qui comporte l'état de l'objet Graphics est placé sur une pile. Une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2() retourne un objet GraphicsContainer qui identifie ce bloc d'informations. Lorsque vous passez l'objet d'identification à la fonction GdipEndContainer(), le bloc d'informations est supprimé de la pile et est utilisé pour rétablir l'objet Graphics dans l'état dans lequel il se trouvait lors de l'appel à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2().

Les conteneurs peuvent être imbriqués ; en d'autres termes, vous pouvez appeler une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2() plusieurs fois avant d'appeler la fonction GdipEndContainer(). Chaque fois que vous appelez une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2(), un bloc d'informations est placé sur la pile et vous recevez un identifiant GraphicsContainer pour ce bloc d'informations. Lorsque vous passez l'un de ces objets à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2(), l'objet Graphics est remis dans l'état dans lequel il se trouvait au moment de l'appel à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2() qui a retourné cet objet GraphicsContainer particulier. Le bloc d'informations placé sur la pile lors de cet appel à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2() est retiré de la pile, de même que tous les blocs d'informations placés sur cette pile après cet appel à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2().

Les appels à la fonction GdipSaveGraphics() permettent de placer des blocs d'informations sur la même pile que celle des appels à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2(). Tout comme un appel à la fonction GdipEndContainer() est associé à un appel à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2(), un appel à la fonction GdipRestoreGraphics() est associé à un appel à la fonction GdipSaveGraphics().

Lorsque vous appelez la fonction GdipEndContainer(), tous les blocs d'informations placés sur la pile (par la fonction GdipSaveGraphics() ou une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2()) après l'appel correspondant à une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2() sont retirés de la pile. De la même manière, lorsque vous appelez la fonction GdipRestoreGraphics(), tous les blocs d'informations placés sur la pile (par la fonction GdipSaveGraphics() ou par une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2()) après l'appel correspondant à la fonction GdipSaveGraphics() sont enlevés de la pile.

L'état des graphiques établi par une des fonctions GdipBeginContainer(), GdipBeginContainerI(), GdipBeginContainer2() comprend les qualités de rendu de l'état des graphiques par défaut ; tout changement de la qualité de rendu de l'état constaté au moment de l'appel à la fonction provoque le rétablissement des valeurs par défaut.

Si la fonction réussit, elle retourne #Ok qui est une constante de l'énumération status.
Si la fonction échoue, elle retourne une des autres valeurs de l'énumération status.