GdipBeginContainer2()

Resultat.i = GdipBeginContainer2(*graphics, @*state)

*graphics
[in] Pointeur sur un objet Graphics existant.

*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 appel de la fonction GdipBeginContainer2() doit correspondre un appel à la fonction GdipEndContainer() lorsque le conteneur graphique n'est plus utile.

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.

Le premier exemple utilise un graphique à partir de l'identifiant système de la fenêtre. Un premier conteneur graphique est créé, ensuite on applique au graphique une translation en x de 50 et y de 150. Un deuxième conteneur est créé sans fermer le premier avec la fonction GdipEndContainer(), on applique au graphique une translation en x de -50 et en y de -150 ce qui revient à n'avoir plus aucune translation pour le graphique. Un rectangle de 200 x 200 est dessiné et rempli en rouge à la position x = 0 et y = 0. Le deuxième container est fermé avec la fonction GdipEndContainer(). Par conséquent, on revient au premier conteneur dont les caractéristiques s'appliquent au graphique, soit la translation en x de 50 et y de 150.
Lorsque le timer déclenche la première fois, on dessine et rempli un rectangle de 200 x 200 en jaune à la position x = 0 etr y = 0. Ce rectangle est réellement positionné en x = 50 et y = 150 du aux propriétés du conteneur appliquées au graphique. Au deuxième déclenchement du timer, l'application se ferme.

Le deuxième exemple utilise un graphique à partir de l'identifiant système de la fenêtre et lui applique une translation en x de 10 et y de 10 avant de créer les conteneurs graphiques. Un premier conteneur graphique est créé, ensuite on applique au graphique une translation en x de 50 et y de 150. Un deuxième conteneur est créé sans fermer le premier avec la fonction GdipEndContainer(), on applique au graphique une translation en x de -60 et en y de -160 ce qui revient à n'avoir plus aucune translation pour le graphique. Un rectangle de 200 x 200 est dessiné et rempli en rouge à la position x = 0 etr y = 0. Le deuxième container est fermé avec la fonction GdipEndContainer(). Par conséquent, on revient au premier conteneur dont les caractéristiques s'appliquent au graphique, soit la translation en x de 50 et y de 150 par rapport à l'origine du graphique qui est à x = 10 et y = 10.
Lorsque le timer déclenche la première fois, le premier conteneur graphique est fermé, ce qui fait que le graphique retrouve ses coordonnées d'avant la création du premier conteneur, soit x = 10 et y = 10. On dessine et rempli un rectangle de 200 x 200 en jaune à la position x = 0 etr y = 0. Ce rectangle est réellement positionné en x = 10 et y = 10 du aux propriétés initiales du graphique. Au deuxième déclenchement du timer, l'application se ferme.

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.