1 //------------------------------------------------------------------------------
2 // <copyright file="ModelItem.cs" company="Microsoft">
3 // Copyright (c) Microsoft Corporation. All rights reserved.
5 //------------------------------------------------------------------------------
7 namespace System.Activities.Presentation.Model
11 using System.ComponentModel;
12 using System.Diagnostics.CodeAnalysis;
14 using System.Collections.Generic;
17 // The ModelItem class represents a single item in the editing model. An
18 // item can be anything from a Window or Control down to a color or integer.
20 // You may access the item�s properties through its Properties collection
21 // and make changes to the values of the properties.
23 // A ModelItem is essentially a wrapper around the designer�s underlying
24 // data model. You can access the underlying model through the
25 // GetCurrentValue method. Note that you should never make any serializable
26 // changes to an object returned from the GetCurrentValue method: it will
27 // not be reflected back in the designer�s serialization or undo systems.
29 public abstract class ModelItem : INotifyPropertyChanged
33 // Creates a new ModelItem.
40 // Implements INotifyPropertyChanged. This can be used to tell when a property
41 // on the model changes. It is also useful because INotifyPropertyChanged can
42 // be used by the data binding features of WPF.
44 // You should take care to disconnect events from items when you are finished
45 // when them. Otherwise you can prevent the item from garbage collecting.
47 public abstract event PropertyChangedEventHandler PropertyChanged;
50 // Returns the attributes declared on this item.
52 public abstract AttributeCollection Attributes { get; }
55 // If this item's ItemType declares a ContentPropertyAttribute,
56 // that property will be exposed here. Otherwise, this will
59 public abstract ModelProperty Content { get; }
62 // Returns the type of object the item represents.
64 public abstract Type ItemType { get; }
67 // This property represents the name or ID of the item. Not
68 // all items need to have names so this may return null. Also,
69 // depending on the type of item and where it sits in the
70 // hierarchy, it may not always be legal to set the name on
71 // an item. If this item's ItemType declares a
72 // RuntimeNamePropertyAttribute, this Name property will be
73 // a direct mapping to the property dictated by that attribute.
75 public abstract string Name { get; set; }
78 // Returns the item that is the parent of this item.
79 // If an item is contained in a collection or dictionary
80 // the collection or dictionary is skipped, returning the
81 // object owns the collection or dictionary.
83 public abstract ModelItem Parent { get; }
86 // Returns the al the parents of this item.
88 public abstract IEnumerable<ModelItem> Parents { get; }
91 // Returns the item that is the root of this tree.
92 // If there is no root yet, as this isn't part of a tree
95 public abstract ModelItem Root { get; }
98 // Returns the public properties on this object. The set of
99 // properties returned may change based on attached
100 // properties or changes to the editing scope.
102 public abstract ModelPropertyCollection Properties { get; }
105 // Returns the property that provided this value. If the item represents
106 // the root of the object graph, this will return null. If an item is a
107 // member of a collection or dictionary, the property returned from Source
108 // will be a pseudo-property provided by the collection or dictionary.
109 // For other values, the Source property returns the property where the
110 // value was actually set. Therefore, if a value is being inherited,
111 // Source allows you to find out who originally provided the value.
113 public abstract ModelProperty Source { get; }
117 // Returns all the properties that hold this value.
119 public abstract IEnumerable<ModelProperty> Sources { get; }
122 // Returns the visual or visual3D representing the UI for this item. This
123 // may return null if there is no view for this object.
125 public abstract DependencyObject View { get; }
128 // If you are doing multiple operations on an object or group of objects
129 // you may call BeginEdit. Once an editing scope is open, all changes
130 // across all objects will be saved into the scope.
132 // Editing scopes are global to the designer. An editing scope may be
133 // created for any item in the designer; you do not need to create an
134 // editing scope for the specific item you are changing.
136 // Editing scopes can be nested, but must be committed in order.
139 // An editing scope that must be either completed or reverted.
141 public abstract ModelEditingScope BeginEdit();
144 // If you are doing multiple operations on an object or group of objects
145 // you may call BeginEdit. Once an editing scope is open, all changes
146 // across all objects will be saved into the scope.
148 // Editing scopes are global to the designer. An editing scope may be
149 // created for any item in the designer; you do not need to create an
150 // editing scope for the specific item you are changing.
152 // Editing scopes can be nested, but must be committed in order.
154 // <param name="description">
155 // An optional description that describes the change. This will be set
156 // into the editing scope�s Description property.
159 // An editing scope that must be either completed or reverted.
161 public abstract ModelEditingScope BeginEdit(string description);
164 // If you are doing multiple operations on an object or group of objects
165 // you may call BeginEdit. Once an editing scope is open, all changes
166 // across all objects will be saved into the scope.
168 // Editing scopes are global to the designer. An editing scope may be
169 // created for any item in the designer; you do not need to create an
170 // editing scope for the specific item you are changing.
172 // Editing scopes can be nested, but must be committed in order.
174 // <param name="shouldApplyChangesImmediately">
175 // A flag to control whether changes should take effect immediately.
178 // An editing scope that must be either completed or reverted.
180 // <exception cref="NotImplementedException">
181 // If the derived class doesn't override this method.
183 // <exception cref="InvalidOperationException">
184 // If shouldApplyChangesImmediately == true but the outer editing scope is not null.
186 public virtual ModelEditingScope BeginEdit(bool shouldApplyChangesImmediately)
188 throw FxTrace.Exception.AsError(new NotImplementedException());
192 // If you are doing multiple operations on an object or group of objects
193 // you may call BeginEdit. Once an editing scope is open, all changes
194 // across all objects will be saved into the scope.
196 // Editing scopes are global to the designer. An editing scope may be
197 // created for any item in the designer; you do not need to create an
198 // editing scope for the specific item you are changing.
200 // Editing scopes can be nested, but must be committed in order.
202 // <param name="description">
203 // An optional description that describes the change. This will be set
204 // into the editing scope�s Description property.
206 // <param name="shouldApplyChangesImmediately">
207 // A flag to control whether changes should take effect immediately.
210 // An editing scope that must be either completed or reverted.
212 // <exception cref="NotImplementedException">
213 // If the derived class doesn't override this method.
215 // <exception cref="InvalidOperationException">
216 // If shouldApplyChangesImmediately == true but the outer editing scope is not null.
218 public virtual ModelEditingScope BeginEdit(string description, bool shouldApplyChangesImmediately)
220 throw FxTrace.Exception.AsError(new NotImplementedException());
224 // Returns the current value of the underlying model object the ModelItem
225 // is wrapping. You can inspect this object, but you should not make any
226 // changes to it. Changes made to the object returned will not be incorporated
227 // into the designer. The GetCurrentValue method may return either an existing
228 // or new cloned instance of the object.
231 // Returns the current value of the underlying model object the ModelItem is wrapping.
233 public abstract object GetCurrentValue();
236 // Returns string representation of the ModelItem which is the string representation
237 // of underlying object the ModelItem is wrapping.
240 // Returns string representation of the ModelItem.
242 public override string ToString()
244 object instance = this.GetCurrentValue();
245 if (instance != null)
247 return instance.ToString();
251 return base.ToString();
255 internal virtual event PropertyReferenceChangedEventHandler PropertyReferenceChanged;
257 internal virtual void OnPropertyReferenceChanged(string targetProperty)
259 if (this.PropertyReferenceChanged != null)
261 this.PropertyReferenceChanged(this, new PropertyReferenceChangedEventArgs(targetProperty));