[GenGrid|GenGridItem|GenItem|GenItemClass]Add Comments.
authorQian Sui <qian.sui@samsung.com>
Fri, 17 Mar 2017 02:28:21 +0000 (10:28 +0800)
committerQian Sui <qian.sui@samsung.com>
Mon, 20 Mar 2017 06:00:02 +0000 (14:00 +0800)
Change-Id: Ie9b8f87b646aa3ab0d2099ca6eff05c9a6d0b5dc
Signed-off-by: Qian Sui <qian.sui@samsung.com>
src/ElmSharp/ElmSharp/GenGrid.cs [changed mode: 0644->0755]
src/ElmSharp/ElmSharp/GenGridItem.cs [changed mode: 0644->0755]
src/ElmSharp/ElmSharp/GenItem.cs [changed mode: 0644->0755]
src/ElmSharp/ElmSharp/GenItemClass.cs [changed mode: 0644->0755]

old mode 100644 (file)
new mode 100755 (executable)
index fe7b2d0..2d22658
@@ -19,16 +19,43 @@ using System.Collections.Generic;
 
 namespace ElmSharp
 {
+    /// <summary>
+    /// Enumeration for setting selection mode for GenGird.
+    /// </summary>
     public enum GenGridSelectionMode
     {
+        /// <summary>
+        /// The item will only call their selection func and callback when first becoming selected.
+        /// Any further clicks will do nothing, unless you set Always select mode.
+        /// </summary>
         Default = 0,
+        /// <summary>
+        /// This means that, even if selected, every click will make the selected callbacks be called.
+        /// </summary>
         Always,
+        /// <summary>
+        /// This will turn off the ability to select the item entirely and they will neither appear selected nor call selected callback functions.
+        /// </summary>
         None,
+        /// <summary>
+        /// This will apply no-finger-size rule with DisplayOnly.
+        /// No-finger-size rule makes an item can be smaller than lower limit.
+        /// Clickable objects should be bigger than human touch point device (your finger) for some touch or small screen devices.
+        /// So it is enabled, the item can be shrink than predefined finger-size value. And the item will be updated.
+        /// </summary>
         DisplayOnly,
     }
 
+    /// <summary>
+    /// It inherits System.EventArgs.
+    /// It contains Item which is <see cref="GenGridItem"/> type.
+    /// All events of GenGrid contain GenGridItemEventArgs as a parameter.
+    /// </summary>
     public class GenGridItemEventArgs : EventArgs
     {
+        /// <summary>
+        /// Gets or sets GenGrid item.The return type is <see cref="GenGridItem"/>.
+        /// </summary>
         public GenGridItem Item { get; set; }
 
         internal static GenGridItemEventArgs CreateFromSmartEvent(IntPtr data, IntPtr obj, IntPtr info)
@@ -38,6 +65,12 @@ namespace ElmSharp
         }
     }
 
+    /// <summary>
+    /// It inherits <see cref="Layout"/>.
+    /// The GenGrid is a widget that aims to position objects in a grid layout while actually creating and rendering only the visible ones.
+    /// It has two direction in which a given GenGrid widget expands while placing its items, horizontal and vertical.
+    /// The GenGrid items are represented through <see cref="GenItemClass"/> definition field details.
+    /// </summary>
     public class GenGrid : Layout
     {
         HashSet<GenGridItem> _children = new HashSet<GenGridItem>();
@@ -52,21 +85,65 @@ namespace ElmSharp
         SmartEvent<GenGridItemEventArgs> _unrealized;
         SmartEvent<GenGridItemEventArgs> _longpressed;
 
+        /// <summary>
+        /// Creates and initializes a new instance of the GenGrid class.
+        /// </summary>
+        /// <param name="parent">The parent is a given container which will be attached by GenGrid as a child. It's <see cref="EvasObject"/> type.</param>
         public GenGrid(EvasObject parent) : base(parent)
         {
             InitializeSmartEvent();
         }
 
+        /// <summary>
+        /// ItemSelected is raised when a new gengrid item is selected.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemSelected;
+
+        /// <summary>
+        /// ItemUnselected is raised when the gengrid item is Unselected.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemUnselected;
+
+        /// <summary>
+        /// ItemPressed is raised when a new gengrid item is pressed.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemPressed;
+
+        /// <summary>
+        /// ItemReleased is raised when a new gengrid item is released.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemReleased;
+
+        /// <summary>
+        /// ItemActivated is raised when a new gengrid item is double clicked or pressed (enter|return|spacebar).
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemActivated;
+
+        /// <summary>
+        /// ItemDoubleClicked is raised when a new gengrid item is double clicked.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemDoubleClicked;
+
+        /// <summary>
+        /// ItemRealized is raised when a gengrid item is implementing through <see cref="GenItemClass"/>.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemRealized;
+
+        /// <summary>
+        /// ItemUnrealized is raised when the gengrid item is deleted.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemUnrealized;
+
+        /// <summary>
+        /// ItemLongPressed is raised when a gengrid item is pressed for a certain amount of time. By default it's 1 second.
+        /// </summary>
         public event EventHandler<GenGridItemEventArgs> ItemLongPressed;
 
+        /// <summary>
+        /// Gets or sets the item's grid alignment along x-axis within a given gengrid widget.
+        /// The range is less than or equal to 1,and greater than or equal to 0.
+        /// By default, value is 0.5, meaning that the gengrid has its items grid placed exactly in the middle along x-axis.
+        /// </summary>
         public double ItemAlignmentX
         {
             get
@@ -82,6 +159,11 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets the item's grid alignment on y-axis within a given gengrid widget.
+        /// The range is less than or equal to 1, and greater than or equal to 0.
+        /// By default, value is 0.5, meaning that the gengrid has its items grid placed exactly in the middle along y-axis.
+        /// </summary>
         public double ItemAlignmentY
         {
             get
@@ -97,6 +179,10 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets the manner in which the items grid is filled within a given gengrid widget.
+        /// It is filled if true, otherwise false.
+        /// </summary>
         public bool FillItems
         {
             get
@@ -109,6 +195,15 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets whether multi-selection is enabled or disabled for a given gengrid widget.
+        /// </summary>
+        /// <remarks>
+        /// Multi-selection is the ability to have more than one item selected, on a given gengrid, simultaneously.
+        /// When it is enabled, a sequence of clicks on different items makes them all selected, progressively.
+        /// A click on an already selected item unselects it. If interacting via the keyboard, multi-selection is enabled while holding the "Shift" key.
+        /// By default, multi-selection is disabled.
+        /// </remarks>
         public bool MultipleSelection
         {
             get
@@ -121,6 +216,14 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets the width for the items of a given gengrid widget.
+        /// </summary>
+        /// <remarks>
+        /// A gengrid, after creation, still has no information on the size to give to each of its cells.
+        /// The default width and height just have one finger wide.
+        /// Use this property to force a custom width for your items, making them as big as you wish.
+        /// </remarks>
         public int ItemWidth
         {
             get
@@ -137,6 +240,14 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets the height for the items of a given gengrid widget.
+        /// </summary>
+        /// <remarks>
+        /// A gengrid, after creation, still has no information on the size to give to each of its cells.
+        /// The default width and height just have one finger wide.
+        /// Use this property to force a custom height for your items, making them as big as you wish.
+        /// </remarks>
         public int ItemHeight
         {
             get
@@ -152,6 +263,9 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets the gengrid select mode by <see cref="GenGridSelectionMode"/>.
+        /// </summary>
         public GenGridSelectionMode SelectionMode
         {
             get
@@ -164,6 +278,13 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets the direction for which a given gengrid widget expands while placing its items.
+        /// </summary>
+        /// <remarks>
+        /// If true, items are placed in columns from top to bottom and when the space for a column is filled, another one is started on the right, thus expanding the grid horizontally.
+        /// If false, items are placed in rows from left to right, and when the space for a row is filled, another one is started below, thus expanding the grid vertically.
+        /// </remarks>
         public bool IsHorizontal
         {
             get
@@ -176,6 +297,9 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Gets or sets whether the gengrid items should be highlighted when an item is selected.
+        /// </summary>
         public bool IsHighlight
         {
             get
@@ -188,6 +312,14 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Appends a new item to a given gengrid widget. This adds an item to the end of the gengrid.
+        /// </summary>
+        /// <param name="itemClass">The itemClass defines how to display the data.</param>
+        /// <param name="data">The item data.</param>
+        /// <returns>Return a gengrid item that contains data and itemClass.</returns>
+        /// <seealso cref="GenItemClass"/>
+        /// <seealso cref="GenGridItem"/>
         public GenGridItem Append(GenItemClass itemClass, object data)
         {
             GenGridItem item = new GenGridItem(data, itemClass);
@@ -197,6 +329,14 @@ namespace ElmSharp
             return item;
         }
 
+        /// <summary>
+        /// Prepends a new item to a given gengrid widget. This adds an item to the beginning of the gengrid.
+        /// </summary>
+        /// <param name="itemClass">The itemClass defines how to display the data.</param>
+        /// <param name="data">The item data.</param>
+        /// <returns>Return a gengrid item that contains data and itemClass.</returns>
+        /// <seealso cref="GenItemClass"/>
+        /// <seealso cref="GenGridItem"/>
         public GenGridItem Prepend(GenItemClass itemClass, object data)
         {
             GenGridItem item = new GenGridItem(data, itemClass);
@@ -206,6 +346,15 @@ namespace ElmSharp
             return item;
         }
 
+        /// <summary>
+        /// Inserts an item before another in a gengrid widget. This inserts an item before another in the gengrid.
+        /// </summary>
+        /// <param name="itemClass">The itemClass defines how to display the data.</param>
+        /// <param name="data">The item data.</param>
+        /// <param name="before">The item before which to place this new one.</param>
+        /// <returns>Return a gengrid item that contains data and itemClass./></returns>
+        /// <seealso cref="GenItemClass"/>
+        /// <seealso cref="GenGridItem"/>
         public GenGridItem InsertBefore(GenItemClass itemClass, object data, GenGridItem before)
         {
             GenGridItem item = new GenGridItem(data, itemClass);
@@ -215,6 +364,17 @@ namespace ElmSharp
             return item;
         }
 
+        /// <summary>
+        /// Shows a given item to the visible area of a gengrid.
+        /// </summary>
+        /// <param name="item">The gengrid item to display.</param>
+        /// <param name="position">The position of the item in the viewport.</param>
+        /// <param name="animated">The type of how to show the item.</param>
+        /// <remarks>
+        /// If animated is true, the gengrid shows item by scrolling if it's not fully visible.
+        /// If animated is false, the gengrid shows item by jumping if it's not fully visible.
+        /// </remarks>
+        /// <seealso cref="ScrollToPosition"/>
         public void ScrollTo(GenGridItem item, ScrollToPosition position, bool animated)
         {
             if (animated)
@@ -227,11 +387,26 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Updates the contents of all the realized items.
+        /// This updates all realized items by calling all the <see cref="GenItemClass"/> again to get the content, text, and states.
+        /// Use this when the original item data has changed and the changes are desired to reflect.
+        /// </summary>
+        /// <remarks>
+        /// <see cref="GenItem.Update()"/> to update just one item.
+        /// </remarks>
         public void UpdateRealizedItems()
         {
             Interop.Elementary.elm_gengrid_realized_items_update(RealHandle);
         }
 
+        /// <summary>
+        /// Removes all items from a given gengrid widget.
+        /// This removes(and deletes) all items in obj, making it empty.
+        /// </summary>
+        /// <remarks>
+        /// <see cref="ItemObject.Delete()"/> to delete just one item.
+        /// </remarks>
         public void Clear()
         {
             Interop.Elementary.elm_gengrid_clear(RealHandle);
old mode 100644 (file)
new mode 100755 (executable)
index fc79f0b..1ce34cd
@@ -18,12 +18,25 @@ using System;
 
 namespace ElmSharp
 {
+    /// <summary>
+    /// It inherits <see cref="GenItem"/>.
+    /// A instance to the gengrid item added.
+    /// It contains Update() method to update a gengrid item which is given.
+    /// </summary>
     public class GenGridItem : GenItem
     {
         internal GenGridItem(object data, GenItemClass itemClass) : base(data, itemClass)
         {
         }
 
+        /// <summary>
+        /// Gets or sets whether a given gengrid item is selected.
+        /// If one gengrid item is selected, any other previously selected items get unselected in favor of this new one.
+        /// </summary>
+        /// <remarks>
+        /// If true, it is selected.
+        /// If false, it is unselected.
+        /// </remarks>
         public override bool IsSelected
         {
             get
@@ -36,6 +49,14 @@ namespace ElmSharp
             }
         }
 
+        /// <summary>
+        /// Updates the content of a given gengrid item.
+        /// This updates an item by calling all the genitem class functions again to get the content, text, and states.
+        /// Use this when the original item data has changed and you want the changes to reflect.
+        /// </summary>
+        /// <remarks>
+        /// <see cref="GenGrid.UpdateRealizedItems"/> to update the contents of all the realized items.
+        /// </remarks>
         public override void Update()
         {
             Interop.Elementary.elm_gengrid_item_update(Handle);
old mode 100644 (file)
new mode 100755 (executable)
index e6f6c9d..3ac0335
@@ -18,6 +18,11 @@ using System;
 
 namespace ElmSharp
 {
+    /// <summary>
+    /// It inherits <see cref="ItemObject"/>.
+    /// A base class for <see cref="GenGridItem"/> and <see cref="GenListItem"/>.
+    /// It contains genitem class and data to display data.
+    /// </summary>
     public abstract class GenItem : ItemObject
     {
         internal GenItem(object data, GenItemClass itemClass) : base(IntPtr.Zero)
@@ -26,10 +31,29 @@ namespace ElmSharp
             ItemClass = itemClass;
         }
 
+        /// <summary>
+        /// Gets the item class that defines how to display data. It returns <see cref="GenItemClass"/> type.
+        /// </summary>
         public GenItemClass ItemClass { get; protected set; }
+
+        /// <summary>
+        /// Gets item data that is added through calling <see cref="GenGrid.Append(GenItemClass, object)"/>, <see cref="GenGrid.Prepend(GenItemClass, object)"/> or <see cref="GenGrid.InsertBefore(GenItemClass, object, GenGridItem)"/> methods.
+        /// </summary>
         public object Data { get; protected set; }
+
+        /// <summary>
+        /// It's a abstract property. It's implemented by <see cref="GenGridItem.IsSelected"/> and <see cref="GenListItem.IsSelected"/>.
+        /// </summary>
         public abstract bool IsSelected { get; set; }
+
+        /// <summary>
+        /// It's a abstract method. It's implemented by <see cref="GenGridItem.Update"/> and <see cref="GenListItem.Update"/>.
+        /// </summary>
         public abstract void Update();
+
+        /// <summary>
+        /// The override method for delete item class and item data. It's called when the item is deleting.
+        /// </summary>
         protected override void OnInvalidate()
         {
             ItemClass?.SendItemDeleted(Data);
old mode 100644 (file)
new mode 100755 (executable)
index 0ece261..d0343cb
@@ -20,18 +20,53 @@ using System.Runtime.InteropServices;
 
 namespace ElmSharp
 {
+    /// <summary>
+    /// It represents the GenGrid or GenList item class definition field details.
+    /// It has some display styles, such as "default", "full" and "group_index".
+    /// </summary>
     public class GenItemClass : IDisposable
     {
         private static Dictionary<IntPtr, EvasObject> s_HandleToEvasObject = new Dictionary<IntPtr, EvasObject>();
+
+        /// <summary>
+        /// The delegate to define <see cref="GetTextHandler"/>.
+        /// </summary>
+        /// <param name="data">The item data.</param>
+        /// <param name="part">The part where the data should be shown.</param>
+        /// <returns>Return string that should be shown.</returns>
         public delegate string GetTextDelegate(object data, string part);
+
+        /// <summary>
+        /// The delegate to define <see cref="GetContentHandler"/>.
+        /// </summary>
+        /// <param name="data">The item data.</param>
+        /// <param name="part">The part where the data should be shown.</param>
+        /// <returns>Return content that should be shown.</returns>
         public delegate EvasObject GetContentDelegate(object data, string part);
+
+        /// <summary>
+        /// The delegate to define <see cref="DeleteHandler"/>.
+        /// </summary>
+        /// <param name="data">The item data.</param>
         public delegate void DeleteDelegate(object data);
+
+        /// <summary>
+        /// The delegate to define <see cref="ReusableContentHandler"/>.
+        /// </summary>
+        /// <param name="data">The item data.</param>
+        /// <param name="part">The part where the data should be shown.</param>
+        /// <param name="old">The content has been added in gengrid.</param>
+        /// <returns>Return content that should be shown.</returns>
         public delegate EvasObject GetReusableContentDelegate(object data, string part, EvasObject old);
 
         private ItemClass _itemClass;
         private IntPtr _unmanagedPtr = IntPtr.Zero;
         private string _style;
 
+        /// <summary>
+        /// Creates and initializes a new instance of the GenItemClass.
+        /// </summary>
+        /// <param name="style">The item display style.</param>
         public GenItemClass(string style)
         {
             _style = style;
@@ -52,10 +87,33 @@ namespace ElmSharp
             Dispose(false);
         }
 
+        /// <summary>
+        /// Gets the item style.
+        /// </summary>
         public string ItemStyle { get { return _style; } }
+
+        /// <summary>
+        /// Gets or sets the callback that defines how to display item text.
+        /// If get, return <see cref="GetTextDelegate"/>.
+        /// </summary>
         public GetTextDelegate GetTextHandler { get; set; }
+
+        /// <summary>
+        /// Gets or sets the callback that defines how to display item content.
+        /// If get, return <see cref="GetContentDelegate"/>.
+        /// </summary>
         public GetContentDelegate GetContentHandler { get; set; }
+
+        /// <summary>
+        /// Gets or sets the callback that defines how to delete item text and content.
+        /// If get, return <see cref="DeleteDelegate"/>.
+        /// </summary>
         public DeleteDelegate DeleteHandler { get; set; }
+
+        /// <summary>
+        /// Gets or sets the callback that defines how to reuse item content.
+        /// If get, return <see cref="GetReusableContentDelegate"/>.
+        /// </summary>
         public GetReusableContentDelegate ReusableContentHandler { get; set; }
 
         internal IntPtr UnmanagedPtr
@@ -80,9 +138,6 @@ namespace ElmSharp
             }
         }
 
-        /// <summary>
-        /// Releases all resources used by the class.
-        /// </summary>
         public void Dispose()
         {
             Dispose(true);