Skip to content

Commit c4f8c7d

Browse files
author
runrevali
committed
[[ LCB Docs ]] Add docs for control structures
1 parent 909932c commit c4f8c7d

File tree

4 files changed

+307
-6
lines changed

4 files changed

+307
-6
lines changed

‎docs/builder/control_st.lcdoc‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
Library: control structures
2+
3+
Name: If
4+
5+
Type: control structure
6+
7+
Syntax:
8+
if <IfCondition> then
9+
<IfStatementList>
10+
[else if <ElseCondition> then
11+
<ElseIfStatementList>]
12+
[else
13+
<ElseStatementList>]
14+
end if
15+
16+
Summary: Executes a list of statements depending on the value of a condition.
17+
18+
Parameters:
19+
IfCondition(bool): An expression which evaluates to a boolean.
20+
IfStatementList: A set of statements.
21+
ElseCondition(bool): An expression which evaluates to a boolean.
22+
ElseIfStatementList: A set of statements.
23+
ElseStatementList: A set of statements.
24+
25+
Description:
26+
Use the if control structure to execute a statement (or list of statements) only under certain circumstances. If <IfCondition> evaluates to true, the statements in <IfStatementList> are executed. For each condition <ElseCondition> such that none of the previous conditions evaluates to true, the condition is evaluated and the corresponding statements in <ElseIfStatementList> are executed. If none of the conditions evaluate to true, the statements in <ElseStatementList> are executed.
27+
28+
Name: RepeatForEach
29+
30+
Type: control structure
31+
32+
Syntax:
33+
repeat for each <Iterator> in <Container>
34+
<StatementList>
35+
end repeat
36+
37+
Summary: Executes a list of statements until the <Iterator> is exhausted.
38+
39+
Parameters:
40+
Iterator: Any iterator expression.
41+
Container: The container over which to iterate.
42+
StatementList: A set of statements.
43+
44+
Example:
45+
variable tElement
46+
variable tNumbers as list
47+
put the empty list into tNumbers
48+
49+
repeat for each element tElement in ["a", 1, 2, 3, "b", "c", 4]
50+
if tElement is a number then
51+
push tElement onto tNumbers
52+
end if
53+
end repeat
54+
55+
// tNumbers contains [1, 2, 3, 4]
56+
57+
Description:
58+
Use the repeat for each control structure to iterate though the chars of a string, bytes of data, elements of a list or array, or keys of an array.
59+
>*Note:* The variable which contains the iterand must be declared prior to being used in the repeat loop.
60+
61+
References: RepeatForEachChar(iterator), RepeatForEachByte(iterator), RepeatForEachKey(iterator), RepeatForEachElementInList(iterator), RepeatForEachElementInArray(iterator)
62+
63+
Name: RepeatForever
64+
65+
Type: control structure
66+
67+
Syntax:
68+
repeat forever
69+
<StatementList>
70+
end repeat
71+
72+
Summary: Executes a list of statements continually.
73+
74+
Parameters:
75+
StatementList: A set of statements.
76+
77+
Example:
78+
variable tCount as number
79+
variable tList as list
80+
put [ 1, 2, 3, 4, 5, 6, 7, 8, "A", 9, 10 ] into tList
81+
put 0 into tCount
82+
repeat forever
83+
if tList[tCount] is not a number then
84+
exit repeat
85+
end if
86+
add 1 to tCount
87+
end repeat
88+
89+
// tCount is 8
90+
91+
Description:
92+
Use the repeat forever structure to execute a set of statements until either an error is thrown, or exit repeat is executed.
93+
94+
Name: RepeatTimes
95+
96+
Type: control structure
97+
98+
Syntax:
99+
repeat <Count> times
100+
<StatementList>
101+
end repeat
102+
103+
Summary: Executes a list of statements a given number of times.
104+
105+
Parameters:
106+
Count(integer): An expression which evaluates to an integer.
107+
StatementList: A set of statements.
108+
109+
Example:
110+
public handler TwoToThePower(in pOperand as integer) as number
111+
112+
if pOperand is 0 then
113+
return 1
114+
end if
115+
116+
variable tCount as number
117+
put the abs of pOperand into tCount
118+
119+
variable tResult as number
120+
put 1 into tResult
121+
repeat tCount times
122+
multiply tResult by 2
123+
end repeat
124+
125+
if pOperand < 0 then
126+
return 1 / tResult
127+
end if
128+
129+
return tResult
130+
end handler
131+
132+
Description:
133+
Use the repeat <Count> times structure to execute a set of statements a given number of times, when the statements executed do not rely on knowing which iteration the repeat loop is on.
134+
135+
Name: RepeatWhile
136+
137+
Type: control structure
138+
139+
Syntax:
140+
repeat while <Condition>
141+
<StatementList>
142+
end repeat
143+
144+
Summary: Executes a list of statements while a condition continues to be true.
145+
146+
Parameters:
147+
Condition(bool): An expression which evaluates to a boolean.
148+
StatementList: A set of statements.
149+
150+
Description:
151+
Use the repeat while <Condition> structure to execute a set of statements repeatedly, while the <Condition> continues to evaluate to true.
152+
153+
Name: RepeatUntil
154+
155+
Type: control structure
156+
157+
Syntax:
158+
repeat until <Condition>
159+
<StatementList>
160+
end repeat
161+
162+
Summary: Executes a list of statements until a condition becomes true.
163+
164+
Parameters:
165+
Condition(bool): An expression which evaluates to a boolean.
166+
StatementList: A set of statements.
167+
168+
Description:
169+
Use the repeat until <Condition> structure to execute a set of statements repeatedly, until the <Condition> evaluates to true.
170+
171+
Name: RepeatWith
172+
173+
Type: control structure
174+
175+
Syntax:
176+
repeat with <Counter> from <Start> ( up | down ) to <Finish> [ by <Step> ]
177+
<StatementList>
178+
end repeat
179+
180+
Summary: Executes a list of statements
181+
182+
Parameters:
183+
Counter: A numeric variable.
184+
Start(number): The initial value of <Counter>
185+
Finish(number): The boundary value of <Counter>
186+
Step(number): The value by which to increase or decrease the <Counter>
187+
StatementList: A set of statements.
188+
189+
Example:
190+
191+
Description:
192+
Use the repeat with <Counter> structure to execute a set of statements until the value of <Counter> reaches or crosses (depending on iteration direction) the value of <Finish>. The counter is increased (or decreased) by <Step> on each iteration of the loop.

‎engine/src/engine.mlc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ end syntax
8282
Summary: Tests the existence of a script object.
8383
Object: An expression that evaluates to a <ScriptObject>.
8484

85-
The result: True if the object <Object> exists, and false otherwise.
85+
Returns: True if the object <Object> exists, and false otherwise.
8686

8787
Example:
8888
variable tObject as ScriptObject
@@ -110,7 +110,7 @@ end syntax
110110
Summary: Tests the existence of a script object.
111111
Object: An expression that evaluates to a <ScriptObject>.
112112

113-
The result: True if the object <Object> exists, and false otherwise.
113+
Returns: True if the object <Object> exists, and false otherwise.
114114

115115
Example:
116116
variable tObject as ScriptObject

‎engine/src/widget.mlc‎

Lines changed: 111 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717
/*
1818
This library consists of the operations on widgets provided by LiveCode Builder.
1919

20+
Tags: Widget
21+
2022
Name: OnOpen
2123
Type: message
2224
Syntax: OnOpen
@@ -320,30 +322,81 @@ public foreign handler MCWidgetEvalInEditMode(out rInEditMode as bool) as undefi
320322
public foreign handler MCWidgetExecDispatch(in pIsFunction as bool, in pMessage as string) as any binds to "<builtin>"
321323
public foreign handler MCWidgetExecDispatchWithArguments(in pIsFunction as bool, in pMessage as string, in pArguments as optional list) as any binds to "<builtin>"
322324

325+
/*
326+
Summary: Redraws the widget.
327+
328+
Example:
329+
330+
Description:
331+
332+
References: OnPaint(message)
333+
*/
334+
323335
syntax RedrawAll is statement
324336
"redraw" "all"
325337
begin
326338
MCWidgetExecRedrawAll()
327339
end syntax
328340

341+
/*
342+
Summary: Schedules a timer.
343+
Time: An expression which evaluates to a number.
344+
345+
Example:
346+
347+
Description:
348+
349+
References: OnTimer(message)
350+
*/
351+
329352
syntax ScheduleTimerIn is statement
330353
"schedule" "timer" "in" <Time: Expression> "seconds"
331354
begin
332355
MCWidgetExecScheduleTimerIn(Time)
333356
end syntax
334357

358+
/*
359+
Summary: Cancels a timer.
360+
361+
Example:
362+
363+
Description:
364+
Use to cancel a timer scheduled by the <ScheduleTimerIn|schedule> statement.
365+
366+
References: OnTimer(message), ScheduleTimerIn(statement)
367+
*/
368+
335369
syntax CancelTimer is statement
336370
"cancel" "timer"
337371
begin
338372
MCWidgetExecCancelTimer()
339373
end syntax
340374

375+
/*
376+
Summary: Determines whether the IDE is in edit mode.
377+
378+
Example:
379+
380+
Description:
381+
382+
*/
383+
384+
341385
syntax IsEditMode is expression
342386
"in" "edit" "mode"
343387
begin
344388
MCWidgetEvalInEditMode(output)
345389
end syntax
346390

391+
/*
392+
Summary: Dispatches a message to the widget script object.
393+
394+
Example:
395+
396+
Description:
397+
398+
*/
399+
347400
syntax Dispatch is statement
348401
"dispatch" ( "function" <IsFunction=true> | "command" <IsFunction=false> | <IsFunction=false> ) <Message: Expression> [ "with" <Arguments: Expression> ]
349402
begin
@@ -363,12 +416,34 @@ public foreign handler MCWidgetSetWidth(in pWidth as real) as undefined binds to
363416
public foreign handler MCWidgetGetHeight(out rHeight as real) as undefined binds to "<builtin>"
364417
public foreign handler MCWidgetSetHeight(in pHeight as real) as undefined binds to "<builtin>"
365418

419+
/*
420+
Summary: Obtains a reference to the widget script object.
421+
422+
Returns: The widget script object.
423+
424+
Example:
425+
426+
Description:
427+
428+
*/
429+
366430
syntax MyScriptObject is expression
367431
"my" "script" "object"
368432
begin
369433
MCWidgetGetScriptObject(output)
370434
end syntax
371435

436+
/*
437+
Summary:
438+
439+
Returns: The rectangle of the widget script object.
440+
441+
Example:
442+
443+
Description:
444+
445+
*/
446+
372447
syntax MyRectangle is expression
373448
"my" "rectangle"
374449
begin
@@ -464,16 +539,50 @@ end syntax
464539
public foreign handler MCWidgetEvalIsPointWithinRect(in pPoint as Point, in pRect as Rectangle, out rWithin as bool) as undefined binds to "<builtin>"
465540
public foreign handler MCWidgetEvalIsPointNotWithinRect(in pPoint as Point, in pRect as Rectangle, out rNotWithin as bool) as undefined binds to "<builtin>"
466541

542+
/*
543+
Summary: Determines whether a point is within a rectangle.
544+
Point: An expression that evaluates to a Point.
545+
Rect: An expression that evaluates to a Rectangle.
546+
547+
Example:
548+
variable tClick as Point
549+
put the click position into tClick
550+
551+
variable tRect as Rectangle
552+
put my bounds into tRect
553+
554+
if tClick is within tRect then
555+
// click was within widget bounds
556+
end if
557+
*/
558+
467559
syntax IsPointWithinRect is neutral binary operator with precedence 5
468560
<mPoint: Expression> "is" "within" <mRect: Expression>
469561
begin
470562
MCWidgetEvalIsPointWithinRect(mPoint, mRect, output)
471563
end syntax
472564

565+
/*
566+
Summary: Determines whether a point is within a rectangle.
567+
Point: An expression that evaluates to a Point.
568+
Rect: An expression that evaluates to a Rectangle.
569+
570+
Example:
571+
variable tClick as Point
572+
put the click position into tClick
573+
574+
variable tRect as Rectangle
575+
put my bounds into tRect
576+
577+
if tClick is not within tRect then
578+
// click was outside of widget bounds
579+
end if
580+
*/
581+
473582
syntax IsPointNotWithinRect is neutral binary operator with precedence 5
474-
<mPoint: Expression> "is not" "within" <mRect: Expression>
583+
<Point: Expression> "is not" "within" <Rect: Expression>
475584
begin
476-
MCWidgetEvalIsPointNotWithinRect(mPoint, mRect, output)
585+
MCWidgetEvalIsPointNotWithinRect(Point, Rect, output)
477586
end syntax
478587

479588
end module

0 commit comments

Comments
 (0)