piDogScrollingCanvas
Protected Class piDogScrollingCanvas
Description
The control is designed to provide a natural feel with scroll, zoom and rotate gestures (Cocoa only).
Scrolling is handled by assigning a value to ScrollingLayerSize. You may then call RefreshRectScrollingLayer when a part of the layer has changed.
The PaintScrollingLayer Event will then be fired, allowing the drawing code to proceed.
The same is true for the DragLayer and OverlayLayer
One of the benefits of this system is that non-visible areas will not be drawn, but will remain "dirty" until they become visible reducing cpu usage.
When dirty areas in the ScrollingLayer, DragLayer, and/or OverlayLayer overlap, then areas are combined to reduce rendering steps.
When scrolling with a Magic Trackpad, the trackpad's inertial scrolling superceeds the canvas's inertial scrolling for a natural feel.
Zooming with a Magic Trackpad will focus the zoom area so as to keep the same point in the image under the mouse pointer through the zoom gesture.
The canvas has several modes:
Raster - The ScrollingLayer is rendered at 1:1 and scaled to zoom
Vector - The PaintScrollingLayer event is given a zoom factor for rendering, so rendering always appears at screen resolution.
Hybrid - Uses Raster mode when under 100% zoom and Vector otherwise
ReverseHybrid - Uses Vector mode when under 100% zoom and Raster otherwise
ScrollingImage and OverlayImage are non-dynamic versions of the similarly named dynamic layers and can be assigned in the IDE or at runtime.
To use piDogScrollingCanvas in your Xojo app, simply drag the canvas to a window and add needed events.
License
piDogScrollingCanvas is a custom Canvas subclass by piDog Software and is a part of the piDog Bundle for Xojo.
As a licensed user you have the right to use this class in your Xojo projects. Reverse engineering or breaking the encryption is prohibited.
Constants
AlignmentBottom
AlignmentCenter
AlignmentDefault
AlignmentLeft
AlignmentRight
AlignmentTop
RenderModeHybrid
Renders in Vector mode below 100% zoom, Raster above
RenderModeRaster
Rendering is scaled after painting at 100% zoom
RenderModeReverseHybrid
Vector mode above 100%, Raster mode below
RenderModeVector
Content is drawn on-demand at screen (Zoom) resolution
Enums
NSVisualEffectMaterials
WrapMode
Events
Activate
AdjustScrollerBounds
Called when scrollerbounds need adjusting. Change the properties of the bounds parameter to the desi
BackingScaleChanged
Called when the BackingScale of the window changes. ie. moving from retina-to non-retina.
Close
The control is about to close
ConstructContextualMenu
ConstructContextualMenuOverlayLayer
The user has right-clicked in the canvas at x,y. Return true to handle the event in the Overla
ConstructContextualMenuScrollingLayer
The user has right-clicked in the canvas at x,y. Return true to handle the event in the Scroll
ContextualMenuAction
ContextualMenuActionOverlayLayer
The user has selected a menuItem created in ConstructContextualMenuOverlayLayer.
ContextualMenuActionScrollingLayer
The user has selected a menuItem created in ConstructContextualMenuScrollingLayer.
Deactivate
doPreRender
DoubleClick
DragExit
DragOver
A drag event is occurring at x,y. Return false to pass the event throught to individual layers
DragOverOverlayLayer
A drag event is occuring at x,y. Return false to pass the event throught to scrolling layer.
DragOverScrollingLayer
A drag event is occuring at x,y relative to the scrollbounds.
DropObject
Standard DropObjec event.
DropObjectOverlayLayer
A drop occurred after true was returned from DragOverOverlayLayer.
DropObjectScrollingLayer
A Drop occurred after true was returned from DragOverScrollingLayer.
EdgeScroll
Return true from this event to prevent automated drag-scrolling behavior
GotFocus
KeyDown
LostFocus
Magnify
The user has used a pinch to zoom gesture. Return true to handle the zoom, otherwise automatic
MouseDown
The user has clicked in the control at x,y
MouseDownOverlayLayer
The User has clicked the mouse within the control at x,y. Return true to handle the event and
MouseDownScrollingLayer
The User has clicked the mouse within the control at x,y adjusted for scrolling and zooming. R
MouseDrag
The user has dragged the mouse at x,y
MouseDragOverlayLayer
User is dragging at x,y.
MouseDragScrollingLayer
User is dragging at x,y relative to scrollingarea, adjusted for scroll/zoom
MouseEnter
The mouse entered the control
MouseExit
The mouse has left the control
MouseMove
the mouse moved in the control at x,y
MouseMoveOverlayLayer
The mouse moved at x,y. Return true to prevent scrolling layer mouse moved event.
MouseMoveScrollingLayer
The mouse moved at x,y relative to the scrollig area, adjusted for zoom and not handled
MouseUp
Standard MouseUp Event
MouseUpOverlayLayer
MouseUp occurred at x,y after a MouseDownOverlay returned true.
MouseUpScrollingLayer
A MouseUp occurred at x,y relative to the scollbounds adjusted for scroll/zoom after true was
MouseWheelOverlayLayer
The scrollwheel was turned at x,y. Return true to handle the event, otherwise it will pa
MouseWheelScrollingLayer
A MouseWheel occurred at x,y relative to the scroll bounds, adjusted for scroll/zoom. Re
Open
The canvas is about to open.
PageLeft
The user has scrolled left by clicking below the scrollbar handle. Adjust targetRect to change desti
PageRight
The user has scrolled right by clicking below the scrollbar handle. Adjust targetRect to change dest
PageUp
The user has scrolled up by clicking below the scrollbar handle. Adjust targetRect to change destina
PaintDragLayer
area needs to be redrawn. g is the main graphics. m is the graphcs for masking under carbon/win32. Z
PaintOverlayLayer
area needs to be redrawn. g is the main graphics. m is the graphcs for masking under carbon/win32.
PaintScrollers
Return true to handle scroller painting and prevent built-in drawing
PaintScrollingLayer
area needs to be redrawn. g is the main graphics. m is the graphcs for masking under carbon/win32. Z
Resized
The Canvas was resized. Called after painting.
Resizing
The Canvas is resizing. Called before painting
Rotate
A rotate gesture occurred at x,y. Angle is the rotation delta.
ScrollabilityChanged
The CanScrollVertical or CanScrollHorizontal value has changed.
Scrolled
The scrollbounds have moved.
ScrollingLayerSizeChanged
Use this event to make adjusments based on the size of the scrolling layer.
ScrollPastX
The user has scrolled past a horizontal limit. leftBound will be true if the scroll was past the lef
ScrollPastY
The user has scrolled past a vertical limit. topBound will be true if the scroll was past the top ed
ThemeChanged
ZoomChanged
The current zoom value has changed, either through code or by a zoom gesture.
Methods
adjustVibrantView
BitmapForCaching

CanScrollHorizontal
whether the view can scroll Horizontally (read only)

CanScrollVertical
Whether the view can scroll Horizontally (read only)

Constructor
Standard Constructor
drawInto

Like standard Xojo drawInto function, but allows setting hidescrollers to avoid rendering scrollers
EnableVibrancy
Under MacOSX 10.10 calling this Method will enable vibrancy for the canvas and (optionally) the titl
FakeMouseDrag
getMouseX
GetMouseY
HorizontalScrollerIsVisible
Invalidate
Requests that the entire Canvas be redrawn.
invertcolor
MousePositionX
returns the current X location of the mouse relative to the scrollingLayer
MousePositionY
returns the current Y location of the mouse relative to the scrollingLayer
PageDown
Causes the view to scroll down by one page (the height of the control)
PrintTo
Refresh
Requests that the entire canvas be redrawn. Also clears cached renderings.
RefreshRect
Sets an area to be redrawn (all layers)
RefreshRectDragLayer
Sets an area in the drag layer to be redrawn.
RefreshRectScrollingLayer
Sets an area in the scrolling layer to be redrawn,
RefreshRectStaticLayer
Sets an area in the Overlay layer to be redrawn.
RenderToGraphics
Draws the layers to the passed graphics object rather than to screen
ScrollToRect
Scrolls the specified rectangle into view
SetInterpolationQuality

Snapshot
Returns a picture of the specified layers at 100% scale.
StartEdgeScrolling
TranslatePointFromView
Translates a point in View coords to position in scrollingLayer coordinates
TranslatePointToView
Translates a point in scrollingLayer coords to position in View coordinates
TranslateRectFromView
Translates a rect in View coords to area in ScrollingLayer coordinates
TranslateRectToView
Translates a rect in scrollingLayer coords to area in View coordinates
VerticalScrollerIsVisible
Properties
AlignmentHorizonal
Determines the Horizontal alignment when the scrollingLayer Is less wide than the view
AlignmentVertical
Determines the Vertical alignment when the scrollingLayer Is less tall than the view
AutoHideScrollers
Whether the scrollbars are hidden when not scrolling. On OS X this is set by the system.
BackdropImage
An Image to be drawn behind other layers
BackgroundColor
The color used to fill empty space in the canvas
BackgroundPattern
An image to be tiled beneath other layers aside from a BackdropImage.
BackingScale
The BackingScale of the window. On a Retina display returns 2
BorderColor
The color used to draw the border of the control.
Bordered
Set to true to draw a one-pixel border around the control
BuiltInScrollers
Whether to use the built in scrollers. Set to false to use scrollbars added to the window.
ClipScrollingLayerDrawing
When true(default), drawing outside of the area of the scrolling layer will be clipped.
DebugRects
When true, piDogScrollingCanvas will outline each area as it is drawn
DisableHorizontalBounce
When true, prevents scrolling past left or right of view
DisableVerticalBounce
When true, prevents scrolling past top or bottom of view
FPS
Returns the theoretical number of frames that could be drawn based on most recent frame
Interpolation
Whether scaled drawing should be interpolated or use the faster non-interpolated rendering.
isActive
isDarkMode
isMojave
LastFrameDuration
Used to benchmark rendering speed
MaxZoom
The maximum allowed zoom value
MinZoom
The minimum allowed zoom value
NSScrollerSlots
Whether Scroller slots are visible when using NSScrollers
NSScrollerStyle
The style of the NSScrollers when UseNativeScrollers is true
NSVisualEffectMaterial
/// The Material used for a visualEffectView under the control.
NSVisualEffectMaterialWindow
/// The Material used for a visualEffectView under the window.
OverlayImage
An Image to be rendered above all other layers.
PageScroll
Whether a click above or below the scroller will scroll by visible pages
renderMode
Sets the Rendering Mode for the canvas. See Constants for available modes.
ScrollbarBorderColor
The color used to draw outlines on the scrollers.
ScrollbarBorderSize
The original thickness of the scroller borders. Scrollers are drawn at double resolution and scaled
ScrollbarColor
The fill color for the scrollbars.
ScrollBarHorizontal
Whether a Horizontal scrollbar will be shown when the Horizontal content exceeds the Width of the co
ScrollBarsHaveBorder
Whether or not to render outlines for scrollbars.
ScrollBarSize
Width, in pixels of scrollbars.
ScrollBarVertical
Whether a Vertical scrollbar will be shown when the vertical content exceeds the height of the contr
ScrollerOnLeft
Scrolling
///Will return true while a scrollToRect or pageScroll is currently proceeding
ScrollingImage
An image to be drawn below the scrolling layer and above the backdrop image. This layer scrolls with
ScrollingLayerHeight
Set/Get the Height in points of the ScrollingLayer
ScrollingLayerSize
The actual size, in points, of the scrollable area.
ScrollingLayerWidth
The width of the ScrollingLayer
ScrollOnEdgeDrag
Whether the control will adjust scrolling layer and/or scrolling image when the user drags out of th
ScrollPast
Whether the canvas has a "snap-back" behavior. Also determines in the ScrollPastX and Scro
ScrollPosition
The position of the ScrollingImage and/or ScrollingLayer
ScrollPositionX
The Horizontal position of the ScrollingImage and/or ScrollingLayer
ScrollPositionY
The Vertical position of the ScrollingImage and/or ScrollingLayer
ScrollToDuration
The time to scroll to an area by calling ScrollToRect
ScrollwheelDuration
The time to scroll to the area made visible by scrolling with a scrollwheel or trackpad
ShowScrollButtons
SnapBackDuration
The time to snap the view back after scrolling past horizontal or vertical edges
UseDragLayer
Whether drawing should be performed for a drag layer. Set to false if the drag layer will not be use
UseNativeScrollers
Whether the control will use native NSScrollers to manage scrolling on MacOSX. The side effect of th
UseOverlayLayer
Whether the control will use a dynamic overlay layer
UseScrollingLayer
Whether drawing should be performed for a scrolling layer. Set to false if the scrolling layer is no
WrapAroundMode
How to handle wrapping around when scrolling past an edge of the view.
Zoom
The zoom factor of the view
ZoomPoint
The point (scrolling layer based coordinates) where zooming in or out will attempt to focus the view
Shared Methods
NS_DummyDraw
Register
Used to enter piDog Bundle / piDogScrollingCanvas Registration Key. If not registered, a warning wil