What is the purpose of the canvas gadget?

[Mistrel]

I've never used it as I made due without before it existed by leveraging the other libraries provided. For a full-window application there is WindowOutput() and for gadgets there is ImageOutput() + ImageGadget(). Everything else can already be done with events, I think.

What can the canvas gadget do that can't be done with the other drawing outputs?

[Hadrianus]

Not to worry about re-draw after resizing etc, unlike the use of Windowoutput(). So, your drawing remains intact in the canvas. I am not familiair with windows api for keeping drawings intact.

[wombats]

It's an easy to use, cross-platform drawing output. It can be used for custom gadgets, displaying images as you wish, etc.

[Demivec]

It also receives a large collection of gadget events, unlike an ImageGadget. This means it is useful for custom gadgets.

[netmaestro]

Demivec has called it. True, as a drawing surface there are alternatives just as good. But the real strength is in the rich variety of native events that the gadget handles, most of which would otherwise only be available through a callback and lots of API. You can take a canvas gadget and craft any kind of custom control you can imagine out of it without once dipping into OS-specific code. That's worth a lot and many on the forum have done so, singing its praises all the way. Yes, the canvas was a real home run for the PB team, one of the best new features ever released. And with the latest release of PB, it's even been enhanced to function as a container for other gadgets, making custom control creation even easier.

[wombats]

Demivec has called it. True, as a drawing surface there are alternatives just as good. But the real strength is in the rich variety of native events that the gadget handles, most of which would otherwise only be available through a callback and lots of API. You can take a canvas gadget and craft any kind of custom control you can imagine out of it without once dipping into OS-specific code. That's worth a lot and many on the forum have done so, singing its praises all the way. Yes, the canvas was a real home run for the PB team, one of the best new features ever released. And with the latest release of PB, it's even been enhanced to function as a container for other gadgets, making custom control creation even easier.

Indeed. The Dialog library and the CanvasGadget have truly made PureBasic the ideal language for me.

[Mistrel]

Would someone provide an example of a canvas event which cannot be reproduced with an ImageGadget()?

[netmaestro]

Code: Select all

Canvas Gadget                      Image Gadget

#PB_EventType_MouseEnter           
#PB_EventType_MouseLeave           
#PB_EventType_MouseMove                   
#PB_EventType_MouseWheel           
#PB_EventType_LeftButtonDown       
#PB_EventType_LeftButtonUp         
#PB_EventType_LeftClick            yes
#PB_EventType_LeftDoubleClick      yes
#PB_EventType_RightButtonDown 
#PB_EventType_RightButtonUp   
#PB_EventType_RightClick           yes
#PB_EventType_RightDoubleClick     yes
#PB_EventType_MiddleButtonDown 
#PB_EventType_MiddleButtonUp   
#PB_EventType_Focus            
#PB_EventType_LostFocus        
#PB_EventType_KeyDown          
#PB_EventType_KeyUp            
#PB_EventType_Input            
#PB_EventType_Resize              

Many more events but not only that - a wealth of attributes available with Get/SetGadgetAttribute():

Further information about the current event can be received with the GetGadgetAttribute() function.

This information is only available if the current event received by WaitWindowEvent() or WindowEvent() is an event for this gadget. The following attributes can be used:

#PB_Canvas_MouseX, #PB_Canvas_MouseY
Returns the given mouse coordinate relative to the drawing area of the gadget. This returns the mouse location at the time that the event was generated, so the result can differ from the coordinates reported by WindowMouseX() and WindowMouseY() which return the current mouse location regardless of the state of the processed events. The coordinates returned using these attributes should be used for this gadget to ensure that the mouse coordinates are in sync with the current event.
#PB_Canvas_Buttons
Returns the state of the mouse buttons for the event. The result is a combination (using bitwise or) of the following values:
#PB_Canvas_LeftButton : The left button is currently down.
#PB_Canvas_RightButton : The right button is currently down.
#PB_Canvas_MiddleButton: The middle button is currently down.

#PB_Canvas_Modifiers
Returns the state of the keyboard modifiers for the event. The result is a combination (using bitwise or) of the following values:
#PB_Canvas_Shift : The 'shift' key is currently pressed.
#PB_Canvas_Alt : The 'alt' key is currently pressed.
#PB_Canvas_Control: The 'control' key is currently pressed.
#PB_Canvas_Command: The 'command' (or "apple") key is currently pressed. (Mac OSX only)

#PB_Canvas_WheelDelta
Returns the movement of the mouse wheel in the current event in multiples of 1 or -1. A positive value indicates that the wheel was moved up (away from the user) and a negative value indicates that the wheel was moved down (towards the user). This attribute is 0 if the current event is not a #PB_EventType_MouseWheel event.
#PB_Canvas_Key
Returns the key that was pressed or released in a #PB_EventType_KeyDown or #PB_EventType_KeyUp event. The returned value is one of the #PB_Shortcut_... values used by the AddKeyboardShortcut() function. This attribute returns raw key presses. To get text input for the gadget, it is better to watch for #PB_EventType_Input events and use the #PB_Canvas_Input attribute because it contains the text input from multiple key presses such as shift or dead keys combined.
#PB_Canvas_Input
Returns the input character that was generated by one or more key presses. This attribute is only present after a #PB_EventType_Input event. The returned character value can be converted into a string using the Chr() function.
In addition to this event information, GetGadgetAttribute() can also be used to read the following attributes:

#PB_Canvas_Image
Returns an ImageID value that represents an image with the current content of the CanvasGadget. This value can be used to draw the content of the gadget to another drawing output using the DrawImage() function.

Note: The returned value is only valid until changes are made to the gadget by resizing it or drawing to it, so it should only be used directly in a command like DrawImage() and not stored for future use.
#PB_Canvas_Clip
Returns non-zero if the mouse is currently clipped to the gadget area or zero if not.
#PB_Canvas_Cursor
Returns the cursor that is currently used in the gadget. See below for a list of possible values. If the gadget is using a custom cursor handle, the return-value is -1.
#PB_Canvas_CustomCursor
Returns the custom cursor handle that was set using SetGadgetAttribute(). If the gadget uses a standard cursor, the return-value is 0.

The SetGadgetAttribute() function can be used to modify the following gadget attributes

#PB_Canvas_Image
Applies the given ImageID to the CanvasGadget. The gadget makes a copy of the input image so it can be freed or reused after this call. Setting this attribute is the same as using StartDrawing(), CanvasOutput() and DrawImage() to draw the image onto the CanvasGadget.
#PB_Canvas_Clip
If the value is set to a non-zero value, the mouse cursor will be confined to the area of the canvas gadget. Setting the value to zero removes the clipping.

Note: Mouse clipping should only be done as a direct result of user interaction with the gadget such as a mouse click and care must be taken to properly remove the clipping again or the user's mouse will be trapped inside the gadget. The #PB_Canvas_ClipMouse gadget flag can be used to automatically clip/unclip the mouse when the user presses or releases a mouse button in the gadget.
#PB_Canvas_Cursor
Changes the cursor that is displayed when the mouse is over the gadget. The following values are possible:
#PB_Cursor_Default : default arrow cursor
#PB_Cursor_Cross : crosshair cursor
#PB_Cursor_IBeam : I-cursor used for text selection
#PB_Cursor_Hand : hand cursor
#PB_Cursor_Busy : hourglass or watch cursor
#PB_Cursor_Denied : slashed circle or X cursor
#PB_Cursor_Arrows : arrows in all direction (not available on Mac OSX)
#PB_Cursor_LeftRight : left and right arrows
#PB_Cursor_UpDown : up and down arrows
#PB_Cursor_LeftUpRightDown: diagonal arrows (Windows only)
#PB_Cursor_LeftDownRightUp: diagonal arrows (Windows only)
#PB_Cursor_Invisible : hides the cursor

#PB_Canvas_CustomCursor
Changes the cursor that is displayed when the mouse is over the gadget to a custom cursor handle created using the corresponding OS API. This attribute expects the following kind of input:
Windows: a HCURSOR handle
Linux: a GtkCursor pointer
Mac OSX: a pointer to a Cursor structure

The image gadget handles four of the events and none of the attributes. If you need to do any of this with an imagegadget, it's API time.

[Mistrel]

I see now. I use SetWindowCallback() so heavily than I didn't realize how little control we had previously.

For example, #PB_Event_LeftClick is received only when clicking on the window and not its children:

Code: Select all

Window=OpenWindow(#PB_Any,0,0,320,240,"")
Image=CreateImage(#PB_Any,160,240,32,RGB(0,0,0))
ImageGadget=ImageGadget(#PB_Any,0,0,160,24,ImageID(Image))

Repeat
  WindowEvent=WaitWindowEvent(1)
  
  Select WindowEvent
    Case #PB_Event_LeftClick
      Debug "Click Window! "+Str(Random(255,0))
  EndSelect
Until WindowEvent=#PB_Event_CloseWindow

You could monitor MouseButton() in the main loop but it would be a race condition.