// 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.ComponentModel;

#nullable disable

namespace Microsoft.Build.Framework.XamlTypes
{
    /// <summary>
    /// Indicates where the default value for some property may be found.
    /// </summary>
    public enum DefaultValueSourceLocation
    {
        /// <summary>
        /// The default value for a property is set at the top of the project file (usually via an import of a .props file).
        /// </summary>
        BeforeContext,

        /// <summary>
        /// The default value for a property is set at the bottom of the project file (usually via an import of a .targets file,
        /// where the property definition is conditional on whether the property has not already been defined.)
        /// </summary>
        AfterContext,
    }

    /// <summary>
    /// Represents the location and grouping for a <see cref="BaseProperty"/>.
    /// </summary>
    /// <remarks>
    /// 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.
    /// </remarks>
    public sealed class DataSource : ISupportInitialize
    {
        #region Constructor

        /// <summary>
        /// Default constructor. Needed for proper XAML deserialization.
        /// </summary>
        public DataSource()
        {
            // Set the default value for this property.
            HasConfigurationCondition = true;
            Label = String.Empty;
            SourceOfDefaultValue = DefaultValueSourceLocation.BeforeContext;
        }

        #endregion

        #region Properties

        /// <summary>
        /// The storage location for this data source.
        /// </summary>
        /// <remarks>
        /// This field is mandatory unless <see cref="PersistenceStyle"/> is set. In that case, the parent
        /// <see cref="DataSource"/> will be used with the specified style. Example values are <c>ProjectFile</c> and
        /// <c>UserFile</c>. <c>ProjectFile</c> causes the property value to be written to and read from the project
        /// manifest file or the property sheet (depending on which node in the solution explorer/property manager window
        /// is used to spawn the property pages UI). <c>UserFile</c> causes the property value to be written to and read
        /// from the .user file.
        /// </remarks>
        public string Persistence
        {
            get;
            set;
        }

        /// <summary>
        /// The storage style for this data source.
        /// </summary>
        /// <remarks>
        /// For example, with <see cref="Persistence"/> of <c>ProjectFile</c>, this field can be <c>Element</c> (default) to
        /// save as a child XML Element, or <c>Attribute</c> to save properties as an XML attribute.
        /// </remarks>
        public string PersistenceStyle
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the actual MSBuild property name used to read/write the value of this property.
        /// Applicable only to <see cref="DataSource"/> objects attached to properties.
        /// </summary>
        /// <value>The MSBuild property name to use; or <c>null</c> to use the <see cref="BaseProperty.Name"/> as the MSBuild property name.</value>
        /// <remarks>
        /// <para>The persisted name will usually be the same as the property name as it appears in the <see cref="Rule"/>
        /// and the value of this property can therefore be left at is default of <c>null</c>.
        /// Since property names must be unique but need not be unique in the persisted store (due to other differences
        /// in the data source such as item type) there may be times when Rule property names must be changed to be
        /// unique in the XAML file, but without changing how the property is persisted in the MSBuild file.
        /// It is in those cases where this property becomes useful.</para>
        /// <para>It may also be useful in specialized build environments where property names must differ from the
        /// normally used name in order to maintain compatibility with the project system.</para>
        /// </remarks>
        public string PersistedName
        {
            get;
            set;
        }

        /// <summary>
        /// The label of the MSBuild property group/item definition group to which
        /// a property/item definition metadata belongs to. Default value is the
        /// empty string.
        /// </summary>
        /// <example> A VC++ property that exists in the project manifest
        /// in the MSBuild property group with label <c>Globals</c> would have this
        /// same value for this field. </example>
        public string Label
        {
            get;
            set;
        }

        /// <summary>
        /// If a <see cref="BaseProperty"/> is an item definition metadata or item metadata, this field
        /// specified the item type of the item definition or the item, respectively. For common properties
        /// this field must not be set.
        /// </summary>
        public string ItemType
        {
            get;
            set;
        }

        /// <summary>
        /// Indicates if a property is configuration-dependent as indicated by the presence of a configuration
        /// condition attached to the property definition at its persistence location.
        /// </summary>
        /// <remarks>
        /// This field is optional and has the default value of <c>true</c>.
        /// </remarks>
        public bool HasConfigurationCondition
        {
            get;
            set;
        }

        /// <summary>
        /// The data type of the source.  Generally one of <c>Item</c>, <c>ItemDefinition</c>, <c>Property</c>,
        /// or <c>TargetResults</c> (when <see cref="MSBuildTarget"/> is non-empty).
        /// Among other things this governs how the data is treated during build.
        /// </summary>
        /// <example>
        /// A value of <c>Item</c> for this property indicates that this property is actually
        /// an item array - the list of all items with the item type specified by <see cref="ItemType"/>.
        /// </example>
        public string SourceType
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets the semicolon-delimited list of MSBuild targets that must be executed before reading
        /// the read-only properties or items described by this <see cref="DataSource"/>.
        /// </summary>
        public string MSBuildTarget
        {
            get;
            set;
        }

        /// <summary>
        /// Gets or sets a value indicating where the default value for this property can be found.
        /// </summary>
        public DefaultValueSourceLocation SourceOfDefaultValue
        {
            get;
            set;
        }

        #endregion // Properties

        #region ISupportInitialize Members

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

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

        #endregion
    }
}
