BaseProperty.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Diagnostics.CodeAnalysis;
using System.Windows.Markup;

#nullable disable

namespace Microsoft.Build.Framework.XamlTypes
{
    /// <summary>
    /// Represents a <see cref="Rule"/> property.
    /// </summary>
    /// <remarks>
    /// <para>This represents schema information (name, allowed values, etc) of a <see cref="Rule"/> property.
    /// Since this is just schema information, there is no field like "Value" used to get/set the value of this
    /// property.</para>
    /// <para> Those who manually instantiate this class should remember to call <see cref="BeginInit"/> before
    /// setting the first property and <see cref="EndInit"/> after setting the last property of the object.</para>
    /// </remarks>
    /// <comment>
    /// This partial class contains all properties which are public and hence settable in XAML. Those properties that
    /// are internal are defined in another partial class below.
    /// </comment>
    [ContentProperty("Arguments")]
    public abstract partial class BaseProperty : ISupportInitialize
    {
        #region Fields

        /// <summary>
        /// See DisplayName property.
        /// </summary>
        private string _displayName;

        #endregion

        #region Constructor

        /// <summary>
        /// Default constructor. Needed for deserializtion from a persisted format.
        /// </summary>
        protected BaseProperty()
        {
            // Initialize collection properties in this class. This is required for
            // proper deserialization.
            Metadata = new List<NameValuePair>();
            Arguments = new List<Argument>();
            ValueEditors = new List<ValueEditor>();

            // The default value of Visible.
            Visible = true;

            // The default value of IncludeInCommandLine.
            IncludeInCommandLine = true;

            SwitchPrefix = String.Empty;
            Separator = String.Empty;
            Category = "General";
            Subcategory = String.Empty;

            HelpContext = -1;
            HelpFile = String.Empty;
            HelpUrl = String.Empty;
        }

        #endregion

        #region Properties

        /// <summary>
        /// The name of this <see cref="BaseProperty"/>.
        /// </summary>
        /// <remarks>
        /// This field is mandatory and culture invariant. The value of this field cannot be set to the empty string.
        /// </remarks>
        public string Name
        {
            get;
            set;
        }

        /// <summary>
        /// The name that could be used by a prospective UI client to display this <see cref="BaseProperty"/>.
        /// </summary>
        /// <remarks>
        /// This field is optional and is culture sensitive. When this property is not set, it is assigned the same
        /// value as the <see cref="Name"/> property (and hence, would not be localized).
        /// </remarks>
        [Localizable(true)]
        public string DisplayName
        {
            get
            {
                return _displayName ?? Name;
            }

            set
            {
                _displayName = value;
            }
        }

        /// <summary>
        /// Description of this <see cref="BaseProperty"/> for use by a prospective UI client.
        /// </summary>
        /// <remarks>
        /// This field is optional and is culture sensitive.
        /// </remarks>
        [Localizable(true)]
        public string Description
        {
            get;
            set;
        }

        /// <summary>
        /// The keyword that is used to open the help page for this property.
        /// </summary>
        /// <remarks>
        /// This form of specifying help takes precedence over <see cref="HelpUrl"/>
        /// and <see cref="HelpFile"/> + <see cref="HelpContext"/>.
        /// This field is optional and is culture insensitive.
        /// </remarks>
        [Localizable(false)]
        public string F1Keyword
        {
            get;
            set;
        }

        /// <summary>
        /// The URL of the help page for this property that will be opened when the user hits F1.
        /// </summary>
        /// <remarks>
        /// This property is higher in priority that <see cref="HelpContext"/> + <see cref="HelpFile"/>
        /// (i.e., these two properties are ignored if <see cref="HelpUrl"/>
        /// is specified), but lower in priority than <see cref="F1Keyword"/>.
        /// This field is optional and is culture insensitive.
        /// </remarks>
        /// <example> <c>ms-help://MS.VSCC.v80/MS.MSDN.v80/MS.VisualStudio.v80.en/dv_vstoc/html/06ddebea-2c83-4a45-bb48-6264c797ed93.htm</c> </example>
        [Localizable(false)]
        [SuppressMessage("Microsoft.Design", "CA1056:UriPropertiesShouldNotBeStrings", Justification = "This has shipped in Framework, which is especially important to keep binary compatible, so we can't change it now")]
        public string HelpUrl
        {
            get;
            set;
        }

        /// <summary>
        /// The help file to use when the user hits F1. Must specify <see cref="HelpContext"/> along with this.
        /// </summary>
        /// <remarks>
        /// This property goes along with <see cref="HelpContext"/>. This
        /// form of specifying the help page for a property takes lower precedence than both <see cref="F1Keyword"/>
        /// and <see cref="HelpUrl"/>.
        /// This field is optional and is culture insensitive.
        /// </remarks>
        [Localizable(false)]
        public string HelpFile
        {
            get;
            set;
        }

        /// <summary>
        /// The help context to use when the user hits F1. Must specify <see cref="HelpFile"/> along with this.
        /// </summary>
        /// <remarks>
        /// This property uses the <see cref="HelpFile"/> property to display the help context of the specified
        /// help file. This field is optional. This
        /// form of specifying the help page for a property takes lower precedence than both <see cref="F1Keyword"/>
        /// and <see cref="HelpUrl"/>.
        /// </remarks>
        public int HelpContext
        {
            get;
            set;
        }

        /// <summary>
        /// The name of the category to which this property belongs to.
        /// </summary>
        /// <remarks>
        /// <para>
        /// If the value of this field  does not correspond to the <c>Name</c>
        /// property of a <see cref="Category"/> element defined in
        /// the containing <see cref="Rule"/>, a default <see cref="Category"/> with this name
        /// is auto-generated and added to the containing <see cref="Rule"/> class.
        /// </para>
        /// <para>
        /// This field is optional and is culture invariant.
        /// </para>
        /// <para>
        /// When this field is not specified, this property is added to a
        /// auto-generated category called <c>General</c> (localized). This field cannot be set to the
        /// empty string.
        /// </para>
        /// </remarks>
        public string Category
        {
            get;
            set;
        }

        /// <summary>
        /// The sub category to which this property belongs to.
        /// </summary>
        public string Subcategory
        {
            get;
            set;
        }

        /// <summary>
        /// Tells if this property is a read-only property.
        /// </summary>
        /// <remarks>
        /// This field is optional and its default value is "false".
        /// </remarks>
        public bool ReadOnly
        {
            get;
            set;
        }

        /// <summary>
        /// A value indicating whether this property allows multiple values to be supplied/selected simultaneously.
        /// </summary>
        public bool MultipleValuesAllowed
        {
            get;
            set;
        }

        /// <summary>
        /// The switch representation of this property for the case when this property represents a tool parameter.
        /// </summary>
        /// <remarks>
        /// This field is optional and culture invariant.
        /// </remarks>
        /// <example>
        /// For the VC++ CL task, <c>WholeProgramOptimization</c> is a boolean parameter. It's switch is <c>GL</c>.
        /// </example>
        public string Switch
        {
            get;
            set;
        }

        /// <summary>
        /// The prefix for the switch representation of this property for the case when this property represents a tool parameter.
        /// </summary>
        /// <remarks>
        /// The value specified here overrides the value specified for the parent <see cref="Rule"/>'s <see cref="Rule.SwitchPrefix"/>.
        /// This field is optional and culture invariant.
        /// </remarks>
        /// <example>
        /// For the VC++ CL task, <c>WholeProgramOptimization</c> is a boolean parameter. It's switch is <c>GL</c> and its
        /// switch prefix (inherited from the parent <see cref="Rule.SwitchPrefix"/> since it is not overridden by <c>WholeProgramOptimization</c>)
        /// is <c>/</c>. Thus the complete switch in the command line for this property would be <c>/GL</c>
        /// </example>
        public string SwitchPrefix
        {
            get;
            set;
        }

        /// <summary>
        /// The token used to separate a switch from its value.
        /// </summary>
        /// <remarks>
        /// The value specified here overrides the value specified for the parent <see cref="Rule"/>'s <see cref="Rule.Separator"/>.
        /// This field is optional and culture invariant.
        /// </remarks>
        /// <example>
        /// Example: Consider <c>/D:WIN32</c>. In this switch and value representation, ":" is the separator since its separates the switch <c>D</c>
        /// from its value <c>WIN32</c>.
        /// </example>
        public string Separator
        {
            get;
            set;
        }

        /// <summary>
        /// A hint to the UI client telling it whether to display this property or not.
        /// </summary>
        /// <remarks>
        /// This field is optional and has the default value of "true".
        /// </remarks>
        public bool Visible
        {
            get;
            set;
        }

        /// <summary>
        /// A hint to the command line constructor whether to include this property in the command line or not.
        /// </summary>
        /// <remarks>
        /// Some properties are used only by the targets and don't want to be included in the command line.
        /// Others (like task parameters) are included in the command line in the form of the switch/value they emit.
        /// This field is optional and has the default value of <c>true</c>.
        /// </remarks>
        public bool IncludeInCommandLine
        {
            get;
            set;
        }

        /// <summary>
        /// Indicates whether this property is required to have a value set.
        /// </summary>
        public bool IsRequired
        {
            get;
            set;
        }

        /// <summary>
        /// Specifies the default value for this property.
        /// </summary>
        /// <remarks>
        /// This field is optional and whether, for a <see cref="StringProperty"/>,
        /// it is culture sensitive or not depends on the semantics of it.
        /// </remarks>
        [Localizable(true)]
        public string Default
        {
            get;
            set;
        }

        /// <summary>
        /// The data source where the current value of this property is stored.
        /// </summary>
        /// <remarks>
        /// If defined, it overrides the
        /// <see cref="Rule.DataSource"/> property on the containing <see cref="Rule"/>. This field is mandatory only if the parent
        /// <see cref="Rule"/> does not have the data source initialized. The getter for this property returns
        /// only the <see cref="DataSource"/> set directly on this <see cref="BaseProperty"/> instance.
        /// </remarks>
        public DataSource DataSource
        {
            get;
            set;
        }

        /// <summary>
        /// Additional attributes of this <see cref="BaseProperty"/>.
        /// </summary>
        /// <remarks>
        /// This can be used as a grab bag of additional metadata of this property that are not
        /// captured by the primary fields. You will need a custom UI to interpret the additional
        /// metadata since the shipped UI formats can't obviously know about it.
        /// This field is optional.
        /// </remarks>
        [SuppressMessage("Microsoft.Usage", "CA2227:CollectionPropertiesShouldBeReadOnly", Justification = "This has shipped in Framework, which is especially important to keep binary compatible, so we can't change it now")]
        public List<NameValuePair> Metadata
        {
            get;
            set;
        }

        /// <summary>
        /// List of arguments for this property.
        /// </summary>
        /// <remarks>
        ///  This field is optional.
        /// </remarks>
        [SuppressMessage("Microsoft.Usage", "CA2227:CollectionPropertiesShouldBeReadOnly", Justification = "This has shipped in Framework, which is especially important to keep binary compatible, so we can't change it now")]
        public List<Argument> Arguments
        {
            get;
            set;
        }

        /// <summary>
        /// List of value editors for this property.
        /// </summary>
        /// <remarks>
        /// This field is optional.
        /// </remarks>
        [SuppressMessage("Microsoft.Usage", "CA2227:CollectionPropertiesShouldBeReadOnly", Justification = "This has shipped in Framework, which is especially important to keep binary compatible, so we can't change it now")]
        public List<ValueEditor> ValueEditors
        {
            get;
            set;
        }

        #endregion
    }

    /// <summary>
    /// Represents a <see cref="Rule"/> property.
    /// </summary>
    /// <remarks>
    /// <para>This represents schema information (name, allowed values, etc) of a <see cref="Rule"/> property.
    /// Since this is just schema information, there is no field like "Value" used to get/set the value of this
    /// property.</para>
    /// <para> Those who manually instantiate this class should remember to call <see cref="BeginInit"/> before
    /// setting the first property and <see cref="EndInit"/> after setting the last property of the object.</para>
    /// </remarks>
    /// <comment>
    /// This partial class contains members that are auto-generated, internal, etc. Whereas the
    /// other partial class contains public properties that can be set in XAML.
    /// </comment>
    public abstract partial class BaseProperty : ISupportInitialize
    {
        #region Properties

        /// <summary>
        /// The <see cref="Rule"/> containing this <see cref="BaseProperty"/>.
        /// </summary>
        public Rule ContainingRule
        {
            get;
            internal set;
        }

        #endregion // Properties

        #region ISupportInitialize Members

        /// <summary>
        /// See ISupportInitialize.
        /// </summary>
        public virtual void BeginInit()
        {
        }

        /// <summary>
        /// See ISupportInitialize.
        /// </summary>
        public virtual void EndInit()
        {
        }

        #endregion
    }
}