Cleaning Up UIItem

Cleaning Up UIItem and IUIItem

- Adding Regions for sets of Functionality such as 'Interaction with an
UI Item', 'Properties of an UI Item', etc
- Renamed the RaiseClickEvent to Invoke
- Added code documentation
- Moved some public properties and functions also into the Interface to
get the Interface and implementing class in Synch

- Renamed UIItemEventListener to IUIItemEventListener

Author: dpisanu

src/TestStack.White.UITests/ControlTests/ButtonTests.cs

@@ -35,10 +35,10 @@ public void ThrowsWhenNotFound()
         }
 
         [Test]
-        public void RaiseClickEvent()
+        public void TestInvokePattern()
         {
             var button = MainWindow.Get<Button>("ButtonWithTooltip");
-            button.RaiseClickEvent();
+            button.Invoke();
             Assert.That(button.Text, Is.EqualTo("Clicked"));
         }
     }

src/TestStack.White/Recording/SafeAutomationEventHandler.cs

@@ -11,12 +11,12 @@ public class SafeAutomationEventHandler
     {
         private readonly IUIItem uiItem;
         private readonly Create createUserEvent;
-        private readonly UIItemEventListener eventListener;
+        private readonly IUIItemEventListener eventListener;
         private readonly ILogger logger = CoreAppXmlConfiguration.Instance.LoggerFactory.Create(typeof(SafeAutomationEventHandler));
 
         public delegate UserEvent Create(object[] parameters);
 
-        public SafeAutomationEventHandler(IUIItem uiItem, UIItemEventListener eventListener, Create createUserEvent)
+        public SafeAutomationEventHandler(IUIItem uiItem, IUIItemEventListener eventListener, Create createUserEvent)
         {
             this.uiItem = uiItem;
             this.eventListener = eventListener;

src/TestStack.White/Recording/UIItemEventListener.cs

@@ -2,7 +2,7 @@
 
 namespace TestStack.White.Recording
 {
-    public interface UIItemEventListener
+    public interface IUIItemEventListener
     {
         void EventOccured(UserEvent userEvent);
     }

src/TestStack.White/UIItems/Button.cs

@@ -15,7 +15,7 @@ public Button(AutomationElement automationElement, IActionListener actionListene
             toggleableItem = new ToggleableItem(this);
         }
 
-        public override void HookEvents(UIItemEventListener eventListener)
+        public override void HookEvents(IUIItemEventListener eventListener)
         {
             HookClickEvent(eventListener);
         }

src/TestStack.White/UIItems/CheckBox.cs

@@ -48,7 +48,7 @@ public virtual void UnSelect()
             Checked = false;
         }
 
-        public override void HookEvents(UIItemEventListener eventListener)
+        public override void HookEvents(IUIItemEventListener eventListener)
         {
             handler = delegate
                           {

src/TestStack.White/UIItems/Hyperlink.cs

@@ -17,7 +17,7 @@ public virtual void Click(int xOffset, int yOffset)
             mouse.Click(new Point((int) x, (int) y), actionListener);
         }
 
-        public override void HookEvents(UIItemEventListener eventListener)
+        public override void HookEvents(IUIItemEventListener eventListener)
         {
             HookClickEvent(eventListener);
         }

src/TestStack.White/UIItems/IUIItem.cs

@@ -13,69 +13,220 @@ namespace TestStack.White.UIItems
 {
     public interface IUIItem : IActionListener
     {
+        #region Automation
+
         /// <summary>
         /// Should be used only if white doesn't support the feature you are looking for.
         /// Knowledge of UIAutomation would be required. It would better idea to also raise an issue if you are using it.
         /// </summary>
         AutomationElement AutomationElement { get; }
 
-        bool Enabled { get; }
+        /// <summary>
+        /// The <see cref="WindowsFramework"/> of the UI Item
+        /// </summary>
         WindowsFramework Framework { get; }
-        Point Location { get; }
-        Rect Bounds { get; }
+
+        /// <summary>
+        /// The <see cref="IActionListener"/> of the UI Item
+        /// </summary>
+        IActionListener ActionListener { get; }
+
+        /// <summary>
+        /// Uses the Raw View provided by UIAutomation to find elements within this UIItem. 
+        /// RawView sometimes contains extra AutomationElements. 
+        /// This is internal to white although made public. 
+        /// Should be used only if the standard approaches dont work. 
+        /// Also if you end up using it please raise an issue so that it can be fixed.
+        /// Please understand that calling this method on any UIItem,
+        /// which has a lot of child AutomationElements might result in very bad performance.
+        /// </summary>
+        /// <param name="searchCriteria"></param>
+        /// <returns>null or found AutomationElement</returns>
+        AutomationElement GetElement(SearchCriteria searchCriteria);
+
+        #endregion
+
+        #region State Properties
+
+        /// <summary>
+        /// Is UI Item Enabled
+        /// </summary>
+        bool Enabled { get; }
+
+        /// <summary>
+        /// Is UI Item Off Screen
+        /// </summary>
+        bool IsOffScreen { get; }
+
+        /// <summary>
+        /// Is UI Item Visible
+        /// </summary>
+        bool Visible { get; }
+
+        /// <summary>
+        /// Is UI Item Focussed
+        /// </summary>
+        bool IsFocussed { get; }
+
+        /// <summary>
+        /// The Status of the UI Item
+        /// </summary>
+        string ItemStatus { get; }
+
+        /// <summary>
+        /// Name of the UI Item
+        /// </summary>
         string Name { get; }
-        Point ClickablePoint { get; }
-        string AccessKey { get; }
+
+        /// <summary>
+        /// ID of the UI Item
+        /// </summary>
         string Id { get; }
-        bool Visible { get; }
+
+        /// <summary>
+        /// Primary Identification of the UI Item
+        /// </summary>
         string PrimaryIdentification { get; }
-        IActionListener ActionListener { get; }
+
+        /// <summary>
+        /// Access Key of the UI Item
+        /// </summary>
+        string AccessKey { get; }
+
+        /// <summary>
+        /// HelpText of the UI Item
+        /// </summary>
+        string HelpText { get; }
+
+        /// <summary>
+        /// <see cref="IScrollBars"/> of the UI Item
+        /// </summary>
         IScrollBars ScrollBars { get; }
-        bool IsOffScreen { get; }
-        bool IsFocussed { get; }
+
+        #endregion
+
+        #region Dimension Properties
+
+        /// <summary>
+        /// <see cref="Point"/> location of the UI Item
+        /// </summary>
+        Point Location { get; }
+
+        /// <summary>
+        /// <see cref="Rect"/> Bounds of the UI Item
+        /// </summary>
+        Rect Bounds { get; }
+
+        /// <summary>
+        /// <see cref="Point"/> ClickablePoint of the UI Item
+        /// </summary>
+        Point ClickablePoint { get; }
+
+        #endregion
+
+        #region Graphics
+
+        /// <summary>
+        /// <see cref="Color"/> of the UI Item Border
+        /// </summary>
         Color BorderColor { get; }
+
+        /// <summary>
+        /// <see cref="Bitmap"/> representing the VisibleImage of the UI Item
+        /// </summary>
         Bitmap VisibleImage { get; }
-        bool ValueOfEquals(AutomationProperty property, object compareTo);
-        void RightClickAt(Point point);
-        void RightClick();
+
+        /// <summary>
+        /// Draw a Highlighting around the UI Item in the Color <see cref="Color.Red"/>
+        /// </summary>
+        void DrawHighlight();
+
+        /// <summary>
+        /// Draw a Highlighting around the UI Item in a specific color
+        /// </summary>
+        /// <param name="color">Color of the Highlighting</param>
+        void DrawHighlight(Color color);
+
+        /// <summary>
+        /// Capture a <see cref="Bitmap"/> image of the UI Item
+        /// </summary>
+        Bitmap Capture();
+
+        #endregion
+
+        #region Interaction
+
+        /// <summary>
+        /// Focus the UI Item
+        /// </summary>
         void Focus();
 
         /// <summary>
-        /// An alternative to use instead of Focus, might sometimes be more reliable
+        /// Bring the UI Item to the Foreground
         /// </summary>
+        /// <remarks>
+        /// An alternative to use instead of Focus, might sometimes be more reliable
+        /// </remarks>
         void SetForeground();
-
+        
+        /// <summary>
+        /// Visit the UI Item
+        /// </summary>
+        /// <param name="windowControlVisitor">Window Control Visitor</param>
         void Visit(IWindowControlVisitor windowControlVisitor);
 
         /// <summary>
-        /// Provides the Error on this UIItem. 
-        /// This would return Error object when this item has ErrorProvider displayed next to it.
+        /// Performs an Invoke on the <see cref="InvokePattern"/> Pattern of the UI Item
         /// </summary>
-        /// <param name="window"></param>
-        /// <returns></returns>
-        string ErrorProviderMessage(Window window);
-
-        bool NameMatches(string text);
+        /// <remarks>
+        /// This is faster then a <see cref="Click()"/> on the UI Item.
+        /// Can have some side effects that certain Click Events are bypassed.
+        /// </remarks>
+        void Invoke();
 
         /// <summary>
-        /// Performs mouse click at the center of this item
+        /// Performs mouse click at the center of the UI Item
         /// </summary>
         void Click();
 
         /// <summary>
-        /// Performs mouse double click at the center of this item
+        /// Performs mouse double click at the center of the UI Item
         /// </summary>
         void DoubleClick();
 
         /// <summary>
-        ///Perform keyboard action on this UIItem
+        /// Performs a right mouse click at the center of the UI Item
+        /// </summary>
+        void RightClick();
+
+        /// <summary>
+        /// Performas a right mouse click at a defined <remarks>Point</remarks>
+        /// </summary>
+        /// <param name="point">Point to mouse right click</param>
+        void RightClickAt(Point point);
+
+        /// <summary>
+        ///Perform keyboard action on this UI Item
         /// </summary>
         /// <param name="key"></param>
         void KeyIn(KeyboardInput.SpecialKeys key);
 
-        bool Equals(object obj);
-        int GetHashCode();
-        string ToString();
+        /// <summary>
+        /// Sets a value on this UI Item
+        /// </summary>
+        /// <param name="value">Value to set</param>
+        void SetValue(object value);
+
+        /// <summary>
+        /// Enter a value on this UI Item
+        /// </summary>
+        /// <param name="value">Value to enter</param>
+        /// <remarks>The <see cref="ValuePattern"/> must be supported by the UI Item for this to work</remarks>
+        void Enter(string value);
+
+        #endregion
+
+        #region Recording
 
         /// <summary>
         /// Internal to white and intended to be used for white recording
@@ -86,32 +237,63 @@ public interface IUIItem : IActionListener
         /// Internal to white and intended to be used for white recording
         /// </summary>
         /// <param name="eventListener"></param>
-        void HookEvents(UIItemEventListener eventListener);
+        void HookEvents(IUIItemEventListener eventListener);
 
-        void SetValue(object value);
+        #endregion
+
+        #region Debugging
+
+        /// <summary>
+        /// Provides the Error on this UIItem. 
+        /// This would return Error object when this item has ErrorProvider displayed next to it.
+        /// </summary>
+        /// <param name="window"></param>
+        /// <returns></returns>
+        string ErrorProviderMessage(Window window);
+
+        /// <summary>
+        /// Log Structure of the UI Item
+        /// </summary>
         void LogStructure();
 
+        #endregion
+
+        #region Equality
+
         /// <summary>
-        /// Uses the Raw View provided by UIAutomation to find elements within this UIItem. 
-        /// RawView sometimes contains extra AutomationElements. 
-        /// This is internal to white although made public. 
-        /// Should be used only if the standard approaches dont work. 
-        /// Also if you end up using it please raise an issue so that it can be fixed.
-        /// Please understand that calling this method on any UIItem,
-        /// which has a lot of child AutomationElements might result in very bad performance.
+        /// Check if the UI Item name matches a given name
         /// </summary>
-        /// <param name="searchCriteria"></param>
-        /// <returns>null or found AutomationElement</returns>
-        AutomationElement GetElement(SearchCriteria searchCriteria);
+        /// <param name="text">Name Value to match against</param>
+        /// <returns>Returns <c>true</c> if matches, else <c>false</c></returns>
+        bool NameMatches(string text);
 
-        void Enter(string value);
+        /// <summary>
+        /// Compare the <see cref="AutomationProperty"/> from the UI Item against an object
+        /// </summary>
+        /// <param name="property">The <see cref="AutomationProperty"/> value to compare to</param>
+        /// <param name="compareTo">The object to compare it to</param>
+        /// <returns>Returns <c>true</c> if matches, else <c>false</c></returns>
+        bool ValueOfEquals(AutomationProperty property, object compareTo);
 
-        void DrawHighlight();
-        void DrawHighlight(Color color);
+        /// <summary>
+        /// CHeck if the UI Item equals an object
+        /// </summary>
+        /// <param name="obj">Object to compare to</param>
+        /// <returns>Returns <c>true</c> if matches, else <c>false</c></returns>
+        bool Equals(object obj);
 
         /// <summary>
-        /// Captures an image of the element
+        /// Get the HashCode of the UI Item
         /// </summary>
-        Bitmap Capture();
+        /// <returns>The HashCode of the UI Item</returns>
+        int GetHashCode();
+        
+        /// <summary>
+        /// ToString overload for the UI Item
+        /// </summary>
+        /// <returns>The String representation of the UI Item</returns>
+        string ToString();
+
+        #endregion
     }
 }