Class ExplorerControl

Control used for the navigation part of the RadOpenFileDialog, RadSaveFileDialog and RadOpenFolderDialog

Inheritance
System.Object
ExplorerControl
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class ExplorerControl : UserControl, IViewModelChangedListener, IThemeChangeListener

Constructors

ExplorerControl()

Initializes a new instance of the ExplorerControl class.

Declaration
public ExplorerControl()

Properties

ControlThemeClassName

Gets the theme class name used for styling the control.

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

Implements

CurrentDirectoryPath

Gets or sets the path of the current directory in this ExplorerControl instance. Setting this property navigates to the specified directory.

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

CustomPlacesPaths

Gets or sets the paths to the custom places displayed in the navigation tree view. These provide quick access to frequently used directories.

Declaration
public IEnumerable<string> CustomPlacesPaths { get; set; }
Property Value
System.Collections.Generic.IEnumerable<System.String>

CustomPlacesTreeNode

Gets the custom places tree node that contains shortcuts to frequently used locations.

Declaration
public RadTreeNode CustomPlacesTreeNode { get; }
Property Value
RadTreeNode

EditingOptions

Gets or sets how the files and folders in the ExplorerControl can be edited. This controls operations like renaming, creating new folders, etc. Note that shell context menu and drag and drop operations are handled separately.

Declaration
public EditingOptions EditingOptions { get; set; }
Property Value
EditingOptions

ExpandToCurrentDirectory

Gets or sets a value indicating whether the main navigation pane automatically expands and brings into view the current directory. When true, the tree view will expand to show the current location.

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

FileBrowserListView

Gets the file browser list view component that displays files and folders in the current directory.

Declaration
public FileBrowserListView FileBrowserListView { get; }
Property Value
FileBrowserListView

Filter

Gets or sets the filter string that describes the list of file extensions to filter by. This property has effect only when IsFolderBrowser is false.

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

FilterDescriptors

Gets the list of FileFilterDescriptor objects specified by the Filter property. This property has effect only when IsFolderBrowser is false.

Declaration
public IList<FileFilterDescriptor> FilterDescriptors { get; }
Property Value
System.Collections.Generic.IList<FileFilterDescriptor>

FilterIndex

Gets or sets the current filter index from the list of filter strings specified by the Filter property. This property has effect only when IsFolderBrowser is false.

Declaration
public int FilterIndex { get; set; }
Property Value
System.Int32

IsDragDropEnabled

Gets or sets a value indicating whether this ExplorerControl allows drag and drop operations. When enabled, users can drag files and folders between the tree view and list view.

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

IsFolderBrowser

Gets or sets a value indicating whether this ExplorerControl instance is used for directory selection only or for both directories and files. When true, only directories can be selected.

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

LayoutType

Gets or sets the current layout type of the main file browser pane, controlling how files and folders are displayed.

Declaration
public LayoutType LayoutType { get; set; }
Property Value
LayoutType

MainNavigationTreeView

Gets the main navigation tree view component that displays the directory structure.

Declaration
public FileBrowserTreeView MainNavigationTreeView { get; }
Property Value
FileBrowserTreeView

MainNavigationTreeViewProportionalWidth

Gets or sets the proportional size of MainNavigationTreeView according to the total width of the ExplorerControl. This property is only considered when SizeMode is set to Proportional. The value should be between 0 and 1, with the default being 0.25.

Declaration
public float MainNavigationTreeViewProportionalWidth { get; set; }
Property Value
System.Single

MinFileBrowserListViewWidth

Gets or sets the minimum width for FileBrowserListView when the ExplorerControl is resized or the separator is dragged. The value is automatically scaled for DPI.

Declaration
public int MinFileBrowserListViewWidth { get; set; }
Property Value
System.Int32

MinNavigationTreeViewWidth

Gets or sets the minimum width for MainNavigationTreeView when the ExplorerControl is resized or the separator is dragged. The value is automatically scaled for DPI.

Declaration
public int MinNavigationTreeViewWidth { get; set; }
Property Value
System.Int32

MultiSelect

Gets or sets a value indicating whether multiple selection of files or folders is allowed. When enabled, users can select multiple items using Ctrl+Click or Shift+Click.

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

PathNavigationBreadCrumb

Gets the breadcrumb navigation component that shows the current path.

Declaration
public FileDialogsBreadcrumb PathNavigationBreadCrumb { get; }
Property Value
FileDialogsBreadcrumb

SearchTextBox

Gets the search text box component used for file and folder searching.

Declaration
public FileDialogSearchPane SearchTextBox { get; }
Property Value
FileDialogSearchPane

SelectedFileName

Gets the full path of the currently selected file or directory. Returns an empty string if no item is selected.

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

SelectedFileNames

Gets the list of full paths of the currently selected files and/or folders. In single selection mode, this list contains at most one item.

Declaration
public IList<string> SelectedFileNames { get; }
Property Value
System.Collections.Generic.IList<System.String>

SelectedSafeFileNames

Gets the list of names (without full path) of the currently selected files and/or folders. In single selection mode, this list contains at most one item.

Declaration
public IList<string> SelectedSafeFileNames { get; }
Property Value
System.Collections.Generic.IList<System.String>

ShowHiddenFiles

Gets or sets a value indicating whether hidden files and folders should be visible in the explorer. When true, files and folders with the hidden attribute will be displayed.

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

ShowNetworkLocations

Gets or sets a value indicating whether the dialog shows network computers in the navigation tree. When true, network locations will be accessible through the tree view.

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

ShowSystemCustomPlaces

Gets or sets a value indicating whether the Quick Access/Favorites items from the Windows File Explorer will be shown as child nodes in the CustomPlacesTreeNode. When enabled, system custom places like Quick Access, Desktop, Downloads, etc. will be displayed.

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

SizeMode

Gets or sets a value indicating how the MainNavigationTreeView width will be changed when the ExplorerControl is resized.

Declaration
public ExplorerControlSizeMode SizeMode { get; set; }
Property Value
ExplorerControlSizeMode

ThemeName

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

ViewModel

This property is not relevant for this class.

Declaration
public DialogViewModel ViewModel { get; }
Property Value
DialogViewModel

ViewModelChangedListeners

This property is not relevant for this class.

Declaration
public IList<IViewModelChangedListener> ViewModelChangedListeners { get; set; }
Property Value
System.Collections.Generic.IList<IViewModelChangedListener>

Methods

AddCustomPlacesNode(String, Image, IList<String>)

Adds a new custom places node to the MainNavigationTreeView. This node can be used to add organized shortcuts such as Favorites, Libraries, etc.

Declaration
public CustomPlacesFileBrowserTreeNode AddCustomPlacesNode(string nodeName, Image nodeImage, IList<string> paths)
Parameters
System.String nodeName

The display name of the custom places node.
System.Drawing.Image nodeImage

The image to display for the custom places node.
System.Collections.Generic.IList<System.String> paths

The list of directory paths that will be displayed as children of the newly created node.
Returns
CustomPlacesFileBrowserTreeNode

The created CustomPlacesFileBrowserTreeNode, or null if the parameters are invalid.

AddSystemCustomPlaces()

Adds system custom places from Windows File Explorer (Quick Access, Favorites) to the custom places node. This method uses COM interop to access Windows Shell functionality.

Declaration
protected virtual void AddSystemCustomPlaces()

CreateCustomPlacesNode()

Creates a custom places tree node with default settings.

Declaration
protected virtual CustomPlacesFileBrowserTreeNode CreateCustomPlacesNode()
Returns
CustomPlacesFileBrowserTreeNode

A new instance of CustomPlacesFileBrowserTreeNode.

CreateTreeNode(DirectoryBaseWrapper)

Creates a new tree node for the specified directory wrapper.

Declaration
public FileBrowserTreeNode CreateTreeNode(DirectoryBaseWrapper dir)
Parameters
DirectoryBaseWrapper dir

The directory wrapper to create a tree node for.
Returns
FileBrowserTreeNode

A new FileBrowserTreeNode configured for the specified directory.

Dispose(Boolean)

Clean up any resources being used.

Declaration
protected override void Dispose(bool disposing)
Parameters
System.Boolean disposing

true if managed resources should be disposed; otherwise, false.

GetControlsHeightForCurrentTheme(String, out Boolean)

Gets the appropriate control height for the specified theme and determines if button fill and border should be hidden. Different themes require different control heights to maintain visual consistency.

Declaration
protected virtual int GetControlsHeightForCurrentTheme(string themeName, out bool hideButtonsFillAndBorder)
Parameters
System.String themeName

The name of the theme to get control heights for.
System.Boolean hideButtonsFillAndBorder

When this method returns, contains a value indicating whether button fill and border should be hidden for the specified theme.
Returns
System.Int32

The control height in pixels appropriate for the specified theme.

GetDirectoryInfoWrappersFromPaths(IEnumerable<String>)

Gets a list of DirectoryInfoWrapper objects from the specified file paths.

Declaration
public List<DirectoryInfoWrapper> GetDirectoryInfoWrappersFromPaths(IEnumerable<string> paths)
Parameters
System.Collections.Generic.IEnumerable<System.String> paths

The collection of directory paths to convert.
Returns
System.Collections.Generic.List<DirectoryInfoWrapper>

A list of directory info wrappers for the specified paths.

GetLayoutTypeToIconConverter()

Declaration
protected virtual LayoutTypeToIconConverter GetLayoutTypeToIconConverter()
Returns
LayoutTypeToIconConverter

NotifyViewModelListeners(DialogViewModel)

Notifies all registered view model listeners of a view model change.

Declaration
protected void NotifyViewModelListeners(DialogViewModel viewModel)
Parameters
DialogViewModel viewModel

The new view model to set.

OnCurrentDirectoryPathChanged()

Called when the current directory path property changes and navigates to the new directory.

Declaration
protected virtual void OnCurrentDirectoryPathChanged()

OnFileDirectoryChanged(Action)

Handles file or directory change notifications when used in standalone mode.

Declaration
public void OnFileDirectoryChanged(Action action)
Parameters
System.Action action

The action to execute, typically on the UI thread.

OnFilterChanged()

Called when the filter property changes and processes the filtering accordingly.

Declaration
protected virtual void OnFilterChanged()

OnFilterIndexChanged()

Called when the filter index property changes and processes the filtering accordingly.

Declaration
protected virtual void OnFilterIndexChanged()

OnIsDragDropEnabledPropertyChanged()

Called when the drag and drop enabled property changes and updates the child controls accordingly.

Declaration
protected virtual void OnIsDragDropEnabledPropertyChanged()

OnLayoutChanged()

Called when the layout property changes and updates the view model accordingly.

Declaration
protected virtual void OnLayoutChanged()

OnLoad(EventArgs)

Called when the control is loaded and initializes the view model if necessary.

Declaration
protected override void OnLoad(EventArgs e)
Parameters
System.EventArgs e

The event arguments.

OnMouseMove(MouseEventArgs)

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

OnMouseUp(MouseEventArgs)

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

OnMultiSelectChanged()

Called when the multi-select property changes and updates the view model accordingly.

Declaration
protected virtual void OnMultiSelectChanged()

OnShowHiddenFilesChanged()

Called when the show hidden files property changes and updates the view model accordingly.

Declaration
protected virtual void OnShowHiddenFilesChanged()

OnSizeChanged(EventArgs)

Declaration
protected override void OnSizeChanged(EventArgs e)
Parameters
System.EventArgs e

OnThemeChanged(ThemeChangedEventArgs)

Handles theme changes for this control and applies the new theme to the control tree. This method is called when the theme of the control or application changes.

Declaration
public void OnThemeChanged(ThemeChangedEventArgs e)
Parameters
ThemeChangedEventArgs e

The theme changed event arguments containing the new theme name.
Implements

OnViewModelChanged(DialogViewModel)

Called when the view model changes and updates all related components.

Declaration
protected virtual void OnViewModelChanged(DialogViewModel viewModel)
Parameters
DialogViewModel viewModel

The new view model.

SetupControlsForTheme()

Sets up controls for the current application theme by determining the theme name and applying appropriate styling. This method uses the application theme name or falls back to the control's theme name.

Declaration
protected virtual void SetupControlsForTheme()

SetupControlsForTheme(String)

Sets up controls for the specified theme by configuring control heights and visual properties based on the theme requirements. Different themes may require different control dimensions and styling.

Declaration
protected virtual void SetupControlsForTheme(string themeName)
Parameters
System.String themeName

The name of the theme to apply to the controls.

SetupViewModelListeners()

Sets up the list of view model change listeners for the control's child components.

Declaration
protected void SetupViewModelListeners()

SetViewModel(DialogViewModel)

Sets the view model for this control and all its child components.

Declaration
public void SetViewModel(DialogViewModel viewModel)
Parameters
DialogViewModel viewModel

The view model to set.
Implements

WireEvents()

Wires up event handlers for the control's child components.

Declaration
protected virtual void WireEvents()

Events

DirectoryNavigating

Occurs when the current folder is about to change.

Declaration
public event EventHandler<DirectoryNavigatingEventArgs> DirectoryNavigating
Event Type
System.EventHandler<DirectoryNavigatingEventArgs>

DirectoryRequesting

Occurs when the DirectoryInfo wrapper is about to be created.

Declaration
public event EventHandler<DirectoryRequestingEventArgs> DirectoryRequesting
Event Type
System.EventHandler<DirectoryRequestingEventArgs>

ExceptionRaised

Occurs when Exception during File (or Directory) creation / observation / modification is raised.

Declaration
public event EventHandler<FileBrowserExceptionRaisedEventArgs> ExceptionRaised
Event Type
System.EventHandler<FileBrowserExceptionRaisedEventArgs>

ShellContextMenuOpening

Occurs when context menu is about to open.

Declaration
public event EventHandler<ContextMenuOpeningEventArgs> ShellContextMenuOpening
Event Type
System.EventHandler<ContextMenuOpeningEventArgs>

Extension Methods