1 #ifndef _ECORE_LEGACY_H 2 #define _ECORE_LEGACY_H 3 4 /** 5 * @addtogroup Ecore_Poller_Group 6 * 7 * @{ 8 */ 9 typedef enum 10 { 11 ECORE_POLLER_CORE = 0 /**< The core poller interval */ 12 } Ecore_Poller_Type; 13 14 typedef struct _Ecore_Poller Ecore_Poller; 15 16 /** 17 * @brief Creates a poller to call the given function at a particular tick interval. 18 * @param type The ticker type to attach the poller to. Must be ECORE_POLLER_CORE. 19 * @param interval The poll interval. 20 * @param func The poller function. 21 * @param data Data to pass to @a func when it is called. 22 * @return A poller object on success, @c NULL otherwise. 23 * 24 * This function adds @a func as a poller callback that will be called every @a 25 * interval ticks together with other pollers of type @a type. @a func will be 26 * passed the @p data pointer as a parameter. 27 * 28 * The @p interval must be between 1 and 32768 inclusive, and must be a power of 29 * 2 (i.e. 1, 2, 4, 8, 16, ... 16384, 32768). The exact tick in which @a func 30 * will be called is undefined, as only the interval between calls can be 31 * defined. Ecore will endeavor to keep pollers synchronized and to call as 32 * many in 1 wakeup event as possible. If @a interval is not a power of two, the 33 * closest power of 2 greater than @a interval will be used. 34 * 35 * When the poller @p func is called, it must return a value of either 36 * @c ECORE_CALLBACK_RENEW(or @c 1) or @c ECORE_CALLBACK_CANCEL(or @c 0). If it 37 * returns @c 1, it will be called again at the next tick, or if it returns 38 * @c 0 it will be deleted automatically making any references/handles for it 39 * invalid. 40 */ 41 EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data); 42 43 /** 44 * @brief Deletes the specified poller from the timer list. 45 * @param poller The poller to delete. 46 * @return The data pointer set for the timer when @ref ecore_poller_add was 47 * called on success, @c NULL otherwise. 48 * 49 * @note @a poller must be a valid handle. If the poller function has already 50 * returned @c 0, the handle is no longer valid (and does not need to be deleted). 51 */ 52 EAPI void *ecore_poller_del(Ecore_Poller *poller); 53 54 /** 55 * @brief Sets the time(in seconds) between ticks for the given poller type. 56 * @param type The poller type to adjust. 57 * @param poll_time The time(in seconds) between ticks of the timer. 58 * 59 * This will adjust the time between ticks of the given timer type defined by 60 * @p type to the time period defined by @p poll_time. 61 */ 62 EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time); 63 64 /** 65 * @brief Gets the time(in seconds) between ticks for the given poller type. 66 * @param type The poller type to query. 67 * @return The time in seconds between ticks of the poller timer. 68 * 69 * This will get the time between ticks of the specified poller timer. 70 */ 71 EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type); 72 73 /** 74 * @brief Polling interval rate of the poller. 75 * 76 * @param[in] interval The tick interval; must be a power of 2 and <= 32768. 77 * 78 * @return @c true on success, @c false on failure. 79 */ 80 EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *obj, int interval); 81 82 /** 83 * @brief Polling interval rate of the poller. 84 * 85 * @return The tick interval; must be a power of 2 and <= 32768. 86 */ 87 EAPI int ecore_poller_poller_interval_get(const Ecore_Poller *obj); 88 89 /** 90 * @} 91 */ 92 93 /** 94 * @addtogroup Ecore_Animator_Group 95 * 96 * @{ 97 */ 98 99 /** 100 * @struct Ecore_Animator 101 * Opaque handle to manage Ecore Animator objects. 102 */ 103 typedef struct _Ecore_Animator Ecore_Animator; 104 105 /** 106 * @brief Adds an animator to call @p func at every animation tick during main 107 * loop execution. 108 * 109 * @param func The function to call when it ticks off 110 * @param data The data to pass to the function 111 * @return A handle to the new animator 112 * 113 * This function adds an animator and returns its handle on success and @c NULL 114 * on failure. The function @p func will be called every N seconds where N is 115 * the @p frametime interval set by ecore_animator_frametime_set(). The 116 * function will be passed the @p data pointer as its parameter. 117 * 118 * When the animator @p func is called, it must return a boolean value. 119 * If it returns @c EINA_TRUE (or @c ECORE_CALLBACK_RENEW), it will be called again at 120 * the next tick, or if it returns @c EINA_FALSE (or @c ECORE_CALLBACK_CANCEL) it will be 121 * deleted automatically making any references/handles for it invalid. 122 * @see ecore_animator_timeline_add() 123 * @see ecore_animator_frametime_set() 124 * 125 * @note The default @p frametime value is 1/30th of a second. 126 * 127 */ 128 EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data); 129 130 /** 131 * @brief Adds an animator that runs for a limited time. 132 * 133 * @param runtime The time to run in seconds 134 * @param func The function to call when it ticks off 135 * @param data The data to pass to the function 136 * @return A handle to the new animator 137 * 138 * This function is just like ecore_animator_add() except the animator only 139 * runs for a limited time specified in seconds by @p runtime. Once the 140 * runtime the animator has elapsed (animator finished) it will automatically 141 * be deleted. The callback function @p func can return @c ECORE_CALLBACK_RENEW 142 * to keep the animator running or @c ECORE_CALLBACK_CANCEL or stop it and have 143 * it be deleted automatically at any time. Just like timers, the start of 144 * The animation is "now" (when the loop woke up - gettable with 145 * ecore_loop_time_get()). 146 * 147 * The @p func will ALSO be passed a position parameter that will be in value 148 * from 0.0 to 1.0 to indicate where along the timeline (0.0 start, 1.0 end) 149 * the animator run is at. If the callback wishes not to have a linear 150 * transition it can "map" this value to one of several curves and mappings 151 * via ecore_animator_pos_map(). 152 * @see ecore_animator_add() 153 * @see ecore_animator_pos_map() 154 * 155 * @note The default @p frametime value is 1/30th of a second. 156 * @note The first position parameter passed to the callback will never be 0. 157 * 158 * @since 1.1.0 159 */ 160 EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data); 161 162 /** 163 * @brief Deletes the specified animator from the animator list. 164 * 165 * @param animator The animator to delete 166 * @return The data pointer set for the animator on add 167 * 168 * Deletes the specified @p animator from the set of animators that are 169 * executed during main loop execution. This function returns the data 170 * parameter that was being passed to the callback on success, or @c NULL on 171 * failure. After this call returns the specified animator object @p animator 172 * is invalid and should not be used again. It will not get called again after 173 * deletion. 174 */ 175 EAPI void *ecore_animator_del(Ecore_Animator *animator); 176 177 /** 178 * @brief Suspends the specified animator. 179 * 180 * @param animator The animator to delete 181 * 182 * The specified @p animator will be temporarily removed from the set of 183 * animators that are executed during main loop. 184 * 185 * @warning Freezing an animator doesn't freeze accounting of how long that 186 * animator has been running. Therefore if the animator was created with 187 *ecore_animator_timeline_add() the @p pos argument given to the callback 188 * will increase as if the animator hadn't been frozen and the animator may 189 * have it's execution halted if @p runtime elapsed. 190 */ 191 EAPI void ecore_animator_freeze(Ecore_Animator *animator); 192 193 /** 194 * @brief Restores execution of the specified animator. 195 * 196 * @param animator The animator to delete 197 * 198 * The specified @p animator will be put back in the set of animators that are 199 * executed during main loop. 200 */ 201 EAPI void ecore_animator_thaw(Ecore_Animator *animator); 202 203 /** 204 * @} 205 */ 206 207 /** 208 * @addtogroup Ecore_Timer_Group 209 * 210 * @{ 211 */ 212 213 /** 214 * Creates a timer to call the given function in the given period of time. 215 * @param in The interval in seconds. 216 * @param func The given function. If @p func returns @c 1, the timer is 217 * rescheduled for the next interval @p in. 218 * @param data Data to pass to @p func when it is called. 219 * @return A timer object on success, @c NULL on failure. 220 * 221 * This function adds a timer and returns its handle on success and @c NULL on 222 * failure. The function @p func will be called every @p in seconds. The 223 * function will be passed the @p data pointer as its parameter. 224 * 225 * When the timer @p func is called, it must return a value of either @c 1 226 * (or @c ECORE_CALLBACK_RENEW) or @c 0 (or @c ECORE_CALLBACK_CANCEL). 227 * If it returns @c 1, it will be called again at the next tick, or if it returns 228 * @c 0 it will be deleted automatically making any references/handles for it 229 * invalid. 230 */ 231 EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data); 232 233 /** 234 * Creates a timer to call the given function in the given period of time. 235 * @param in The interval in seconds from current loop time. 236 * @param func The given function. If @p func returns 1, the timer is 237 * rescheduled for the next interval @p in. 238 * @param data Data to pass to @p func when it is called. 239 * @return A timer object on success, @c NULL on failure. 240 * 241 * This is the same as ecore_timer_add(), but "now" is the time from 242 * ecore_loop_time_get() not ecore_time_get() as ecore_timer_add() uses. See 243 * ecore_timer_add() for more details. 244 */ 245 EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data); 246 247 /** 248 * Deletes the specified timer from the timer list. 249 * @param timer The timer to delete. 250 * @return The data pointer set for the timer when @ref ecore_timer_add was 251 * called. @c NULL is returned if the function is unsuccessful. 252 * 253 * Note: @p timer must be a valid handle. If the timer function has already 254 * returned @c 0, the handle is no longer valid (and does not need to be delete). 255 */ 256 EAPI void *ecore_timer_del(Ecore_Timer *timer); 257 258 /** 259 * Pauses a running timer. 260 * 261 * @param timer The timer to be paused. 262 * 263 * @remarks The timer callback won't be called while the timer is paused. The remaining 264 * time until the timer expires will be saved, so the timer can be resumed with 265 * that same remaining time to expire, instead of expiring instantly. Use 266 * ecore_timer_thaw() to resume it. 267 * 268 * @note Nothing happens if the timer was already paused. 269 * 270 * @see ecore_timer_thaw() 271 */ 272 EAPI void ecore_timer_freeze(Ecore_Timer *timer); 273 274 /** 275 * @brief Return whether the timer is freezing. 276 * 277 * @return True if the timer object is freezed, false otherwise. 278 * 279 * @see ecore_timer_freeze(), ecore_timer_thaw() 280 */ 281 EAPI Eina_Bool ecore_timer_freeze_get(Ecore_Timer *timer); 282 283 /** 284 * @brief Resumes a frozen (paused) timer. 285 * 286 * @remarks The timer will be resumed from its previous relative position in time. That 287 * means, if it had X seconds remaining until expire when it was paused, it will 288 * be started now with those same X seconds remaining to expire again. But 289 * notice that the interval time won't be touched by this call or by 290 * ecore_timer_freeze(). 291 * 292 * @param[in] timer The timer to be resumed. 293 * 294 * @see ecore_timer_freeze() 295 */ 296 EAPI void ecore_timer_thaw(Ecore_Timer *timer); 297 298 #include "efl_loop_timer_eo.legacy.h" 299 300 /** 301 * @} 302 */ 303 304 /** 305 * @addtogroup Ecore_Idle_Group 306 * 307 * @{ 308 */ 309 310 /** 311 * Adds an idler handler. 312 * @param func The function to call when idling. 313 * @param data The data to be passed to this @p func call. 314 * @return A idler handle if successfully added, @c NULL otherwise. 315 * 316 * Add an idler handle to the event loop, returning a handle on 317 * success and @c NULL otherwise. The function @p func will be called 318 * repeatedly while no other events are ready to be processed, as 319 * long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0 320 * (or @c ECORE_CALLBACK_CANCEL) deletes the idler. 321 * 322 * Idlers are useful for progressively processing data without blocking. 323 */ 324 EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data); 325 326 /** 327 * Deletes an idler callback from the list to be executed. 328 * @param idler The handle of the idler callback to delete 329 * @return The data pointer passed to the idler callback on success, @c NULL 330 * otherwise. 331 */ 332 EAPI void *ecore_idler_del(Ecore_Idler *idler); 333 334 /** 335 * Adds an idle enterer handler. 336 * @param func The function to call when entering an idle state. 337 * @param data The data to be passed to the @p func call 338 * @return A handle to the idle enterer callback if successful. Otherwise, 339 * @c NULL is returned. 340 * @note The function func will be called every time the main loop is entering 341 * idle state, as long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0 342 * (or @c ECORE_CALLBACK_CANCEL) deletes the idle enterer. 343 */ 344 EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data); 345 346 /** 347 * Adds an idle enterer handler at the start of the list so it gets called earlier than others. 348 * @param func The function to call when entering an idle state. 349 * @param data The data to be passed to the @p func call 350 * @return A handle to the idle enterer callback if successful. Otherwise, 351 * @c NULL is returned. 352 * @note The function func will be called every time the main loop is entering 353 * idle state, as long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0 354 * (or @c ECORE_CALLBACK_CANCEL) deletes the idle enterer. 355 */ 356 EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data); 357 358 /** 359 * Deletes an idle enterer callback. 360 * @param idle_enterer The idle enterer to delete 361 * @return The data pointer passed to the idler enterer callback on success. 362 * @c NULL otherwise. 363 */ 364 EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer); 365 366 /** 367 * Adds an idle exiter handler. 368 * @param func The function to call when exiting an idle state. 369 * @param data The data to be passed to the @p func call. 370 * @return A handle to the idle exiter callback on success. @c NULL otherwise. 371 * @note The function func will be called every time the main loop is exiting 372 * idle state, as long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0 373 * (or @c ECORE_CALLBACK_CANCEL) deletes the idle exiter. 374 */ 375 EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data); 376 377 /** 378 * Deletes an idle exiter handler from the list to be run on exiting idle state. 379 * @param idle_exiter The idle exiter to delete 380 * @return The data pointer that was being being passed to the handler if 381 * successful. @c NULL otherwise. 382 */ 383 EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); 384 385 /** 386 * @} 387 */ 388 389 /** 390 * @addtogroup Ecore_Exe_Group 391 * 392 * @{ 393 */ 394 395 #include "ecore_exe_eo.legacy.h" 396 397 /** 398 * @} 399 */ 400 401 /** 402 * @addtogroup Ecore_Job_Group 403 * 404 * @{ 405 */ 406 /** 407 * Adds a job to the event queue. 408 * @param func The function to call when the job gets handled. 409 * @param data Data pointer to be passed to the job function when the job is 410 * handled. 411 * @return The handle of the job. @c NULL is returned if the job could not be 412 * added to the queue. 413 * @note Once the job has been executed, the job handle is invalid. 414 */ 415 EAPI Ecore_Job *ecore_job_add(Ecore_Cb func, const void *data); 416 417 /** 418 * Deletes a queued job that has not yet been executed. 419 * @param obj Handle of the job to delete. 420 * @return The data pointer that was to be passed to the job. 421 */ 422 EAPI void *ecore_job_del(Ecore_Job *obj); 423 424 /** 425 * @} 426 */ 427 428 #ifdef EFL_BETA_API_SUPPORT 429 EAPI Ecore_Animator *ecore_evas_animator_timeline_add(void *evo, double runtime, Ecore_Timeline_Cb func, const void *data); 430 EAPI Ecore_Animator *ecore_evas_animator_add(void *evo, Ecore_Task_Cb func, const void *data); 431 #endif /* EFL_BETA_API_SUPPORT */ 432 433 #endif 434