Represents the main element of a tabbed form control that provides comprehensive tabbed interface functionality with integrated caption management, drag-and-drop support, and content area handling for creating modern tabbed applications.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
[ComVisible(false)]
public class RadTabbedFormControlElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProvider
Inheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemUIItemBaseLightVisualElementRadTabbedFormControlElement...
Implements:
Inherited Members
Constructors
public RadTabbedFormControlElement()
Fields
Identifies the IsTabbedFormActive dependency property that indicates whether the tabbed form is currently active and focused.
public static RadProperty IsTabbedFormActiveProperty
Identifies the ItemDragHint dependency property that defines the visual hint displayed during drag operations.
public static RadProperty ItemDragHintProperty
Identifies the ItemDragMode dependency property that controls how tab items respond to drag operations.
public static RadProperty ItemDragModeProperty
Identifies the TabbedFormWindowState dependency property that tracks the current window state of the tabbed form.
public static RadProperty TabbedFormWindowStateProperty
Properties
Gets the BorderPrimitive instance that represents the border of the tabbed control's caption.
[Browsable(false)]
public BorderPrimitive CaptionBorder { get; }
Gets the FillPrimitive instance that represents the fill of the tabbed control's caption.
[Browsable(false)]
public FillPrimitive CaptionFill { get; }
Gets or sets the height of the extended title bar area that contains tabs and caption elements.
[Browsable(true)]
public int CaptionHeight { get; set; }
Gets the text primitive element that displays the caption text in the tabbed form control's title area.
public TextPrimitive CaptionTextElement { get; }
Gets or sets a value indicating whether the close button is visible in the caption area of the tabbed form control.
public bool CloseButton { get; set; }
Gets the content area element that hosts and manages the display of tab content panels.
[Browsable(false)]
public RadTabbedFormControlContentAreaElement ContentArea { get; }
Gets the image primitive element that displays the form icon in the caption area of the tabbed form control.
public ImagePrimitive IconPrimitive { get; }
Gets or sets the RadImageShape instance which describes the hint that indicates where an item will be dropped after a drag operation.
[Browsable(false)]
[VsbBrowsable(true)]
public RadImageShape ItemDragHint { get; set; }
Gets or sets the drag mode for tab items, controlling when and how tab drag operations are initiated by user interaction.
public virtual TabItemDragMode ItemDragMode { get; set; }
Gets or sets the RadTabbedFormDragDropService instance which handles item drag requests.
[Browsable(false)]
public RadTabbedFormDragDropService ItemDragService { get; set; }
Gets all the items currently present within this element.
[Browsable(false)]
public IReadOnlyCollection<RadTabbedFormControlItem> Items { get; }
Gets the collection of items hosted in the left quick access toolbar container.
[Browsable(false)]
public RadItemOwnerCollection LeftItems { get; }
Gets the quick access toolbar container that hosts items on the left side of the caption area.
[Browsable(false)]
public RadQuickAccessToolBar LeftItemsContainer { get; }
Gets or sets a value indicating whether the maximize button is visible in the caption area of the tabbed form control.
public bool MaximizeButton { get; set; }
Gets or sets a value indicating whether the minimize button is visible in the caption area of the tabbed form control.
public bool MinimizeButton { get; set; }
Gets or sets the minimum width that tabs can be resized to, ensuring tabs remain readable and functional at smaller sizes.
public virtual int MinimumTabWidth { get; set; }
Gets the item which stands for adding new tabs on click.
[Browsable(false)]
public LightVisualButtonElement NewItem { get; }
Gets or sets the owner RadTabbedFormControl instance.
public RadTabbedFormControl Owner { get; }
Gets all the pinned items in the tab collection.
[Browsable(false)]
public ObservableCollection<RadTabbedFormControlItem> PinnedItems { get; }
Gets or sets the position where pinned tabs will be displayed relative to regular tabs in the tab strip area.
public virtual PinnedItemsPosition PinnedItemsPosition { get; set; }
Gets the collection of items hosted in the right quick access toolbar container.
[Browsable(false)]
public RadItemOwnerCollection RightItems { get; }
Gets the quick access toolbar container that hosts items on the right side of the caption area.
[Browsable(false)]
public RadQuickAccessToolBar RightItemsContainer { get; }
Gets or sets the currently selected item in the view.
[Browsable(false)]
public RadTabbedFormControlItem SelectedItem { get; set; }
Gets or sets a value indicating whether the form icon is displayed in the caption bar area of the tabbed form control.
public virtual bool ShowIcon { get; set; }
Gets or sets a value indicating whether the new tab button is visible, providing users with the ability to create new tabs through the UI.
public virtual bool ShowNewTabButton { get; set; }
Gets or sets a value indicating whether close buttons are displayed on individual tabs, allowing users to close tabs directly.
public virtual bool ShowTabCloseButton { get; set; }
Gets or sets a value indicating whether pin buttons are displayed on individual tabs, allowing users to pin tabs for persistent visibility.
public bool ShowTabPinButton { get; set; }
Gets or sets a value indicating whether the text element displaying the form title is visible in the caption area.
public virtual bool ShowText { get; set; }
Gets or sets the caption element that manages the display of tabs, system buttons, and title text in the tabbed form control.
public RadTabbedFormControlCaption TabbedFormCaption { get; set; }
Gets or sets the default height for tabs in the tabbed form control, affecting the overall appearance of the tab strip.
public virtual int TabHeight { get; set; }
Gets or sets the spacing between individual tabs in the tab strip, controlling the visual separation between tabs.
public virtual int TabSpacing { get; set; }
Methods
Adds an item to the internal collection and configures it as part of the tabbed form control.
protected virtual void AddItemCore(RadTabbedFormControlItem item)
The item to add to the collection.
Brings the parent tabbed form to the front if it is not currently active.
protected virtual void BringFormToFront()
Scrolls the RadTabbedFormControlTabsElement so that the passed item is visible and centered.
protected virtual void BringIntoView(RadTabbedFormControlItem item)
The item to bring into view.
Determines whether a drop operation can occur in the title bar area.
protected virtual bool CanDropInTitleBarArea(Point client, RadTabbedFormControlElement dropTarget)
The client coordinates of the drop position.
dropTargetRadTabbedFormControlElementThe element that would receive the drop.
Returns:True if drop is allowed in the title bar area; otherwise, false.
Determines whether a drag item can be dropped over the specified hit item at the given position.
protected virtual bool CanDropOverItem(RadTabbedFormControlItem dragItem, RadTabbedFormControlItem hitItem, Point mousePosition)
The item being dragged.
hitItemRadTabbedFormControlItemThe item that would receive the drop.
mousePositionPointThe current mouse position.
Returns:True if the drop operation is allowed; otherwise, false.
Determines whether an immediate drop operation can be performed based on drag direction and position.
protected virtual bool CanPerformImmediateDrop(DragDirection direction, int x, RadTabbedFormControlItem dragItem, RadTabbedFormControlItem hitItem)
The direction of the drag operation.
xintThe x-coordinate of the drop position.
dragItemRadTabbedFormControlItemThe item being dragged.
hitItemRadTabbedFormControlItemThe item that would receive the drop.
Returns:True if immediate drop can be performed; otherwise, false.
Determines whether an item can be selected by keyboard navigation.
protected virtual bool CanSelectItem(RadTabbedFormControlItem item)
The item to check.
Returns:true when the item is visible and enabled.
Closes the parent tabbed form.
protected virtual void CloseForm()
Removes the tab associated with the item from the owning control's tab collection.
protected virtual void CloseItem(RadTabbedFormControlItem item)
The item whose tab should be closed.
Creates and configures the border primitive element that provides the border visualization for the caption area.
protected virtual BorderPrimitive CreateBorderElement()
A configured BorderPrimitive for the caption border.
Creates and configures a button group element for hosting quick access toolbar items in the caption area.
protected virtual RadQuickAccessToolBar CreateButtonGroup()
A configured RadQuickAccessToolBar for hosting toolbar items.
Creates and configures all child elements of the tabbed form control including icon, caption, toolbars, and content area.
protected override void CreateChildElements()
Overrides:
Creates and configures the content area element that hosts the tab content panels.
protected virtual RadTabbedFormControlContentAreaElement CreateContentAreaElement()
RadTabbedFormControlContentAreaElement
A new instance of RadTabbedFormControlContentAreaElement for hosting tab contents.
Creates the standard menu for adding, pinning, and closing tabs.
protected virtual RadDropDownMenu CreateDefaultContextMenu()
The newly created default tab context menu.
Creates and configures the fill primitive element that provides the background fill for the caption area.
protected virtual FillPrimitive CreateFillElement()
A configured FillPrimitive for the caption background.
Creates and configures the icon primitive element for displaying the form icon in the caption area.
protected virtual ImagePrimitive CreateIconElement()
A configured ImagePrimitive for the form icon.
Creates a new tab item element that represents an individual tab in the tabbed form control.
protected virtual RadTabbedFormControlItem CreateItem()
A new instance of RadTabbedFormControlItem representing a tab.
Creates and configures the main caption element that manages tabs, system buttons, and title text display.
protected virtual RadTabbedFormControlCaption CreateTabbedFormCaption()
A configured RadTabbedFormControlCaption for the main caption area.
Creates and configures the text primitive element for displaying the caption text in the tabbed form control.
protected virtual TextPrimitive CreateTextElement()
A configured TextPrimitive for the caption text.
Releases managed resources used by the tabbed form control element including drag service, event handlers, and child controls.
protected override void DisposeManagedResources()
Overrides:
Invalidates measurement and arrangement and immediately refreshes layout after a DPI scale change.
public override void DpiScaleChanged(SizeF scaleFactor)
The new horizontal and vertical DPI scale factors.
Overrides:
Ends the drag operation for the specified tab item.
protected virtual void EndItemDrag(RadTabbedFormControlItem item)
The item that finished dragging.
Calculates the content rectangle below the caption, offset by the content border and reduced by border and margin totals.
public virtual Rectangle GetClientRectangleFromContentElement(RadTabbedFormControlContentAreaElement contentArea)
The content-area element whose border and margins are applied.
Returns:The resulting content rectangle in the tabbed-form control's coordinates.
Gets the rectangle used to arrange tab content below the caption, adjusted for the content border and margin sizes.
public virtual Rectangle GetContentAreaRectangle()
The content area's client rectangle.
Creates and returns a new empty tab instance for new tab requests.
protected virtual RadTabbedFormControlTab GetEmptyTab()
A new instance of RadTabbedFormControlTab.
Gets the item at the specified index in the collection.
public RadTabbedFormControlItem GetItemAt(int index)
The zero-based index of the item to retrieve.
Returns:The RadTabbedFormControlItem at the specified index.
Finds the next visible, enabled item in the requested direction, optionally wrapping at the collection boundary.
protected virtual int GetNextItemIndex(RadTabbedFormControlItem current, bool forward, bool wrap)
The item from which to begin the search.
forwardbooltrue to search toward later items; otherwise, toward earlier items.
wrapbooltrue to continue from the opposite end when the search reaches a boundary.
Returns:The zero-based index of the next candidate. At a non-wrapping boundary or when there is at most one item, the result is out of range; with wrapping enabled, the current item's index is returned if no other visible, enabled item is available.
Handles the request for creating a new tab and raises the appropriate events.
protected virtual void HandleNewTabRequested()
Initializes the fields and sets up default configurations for the tabbed form control element including drag-drop service and collections.
protected override void InitializeFields()
Overrides:
Initializes and returns a new RadTabbedForm instance for drag-drop operations.
Inserts an item at the specified index in the internal collection and configures it as part of the tabbed form control.
protected virtual void InsertItemCore(int index, RadTabbedFormControlItem item)
The zero-based index at which to insert the item.
itemRadTabbedFormControlItemThe item to insert into the collection.
Gets the item that contains the provided point in control's client coordinates.
public RadTabbedFormControlItem ItemFromPoint(Point client)
The point in client coordinates to check for item containment.
Returns:The RadTabbedFormControlItem at the specified point, or null if no item is found.
Measures the caption, quick-access items, and content area; returns an empty size when the owner form is minimized.
Insets the content rectangle by the content area's padding before assigning it to a tab.
Recalculates the selected tab's bounds when the content area changes outside an active arrange pass.
protected virtual void OnContentBoundsChanged()
Raises ContextMenuOpening before the tab context menu is displayed.
protected virtual void OnContextMenuOpening(RadTabbedFormControlItemConextMenuOpeningEventArgs args)
The tab, menu, and cancellation flag.
Handles the addition of a new control during drag-drop operations.
protected virtual void OnControlAdded(object sender, ControlEventArgs e)
The object that raised the event.
eControlEventArgsThe event arguments containing the added control information.
Handles the double click event and delegates to the caption element for maximize/restore functionality.
protected override void OnDoubleClick(EventArgs e)
The event arguments.
Overrides:
Raises ItemClicked for a tab-item click.
protected virtual void OnItemClick(RadTabbedFormControlItem sender, EventArgs e)
The item that was clicked.
eEventArgsThe event data.
Raises ItemCreating and returns any replacement item supplied by a handler.
protected virtual RadTabbedFormControlItem OnItemCreating(RadTabbedFormControlItemCreatingEventArgs args)
The tab being attached and the optional item supplied by an event handler.
Returns:The item supplied by a handler, or null to keep the default item.
Starts a tab drag when dragging is enabled and the control is not in design mode.
protected virtual void OnItemDrag(RadTabbedFormControlItem sender, MouseEventArgs e)
The item being dragged.
eMouseEventArgsThe mouse event data.
Raises ItemDropped after processing a tab drop.
protected virtual void OnItemDropped(object sender, RadTabbedFormControlItemDroppedEventArgs args)
The source of the drop notification.
argsRadTabbedFormControlItemDroppedEventArgsThe dragged item and optional target item.
Raises ItemDropping before processing a tab drop; handlers can cancel the operation.
protected virtual void OnItemDropping(object sender, RadTabbedFormControlItemDroppingEventArgs args)
The source of the drop request.
argsRadTabbedFormControlItemDroppingEventArgsThe dragged item, optional target item, and cancellation flag.
Selects the clicked item on a single left-button press.
protected virtual void OnItemMouseDown(RadTabbedFormControlItem sender, MouseEventArgs e)
The item receiving the mouse input.
eMouseEventArgsThe mouse event data.
Closes the item on a middle-button release or opens its context menu on a single right-button release.
protected virtual void OnItemMouseUp(RadTabbedFormControlItem sender, MouseEventArgs e)
The item receiving the mouse input.
eMouseEventArgsThe mouse event data.
Raises ItemsChanged after an item is inserted, removed, or repositioned.
protected virtual void OnItemsChanged(object sender, RadTabbedFormControlItemsChangedEventArgs args)
The source of the collection change.
argsRadTabbedFormControlItemsChangedEventArgsThe changed item and operation.
Raises ItemSelected after the selected item has changed.
public virtual void OnItemSelected(object sender, RadTabbedFormControlItemSelectedEventArgs args)
The source of the selection change.
argsRadTabbedFormControlItemSelectedEventArgsThe previous and newly selected items.
Raises ItemSelecting before changing the selected-item state. Setting Cancel prevents that state change, although tab-content visibility may already have been updated.
public virtual void OnItemSelecting(object sender, RadTabbedFormControlItemSelectingEventArgs args)
The source of the selection request.
argsRadTabbedFormControlItemSelectingEventArgsThe current and requested items and the cancellation flag.
Called when the element is loaded and handles initialization of tab visibility and event registration for tab management functionality.
protected override void OnLoaded()
Overrides:
Handles the mouse down event and delegates to the caption element for form dragging functionality.
protected override void OnMouseDown(MouseEventArgs e)
The mouse event arguments.
Overrides:
Handles the mouse move event and delegates to the caption element for form dragging functionality.
protected override void OnMouseMove(MouseEventArgs e)
The mouse event arguments.
Overrides:
Handles property changes and performs necessary updates for specific properties.
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
The property change event arguments.
Overrides:
Handles changes to the selected tab in the owner control.
protected virtual void OnSelectedTabChanged(RadTabbedFormControlEventArgs e)
The event arguments containing the selected tab information.
Handles the creation of a new tabbed form control during drag operations.
protected virtual void OnTabbedFormControlCreating(object sender, TabbedFormControlCreatingEventArgs e)
The object that raised the event.
eTabbedFormControlCreatingEventArgsThe event arguments containing the new form control information.
Handles changes to tab index positions within the collection.
protected virtual void OnTabIndexChanged(RadTabbedFormControlIndexChangedEventArgs e)
The event arguments containing the old and new index information.
Performs custom painting of the element including special handling for composition-enabled forms.
protected override void PaintOverride(IGraphics screenRadGraphics, Rectangle clipRectangle, float angle, SizeF scale, bool useRelativeTransformation)
The graphics object used for painting.
clipRectangleRectangleThe clipping rectangle for the paint operation.
anglefloatThe rotation angle for the paint operation.
scaleSizeFThe scale factor for the paint operation.
useRelativeTransformationboolWhether to use relative transformation.
Overrides:
Performs the actual drop operation for moving or detaching tab items.
protected virtual void PerformItemDrop(RadTabbedFormControlItem dragItem, RadTabbedFormControlItem hitItem)
The item being dropped.
hitItemRadTabbedFormControlItemThe item that received the drop.
Processes the final drop operation when a drag object is dropped.
protected override void ProcessDragDrop(Point dropLocation, ISupportDrag dragObject)
The location where the drop occurred.
dragObjectISupportDragThe object that was dropped.
Overrides:
Processes drag over events and determines whether the drag operation can proceed.
protected override bool ProcessDragOver(Point mousePosition, ISupportDrag dragObject)
The current mouse position.
dragObjectISupportDragThe object being dragged.
Returns:True if the drag can proceed; otherwise, false.
Overrides:
Removes an item from the internal collection and handles selection updates.
protected virtual void RemoveItemCore(RadTabbedFormControlItem item)
The item to remove from the collection.
Selects the next available item.
Requests selection of the next item returned by GetNextItemIndex(RadTabbedFormControlItem, bool, bool).
protected virtual bool SelectNextItemCore(RadTabbedFormControlItem current, bool forward, bool wrap)
The item from which navigation starts.
forwardbooltrue to search toward later items; otherwise, toward earlier items.
wrapbooltrue to continue from the opposite end when the search reaches a boundary.
Returns:true when the resulting index is within the item collection.
Selects the previous available item.
Hides the previously selected tab, updates the target tab's bounds, and shows the target tab. If the owner has no handle yet, records the visibility changes for handle creation.
protected virtual void SetSelectedContent(RadTabbedFormControlItem item)
The item whose tab should become visible, or null to hide the current tab.
Sets the specified item as the selected item in the tabbed form control.
protected virtual void SetSelectedItem(RadTabbedFormControlItem item)
The item to select.
Uses ShouldLayoutChild(RadElement) to exclude children that are arranged explicitly by this element.
protected override bool ShouldArrangeChild(RadElement child)
The child element to check.
Returns:The result of ShouldLayoutChild(RadElement) for the child.
Overrides:
Excludes elements laid out explicitly by this control from the base layout pass.
protected virtual bool ShouldLayoutChild(RadElement child)
The child element to check.
Returns:false for the icon, caption text, quick-access toolbars, tab caption, and content area.
Uses ShouldLayoutChild(RadElement) to exclude children that are measured explicitly by this element.
protected override bool ShouldMeasureChild(RadElement child)
The child element to check.
Returns:The result of ShouldLayoutChild(RadElement) for the child.
Overrides:
Builds the tab context menu, raises ContextMenuOpening, and displays the resulting non-empty menu.
protected virtual void ShowContextMenu(RadTabbedFormControlItem tabItem)
The tab whose context menu is being opened.
Starts the drag operation for the specified tab item.
protected virtual void StartItemDrag(RadTabbedFormControlItem item)
The item to start dragging.
Invalidates measurement so the element recalculates its layout after an item is synchronized.
protected virtual void SyncronizeItem(RadTabbedFormControlItem item)
The item whose synchronization may affect layout.
Updates button group configurations when items are added or removed from the toolbar collections.
protected virtual void UpdateButtonGroupsOnItemsChanged(RadItemCollection changed, RadItem target, ItemsChangeOperation operation)
The collection that changed.
targetRadItemThe item that was affected.
operationItemsChangeOperationThe type of change operation.
Updates the layout during an immediate drag operation to provide visual feedback.
protected virtual void UpdateLayoutWhileImmediateDrag(RadTabbedFormControlItem dragItem, DragDirection direction, int deltaX)
The item being dragged.
directionDragDirectionThe direction of the drag operation.
deltaXintThe horizontal displacement of the drag operation.
Adds or removes the item from the pinned-item collection to match its IsPinned state.
protected virtual void UpdatePinnedItems(RadTabbedFormControlItem item)
The item whose pinned state changed.
Updates element tree references and establishes event handlers for size and visibility changes.
protected override void UpdateReferences(ComponentThemableElementTree tree, bool updateInheritance, bool recursive)
The element tree to update references for.
updateInheritanceboolWhether to update property inheritance.
recursiveboolWhether to update references recursively.
Overrides:
Updates the tab control's bounds to match the available content rectangle when the element is loaded.
protected virtual void UpdateTabBounds(RadTabbedFormControlTab tab)
The tab whose content bounds should be synchronized.
Core method for handling visibility and size changes that updates the layout when necessary.
protected virtual void VisibleChangedCore()
Events
Occurs before the default context menu is opened.
public event EventHandler<RadTabbedFormControlItemConextMenuOpeningEventArgs> ContextMenuOpening
Occurs when a tab is clicked.
public event EventHandler ItemClicked
Occurs before the tab items is attached to its owner element.
public event EventHandler<RadTabbedFormControlItemCreatingEventArgs> ItemCreating
Occurs after a tab is dropped.
public event EventHandler<RadTabbedFormControlItemDroppedEventArgs> ItemDropped
Occurs before a tab is dropped.
public event EventHandler<RadTabbedFormControlItemDroppingEventArgs> ItemDropping
Occurs when a tab is added or removed.
public event EventHandler<RadTabbedFormControlItemsChangedEventArgs> ItemsChanged
Occurs after a tab is selected.
public event EventHandler<RadTabbedFormControlItemSelectedEventArgs> ItemSelected
Occurs before the tab is selected.
public event EventHandler<RadTabbedFormControlItemSelectingEventArgs> ItemSelecting