[NUI] change some comments of Timer and Window APIs
[platform/core/csapi/tizenfx.git] / src / Tizen.NUI / src / public / Timer.cs
index 8229740..cfae067 100755 (executable)
@@ -1,39 +1,43 @@
-/** Copyright (c) 2017 Samsung Electronics Co., Ltd.
-*
-* Licensed under the Apache License, Version 2.0 (the "License");
-* you may not use this file except in compliance with the License.
-* You may obtain a copy of the License at
-*
-* http://www.apache.org/licenses/LICENSE-2.0
-*
-* Unless required by applicable law or agreed to in writing, software
-* distributed under the License is distributed on an "AS IS" BASIS,
-* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-* See the License for the specific language governing permissions and
-* limitations under the License.
-*
-*/
+/*
+ * Copyright(c) 2017 Samsung Electronics Co., Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+using System;
+using System.Runtime.InteropServices;
+using System.ComponentModel;
+using System.Threading;
 
 namespace Tizen.NUI
 {
-
-    using System;
-    using System.Runtime.InteropServices;
-
     /// <summary>
-    /// Mechanism to issue simple periodic or one-shot events.<br>
+    /// Mechanism to issue simple periodic or one-shot events.<br />
     /// Timer is provided for application developers to be able to issue
-    /// simple periodic or one-shot events.  Please note that timer
-    /// callback functions should return as soon as possible, because they
-    /// block the next SignalTick.  Please note that timer signals are not
-    /// in sync with Dali's render timer.<br>
+    /// simple periodic or one-shot events. Please note that the timer
+    /// callback functions should return as soon as possible because they
+    /// block the next SignalTick. Please note that timer signals are not
+    /// in sync with DALi's render timer.<br />
     /// This class is a handle class so it can be stack allocated and used
-    /// as a member.<br>
+    /// as a member.<br />
     /// </summary>
+    /// <since_tizen> 3 </since_tizen>
     public class Timer : BaseHandle
     {
         private global::System.Runtime.InteropServices.HandleRef swigCPtr;
 
+        private bool played = false;
+
         internal Timer(global::System.IntPtr cPtr, bool cMemoryOwn) : base(NDalicPINVOKE.Timer_SWIGUpcast(cPtr), cMemoryOwn)
         {
             swigCPtr = new global::System.Runtime.InteropServices.HandleRef(this, cPtr);
@@ -44,14 +48,18 @@ namespace Tizen.NUI
             return (obj == null) ? new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero) : obj.swigCPtr;
         }
 
+        /// <summary>
+        /// Dispose.
+        /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         protected override void Dispose(DisposeTypes type)
         {
-            if(disposed)
+            if (disposed)
             {
                 return;
             }
 
-            if(type == DisposeTypes.Explicit)
+            if (type == DisposeTypes.Explicit)
             {
                 //Called by User
                 //Release your own managed resources here.
@@ -62,6 +70,11 @@ namespace Tizen.NUI
             //You should not access any managed member here except static instance.
             //because the execution order of Finalizes is non-deterministic.
 
+            if (_timerTickCallbackDelegate != null)
+            {
+                TickSignal().Disconnect(_timerTickCallbackDelegate);
+            }
+
             if (swigCPtr.Handle != global::System.IntPtr.Zero)
             {
                 if (swigCMemOwn)
@@ -72,27 +85,29 @@ namespace Tizen.NUI
                 swigCPtr = new global::System.Runtime.InteropServices.HandleRef(null, global::System.IntPtr.Zero);
             }
 
+            played = false;
             base.Dispose(type);
         }
 
 
         /// <summary>
-        /// Event arguments that passed via Tick event.
+        /// Event arguments that passed via the tick event.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         public class TickEventArgs : EventArgs
         {
         }
 
         [UnmanagedFunctionPointer(CallingConvention.StdCall)]
-        private delegate bool TickCallbackDelegate(IntPtr data);
+        private delegate bool TickCallbackDelegate();
         private EventHandlerWithReturnType<object, TickEventArgs, bool> _timerTickEventHandler;
         private TickCallbackDelegate _timerTickCallbackDelegate;
 
         /// <summary>
-        /// brief Event for Ticked signal which can be used to subscribe/unsubscribe the event handler
-        /// (in the type of TickEventHandler-DaliEventHandlerWithReturnType<object,TickEventArgs,bool>).<br>
-        /// provided by the user. Ticked signal is emitted after specified time interval.<br>
+        /// @brief Event for the ticked signal, which can be used to subscribe or unsubscribe the event handler
+        /// provided by the user. The ticked signal is emitted after specified time interval.<br />
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         public event EventHandlerWithReturnType<object, TickEventArgs, bool> Tick
         {
             add
@@ -114,11 +129,16 @@ namespace Tizen.NUI
             }
         }
 
-        private bool OnTick(IntPtr data)
+        private bool OnTick()
         {
             TickEventArgs e = new TickEventArgs();
 
-            if (_timerTickEventHandler != null)
+            if (played == false)
+            {
+                Tizen.Log.Fatal("NUI", $"({swigCPtr.Handle}) OnTick() is called even played is false!");
+            }
+
+            if (_timerTickEventHandler != null && played == true)
             {
                 //here we send all data to user event handlers
                 return _timerTickEventHandler(this, e);
@@ -127,55 +147,92 @@ namespace Tizen.NUI
         }
 
         /// <summary>
-        /// Creates a tick Timer that emits periodic signal.
+        /// Creates a tick timer that emits periodic signal.
         /// </summary>
-        /// <param name="milliSec">Interval in milliseconds</param>
-        /// <returns>A new timer</returns>
+        /// <param name="milliSec">Interval in milliseconds.</param>
+        /// <returns>A new timer.</returns>
+        /// <since_tizen> 3 </since_tizen>
         public Timer(uint milliSec) : this(NDalicPINVOKE.Timer_New(milliSec), true)
         {
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
 
+            Tizen.Log.Error("NUI", $"({swigCPtr.Handle}) Timer({milliSec}) Constructor!");
         }
         internal Timer(Timer timer) : this(NDalicPINVOKE.new_Timer__SWIG_1(Timer.getCPtr(timer)), true)
         {
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
         }
 
-
-        [Obsolete("Please do not use! this will be deprecated")]
+        /// <summary>
+        /// Downcasts a handle to Timer handle.
+        /// </summary>
+        /// <since_tizen> 3 </since_tizen>
+        /// Please do not use! this will be deprecated!
+        /// Instead please use as keyword.
+        [Obsolete("Please do not use! This will be deprecated! Please use as keyword instead!")]
+        [EditorBrowsable(EditorBrowsableState.Never)]
         public static Timer DownCast(BaseHandle handle)
         {
-            Timer ret = new Timer(NDalicPINVOKE.Timer_DownCast(BaseHandle.getCPtr(handle)), true);
+            Timer ret = Registry.GetManagedBaseHandleFromNativePtr(handle) as Timer;
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
             return ret;
         }
 
         /// <summary>
-        /// Starts timer.<br>
-        /// In case a Timer is already running, its time is reset and timer is restarted.<br>
+        /// Starts the timer.<br />
+        /// In case a timer is already running, its time is reset and the timer is restarted.<br />
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         public void Start()
         {
+            played = true;
             NDalicPINVOKE.Timer_Start(swigCPtr);
+
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
         }
 
         /// <summary>
-        /// Stops timer.
+        /// Stops the timer.
         /// </summary>
+        /// <since_tizen> 3 </since_tizen>
         public void Stop()
         {
+            played = false;
             NDalicPINVOKE.Timer_Stop(swigCPtr);
+
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
         }
 
         /// <summary>
-        /// Sets a new interval on the timer and starts the timer.<br>
-        /// Cancels the previous timer.<br>
+        /// Gets/Sets the interval of the timer.
+        /// </summary>
+        /// <remarks>For setter, this sets a new interval on the timer and starts the timer. <br />
+        /// Cancels the previous timer.
+        /// </remarks>
+        /// <since_tizen> 4 </since_tizen>
+        public uint Interval
+        {
+            get
+            {
+                return GetInterval();
+            }
+            set
+            {
+                SetInterval(value);
+            }
+        }
+
+        /// <summary>
+        /// Sets a new interval on the timer and starts the timer.<br />
+        /// Cancels the previous timer.<br />
         /// </summary>
-        /// <param name="milliSec">milliSec Interval in milliseconds</param>
+        /// <param name="milliSec">MilliSec interval in milliseconds.</param>
         internal void SetInterval(uint milliSec)
         {
+
+            Tizen.Log.Error("NUI", $"({swigCPtr.Handle}) SetInterval({milliSec})");
+            played = true;
+
             NDalicPINVOKE.Timer_SetInterval(swigCPtr, milliSec);
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
         }
@@ -184,13 +241,15 @@ namespace Tizen.NUI
         {
             uint ret = NDalicPINVOKE.Timer_GetInterval(swigCPtr);
             if (NDalicPINVOKE.SWIGPendingException.Pending) throw NDalicPINVOKE.SWIGPendingException.Retrieve();
+            Tizen.Log.Error("NUI", $"({swigCPtr.Handle})GetInterval({ret})");
             return ret;
         }
 
         /// <summary>
-        /// Tells whether timer is running.
+        /// Tells whether the timer is running.
         /// </summary>
-        /// <returns>Whether Timer is started or not</returns>
+        /// <returns>Whether the timer is started or not.</returns>
+        /// <since_tizen> 3 </since_tizen>
         public bool IsRunning()
         {
             bool ret = NDalicPINVOKE.Timer_IsRunning(swigCPtr);
@@ -208,3 +267,4 @@ namespace Tizen.NUI
     }
 
 }
+