RadPictureBoxElement
This class is used to display raster or vector images. It allows image scrolling as well as pan, zoom, image editing and many more.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
public class RadPictureBoxElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProvider
Inheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemUIItemBaseLightVisualElementRadPictureBoxElement...
Implements:
Inherited Members
Constructors
Initializes a new instance of the RadPictureBoxElement class.
public RadPictureBoxElement()
Properties
Gets or sets a value indicating whether to show animations when showing and hiding panels. Note that animations are applied only when PanelDisplayMode is set to OnMouseHover.
public bool AllowPanelAnimations { get; set; }
Gets the bottom panel element. This panel allows adding buttons label and other elements in three collections - left, center and right items.
public PictureBoxHorizontalPanelElement BottomPanel { get; }
Gets the element that is responsible for painting the image.
public PictureBoxCanvasElement CanvasElement { get; }
Gets the context menu.
public RadContextMenuDropDown ContextMenu { get; }
Gets or sets a value indicating whether to display context menu on right mouse click.
[Browsable(false)]
public bool ContextMenuEnabled { get; set; }
Gets the context menu related properties.
public PictureBoxContextMenuProperties ContextMenuProperties { get; }
Gets the horizontal scrollbar element.
public RadScrollBarElement HorizontalScrollBar { get; }
Gets or sets the alignment of the image on the drawing surface. Default is TopLeft. Note that this property is respected only when the ImageLayout is set to None.
public override ContentAlignment ImageAlignment { get; set; }
Overrides:
Gets or sets the dialog responsible for image editing.
public PictureBoxImageEditorDialog ImageEditorDialog { get; set; }
Gets the left panel element. This panel allows adding buttons label and other elements in three collections - top, center and bottom items.
public PictureBoxVerticalPanelElement LeftPanel { get; }
Gets the element that holds the image visible when there is no image(raster or vector) assigned.
public LightVisualElement NoPictureImageElement { get; }
Gets the StackLayoutPanel that is displayed when there is no image(raster or vector) assigned.
public StackLayoutPanel NoPictureStack { get; }
Gets the element that holds the text visible when there is no image(raster or vector) assigned.
public LightVisualElement NoPictureTextElement { get; }
Gets or sets a value indicating how the panels are displayed. The possible options are: always or on mouse hover.
public PictureBoxPanelDisplayMode PanelDisplayMode { get; set; }
Gets or sets a value indicating how the panels are positioned.
public PictureBoxPanelOverflowMode PanelOverflowMode { get; set; }
Specifies how the image is positioned on the element.
public virtual RadImageLayout RadImageLayout { get; set; }
Determines if users can only view the image with no interaction: zoom and context menu are not available when read only is true.
[Browsable(true)]
public bool ReadOnly { get; set; }
Gets the right panel element. This panel allows adding buttons label and other elements in three collections - top, center and bottom items.
public PictureBoxVerticalPanelElement RightPanel { get; }
Gets or sets a value indicating whether to display scrollbars when the displayed image is larger than the element.
public bool ShowScrollBars { get; set; }
Gets the top panel element. This panel allows adding buttons label and other elements in three collections - left, center and right items.
public PictureBoxHorizontalPanelElement TopPanel { get; }
Gets the vertical scrollbar element.
public RadScrollBarElement VerticalScrollBar { get; }
Gets the properties responsible for the zoom operations.
public PictureBoxZoomProperties ZoomProperties { get; }
Methods
Arranges the RadPictureBoxElement to its final location. The element must call the Arrange method of each of its children.
protected override SizeF ArrangeOverride(SizeF finalSize)
The size that is available for element.
Returns:The rectangle occupied by the element. Usually finalSize. Should you return different size, the Layout system will restart measuring and rearranging the items. That could lead to infinite recursion.
Overrides:
In this method call to the Arrange method of each child must be made.
Calculates the new canvas offset that keeps the image position under the zoom pivot aligned after resizing.
protected virtual SizeF CalculateZoomOffset(double newZoomFactor, SizeF newCanvasSize)
The target zoom factor supplied to this overridable calculation.
newCanvasSizeSizeFThe canvas size after the zoom update.
Returns:The offset that keeps the image-relative pivot position aligned with the zoom point.
Removes the image and/or svg image.
public virtual void ClearImage()
Copies the displayed image into the clipboard.
public virtual void CopyImage()
Creates the horizontal panel displayed along the bottom edge for hosting PictureBox panel items. Override this factory to provide a specialized panel element.
protected virtual PictureBoxHorizontalPanelElement CreateBottomPanel()
PictureBoxHorizontalPanelElement
The panel added to the bottom of the PictureBox element tree.
Creates the canvas that paints and positions the image displayed by this PictureBox.
protected virtual PictureBoxCanvasElement CreateCanvasElement()
The image canvas associated with this element.
Called by the element when constructed. Allows inheritors to build the element tree.
protected override void CreateChildElements()
Overrides:
Creates the drop-down menu shown for the PictureBox's built-in image actions.
protected virtual RadContextMenuDropDown CreateContextMenu()
The context menu used by this element.
Creates the settings object that supplies and configures the PictureBox context-menu items.
protected virtual PictureBoxContextMenuProperties CreateContextMenuProperties()
PictureBoxContextMenuProperties
The context-menu settings associated with this element.
Creates the scrollbar used to pan the image horizontally when it extends beyond the viewport.
protected virtual RadScrollBarElement CreateHorizontalScrollBarElement()
The horizontal image scrollbar.
Creates the vertical panel displayed along the left edge for hosting PictureBox panel items. Override this factory to provide a specialized panel element.
protected virtual PictureBoxVerticalPanelElement CreateLeftPanel()
PictureBoxVerticalPanelElement
The panel added to the left of the PictureBox element tree.
Creates the element that displays the default image in the no-image placeholder.
protected virtual LightVisualElement CreateNoPictureImageElement()
The placeholder image element.
Creates the vertical layout container for the no-image placeholder.
protected virtual StackLayoutPanel CreateNoPictureStack()
The stack containing the placeholder image and text elements.
Creates the element that displays the localized message in the no-image placeholder.
protected virtual LightVisualElement CreateNoPictureTextElement()
The placeholder text element.
Creates the vertical panel displayed along the right edge for hosting PictureBox panel items. Override this factory to provide a specialized panel element.
protected virtual PictureBoxVerticalPanelElement CreateRightPanel()
PictureBoxVerticalPanelElement
The panel added to the right of the PictureBox element tree.
Creates the horizontal panel displayed along the top edge for hosting PictureBox panel items. Override this factory to provide a specialized panel element.
protected virtual PictureBoxHorizontalPanelElement CreateTopPanel()
PictureBoxHorizontalPanelElement
The panel added to the top of the PictureBox element tree.
Creates the scrollbar used to pan the image vertically when it extends beyond the viewport.
protected virtual RadScrollBarElement CreateVerticalScrollBarElement()
The vertical image scrollbar.
Creates the settings object that controls zoom behavior for this PictureBox.
protected virtual PictureBoxZoomProperties CreateZoomProperties()
The zoom settings associated with this element.
Copies the displayed image into the clipboard and clears the displayed image.
public virtual void CutImage()
Detaches parent-control mouse handlers before disposing managed resources.
protected override void DisposeManagedResources()
Overrides:
Edits the image using a RadImageEditor displayed in a PictureBoxImageEditorDialog.
public void EditImage()
Enables image actions when an image is present and enables Paste only when the clipboard contains an image.
protected virtual void EnableContextMenuItems()
Hides the panels.
public virtual void HidePanels(bool animate = true)
A value indicating whether to use animation.
Initializes member fields to their default values. This method is called prior the CreateChildItems one and allows for initialization of members on which child elements depend.
protected override void InitializeFields()
Overrides:
Opens an OpenFileDialog which allows the user to choose an image.
public virtual void LoadImage()
Measures the image layout and auxiliary elements, including border, padding, and the optional horizontal line.
Recalculates image layout or pan and scrollbar state when the element's bounds change.
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)
The bounds property change and its old and new values.
Overrides:
Raises the ContextMenuClosed event.
protected virtual void OnContextMenuClosed()
Raises the ContextMenuClosing event.
protected virtual void OnContextMenuClosing(CancelEventArgs args)
The event arguments
Raises ContextMenuItemClick before running the selected built-in action; setting Handled suppresses that default action.
Raises the ContextMenuOpened event.
protected virtual void OnContextMenuOpened()
Raises the ContextMenuOpening event.
protected virtual void OnContextMenuOpening(CancelEventArgs args)
The event arguments
Raises ImageLoaded with Empty for legacy overrides. Override the typed overload to receive image kind and load-context information.
[Obsolete("Override OnImageLoaded(ImageKind, LoadImageContext, string) instead.")]
protected virtual void OnImageLoaded()
Raises ImageLoaded with details about the loaded image and its source.
protected virtual void OnImageLoaded(ImageKind imageKind, LoadImageContext loadContext, string filePath = null)
Whether the loaded content is a raster or SVG image.
loadContextLoadImageContextWhether the image was loaded from a file or the clipboard.
filePathstringThe source file path, when the image was loaded from a file.
Raises ImageSaved after the displayed image has been saved successfully.
protected virtual void OnImageSaved()
Begins a pan operation on left-button down when the image can be panned.
protected override void OnMouseDown(MouseEventArgs e)
The mouse button and pointer position.
Overrides:
Updates the pan offset during a captured drag, reversing horizontal movement for right-to-left layout.
protected override void OnMouseMove(MouseEventArgs e)
The mouse button and pointer position.
Overrides:
Ends panning and, for a runtime right-click, opens the enabled image context menu when context menus are enabled.
protected override void OnMouseUp(MouseEventArgs e)
The mouse button and pointer position.
Overrides:
Uses Ctrl+wheel to zoom around the pointer, Shift+wheel to scroll horizontally, and wheel alone to scroll vertically.
protected override void OnMouseWheel(MouseEventArgs e)
The wheel delta and modifier state.
Overrides:
Raises PanChanged after the canvas position offset changes.
protected virtual void OnPanChanged()
Validates the panel display mode and updates the related mouse subscriptions and panel visibility.
protected virtual void OnPanelDisplayModeChanged()
PanelDisplayMode is not a defined PictureBoxPanelDisplayMode value.
Invalidates layout so the panels are repositioned for the selected overflow mode.
protected virtual void OnPanelOverflowModeChanged()
Refreshes the parent-control event subscriptions used to show or hide hover-mode panels.
protected override void OnParentChanged(RadElement previousParent)
The element that was the parent before the change.
Overrides:
Refreshes image state when the raster or SVG source changes and remeasures when border drawing changes.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
The changed property and its old and new values.
Overrides:
Maps the PictureBox layout mode to the image layout, recalculates the canvas size, and resets scrollbars. For FitIntoBounds, uses centered layout when the scaled image fits and zoom layout otherwise.
protected virtual void OnRadImageLayoutChanged()
Raises ZoomChanged after the zoom factor changes.
protected virtual void OnZoomChanged()
Consumes enabled touch-zoom gestures and increments or decrements the zoom factor by one touch step when the gesture factor is above or below one.
protected override void OnZoomGesture(ZoomGestureEventArgs args)
The touch-zoom factor and handled state.
Overrides:
Pastes an image from the clipboard.
public virtual void PasteImage()
Applies a mouse-wheel delta to the specified scrollbar using the system wheel-line setting and clamps its value.
protected virtual void ProcessMouseWheelScroll(MouseEventArgs e, RadScrollBarElement scrollBar)
The mouse-wheel delta.
scrollBarRadScrollBarElementThe scrollbar to update.
Clears the image pan offset and restores the zoom settings to their default factor.
protected virtual void ResetPanAndZoom()
Opens a SaveFileDialog which allows the user to save the displayed image.
public virtual void SaveImage()
Restores local defaults and disables fill and border drawing for this element.
public override void SetAllLocalValuesAsDefault(bool recursive)
Whether to restore local defaults recursively on child elements.
Overrides:
Gets a value indicating, whether a child will be arranged during the ArrangeOverride.
protected override bool ShouldArrangeChild(RadElement child)
The child.
Returns:Whether the child will be arranged in ArrangeOverride.
Overrides:
Shows the panels.
public virtual void ShowPanels(bool animate = true)
A value indicating whether to use animation.
Removes the parent control's mouse-event subscriptions used for hover-mode panel visibility.
protected virtual void UnwireParentControl()
Shows, hides, or toggles the four edge panels according to PanelDisplayMode and pointer position.
protected virtual void UpdatePanels(bool animate = true)
Whether hover-triggered panel transitions may animate; animation still depends on AllowPanelAnimations.
Reconnects parent-control mouse handlers when panels use hover display mode.
protected virtual void UpdateParentControl()
Recalculates the canvas size and pan offset for the current image layout and zoom, then updates the scrollbars.
protected virtual void UpdatePictureElementPanZoomAndSize()
Subscribes to the parent control's mouse events so panel visibility can follow pointer movement.
protected virtual void WireParentControl()
Performs a zoom-in operation with one step, according to the ZoomProperties.ZoomStep value.
public void ZoomIn()
Performs a zoom-in operation with several steps, according to the ZoomProperties.ZoomStep value.
Performs a zoom-out operation with one step, according to the ZoomProperties.ZoomStep value.
public void ZoomOut()
Performs a zoom-out operation with several steps, according to the ZoomProperties.ZoomStep value.
Events
Occurs when the context menu is closed.
public event EventHandler ContextMenuClosed
Occurs when the context menu is closing.
public event CancelEventHandler ContextMenuClosing
Occurs when an item in the context menu is clicked.
public event HandledEventHandler ContextMenuItemClick
Occurs when the context menu is opened.
public event EventHandler ContextMenuOpened
Occurs when the context menu is opening.
public event CancelEventHandler ContextMenuOpening
Occurs when the image has been edited by the ImageEditorDialog and the user has accepted the changes. Can be handled. Note that this event fill be fired always when the user clicks the OK button of the dialog, even if there are no changes in the image.
public event PictureBoxImageEditedEventHandler ImageEdited
Occurs when the image is about to be edited in the ImageEditorDialog. Cancellable.
public event PictureBoxImageEditorOpeningEventHandler ImageEditorOpening
Occurs when a raster or vector(SVG) image has been loaded by the user.
public event EventHandler ImageLoaded
Occurs when the displayed image has been saved by the user.
public event EventHandler ImageSaved
Occurs when the PositionOffset property of PictureBoxCanvasElement is changed.
public event EventHandler PanChanged
Raised after the ZoomFactor is changed.
public event EventHandler ZoomChanged