WinExplorer View

  • 9 minutes to read

The WinExplorer View (WinExplorerView) can emulate seven view styles supported by Microsoft Windows Explorer — Small, Medium, Large, Extra Large, List, Tiles, and Content.

In v21.2 and newer, 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.

Default Data Presentation

Run Demo: File Manager

Run Demo: WinExplorer View (DB)

Run Demo: Context Buttons

The following image gallery shows the default data presentations of the WinExplorerView’s visual styles:

Select View Style

The OptionsView.Style property allows you to apply one of the supported view styles:

winexplorerview-select-viewstyle

View styles have fixed UIs that cannot be changed, unless you use HTML-CSS templates.

Specify Fields That Contain Item Data

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:

WinExplorer View - Item Elements

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:

Data Grid - WinExp View - Columns

Images

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

ColumnSet.SmallImageColumn

Small

16x16

Medium, Content, Tiles

ColumnSet.MediumImageColumn

Medium

48x48

Large

ColumnSet.LargeImageColumn

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.

Stub Glyphs

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.

WinExplorer View - Stub Glyphs

Related API

Customize Common Display Settings

The WinExplorerView.OptionsView object allows you to modify settings shared by all view styles:

winexplorerview-optionsview

Customize Additional Settings

Each view style has its own display settings. You can access them as follows:

winexplorerview - options

Group and Disable Items

Two additional properties of the WinExplorerView.ColumnSet object allow you to group data and display specific records as disabled.

  • Set the ColumnSet.GroupColumn property to group all records by a specific column.
  • Set the WinExplorerViewColumns.EnabledColumn property to a Boolean column whose values specify the ‘enable’ state of records. If a record’s ‘enable’ state is false, the WinExplorerView paints the corresponding item as disabled. Users cannot interact with disabled items.

Data Grid - WinExp View - Columns 2

Online Videos

  • Item Customization

    Online Video | Walkthrough

    Shows how to customize records in specific view styles.

  • Context Buttons

    Online Video | Walkthrough

    Shows how to add clickable buttons to your data records. It is recommended that you add context buttons only to items displayed in the ExtraLarge style.

HTML-CSS Templates

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.

Note

Support for HTML and CSS-based UI design in controls is under active development and is available as a Community Technology Preview (CTP). We appreciate your feedback on how you build desktop UIs with HTML and CSS.

Run Demo: HTML MainDemo – WinExplorer View

WinExplorerView - HTML-CSS templates

Specify HTML-CSS Templates

Use the following HtmlTemplate properties to specify HTML-CSS templates for the view styles supported by the WinExplorerView:

WinExplorerView - HtmlTemplate property

Each HtmlTemplate object exposes two nested properties:

  • HtmlTemplate.Template — Specifies HTML code that defines an item’s content (UI elements).
  • HtmlTemplate.Styles — Specifies CSS styles applied to the UI elements.

At design time, click the ellipsis button (…) for any HtmlTemplate property to open the Html Template Editor, and specify HTML and CSS code.

WinExplorerView - Html template editor

Main Features of HTML and CSS Templates

Data binding
The ${FieldName} syntax in HTML markup inserts values of fields from the control’s data source. See Data Binding.
Images
The <img> HTML tag allows you to add images.
Buttons
The HTML-CSS markup allows you to add elements to emulate buttons.
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.

Specify Different Templates for Different Items

Handle the WinExplorerView.QueryItemTemplate event to assign custom templates to individual items. This event fires repeatedly for each item.

Customize Items Dynamically

When a specific item is about to be displayed onscreen, the WinExplorerView raises the WinExplorerView.CustomizeItem event. You can handle this event to dynamically customize the style and visibility of the item’s HTML elements.

Asynchronous Image Load

Activating the Asynchronous Image Load mode allows you to do the following:

  • force the view to load images dynamically, on-demand, rather than all images at once;
  • retrieve images from the data source and manually transform them;
  • assign your own images from an external source;
  • display images with animation effects and show animated indicators for those images that are not yet ready.

WinExplorerView - Loading Indicator

Context Buttons

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.

WinExplorer View - Button Panels

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:

  • ContextButton - a regular push button that performs actions when clicked. With no glyph assigned, such buttons serve as labels;
  • CheckContextButton - check buttons that toggle their checked/unchecked states when clicked;
  • RatingContextButton - items that allow end-users to rate this item based on a default five-star grade.

WinExplorerView - Context Buttons Designer

Related API

  • 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 bounds of 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-number 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. A code sample for this task can be found later in this section.

WinExplorer View - Hovered State

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;
}
See Also