CanvasGadget()

Syntaxe

Resultat = CanvasGadget(#Gadget, X, Y, Largeur, Hauteur [, Options])
Description
Crée un canvas dans la GadgetList en cours.

Ce gadget offre une surface de dessin sans canal alpha et d'évènements pour la souris et le clavier dans le but de créer facilement des affichages personnalisées.

Arguments

#Gadget Numéro d'identification du canvas.

#PB_Any peut être utilisé pour générer automatiquement ce numéro.
X, Y, Largeur, Hauteur Position et dimensions du canvas en pixels.
Les valeurs maximales pour la largeur et la hauteur sont de 16 000 pixels.
Options (optionnel) Combinaison des constantes suivantes:
  #PB_Canvas_Border   : Trace une bordure autour du gadget.
  
  #PB_Canvas_ClipMouse: Capture automatiquement la souris dans la zone 
                        du gadget tant qu'un bouton de la souris est appuyé.
                        (Non supporté par OS X).
  
  #PB_Canvas_Keyboard : Reçoit le focus du clavier ainsi que les évènements clavier.
                        Avec cette option, utilisez les évènements #PB_EventType_Focus 
                        et #PB_EventType_LostFocus pour identifier le gadget qui a le focus. 
                        Une autre façon de savoir si le canvas a le focus, est l'utilisation de #PB_Canvas_DrawFocus 
                        qui dessine un rectangle de focus chaque fois qu'il a le focus.

  #PB_Canvas_DrawFocus: Dessine un rectangle de focus sur le gadget s'il a le focus clavier.
  
  #PB_Canvas_Container: Permet le support du mode conteneur afin d'y ajouter des gadgets. CloseGadgetList() 
                        doit être appelé pour revenir à la liste de gadgets précédente comme tout autre conteneur.
                        Sous Windows, la transparence des gadgets n'est pas prise en compte ainsi le texte des gadgets 
                        suivants sera affiché sur un fond opaque: CheckBoxGadget, FrameGadget, HyperlinkGadget, 
                        OptionGadget, TextGadget et TrackBarGadget.



Valeur de retour

Renvoie une valeur non nulle en cas de succès ou une valeur nulle en cas d'échec.

Si #PB_Any a été utilisé alors la valeur retournée est son numéro d'dentification en cas de succès.

Remarques

- Le CanvasGadget() n'ayant pas de canal alpha (transparence), les modes #PB_2DDrawing_AlphaChannel de la fonction DrawingMode() n'aura aucun effet et le mode #PB_2DDrawing_AllChannels sera équivalent à #PB_2DDrawing_Default

- Le gadget apparaît comme un simple fond blanc.

- Utiliser la commande CanvasOutput() ou la commande CanvasVectorOutput() pour dessiner sur le canvas.

- Le contenu reste persistant jusqu'à ce qu'il soit effacé par une opération de dessin.

- Il n'est pas nécessaire de redessiner le contenu à chaque fois qu'un évènement #PB_Event_Repaint est reçu.



.:Evènements:.

Le canvas renvoie les types d'évènements EventType() suivant: 
Connaitre l'état du canvas: GetGadgetAttribute() avec les options suivantes:
#PB_EventType_MouseEnter : Le curseur de la souris est entré dans le gadget #PB_EventType_MouseLeave : Le curseur de la souris est sorti du gadget #PB_EventType_MouseMove : Le curseur de la souris a bougé #PB_EventType_MouseWheel(*) : La molette de la souris a bougé #PB_EventType_LeftButtonDown : Le bouton gauche de la souris a été pressé #PB_EventType_LeftButtonUp : Le bouton gauche de la souris a été relâché #PB_EventType_LeftClick : Un clic avec le bouton gauche de la souris #PB_EventType_LeftDoubleClick : Un double-clic avec le bouton gauche de la souris #PB_EventType_RightButtonDown : Le bouton droit de la souris a été pressé #PB_EventType_RightButtonUp : Le bouton droit de la souris a été relâché #PB_EventType_RightClick : Un clic avec le bouton droit de la souris #PB_EventType_RightDoubleClick: Un double-clic avec le bouton droit de la souris #PB_EventType_MiddleButtonDown: Le bouton central de la souris a été pressé #PB_EventType_MiddleButtonUp : Le bouton central de la souris a été relâché #PB_EventType_Focus : Le gadget a obtenu le focus clavier #PB_EventType_LostFocus : Le gadget a perdu le focus clavier #PB_EventType_KeyDown(*) : Une touche clavier a été pressée #PB_EventType_KeyUp(*) : Une touche clavier a été relâchée #PB_EventType_Input(*) : Du texte a été entré dans le gadget #PB_EventType_Resize : Le gadget a été redimensionné (*) Les évènements #PB_EventType_KeyDown, #PB_EventType_KeyUp et #PB_EventType_Input sont renvoyés seulement si le gadget a le focus clavier (Voir l'option #PB_Canvas_Keyboard).
Avec Windows, l'évènement #PB_EventType_MouseWheel est renvoyé seulement si le gadget a le focus clavier. Avec les autres OS, cet évènement est renvoyé au gadget sous le curseur, qu'il ait le focus clavier ou non.

.:Attributs:. Les connaître.

  - GetGadgetAttribute() permet de connaître les attributs du canvas avec les options suivantes:
Souris:
  - #PB_Canvas_MouseX    : Renvoie les coordonnées de la souris dans la zone de dessin du canvas 
  - #PB_Canvas_MouseY    : au moment où l'évènement a été généré.
                           Note: Le résultat peut être différent des coordonnées envoyées par WindowMouseX() et par 
                                 WindowMouseY() qui elles, renvoient l'emplacement actuel de la souris indépendamment des 
                                 évènements.

  - #PB_Canvas_Buttons   : Renvoie l'état des boutons de la souris.
                           Peut être une combinaison de: 
                             #PB_Canvas_LeftButton  : Le bouton de gauche est actuellement enfoncé.  
                             #PB_Canvas_RightButton : Le bouton de droite est actuellement enfoncé.  
                             #PB_Canvas_MiddleButton: Le bouton du milieu est actuellement enfoncé.

  - #PB_Canvas_WheelDelta: Renvoie le mouvement de la molette de la souris par multiple de 1 ou -1.
                           Une valeur positive indique que la roue a été tournée vers le haut (en l'éloignant de 
                           l'utilisateur) et une valeur négative indique que la roue a été déplacée vers le bas 
                           (vers l'utilisateur). 
                           Cet attribut est à 0 si l'évènement en cours n'est pas un évènement #PB_EventType_MouseWheel.
  
  - #PB_Canvas_Clip      : Renvoie une valeur non nulle si la souris est confinée dans le canvas, zéro sinon.
  
  - #PB_Canvas_Cursor    : Renvoie le curseur qui est actuellement utilisé dans le gadget.
                           Voir ci-dessous pour obtenir une liste des valeurs possibles. 
                           Si le gadget utilise un handle de curseur personnalisé, la valeur retournée est -1.
  
  - #PB_Canvas_CustomCursor: Renvoie le handle personnalisé du curseur qui a été défini à l'aide de SetGadgetAttribute(). 
                             Si le gadget utilise un curseur standard, la valeur retournée est zéro. 
Clavier:
   - #PB_Canvas_Modifiers: Renvoie l'état des touches de contrôle du clavier. 
                           Peut être une combinaison de:
                             #PB_Canvas_Shift  : La touche 'Shift' est actuellement pressée. 
                             #PB_Canvas_Alt    : La touche 'Alt' est actuellement pressée. 
                             #PB_Canvas_Control: La touche 'Control' est actuellement pressée. 
                             #PB_Canvas_Command: La touche 'Command' (ou 'Pomme') est actuellement pressée. (OS X seulement)

  - #PB_Canvas_Key  : Renvoie la touche du clavier qui a été enfoncée ou relâchée après un évènement #PB_EventType_KeyDown ou un évènement #PB_EventType_KeyUp et 
                      la valeur retournée est l'une des constantes #PB_Shortcut_ ... qui sont utilisées par la fonction AddKeyboardShortcut(). 
                      Note: Cet attribut renvoie la première touche pressée. 
                      Note: Pour obtenir un texte saisi au clavier dans le Canvasgadget, il est préférable d'utiliser l'évènement #PB_EventType_Input 
                            avec l'attribut #PB_Canvas_Input, car il permet la saisie de texte à partir d'une combinaison de plusieurs touches telles 
                            que la touche 'Shift' et autres touches muettes.

  - #PB_Canvas_Input: Renvoie le caractère qui a été généré par une ou plusieurs touches. Cet attribut n'est présent qu'après un évènement #PB_EventType_Input. 
                      La valeur du caractère retourné peut être convertie en une chaîne de caractères en utilisant la fonction Chr().   
Image:
  - #PB_Canvas_Image: Renvoie un ImageID, valeur qui représente le numéro d'une image avec le contenu actuel du CanvasGadget. 
                      Cette valeur peut être utilisée pour dessiner le contenu du gadget vers une autre surface de dessin en utilisant la fonction DrawImage(). 
                      Note: La valeur retournée est valable uniquement jusqu'à l'apparition d'une modification apportée au gadget comme le 
                            redimensionnement ou un changement dans le dessin, donc elle ne devrait être utilisée directement que dans une commande de 
                            type DrawImage() et ne pas être stockée pour une utilisation future.
Attention: Ces informations ne sont disponibles que si l'évènement courant reçu par WaitWindowEvent() ou WindowEvent() provient d'un canvas.






.:Attributs:. Les modifier.

  - SetGadgetAttribute() permet de changer les attributs du canvas avec les options suivantes:
Souris:
  - #PB_Canvas_Clip: Une valeur non nulle et le mouvement du curseur de la souris sera confiné à la zone du canvas gadget. 
                     Avec une valeur nulle, cela supprime le confinement. 
                     Note: Le confinement de la souris doit être uniquement le résultat direct de l'action de l'utilisateur sur le canvas, comme un clic de souris par exemple, 
                           et il faut prendre soin de bien enlever le confinement à nouveau, sinon l'utilisateur sera emprisonné à l'intérieur du gadget. 
                     L'option #PB_Canvas_ClipMouse peut être utilisée pour automatiquement capturer/relâcher la souris lorsque l'utilisateur appuie ou relâche le bouton 
                     de la souris dans le canvas. 

  - #PB_Canvas_Cursor: Change le curseur lorsque la souris survole le gadget. 
                       Les valeurs suivantes sont possibles: 
                         #PB_Cursor_Default   : Flèche du curseur par défaut 
                         #PB_Cursor_Cross     : Curseur en forme de croix 
                         #PB_Cursor_IBeam     : Barre d'insertion 'I' utilisée pour la sélection de texte  
                         #PB_Cursor_Hand      : Curseur main 
                         #PB_Cursor_Busy      : Curseur sablier ou une montre 
                         #PB_Cursor_Denied    : Curseur cercle barré ou curseur X 
                         #PB_Cursor_Arrows    : Flèches dans toutes les directions (non disponible sur OS X) 
                         #PB_Cursor_LeftRight : Flèches gauche et droite 
                         #PB_Cursor_UpDown    : Flèches haut et bas 
                         #PB_Cursor_LeftUpRightDown: Flèches diagonales (Windows uniquement) 
                         #PB_Cursor_LeftDownRightUp: Flèches diagonales (Windows uniquement)  
                         #PB_Cursor_Invisible      : Cache le curseur 

  - #PB_Canvas_CustomCursor: Change le curseur lorsque la souris survole le gadget en un curseur personnalisé créé en utilisant l'API de l'OS correspondant.

                             Le type attendu est: 
                               Avec Windows: Un handle HCURSOR 
                               Avec Linux  : Un pointeur GtkCursor 
                               Avec OS X: Un pointeur vers une structure Curseur 

Image:
  - #PB_Canvas_Image: Applique l'ImageID au CanvasGadget. 
                      Le gadget fait une copie de l'image d'entrée afin qu'elle puisse être libérée ou réutilisée après cet appel. 
                      Utiliser cet attribut revient à utiliser StartDrawing(), CanvasOutput() et DrawImage() pour dessiner l'image sur le CanvasGadget.  
  - GadgetToolTip() permet d'ajouter une 'mini aide' à ce gadget. 

Exemple

  If OpenWindow(0, 0, 0, 220, 220, "CanvasGadget", #PB_Window_SystemMenu | #PB_Window_ScreenCentered)
    CanvasGadget(0, 10, 10, 200, 200)
    
    Repeat
      Event = WaitWindowEvent()
          
      If Event = #PB_Event_Gadget And EventGadget() = 0 
        If EventType() = #PB_EventType_LeftButtonDown Or (EventType() = #PB_EventType_MouseMove And GetGadgetAttribute(0, #PB_Canvas_Buttons) & #PB_Canvas_LeftButton)
          If StartDrawing(CanvasOutput(0))
            x = GetGadgetAttribute(0, #PB_Canvas_MouseX)
            y = GetGadgetAttribute(0, #PB_Canvas_MouseY)
            Circle(X, Y, 10, RGB(Random(255), Random(255), Random(255)))
            StopDrawing()
          EndIf
        EndIf
      EndIf    
      
    Until Event = #PB_Event_CloseWindow
  EndIf

Exemple: Canvas container

If OpenWindow(0, 0, 0, 220, 220, "Canvas container", #PB_Window_SystemMenu | #PB_Window_ScreenCentered)
  
  CanvasGadget(0, 10, 10, 200, 200, #PB_Canvas_Container)
  ButtonGadget(1, 10, 10, 80, 30, "Effacer")
  CloseGadgetList()
  
  Repeat
    Event = WaitWindowEvent()
    
    If Event = #PB_Event_Gadget
      Select EventGadget() 
        Case 0
          If EventType() = #PB_EventType_LeftButtonDown Or (EventType() = #PB_EventType_MouseMove And GetGadgetAttribute(0, #PB_Canvas_Buttons) & #PB_Canvas_LeftButton)
            If StartDrawing(CanvasOutput(0))
              x = GetGadgetAttribute(0, #PB_Canvas_MouseX)
              y = GetGadgetAttribute(0, #PB_Canvas_MouseY)
              Circle(x, y, 10, RGB(Random(255), Random(255), Random(255)))
              StopDrawing()
            EndIf
          EndIf
          
        Case 1
          If StartDrawing(CanvasOutput(0))
            Box(0, 0, 200, 200, #White)
            StopDrawing()
          EndIf
      EndSelect
    EndIf
    
  Until Event = #PB_Event_CloseWindow
EndIf

Exemple

CanvasGadget.pb

Voir aussi

CanvasOutput(), GetGadgetAttribute(), SetGadgetAttribute(), EventType(), StartDrawing()

OS Supportés

Tous

<- CalendarGadget() - Gadget Index - CanvasOutput() ->