[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Expand]Controls and Libraries
 [Expand]Common Features
  Get More Help
 [Collapse]API Reference
  [Expand]DevExpress.DataAccess.UI
  [Expand]DevExpress.DataAccess.UI.Design
  [Expand]DevExpress.DataAccess.UI.EntityFramework
  [Expand]DevExpress.DataAccess.UI.Excel
  [Expand]DevExpress.DataAccess.UI.ObjectBinding
  [Expand]DevExpress.DataAccess.UI.Sql
  [Expand]DevExpress.DataAccess.UI.Wizard
  [Expand]DevExpress.DataAccess.UI.Wizard.Services
  [Expand]DevExpress.DataAccess.UI.Wizard.Views
  [Expand]DevExpress.DocumentView
  [Expand]DevExpress.DocumentView.Controls
  [Expand]DevExpress.LookAndFeel
  [Expand]DevExpress.LookAndFeel.Helpers
  [Expand]DevExpress.Skins
  [Expand]DevExpress.Snap
  [Expand]DevExpress.Snap.API.Native
  [Expand]DevExpress.Snap.Core
  [Expand]DevExpress.Snap.Core.API
  [Expand]DevExpress.Snap.Core.Fields
  [Expand]DevExpress.Snap.Core.Forms
  [Expand]DevExpress.Snap.Core.Options
  [Expand]DevExpress.Snap.Core.Services
  [Expand]DevExpress.Snap.Extensions
  [Expand]DevExpress.Snap.Extensions.Localization
  [Expand]DevExpress.Snap.Extensions.UI
  [Expand]DevExpress.Snap.Localization
  [Expand]DevExpress.Snap.Options
  [Expand]DevExpress.Snap.Services
  [Expand]DevExpress.Utils
  [Expand]DevExpress.Utils.Animation
  [Expand]DevExpress.Utils.Behaviors
  [Expand]DevExpress.Utils.Controls
  [Expand]DevExpress.Utils.DragDrop
  [Expand]DevExpress.Utils.Drawing
  [Expand]DevExpress.Utils.Filtering
  [Expand]DevExpress.Utils.Layout
  [Expand]DevExpress.Utils.Menu
  [Expand]DevExpress.Utils.MVVM
  [Expand]DevExpress.Utils.Taskbar
  [Expand]DevExpress.Utils.Taskbar.Core
  [Expand]DevExpress.Utils.UI.Localization
  [Expand]DevExpress.Utils.VisualEffects
  [Expand]DevExpress.Utils.Win
  [Expand]DevExpress.XtraBars
  [Expand]DevExpress.XtraBars.Alerter
  [Expand]DevExpress.XtraBars.Docking
  [Expand]DevExpress.XtraBars.Docking2010
  [Expand]DevExpress.XtraBars.Docking2010.Base
  [Expand]DevExpress.XtraBars.Docking2010.Customization
  [Expand]DevExpress.XtraBars.Docking2010.Views
  [Expand]DevExpress.XtraBars.Docking2010.Views.NativeMdi
  [Expand]DevExpress.XtraBars.Docking2010.Views.Tabbed
  [Expand]DevExpress.XtraBars.Docking2010.Views.Widget
  [Expand]DevExpress.XtraBars.Docking2010.Views.WindowsUI
  [Expand]DevExpress.XtraBars.FluentDesignSystem
  [Expand]DevExpress.XtraBars.Localization
  [Expand]DevExpress.XtraBars.Navigation
  [Expand]DevExpress.XtraBars.Ribbon
  [Expand]DevExpress.XtraBars.Ribbon.Gallery
  [Expand]DevExpress.XtraBars.Ribbon.ViewInfo
  [Expand]DevExpress.XtraBars.ToastNotifications
  [Expand]DevExpress.XtraBars.ToolbarForm
  [Expand]DevExpress.XtraBars.Utils
  [Expand]DevExpress.XtraBars.WinRTLiveTiles
  [Expand]DevExpress.XtraCharts
  [Expand]DevExpress.XtraCharts.Designer
  [Expand]DevExpress.XtraCharts.Wizard
  [Expand]DevExpress.XtraDataLayout
  [Expand]DevExpress.XtraDiagram
  [Expand]DevExpress.XtraDiagram.Docking
  [Expand]DevExpress.XtraDiagram.Options
  [Collapse]DevExpress.XtraEditors
   [Expand]AreaChartRangeControlClientView Class
   [Expand]AutoCloseOptions Class
   [Expand]BarCodeControl Class
   [Expand]BaseButton Class
   [Expand]BaseCheckEdit Class
   [Expand]BaseCheckedListBoxControl Class
   [Expand]BaseControl Class
   [Expand]BaseDateControl Class
   [Expand]BaseEdit Class
   [Expand]BaseImageListBoxControl Class
   [Expand]BaseListBoxControl Class
   [Expand]BaseSpinEdit Class
   [Expand]BaseStyleControl Class
   [Expand]BlobBaseEdit Class
   [Expand]BreadCrumbEdit Class
   [Expand]BreadCrumbHistory Class
   [Expand]BreadCrumbHistoryItem Class
    BreadCrumbMode Enumeration
   [Expand]BreadCrumbNode Class
   [Expand]BreadCrumbNodeCollection Class
   [Expand]ButtonEdit Class
   [Expand]CalcEdit Class
   [Expand]ChartRangeControlClientBase Class
   [Expand]ChartRangeControlClientDataProvider Class
   [Expand]ChartRangeControlClientGridOptions Class
   [Expand]ChartRangeControlClientRange Class
   [Expand]ChartRangeControlClientView Class
   [Expand]CheckButton Class
   [Expand]CheckedComboBoxEdit Class
   [Expand]CheckEdit Class
   [Expand]CheckedListBoxControl Class
   [Expand]ClientDataSourceProviderCustomizeSeriesEventArgs Class
   [Expand]ColorDialogOptions Class
   [Expand]ColorEdit Class
   [Expand]ColorPickEdit Class
   [Expand]ColorPickEditBase Class
   [Expand]ColorPickEditTooltipShowingEventArgs Class
    ColorTooltipFormat Enumeration
    ColumnFilterPopupMode Enumeration
   [Expand]ComboBox Class
   [Expand]ComboBoxEdit Class
   [Expand]ControlNavigator Class
   [Expand]ControlNavigatorButtonCollection Class
   [Expand]ControlNavigatorButtons Class
   [Expand]CustomizeTemplatedItemEventArgs Class
   [Expand]DataNavigator Class
   [Expand]DataNavigatorButtonCollection Class
   [Expand]DataNavigatorButtons Class
   [Expand]DateControl Class
   [Expand]DateEdit Class
   [Expand]DateTimeChartRangeControlClient Class
   [Expand]DateTimeChartRangeControlClientGridOptions Class
   [Expand]DateTimeChartRangeControlClientRange Class
    DateTimeFunctionsShowMode Enumeration
   [Expand]DateTimeRangeControlClient Class
    DropDownArrowStyle Enumeration
   [Expand]DropDownButton Class
    ExpressionEditorMode Enumeration
   [Expand]FilterControl Class
    FilterCriteriaDisplayStyle Enumeration
    FilterEditorViewMode Enumeration
    FindMode Enumeration
    FindPanelBehavior Enumeration
   [Expand]FontEdit Class
    FormatCondition Enumeration
    FormatConditionAboveBelowType Enumeration
    FormatConditionAutomaticType Enumeration
   [Expand]FormatConditionCollectionBase Class
    FormatConditionComparisonType Enumeration
    FormatConditionDataUpdateTrigger Enumeration
   [Expand]FormatConditionIconSet Class
   [Expand]FormatConditionIconSetIcon Class
   [Expand]FormatConditionRule2ColorScale Class
   [Expand]FormatConditionRule3ColorScale Class
   [Expand]FormatConditionRuleAboveBelowAverage Class
   [Expand]FormatConditionRuleAppearanceBase Class
   [Expand]FormatConditionRuleBase Class
    FormatConditionRuleChangeType Enumeration
   [Expand]FormatConditionRuleContains Class
   [Expand]FormatConditionRuleDataBar Class
   [Expand]FormatConditionRuleDataUpdate Class
   [Expand]FormatConditionRuleDateOccuring Class
   [Expand]FormatConditionRuleExpression Class
   [Expand]FormatConditionRuleIconSet Class
   [Expand]FormatConditionRuleMinMaxBase Class
   [Expand]FormatConditionRuleTopBottom Class
   [Expand]FormatConditionRuleUniqueDuplicate Class
   [Expand]FormatConditionRuleValue Class
    FormatConditionTopBottomType Enumeration
    FormatConditionUniqueDuplicateType Enumeration
    FormatConditionValueType Enumeration
   [Expand]FormatRuleBase Class
    FormBorderEffect Enumeration
   [Collapse]GridLookUpEdit Class
     GridLookUpEdit Members
     GridLookUpEdit Constructor
    [Expand]GridLookUpEdit Properties
    [Expand]GridLookUpEdit Events
    [Expand]GridLookUpEdit Methods
   [Expand]GridLookUpEditBase Class
   [Expand]GroupCaptionCustomDrawEventArgs Class
    GroupCaptionCustomDrawEventHandler Delegate
   [Expand]GroupControl Class
    HighlightStyle Enumeration
    HotTrackSelectMode Enumeration
   [Expand]HScrollBar Class
   [Expand]HScrollBarBase Class
   [Expand]HyperLinkEdit Class
   [Expand]HyperlinkLabelControl Class
   [Expand]HyperlinkLabelControlAppearanceObject Class
   [Expand]HyperlinkLabelControlAppearanceOptions Class
    ImageAlignToText Enumeration
   [Expand]ImageComboBoxEdit Class
   [Expand]ImageEdit Class
   [Expand]ImageListBoxControl Class
    ImageLocation Enumeration
    LabelAutoSizeMode Enumeration
   [Expand]LabelControl Class
   [Expand]LabelControlAppearanceObject Class
   [Expand]LineChartRangeControlClientView Class
   [Expand]ListBoxControl Class
   [Expand]ListBoxDrawItemEventArgs Class
    ListBoxDrawItemEventHandler Delegate
   [Expand]LookUpEdit Class
   [Expand]LookUpEditBase Class
   [Expand]MarqueeProgressBarControl Class
   [Expand]MemoEdit Class
   [Expand]MemoExEdit Class
   [Expand]MRUEdit Class
   [Expand]NavigatorBase Class
   [Expand]NavigatorButton Class
   [Expand]NavigatorButtonBase Class
   [Expand]NavigatorButtonClickEventArgs Class
    NavigatorButtonClickEventHandler Delegate
   [Expand]NavigatorButtonCollectionBase Class
   [Expand]NavigatorButtonsBase Class
    NavigatorButtonsTextLocation Enumeration
    NavigatorButtonType Enumeration
   [Expand]NavigatorCustomButton Class
   [Expand]NavigatorCustomButtons Class
   [Expand]NavigatorExceptionEventArgs Class
    NavigatorExceptionEventHandler Delegate
   [Expand]NumericChartRangeControlClient Class
   [Expand]NumericChartRangeControlClientGridOptions Class
   [Expand]NumericChartRangeControlClientRange Class
   [Expand]NumericRangeControlClient Class
   [Expand]PanelControl Class
   [Expand]PickImage Class
   [Expand]PictureEdit Class
   [Expand]PopupBaseAutoSearchEdit Class
   [Expand]PopupBaseEdit Class
    PopupCloseMode Enumeration
   [Expand]PopupContainerControl Class
   [Expand]PopupContainerEdit Class
    PopupFilterMode Enumeration
   [Expand]PopupGalleryEdit Class
   [Expand]PopupGalleryEditGallery Class
   [Expand]PopupPanelOptions Class
   [Expand]ProgressBarBaseControl Class
   [Expand]ProgressBarControl Class
   [Expand]RadioGroup Class
   [Expand]RangeControl Class
   [Expand]RangeControlClientBase Class
    RangeControlDateTimeGridAlignment Enumeration
    RangeControlTimeSpanGridAlignment Enumeration
   [Expand]RangeTrackBarControl Class
   [Expand]RatingControl Class
   [Expand]ScrollBarBase Class
    ScrollBarType Enumeration
    ScrollUIMode Enumeration
   [Expand]SearchControl Class
   [Expand]SearchLookUpEdit Class
   [Expand]SeparatorControl Class
    ShowNullValuePromptOptions Enumeration
   [Expand]SidePanel Class
   [Expand]SimpleButton Class
   [Expand]SimpleControl Class
   [Expand]SparklineEdit Class
   [Expand]SpinEdit Class
   [Expand]SplitContainerControl Class
    SplitFixedPanel Enumeration
    SplitPanelVisibility Enumeration
   [Expand]SplitterControl Class
   [Expand]StyleController Class
   [Expand]StyleFormatConditionBase Class
   [Expand]SvgImageBox Class
   [Expand]SvgImageBoxOptionsSelection Class
   [Expand]SvgImageItem Class
   [Expand]SvgImageItemAppearance Class
   [Expand]SvgImageItemAppearanceCollection Class
   [Expand]SvgImageItemCollection Class
   [Expand]SvgImageItemEventArgs Class
   [Expand]SvgImagePopupMenuShowingEventArgs Class
   [Expand]SvgImageSelection Class
   [Expand]SvgImageSelectionChangingEventArgs Class
    SvgImageSizeMode Enumeration
   [Expand]TextEdit Class
   [Expand]TileControl Class
    TileControlImageToTextAlignment Enumeration
    TileControlScrollMode Enumeration
   [Expand]TileGroup Class
   [Expand]TileGroupCollection Class
   [Expand]TileItem Class
   [Expand]TileItemAppearances Class
    TileItemCheckMode Enumeration
    TileItemClickEventHandler Delegate
   [Expand]TileItemCollection Class
    TileItemContentAlignment Enumeration
   [Expand]TileItemDragEventArgs Class
    TileItemDragEventHandler Delegate
   [Expand]TileItemElement Class
   [Expand]TileItemElementCollection Class
   [Expand]TileItemEventArgs Class
   [Expand]TileItemFrame Class
   [Expand]TileItemFrameCollection Class
    TileItemImageScaleMode Enumeration
    TileItemSize Enumeration
   [Expand]TimeEdit Class
   [Expand]TimeSpanChartRangeControlClient Class
   [Expand]TimeSpanChartRangeControlClientGridOptions Class
   [Expand]TimeSpanChartRangeControlClientRange Class
   [Expand]TimeSpanEdit Class
   [Expand]ToggleSwitch Class
   [Expand]TokenEdit Class
   [Expand]TrackBarControl Class
   [Expand]TreeListLookUpEdit Class
    VistaCalendarViewStyle Enumeration
   [Expand]VScrollBar Class
   [Expand]VScrollBarBase Class
    WaitAnimationOptions Enumeration
   [Expand]WindowsFormsSettings Class
   [Expand]XtraBaseArgs Class
   [Expand]XtraDialog Class
   [Expand]XtraDialogArgs Class
   [Expand]XtraFolderBrowserDialog Class
   [Expand]XtraForm Class
   [Expand]XtraInputBox Class
   [Expand]XtraInputBoxArgs Class
   [Expand]XtraMessageBox Class
   [Expand]XtraMessageBoxArgs Class
   [Expand]XtraOpenFileDialog Class
   [Expand]XtraPanel Class
   [Expand]XtraSaveFileDialog Class
   [Expand]XtraScrollableControl Class
   [Expand]XtraUserControl Class
   [Expand]ZoomTrackBarControl Class
  [Expand]DevExpress.XtraEditors.ButtonPanel
  [Expand]DevExpress.XtraEditors.Calendar
  [Expand]DevExpress.XtraEditors.Camera
  [Expand]DevExpress.XtraEditors.Container
  [Expand]DevExpress.XtraEditors.Controls
  [Expand]DevExpress.XtraEditors.CustomEditor
  [Expand]DevExpress.XtraEditors.DXErrorProvider
  [Expand]DevExpress.XtraEditors.Filtering
  [Expand]DevExpress.XtraEditors.Mask
  [Expand]DevExpress.XtraEditors.Persistent
  [Expand]DevExpress.XtraEditors.Repository
  [Expand]DevExpress.XtraEditors.ViewInfo
  [Expand]DevExpress.XtraFilterEditor
  [Expand]DevExpress.XtraGantt
  [Expand]DevExpress.XtraGantt.Base.Scheduling
  [Expand]DevExpress.XtraGantt.Exceptions
  [Expand]DevExpress.XtraGantt.Localization
  [Expand]DevExpress.XtraGantt.Scheduling
  [Expand]DevExpress.XtraGauges.Presets.Styles
  [Expand]DevExpress.XtraGauges.Win
  [Expand]DevExpress.XtraGauges.Win.Base
  [Expand]DevExpress.XtraGauges.Win.Gauges.Circular
  [Expand]DevExpress.XtraGauges.Win.Gauges.Digital
  [Expand]DevExpress.XtraGauges.Win.Gauges.Linear
  [Expand]DevExpress.XtraGauges.Win.Gauges.State
  [Expand]DevExpress.XtraGrid
  [Expand]DevExpress.XtraGrid.Columns
  [Expand]DevExpress.XtraGrid.EditForm
  [Expand]DevExpress.XtraGrid.FilterEditor
  [Expand]DevExpress.XtraGrid.Localization
  [Expand]DevExpress.XtraGrid.Views.BandedGrid
  [Expand]DevExpress.XtraGrid.Views.BandedGrid.ViewInfo
  [Expand]DevExpress.XtraGrid.Views.Base
  [Expand]DevExpress.XtraGrid.Views.Base.ViewInfo
  [Expand]DevExpress.XtraGrid.Views.Card
  [Expand]DevExpress.XtraGrid.Views.Card.ViewInfo
  [Expand]DevExpress.XtraGrid.Views.Grid
  [Expand]DevExpress.XtraGrid.Views.Grid.ViewInfo
  [Expand]DevExpress.XtraGrid.Views.Layout
  [Expand]DevExpress.XtraGrid.Views.Layout.Events
  [Expand]DevExpress.XtraGrid.Views.Layout.ViewInfo
  [Expand]DevExpress.XtraGrid.Views.Printing
  [Expand]DevExpress.XtraGrid.Views.Tile
  [Expand]DevExpress.XtraGrid.Views.WinExplorer
  [Expand]DevExpress.XtraGrid.WinExplorer
  [Expand]DevExpress.XtraLayout
  [Expand]DevExpress.XtraLayout.Converter
  [Expand]DevExpress.XtraLayout.Customization
  [Expand]DevExpress.XtraLayout.HitInfo
  [Expand]DevExpress.XtraLayout.Localization
  [Expand]DevExpress.XtraLayout.Utils
  [Expand]DevExpress.XtraMap
  [Expand]DevExpress.XtraMap.Printing
  [Expand]DevExpress.XtraNavBar
  [Expand]DevExpress.XtraNavBar.ViewInfo
  [Expand]DevExpress.XtraPdfViewer
  [Expand]DevExpress.XtraPdfViewer.Commands
  [Expand]DevExpress.XtraPdfViewer.Extensions
  [Expand]DevExpress.XtraPdfViewer.Localization
  [Expand]DevExpress.XtraPivotGrid
  [Expand]DevExpress.XtraPivotGrid.Data
  [Expand]DevExpress.XtraPrinting
  [Expand]DevExpress.XtraPrinting.Control
  [Expand]DevExpress.XtraPrinting.Preview
  [Expand]DevExpress.XtraPrintingLinks
  [Expand]DevExpress.XtraReports.UI
  [Expand]DevExpress.XtraRichEdit
  [Expand]DevExpress.XtraRichEdit.Commands
  [Expand]DevExpress.XtraRichEdit.Export
  [Expand]DevExpress.XtraRichEdit.Import
  [Expand]DevExpress.XtraRichEdit.Menu
  [Expand]DevExpress.XtraScheduler
  [Expand]DevExpress.XtraScheduler.Drawing
  [Expand]DevExpress.XtraScheduler.GoogleCalendar
  [Expand]DevExpress.XtraScheduler.Printing
  [Expand]DevExpress.XtraScheduler.Reporting
  [Expand]DevExpress.XtraScheduler.Reporting.UI
  [Expand]DevExpress.XtraScheduler.Services
  [Expand]DevExpress.XtraScheduler.Services.Implementation
  [Expand]DevExpress.XtraScheduler.UI
  [Expand]DevExpress.XtraSpellChecker
  [Expand]DevExpress.XtraSpellChecker.Localization
  [Expand]DevExpress.XtraSplashForm
  [Expand]DevExpress.XtraSplashScreen
  [Expand]DevExpress.XtraSpreadsheet
  [Expand]DevExpress.XtraSpreadsheet.Services
  [Expand]DevExpress.XtraTab
  [Expand]DevExpress.XtraTab.Buttons
  [Expand]DevExpress.XtraTab.ViewInfo
  [Expand]DevExpress.XtraTabbedMdi
  [Expand]DevExpress.XtraToolbox
  [Expand]DevExpress.XtraTreeList
  [Expand]DevExpress.XtraTreeList.Columns
  [Expand]DevExpress.XtraTreeList.Data
  [Expand]DevExpress.XtraTreeList.Localization
  [Expand]DevExpress.XtraTreeList.Menu
  [Expand]DevExpress.XtraTreeList.Nodes
  [Expand]DevExpress.XtraTreeList.Nodes.Operations
  [Expand]DevExpress.XtraTreeList.StyleFormatConditions
  [Expand]DevExpress.XtraTreeMap
  [Expand]DevExpress.XtraTreeMap.Printing
  [Expand]DevExpress.XtraVerticalGrid
  [Expand]DevExpress.XtraVerticalGrid.Events
  [Expand]DevExpress.XtraVerticalGrid.Localization
  [Expand]DevExpress.XtraVerticalGrid.Rows
  [Expand]DevExpress.XtraWaitForm
  [Expand]DevExpress.XtraWizard
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

GridLookUpEdit Class

The editor that provides lookup functionality using a dropdown feature-rich Data Grid (GridControl). You can display lookup records in a tabular format, banded tabular format, or as tiles (which can be arranged in one or multiple columns/rows, rendered as a list or a Kanban board).

Namespace:DevExpress.XtraEditors
Assembly:DevExpress.XtraGrid.v19.2.dll

Expanded Syntax

Expanded Remarks

A lookup editor is an editor with an embedded dropdown window that displays lookup records (the records from which an end-user can select). When a lookup record is selected, the editor's value (the BaseEdit.EditValue bindable property) and display text are modified accordingly.

The GridLookUpEdit can display lookup records in the dropdown using multiple data presentation formats (Views), which you can choose with the RepositoryItemGridLookUpEditBase.PopupViewType property:

  • Grid View (default) - Displays data in a tabular form. The following features, and many more, can be employed for the Grid View embedded in the GridLookUpEdit: data sorting, grouping, filtering, summaries, hiding column headers, changing row height, etc. See Grid View to learn more.

  • Tile View - Displays records as read-only tiles, using one of the following layout modes: default (one or multiple columns/rows), list (without spaces between records) and Kanban. This View provides the advanced field positioning feature, which helps you arrange fields relative to other fields, specify absolute or relative field display bounds, etc. See Tile View.

  • Banded Grid View - Displays data in a tabular form and allows grouping of columns into bands. See Banded Grid Views.

  • Advanced Banded Grid View - Displays data in a tabular form, allows grouping columns into bands and supports complex data cell arrangements. See Banded Grid Views.

When you change the data presentation format (RepositoryItemGridLookUpEditBase.PopupViewType), the GridLookUpEdit control creates a corresponding View object (accessible from the RepositoryItemGridLookUpEditBase.PopupView property). You may need to perform additional customizations of the created View. For instance, after you activate the BandedView or AdvBandedView format, you need to manually create bands and add columns to the bands. Otherwise, these Views cannot display data.

At design time, you can customize the View with the Data Grid Designer. To open the designer, do one of the following:

  • click the ellipsis button for the PopupView property in Properties grid.
  • invoke the Designer View command from the Properties window or the control's smart tag.

To learn how to set up lookup editors in different binding modes, see the following topics:

You may want to filter the popup data source of one (secondary) lookup editor based on the value of another (primary) lookup editor. This scenario is covered in the following topic:

In case you need to access lookup grid columns before the editor has created them, call the RepositoryItemGridLookUpEditBase.PopulateViewColumns method to manually trigger column generation.

Expanded Additional Customization

The following list shows some of the members that help you perform additional customization of the GridLookUpEdit control.

To embed a GridLookUpEdit in a cell within a container control (XtraGrid, XtraTreeList, etc), use the RepositoryItemGridLookUpEdit component. See the "Repository Items" section in the Editors and Simple Controls topic for more information.

Note

The GridLookUpEdit control does not support Instant Feedback Mode.

Note

The GridLookUpEdit and SearchLookUpEdit controls do not have a connection to their underlying data sources while their dropdown windows are closed. So in this instance it is not possible to access the underlying data or a grid's calculated data using methods provided by the embedded Grid Control and its View. You can use these methods only when the controls' dropdown windows are open.

While the dropdown windows are closed, you can access the underlying data using methods provided by the underlying data source.

Note

The Find Panel is not supported for the GridLookUpEdit's dropdown GridControl. If you need to enable the Find Panel for a look up editor, use the SearchLookUpEdit control instead.

Expanded Item Search

If you want users to be able to search for lookup items, change the RepositoryItemLookUpEdit.SearchMode property to either AutoSuggest or AutoSearch. The RepositoryItemGridLookUpEdit.TextEditStyle property automatically switches to Standard when you select either of these modes.

Difference between AutoSearch and AutoSuggest modes:

  • AutoSuggest runs a custom Task to return a collection of items for the drop-down panel. As a result, the editor has a virtual data source that changes every time a user text changes. This mode is primarily used with unbound editors.

  • AutoSearch uses the default search logic to find required items in the data source to which this lookup is bound.

  • AutoSearch mode is not currently available with server-mode editor sources.

Both modes are available for stand-alone editors only.

Expanded AutoSuggest Mode

When a user types in text, the editor fires the AutoSuggest event (LookUpEdit.AutoSuggest \ AutoSuggest) that runs a custom asynchronous task (a System.Threading.Tasks.Task object). This task performs a search against the given data set, and returns the ICollection object with records that match the entered text. This collection is automatically assigned to the editor's DataSource and its entries appear in the editor drop-down menu.

This feature is in effect only for stand-alone editors.

AutoSuggest event parameters provide the following API.

To test the AutoSuggest mode, run the AutoSuggest Lookup Demo Center module. You can click the "Open Solution" Ribbon button to view the complete demo code.

In this demo, suggestions (drop-down menu items) are retrieved on the QueryAsync task. The SetMinimumAnimationDuration method ensures the loading indicator is visible for at least one second.

The code below demonstrates how this QueryAsync Task is implemented. The EnsureAllEntries method retrieves all locations from the source. If a user opens the editor drop-down menu, all these entries are visible. Otherwise, the method compares user text with data source records.

In this demo, the data source is the "Data\cities.csv" Excel file that stores nearly 13.000 city names. Each record also contains country and state names, country UN code, and Unicode city name. All records are extracted inside the custom Entry class.

The Entry class contains data fields for Excel file columns, plus additional data fields for values combined from standard fields.

  • Tags - a portion of a record to be checked against an entered user text: City, Unicode City Name, and State Name;
  • Text - full location address in the "CountryName, CityName, StateName" format.
  • HtmlText - same as Text, but country name is written with a grayed-out text. This field is used to custom draw lookup items (see the "Additional Customization" section below).

Custom Item Draw

The HtmlText property decalred in the Entry class is optional - it is not required to implement the auto-suggest functionality. This property is used to manually re-paint lookup items so that country names appear washed out. To do that, handle the RepositoryItemLookUpEdit.CustomDrawCell event.

Custom Highlight Ranges

The QueryAsync Task compares user text with the entry Tags property. This property includes city name, city unicode name, and state name - country names are ignored. For example, the figure below illustrates that the demo database contains many Mexican cities.

If a user enters "ex", from all Mexican cities only "Mexicali" and "Mexico City" remain visible - the Task behaves correctly and filters out non-matching records. However, although the Task ignores countries, the editor highlights "ex" in country names as well.

This happens because there are two separate processes that take place in a lookup editor.

  1. A Task assigned to the QuerySuggestions property scans the data source and chooses records to show in a drop-down menu.
  2. A lookup editor scans items returned by the Task, and looks for user text matches.

If these two processes use different algorhythms, a misleading highlight behavior similar to that mentioned above may happen. If that happens, define custom highlight range(s) with the SetHighlightRange \ SetHighlightRanges methods. The demo code below uses the same logic as in the QueryAsync task to provide correct ranges.

The AutoSuggest event parameter offers a number of methods that you can use to define custom highlight ranges.

Expanded AutoSearch Mode

The AutoSearch mode allows users to search for required data source items.

Change Search Logic

Handle the AutoSearch event (LookUpEdit.AutoSearch \ AutoSearch) and use a SetParameters (see LookUpEditAutoSearchEventArgs.SetParameters) method overload to specify how the editor should compare user text with editor items.

  • parserKind parameter - specifies how user text parts divided by a space character should be combined (see the ColumnViewOptionsFind.ParserKind property for examples).
  • condition parameter - specifies which function should be used to build filter expressions (see the ColumnViewOptionsFind.Condition Data Grid property for examples).
  • field or fieds[] parameter - allows you to limit the search by specific data fields only.
  • text parameter - allows you to replace the user text.

The example below illustrates how to make the editor look for items whose text starts with the user text.

Custom Text Highlight Ranges

Lookup editors highlight text portions that match user text. Handle the AutoSearch event to provide custom highlight ranges. This mode uses same highlight API as the AutoSuggest mode does.

The example below illustrates how to make a lookup editor highlight the entire field value if it starts with user text.

Expanded Example 1

The following example demonstrates how to create and customize a GridLookUpEdit control at runtime.

In the example, a lookup editor will be used to edit the values of the "ProductID" field in the "Order Details" table (NWind database). It must display a list of the available products in the dropdown, which are stored in the "Products" table in the NWind database. By selecting a row from the dropdown an end-user will change the current order's product. Also a data navigator will be created that will assist an end-user to navigate through the "Order Details" table.

To implement the required functionality the following key properties of the lookup editor must be set:

  • The editor's BaseEdit.EditValue property is bound to the "ProductID" field in the "Order Details" table via the DataBindings property.
  • The editor's RepositoryItemLookUpEditBase.DataSource property is set to a DataView object which contains rows from the "Products" table in the NWind database.
  • The editor's RepositoryItemLookUpEditBase.ValueMember property is set to the "ProductID" field in the "Products" table. This field's value must match the editor's edit value, and so the "ProductID" field in the "Order Details" table.
  • The editor's RepositoryItemLookUpEditBase.DisplayMember property is set to the "ProductName" field in the "Products" table. This identifies the field in the DataSource whose values match the editor's display text.
  • Two columns are created within the underlying View via the ColumnView.Columns property. These will display values from the "ProductID" and "ProductName" fields in the dropdown data source.

The result of the example is shown in the following image:

Expanded Example 2

Assume that a GridLookUpEdit control needs to be used in multiple places, and all editors must display data from one predefined data source and contain predefined columns. In this instance, you can create a custom GridLookUpEdit control.

This example shows how to create a custom GridLookUpEdit control, and initialize its properties as required. The structure of descendant classes is based on the code template shown in the Custom Editors.Editors Structure topic.

To customize the control's settings, the OnLoaded method is overridden. In this method, the control's DataSource, columns and some other options are initialized. Note that columns created in this method are not accessible at design time.

Expanded Inheritance Hierarchy

System.Object
    System.MarshalByRefObject
       System.ComponentModel.Component
          System.Windows.Forms.Control
             ControlBase
                BaseControl
                   BaseEdit
                      TextEdit
                         ButtonEdit
                            PopupBaseEdit
                               PopupBaseAutoSearchEdit
                                  LookUpEditBase
                                     GridLookUpEditBase
                                        GridLookUpEdit

Expanded See Also

Is this topic helpful?​​​​​​​