windowsforms-120262-controls-and-libraries-property-grid-office-view.md
|
|
The Office View emulates settings panels available in Microsoft Office applications. This view type supports the following features:
To activate the Office View, set the PropertyGridControl.ActiveViewType property to Office.
|
Important
The Office View does not support multi-editor rows. If the control contains multi-editor rows and you change the ActiveViewType property from Classic to Office in the Windows Forms Designer, the control automatically converts multi-editor rows into multiple single-editor rows. This operation is irreversible.
Tip
Run the following demo to see the Office View: Property Grid module in the XtraVerticalGrid MainDemo.
The default Office View displays properties without tabs. To organize properties into tabs, you should create these tabs and assign properties to them. The images below display the same object with and without tabs.
To create tabs, follow the steps below:
Assign an object to the PropertyGridControl.SelectedObject property.
In the control’s smart tag, click Run Designer. Switch to the Tabs page.
Click Create Tab. Select the created tab and use the check boxes on the right to add properties to the tab. Note that the Property Grid does not display a property if you do not assign it to a tab.
Handle the PropertyGridControl.TabPanelCustomize event as follows to create tabs in code and populate them with properties and categories:
The code sample below organizes properties into the following tabs:
using DevExpress.XtraVerticalGrid;
using DevExpress.Utils.Svg;
private void propertyGridControl1_TabPanelCustomize(object sender, DevExpress.XtraVerticalGrid.Events.TabPanelCustomizeEventArgs e) {
//Tab #1.
Tab tab1 = new Tab();
tab1.Caption = "Accessibility";
tab1.ImageOptions.Image = SvgBitmap.FromFile(@"D:\Images\Pages.svg").Render(null, 1);
//Add a property.
tab1.FieldNames.Add("Text");
//Add a category.
tab1.CategoryNames.Add("Accessibility");
//Tab #2.
Tab tab2 = new Tab();
tab2.Caption = "Appearance";
tab2.ImageOptions.Image = SvgBitmap.FromFile(@"D:\Images\Medium.svg").Render(null, 1);
tab2.CategoryNames.Add("Appearance");
e.Tabs.Add(tab1);
e.Tabs.Add(tab2);
propertyGridControl1.SelectedTab = propertyGridControl1.Tabs[0];
}
Imports DevExpress.XtraVerticalGrid
Imports DevExpress.Utils.Svg
Private Sub propertyGridControl1_TabPanelCustomize(ByVal sender As Object, ByVal e As DevExpress.XtraVerticalGrid.Events.TabPanelCustomizeEventArgs)
'Tab #1.
Dim tab1 As New Tab()
tab1.Caption = "Accessibility"
tab1.ImageOptions.Image = SvgBitmap.FromFile("D:\Images\Pages.svg").Render(Nothing, 1)
'Add a property.
tab1.FieldNames.Add("Text")
'Add a category.
tab1.CategoryNames.Add("Accessibility")
'Tab #2.
Dim tab2 As New Tab()
tab2.Caption = "Appearance"
tab2.ImageOptions.Image = SvgBitmap.FromFile("D:\Images\Medium.svg").Render(Nothing, 1)
tab2.CategoryNames.Add("Appearance")
e.Tabs.Add(tab1)
e.Tabs.Add(tab2)
propertyGridControl1.SelectedTab = propertyGridControl1.Tabs(0)
End Sub
To display a trackbar editor for a numeric property, enable the ShowTrackBar option. Use the MinValue and MaxValue to specify the trackbar’s minimum and maximum values, respectively.
If you generate rows at design time, you can also set these properties in the designer.
You can also use the ShowTrackBar event argument in a PropertyGridControl.CustomRowCreated event handler.
The code below displays a trackbar editor for the Font.Size property. The event handler also specifies the minimum and maximum editor values.
private void PropertyGridControl1_CustomRowCreated(object sender, DevExpress.XtraVerticalGrid.Events.CustomRowCreatedEventArgs e) {
if (e.Row.Properties.FieldName == "Font.Size") {
PGridNumericEditorRow row = e.Row as PGridNumericEditorRow;
row.MinValue = 8;
row.MaxValue = 72;
row.ShowTrackBar = true;
row.IgnoreMinMaxForSpinEdit = true;
}
}
Private Sub PropertyGridControl1_CustomRowCreated(ByVal sender As Object, ByVal e As DevExpress.XtraVerticalGrid.Events.CustomRowCreatedEventArgs)
If e.Row.Properties.FieldName = "Font.Size" Then
Dim row As PGridNumericEditorRow = TryCast(e.Row, PGridNumericEditorRow)
row.MinValue = 8
row.MaxValue = 72
row.ShowTrackBar = True
row.IgnoreMinMaxForSpinEdit = True
End If
End Sub
The Property Grid fires the PropertyGridControl.CustomRowCreated event when it generates rows. You can handle this event to customize created rows.
The following example displays properties of an AppSettings object in a Property Grid in OfficeView mode. The code handles the PropertyGridControl.CustomRowCreated event to hide editors for the SystemSettings and ReportSettings properties.
public partial class Form1 : Form {
public AppSettings Settings { get; set; } = new AppSettings();
public Form1() {
InitializeComponent();
propertyGridControl1.ActiveViewType = DevExpress.XtraVerticalGrid.PropertyGridView.Office;
propertyGridControl1.CustomRowCreated += PropertyGridControl1_CustomRowCreated;
propertyGridControl1.SelectedObject = Settings;
}
private void PropertyGridControl1_CustomRowCreated(object sender, DevExpress.XtraVerticalGrid.Events.CustomRowCreatedEventArgs e) {
// Hide editors for "SystemSettings" and "ReportSettings" properties.
if (e.Row.Properties.FieldName == "SystemSettings" || e.Row.Properties.FieldName == "ReportSettings") {
e.Row = new PGridEmptyRow();
e.Handled = true;
}
}
}
public class AppSettings {
[Category("System")]
[DisplayName("System Settings")]
[TypeConverter(typeof(ExpandableObjectConverter))]
public SystemSettings SystemSettings { get; } = new SystemSettings();
[Category("System")]
[DisplayName("Reporting")]
[TypeConverter(typeof(ExpandableObjectConverter))]
public ReportSettings ReportSettings { get; set; } = new ReportSettings();
}
public class SystemSettings {
[DisplayName("Run in background")]
[Category("System")]
[DefaultValue(true)]
public bool RunInBackground { get; set; } = true;
[DisplayName("Process count")]
[Category("System")]
[DefaultValue(2)]
public int ProcessCount { get; set; } = 2;
}
public class ReportSettings {
[DisplayName("Zoom")]
[DefaultValue(100)]
public decimal ZoomFactor { get; set; } = 100;
}
Partial Public Class Form1
Public Property Settings() As New AppSettings()
Public Sub New()
InitializeComponent()
PropertyGridControl1.ActiveViewType = DevExpress.XtraVerticalGrid.PropertyGridView.Office
AddHandler PropertyGridControl1.CustomRowCreated, AddressOf PropertyGridControl1_CustomRowCreated
PropertyGridControl1.SelectedObject = Settings
End Sub
Private Sub PropertyGridControl1_CustomRowCreated(ByVal sender As Object, ByVal e As DevExpress.XtraVerticalGrid.Events.CustomRowCreatedEventArgs)
' Hide editors for "SystemSettings" and "ReportSettings" properties.
If e.Row.Properties.FieldName = "SystemSettings" OrElse e.Row.Properties.FieldName = "ReportSettings" Then
e.Row = New PGridEmptyRow()
e.Handled = True
End If
End Sub
Public Class AppSettings
<Category("System")>
<DisplayName("System Settings")>
<TypeConverter(GetType(ExpandableObjectConverter))>
Public ReadOnly Property SystemSettings() As New SystemSettings()
<Category("System")>
<DisplayName("Reporting")>
<TypeConverter(GetType(ExpandableObjectConverter))>
Public Property ReportSettings() As New ReportSettings()
End Class
Public Class SystemSettings
<DisplayName("Run in background")>
<Category("System")>
<DefaultValue(True)>
Public Property RunInBackground() As Boolean = True
<DisplayName("Process count")>
<Category("System")>
<DefaultValue(2)>
Public Property ProcessCount() As Integer = 2
End Class
Public Class ReportSettings
<DisplayName("Zoom")>
<DefaultValue(100)>
Public Property ZoomFactor() As Decimal = 100
End Class
End Class
The Office View can display property markers — small rectangles displayed next to property editors. A property marker shows whether a property is set to its default value and allows a user to invoke a context menu.
To display property markers, enable the ShowRowBrick option. The default context menu contains the Reset command that sets the property to its default value. To populate the context menu with custom commands, handle the PropertyGridControl.RowBrickMenuShowing event.
using DevExpress.Utils.Menu;
DXMenuItem createDataBindingItem;
protected DXMenuItem CreateDataBindingItem {
get {
if (createDataBindingItem == null) {
DXMenuItem item = new DXMenuItem("Create Data Binding...");
item.Click += (s, ee) => MessageBox.Show("'Create Data Binding...' is clicked.");
createDataBindingItem = item;
}
return createDataBindingItem;
}
}
private void Grid_RowBrickMenuShowing(object sender, Events.PopupMenuShowingEventArgs e) {
if(e.Row.Properties.FieldName == "Appearance.BackColor")
e.Menu.Items.Add(CreateDataBindingItem);
}
Imports DevExpress.Utils.Menu
Private Sub propertyGridControl1_RowBrickMenuShowing(ByVal sender As Object, ByVal e As DevExpress.XtraVerticalGrid.Events.PopupMenuShowingEventArgs) _
Handles propertyGridControl1.RowBrickMenuShowing
If e.Row.Properties.FieldName = "Appearance.BackColor" Then
e.Menu.Items.Add(CreateDataBindingItem)
End If
End Sub
Private createDataBindingItem1 As DXMenuItem
Protected ReadOnly Property CreateDataBindingItem() As DXMenuItem
Get
If createDataBindingItem1 Is Nothing Then
Dim item As New DXMenuItem("Create Data Binding...")
AddHandler item.Click, Sub(s, ee) MessageBox.Show("'Create Data Binding...' is clicked.")
createDataBindingItem1 = item
End If
Return createDataBindingItem1
End Get
End Property
Note
When a user right-clicks a property (not a property marker), the context menu does not contain commands added in a RowBrickMenuShowing event handler.
A property marker color depends on whether the property is set to its default value. The default colors depend on the applied skin. You can handle the PropertyGridControl.CustomDrawRowBrick event to customize property marker colors.
private void propertyGridControl1_CustomDrawRowBrick(object sender, DevExpress.XtraVerticalGrid.Events.CustomDrawRowBrickEventArgs e) {
e.Handled = true;
Size size = new Size(7, 7);
Rectangle bounds = RectangleHelper.GetCenterBounds(e.RowBrickInfo.BrickArea, size);
if (e.RowBrickInfo.State == DevExpress.Utils.Drawing.ObjectState.Normal)
e.Cache.FillRectangle(Color.Transparent, bounds);
if (e.RowBrickInfo.State == DevExpress.Utils.Drawing.ObjectState.Hot)
e.Cache.FillRectangle(Color.LightGray, bounds);
e.Cache.DrawRectangle(bounds, Color.DarkGray, e.RowBrickInfo.BorderThickness);
}
Private Sub propertyGridControl1_CustomDrawRowBrick(ByVal sender As Object, ByVal e As DevExpress.XtraVerticalGrid.Events.CustomDrawRowBrickEventArgs) _
Handles propertyGridControl1.CustomDrawRowBrick
e.Handled = True
Dim size1 As New Size(7, 7)
Dim bounds1 As Rectangle = RectangleHelper.GetCenterBounds(e.RowBrickInfo.BrickArea, size1)
If e.RowBrickInfo.State = DevExpress.Utils.Drawing.ObjectState.Normal Then
e.Cache.FillRectangle(Color.Transparent, bounds1)
End If
If e.RowBrickInfo.State = DevExpress.Utils.Drawing.ObjectState.Hot Then
e.Cache.FillRectangle(Color.LightGray, bounds1)
End If
e.Cache.DrawRectangle(bounds1, Color.DarkGray, e.RowBrickInfo.BorderThickness)
End Sub
The Property Grid control with active Office View posts changes to a data source immediately. Use the OptionsBehavior.AutoPostEditorDelay property to specify the delay between changing a value in the editor and posting it to the data source.