mcs/class/referencesource/System.Activities.Presentation/System.Activities.Presentation/System/Activities/Presentation/Model/ModelService.cs

   1 //------------------------------------------------------------------------------
   2 // <copyright file="ModelService.cs" company="Microsoft">
   3 //     Copyright (c) Microsoft Corporation.  All rights reserved.
   4 // </copyright>
   5 //------------------------------------------------------------------------------
   6
   7 namespace System.Activities.Presentation.Services {
   8
   9     using System;
  10     using System.Collections.Generic;
  11     using System.Activities.Presentation.Model;
  12
  13     /// <summary>
  14     /// The ModelService class is the main entry point the designer
  15     /// uses to obtain the model.  The service actually has a split
  16     /// between public and protected methods you must implement.
  17     /// The public methods are (obviously) callable by anyone.
  18     /// The protected methods are invoked by the model.
  19     /// </summary>
  20     public abstract class ModelService {
  21
  22         /// <summary>
  23         /// Constructs a new ModelService.
  24         /// </summary>
  25         protected ModelService() {
  26         }
  27
  28         /// <summary>
  29         /// The root of the object hierarchy.  For purely linear stores
  30         /// this will be the first object in the store.  For stores that
  31         /// represent a tree of objects this returns the topmost node of
  32         /// the tree.
  33         /// </summary>
  34         public abstract ModelItem Root { get; }
  35
  36         /// <summary>
  37         /// This event is raised when something in the model has changed.
  38         /// The event args in the event can be used to find what has changed.
  39         /// </summary>
  40         public abstract event EventHandler<ModelChangedEventArgs> ModelChanged;
  41
  42         /// <summary>
  43         /// Creates a ModelItem for a given type.  This method is called by
  44         /// ModelFactory when the user wishes to create a new item.
  45         /// </summary>
  46         /// <param name="itemType">
  47         /// The type of item to create.
  48         /// </param>
  49         /// <param name="options">
  50         /// Creation options.  You can specify if you would like to initialize
  51         /// default values for an item.
  52         /// </param>
  53         /// <param name="arguments">
  54         /// An array of arguments to the constructor of the item.
  55         /// </param>
  56         /// <returns>The newly created model item.</returns>
  57         /// <exception cref="ArgumentNullException">if itemType is null</exception>
  58         protected abstract ModelItem CreateItem(Type itemType, CreateOptions options, params object[] arguments);
  59
  60         /// <summary>
  61         /// Takes an existing instance and creates a model item that is a deep clone
  62         /// of the instance.
  63         /// </summary>
  64         /// <param name="item">
  65         /// The item to wrap.
  66         /// </param>
  67         /// <returns>A newly created model item that is a clone of the existing item.</returns>
  68         /// <exception cref="ArgumentNullException">if item is null</exception>
  69         protected abstract ModelItem CreateItem(object item);
  70
  71         /// <summary>
  72         /// Create a new model item that represents a the value of a static member of a the given class.
  73         /// For example, to add a reference to Brushes.Red to the model call this methods with
  74         /// typeof(Brushes) and the string "Red". This will be serialized into XAML as
  75         /// {x:Static Brushes.Red}.
  76         /// </summary>
  77         /// <param name="type">
  78         /// The type that contains the static member being referenced.
  79         /// </param>
  80         /// <param name="memberName">
  81         /// The name of the static member being referenced.
  82         /// </param>
  83         protected abstract ModelItem CreateStaticMemberItem(Type type, string memberName);
  84
  85         /// <summary>
  86         /// Finds matching model items given a starting point to look.  All
  87         /// walks are recursive.
  88         /// </summary>
  89         /// <param name="startingItem">
  90         /// The model item to start the search.  Items above this item
  91         /// will be ignored.  This item, and any item below it in the
  92         /// hierarchy, will be included in the search.  If this value is
  93         /// null, the root is used.
  94         /// </param>
  95         /// <param name="type">
  96         /// The type of the object to find.  This will enumerate all items
  97         /// within the given parent scope that are of the requested type.
  98         /// </param>
  99         /// <returns>
 100         /// An enumeration of model items matching the query.
 101         /// </returns>
 102         /// <exception cref="ArgumentNullException">if type is null</exception>
 103         public abstract IEnumerable<ModelItem> Find(ModelItem startingItem, Type type);
 104
 105         /// <summary>
 106         /// Finds matching model items given a starting point to look.  All
 107         /// walks are recursive.
 108         /// </summary>
 109         /// <param name="startingItem">
 110         /// The model item to start the search.  Items above this item
 111         /// will be ignored.  This item, and any item below it in the
 112         /// hierarchy, will be included in the search.  If this value is
 113         /// null, the root is used.
 114         /// </param>
 115         /// <param name="match">
 116         /// A predicate that allows more complex type matching to be used.
 117         /// For example, the predicate could return true for both
 118         /// FrameworkElement and FrameworkContentElement.
 119         /// </param>
 120         /// <returns>
 121         /// An enumeration of model items matching the query.
 122         /// </returns>
 123         /// <exception cref="ArgumentNullException">if match is null</exception>
 124         public abstract IEnumerable<ModelItem> Find(ModelItem startingItem, Predicate<Type> match);
 125
 126         /// <summary>
 127         /// Locates the model item in the given scope with the given name.  Returns null if
 128         /// the model item could not be located.
 129         /// </summary>
 130         /// <param name="scope">
 131         /// An optional scope to provide.  If not provided, the root element will
 132         /// be used as a scope.  If provided, the nearest INameScope in the hierarchy
 133         /// will be used to locate the item.
 134         /// </param>
 135         /// <param name="name">
 136         /// The name to locate.
 137         /// </param>
 138         /// <returns>
 139         /// A model item whose name matches that provided, or null if no match was
 140         /// found.
 141         /// </returns>
 142         /// <exception cref="ArgumentNullException">If name is null.</exception>
 143         public ModelItem FromName(ModelItem scope, string name) {
 144             return FromName(scope, name, StringComparison.Ordinal);
 145         }
 146
 147         /// <summary>
 148         /// Locates the model item in the given scope with the given name.  Returns null if
 149         /// the model item could not be located.
 150         /// </summary>
 151         /// <param name="scope">
 152         /// An optional scope to provide.  If not provided, the root element will
 153         /// be used as a scope.  If provided, the nearest INameScope in the hierarchy
 154         /// will be used to locate the item.
 155         /// </param>
 156         /// <param name="name">
 157         /// The name to locate.
 158         /// </param>
 159         /// <param name="comparison">
 160         /// Determines how the name should be compared.  The default is to compare against
 161         /// ordinal.
 162         /// </param>
 163         /// <returns>
 164         /// A model item whose name matches that provided, or null if no match was
 165         /// found.
 166         /// </returns>
 167         /// <exception cref="ArgumentNullException">If name is null.</exception>
 168         public abstract ModelItem FromName(ModelItem scope, string name, StringComparison comparison);
 169
 170         /// <summary>
 171         /// Creates a ModelItem for a given type.  This method is called by
 172         /// ModelFactory when the user wishes to create a new item.
 173         /// </summary>
 174         internal ModelItem InvokeCreateItem(Type itemType, CreateOptions options, params object[] arguments) {
 175             return CreateItem(itemType, options, arguments);
 176         }
 177
 178         /// <summary>
 179         /// Creates a member item that refers to a static member of the given type.
 180         /// </summary>
 181         internal ModelItem InvokeCreateStaticMemberItem(Type type, string memberName) {
 182             return CreateStaticMemberItem(type, memberName);
 183         }
 184
 185         /// <summary>
 186         /// Takes an existing instance and wraps it in a ModelItem.  The set
 187         /// properties on the instance are promoted to the model item.
 188         /// </summary>
 189         internal ModelItem InvokeCreateItem(object item) {
 190             return CreateItem(item);
 191         }
 192     }
 193 }