Imported Upstream version 4.6.0.125

Former-commit-id: a2155e9bd80020e49e72e86c44da02a8ac0e57a4

mcs/class/referencesource/System.Web/UI/WebControls/BaseDataBoundControl.cs

@@ -0,0 +1,287 @@
+//------------------------------------------------------------------------------
+// <copyright file="BaseDataBoundControl.cs" company="Microsoft">
+//     Copyright (c) Microsoft Corporation.  All rights reserved.
+// </copyright>
+//------------------------------------------------------------------------------
+
+namespace System.Web.UI.WebControls {
+
+    using System;
+    using System.Collections;
+    using System.ComponentModel;
+    using System.Web.Util;
+
+    /// <summary>
+    /// A BaseDataBoundControl is bound to a data source and generates its
+    /// user interface (or child control hierarchy typically), by enumerating
+    /// the items in the data source it is bound to.
+    /// BaseDataBoundControl is an abstract base class that defines the common
+    /// characteristics of all controls that use a list as a data source, such as
+    /// DataGrid, DataBoundTable, ListBox etc. It encapsulates the logic
+    /// of how a data-bound control binds to collections or DataControl instances.
+    /// </summary>
+
+    [
+    Designer("System.Web.UI.Design.WebControls.BaseDataBoundControlDesigner, " + AssemblyRef.SystemDesign),
+    DefaultProperty("DataSourceID")
+    ]
+    public abstract class BaseDataBoundControl : WebControl {
+
+        private static readonly object EventDataBound = new object();
+
+        private object _dataSource;
+        private bool _requiresDataBinding;
+        private bool _inited;
+        private bool _preRendered;
+        private bool _requiresBindToNull;
+        private bool _throwOnDataPropertyChange;
+
+
+        /// <summary>
+        /// The data source to bind to. This allows a BaseDataBoundControl to bind
+        /// to arbitrary lists of data items.
+        /// </summary>
+        [
+        Bindable(true),
+        DefaultValue(null),
+        DesignerSerializationVisibility(DesignerSerializationVisibility.Hidden),
+        Themeable(false),
+        WebCategory("Data"),
+        WebSysDescription(SR.BaseDataBoundControl_DataSource),
+        ]
+        public virtual object DataSource {
+            get {
+                return _dataSource;
+            }
+            set {
+                if (value != null) {
+                    ValidateDataSource(value);
+                }
+                _dataSource = value;
+                OnDataPropertyChanged();
+            }
+        }
+
+
+        /// <summary>
+        /// The ID of the DataControl that this control should use to retrieve
+        /// its data source. When the control is bound to a DataControl, it
+        /// can retrieve a data source instance on-demand, and thereby attempt
+        /// to work in auto-DataBind mode.
+        /// </summary>
+        [
+        DefaultValue(""),
+        Themeable(false),
+        WebCategory("Data"),
+        WebSysDescription(SR.BaseDataBoundControl_DataSourceID)
+        ]
+        public virtual string DataSourceID {
+            get {
+                object o = ViewState["DataSourceID"];
+                if (o != null) {
+                    return (string)o;
+                }
+                return String.Empty;
+            }
+            set {
+                if (String.IsNullOrEmpty(value) && !String.IsNullOrEmpty(DataSourceID)) {
+                    _requiresBindToNull = true;
+                }
+
+                ViewState["DataSourceID"] = value;
+                OnDataPropertyChanged();
+            }
+        }
+
+
+        protected bool Initialized {
+            get {
+                return _inited;
+            }
+        }
+
+        /// <summary>
+        /// Returns true if the DataBoundControl uses Select/Update/Delete/Insert Methods for databinding. 
+        /// Implementation on BaseDataBoundControl returns false.
+        /// Override in child classes which support the above two properties.
+        /// </summary>
+        protected virtual bool IsUsingModelBinders {
+           get {
+               return false;
+           }
+        }
+
+        /// <summary>
+        /// This returns true only if the DataBoundControl is using a DataSourceID.
+        /// Use the IsDataBindingAutomatic property to determine if the data bound control's data binding is
+        /// automatic. The data binding is automatic if the control is using a DataSourceID or if control
+        /// uses Select/Update/Delete/Insert Methods for data binding.
+        /// </summary>
+        protected bool IsBoundUsingDataSourceID {
+            get {
+                return (DataSourceID.Length > 0);
+            }
+        }
+
+        /// <summary>
+        /// This property is used by FormView/GridView/DetailsView/ListView in the following scenarios.
+        /// 1. Perform an auto data bind (Listen to OnDataSourceViewChanged event and set RequiresDataBinding to true)
+        /// 2. Calling the data source view operations
+        /// 3. Raising exceptions when there is no DataSourceId (i.e., a DataSource is in use) and an event for Data Operation is not handled
+        /// 4. Raising the ModeChanged events for DataControls
+        /// This property is true if the control is bound using a DataSourceId or when the control participates in Model Binding.
+        /// </summary>
+        protected internal bool IsDataBindingAutomatic {
+            get {
+                return IsBoundUsingDataSourceID || IsUsingModelBinders;
+            }
+        }
+
+        public override bool SupportsDisabledAttribute {
+            get {
+                return RenderingCompatibility < VersionUtil.Framework40;
+            }
+        }
+
+        protected bool RequiresDataBinding {
+            get {
+                return _requiresDataBinding;
+            }
+            set {
+                // if we have to play catch-up here because we've already PreRendered, call EnsureDataBound
+                if (value && _preRendered && IsDataBindingAutomatic && Page != null && !Page.IsCallback) {
+                    _requiresDataBinding = true;
+                    EnsureDataBound();
+                }
+                else {
+                    _requiresDataBinding = value;
+                }
+            }
+        }
+
+
+        [
+        WebCategory("Data"),
+        WebSysDescription(SR.BaseDataBoundControl_OnDataBound)
+        ]
+        public event EventHandler DataBound {
+            add {
+                Events.AddHandler(EventDataBound, value);
+            }
+            remove {
+                Events.RemoveHandler(EventDataBound, value);
+            }
+        }
+
+        protected void ConfirmInitState() {
+            _inited = true; // do this in OnLoad in case we were added to the page after Page.OnPreLoad
+        }
+
+
+        /// <summary>
+        /// Overriden by BaseDataBoundControl to use its properties to determine the real
+        /// data source that the control should bind to. It then clears the existing
+        /// control hierarchy, and calls CreateChildControls to create a new control
+        /// hierarchy based on the resolved data source.
+        /// The implementation resolves various data source related properties to
+        /// arrive at the appropriate IEnumerable implementation to use as the real
+        /// data source.
+        /// When resolving data sources, the DataSourceID takes highest precedence.
+        /// If DataSourceID is not set, the value of the DataSource property is used.
+        /// In this second alternative, DataMember is used to extract the appropriate
+        /// list if the control has been handed an IListSource as a data source.
+        ///
+        /// Data bound controls should override PerformDataBinding instead
+        /// of DataBind.  If DataBind if overridden, the OnDataBinding and OnDataBound events will
+        /// fire in the wrong order.  However, for backwards compat on ListControl and AdRotator, we 
+        /// can't seal this method.  It is sealed on all new BaseDataBoundControl-derived controls.
+        /// </summary>
+        public override void DataBind() {
+            // Don't databind when the control is in the designer but not top-level
+            if (DesignMode) {
+                IDictionary designModeState = GetDesignModeState();
+                if (((designModeState == null) || (designModeState["EnableDesignTimeDataBinding"] == null))
+                    && (Site == null)) {
+                    return;
+                }
+            }
+
+            PerformSelect();
+        }
+
+
+        protected virtual void EnsureDataBound() {
+            try {
+                _throwOnDataPropertyChange = true;
+                if (RequiresDataBinding && (IsDataBindingAutomatic || _requiresBindToNull)) {
+                    DataBind();
+                    _requiresBindToNull = false;
+                }
+            }
+            finally {
+                _throwOnDataPropertyChange = false;
+            }
+        }
+
+        internal void InternalEnsureDataBound() {
+            EnsureDataBound();
+        }
+
+
+        protected virtual void OnDataBound(EventArgs e) {
+            EventHandler handler = Events[EventDataBound] as EventHandler;
+            if (handler != null) {
+                handler(this, e);
+            }
+        }
+
+
+        /// <devdoc>
+        ///  This method is called when DataMember, DataSource, or DataSourceID is changed.
+        /// </devdoc>
+        protected virtual void OnDataPropertyChanged() {
+            if (_throwOnDataPropertyChange) {
+                throw new HttpException(SR.GetString(SR.DataBoundControl_InvalidDataPropertyChange, ID));
+            }
+            if (_inited) {
+                RequiresDataBinding = true;
+            }
+        }
+
+
+        protected internal override void OnInit(EventArgs e) {
+            base.OnInit(e);
+
+            if (Page != null) {
+                Page.PreLoad += new EventHandler(this.OnPagePreLoad);
+                
+                if (!IsViewStateEnabled && Page.IsPostBack) {
+                    RequiresDataBinding = true;
+                }
+            }
+        }
+
+        protected virtual void OnPagePreLoad(object sender, EventArgs e) {
+            _inited = true;
+            if (Page != null) {
+                Page.PreLoad -= new EventHandler(this.OnPagePreLoad);
+            }
+        }
+
+
+        protected internal override void OnPreRender(EventArgs e) {
+            _preRendered = true;
+            EnsureDataBound();
+            base.OnPreRender(e);
+        }
+        
+        /// <summary>
+        /// Override to control how the data is selected and the control is databound.
+        /// </summary>
+        protected abstract void PerformSelect();
+
+
+        protected abstract void ValidateDataSource(object dataSource);
+    }
+}
+