class Ecore.Timer (Eo.Base)
{
   [[Timers are objects that will call a given callback at some point
     in the future.

     They may also optionall repeat themselves if the timer callback returns
     $true. If it does not they will be automatically deleted and never called
     again. Timers require the ecore mainloop to be running and functioning
     properly. They do not guarantee exact timing, but try to work on a "best
     effort basis.
   ]]
   eo_prefix: ecore_obj_timer;
   methods {
      @property interval {
         set {
            [[Changes the interval the timer ticks off. If set during
              a timer call, this will affect the next interval.

              \@if MOBILE \@since_tizen 2.3
              \@elseif WEARABLE \@since_tizen 2.3.1
              \@endif
            ]]
         }
         get {
            [[Gets the interval the timer ticks on.

              \@if MOBILE \@since_tizen 2.3
              \@elseif WEARABLE \@since_tizen 2.3.1
              \@endif
            ]]
         }
         values {
            in: double(-1); [[The new interval in seconds]]
         }
      }
      @property pending {
         get {
            [[Gets the pending time regarding a timer.

              \@if MOBILE \@since_tizen 2.3
              \@elseif WEARABLE \@since_tizen 2.3.1
              \@endif
            ]]
            return: double;
         }
      }
      loop_constructor {
         [[Creates a timer to call in a given time from now]]
         legacy: null;
         params {
            @in in: double; [[The time, in seconds, from now when to go off]]
            @in func: Ecore_Task_Cb; [[The callback function to call when the
                                       timer goes off]]
            @in data: const(void)*; [[A pointer to pass to the callback function
                                      as its data pointer]]
         }
      }
      constructor {
         [[Creates a timer to call in a given time from when the mainloop woke
           up from sleep]]
         legacy: null;
         params {
            @in in: double; [[The time, in seconds, from when the main loop
                              woke up, to go off]]
            @in func: Ecore_Task_Cb; [[The callback function to call when the
                                       timer goes off]]
            @in data: const(void)*; [[A pointer to pass to the callback
                                      function as its data pointer]]
         }
      }
      reset {
         /* FIXME-doc:
          * @note This is equivalent to (but faster than)
          * @code
          * ecore_timer_delay(timer, ecore_timer_interval_get(timer) - ecore_timer_pending_get(timer));
          * @endcode
          */
          [[Resets a timer to its full interval. This effectively makes the
            timer start ticking off from zero now.

            \@if MOBILE \@since_tizen 2.3
            \@elseif WEARABLE \@since_tizen 2.3.1
            \@endif

            @since 1.2
          ]]
      }
      delay {
         [[Adds some delay for the next occurrence of a timer.
           This doesn't affect the interval of a timer.

           \@if MOBILE \@since_tizen 2.3
           \@elseif WEARABLE \@since_tizen 2.3.1
           \@endif
         ]]
         params {
            @in add: double; [[The amount of time to delay the timer by in seconds]]
         }
      }
   }
   implements {
      Eo.Base.destructor;
      Eo.Base.finalize;
      Eo.Base.event_freeze;
      /* XXX: can't document overriden methods
       * Pauses a running timer.
       *
       * @param timer The timer to be paused.
       *
       * The timer callback won't be called while the timer is paused. The remaining
       * time until the timer expires will be saved, so the timer can be resumed with
       * that same remaining time to expire, instead of expiring instantly. Use
       * ecore_timer_thaw() to resume it.
       *
       * @note Nothing happens if the timer was already paused.
       *
       * @see ecore_timer_thaw()
       */
      Eo.Base.event_freeze_count.get;
      Eo.Base.event_thaw;
      /* XXX: can't document overriden methods
       * Resumes a frozen (paused) timer.
       *
       * @param timer The timer to be resumed.
       *
       * The timer will be resumed from its previous relative position in time. That
       * means, if it had X seconds remaining until expire when it was paused, it will
       * be started now with those same X seconds remaining to expire again. But
       * notice that the interval time won't be touched by this call or by
       * ecore_timer_freeze().
       *
       * @see ecore_timer_freeze()
       */
   }
   constructors {
      .constructor;
      .loop_constructor;
   }
}
