Class 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.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
UIItemBase
LightVisualElement
RadPictureBoxElement
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadPictureBoxElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProvider

Constructors

RadPictureBoxElement()

Initializes a new instance of the RadPictureBoxElement class.

Declaration
public RadPictureBoxElement()

Properties

AllowPanelAnimations

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.

Declaration
public bool AllowPanelAnimations { get; set; }
Property Value
System.Boolean

BottomPanel

Gets the bottom panel element. This panel allows adding buttons label and other elements in three collections - left, center and right items.

Declaration
public PictureBoxHorizontalPanelElement BottomPanel { get; }
Property Value
PictureBoxHorizontalPanelElement

CanvasElement

Gets the element that is responsible for painting the image.

Declaration
public PictureBoxCanvasElement CanvasElement { get; }
Property Value
PictureBoxCanvasElement

ContextMenu

Gets the context menu.

Declaration
public RadContextMenuDropDown ContextMenu { get; }
Property Value
RadContextMenuDropDown

ContextMenuEnabled

Gets or sets a value indicating whether to display context menu on right mouse click.

Declaration
public bool ContextMenuEnabled { get; set; }
Property Value
System.Boolean

ContextMenuProperties

Gets the context menu related properties.

Declaration
public PictureBoxContextMenuProperties ContextMenuProperties { get; }
Property Value
PictureBoxContextMenuProperties

DefaultImage

Gets or sets the raster image which is displayed when the Image and SvgImage properties are not specified.

Declaration
public Image DefaultImage { get; set; }
Property Value
System.Drawing.Image

DefaultSvgImage

Gets or sets the vector image which is displayed when the Image and SvgImage properties are not specified.

Declaration
public RadSvgImage DefaultSvgImage { get; set; }
Property Value
RadSvgImage

DefaultSvgImageXml

Gets or sets string XML of the the vector image which is displayed when the Image and SvgImage properties are not specified.

Declaration
public string DefaultSvgImageXml { get; set; }
Property Value
System.String

DefaultText

Gets or sets the text which is displayed when the Image and SvgImage properties are not specified.

Declaration
public string DefaultText { get; set; }
Property Value
System.String

HorizontalScrollBar

Gets the horizontal scrollbar element.

Declaration
public RadScrollBarElement HorizontalScrollBar { get; }
Property Value
RadScrollBarElement

ImageAlignment

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.

Declaration
public override ContentAlignment ImageAlignment { get; set; }
Property Value
System.Drawing.ContentAlignment

Overrides

ImageEditorDialog

Gets or sets the dialog responsible for image editing.

Declaration
public PictureBoxImageEditorDialog ImageEditorDialog { get; set; }
Property Value
PictureBoxImageEditorDialog

LeftPanel

Gets the left panel element. This panel allows adding buttons label and other elements in three collections - top, center and bottom items.

Declaration
public PictureBoxVerticalPanelElement LeftPanel { get; }
Property Value
PictureBoxVerticalPanelElement

NoPictureImageElement

Gets the element that holds the image visible when there is no image(raster or vector) assigned.

Declaration
public LightVisualElement NoPictureImageElement { get; }
Property Value
LightVisualElement

NoPictureStack

Gets the StackLayoutPanel that is displayed when there is no image(raster or vector) assigned.

Declaration
public StackLayoutPanel NoPictureStack { get; }
Property Value
StackLayoutPanel

NoPictureTextElement

Gets the element that holds the text visible when there is no image(raster or vector) assigned.

Declaration
public LightVisualElement NoPictureTextElement { get; }
Property Value
LightVisualElement

PanelDisplayMode

Gets or sets a value indicating how the panels are displayed. The possible options are: always or on mouse hover.

Declaration
public PictureBoxPanelDisplayMode PanelDisplayMode { get; set; }
Property Value
PictureBoxPanelDisplayMode

PanelOverflowMode

Gets or sets a value indicating how the panels are positioned.

Declaration
public PictureBoxPanelOverflowMode PanelOverflowMode { get; set; }
Property Value
PictureBoxPanelOverflowMode

RadImageLayout

Specifies how the image is positioned on the element.

Declaration
public virtual RadImageLayout RadImageLayout { get; set; }
Property Value
RadImageLayout

ReadOnly

Determines if users can only view the image with no interaction: zoom and context menu are not available when read only is true.

Declaration
public bool ReadOnly { get; set; }
Property Value
System.Boolean

RightPanel

Gets the right panel element. This panel allows adding buttons label and other elements in three collections - top, center and bottom items.

Declaration
public PictureBoxVerticalPanelElement RightPanel { get; }
Property Value
PictureBoxVerticalPanelElement

ShowScrollBars

Gets or sets a value indicating whether to display scrollbars when the displayed image is larger than the element.

Declaration
public bool ShowScrollBars { get; set; }
Property Value
System.Boolean

TopPanel

Gets the top panel element. This panel allows adding buttons label and other elements in three collections - left, center and right items.

Declaration
public PictureBoxHorizontalPanelElement TopPanel { get; }
Property Value
PictureBoxHorizontalPanelElement

VerticalScrollBar

Gets the vertical scrollbar element.

Declaration
public RadScrollBarElement VerticalScrollBar { get; }
Property Value
RadScrollBarElement

ZoomProperties

Gets the properties responsible for the zoom operations.

Declaration
public PictureBoxZoomProperties ZoomProperties { get; }
Property Value
PictureBoxZoomProperties

Methods

ArrangeOverride(SizeF)

Arranges the RadPictureBoxElement to its final location. The element must call the Arrange method of each of its children.

Declaration
protected override SizeF ArrangeOverride(SizeF finalSize)
Parameters
System.Drawing.SizeF finalSize

The size that is available for element.
Returns
System.Drawing.SizeF

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
Remarks

In this method call to the Arrange method of each child must be made.

CalculateZoomOffset(Double, SizeF)

Declaration
protected virtual SizeF CalculateZoomOffset(double newZoomFactor, SizeF newCanvasSize)
Parameters
System.Double newZoomFactor

System.Drawing.SizeF newCanvasSize

Returns
System.Drawing.SizeF

CanStartPan()

Declaration
protected virtual bool CanStartPan()
Returns
System.Boolean

ClearImage()

Removes the image and/or svg image.

Declaration
public virtual void ClearImage()

CopyImage()

Copies the displayed image into the clipboard.

Declaration
public virtual void CopyImage()

CreateBottomPanel()

Declaration
protected virtual PictureBoxHorizontalPanelElement CreateBottomPanel()
Returns
PictureBoxHorizontalPanelElement

CreateCanvasElement()

Declaration
protected virtual PictureBoxCanvasElement CreateCanvasElement()
Returns
PictureBoxCanvasElement

CreateChildElements()

Called by the element when constructed. Allows inheritors to build the element tree.

Declaration
protected override void CreateChildElements()
Overrides

CreateContextMenu()

Declaration
protected virtual RadContextMenuDropDown CreateContextMenu()
Returns
RadContextMenuDropDown

CreateContextMenuProperties()

Declaration
protected virtual PictureBoxContextMenuProperties CreateContextMenuProperties()
Returns
PictureBoxContextMenuProperties

CreateHorizontalScrollBarElement()

Declaration
protected virtual RadScrollBarElement CreateHorizontalScrollBarElement()
Returns
RadScrollBarElement

CreateLeftPanel()

Declaration
protected virtual PictureBoxVerticalPanelElement CreateLeftPanel()
Returns
PictureBoxVerticalPanelElement

CreateNoPictureImageElement()

Declaration
protected virtual LightVisualElement CreateNoPictureImageElement()
Returns
LightVisualElement

CreateNoPictureStack()

Declaration
protected virtual StackLayoutPanel CreateNoPictureStack()
Returns
StackLayoutPanel

CreateNoPictureTextElement()

Declaration
protected virtual LightVisualElement CreateNoPictureTextElement()
Returns
LightVisualElement

CreateRightPanel()

Declaration
protected virtual PictureBoxVerticalPanelElement CreateRightPanel()
Returns
PictureBoxVerticalPanelElement

CreateTopPanel()

Declaration
protected virtual PictureBoxHorizontalPanelElement CreateTopPanel()
Returns
PictureBoxHorizontalPanelElement

CreateVerticalScrollBarElement()

Declaration
protected virtual RadScrollBarElement CreateVerticalScrollBarElement()
Returns
RadScrollBarElement

CreateZoomProperties()

Declaration
protected virtual PictureBoxZoomProperties CreateZoomProperties()
Returns
PictureBoxZoomProperties

CutImage()

Copies the displayed image into the clipboard and clears the displayed image.

Declaration
public virtual void CutImage()

DisposeManagedResources()

Declaration
protected override void DisposeManagedResources()
Overrides

EditImage()

Edits the image using a RadImageEditor displayed in a PictureBoxImageEditorDialog.

Declaration
public void EditImage()

EnableContextMenuItems()

Declaration
protected virtual void EnableContextMenuItems()

HidePanels(Boolean)

Hides the panels.

Declaration
public virtual void HidePanels(bool animate = true)
Parameters
System.Boolean animate

A value indicating whether to use animation.

InitializeFields()

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.

Declaration
protected override void InitializeFields()
Overrides

LoadImage()

Opens an OpenFileDialog which allows the user to choose an image.

Declaration
public virtual void LoadImage()

MeasureOverride(SizeF)

Declaration
protected override SizeF MeasureOverride(SizeF availableSize)
Parameters
System.Drawing.SizeF availableSize

Returns
System.Drawing.SizeF

Overrides

OnBoundsChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnContextMenuClosed()

Raises the ContextMenuClosed event.

Declaration
protected virtual void OnContextMenuClosed()

OnContextMenuClosing(CancelEventArgs)

Raises the ContextMenuClosing event.

Declaration
protected virtual void OnContextMenuClosing(CancelEventArgs args)
Parameters
System.ComponentModel.CancelEventArgs args

The event arguments

OnContextMenuItemClick(Object, EventArgs)

Declaration
protected virtual void OnContextMenuItemClick(object sender, EventArgs e)
Parameters
System.Object sender

System.EventArgs e

OnContextMenuOpened()

Raises the ContextMenuOpened event.

Declaration
protected virtual void OnContextMenuOpened()

OnContextMenuOpening(CancelEventArgs)

Raises the ContextMenuOpening event.

Declaration
protected virtual void OnContextMenuOpening(CancelEventArgs args)
Parameters
System.ComponentModel.CancelEventArgs args

The event arguments

OnImageLoaded()

Declaration
protected virtual void OnImageLoaded()

OnImageSaved()

Declaration
protected virtual void OnImageSaved()

OnMouseDown(MouseEventArgs)

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnMouseMove(MouseEventArgs)

Declaration
protected override void OnMouseMove(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnMouseUp(MouseEventArgs)

Declaration
protected override void OnMouseUp(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnMouseWheel(MouseEventArgs)

Declaration
protected override void OnMouseWheel(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Overrides

OnPanChanged()

Declaration
protected virtual void OnPanChanged()

OnPanelDisplayModeChanged()

Declaration
protected virtual void OnPanelDisplayModeChanged()

OnPanelOverflowModeChanged()

Declaration
protected virtual void OnPanelOverflowModeChanged()

OnParentChanged(RadElement)

Declaration
protected override void OnParentChanged(RadElement previousParent)
Parameters
RadElement previousParent

Overrides

OnPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnRadImageLayoutChanged()

Declaration
protected virtual void OnRadImageLayoutChanged()

OnZoomChanged()

Declaration
protected virtual void OnZoomChanged()

OnZoomGesture(ZoomGestureEventArgs)

Declaration
protected override void OnZoomGesture(ZoomGestureEventArgs args)
Parameters
ZoomGestureEventArgs args

Overrides

PasteImage()

Pastes an image from the clipboard.

Declaration
public virtual void PasteImage()

ProcessMouseWheelScroll(MouseEventArgs, RadScrollBarElement)

Declaration
protected virtual void ProcessMouseWheelScroll(MouseEventArgs e, RadScrollBarElement scrollBar)
Parameters
System.Windows.Forms.MouseEventArgs e

RadScrollBarElement scrollBar

ResetPanAndZoom()

Declaration
protected virtual void ResetPanAndZoom()

SaveImage()

Opens a SaveFileDialog which allows the user to save the displayed image.

Declaration
public virtual void SaveImage()

SetAllLocalValuesAsDefault(Boolean)

Declaration
public override void SetAllLocalValuesAsDefault(bool recursive)
Parameters
System.Boolean recursive

Overrides

ShouldArrangeChild(RadElement)

Gets a value indicating, whether a child will be arranged during the ArrangeOverride.

Declaration
protected override bool ShouldArrangeChild(RadElement child)
Parameters
RadElement child

The child.
Returns
System.Boolean

Whether the child will be arranged in ArrangeOverride.
Overrides

ShowPanels(Boolean)

Shows the panels.

Declaration
public virtual void ShowPanels(bool animate = true)
Parameters
System.Boolean animate

A value indicating whether to use animation.

UnwireParentControl()

Declaration
protected virtual void UnwireParentControl()

UpdatePanels(Boolean)

Declaration
protected virtual void UpdatePanels(bool animate = true)
Parameters
System.Boolean animate

UpdateParentControl()

Declaration
protected virtual void UpdateParentControl()

UpdatePictureElementPanZoomAndSize()

Declaration
protected virtual void UpdatePictureElementPanZoomAndSize()

WireParentControl()

Declaration
protected virtual void WireParentControl()

Zoom(Int32, Nullable<Point>)

Performs a zoom operation by given steps count.

Declaration
public void Zoom(int step, Point? pivotPoint = default(Point? ))
Parameters
System.Int32 step

Number of steps to zoom. Positive value will zoom-in, while a negative value will zoom-out.
System.Nullable<System.Drawing.Point> pivotPoint

The point against which the zoom operation will be executed.

ZoomIn()

Performs a zoom-in operation with one step, according to the ZoomProperties.ZoomStep value.

Declaration
public void ZoomIn()

ZoomIn(Int32)

Performs a zoom-in operation with several steps, according to the ZoomProperties.ZoomStep value.

Declaration
public void ZoomIn(int steps)
Parameters
System.Int32 steps

The count of steps to zoom in.

ZoomOut()

Performs a zoom-out operation with one step, according to the ZoomProperties.ZoomStep value.

Declaration
public void ZoomOut()

ZoomOut(Int32)

Performs a zoom-out operation with several steps, according to the ZoomProperties.ZoomStep value.

Declaration
public void ZoomOut(int steps)
Parameters
System.Int32 steps

The count of steps to zoom-out.

Events

ContextMenuClosed

Occurs when the context menu is closed.

Declaration
public event EventHandler ContextMenuClosed
Event Type
System.EventHandler

ContextMenuClosing

Occurs when the context menu is closing.

Declaration
public event CancelEventHandler ContextMenuClosing
Event Type
System.ComponentModel.CancelEventHandler

ContextMenuItemClick

Occurs when an item in the context menu is clicked.

Declaration
public event HandledEventHandler ContextMenuItemClick
Event Type
System.ComponentModel.HandledEventHandler

ContextMenuOpened

Occurs when the context menu is opened.

Declaration
public event EventHandler ContextMenuOpened
Event Type
System.EventHandler

ContextMenuOpening

Occurs when the context menu is opening.

Declaration
public event CancelEventHandler ContextMenuOpening
Event Type
System.ComponentModel.CancelEventHandler

ImageEdited

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.

Declaration
public event PictureBoxImageEditedEventHandler ImageEdited
Event Type
PictureBoxImageEditedEventHandler

ImageEditorOpening

Occurs when the image is about to be edited in the ImageEditorDialog. Cancellable.

Declaration
public event PictureBoxImageEditorOpeningEventHandler ImageEditorOpening
Event Type
PictureBoxImageEditorOpeningEventHandler

ImageLoaded

Occurs when a raster or vector(SVG) image has been loaded by the user.

Declaration
public event EventHandler ImageLoaded
Event Type
System.EventHandler

ImageSaved

Occurs when the displayed image has been saved by the user.

Declaration
public event EventHandler ImageSaved
Event Type
System.EventHandler

PanChanged

Occurs when the PositionOffset property of PictureBoxCanvasElement is changed.

Declaration
public event EventHandler PanChanged
Event Type
System.EventHandler

ZoomChanged

Raised after the ZoomFactor is changed.

Declaration
public event EventHandler ZoomChanged
Event Type
System.EventHandler

Extension Methods