windowsforms-114759-controls-and-libraries-data-grid-views-winexplorer-view.md
The WinExplorer View (WinExplorerView) can emulate seven view styles supported by Microsoft Windows Explorer — Small, Medium, Large, Extra Large, List, Tiles, and Content.
You can use HTML-CSS templates to override the default data presentation of items in these styles. HTML-CSS templates allow you to create custom layouts of data fields, and display any number of data fields in WinExplorerView items.
Run Demo: WinExplorer View (DB)
The following image gallery shows the default data presentations of the WinExplorerView’s visual styles:
WinExplorerView - Tiles Style
Records display medium images with text captions, descriptions, and optional check boxes painted at the image’s top-left corner. Check boxes are visible only when checked or hovered.
WinExplorerView - Small Style
Records display small images with text captions to the right and optional check boxes to the left. Records are arranged horizontally. Groups are placed one under another.
WinExplorerView - Medium Style
Records display medium images with text captions below and optional check boxes to the left.
WinExplorerView - Large Style
Records display large images with text captions below and optional check boxes to the left.
WinExplorerView - ExtraLarge Style
Records display extra-large images with text captions below and optional check boxes to the left.
WinExplorerView - Content Style
Records display medium images, bold text captions, and descriptions in a row. Records are arranged one under another and separated by horizontal lines. You can optionally display a check box to the left of the image.
WinExplorerView - List Style
Records display small images with text captions to the right and optional check boxes to the left. Records are arranged vertically while groups are placed horizontally, side-by-side. Groups display no collapse buttons.
The OptionsView.Style property allows you to apply one of the supported view styles:
View styles have fixed UIs that cannot be changed, unless you use HTML-CSS templates.
Each view style renders its items using a unique layout of data fields. The default item presentation in these styles is limited to a maximum of four data fields. These fields specify an item’s Text, Image, Description, and Check Box value. The following figure illustrates the field layout in the Tiles visual style:
Note
Only the Tiles and Content view styles can display item descriptions.
Use the WinExplorerView.ColumnSet property to specify fields (columns) that contain data for WinExplorerView items. The following image shows the columns used by the Tiles view style:
The WinExplorerView.ColumnSet property allows you to specify image columns that store images for your view styles.
|
View styles
|
Image Columns
|
Image Type and Default Size
| | --- | --- | --- | |
Small, List
|
|
Small
16x16
| |
Medium, Content, Tiles
|
|
Medium
48x48
| |
Large
|
|
Large
96x96
| |
ExtraLarge
|
ColumnSet.ExtraLargeImageColumn
|
Extra Large
256x256
|
You do not need to assign image columns to all four …ImageColumn properties. If you do not specify images for a specific view style, the WinExplorerView automatically retrieves images from other view styles, and scales these images to the required size.
Use the ImageSize property to change the default image size for a specific view style.
You can also specify images by indexes in corresponding image collections. See the following topics for more information: SmallImageIndexColumn, MediumImageIndexColumn, LargeImageIndexColumn, and ExtraLargeImageIndexColumn.
Instead of regular images, the WinExplorer View can display auto-generated images called stub glyphs. A stub glyph is a colored square or circle with one or two initial letters of the item’s text.
Related API
StubGlyphOptions.AllowStubGlyphs — Specifies whether stub glyphs are enabled.
WinExplorerView.OptionsStubGlyphs — Provides access to advanced stub glyph options, such as font settings, color scheme, glyph shapes, etc. Refer to the “Customize Stub Glyphs” section of the following topic for details: Stub Glyphs.
The WinExplorerView.OptionsView object allows you to modify settings shared by all view styles:
Each view style has its own display settings. You can access them as follows:
|
|
|
Two additional properties of the WinExplorerView.ColumnSet object allow you to group data and display specific records as disabled.
Item Customization
Context Buttons
HTML-CSS templates allow you to override the default data presentation in all seven view styles — Small, Medium, Large, Extra Large, List, Tiles, and Content. You can create your own layout of data fields, and display an unlimited number of data fields in each item.
Use HTML markup to specify content for WinExplorerView items, and use CSS code to customize the appearance settings, size, padding, and layout options of UI elements.
Run Demo: HTML MainDemo – WinExplorer View
Use the following HtmlTemplate properties to specify HTML-CSS templates for the view styles supported by the WinExplorerView:
|
|
|
Each HtmlTemplate object exposes two nested properties:
At design time, click the ellipsis button (…) for any HtmlTemplate property to open the Html Template Editor , and specify HTML and CSS code.
Data bindingThe ${FieldName} syntax in HTML markup inserts values of fields from the control’s data source. See Data Binding.ImagesThe `` HTML tag allows you to add images.ButtonsThe HTML-CSS markup allows you to add elements to emulate buttons.Inplace EditorsThe <input> tag allows you to embed in-place editors (Repository Items) into WinExplorer View items to display and edit data source fields.
<input name="repositoryItemButtonEdit1" value="${Price}" class="editor"/>
In-place editors are activated at runtime when a user clicks them if the View’s OptionsBehavior.Editable option is set to true.
At design time, you can use the “In-place Editor Repository” page in the Data Grid’s Designer to create and customize in-place editors:
See the following topic for more information: HTML Tags - Input.
Mouse actions
The WinExplorerView contains events to respond to mouse actions on HTML elements: HtmlElementMouseClick, HtmlElementMouseDown, HtmlElementMouseMove, HtmlElementMouseOut, HtmlElementMouseOver, and HtmlElementMouseUp.
You can also subscribe to mouse events for elements in HTML markup, and when using Fluent API.
See the following topic for more information: HTML-CSS-based Desktop UI.
Handle the WinExplorerView.QueryItemTemplate event to assign custom templates to individual items. This event fires repeatedly for each item.
When a specific item is about to be displayed onscreen, the WinExplorerView raises the WinExplorerView.CustomizeItem event. You can handle this event to customize the style and visibility of the item’s HTML elements dynamically.
Activating the Asynchronous Image Load mode allows you to do the following:
The WinExplorer records can display context buttons along their top and bottom sides. You can choose whether these buttons are constantly visible, or only when a user hovers over an item.
To add context buttons, click the ellipsis button next to the WinExplorerView.ContextButtons property. The combo-box editor of the Collection Editor dialog allows you to add items of three types:
ContextItem.AlignmentOptions — Allow you to choose whether a button should be displayed above the item, below it, or in the middle.
WinExplorerViewStyleOptions.ContextButtonsUseFullItemArea — Context buttons are drawn within the bounds of an item image. If your items have no images, or you want to draw buttons inside bounds of an entire item, set this property to true. You can also increase WinExplorerViewStyleOptions.ContentMargins to increase the distance between item images and top (bottom) context buttons.
TopPanelColor , BottomPanelColor — These properties, accessed through the WinExplorerView.ContextButtonOptions group, specify colors for top and bottom panels that host context buttons. Use 4-digit ARGB values to assign semi-transparent colors.
ContextItem.Visibility — Specifies whether this button is always visible or only when the parent record is hovered (default behavior). If a button is constantly visible, its underlying button panel is shown as well. With this feature, you can clear the WinExplorerViewColumns.TextColumn property to replace default record titles with context buttons. The following image demonstrates a WinExplorer View record with a caption inside the record itself. You can find a code sample for this task later in this section.
WinExplorerView.ContextButtonClick — Occurs when end users click context buttons.
WinExplorerView.ContextButtonCustomize — Handle this event to modify context buttons for individual records.
The code below illustrates how to turn a regular context button into a label that shows a model name and a trademark for car records.
using DevExpress.XtraGrid.Views.WinExplorer;
// ...
private void winExplorerView1_ContextButtonCustomize(object sender, Views.WinExplorer.WinExplorerViewContextButtonCustomizeEventArgs e) {
WinExplorerView view = sender as WinExplorerView;
if(view == null) return;
if(e.Item.Name == "itemText") {
((ContextButton)e.Item).Caption = GetContextButtonCaption(e.RowHandle, view.Columns["model.Name"], view.Columns["trademark.Name"]);
}
}
string GetContextButtonCaption(int rowHandle, GridColumn model, GridColumn trademark) {
string caption = string.Empty;
if(model != null)
caption = (string)this.winExplorerView1.GetRowCellValue(rowHandle, model);
if(caption != null && trademark != null && caption.Length < 20)
caption = string.Format("{0} {1}", this.winExplorerView1.GetRowCellValue(rowHandle, trademark), caption);
return caption;
}
Imports DevExpress.XtraGrid.Views.WinExplorer
' ...
Private Sub winExplorerView1_ContextButtonCustomize(ByVal sender As Object, ByVal e As Views.WinExplorer.WinExplorerViewContextButtonCustomizeEventArgs)
Dim view As WinExplorerView = sender
If view Is Nothing Then
Return
End If
If e.Item.Name = "itemText" Then
CType(e.Item, ContextButton).Caption = GetContextButtonCaption(e.RowHandle, view.Columns("model.Name"), view.Columns("trademark.Name"))
End If
End Sub
Private Function GetContextButtonCaption(ByVal rowHandle As Integer, ByVal model As GridColumn, ByVal trademark As GridColumn) As String
Dim caption As String = String.Empty
If model IsNot Nothing Then
caption = CStr(Me.winExplorerView1.GetRowCellValue(rowHandle, model))
End If
If caption IsNot Nothing AndAlso trademark IsNot Nothing AndAlso caption.Length < 20 Then
caption = String.Format("{0} {1}", Me.winExplorerView1.GetRowCellValue(rowHandle, trademark), caption)
End If
Return caption
End Function
using System;
using System.Data;
using DevExpress.Data;
using DevExpress.Utils;
using DevExpress.XtraEditors;
using DevExpress.XtraGrid.Views.Base;
using DevExpress.XtraGrid.Views.WinExplorer;
namespace dxSample {
public partial class Form1 : XtraForm {
DataTable masterTable;
public DataTable CreateDataTable() {
masterTable = new DataTable();
masterTable.Columns.Add("Id", typeof(int));
masterTable.Columns.Add("Name");
masterTable.Columns.Add("Favorites", typeof(bool));
masterTable.Columns.Add("OrderCount", typeof(int));
masterTable.Columns.Add("RegistrationDate", typeof(DateTime));
masterTable.Columns.Add("SvgImageIndex", typeof(int));
for (int i = 0; i < 6; i++) {
masterTable.Rows.Add(i, "Items group " + i, i % 2 == 0, i * 10, DateTime.Now.AddDays(i), i);
}
return masterTable;
}
public Form1() {
InitializeComponent();
winExplorerView.OptionsView.Style = WinExplorerViewStyle.Large;
winExplorerView.OptionsViewStyles.Large.ItemWidth = 360;
winExplorerView.CustomUnboundColumnData += WinExplorerView_CustomUnboundColumnData;
var column = winExplorerView.Columns.AddVisible("NameOrFavorite");
column.UnboundType = UnboundColumnType.String;
winExplorerView.ColumnSet.GroupColumn = column;
winExplorerView.ContextButtonCustomize += WinExplorerView_ContextButtonCustomize;
ContextButton btn = new ContextButton();
btn.Caption = "Add to Favorites";
btn.ImageOptionsCollection.ItemNormal.SvgImage = svgImageCollection2[0];
btn.Width = 250;
btn.AlignmentOptions.Panel = ContextItemPanel.Bottom;
winExplorerView.ContextButtonClick += (o, ee) => {
if (ee.DataItem == null)
return;
int rowHandle = (int)ee.DataItem;
bool isFavorite = (bool)winExplorerView.GetRowCellValue(rowHandle, "Favorites");
winExplorerView.SetRowCellValue(rowHandle, "Favorites", !isFavorite);
winExplorerView.RefreshData();
};
winExplorerView.ContextButtons.Add(btn);
gridControl1.DataSource = CreateDataTable();
}
private void WinExplorerView_ContextButtonCustomize(object sender, WinExplorerViewContextButtonCustomizeEventArgs e) {
WinExplorerView view = sender as WinExplorerView;
if (!view.IsValidRowHandle(e.RowHandle) || view.IsGroupRow(e.RowHandle))
return;
bool isFavorite = (bool)winExplorerView.GetRowCellValue(e.RowHandle, "Favorites");
if (isFavorite)
(e.Item as ContextButton).Caption = "Remove from Favorites";
}
private void WinExplorerView_CustomUnboundColumnData(object sender, CustomColumnDataEventArgs e) {
WinExplorerView view = sender as WinExplorerView;
bool favorite = (bool)view.GetListSourceRowCellValue(e.ListSourceRowIndex, "Favorites");
if (e.IsGetData) {
e.Value = favorite ? "Favorites" : view.GetListSourceRowCellValue(e.ListSourceRowIndex, "Name");
}
}
}
}
Imports System
Imports System.Data
Imports DevExpress.Data
Imports DevExpress.Utils
Imports DevExpress.XtraEditors
Imports DevExpress.XtraGrid.Views.Base
Imports DevExpress.XtraGrid.Views.WinExplorer
Namespace dxSample
Partial Public Class Form1
Inherits XtraForm
Private masterTable As DataTable
Public Function CreateDataTable() As DataTable
masterTable = New DataTable()
masterTable.Columns.Add("Id", GetType(Integer))
masterTable.Columns.Add("Name")
masterTable.Columns.Add("Favorites", GetType(Boolean))
masterTable.Columns.Add("OrderCount", GetType(Integer))
masterTable.Columns.Add("RegistrationDate", GetType(Date))
masterTable.Columns.Add("SvgImageIndex", GetType(Integer))
For i As Integer = 0 To 5
masterTable.Rows.Add(i, "Items group " & i, i Mod 2 = 0, i * 10, Date.Now.AddDays(i), i)
Next i
Return masterTable
End Function
Public Sub New()
InitializeComponent()
winExplorerView.OptionsView.Style = WinExplorerViewStyle.Large
winExplorerView.OptionsViewStyles.Large.ItemWidth = 360
AddHandler winExplorerView.CustomUnboundColumnData, AddressOf WinExplorerView_CustomUnboundColumnData
Dim column = winExplorerView.Columns.AddVisible("NameOrFavorite")
column.UnboundType = UnboundColumnType.String
winExplorerView.ColumnSet.GroupColumn = column
AddHandler winExplorerView.ContextButtonCustomize, AddressOf WinExplorerView_ContextButtonCustomize
Dim btn As New ContextButton()
btn.Caption = "Add to Favorites"
btn.ImageOptionsCollection.ItemNormal.SvgImage = svgImageCollection2(0)
btn.Width = 250
btn.AlignmentOptions.Panel = ContextItemPanel.Bottom
AddHandler winExplorerView.ContextButtonClick, Sub(o, ee)
If ee.DataItem Is Nothing Then
Return
End If
Dim rowHandle As Integer = CInt(Math.Truncate(ee.DataItem))
Dim isFavorite As Boolean = CBool(winExplorerView.GetRowCellValue(rowHandle, "Favorites"))
winExplorerView.SetRowCellValue(rowHandle, "Favorites", (Not isFavorite))
winExplorerView.RefreshData()
End Sub
winExplorerView.ContextButtons.Add(btn)
gridControl1.DataSource = CreateDataTable()
End Sub
Private Sub WinExplorerView_ContextButtonCustomize(ByVal sender As Object, ByVal e As WinExplorerViewContextButtonCustomizeEventArgs)
Dim view As WinExplorerView = TryCast(sender, WinExplorerView)
If (Not view.IsValidRowHandle(e.RowHandle)) OrElse view.IsGroupRow(e.RowHandle) Then
Return
End If
Dim isFavorite As Boolean = CBool(winExplorerView.GetRowCellValue(e.RowHandle, "Favorites"))
If isFavorite Then
TryCast(e.Item, ContextButton).Caption = "Remove from Favorites"
End If
End Sub
Private Sub WinExplorerView_CustomUnboundColumnData(ByVal sender As Object, ByVal e As CustomColumnDataEventArgs)
Dim view As WinExplorerView = TryCast(sender, WinExplorerView)
Dim favorite As Boolean = CBool(view.GetListSourceRowCellValue(e.ListSourceRowIndex, "Favorites"))
If e.IsGetData Then
e.Value = If(favorite, "Favorites", view.GetListSourceRowCellValue(e.ListSourceRowIndex, "Name"))
End If
End Sub
End Class
End Namespace
See Also