The Labs \ Source Viewer \ SSCLI \ System.ComponentModel \ ToolboxItemFilterAttribute

  1. //------------------------------------------------------------------------------
  2. // <copyright file="ToolboxItemFilterAttribute.cs" company="Microsoft">
  3. //
  4. // Copyright (c) 2006 Microsoft Corporation. All rights reserved.
  5. //
  6. // The use and distribution terms for this software are contained in the file
  7. // named license.txt, which can be found in the root of this distribution.
  8. // By using this software in any fashion, you are agreeing to be bound by the
  9. // terms of this license.
  10. //
  11. // You must not remove this notice, or any other, from this software.
  12. //
  13. // </copyright>
  14. //------------------------------------------------------------------------------
  15. namespace System.ComponentModel
  16. {
  17.    
  18.     using System;
  19.     using System.Diagnostics;
  20.     using System.Security.Permissions;
  21.    
  22.     /// <devdoc>
  23.     /// This attribute allows you to configure a filter that is used enable or disable toolbox items
  24.     /// from being used on particular designers. For example, you may have a class of components
  25.     /// that can only be used on a certain type of designer. You can configure a toolbox item
  26.     /// filter to enforce that rule. For example, take a report designer that uses a component
  27.     /// base class of ReportElement. You may want to make ReportElement toolbox items enabled only
  28.     /// when a ReportDesigner is the active designer. To do this, you would add the following
  29.     /// ToolboxItemFilter attributes to each class:
  30.     ///
  31.     /// [ToolboxItemFilter("MyReportFilterString", ToolboxItemFilterType.Require)]
  32.     /// public class ReportElement : Component {}
  33.     ///
  34.     /// [ToolboxItemFilter("MyReportFilterString", ToolboxItemFilterType.Require)]
  35.     /// public class ReportDesigner : Component {}
  36.     ///
  37.     /// These two filters specify that ReportElement toolbox items will only be
  38.     /// enabled when a ReportDesigner is visible. By specifying a filter type of
  39.     /// Require on the report designer class, this will disable any toolbox items
  40.     /// that are not report elements. If the report designer specifed a filter type
  41.     /// of "Allow" instead of "Require", other components would be enabled when the
  42.     /// report designer was active. ReportElements would still be disabled when
  43.     /// other designers were active, however, because ReportElement requires designers
  44.     /// to have the given filter string.
  45.     ///
  46.     /// Toolbox item filtering is a useful way to restrict toolbox item visibility to
  47.     /// cases where it is appropriate. This can help to avoid confusion for users, but
  48.     /// you should use caution not to make items unusually restrictive. If you have a
  49.     /// general purpose component, for example, you should allow the component to appear
  50.     /// on any designer.
  51.     ///
  52.     /// The ASP.NET and Windows Forms designers both use filter attributes to prevent
  53.     /// each other's components from being enabled. This is a useful restriction because,
  54.     /// since each has several duplicate class names, it may be confusing to users and
  55.     /// they may not know which controls to choose.
  56.     ///
  57.     /// </devdoc>
  58.     [AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true), Serializable()]
  59.     public sealed class ToolboxItemFilterAttribute : Attribute
  60.     {
  61.         private ToolboxItemFilterType filterType;
  62.         private string filterString;
  63.         private string typeId;
  64.        
  65.         /// <devdoc>
  66.         /// Initializes a new ToolboxItemFilterAttribute with the provide filter string and a filter type of
  67.         /// "Allow".
  68.         /// </devdoc>
  69.         public ToolboxItemFilterAttribute(string filterString) : this(filterString, ToolboxItemFilterType.Allow)
  70.         {
  71.         }
  72.        
  73.         /// <devdoc>
  74.         /// Initializes a new ToolboxItemFilterAttribute with the provide filter string and filter type.
  75.         /// </devdoc>
  76.         public ToolboxItemFilterAttribute(string filterString, ToolboxItemFilterType filterType)
  77.         {
  78.             if (filterString == null)
  79.                 filterString = String.Empty;
  80.            
  81.             this.filterString = filterString;
  82.             this.filterType = filterType;
  83.         }
  84.        
  85.         /// <devdoc>
  86.         /// Retrieves the filter string for this attribute. The filter string is a user-defined string that
  87.         /// is used to identify matching attributes.
  88.         /// </devdoc>
  89.         public string FilterString {
  90.             get { return filterString; }
  91.         }
  92.        
  93.         /// <devdoc>
  94.         /// Retrieves the filter type for this attribute. The filter type determines how the filter string should
  95.         /// be applied.
  96.         /// </devdoc>
  97.         public ToolboxItemFilterType FilterType {
  98.             get { return filterType; }
  99.         }
  100.        
  101.         /// <devdoc>
  102.         /// The unique identifier for this attribute. All ToolboxItemFilterAttributes with the same filter string
  103.         /// are considered the same, so they return the same TypeId.
  104.         /// </devdoc>
  105.         public override object TypeId {
  106.             get {
  107.                 if (typeId == null) {
  108.                     typeId = GetType().FullName + filterString;
  109.                 }
  110.                 return typeId;
  111.             }
  112.         }
  113.        
  114.         public override bool Equals(object obj)
  115.         {
  116.             if (obj == this) {
  117.                 return true;
  118.             }
  119.            
  120.             ToolboxItemFilterAttribute other = obj as ToolboxItemFilterAttribute;
  121.             return (other != null && other.FilterType.Equals(FilterType) && other.FilterString.Equals(FilterString));
  122.         }
  123.        
  124.         public override int GetHashCode()
  125.         {
  126.             // No need to hash on filter type as well; there shouldn't be that many duplicates.
  127.             return filterString.GetHashCode();
  128.         }
  129.        
  130.         public override bool Match(object obj)
  131.         {
  132.            
  133.             ToolboxItemFilterAttribute other = obj as ToolboxItemFilterAttribute;
  134.             if (other == null) {
  135.                 return false;
  136.             }
  137.            
  138.             // different filter string kills a match immediately.
  139.             //
  140.             if (!other.FilterString.Equals(FilterString)) {
  141.                 return false;
  142.             }
  143.            
  144.             return true;
  145.         }
  146.        
  147.         public override string ToString()
  148.         {
  149.             return filterString + "," + Enum.GetName(typeof(ToolboxItemFilterType), filterType);
  150.         }
  151.     }
  152. }

Developer Fusion