Skip to content

Commit f6b4844

Browse files
XeduRXeduR
authored
Update timer and transition docs to reflect new features (coronalabs#47)
Update existing documentation and add new documentation for timer and transition libraries to explain the changes introduced in: coronalabs/framework-timer#2 and coronalabs/framework-transition#1
1 parent 64fe863 commit f6b4844

16 files changed

+349
-19
lines changed

‎markdown/api/library/timer/allowIterationsWithinFrame.markdown

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010

1111
## Overview
1212

13-
Changes the behavior of the timer object to provide events as soon as possible instead of waiting until the next frame to execute. The default behavior is `false` meaning that timers fire on frame intervals. Setting this to `true` will enable the events to arrive as soon as possible.
13+
Changes the behavior of the timer object to provide events as soon as possible instead of waiting until the next frame to execute. The default behavior is `false`, meaning that timers fire on frame intervals. Setting this to `true` will enable the events to arrive as soon as possible.
1414

1515
## Syntax
1616

‎markdown/api/library/timer/cancel.markdown

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
## Overview
1414

15-
Cancels a timer operation initiated with [timer.performWithDelay()][api.library.timer.performWithDelay].
15+
Cancels a specific timer or all timers with the same tag that were initiated with [timer.performWithDelay()][api.library.timer.performWithDelay].
1616

1717
<!---
1818
@@ -22,13 +22,36 @@ This function returns two numbers: time remaining ( and number of iterations tha
2222

2323
## Syntax
2424

25-
timer.cancel( timerID )
25+
timer.cancel( whatToCancel )
2626

27-
##### timerID ~^(required)^~
28-
_[Object][api.type.Object]._ Handle returned by the call to [timer.performWithDelay()][api.library.timer.performWithDelay].
27+
##### whatToCancel ~^(required)^~
28+
_[Object][api.type.Object] or [String][api.type.String]._ The timer ID from, or `tag` passed to, [timer.performWithDelay()][api.library.timer.performWithDelay].
2929

3030
## Example
3131

32+
`````lua
33+
local function listener( event )
34+
print( "listener called" )
35+
end
36+
37+
timer1 = timer.performWithDelay( 2000, listener ) -- wait 2 seconds
38+
39+
-- sometime later...
40+
timer.cancel( timer1 )
41+
`````
42+
43+
`````lua
44+
local function listener( event )
45+
print( "listener called" )
46+
end
47+
48+
timer1 = timer.performWithDelay( 2000, listener, "red" ) -- wait 2 seconds
49+
timer2 = timer.performWithDelay( 3000, listener, "blue" ) -- wait 3 seconds
50+
51+
-- sometime later...
52+
timer.cancel( "red" )
53+
`````
54+
3255
`````lua
3356
local t = {}
3457
function t:timer( event )

‎markdown/api/library/timer/cancelAll.markdown

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
2+
# timer.cancelAll()
3+
4+
> --------------------- ------------------------------------------------------------------------------------------
5+
> __Type__ [Function][api.type.Function]
6+
> __Library__ [timer.*][api.library.timer]
7+
> __Revision__ [REVISION_LABEL](REVISION_URL)
8+
> __Keywords__ timer, delay, cancel
9+
> __See also__ [timer.cancel()][api.library.timer.cancel]
10+
> --------------------- ------------------------------------------------------------------------------------------
11+
12+
13+
## Overview
14+
15+
Cancels all timer operations initiated with [timer.performWithDelay()][api.library.timer.performWithDelay].
16+
17+
<!---
18+
19+
This function doesn't return any values.
20+
21+
-->
22+
23+
## Syntax
24+
25+
timer.cancelAll()
26+
27+
28+
## Example
29+
30+
`````lua
31+
local function listener( event )
32+
print( "listener called" )
33+
end
34+
35+
timer1 = timer.performWithDelay( 2000, listener ) -- wait 2 seconds
36+
timer2 = timer.performWithDelay( 3000, listener ) -- wait 3 seconds
37+
38+
-- sometime later...
39+
timer.cancelAll()
40+
`````

‎markdown/api/library/timer/index.markdown

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,18 @@ Timer functions allow calling a function some time in the future rather than imm
1717

1818
#### [timer.cancel()][api.library.timer.cancel]
1919

20+
#### [timer.cancelAll()][api.library.timer.cancel]
21+
2022
#### [timer.pause()][api.library.timer.pause]
2123

24+
#### [timer.pause()][api.library.timer.pauseAll]
25+
2226
#### [timer.performWithDelay()][api.library.timer.performWithDelay]
2327

2428
#### [timer.resume()][api.library.timer.resume]
2529

30+
#### [timer.resume()][api.library.timer.resumeAll]
31+
2632
## Properties
2733

2834
#### [timer.allowIterationsWithinFrame][api.library.timer.allowIterationsWithinFrame]

‎markdown/api/library/timer/pause.markdown

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,16 @@
1313

1414
## Overview
1515

16-
Pauses a timer started with [timer.performWithDelay()][api.library.timer.performWithDelay]. It returns a [number][api.type.Number] that represents the amount of time remaining, in milliseconds.
16+
Pauses a specific timer or all timers with the same tag that were started with [timer.performWithDelay()][api.library.timer.performWithDelay].
17+
18+
If a specific timer is paused, then the function returns a [number][api.type.Number] that represents the amount of time remaining, in milliseconds.
1719

1820
## Syntax
1921

20-
timer.pause( timerId )
22+
timer.pause( whatToPause )
2123

22-
##### timerId ~^(required)^~
23-
_[Table][api.type.Table]._ The timer ID from [timer.performWithDelay()][api.library.timer.performWithDelay].
24+
##### whatToPause ~^(required)^~
25+
_[Object][api.type.Object] or [String][api.type.String]._ The timer ID from, or `tag` passed to, [timer.performWithDelay()][api.library.timer.performWithDelay].
2426

2527
## Example
2628

@@ -35,3 +37,15 @@ timer1 = timer.performWithDelay( 2000, listener ) -- wait 2 seconds
3537
local result = timer.pause( timer1 )
3638
print( "Time remaining is " .. result )
3739
`````
40+
41+
`````lua
42+
local function listener( event )
43+
print( "listener called" )
44+
end
45+
46+
timer1 = timer.performWithDelay( 2000, listener, "red" ) -- wait 2 seconds
47+
timer2 = timer.performWithDelay( 3000, listener, "blue" ) -- wait 3 seconds
48+
49+
-- sometime later...
50+
timer.pause( "red" )
51+
`````

‎markdown/api/library/timer/pauseAll.markdown

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
2+
# timer.pauseAll()
3+
4+
> --------------------- ------------------------------------------------------------------------------------------
5+
> __Type__ [Function][api.type.Function]
6+
> __Library__ [timer.*][api.library.timer]
7+
> __Revision__ [REVISION_LABEL](REVISION_URL)
8+
> __Keywords__ timer, pause, resume
9+
> __See also__ [timer.pause()][api.library.timer.pause]
10+
> --------------------- ------------------------------------------------------------------------------------------
11+
12+
13+
## Overview
14+
15+
Pauses all timers started with [timer.performWithDelay()][api.library.timer.performWithDelay].
16+
17+
## Syntax
18+
19+
timer.pauseAll( timerId )
20+
21+
22+
## Example
23+
24+
`````lua
25+
local function listener( event )
26+
print( "listener called" )
27+
end
28+
29+
timer1 = timer.performWithDelay( 2000, listener ) -- wait 2 seconds
30+
timer2 = timer.performWithDelay( 3000, listener ) -- wait 3 seconds
31+
32+
-- sometime later...
33+
timer.pauseAll()
34+
`````

‎markdown/api/library/timer/performWithDelay.markdown

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Timers will __not__ be automatically cancelled when changing a scene. Thus, if y
2727

2828
## Syntax
2929

30-
timer.performWithDelay( delay, listener [, iterations] )
30+
timer.performWithDelay( delay, listener [, iterations] [, tag] )
3131

3232
##### delay ~^(required)^~
3333
_[Number][api.type.Number]._ The delay in milliseconds, for example, `1000` = 1 second. Note that timers cannot execute faster than the runtime framerate of the app. For example, if the framerate of the app is `60` frames per second, as defined in the `config.lua` file \([guide][guide.basics.configSettings]\), the shortest delay for a timer is approximately `16.667` milliseconds <nobr>(`1000`/`60` = ~`16.667`)</nobr>.
@@ -36,7 +36,10 @@ _[Number][api.type.Number]._ The delay in milliseconds, for example, `1000` = 1
3636
_[Listener][api.type.Listener]._ The listener to invoke after the delay. This may be either a function listener or a table listener. If a table listener, it must have a timer method because timer events are sent to the listener.
3737

3838
##### iterations ~^(optional)^~
39-
_[Number][api.type.Number]._ Optionally specifies the number of times `listener` is to be invoked. By default, it is `1`; pass `0` or `-1` if you want the timer to loop forever.
39+
_[Number][api.type.Number]._ Optionally specify the number of times `listener` is to be invoked. By default, it is `1`; pass `0` or `-1` if you want the timer to loop forever.
40+
41+
##### tag ~^(optional)^~
42+
_[String][api.type.String]._ Optionally assign a `tag` to the timer. You can pause, resume or cancel all timers that share the same `tag` with a single function call.
4043

4144

4245
## Examples

‎markdown/api/library/timer/resume.markdown

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,16 @@
1313

1414
## Overview
1515

16-
Resumes a timer that was paused with [timer.pause()][api.library.timer.pause]. It returns a [number][api.type.Number] that represents the amount of time remaining in the timer.
16+
Resumes a specific timer or all timers with the same tag that were paused with [timer.pause()][api.library.timer.pause].
17+
18+
If a specific timer is resumed, then the function returns a [number][api.type.Number] that represents the amount of time remaining in the timer.
1719

1820
## Syntax
1921

20-
timer.resume( timerId )
22+
timer.resume( whatToResume )
2123

22-
##### timerId ~^(required)^~
23-
_[Object][api.type.Object]._ The timer ID from [timer.performWithDelay()][api.library.timer.performWithDelay].
24+
##### whatToResume ~^(required)^~
25+
_[Object][api.type.Object] or [String][api.type.String]._ The timer ID from, or `tag` passed to, [timer.performWithDelay()][api.library.timer.performWithDelay].
2426

2527

2628
## Example
@@ -40,3 +42,18 @@ print( "Time remaining is " .. pauseTime )
4042
local resumeTime = timer.resume( timer1 )
4143
print( "Resume time is " .. resumeTime )
4244
`````
45+
46+
`````lua
47+
local function listener( event )
48+
print( "listener called" )
49+
end
50+
51+
timer1 = timer.performWithDelay( 2000, listener, "red" ) -- wait 2 seconds
52+
timer2 = timer.performWithDelay( 3000, listener, "blue" ) -- wait 3 seconds
53+
54+
-- sometime later...
55+
timer.pause( "red" )
56+
57+
-- sometime later...
58+
timer.resume( "red" )
59+
`````

‎markdown/api/library/timer/resumeAll.markdown

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
2+
# timer.resumeAll()
3+
4+
> --------------------- ------------------------------------------------------------------------------------------
5+
> __Type__ [Function][api.type.Function]
6+
> __Library__ [timer.*][api.library.timer]
7+
> __Revision__ [REVISION_LABEL](REVISION_URL)
8+
> __Keywords__ timer, resume, pause
9+
> __See also__ [timer.resume()][api.library.timer.resume]
10+
> --------------------- ------------------------------------------------------------------------------------------
11+
12+
13+
## Overview
14+
15+
Resumes all timers that were paused with [timer.pause()][api.library.timer.pause].
16+
17+
## Syntax
18+
19+
timer.resumeAll()
20+
21+
22+
## Example
23+
24+
`````lua
25+
local function listener( event )
26+
print( "listener called" )
27+
end
28+
29+
timer1 = timer.performWithDelay( 2000, listener ) -- wait 2 seconds
30+
timer2 = timer.performWithDelay( 3000, listener ) -- wait 3 seconds
31+
32+
-- sometime later...
33+
timer.pauseAll()
34+
35+
-- sometime later...
36+
timer.resumeAll()
37+
`````

‎markdown/api/library/transition/cancel.markdown

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ _[String][api.type.String]._ The tag name; all transitions with this tag will be
4040
## Examples
4141

4242
``````lua
43-
-- cancel all running transitions
43+
-- cancel all running (and paused) transitions
4444

4545
local transition1 = transition.to( currentTarget, { time=400, y=y+100, iterations=5, tag="transTag" } )
4646
local transition2 = transition.to( otherTarget, { time=200, y=y-200, tag="transTag" } )

0 commit comments

Comments
 (0)