[NUI] Add more description for selection APIs
[platform/core/csapi/tizenfx.git] / src / Tizen.NUI / src / public / BaseComponents / TextField.cs
index 8466caa..1d4d1ae 100755 (executable)
@@ -38,6 +38,7 @@ namespace Tizen.NUI.BaseComponents
         private InputMethodContext inputMethodCotext = null;
         private float fontSizeScale = 1.0f;
         private bool hasFontSizeChangedCallback = false;
+        private bool isSettingTextInCSharp = false;
 
         static TextField() { }
 
@@ -77,6 +78,8 @@ namespace Tizen.NUI.BaseComponents
             {
                 SetVisible(false);
             }
+
+            TextChanged += TextEditorTextChanged;
         }
 
         internal TextField(global::System.IntPtr cPtr, bool cMemoryOwn, bool shown = true) : base(cPtr, cMemoryOwn, null)
@@ -85,6 +88,8 @@ namespace Tizen.NUI.BaseComponents
             {
                 SetVisible(false);
             }
+
+            TextChanged += TextEditorTextChanged;
         }
 
         internal TextField(TextField handle, bool shown = true) : this(Interop.TextField.NewTextField(TextField.getCPtr(handle)), true)
@@ -95,6 +100,8 @@ namespace Tizen.NUI.BaseComponents
             {
                 SetVisible(false);
             }
+
+            TextChanged += TextEditorTextChanged;
         }
 
         internal enum ExceedPolicyType
@@ -227,7 +234,7 @@ namespace Tizen.NUI.BaseComponents
             }
             set
             {
-                SetValueAndForceSendChangeSignal(TextProperty, value);
+                SetValue(TextProperty, value);
                 NotifyPropertyChanged();
             }
         }
@@ -327,8 +334,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetFontStyle(FontStyle fontStyle)
         {
-            SetProperty(TextField.Property.FontStyle, new PropertyValue(TextUtils.GetFontStyleMap(fontStyle)));
-            NotifyPropertyChanged();
+            SetValue(FontStyleProperty, TextUtils.GetFontStyleMap(fontStyle));
         }
 
         /// <summary>
@@ -341,9 +347,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public FontStyle GetFontStyle()
         {
-            var map = new PropertyMap();
-            GetProperty(TextField.Property.FontStyle).Get(map);
-            return TextUtils.GetFontStyleStruct(map);
+            return TextUtils.GetFontStyleStruct((PropertyMap)GetValue(FontStyleProperty));
         }
 
         /// <summary>
@@ -751,6 +755,49 @@ namespace Tizen.NUI.BaseComponents
         }
 
         /// <summary>
+        /// Set SelectionHandleImage to TextField. <br />
+        /// </summary>
+        /// <param name="selectionHandleImage">The SelectionHandleImage</param>
+        /// <remarks>
+        /// SetSelectionHandleImage specifies the display image used for the selection handle through <see cref="Tizen.NUI.Text.SelectionHandleImage"/>. <br />
+        /// </remarks>
+        /// <example>
+        /// The following example demonstrates how to use the SetSelectionHandleImage method.
+        /// <code>
+        /// var selectionHandleImage = new Tizen.NUI.Text.SelectionHandleImage();
+        /// selectionHandleImage.LeftImageUrl = "handle_downleft.png";
+        /// selectionHandleImage.RightImageUrl = "handle_downright.png";
+        /// field.SetSelectionHandleImage(selectionHandleImage);
+        /// </code>
+        /// </example>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public void SetSelectionHandleImage(SelectionHandleImage selectionHandleImage)
+        {
+            if (!String.IsNullOrEmpty(selectionHandleImage.LeftImageUrl))
+            {
+                SetValue(SelectionHandleImageLeftProperty, TextUtils.GetFileNameMap(selectionHandleImage.LeftImageUrl));
+            }
+
+            if (!String.IsNullOrEmpty(selectionHandleImage.RightImageUrl))
+            {
+                SetValue(SelectionHandleImageRightProperty, TextUtils.GetFileNameMap(selectionHandleImage.RightImageUrl));
+            }
+        }
+
+        /// <summary>
+        /// Get SelectionHandleImage from TextField. <br />
+        /// </summary>
+        /// <returns>The SelectionHandleImage</returns>
+        /// <remarks>
+        /// <see cref="Tizen.NUI.Text.SelectionHandleImage"/>
+        /// </remarks>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public SelectionHandleImage GetSelectionHandleImage()
+        {
+            return TextUtils.GetSelectionHandleImageStruct((PropertyMap)GetValue(SelectionHandleImageLeftProperty), (PropertyMap)GetValue(SelectionHandleImageRightProperty));
+        }
+
+        /// <summary>
         /// The SelectionHandlePressedImageLeft property.
         /// The selectionHandlePressedImageLeft map contains the following key :<br />
         /// <list type="table">
@@ -793,6 +840,49 @@ namespace Tizen.NUI.BaseComponents
         }
 
         /// <summary>
+        /// Set SelectionHandlePressedImage to TextField. <br />
+        /// </summary>
+        /// <param name="selectionHandlePressedImage">The SelectionHandleImage</param>
+        /// <remarks>
+        /// SetSelectionHandlePressedImage specifies the display image used for the selection handle through <see cref="Tizen.NUI.Text.SelectionHandleImage"/>. <br />
+        /// </remarks>
+        /// <example>
+        /// The following example demonstrates how to use the SetSelectionHandlePressedImage method.
+        /// <code>
+        /// var selectionHandlePressedImage = new Tizen.NUI.Text.SelectionHandleImage();
+        /// selectionHandlePressedImage.LeftImageUrl = "handle_pressed_downleft.png";
+        /// selectionHandlePressedImage.RightImageUrl = "handle_pressed_downright.png";
+        /// field.SetSelectionHandlePressedImage(selectionHandlePressedImage);
+        /// </code>
+        /// </example>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public void SetSelectionHandlePressedImage(SelectionHandleImage selectionHandlePressedImage)
+        {
+            if (!String.IsNullOrEmpty(selectionHandlePressedImage.LeftImageUrl))
+            {
+                SetValue(SelectionHandlePressedImageLeftProperty, TextUtils.GetFileNameMap(selectionHandlePressedImage.LeftImageUrl));
+            }
+
+            if (!String.IsNullOrEmpty(selectionHandlePressedImage.RightImageUrl))
+            {
+                SetValue(SelectionHandlePressedImageRightProperty, TextUtils.GetFileNameMap(selectionHandlePressedImage.RightImageUrl));
+            }
+        }
+
+        /// <summary>
+        /// Get SelectionHandlePressedImage from TextField. <br />
+        /// </summary>
+        /// <returns>The SelectionHandlePressedImage</returns>
+        /// <remarks>
+        /// <see cref="Tizen.NUI.Text.SelectionHandleImage"/>
+        /// </remarks>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public SelectionHandleImage GetSelectionHandlePressedImage()
+        {
+            return TextUtils.GetSelectionHandleImageStruct((PropertyMap)GetValue(SelectionHandlePressedImageLeftProperty), (PropertyMap)GetValue(SelectionHandlePressedImageRightProperty));
+        }
+
+        /// <summary>
         /// The SelectionHandleMarkerImageLeft property.
         /// The selectionHandleMarkerImageLeft map contains the following key :<br />
         /// <list type="table">
@@ -835,6 +925,49 @@ namespace Tizen.NUI.BaseComponents
         }
 
         /// <summary>
+        /// Set SelectionHandleMarkerImage to TextField. <br />
+        /// </summary>
+        /// <param name="selectionHandleMarkerImage">The SelectionHandleImage</param>
+        /// <remarks>
+        /// SetSelectionHandleMarkerImage specifies the display image used for the selection handle through <see cref="Tizen.NUI.Text.SelectionHandleImage"/>. <br />
+        /// </remarks>
+        /// <example>
+        /// The following example demonstrates how to use the SetSelectionHandleMarkerImage method.
+        /// <code>
+        /// var selectionHandleMarkerImage = new Tizen.NUI.Text.SelectionHandleImage();
+        /// selectionHandleMarkerImage.LeftImageUrl = "handle_pressed_downleft.png";
+        /// selectionHandleMarkerImage.RightImageUrl = "handle_pressed_downright.png";
+        /// field.SetSelectionHandleMarkerImage(selectionHandleMarkerImage);
+        /// </code>
+        /// </example>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public void SetSelectionHandleMarkerImage(SelectionHandleImage selectionHandleMarkerImage)
+        {
+            if (!String.IsNullOrEmpty(selectionHandleMarkerImage.LeftImageUrl))
+            {
+                SetValue(SelectionHandleMarkerImageLeftProperty, TextUtils.GetFileNameMap(selectionHandleMarkerImage.LeftImageUrl));
+            }
+
+            if (!String.IsNullOrEmpty(selectionHandleMarkerImage.RightImageUrl))
+            {
+                SetValue(SelectionHandleMarkerImageRightProperty, TextUtils.GetFileNameMap(selectionHandleMarkerImage.RightImageUrl));
+            }
+        }
+
+        /// <summary>
+        /// Get SelectionHandleMarkerImage from TextField. <br />
+        /// </summary>
+        /// <returns>The SelectionHandleMarkerImage</returns>
+        /// <remarks>
+        /// <see cref="Tizen.NUI.Text.SelectionHandleImage"/>
+        /// </remarks>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public SelectionHandleImage GetSelectionHandleMarkerImage()
+        {
+            return TextUtils.GetSelectionHandleImageStruct((PropertyMap)GetValue(SelectionHandleMarkerImageLeftProperty), (PropertyMap)GetValue(SelectionHandleMarkerImageRightProperty));
+        }
+
+        /// <summary>
         /// The SelectionHighlightColor property.
         /// </summary>
         /// <remarks>
@@ -1006,8 +1139,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetInputFontStyle(FontStyle fontStyle)
         {
-            SetProperty(TextField.Property.InputFontStyle, new PropertyValue(TextUtils.GetFontStyleMap(fontStyle)));
-            NotifyPropertyChanged();
+            SetValue(InputFontStyleProperty, TextUtils.GetFontStyleMap(fontStyle));
         }
 
         /// <summary>
@@ -1020,9 +1152,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public FontStyle GetInputFontStyle()
         {
-            var map = new PropertyMap();
-            GetProperty(TextField.Property.InputFontStyle).Get(map);
-            return TextUtils.GetFontStyleStruct(map);
+            return TextUtils.GetFontStyleStruct((PropertyMap)GetValue(InputFontStyleProperty));
         }
 
         /// <summary>
@@ -1086,7 +1216,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetUnderline(Underline underline)
         {
-            SetProperty(TextField.Property.UNDERLINE, new PropertyValue(TextUtils.GetUnderlineMap(underline)));
+            SetValue(UnderlineProperty, TextUtils.GetUnderlineMap(underline));
         }
 
         /// <summary>
@@ -1099,9 +1229,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public Underline GetUnderline()
         {
-            var map = new PropertyMap();
-            GetProperty(TextField.Property.UNDERLINE).Get(map);
-            return TextUtils.GetUnderlineStruct(map);
+            return TextUtils.GetUnderlineStruct((PropertyMap)GetValue(UnderlineProperty));
         }
 
         /// <summary>
@@ -1164,7 +1292,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetShadow(Tizen.NUI.Text.Shadow shadow)
         {
-            SetProperty(TextField.Property.SHADOW, new PropertyValue(TextUtils.GetShadowMap(shadow)));
+            SetValue(ShadowProperty, TextUtils.GetShadowMap(shadow));
         }
 
         /// <summary>
@@ -1177,9 +1305,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public Tizen.NUI.Text.Shadow GetShadow()
         {
-            var map = new PropertyMap();
-            GetProperty(TextField.Property.SHADOW).Get(map);
-            return TextUtils.GetShadowStruct(map);
+            return TextUtils.GetShadowStruct((PropertyMap)GetValue(ShadowProperty));
         }
 
         /// <summary>
@@ -1275,7 +1401,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetOutline(Outline outline)
         {
-            SetProperty(TextField.Property.OUTLINE, new PropertyValue(TextUtils.GetOutlineMap(outline)));
+            SetValue(OutlineProperty, TextUtils.GetOutlineMap(outline));
         }
 
         /// <summary>
@@ -1288,9 +1414,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public Outline GetOutline()
         {
-            var map = new PropertyMap();
-            GetProperty(TextField.Property.OUTLINE).Get(map);
-            return TextUtils.GetOutlineStruct(map);
+            return TextUtils.GetOutlineStruct((PropertyMap)GetValue(OutlineProperty));
         }
 
         /// <summary>
@@ -1348,6 +1472,43 @@ namespace Tizen.NUI.BaseComponents
         }
 
         /// <summary>
+        /// Set HiddenInput to TextField. <br />
+        /// </summary>
+        /// <param name="hiddenInput">The HiddenInput</param>
+        /// <remarks>
+        /// SetHiddenInput specifies the requested font style through <see cref="Tizen.NUI.Text.HiddenInput"/>. <br />
+        /// </remarks>
+        /// <example>
+        /// The following example demonstrates how to use the SetHiddenInput method.
+        /// <code>
+        /// var hiddenInput = new Tizen.NUI.Text.HiddenInput();
+        /// hiddenInput.Mode = HiddenInputModeType.ShowLastCharacter;
+        /// hiddenInput.SubstituteCharacter = '★';
+        /// hiddenInput.SubstituteCount = 0;
+        /// hiddenInput.ShowLastCharacterDuration = 1000;
+        /// field.SetHiddenInput(hiddenInput);
+        /// </code>
+        /// </example>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public void SetHiddenInput(HiddenInput hiddenInput)
+        {
+            SetValue(HiddenInputSettingsProperty, TextUtils.GetHiddenInputMap(hiddenInput));
+        }
+
+        /// <summary>
+        /// Get HiddenInput from TextField. <br />
+        /// </summary>
+        /// <returns>The HiddenInput</returns>
+        /// <remarks>
+        /// <see cref="Tizen.NUI.Text.HiddenInput"/>
+        /// </remarks>
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public HiddenInput GetHiddenInput()
+        {
+            return TextUtils.GetHiddenInputStruct((PropertyMap)GetValue(HiddenInputSettingsProperty));
+        }
+
+        /// <summary>
         /// The PixelSize property.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
@@ -1420,11 +1581,12 @@ namespace Tizen.NUI.BaseComponents
         }
 
         /// <summary>
-        /// The Selected Text property.
+        /// The portion of the text that has been selected by the user.
         /// </summary>
-        /// <since_tizen> 8 </since_tizen>
-        /// This will be public opened in tizen_6.0 after ACR done, Before ACR, need to be hidden as inhouse API.
-        [EditorBrowsable(EditorBrowsableState.Never)]
+        /// <remarks>
+        /// Empty string when nothing is selected.
+        /// </remarks>
+        /// <since_tizen> 9 </since_tizen>
         public string SelectedText
         {
             get
@@ -1438,9 +1600,10 @@ namespace Tizen.NUI.BaseComponents
         /// <summary>
         /// The start index for selection.
         /// </summary>
-        /// <since_tizen> 8 </since_tizen>
-        /// This will be public opened in tizen_6.0 after ACR done, Before ACR, need to be hidden as inhouse API.
-        [EditorBrowsable(EditorBrowsableState.Never)]
+        /// <remarks>
+        /// When there is no selection, the index is current cursor position.
+        /// </remarks>
+        /// <since_tizen> 9 </since_tizen>
         public int SelectedTextStart
         {
             get
@@ -1449,19 +1612,15 @@ namespace Tizen.NUI.BaseComponents
                 GetProperty(TextField.Property.SelectedTextStart).Get(out temp);
                 return temp;
             }
-            set
-            {
-                SetProperty(TextField.Property.SelectedTextStart, new PropertyValue(value));
-                NotifyPropertyChanged();
-            }
         }
 
         /// <summary>
         /// The end index for selection.
         /// </summary>
-        /// <since_tizen> 8 </since_tizen>
-        /// This will be public opened in tizen_6.0 after ACR done, Before ACR, need to be hidden as inhouse API.
-        [EditorBrowsable(EditorBrowsableState.Never)]
+        /// <remarks>
+        /// When there is no selection, the index is current cursor position.
+        /// </remarks>
+        /// <since_tizen> 9 </since_tizen>
         public int SelectedTextEnd
         {
             get
@@ -1470,11 +1629,6 @@ namespace Tizen.NUI.BaseComponents
                 GetProperty(TextField.Property.SelectedTextEnd).Get(out temp);
                 return temp;
             }
-            set
-            {
-                SetProperty(TextField.Property.SelectedTextEnd, new PropertyValue(value));
-                NotifyPropertyChanged();
-            }
         }
 
         /// <summary>
@@ -1546,10 +1700,9 @@ namespace Tizen.NUI.BaseComponents
 
         /// <summary>
         /// The ellipsis position of the text.
-        /// The ellipsis position type when the text size over the layout size.<br />
-        /// The ellipsis position: End, Start or Middle.<br />
+        /// Specifies which portion of the text should be replaced with an ellipsis when the text size exceeds the layout size.<br />
         /// </summary>
-        [EditorBrowsable(EditorBrowsableState.Never)]
+        /// <since_tizen> 9 </since_tizen>
         public EllipsisPosition EllipsisPosition
         {
             get
@@ -1757,7 +1910,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetPlaceholder(Placeholder placeholder)
         {
-            SetProperty(TextField.Property.PLACEHOLDER, new PropertyValue(TextUtils.GetPlaceholderMap(placeholder)));
+            SetValue(PlaceholderProperty, TextUtils.GetPlaceholderMap(placeholder));
         }
 
         /// <summary>
@@ -1770,9 +1923,7 @@ namespace Tizen.NUI.BaseComponents
         [EditorBrowsable(EditorBrowsableState.Never)]
         public Placeholder GetPlaceholder()
         {
-            var map = new PropertyMap();
-            GetProperty(TextField.Property.PLACEHOLDER).Get(map);
-            return TextUtils.GetPlaceholderStruct(map);
+            return TextUtils.GetPlaceholderStruct((PropertyMap)GetValue(PlaceholderProperty));
         }
 
         /// <summary>
@@ -1876,28 +2027,6 @@ namespace Tizen.NUI.BaseComponents
             }
         }
 
-        /// Only used by the IL of xaml, will never changed to not hidden.
-        [EditorBrowsable(EditorBrowsableState.Never)]
-        public override bool IsCreateByXaml
-        {
-            get
-            {
-                return base.IsCreateByXaml;
-            }
-            set
-            {
-                base.IsCreateByXaml = value;
-
-                if (value == true)
-                {
-                    this.TextChanged += (obj, e) =>
-                    {
-                        this.Text = e.TextField.Text;
-                    };
-                }
-            }
-        }
-
         /// <summary>
         /// Get the InputMethodContext instance.
         /// </summary>
@@ -1917,9 +2046,7 @@ namespace Tizen.NUI.BaseComponents
         /// <summary>
         /// Select the whole text.
         /// </summary>
-        /// <since_tizen> 6 </since_tizen>
-        /// This will be released at Tizen.NET API Level 5.5, so currently this would be used as inhouse API.
-        [EditorBrowsable(EditorBrowsableState.Never)]
+        /// <since_tizen> 9 </since_tizen>
         public void SelectWholeText()
         {
             Interop.TextField.SelectWholeText(SwigCPtr);
@@ -1927,34 +2054,37 @@ namespace Tizen.NUI.BaseComponents
         }
 
         /// <summary>
-        /// Select text from start to end index.
+        /// Select text from start to end index. <br />
+        /// The index is valid when 0 or positive.
         /// </summary>
         /// <param name="start">The start index for selection.</param>
         /// <param name="end">The end index for selection.</param>
-        [EditorBrowsable(EditorBrowsableState.Never)]
-        public void SelectText(uint start, uint end)
+        /// <remarks>
+        /// If the end index exceeds the maximum value, it is set to the length of the text.
+        /// </remarks>
+        /// <since_tizen> 9 </since_tizen>
+        public void SelectText(int start, int end)
         {
-            Interop.TextField.SelectText(SwigCPtr, start, end);
+            if (start < 0)
+                throw new global::System.ArgumentOutOfRangeException(nameof(start), "Value is less than zero");
+            if (end < 0)
+                throw new global::System.ArgumentOutOfRangeException(nameof(end), "Value is less than zero");
+
+            Interop.TextField.SelectText(SwigCPtr, (uint)start, (uint)end);
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
         }
 
         /// <summary>
-        /// Clear selection of the text.
+        /// Clear selection of the text. <br />
+        /// Valid when selection is activate.
         /// </summary>
-        /// <since_tizen> 8 </since_tizen>
-        /// This will be public opened in tizen_6.0 after ACR done, Before ACR, need to be hidden as inhouse API.
-        [EditorBrowsable(EditorBrowsableState.Never)]
+        /// <since_tizen> 9 </since_tizen>
         public void SelectNone()
         {
             _ = Interop.TextField.SelectNone(SwigCPtr);
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
         }
 
-        internal static global::System.Runtime.InteropServices.HandleRef getCPtr(TextField obj)
-        {
-            return (obj == null) ? new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero) : obj.SwigCPtr;
-        }
-
         internal SWIGTYPE_p_Dali__SignalT_void_fDali__Toolkit__TextField_Dali__Toolkit__TextField__InputStyle__MaskF_t InputStyleChangedSignal()
         {
             SWIGTYPE_p_Dali__SignalT_void_fDali__Toolkit__TextField_Dali__Toolkit__TextField__InputStyle__MaskF_t ret = new SWIGTYPE_p_Dali__SignalT_void_fDali__Toolkit__TextField_Dali__Toolkit__TextField__InputStyle__MaskF_t(Interop.TextField.InputStyleChangedSignal(SwigCPtr));
@@ -2019,6 +2149,8 @@ namespace Tizen.NUI.BaseComponents
                 }
             }
 
+            TextChanged -= TextEditorTextChanged;
+
             base.Dispose(type);
         }
 
@@ -2108,6 +2240,14 @@ namespace Tizen.NUI.BaseComponents
             }
         }
 
+        private void TextEditorTextChanged(object sender, TextChangedEventArgs e)
+        {
+            if (!isSettingTextInCSharp)
+            {
+                EnforceNotifyBindedInstance(TextProperty);
+            }
+        }
+
         internal new class Property
         {
             internal static readonly int TEXT = Interop.TextField.TextGet();