This Control will be very familiar to users of the
Visual Studio .NET IDE, as it is used to provide the property
inspector for objects in the designer. You can use it to provide a
similar function in your own applications.
At its simplest, you can assign any object to the
SelectedObject property, and it will use
reflection to discover the properties and events in your object. You
can also set an array of SelectedObjects. The grid
will then display only those properties common to the entire array.
This should not be confused with the
SelectedGridItem property, which returns a
GridItem representing the currently selected row
in the grid. You can bind to the
SelectedGridItemChanged event to receive
notification when the selection is modified. As the values in the
grid change, the PropertyValueChanged event is
raised. If the SelectedObject (or
SelectedObjects) changes, the grid will fire
SelectedObjectsChanged.
Beyond that, you can use several designer attributes to mark up your
target objects for use with the PropertyGrid,
including System.ComponentModel.CategoryAttribute,
which provides a means of visually grouping properties, and
System.ComponentModel.DescriptionAttribute, which
displays help text.
A property will appear in the grid unless it is annotated with
No. You can customize this behavior by creating a
new System.ComponentModel.AttributeCollection
(passing an array of Attribute objects in the
constructor) and assigning it to the grid's
BrowsableAttributes property. The object must then
be annotated with every attribute in this collection for it to
appear.
To facilitate the editing of properties that are not understood by
the default designers, you can provide a custom
System.ComponentModel.TypeConverter and/or
System.Drawing.Design.UITypeEditor for any and all
of the types the target object exposes.
The grid can also display any
System.ComponentModel.Design.DesignerVerb
(essentially design-time commands) that a
System.ComponentModel.Design.IDesigner-derived
class exposes for the target object through its
Verbs property. All these features are exactly
like those facilities provided by the design-time environment.
Aside from the design-time features, there are a number of properties
that you can use to control the appearance of the grid itself.
The PropertyGrid has a toolbar that allows the
user to customize various aspects of its appearance. If you
don't require this toolbar, it can be hidden with
the ToolbarVisible property.
A panel for the verbs can be shown or hidden using the
CommandsVisible property, but you can determine
whether this is permissible at all with the
CanShowCommands member. You can also decide not to
show the verb panel if there are no verbs defined by using the
CommandsVisibleIfAvailable property. The color of
this pane can be changed with the
CommandsBackColor and
CommandsForeColor properties.
Similarly, you can show or hide the help region with the
HelpVisible property and set its colors with the
HelpForeColor and
HelpBackColor. The grid will display the text
specified in the
System.ComponentModel.DescriptionAttribute with
which you adorned a property.
By default, the grid sorts the properties into groups according to
their System.ComponentModel.CategoryAttributes
(with Misc being the default group for unattributed properties). If
you don't want this behavior, it can be modified by
changing the PropertySort member
(Alphabetical, for instance, would display a
single alphabetical list).
You can also change the LineColor of the grid
lines and the size of the toolbar buttons (with the
LargeButtons member).
public class PropertyGrid : ContainerControl :
System.Windows.Forms.ComponentModel.Com2Interop.IComPropertyBrowser, IPropertyNotifySink {
// Public Constructors
public PropertyGrid();
// Public Instance Properties
public override bool AutoScroll{set; get; }
// overrides ScrollableControl
public override Color BackColor{set; get; }
// overrides Control
public override Image BackgroundImage{set; get; }
// overrides Control
public AttributeCollection BrowsableAttributes{set; get; }
public virtual bool CanShowCommands{get; }
public Color CommandsBackColor{set; get; }
public Color CommandsForeColor{set; get; }
public virtual bool CommandsVisible{get; }
public virtual bool CommandsVisibleIfAvailable{set; get; }
public Point ContextMenuDefaultLocation{get; }
public ControlCollection Controls{get; }
// overrides Control
public override Color ForeColor{set; get; }
// overrides Control
public Color HelpBackColor{set; get; }
public Color HelpForeColor{set; get; }
public virtual bool HelpVisible{set; get; }
public bool LargeButtons{set; get; }
public Color LineColor{set; get; }
public PropertySort PropertySort{set; get; }
public PropertyTabCollection PropertyTabs{get; }
public GridItem SelectedGridItem{set; get; }
public object SelectedObject{set; get; }
public object[ ] SelectedObjects{set; get; }
public PropertyTab SelectedTab{get; }
public override ISite Site{set; get; }
// overrides Control
public virtual bool ToolbarVisible{set; get; }
public Color ViewBackColor{set; get; }
public Color ViewForeColor{set; get; }
// Protected Instance Properties
protected override Size DefaultSize{get; }
// overrides Control
protected virtual Type DefaultTabType{get; }
protected bool DrawFlatToolbar{set; get; }
protected override bool ShowFocusCues{get; }
// overrides Control
// Public Instance Methods
public void CollapseAllGridItems();
public void ExpandAllGridItems();
public override void Refresh(); // overrides Control
public void RefreshTabs(System.ComponentModel.PropertyTabScope tabScope);
public void ResetSelectedProperty();
// Protected Instance Methods
protected virtual PropertyTab CreatePropertyTab(Type tabType);
protected override void Dispose(bool disposing); // overrides ContainerControl
protected void OnComComponentNameChanged(System.ComponentModel.Design.ComponentRenameEventArgs e);
protected override void OnFontChanged(EventArgs e); // overrides Control
protected override void OnGotFocus(EventArgs e); // overrides Control
protected override void OnHandleCreated(EventArgs e); // overrides Control
protected override void OnHandleDestroyed(EventArgs e); // overrides Control
protected override void OnMouseDown(MouseEventArgs me); // overrides Control
protected override void OnMouseMove(MouseEventArgs me); // overrides Control
protected override void OnMouseUp(MouseEventArgs me); // overrides Control
protected void OnNotifyPropertyValueUIItemsChanged(object sender, EventArgs e);
protected override void OnPaint(PaintEventArgs pevent); // overrides Control
protected virtual void OnPropertyTabChanged(PropertyTabChangedEventArgs e);
protected virtual void OnPropertyValueChanged(PropertyValueChangedEventArgs e);
protected override void OnResize(EventArgs e); // overrides Control
protected virtual void OnSelectedGridItemChanged(SelectedGridItemChangedEventArgs e);
protected virtual void OnSelectedObjectsChanged(EventArgs e);
protected override void OnSystemColorsChanged(EventArgs e); // overrides Control
protected override void OnVisibleChanged(EventArgs e); // overrides ScrollableControl
protected override bool ProcessDialogKey(Keys keyData); // overrides ContainerControl
protected override void ScaleCore(float dx, float dy); // overrides ScrollableControl
protected void ShowEventsButton(bool value);
protected override void WndProc(ref Message m); // overrides ContainerControl
// Events
public event EventHandler PropertySortChanged;
public event PropertyTabChangedEventHandler PropertyTabChanged;
public event PropertyValueChangedEventHandler PropertyValueChanged;
public event SelectedGridItemChangedEventHandler SelectedGridItemChanged;
public event EventHandler SelectedObjectsChanged;
}