import ecore_types;

class Efl.Loop.Timer (Efl.Loop_User)
{
   [[Timers are objects that will call a given callback at some point
     in the future and repeat that tick at a given interval.

     Timers require the ecore main loop to be running and functioning
     properly. They do not guarantee exact timing, but try to work on a
     "best effort" basis.
   ]]
   legacy_prefix: ecore_timer;
   methods {
      @property interval {
         [[Interval the timer ticks on.]]
         set {
            [[If set during a timer call, this will affect the next interval.]]
         }
         get {
         }
         values {
            in: double(-1.0); [[The new interval in seconds]]
         }
      }
      @property pending {
         [[Pending time regarding a timer.]]
         get {
            return: double; [[Pending time]]
         }
      }
      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
          */
          [[Reset a timer to its full interval. This effectively makes the
            timer start ticking off from zero now.

            @since 1.2
          ]]
      }
      loop_reset {
         [[This effectively reset a timer, but based on the time when this iteration of the main loop started.
           @since 1.18
	 ]]
      }
      delay {
         [[Add some delay for the next occurrence of a timer.
           This doesn't affect the interval of a timer.
         ]]
         params {
            @in add: double; [[The amount of time to delay the timer by in seconds]]
         }
      }
   }
   events {
      tick; [[Event triggered when the specified time as passed.]]
   }
   implements {
      Efl.Object.constructor;
      Efl.Object.destructor;
      Efl.Object.finalize;
      Efl.Object.event_freeze;
      Efl.Object.parent { set; }
      /* XXX: can't document overridden 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()
       */
      Efl.Object.event_freeze_count { get; }
      Efl.Object.event_thaw;
      /* XXX: can't document overridden 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()
       */
   }
}