7889 lines
256 KiB
Plaintext
7889 lines
256 KiB
Plaintext
& This is the data file for the help syntax of the yab-IDE 2.0
|
|
& DO NOT CHANGE ANYTHING IN THIS FILE (unless you do a reindexing!)
|
|
&
|
|
& Comments start at the beginning of the line with a &
|
|
&
|
|
& Here the top level starts with the keyword:
|
|
& toplevel
|
|
Arithmetic
|
|
Conditions and Loops
|
|
Data Processing
|
|
Input and Output
|
|
Graphical User Interface
|
|
&Localization
|
|
Sound
|
|
String Handling
|
|
Subroutines
|
|
System
|
|
& Here the sub levels start (they are added as TREEBOX ADD adds).
|
|
& sublevel
|
|
Arithmetic:** or ^
|
|
Arithmetic:xor()
|
|
Arithmetic:tan()
|
|
Arithmetic:sqrt()
|
|
Arithmetic:sqr()
|
|
Arithmetic:sin()
|
|
Arithmetic:sig()
|
|
Arithmetic:ran()
|
|
Arithmetic:pi
|
|
Arithmetic:or()
|
|
Arithmetic:mod()
|
|
Arithmetic:min()
|
|
Arithmetic:max()
|
|
Arithmetic:log()
|
|
Arithmetic:int()
|
|
Arithmetic:frac()
|
|
Arithmetic:exp()
|
|
Arithmetic:euler
|
|
Arithmetic:eor()
|
|
Arithmetic:dec()
|
|
Arithmetic:cos()
|
|
Arithmetic:bin$()
|
|
Arithmetic:atan()
|
|
Arithmetic:asin()
|
|
Arithmetic:and()
|
|
Arithmetic:acos()
|
|
Arithmetic:abs()
|
|
Conditions and Loops:while
|
|
Conditions and Loops:wend
|
|
Conditions and Loops:until
|
|
Conditions and Loops:true
|
|
Conditions and Loops:then
|
|
Conditions and Loops:switch
|
|
Conditions and Loops:step
|
|
Conditions and Loops:return
|
|
Conditions and Loops:repeat
|
|
Conditions and Loops:logical or
|
|
Conditions and Loops:on interrupt
|
|
Conditions and Loops:on goto
|
|
Conditions and Loops:on gosub
|
|
Conditions and Loops:not
|
|
Conditions and Loops:next
|
|
Conditions and Loops:loop
|
|
Conditions and Loops:label
|
|
Conditions and Loops:if
|
|
Conditions and Loops:goto
|
|
Conditions and Loops:gosub
|
|
Conditions and Loops:for
|
|
Conditions and Loops:fi
|
|
Conditions and Loops:false
|
|
Conditions and Loops:endif
|
|
Conditions and Loops:end
|
|
Conditions and Loops:elsif
|
|
Conditions and Loops:else
|
|
Conditions and Loops:do
|
|
Conditions and Loops:default
|
|
Conditions and Loops:continue
|
|
Conditions and Loops:case
|
|
Conditions and Loops:break
|
|
Conditions and Loops:and
|
|
Data Processing:restore
|
|
Data Processing:redim
|
|
Data Processing:read
|
|
Data Processing:dim
|
|
Data Processing:data
|
|
Data Processing:arraysize()
|
|
Data Processing:arraydim()
|
|
Input and Output:;
|
|
Input and Output:using
|
|
Input and Output:tell
|
|
Input and Output:seek()
|
|
Input and Output:screen
|
|
Input and Output:reverse
|
|
Input and Output:putscreen
|
|
Input and Output:print
|
|
Input and Output:open
|
|
Input and Output:line input
|
|
Input and Output:input
|
|
Input and Output:inkey$
|
|
Input and Output:getscreen$()
|
|
Input and Output:eof
|
|
Input and Output:colour
|
|
Input and Output:color
|
|
Input and Output:close
|
|
Input and Output:clear screen
|
|
Input and Output:at()
|
|
Graphical User Interface:Window
|
|
Window :window set
|
|
Window :window open
|
|
Window :window get
|
|
Window :window count
|
|
Window :window close
|
|
Window :filepanel
|
|
Window :alert
|
|
Graphical User Interface:Widgets
|
|
Widgets:Treebox
|
|
Treebox:treebox sort
|
|
Treebox:treebox select
|
|
Treebox:treebox remove
|
|
Treebox:treebox get$
|
|
Treebox:treebox expand
|
|
Treebox:treebox count
|
|
Treebox:treebox collapse
|
|
Treebox:treebox clear
|
|
Treebox:treebox add
|
|
Treebox:treebox
|
|
Widgets:Tooltip
|
|
Tooltip:tooltip color
|
|
Tooltip:tooltip
|
|
Widgets:TextURL
|
|
TextURL:texturl color
|
|
TextURL:texturl
|
|
Widgets:Textedit
|
|
Textedit:textedit set
|
|
Textedit:textedit get$
|
|
Textedit:textedit get
|
|
Textedit:textedit color
|
|
Textedit:textedit clear
|
|
Textedit:textedit add
|
|
Textedit:textedit
|
|
Widgets:Textcontrol
|
|
Textcontrol:textcontrol set
|
|
Textcontrol:textcontrol get$
|
|
Textcontrol:textcontrol clear
|
|
Textcontrol:textcontrol
|
|
Widgets:Text
|
|
Text:text set
|
|
Text:text
|
|
Widgets:Statusbar
|
|
Statusbar:statusbar set
|
|
Statusbar:statusbar
|
|
Widgets:Spincontrol
|
|
Spincontrol:spincontrol set
|
|
Spincontrol:spincontrol get
|
|
Spincontrol:spincontrol
|
|
Widgets:Slider
|
|
Slider:slider set
|
|
Slider:slider label
|
|
Slider:slider get
|
|
Slider:slider hashmarks
|
|
Slider:slider color
|
|
Slider:slider
|
|
Widgets:Radiobutton
|
|
Radiobutton:radiobutton set
|
|
Radiobutton:radiobutton
|
|
Widgets:Options
|
|
Options:option set
|
|
Options:option color
|
|
Widgets:Listbox
|
|
Listbox:listbox sort
|
|
Listbox:listbox select
|
|
Listbox:listbox remove
|
|
Listbox:listbox get$
|
|
Listbox:listbox get
|
|
Listbox:listbox count
|
|
Listbox:listbox clear
|
|
Listbox:listbox add
|
|
Listbox:listbox
|
|
Widgets:Dropbox
|
|
Dropbox:dropbox select
|
|
Dropbox:dropbox remove
|
|
Dropbox:dropbox get$
|
|
Dropbox:dropbox count
|
|
Dropbox:dropbox clear
|
|
Dropbox:dropbox add
|
|
Dropbox:dropbox
|
|
Widgets:Columnbox
|
|
Columnbox:columnbox select
|
|
Columnbox:columnbox remove
|
|
Columnbox:columnbox get$
|
|
Columnbox:columnbox get
|
|
Columnbox:columnbox count
|
|
Columnbox:columnbox column
|
|
Columnbox:columnbox color
|
|
Columnbox:columnbox clear
|
|
Columnbox:columnbox add
|
|
Columnbox:columnbox
|
|
Widgets:Colorcontrol
|
|
Colorcontrol:colorcontrol set
|
|
Colorcontrol:colorcontrol get
|
|
Colorcontrol:colorcontrol
|
|
Widgets:Checkbox
|
|
Checkbox:checkbox set
|
|
Checkbox:checkbox image
|
|
Checkbox:checkbox
|
|
Widgets:Calendar
|
|
Calendar:calendar set
|
|
Calendar:calendar get$
|
|
Calendar:calendar
|
|
Widgets:Button
|
|
Button:button image
|
|
Button:button
|
|
Graphical User Interface:Views
|
|
Views:View
|
|
View :view remove
|
|
View :view get
|
|
View :view dropzone
|
|
View :view
|
|
Views:Tabview
|
|
Tabview:tabview set
|
|
Tabview:tabview get
|
|
Tabview:tabview add
|
|
Tabview:tabview
|
|
Views:Stackview
|
|
Stackview:stackview set
|
|
Stackview:stackview get
|
|
Stackview:stackview
|
|
Views:Splitview
|
|
Splitview:splitview set
|
|
Splitview:splitview get
|
|
Splitview:splitview
|
|
Views:Scrollbar
|
|
Scrollbar:scrollbar set
|
|
Scrollbar:scrollbar get
|
|
Scrollbar:scrollbar
|
|
Views:layout
|
|
Views:boxview
|
|
Graphical User Interface:Printing
|
|
Printing:printer setup
|
|
Printing:printer
|
|
Graphical User Interface:Menus
|
|
Menus:submenu set
|
|
Menus:submenu
|
|
Menus:popupmenu
|
|
Menus:menu set
|
|
Menus:menu
|
|
Graphical User Interface:Input and Messages
|
|
Input and Messages:shortcut
|
|
Input and Messages:mouse set
|
|
Input and Messages:mousemove$
|
|
Input and Messages:mouse message$()
|
|
Input and Messages:message send
|
|
Input and Messages:message$
|
|
Input and Messages:keyboard message$()
|
|
Input and Messages:ismousein()
|
|
Graphical User Interface:Drawing
|
|
Drawing:draw text
|
|
Drawing:draw set
|
|
Drawing:draw rect
|
|
Drawing:draw line
|
|
Drawing:draw image
|
|
Drawing:draw get$
|
|
Drawing:draw get
|
|
Drawing:draw flush
|
|
Drawing:draw ellipse
|
|
Drawing:draw dot
|
|
Drawing:draw curve
|
|
Drawing:draw circle
|
|
Drawing:draw bitmap
|
|
Graphical User Interface:Bitmaps
|
|
Bitmaps:screenshot
|
|
Bitmaps:canvas
|
|
Bitmaps:bitmap save
|
|
Bitmaps:bitmap remove
|
|
Bitmaps:bitmap get
|
|
Bitmaps:bitmap
|
|
&Localization:translate$()
|
|
&Localization:localize
|
|
Sound:sound wait
|
|
Sound:sound stop
|
|
Sound:sound play
|
|
Sound:bell
|
|
Sound:beep
|
|
String Handling:val()
|
|
String Handling:upper$()
|
|
String Handling:trim$()
|
|
String Handling:token()
|
|
String Handling:str$()
|
|
String Handling:split()
|
|
String Handling:rtrim$()
|
|
String Handling:right$()
|
|
String Handling:mid$()
|
|
String Handling:ltrim$()
|
|
String Handling:lower$()
|
|
String Handling:len()
|
|
String Handling:left$()
|
|
String Handling:instr()
|
|
String Handling:hex$()
|
|
String Handling:glob()
|
|
String Handling:chr$()
|
|
String Handling:asc()
|
|
Subroutines:sub
|
|
Subroutines:static
|
|
Subroutines:return
|
|
Subroutines:numparams
|
|
Subroutines:local
|
|
Subroutines:import
|
|
Subroutines:export
|
|
Subroutines:end sub
|
|
System::
|
|
System:#
|
|
System://
|
|
System:wait
|
|
System:to
|
|
System:time$
|
|
System:thread remove
|
|
System:thread get
|
|
System:system()
|
|
System:system$()
|
|
System:sleep
|
|
System:rem
|
|
System:poke
|
|
System:peek$
|
|
System:peek
|
|
System:pause
|
|
System:iscomputeron
|
|
System:exit
|
|
System:execute()
|
|
System:execute$()
|
|
System:error
|
|
System:docu$
|
|
System:doc
|
|
System:date$
|
|
System:compile
|
|
System:clipboard copy
|
|
System:clipboard paste$
|
|
System:bind()
|
|
&
|
|
& Information texts (info texts for short) are separated by
|
|
& comment lines. The file must end with a comment line!
|
|
&
|
|
& The info texts start here:
|
|
& infotext
|
|
&Arithmetic
|
|
&
|
|
abs()
|
|
|
|
Name:
|
|
abs() -- returns the absolute value of its numeric argument
|
|
|
|
Synopsis:
|
|
y=abs(x)
|
|
|
|
Description:
|
|
If the argument of the abs-function is positive (e.g. 2) it is returned unchanged, if the argument is negative (e.g. -1) it is returned as a positive value (e.g. 1).
|
|
|
|
Example:
|
|
print abs(-2),abs(2)
|
|
Explanation:
|
|
|
|
This example will print 2 2
|
|
|
|
|
|
Related: sig
|
|
|
|
&
|
|
acos()
|
|
|
|
Name:
|
|
acos() -- returns the arcus cosine of its numeric argument
|
|
|
|
Synopsis:
|
|
x=acos(angle)
|
|
|
|
Description:
|
|
The acos is the arcus cosine-function, i.e. the inverse of the cos-function. Or, more elaborate: It Returns the angle (in radian, not degree!), which, fed to the cosine-function will produce the argument passed to the acos-function.
|
|
|
|
Example:
|
|
print acos(0.5),acos(cos(pi))
|
|
Explanation:
|
|
|
|
This example will print 1.0472 3.14159 which are pi/3 and pi respectively.
|
|
|
|
|
|
Related: cos, asin
|
|
|
|
&
|
|
and()
|
|
|
|
Name:
|
|
and() -- the bitwise arithmetic and
|
|
|
|
Synopsis:
|
|
x=and(a,b)
|
|
|
|
Description:
|
|
Used to compute the bitwise and of both its argument. Both arguments are treated as binary numbers (i.e. a series of 0 and 1); a bit of the resultingvalue will then be 1, if both arguments have a 1 at this position in their binary representation.
|
|
Note, that both arguments are silently converted to integer values and that negative numbers have their own binary representation and may leadto unexpected results when passed to and.
|
|
|
|
Example:
|
|
print and(6,3)
|
|
Explanation:
|
|
|
|
This will print 2. This result is clear, if you note, that the binary representation of 6 and 3 are 110 and 011 respectively; this will yield 010 in binary representaion or 2 as decimal.
|
|
|
|
|
|
Related: or, eor, xor, not
|
|
|
|
&
|
|
asin()
|
|
|
|
Name:
|
|
asin() -- returns the arcus sine of its numeric argument
|
|
|
|
Synopsis:
|
|
angle=asin(x)
|
|
|
|
Description:
|
|
The acos is the arcus sine-function, i.e. the inverse of the sin-function. Or, more elaborate: It Returns the angle (in radian, not degree!), which,fed to the sine -function will produce the argument passed to the asin-function.
|
|
|
|
Example:
|
|
print asin(0.5),asin(sin(pi))
|
|
Explanation:
|
|
|
|
This will print 0.523599 -2.06823e-13 which is pi/6 and almost 0 respectively.
|
|
|
|
|
|
Related: sin, acos
|
|
|
|
&
|
|
atan()
|
|
|
|
Name:
|
|
atan() -- returns the arcus tangens of its numeric argument
|
|
|
|
Synopsis:
|
|
angle=atan(a,b)
|
|
angle=atan(a)
|
|
|
|
Description:
|
|
The atan is the arcus-tangens-function, i.e. the inverse of the tan-function. Or, more elaborate: It Returns the angle (in radian, not degree!), which, fed to the tan-function will produce the argument passed to the atan-function.
|
|
The atan-function has a second form, which accepts two arguments: atan(a,b) which is (mostly) equivilantly to atan(a/b) except for the fact, that the two-argument-form returns an angle in the range -pi to pi, whereas the one-argument-form returns an angle in the range -pi/2 to pi/2. To understand this you have to be good at math.
|
|
|
|
Example:
|
|
print atan(1),atan(tan(pi)),atan(-0,-1),atan(-0,1)
|
|
Explanation:
|
|
|
|
This will print 0.785398 2.06823e-13 -3.14159 3.14159 which is pi/4, almost 0, -pi and pi respectively.
|
|
|
|
|
|
Related: tan, sin
|
|
|
|
&
|
|
bin$()
|
|
|
|
Name:
|
|
bin$() -- converts a number into a sequence of binary digits
|
|
|
|
Synopsis:
|
|
hexadecimal$=bin$(decimal)
|
|
|
|
Description:
|
|
The bin$-function takes a single numeric argument an converts it into a stringof binary digits (i.e. zeroes and ones). If you pass a negative number to bin$, the resulting string will be preceeded by a '-'.
|
|
If you want to convert the other way around (i.e. from binary to decimal) you may use the dec-function.
|
|
|
|
Example:
|
|
for a=1 to 100
|
|
print bin$(a)
|
|
next a
|
|
Explanation:
|
|
|
|
This example prints the binary representation of all digits between 1 and 100.
|
|
|
|
|
|
Related: hex$, dec
|
|
|
|
&
|
|
cos()
|
|
|
|
Name:
|
|
cos() -- return the cosine of its single argument
|
|
|
|
Synopsis:
|
|
x=cos(angle)
|
|
|
|
Description:
|
|
The cos-function expects an angle (in radian) and returns its cosine.
|
|
|
|
Example:
|
|
print cos(pi)
|
|
Explanation:
|
|
|
|
This example will print -1.
|
|
|
|
|
|
Related: acos, sin
|
|
|
|
&
|
|
dec()
|
|
|
|
Name:
|
|
dec() -- convert a base 2 or base 16 number into decimal form
|
|
|
|
Synopsis:
|
|
a=dec(number$)
|
|
a=dec(number$,base)
|
|
|
|
Description:
|
|
The dec-function takes the string-representation of a base-2 or base-16 (which is the default) number and converts it into a decimal number. The optional second argument (base) might be used to specify a base other than 16. However, currently only base 2 or base 16 are supported.
|
|
|
|
Example:
|
|
input "Please enter a binary number: " a$
|
|
print a$," is ",dec(a$)
|
|
Related: bin$, hex$
|
|
|
|
&
|
|
eor()
|
|
|
|
Name:
|
|
eor() -- compute the bitwise exclusive or of its two arguments
|
|
|
|
Synopsis:
|
|
print eor(a,b)
|
|
|
|
Description:
|
|
The eor-function takes two arguments and computes their bitwise exclusive or. See your favorite introductory text on informatics for an explanation of this function.
|
|
The xor-function is the same as the eor function; both are synonymous; however they have each their own description, so you may check out the entry of xor for a slightly different view.
|
|
|
|
Example:
|
|
for a=0 to 3
|
|
for b=0 to 3
|
|
print fill$(bin$(a))," eor ",fill$(bin$(b))," = ",fill$(bin$(eor(a,b)))
|
|
next b
|
|
next a
|
|
|
|
sub fill$(a$)
|
|
return right$("0"+a$,2)
|
|
end sub
|
|
Explanation:
|
|
|
|
This example prints a table, from which you may figure, how the eor-function is computed.
|
|
|
|
Related: and, or
|
|
|
|
&
|
|
euler
|
|
|
|
Name:
|
|
euler -- another name for the constant 2.71828182864
|
|
|
|
Synopsis:
|
|
foo=euler
|
|
|
|
Description:
|
|
euler is the well known constant named after Leonard Euler; its value is 2.71828182864. euler is not a function, so parens are not allowed (i.e. euler() will produce an error). Finally, you may not assign to euler; it wouldn't sense anyway, because it is a constant.
|
|
|
|
Example:
|
|
print euler
|
|
Related: pi
|
|
|
|
&
|
|
exp()
|
|
|
|
Name:
|
|
exp() -- compute the exponential function of its single argument
|
|
|
|
Synopsis:
|
|
foo=exp(bar)
|
|
|
|
Description:
|
|
This function computes e to the power of its argument, where e is the well known euler constant 2.71828182864. The exp-function is the inverse of the log-function.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
for x=-100 to 100
|
|
draw dot x,100-100*exp(x/100)/euler, "Example"
|
|
next x
|
|
sleep 5
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This program plots part of the exp-function, however the range is rather small, so that you may not recognize the function from this plot.
|
|
|
|
Related: log
|
|
|
|
&
|
|
frac()
|
|
|
|
Name:
|
|
frac() -- return the fractional part of its numeric argument
|
|
|
|
Synopsis:
|
|
x=frac(y)
|
|
|
|
Description:
|
|
The frac-function takes its argument, removes all the digits to the left of the comma and just returns the digits right of the comma, i.e. the fractional part. Refer to the example to learn how to rewrite frac by employing the int-function.
|
|
|
|
Example:
|
|
for a=1 to 10
|
|
print frac(sqr(a))
|
|
print sqr(a)-int(sqr(a))
|
|
next a
|
|
Explanation:
|
|
|
|
The example prints the fractional part of the square root of the numbers between 1 and 10.
|
|
Each result is computed (and printed) twice: Once by employing the frac-function and once by employing the int-function.
|
|
|
|
|
|
Related: int
|
|
|
|
&
|
|
int()
|
|
|
|
Name:
|
|
int() -- return the integer part of its single numeric argument
|
|
|
|
Synopsis:
|
|
print int(a)
|
|
|
|
Description:
|
|
The int-function returns only the digits before the comma; int(2.5) returns 2 and int(-2.3) returns -2.
|
|
|
|
Example:
|
|
input "Please enter a whole number between 1 and 10: " a
|
|
if (a=int(a) and a>=1 and a<=10) then
|
|
print "Thanx!"
|
|
else
|
|
print "Never mind ..."
|
|
endif
|
|
Related: frac
|
|
|
|
&
|
|
log()
|
|
|
|
Name:
|
|
log() -- compute the natural logarithm
|
|
|
|
Synopsis:
|
|
a=log(x)
|
|
a=log(x,base)
|
|
|
|
Description:
|
|
The log-function computes the logarithm of its first argument. The optional second argument gives the base for the logarithm; if this second argument is omitted, the euler-constant 2.71828... will be taken as the base.
|
|
|
|
Example:
|
|
window open 200,200 to 400,400, "Example", "Example"
|
|
draw set 0, "highsolidfill"
|
|
for x=10 to 190 step 10
|
|
for y=10 to 190 step 10
|
|
r=3*log(1+x,1+y)
|
|
if (r>10) r=10
|
|
if (r<1) r=1
|
|
draw circle x,y,r, "Example"
|
|
next y
|
|
next x
|
|
sleep 5
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This draws another nice plot.
|
|
|
|
|
|
Related: exp
|
|
|
|
&
|
|
max()
|
|
|
|
Name:
|
|
max() -- return the larger of its two arguments
|
|
|
|
Synopsis:
|
|
print max(a,b)
|
|
|
|
Description:
|
|
Return the maximum of its two arguments.
|
|
|
|
Example:
|
|
dim m(10)
|
|
for a=1 to 1000
|
|
m=0
|
|
for b=1 to 10
|
|
m=max(m,ran(10))
|
|
next b
|
|
m(m)=m(m)+1
|
|
next a
|
|
|
|
for a=1 to 9
|
|
print a,": ",m(a)
|
|
next a
|
|
Explanation:
|
|
|
|
Within the inner for-loop (the one with the loop-variable b), the example computes the maximum of 10 random numbers. The outer loop (with the loop variable a) now repeats this process 1000 times and counts, how often each maximum appears. The last loop finally reports the result.
|
|
Now, the interesting question would be, which will be approached, when we increase the number of iterations from thousend to infinity. Well, maybe someone could just tell me :-)
|
|
|
|
Related: min
|
|
|
|
&
|
|
min()
|
|
|
|
Name:
|
|
min() -- return the smaller of its two arguments
|
|
|
|
Synopsis:
|
|
print min(a,b)
|
|
|
|
Description:
|
|
Return the minimum of its two argument.
|
|
|
|
Example:
|
|
dim m(10)
|
|
for a=1 to 1000
|
|
m=min(ran(10),ran(10))
|
|
m(m)=m(m)+1
|
|
next a
|
|
|
|
for a=1 to 9
|
|
print a,": ",m(a)
|
|
next a
|
|
Explanation:
|
|
|
|
For each iteration of the loop, the lower of two random number is recorded. The result is printed at the end.
|
|
|
|
|
|
Related: max
|
|
|
|
&
|
|
mod()
|
|
|
|
Name:
|
|
mod() -- compute the remainder of a division
|
|
|
|
Synopsis:
|
|
print mod(a,b)
|
|
|
|
Description:
|
|
The mod-function divides its two arguments and computes the remainder. Note, that a/b-int(a/b) and mod(a,b) are always equal.
|
|
|
|
Example:
|
|
clear screen
|
|
print at(10,10) "Please wait "
|
|
p$="-\|/"
|
|
for a=1 to 100
|
|
rem ... do something lengthy here, or simply sleep :-)
|
|
pause(1)
|
|
print at(22,10) mid$(p$,1+mod(a,4))
|
|
next a
|
|
Explanation:
|
|
|
|
This example executes some time consuming action within a loop (in fact, it simply sleeps) and gives the user some indication of progress by displaying a turning bar (thats where the mod()-function comes into play).
|
|
Start this program in a terminal.
|
|
|
|
|
|
Related: int, frac
|
|
|
|
&
|
|
or()
|
|
|
|
Name:
|
|
or() -- arithmetic or, used for bit-operations
|
|
|
|
Synopsis:
|
|
x=or(a,b)
|
|
|
|
Description:
|
|
Used to compute the bitwise or of both its argument. Both arguments are treated as binary numbers (i.e. a series of 0 and 1); a bit of the resulting value will then be 1, if any of its arguments has 1 at this position in theirbinary representation.
|
|
Note, that both arguments are silently converted to integer values and that negative numbers have their own binary representation and may lead to unexpected results when passed to or.
|
|
|
|
Example:
|
|
print or(14,3)
|
|
Explanation:
|
|
|
|
This will print 15. This result is clear, if you note, that the binary representation of 14 and 3 are 1110 and 0011 respectively; this will yield 1111 in binary representaion or 15 as decimal.
|
|
|
|
Related: and, eor, xor, not
|
|
|
|
&
|
|
pi
|
|
|
|
Name:
|
|
pi -- a constant with the value 3.14159
|
|
|
|
Synopsis:
|
|
print pi
|
|
|
|
Description:
|
|
pi is 3.14159265359 (well at least for yab); do not try to assign to pi (e.g. pi=22/7)this would not only be mathematically dubious, but would also result in a syntax error.
|
|
|
|
Example:
|
|
for a=0 to 180
|
|
print "The sine of ",a," degrees is ",sin(a*pi/180)
|
|
next a
|
|
Explanation:
|
|
|
|
This program uses pi to transform an angle from degrees into radians.
|
|
|
|
|
|
Related: euler
|
|
|
|
&
|
|
ran()
|
|
|
|
Name:
|
|
ran() -- return a random number
|
|
|
|
Synopsis:
|
|
print ran()
|
|
x=ran(y)
|
|
|
|
Description:
|
|
The ran-function returns a random number. If no argument is given, the number returned is in the range from 0 to 1; where only 0 is a possible value; 1 will never be returned. If an argument is supplied, the number returned will be in the range from 0 up to this argument, whereas this argument itself is not a possible return value.
|
|
|
|
Example:
|
|
clear screen
|
|
c=peek("screenwidth")-1
|
|
l=peek("screenheight")
|
|
|
|
dim col$(8)
|
|
for a=0 to 7
|
|
read col$(a)
|
|
next a
|
|
|
|
do
|
|
x=ran(c)
|
|
y=l-ran(l*exp(-32*((x/c-1/2)**2)))
|
|
i=i+1
|
|
print color(col$(mod(i,8))) at(x,y) "*"
|
|
loop
|
|
|
|
data "black","white","red","blue","green","yellow","cyan","magenta"
|
|
Explanation:
|
|
|
|
This example will print a cloured bell-curve. Start this program in a terminal.
|
|
|
|
|
|
Related: int
|
|
|
|
&
|
|
sig()
|
|
|
|
Name:
|
|
sig() -- return the sign of its argument
|
|
|
|
Synopsis:
|
|
a=sig(b)
|
|
|
|
Description:
|
|
Return +1, -1 or 0, if the single argument is positive, negative or zero.
|
|
|
|
Example:
|
|
clear screen
|
|
dim c$(3):c$(1)="red":c$(2)="white":c$(3)="green"
|
|
do
|
|
num=ran(100)-50
|
|
print color(c$(2+sig(num))) num
|
|
loop
|
|
Explanation:
|
|
|
|
This program prints an infinite sequence of random number; positive numbers are printed in green, negative numbers are printed red (an exact zero would be printed white). (With a little extra work, this program could be easily extended into a brogerage system).
|
|
|
|
Start this program in a terminal.
|
|
|
|
|
|
Related: abs, int, frac
|
|
|
|
&
|
|
sin()
|
|
|
|
Name:
|
|
sin() -- return the sine of its single argument
|
|
|
|
Synopsis:
|
|
y=sin(angle)
|
|
|
|
Description:
|
|
The sin-function expects an angle (in radian, not degree) and returns its sine.
|
|
|
|
Example:
|
|
window open 200,200 to 400,400, "Example", "Example"
|
|
for phi=0 to 2*pi step 0.1
|
|
draw line 100+90*sin(phi-0.1),100+90*cos(phi-0.1) to 100+90*sin(phi),100+90*cos(phi), "Example"
|
|
next phi
|
|
sleep 5
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This program draws a circle (ignoring the existence of the circle-command).
|
|
|
|
|
|
Related: asin, cos
|
|
|
|
&
|
|
sqr()
|
|
|
|
Name:
|
|
sqr() -- compute the square of its argument
|
|
|
|
Synopsis:
|
|
a=sqr(b)
|
|
|
|
Description:
|
|
The sqr-function computes the square of its numerical argument (i.e. it multiplies its argument with itself).
|
|
|
|
Example:
|
|
for a=1 to 10
|
|
print a,sqr(a),a**2
|
|
next a
|
|
Explanation:
|
|
|
|
As you may see from the output, sqr can be written as **2 (or ^2) too.
|
|
|
|
|
|
Related: sqrt, **, ^
|
|
|
|
&
|
|
sqrt()
|
|
|
|
Name:
|
|
sqrt() -- compute the square root of its argument
|
|
|
|
Synopsis:
|
|
to be written
|
|
|
|
Description:
|
|
The sqrt-function computes the square root of its numerical argument.
|
|
|
|
Example:
|
|
for a=1 to 5
|
|
print a,sqrt(a),a**(1/2)
|
|
next a
|
|
Explanation:
|
|
|
|
As you may see from the output, sqrt can be written as **(1/2) (or ^(1/2)) too.
|
|
|
|
|
|
Related: sqr, **, ^
|
|
|
|
&
|
|
tan()
|
|
|
|
Name:
|
|
tan() -- return the tangens of its argument
|
|
|
|
Synopsis:
|
|
foo=tan(bar)
|
|
|
|
Description:
|
|
The tan-function computes the tangens of its arguments (which should be specified in radian).
|
|
|
|
Example:
|
|
for a=0 to 45
|
|
print tan(a*pi/180)
|
|
next a
|
|
Explanation:
|
|
|
|
This example simply prints the tangens of all angles between 0 and 45 degree.
|
|
|
|
|
|
Related: atan, sin
|
|
|
|
&
|
|
xor()
|
|
|
|
Name:
|
|
xor() -- compute the exclusive or
|
|
|
|
Synopsis:
|
|
x=xor(a,b)
|
|
|
|
Description:
|
|
The xor computes the bitwise exclusive or of its two numeric arguments. To understand the result, both arguments should be viewed as binary numbers(i.e. a series of 0 and 1); a bit of the result will then be 1, if exactly one argument has a 1 and the other has a 0 at this position in their binary representation.
|
|
Note, that both arguments are silently converted to integer values and that negative numbers have their own binary representation and may lead tounexpected results when passed to and.
|
|
|
|
Example:
|
|
print xor(7,4)
|
|
Explanation:
|
|
|
|
This will print 3. This result is obvious, if you note, that the binary representation of 7 and 4 are 111 and 100 respectively; this will yield 011 in binary representaion or 2 as decimal. The eor-function is the same as the xor function; both are synonymous; however they have each their own description, so you may check out the entry of eor for a slightly different view.
|
|
|
|
|
|
Related: and, or, eor, not
|
|
|
|
&
|
|
** or ^
|
|
|
|
Name:
|
|
** or ^ -- raise its first argument to the power of its second
|
|
|
|
Synopsis:
|
|
print 2**b
|
|
print 3^4
|
|
|
|
Description:
|
|
** (or ^, which is an exact synonym), is the arithmetic operator of exponentiation; it requires one number to its left and a second one to its right; ** then raises thefirst argument to the power of the second and returns the result. The result will only be computed if it yields a real number (as opposed to a complex number); this means, that the power can not be computed, if the first argument is negative and the second one is fractional. On the other hand, the second argument can be fractional, if the first one ist positive; this means, that ** may be used to compute arbitrary roots: e.g. x**0.5 computes the square root of x.
|
|
|
|
Example:
|
|
print 2**0.5
|
|
Related: sqrt
|
|
|
|
&Conditions and Loops
|
|
&
|
|
and
|
|
|
|
Name:
|
|
and -- logical and, used in conditions
|
|
|
|
Synopsis:
|
|
if (a and b)
|
|
while (a and b)
|
|
|
|
Description:
|
|
Used in conditions (e.g within if, while or until) to join two expressions. Returns true, if and only if its left and right argument are both true and false otherwise.
|
|
Note, that logical shortcuts may take place.
|
|
|
|
Example:
|
|
input "Please enter a number" a
|
|
if (a>=1 and a<=9) print "your input is between 1 and 9"
|
|
Related: or, not, xor, eor
|
|
|
|
&
|
|
break
|
|
|
|
Name:
|
|
break -- breaks out of a switch statement or a loop
|
|
|
|
Synopsis:
|
|
break
|
|
|
|
Description:
|
|
break transfers control immediately outside the enclosing loop or switch statement. This is the preferred way of leaving a such a statement (rather than goto, which is still possible in most cases).
|
|
|
|
Example:
|
|
for a=1 to 10
|
|
break
|
|
print "Hi"
|
|
next a
|
|
|
|
while(1)
|
|
break
|
|
print "Hi"
|
|
wend
|
|
|
|
repeat
|
|
break
|
|
print "Hi"
|
|
until(0)
|
|
|
|
switch 1
|
|
case 1:break
|
|
case 2:case 3:print "Hi"
|
|
end switch
|
|
Explanation:
|
|
|
|
This example prints nothing at all, because each of the loops (and the switch-statement) does an immediate break (before it could print any "Hi").
|
|
|
|
|
|
Related: for, while, repeat, switch
|
|
|
|
&
|
|
case
|
|
|
|
Name:
|
|
case -- mark the different cases within a switch-statement
|
|
|
|
Synopsis:
|
|
switch a
|
|
case 1
|
|
case 2
|
|
...
|
|
end switch
|
|
|
|
...
|
|
|
|
switch a$
|
|
case "a"
|
|
case "b"
|
|
...
|
|
end switch
|
|
|
|
Description:
|
|
Please see the switch-statement.
|
|
|
|
Example:
|
|
input a
|
|
switch(a)
|
|
case 1:print "one":break
|
|
case 2:print "two":break
|
|
default:print "more"
|
|
end switch
|
|
Explanation:
|
|
|
|
Depending on your input (a number is expected) this code will print one or two or otherwise more.
|
|
|
|
|
|
Related: switch
|
|
|
|
&
|
|
continue
|
|
|
|
Name:
|
|
continue -- start the next iteration of a for-, do-, repeat- or while-loop
|
|
|
|
Synopsis:
|
|
continue
|
|
|
|
Description:
|
|
You may use continue within any loop to start the next iteration immediately. Depending on the type of the loop, the loop-condition will or will not be checked. Especially: for- and while-loops will evaluate their respective conditions, do- and repeat-loops will not.
|
|
Remark: Another way to change the flow of execution within a loop, is the break-command.
|
|
|
|
Example:
|
|
for a=1 to 100
|
|
if mod(a,2)=0 continue
|
|
print a
|
|
next a
|
|
Explanation:
|
|
|
|
This example will print all odd numbers between 1 and 100.
|
|
|
|
|
|
Related: for, do, repeat, while, break
|
|
|
|
&
|
|
default
|
|
|
|
Name:
|
|
default -- mark the default-branch within a switch-statement
|
|
|
|
Synopsis:
|
|
switch a+3
|
|
case 1
|
|
...
|
|
case 2
|
|
...
|
|
default
|
|
...
|
|
end switch
|
|
|
|
Description:
|
|
The default-clause is an optional part of the switch-statement (see there for more information). It introduces a series of statements, that should be executed, if none of the casese matches, that have been specified before (each with its own case-clause). So default specifies a default to be executed, if none of the explicitly named cases matches; hence its name.
|
|
|
|
Example:
|
|
print "Please enter a number between 0 and 6,"
|
|
print "specifying a day in the week."
|
|
input d
|
|
switch d
|
|
case 0:print "Monday":break
|
|
case 1:print "Tuesday":break
|
|
case 2:print "Wednesday":break
|
|
case 3:print "Thursday":break
|
|
case 4:print "Friday":break
|
|
case 5:print "Saturday":break
|
|
case 6:print "Sunday":break
|
|
default:print "Hey you entered something invalid!"
|
|
end switch
|
|
Explanation:
|
|
|
|
This program translates a number between 0 and 6 into the name of a weekday; the default -case is used to detect (and complain about) invalid input.
|
|
|
|
|
|
Related: sub, case
|
|
|
|
&
|
|
do
|
|
|
|
Name:
|
|
do -- start a (conditionless) do-loop
|
|
|
|
Synopsis:
|
|
do
|
|
...
|
|
loop
|
|
|
|
Description:
|
|
Starts a loop, which is terminated by loop; everything between do and loop willbe repeated forever. This loop has no condition, so it is an infinite loop; note however, that a break- or goto-statement might be used to leave this loop anytime.
|
|
|
|
Example:
|
|
do
|
|
a=a+1
|
|
print a
|
|
if (a>100) break
|
|
loop
|
|
Explanation:
|
|
|
|
This example prints the numbers between 1 and 101. The break-statement is used to leave the loop.
|
|
|
|
|
|
Related: loop, repeat, while, break
|
|
|
|
&
|
|
else
|
|
|
|
Name:
|
|
else -- mark an alternative within an if-statement
|
|
|
|
Synopsis:
|
|
if (...) then
|
|
...
|
|
else
|
|
...
|
|
endif
|
|
|
|
Description:
|
|
The else-statement introduces the alternate branch of an if-statement. I.e. it starts the sequence of statements, which is executed, if the condition of the if-statement is not true.
|
|
|
|
Example:
|
|
input "Please enter a number: " a
|
|
if (mod(a,2)=1) then
|
|
print a," is odd."
|
|
else
|
|
print a," is even."
|
|
endif
|
|
Explanation:
|
|
|
|
This program detects, if the number you have entered is even or odd.
|
|
|
|
|
|
Related: if
|
|
|
|
&
|
|
elsif
|
|
|
|
Name:
|
|
elsif -- starts an alternate condition within an if-statement
|
|
|
|
Synopsis:
|
|
if (...) then
|
|
...
|
|
elseif (...)
|
|
...
|
|
elsif (...) then
|
|
...
|
|
else
|
|
...
|
|
endif
|
|
|
|
Description:
|
|
The elsif-statement is used to select a single alternative among a seriesof choices. With each elsif-statement you may specify a condition, which is tested, if the main condition (specified with the if-statement) has failed. Note that elsif might be just as well written as elseif.
|
|
Within the example below, two variables a and b are tested against a rangeof values. The variable a is tested with the elsif-statement. The very same tests are performed for the variable b too; but here an involved series of if-else-statements is employed, making the tests much more obscure.
|
|
|
|
Example:
|
|
|
|
input "Please enter a number: " a
|
|
if (a<0) then
|
|
print "less than 0"
|
|
elseif (a<=10) then
|
|
print "between 0 and 10"
|
|
elsif (a<=20)
|
|
print "between 11 and 20"
|
|
else
|
|
print "over 20"
|
|
endif
|
|
|
|
input "Please enter another number: " b
|
|
if (b<0) then
|
|
print "less than 0"
|
|
else
|
|
if (b<=10) then
|
|
print "between 0 and 10"
|
|
else
|
|
if (b<=20) then
|
|
print "between 11 and 20"
|
|
else
|
|
print "over 20"
|
|
endif
|
|
endif
|
|
endif
|
|
Explanation:
|
|
|
|
Note, that the very same tests are performed for the variables a and b, but can be stated much more clearly with the elsif-statement.
|
|
Note, that elsif might be written as elseif too, and that the keyword then is optional.
|
|
|
|
|
|
Related: if, else
|
|
|
|
&
|
|
end
|
|
|
|
Name:
|
|
end -- terminate your program
|
|
|
|
Synopsis:
|
|
end
|
|
|
|
Description:
|
|
Terminate your program. Much (but not exactly) like the exit command.
|
|
Note, that end may not end your program immediately; if you have opened a window or called clear screen, yab assumes, that your user wants to study the output of your program after it has ended; therfore it issuesthe line ---Program done, press RETURN--- and waits for a key to be pressed. If you do not like this behaviour, consider using exit.
|
|
|
|
Example:
|
|
|
|
print "Do you want to continue ?"
|
|
input "Please answer y(es) or n(o): " a$
|
|
if (lower$(left$(a$,1))="n") then
|
|
print "bye"
|
|
end
|
|
fi
|
|
|
|
|
|
Related: exit
|
|
|
|
&
|
|
endif
|
|
|
|
Name:
|
|
endif -- ends an if-statement
|
|
|
|
Synopsis:
|
|
if (...) then
|
|
...
|
|
endif
|
|
|
|
Description:
|
|
The endif-statement closes (or ends) an if-statement.
|
|
Note, that endif may be written in a variety of other ways: end if, end-if or even fi. The endif-statement must be omitted, if the if-statement does not contain the keyword then (see the example below). Such an if-statement without endif extends only over a single line.
|
|
|
|
Example:
|
|
input "A number please: " a
|
|
if (a<10) then
|
|
print "Your number is less than 10."
|
|
endif
|
|
|
|
rem and now without endif
|
|
|
|
input "A number please: " a
|
|
if (a<10) print "Your number is less than 10."
|
|
Related: if
|
|
|
|
&
|
|
false
|
|
|
|
Name:
|
|
false -- a constant with the value of 0
|
|
|
|
Synopsis:
|
|
okay=false
|
|
|
|
Description:
|
|
The constant false can be assigned to variables which later appear in conditions (e.g. within an if-statement.
|
|
false may also be written as FALSE or even FaLsE.
|
|
|
|
Example:
|
|
input "Please enter a number between 1 and 10: " a
|
|
if (check_input(a)) print "Okay"
|
|
|
|
sub check_input(x)
|
|
if (x>10 or x<1) return false
|
|
return true
|
|
end sub
|
|
Explanation:
|
|
|
|
The subroutine check_input checks its argument and returns true or false according to the outcome of the check.
|
|
|
|
|
|
Related: true
|
|
|
|
&
|
|
fi
|
|
|
|
Name:
|
|
fi -- another name for endif
|
|
|
|
Synopsis:
|
|
if (...)
|
|
...
|
|
fi
|
|
|
|
Description:
|
|
fi marks the end of an if-statement and is exactly equivilent to endif, please see there for further information.
|
|
|
|
Example:
|
|
input "A number please: " a
|
|
if (a<10) then
|
|
print "Your number is less than 10."
|
|
fi
|
|
Related: endif
|
|
|
|
&
|
|
for
|
|
|
|
Name:
|
|
for -- starts a for-loop
|
|
|
|
Synopsis:
|
|
for a=1 to 100 step 2
|
|
...
|
|
next a
|
|
|
|
Description:
|
|
The for-loop lets its numerical variable (a in the synopsis) assume all valueswithin the given range. The optional step-clause may specify a value (default: 1) by which the variable will be incremented (or decremented, if step is negative).
|
|
|
|
Any for-statement can be replaced by a set of ifs and gotos; as you may infer from the example below this is normally not feasable. However if you want to know in detail how the for-statement works, you should study this example, which presents a for-statement and an exactly equivilant series of ifs and gotos.
|
|
|
|
Example:
|
|
for a=1 to 10 step 2
|
|
print a
|
|
next a
|
|
|
|
a=1
|
|
label check
|
|
if (a>10) goto done
|
|
print a
|
|
a=a+2
|
|
goto check
|
|
label done
|
|
Explanation:
|
|
|
|
This example simply prints the numbers 1, 3, 5, 7 and 9. It does this twice:
|
|
First with a simple for-statment and then with ifs and gotos.
|
|
|
|
|
|
Related: step, next
|
|
|
|
&
|
|
gosub
|
|
|
|
Name:
|
|
gosub -- continue execution at another point within your program
|
|
(and return later)
|
|
|
|
Synopsis:
|
|
gosub foo
|
|
|
|
...
|
|
|
|
label foo
|
|
...
|
|
return
|
|
|
|
Description:
|
|
gosub remembers the current position within your program and then passes the flow of execution to another point (which is normally marked with a label). Later, when a return- statement is encountered, the execution is resumed at the previous location.
|
|
gosub is the traditional command for calling code, which needs to be executed from various places within your program. However, with subroutines yab offers a much more flexible way to achieve this (and more). Therefore gosub must to be considered obsolete.
|
|
|
|
Example:
|
|
print "Do you want to exit ? "
|
|
gosub ask
|
|
if (r$="y") exit
|
|
|
|
label ask
|
|
input "Please answer yes or no, by typing 'y' or 'n': ",r$
|
|
return
|
|
Related: return, goto, sub, label, on gosub
|
|
|
|
&
|
|
goto
|
|
|
|
Name:
|
|
goto -- continue execution at another point within your program (and never come back)
|
|
|
|
Synopsis:
|
|
goto foo
|
|
|
|
...
|
|
|
|
label foo
|
|
|
|
Description:
|
|
The goto-statement passes the flow of execution to another point within your program (which is normally marked with a label).
|
|
goto is normally considered obsolete and harmful, however in yab it may be put to the good use of leaving loops (e.g. while or for) prematurely. Note however, that subroutines may not be left with the goto-statement.
|
|
|
|
Example:
|
|
clear screen
|
|
print "Please press any key to continue."
|
|
print "(program will continue by itself within 10 seconds)"
|
|
for a=1 to 10
|
|
if (inkey$(1)<>"") goto done
|
|
next a
|
|
label done
|
|
print "Hello World!"
|
|
Explanation:
|
|
|
|
Here the goto-statment is used to leave the for-loop prematurely. Start this program in a terminal.
|
|
|
|
|
|
Related: gosub, on goto
|
|
|
|
&
|
|
if
|
|
|
|
Name:
|
|
if -- evaluate a condition and execute statements or not, depending on the result
|
|
|
|
Synopsis:
|
|
if (...) then
|
|
...
|
|
endif
|
|
|
|
if (...) ...
|
|
|
|
if (...) then
|
|
...
|
|
else
|
|
...
|
|
endif
|
|
|
|
if (...) then
|
|
...
|
|
elsif (...)
|
|
...
|
|
elsif (...) then
|
|
...
|
|
else
|
|
...
|
|
endif
|
|
|
|
Description:
|
|
The if-statement is used to evaluate a conditions and take actions accordingly. (As an aside, please note that there is no real difference between conditions and expressions.)There are two major forms of the if-statement:The one-line-form without the keyword then: if (...) ...
|
|
This form evaluates the condition and if the result is true executes all commands (seperated by colons) upt to the end of the line. There is neither an endif keyword nor an else-branch.
|
|
The multi-line-form with the keyword then: if (...) then ... elsif (...) ... else ... endif(where elsif and else are optional, whereas endif is not.
|
|
According to the requirements of your program, you may specify:elsif(...), which specifies a condition, that will be evaluated only if the condition(s) whithin if or any preceeding elsif did not match.
|
|
else, which introduces a sequence of commands, that will be executed, if none of the conditions above did match. endif is required and ends the if-statement.
|
|
|
|
Example:
|
|
input "Please enter a number between 1 and 4: " a
|
|
if (a<=1 or a>=4) error "Wrong, wrong!"
|
|
if (a=1) then
|
|
print "one"
|
|
elsif (a=2)
|
|
print "two"
|
|
elsif (a=3)
|
|
print "three"
|
|
else
|
|
print "four"
|
|
endif
|
|
Explanation:
|
|
|
|
The input-number between 1 and 4 is simply echoed as text (one, two, ...). The example demonstrates both forms (short and long) of the if-statement (Note however, that the same thing can be done, probably somewhat more elegant, with the switch-statement).
|
|
|
|
Related: else, elsif, endif
|
|
|
|
&
|
|
label
|
|
|
|
Name:
|
|
label -- mark a specific location within your program for goto, gosub or restore
|
|
|
|
Synopsis:
|
|
label foo
|
|
|
|
...
|
|
|
|
goto foo
|
|
|
|
Description:
|
|
The label-command can be used to give a name to a specific location within your program. Such a position might be referred from one of three commands: goto, gosub and restore.
|
|
You may use labels safely within libraries, because a label (e.g. foo) does not collide with a label with the same name within the main program or within another library; yab will not mix them up.
|
|
As an aside, please note, that line numbers are a special (however deprecated) case of labels; see the second example below.
|
|
|
|
Example:
|
|
for a=1 to 100
|
|
if (rand(10)>5) goto done
|
|
next a
|
|
label done
|
|
|
|
10 for a=1 to 100
|
|
20 if (rand(10)>5) goto 40
|
|
30 next a
|
|
40
|
|
Explanation:
|
|
|
|
Within this example, the for-loop will probably be left prematurely with a goto-statement. This task is done twice: First with labels and then again with line numbers.
|
|
|
|
Related: gosub, goto
|
|
|
|
&
|
|
loop
|
|
|
|
Name:
|
|
loop -- marks the end of an infinite loop
|
|
|
|
Synopsis:
|
|
do
|
|
...
|
|
loop
|
|
|
|
Description:
|
|
The loop-command marks the ends of a loop (which is started by do), wherein all statements within the loop are repeated forever. In this respect the do loop-loop is infinite, however, you may leave it anytime via break or goto.
|
|
|
|
Example:
|
|
print "Hello, I will throw dice, until I get a 2 ..."
|
|
do
|
|
r=int(rand(6))+1
|
|
print r
|
|
if (r=2) break
|
|
loop
|
|
Related: do, for, repeat, while, break
|
|
|
|
&
|
|
next
|
|
|
|
Name:
|
|
next -- mark the end of a for loop
|
|
|
|
Synopsis:
|
|
for a=1 to 10
|
|
next a
|
|
|
|
Description:
|
|
The next-keyword marks the end of a for-loop. All statements up to the next-keyword will be repeated as specified with the for-clause. Note, that the name of the variable is optional; so instead of next a you may write next.
|
|
|
|
Example:
|
|
for a=1 to 300000
|
|
for b=1 to 21+20*sin(pi*a/20)
|
|
print "*"
|
|
next b
|
|
print
|
|
sleep 0.1
|
|
next a
|
|
Explanation:
|
|
|
|
This example simply plots a sine-curve until you fall asleep. Start this program in a terminal.
|
|
|
|
|
|
Related: for
|
|
|
|
&
|
|
not
|
|
|
|
Name:
|
|
not -- negate an expression; can be written as!
|
|
|
|
Synopsis:
|
|
if (not a<b) then ...
|
|
bad=!okay
|
|
|
|
Description:
|
|
The keyword not (or ! for short) is mostly used within conditions (e.g. within if- or while-statements). There it is employed to negate the condition or expression (i.e. turn TRUE into FALSE and vice versa). However not can be used within arithmetic calculations too., simply because there is no difference between arithmetic and logical expressions.
|
|
|
|
Example:
|
|
input "Please enter three ascending numbers: " a,b,c
|
|
if (not (a<b and b<c)) error " the numbers you have entered are not ascending ..."
|
|
Related: and, or, xor, eor
|
|
|
|
&
|
|
on gosub
|
|
|
|
Name:
|
|
on goto -- jump to one of multiple gosub-targets
|
|
|
|
Synopsis:
|
|
on a gosub foo,bar,baz
|
|
...
|
|
label foo
|
|
...
|
|
return
|
|
|
|
label bar
|
|
...
|
|
return
|
|
|
|
label baz
|
|
...
|
|
return
|
|
|
|
Description:
|
|
The on gosub statement uses its numeric argument (the one between on and gosub) to select an element from the list of labels, which follows after the gosub-keyword: If the number is 1, the program does a gosub to the first label; if the number is 2, to the second and, so on. if the number is zero or less, the program continues at the position of the first label; if the number is larger than the total count of labels, the execution continues at the position of the last label; i.e. the first and last label in the list constitute some kind of fallback-slot.
|
|
|
|
Note, that the on gosub-command can no longer be considered state of the art; people (not me!) may even start to mock you, if you use it.
|
|
|
|
Example:
|
|
do
|
|
print "Please enter a number between 1 and 3: "
|
|
print
|
|
input "Your choice " a
|
|
on a gosub bad,one,two,three,bad
|
|
loop
|
|
|
|
label bad
|
|
print "No. Please between 1 and 3"
|
|
return
|
|
|
|
label one
|
|
print "one"
|
|
return
|
|
|
|
label two
|
|
print "two"
|
|
return
|
|
|
|
label three
|
|
print "three"
|
|
return
|
|
Explanation:
|
|
|
|
Note, how invalid input (a number less than 1, or larger than 3) is automatically detected.
|
|
|
|
Related: goto, on gosub
|
|
|
|
&
|
|
on goto
|
|
|
|
Name:
|
|
on goto -- jump to one of many goto-targets
|
|
|
|
Synopsis:
|
|
on a goto foo,bar,baz
|
|
...
|
|
label foo
|
|
...
|
|
label bar
|
|
...
|
|
label baz
|
|
...
|
|
|
|
Description:
|
|
The on goto statement uses its numeric argument (the one between on and goto to select an element from the list of labels, which follows after the goto-keyword: If the number is 1, the execution continues at the first label; if the number is 2, at the second, and so on. if the number is zero or less, the program continues at the position of the first label; if the number is larger than the total count of labels, the execution continues at the position of the last label; i.e. the first and last label in the list constitute some kind of fallback-slot.
|
|
|
|
Note, that (unlike the goto-command) the on goto-command can no longer be considered state of the art; people may (not me!) even start to mock you, if you use it.
|
|
|
|
Example:
|
|
label over
|
|
print "Please Select one of these choices: "
|
|
print
|
|
print " 1 -- show time"
|
|
print " 2 -- show date"
|
|
print " 3 -- exit"
|
|
print
|
|
input "Your choice " a
|
|
on a goto over,show_time,show_date,terminate,over
|
|
|
|
label show_time
|
|
print time$()
|
|
goto over
|
|
|
|
label show_date
|
|
print date$()
|
|
goto over
|
|
|
|
label terminate
|
|
exit
|
|
Explanation:
|
|
|
|
Note, how invalid input (a number less than 1, or larger than 3) is automatically detected; in such a case the question is simply issued again.
|
|
|
|
|
|
Related: goto, on gosub
|
|
|
|
&
|
|
on interrupt
|
|
|
|
Name:
|
|
on interrupt -- change reaction on keyboard interrupts
|
|
|
|
Synopsis:
|
|
on interrupt break
|
|
...
|
|
on interrupt continue
|
|
|
|
Description:
|
|
With the on interrupt-command you may change the way, how yab reacts on a keyboard interrupt; it comes in two variants: on interrupt break and on interrupt continue. A keyboard interrupt is produced, if you press ctrl-C on your keyboard; normally (and certainly after you have called on interrupt break), yab will terminate with an error message. However after the command on interrupt continue yab ignores any keyboard interrupt. This may be useful, if you do not want your program beeing interruptible during certain critical operations (e.g. updating of files).
|
|
|
|
Example:
|
|
print "Please stand by while writing a file with random data ..."
|
|
on interrupt continue
|
|
open "random.data" for writing as #1
|
|
for a=1 to 100
|
|
print #1 ran(100)
|
|
print a," percent done."
|
|
sleep 1
|
|
next a
|
|
close #1
|
|
on interrupt continue
|
|
Explanation:
|
|
|
|
This program writes a file with 100 random numbers. The on interrupt continue command insures, that the program will not be terminated on a keyboard interrupt and the file will be written entirely in any case. The sleep-command just stretches the process arificially to give you a chance to try a ctrl-C.
|
|
|
|
|
|
&
|
|
logical or
|
|
|
|
Name:
|
|
or -- logical or, used in conditions
|
|
|
|
Synopsis:
|
|
if (a or b) ...
|
|
while (a or b) ...
|
|
|
|
Description:
|
|
Used in conditions (e.g within if or while) to join two expressions. Returns true, if either its left or its right or both arguments are true; returns false otherwise.
|
|
|
|
Example:
|
|
input "Please enter a number"
|
|
if (a>9 or a<1) print "a is not between 1 and 9"
|
|
Related: and, not, xor, eor
|
|
|
|
&
|
|
pause
|
|
|
|
Name:
|
|
pause -- pause, sleep, wait for the specified number of seconds
|
|
|
|
Synopsis:
|
|
pause 5
|
|
|
|
Description:
|
|
The pause-command has many different names: You may write pause, sleep or wait interchangable; whatever you write, yab will always do exactly the same. The pause-command will simply wait for the specified number of seconds. This may be a fractional number, so you may well wait less than a second. However, if you try to pause for a smaller and smaller interval (e.g. 0.1 seconds, 0.01 seconds, 0.001 seconds and so on) you will find that at some point yab will not wait at all. The pause-command cannot be interrupted. However, sometimes you may want the wait to be interuptible by simply pressing a key on the keyboard. In such cases you should consider using the inkey$-function, with a number of seconds as an argument).
|
|
|
|
Example:
|
|
deg=0
|
|
do
|
|
maxx=44+40*sin(deg)
|
|
for x=1 to maxx
|
|
print "*"
|
|
next x
|
|
pause 0.1+(maxx*maxx/(4*84*84))
|
|
print
|
|
deg=deg+0.1
|
|
loop
|
|
Explanation:
|
|
|
|
This example draws a sine-curve; due to the pause-statement the speed of drawing varies in the same way as the speed of a ball might vary, if it would roll along this curve under the influence of gravity.
|
|
|
|
Related: sleep, wait
|
|
|
|
&
|
|
repeat
|
|
|
|
Name:
|
|
repeat -- start a repeat-loop
|
|
|
|
Synopsis:
|
|
repeat
|
|
...
|
|
until (...)
|
|
|
|
Description:
|
|
The repeat-loop executes all the statements up to the final until-keyword over and over. The loop is executed as long as the condition, which is specified with the until-clause, becomes true. By construction, the statements within the loop are executed at least once.
|
|
|
|
Example:
|
|
x=0
|
|
clear screen
|
|
print "This program will print the numbers from 1 to 10"
|
|
repeat
|
|
x=x+1
|
|
print x
|
|
print "Press any key for the next number, or 'q' to quit"
|
|
if (inkey$="q") break
|
|
until(x=10)
|
|
Explanation:
|
|
|
|
This program is pretty much useless, but self-explanatory.
|
|
|
|
|
|
Related: until, break, while, do
|
|
|
|
&
|
|
return
|
|
|
|
Name:
|
|
return -- return from a subroutine or a gosub
|
|
|
|
Synopsis:
|
|
gosub foo
|
|
...
|
|
label foo
|
|
...
|
|
return
|
|
|
|
sub bar(baz)
|
|
...
|
|
return quertz
|
|
end sub
|
|
|
|
Description:
|
|
The return-statement serves two different (albeit somewhat related) purposes. The probably more important use of return is to return control from within a subroutine to the place in your program, where the subroutine has been called. If the subroutine is declared to return a value, the return-statement might be accompanied by a string or number, which constitutes the return value of the subroutine.
|
|
However, even if the subroutine should return a value, the return-statement need not carry a value; in that case the subroutine will return 0 or the empty string (depending on the type of the subroutine). Moreover, feel free to place multiple return-statements within your subroutine; it's a nice way of controlling the flow of execution.
|
|
The second (but historcially first) use of return is to return to the position, where a prior gosub has left off. In that case return may not carry a value.
|
|
|
|
Example:
|
|
do
|
|
read a$
|
|
if (a$="") then
|
|
print
|
|
end
|
|
endif
|
|
print mark$(a$)," "
|
|
loop
|
|
|
|
data "The","quick","brown","fox","jumped"
|
|
data "over","the","lazy","dog",""
|
|
|
|
sub mark$(a$)
|
|
if (instr(lower$(a$),"q")) return upper$(a$)
|
|
return a$
|
|
end sub
|
|
Explanation:
|
|
|
|
This example features a subroutine mark$, that returns its argument in upper case, if it contains the letter "q", or unchanged otherwise. In the test-text the word quick will end up beeing marked as QUICK.
|
|
The example above demonstrates return within subroutines; please see gosub for an example of how to use return in this context.
|
|
|
|
|
|
Related: sub, gosub
|
|
|
|
&
|
|
sleep
|
|
|
|
Name:
|
|
sleep -- pause, sleep, wait for the specified number of seconds
|
|
|
|
Synopsis:
|
|
sleep 4
|
|
|
|
Description:
|
|
The sleep-command has many different names: You may write pause, sleep or wait interchangable; whatever you write, yab will always do exactly the same.
|
|
Therefore you should refer to the entry for the pause-function for further information.
|
|
|
|
Related: pause, wait
|
|
&
|
|
step
|
|
|
|
Name:
|
|
step -- specifies the increment step in a for-loop
|
|
|
|
Synopsis:
|
|
for a=1 to 10 step 3
|
|
...
|
|
next a
|
|
|
|
Description:
|
|
Specify, by which amount the loop-variable of a for-loop will be incremented at each step.
|
|
The step (as well as the lower and upper bound) are computed anew in each step; this is not common, but possible, as the example below demonstrates.
|
|
|
|
Example:
|
|
for x=1 to 1000 step y
|
|
y=x+y
|
|
print x," ",y," "
|
|
next x
|
|
print
|
|
Explanation:
|
|
|
|
This program computes the fibonacci numbers between 1 and 1000.
|
|
|
|
|
|
Related: for
|
|
|
|
&
|
|
switch
|
|
|
|
Name:
|
|
switch -- select one of many alternatives depending on a value
|
|
|
|
Synopsis:
|
|
switch a
|
|
case 1
|
|
case 2
|
|
...
|
|
end switch
|
|
|
|
...
|
|
|
|
switch a$
|
|
case "a"
|
|
case "b"
|
|
end switch
|
|
|
|
Description:
|
|
The switch-statment selects one of many codepaths depending on a numerical or string expression. I.e. it takes an expression (either numeric or string) and compares it with a series of values, each wrapped within a case-clause. If the expression equals the value given in a case-clause, the subsequent statements are executed.
|
|
The default-clause allows to specify commands, which should be executed, if none of case-clauses matches.
|
|
Note, that many case-clauses might be clustered (e.g. case "a":case "b":case "c"). Or put another way: You need a break-statement at the end of a case-branch, if you do not want to run into the next case.
|
|
|
|
Example:
|
|
input "Please enter a single digit: " n
|
|
switch n
|
|
case 0:print "zero":break
|
|
case 1:print "one":break
|
|
case 2:print "two":break
|
|
case 3:print "three":break
|
|
case 4:print "four":break
|
|
case 5:case 6: case 7:case 8:case 9
|
|
print "Much!":break
|
|
default:print "Hey! That was more than a single digit!"
|
|
end switch
|
|
Explanation:
|
|
|
|
This example translates a single digit into a string; note, how the cases 5 to 7 are clustered.
|
|
|
|
|
|
Related: switch, case, break
|
|
|
|
&
|
|
then
|
|
|
|
Name:
|
|
then -- tell the long from the short form of the if-statement
|
|
|
|
Synopsis:
|
|
if (a<b) then
|
|
...
|
|
endif
|
|
|
|
Description:
|
|
The keyword then is part of the if-statement; please see there for further explanations. However, not every if-statement requires the keyword then: If the keyword then is present, the if-clause may extend over more than one line, and the keyword endif is required to end it. If the keyword then is not present, the if-statement extends up to the end of the line, and any endif would be an error.
|
|
|
|
Example:
|
|
if (1<2) then
|
|
print "Hello "
|
|
endif
|
|
|
|
if (2<3) print "world"
|
|
if (2<1)
|
|
print "!"
|
|
Explanation:
|
|
|
|
This example prints Hello world. Note, that no exclamation mark (!) is printed, which might come as a surprise and may be changed in future versions of yab.
|
|
|
|
|
|
Related: if
|
|
|
|
&
|
|
true
|
|
|
|
Name:
|
|
true -- a constant with the value of 1
|
|
|
|
Synopsis:
|
|
okay=true
|
|
|
|
Description:
|
|
The constant true can be assigned to variables which will later appear in conditions (e.g. an if-statement.
|
|
true may also be written as TRUE or even TrUe.
|
|
|
|
Example:
|
|
input "Please enter a string of all upper letters: " a$
|
|
if (is_upper(a$)) print "Okay"
|
|
|
|
sub is_upper(a$)
|
|
if (a$=upper$(a$)) return true
|
|
return false
|
|
end sub
|
|
Related: false
|
|
|
|
&
|
|
until
|
|
|
|
Name:
|
|
until -- end a repeat-loop
|
|
|
|
Synopsis:
|
|
repeat
|
|
...
|
|
until (...)
|
|
|
|
Description:
|
|
The until-keyword ends a loop, which has been introduced by the repeat-keyword. until requires a condition in braces (or an expression, see here for details) as an argument; the loop will continue until this condition evaluates to true.
|
|
|
|
Example:
|
|
|
|
c=1
|
|
s=1
|
|
repeat
|
|
l=c
|
|
s=-(s+sig(s))
|
|
c=c+1/s
|
|
print c
|
|
until(abs(l-c)<0.000001)
|
|
Explanation:
|
|
|
|
This program calculates the sequence 1/1-1/2+1/3-1/4+1/5-1/6+1/7-1/8+ ... ; please let me know, if you know against which value this converges.
|
|
|
|
|
|
Related: repeat
|
|
|
|
&
|
|
wait
|
|
|
|
Name:
|
|
wait -- pause, sleep, wait for the specified number of seconds
|
|
|
|
Synopsis:
|
|
wait 4
|
|
|
|
Description:
|
|
The wait-command has many different names: You may write pause, sleep or wait interchangeable; whatever you write, yab will always do exactly the same.
|
|
Therefore you should refer to the entry for the pause-function for further information.
|
|
|
|
Related: pause, sleep
|
|
&
|
|
wend
|
|
|
|
Name:
|
|
wend -- end a while-loop
|
|
|
|
Synopsis:
|
|
while(a<b)
|
|
...
|
|
wend
|
|
|
|
Description:
|
|
The wend-keyword marks the end of a while-loop. Please see the while-keyword for more details.
|
|
wend can be written as end while or even end-while.
|
|
|
|
Example:
|
|
line input "Please enter a sentence: " a$
|
|
p=instr(a$,"e")
|
|
while(p)
|
|
mid$(a$,p,1)="E"
|
|
p=instr(a$,"e")
|
|
wend
|
|
print a$
|
|
Explanation:
|
|
|
|
This example reads a sentence and converts every occurence of the letter e into uppercase (E).
|
|
|
|
|
|
Related: while
|
|
|
|
&
|
|
while
|
|
|
|
Name:
|
|
while -- start a while-loop
|
|
|
|
Synopsis:
|
|
while(...)
|
|
...
|
|
wend
|
|
|
|
Description:
|
|
The while-keyword starts a while-loop, i.e. a loop that is excuted as long as the condition (which is specified in braces after the keyword while) evaluates to true.
|
|
Note, that the body of such a while-loop will not be executed at all, if the condition following the while-keyword is not true initially.
|
|
If you want to leave the loop prematurely, you may use the break-statement.
|
|
|
|
Example:
|
|
open #1,"foo"
|
|
while(!eof(1))
|
|
line input #1 a$
|
|
print a$
|
|
wend
|
|
Explanation:
|
|
|
|
This program reads the file foo and prints it line by line.
|
|
|
|
|
|
Related: until, break, wend, do
|
|
|
|
&
|
|
:
|
|
|
|
Name:
|
|
: -- separate commands from each other
|
|
|
|
Synopsis:
|
|
print "Hello ":print "World"
|
|
|
|
Description:
|
|
The colon (':') separates multiple commands on a single line.
|
|
The colon and the newline-character have mostly the same effect, only that the latter, well, starts a new line too. The only other difference is their effect within the (so-called) short if, which is an if-statement without the keyword then. Please see the entry for if for more details.
|
|
|
|
Example:
|
|
if (a<10) print "Hello ":print "World!"
|
|
Explanation:
|
|
|
|
This example demonstrates the difference between colon and newline as described above.
|
|
|
|
|
|
Related: if
|
|
|
|
&Data Processing
|
|
&
|
|
arraydim()
|
|
|
|
Name:
|
|
arraydim() -- returns the dimension of the array, which is passed as an array reference
|
|
|
|
Synopsis:
|
|
a=arraydim(b())
|
|
|
|
Description:
|
|
If you apply the arraydim()-function on a one-dimensional array (i.e. a vector) it will return 1, on a two-dimensional array (i.e. a matrix) it will return 2, and so on.
|
|
This is mostly used within subroutines, which expect an array among their parameters. Such subroutines tend to use the arraydim-funtion to check, if the array which has been passed, has the right dimension. E.g. a subroutine to multiply two matrices may want to check, if it really is invoked with two 2-dimensional arrays.
|
|
|
|
Example:
|
|
dim a(10,10),b(10)
|
|
print arraydim(a()),arraydim(b())
|
|
Explanation:
|
|
|
|
This will print 2 1, which are the dimension of the arrays a() and b(). You may check out the function arraysize for a full-fledged example.
|
|
|
|
Related: arraysize, dim
|
|
|
|
&
|
|
arraysize()
|
|
|
|
Name:
|
|
arraysize() -- returns the size of a dimension of an array
|
|
|
|
Synopsis:
|
|
x=arraysize(a(),b)
|
|
|
|
Description:
|
|
The arraysize-function computes the size of a specified dimension of a specified array. Here, size stands for the maximum number, that may be used as an index for this array. The first argument to this function must be an reference to an array, the second one specifies, which of the multiple dimensions of the array should be taken to calculate the size.
|
|
|
|
An example involving subroutines: Let's say, an array has been declared as dim a(10,20) (that is a two-dimensional array or a matrix). If this array is passed as an array reference to a subroutine, this sub will not know, what sort of array has been passed. With the arraydim-function the sub will be able to find the dimension of the array, with the arraysize-function it will be able to find out the size of this array in its two dimensions, which will be 10 and 20 respectively.
|
|
|
|
Our sample array is two dimensional; if you envision it as a matrix this matrix has 10 lines and 20 columns (see the dim-statement above. To state it more formally: The first dimension (lines) has a size of 10, the second dimension (columns) has a size of 20; these mumbers are those returned by arraysize(a(),1) and arraysize(a(),2) respectively. Refer to the example below for a typical usage.
|
|
|
|
Example:
|
|
rem
|
|
rem This program adds two matrices elementwise.
|
|
rem
|
|
|
|
dim a(10,20),b(10,20),c(10,20)
|
|
|
|
rem initialization of the arrays a() and b()
|
|
for y=1 to 10:for x=1 to 20
|
|
a(y,x)=int(ran(4)):b(y,x)=int(ran(4))
|
|
next x:next y
|
|
|
|
matadd(a(),b(),c())
|
|
|
|
print "Result:"
|
|
for x=1 to 20
|
|
for y=10 to 1 step -1
|
|
print c(y,x)," "
|
|
next y
|
|
print
|
|
next x
|
|
|
|
sub matadd(m1(),m2(),r())
|
|
rem This sub will add the matrices m1() and m2()
|
|
rem elementwise and store the result within r()
|
|
rem This is not very useful but easy to implement.
|
|
rem However, this sub excels in checking its arguments
|
|
rem with arraydim() and arraysize()
|
|
|
|
local x:local y
|
|
|
|
if (arraydim(m1())<>2 or arraydim(m2())<>2 or arraydim(r())<>2) then
|
|
error "Need two dimensional arrays as input"
|
|
endif
|
|
|
|
y=arraysize(m1(),1):x=arraysize(m1(),2)
|
|
if (arraysize(m2(),1)<>y or arraysize(m2(),2)<>x) then
|
|
error "The two matrices cannot be added elementwise"
|
|
endif
|
|
|
|
if (arraysize(r(),1)<>y or arraysize(r(),2)<>x) then
|
|
error "The result cannot be stored in the third argument"
|
|
endif
|
|
|
|
local xx:local yy
|
|
for xx=1 to x
|
|
for yy=1 to y
|
|
r(yy,xx)=m1(yy,xx)+m2(yy,xx)
|
|
next yy
|
|
next xx
|
|
end sub
|
|
Related: arraydim, dim
|
|
|
|
&
|
|
data
|
|
|
|
Name:
|
|
data -- introduces a list of data-items
|
|
|
|
Synopsis:
|
|
data 9,"world"
|
|
...
|
|
read b,a$
|
|
|
|
Description:
|
|
The data-keyword introduces a list of comma-seperated list of strings or numbers, which may be retrieved with the read-command.
|
|
The data-command itself does nothing; it just stores data. A single data-command may precede an arbitrarily long list of values, in which strings or numbers may be mixed at will.
|
|
|
|
yab internally uses a data-pointer to keep track of the current location within the data-list; this pointer may be reset with the restore-command.
|
|
|
|
Example:
|
|
do
|
|
restore
|
|
for a=1 to 4
|
|
read num$,num
|
|
print num$,"=",num
|
|
next a
|
|
loop
|
|
data "eleven",11,"twelve",12,"thirteen",13,"fourteen",14
|
|
Explanation:
|
|
|
|
This example just prints a series of lines eleven=11 up to fourteen=14 and so on without end.
|
|
The restore-command ensures that the list of data-items is read from the start with every iteration.
|
|
|
|
|
|
Related: read, restore
|
|
|
|
&
|
|
dim
|
|
|
|
Name:
|
|
dim -- create an array prior to its first use
|
|
|
|
Synopsis:
|
|
dim array(x,y)
|
|
dim array$(x,y)
|
|
|
|
Description:
|
|
The dim-command prepares one or more arrays (of either strings or numbers) for later use. This command can also be used to enlarges an existing array.
|
|
|
|
When an array is created with the dim-statement, memory is allocated and all elements are initialized with either 0 (for numerical arrays) or "" (for string arrays).
|
|
If the array already existed, and the dim-statement specifies a larger size than the current size, the array is enlarged and any old content is preserved.
|
|
|
|
Note, that dim cannot be used to shrink an array: If you specify a size, that is smaller than the current size, the dim-command does nothing.
|
|
|
|
Finally: To create an array, that is only known within a single subroutine, you should use the command local, which creates local variables as well as local arrays.
|
|
|
|
Example:
|
|
dim a(5,5)
|
|
for x=1 to 5
|
|
for y=1 to 5
|
|
a(x,y)=int(ran(100))
|
|
y
|
|
next x
|
|
printmatrix(a())
|
|
dim a(7,7)
|
|
printmatrix(a())
|
|
|
|
sub printmatrix(ar())
|
|
local x,y,p,q
|
|
x=arraysize(ar(),1)
|
|
y=arraysize(ar(),2)
|
|
for q=1 to y
|
|
for p=1 to y
|
|
print ar(p,q),"\t"
|
|
next p
|
|
print
|
|
next q
|
|
end sub
|
|
Explanation:
|
|
|
|
This example creates a 2-dimenional array (i.e. a matrix) with the dim-statement and fills it with random numbers. The second dim-statement enlarges the array, all new elements are filled with 0.
|
|
|
|
The subroutine printmatrix just does, what its name says.
|
|
|
|
|
|
Related: arraysize, arraydim, local
|
|
|
|
&
|
|
read
|
|
|
|
Name:
|
|
read -- read data from data-statements
|
|
|
|
Synopsis:
|
|
read a$,a
|
|
...
|
|
data "Hello!",7
|
|
|
|
Description:
|
|
The read-statement retrieves literal data, which is stored within data-statements elsewhere in your program.
|
|
|
|
Example:
|
|
read num
|
|
dim col$(num)
|
|
for a=1 to num:read col$(a):next a
|
|
clear screen
|
|
print "These are the colours known to yab:\n"
|
|
for a=1 to num
|
|
print colour(col$(a)) col$(a)
|
|
next a
|
|
|
|
data 8,"black","white","red","blue"
|
|
data "green","yellow","cyan","magenta"
|
|
Explanation:
|
|
|
|
This program prints the names of the colors known to yab in those very colors.
|
|
|
|
Start this program in a terminal.
|
|
|
|
|
|
Related: data, restore
|
|
|
|
&
|
|
redim
|
|
|
|
Name:
|
|
redim -- create an array prior to its first use. A synonym for dim
|
|
|
|
Synopsis:
|
|
See the dim-command.
|
|
|
|
Description:
|
|
The redim-command does exactly the same as the dim-command; it is just a synonym. redim has been around in older versions of basic (not even yab) for many years; therefore it is supported in yab for compatibility reasons.
|
|
Please refer to the entry for the dim-command for further information.
|
|
|
|
Related: dim
|
|
&
|
|
restore
|
|
|
|
Name:
|
|
restore -- reposition the data-pointer
|
|
|
|
Synopsis:
|
|
read a,b,c,d,e,f
|
|
restore
|
|
read g,h,i
|
|
restore foo
|
|
data 1,2,3
|
|
label foo
|
|
data 4,5,6
|
|
|
|
Description:
|
|
The restore-command may be used to reset the reading of data-statements, so that the next read-statement will read data from the first data-statement.
|
|
You may specify a label with the restore-command; in that case, the next read-statement will read data starting at the given label. If the label is omitted, reading data will begin with the first data-statement within your program.
|
|
|
|
Example:
|
|
input "Which language (German/English) ? " l$
|
|
if (instr("German",l$)>0) then
|
|
restore German
|
|
else
|
|
restore English
|
|
endif
|
|
|
|
for a=1 to 3
|
|
read x,x$
|
|
print x,"=",x$
|
|
next a
|
|
|
|
label English
|
|
data 1,"one",2,"two",3,"three"
|
|
label German
|
|
data 1,"eins",2,"zwei",3,"drei"
|
|
Explanation:
|
|
|
|
This program asks to select one of those languages known to me (i.e. English or German) and then prints the numbers 1,2 and 3 and their textual equivalents in the chosen language.
|
|
|
|
|
|
Related: read, data, label
|
|
|
|
&String Handling
|
|
&
|
|
asc()
|
|
|
|
Name:
|
|
asc() -- accepts a string and returns the position of its first character
|
|
within the ascii charset
|
|
|
|
Synopsis:
|
|
a=asc(char$)
|
|
|
|
Description:
|
|
The asc-function accepts a string, takes its first character and looks it up within the ascii-charset; this position will be returned. The asc-function is the opposite of the chr$-function. There are valid uses for asc, however, comparing strings (i.e. to bring them into alphabetical sequence) is not among them; in such many cases you might consider to compare strings directly with <, = and > (rather than converting a string to a number and comparing this number).
|
|
|
|
Example:
|
|
input "Please enter a letter between 'a' and 'y': " a$
|
|
if (a$<"a" or a$>"y") print a$," is not in the proper range":end
|
|
print "The letter after ",a$," is ",chr$(asc(a$)+1)
|
|
Related: chr$
|
|
|
|
&
|
|
chr$()
|
|
|
|
Name:
|
|
chr$() -- accepts a number and returns the character at this position within the ascii charset
|
|
|
|
Synopsis:
|
|
character$=chr$(ascii)
|
|
|
|
Description:
|
|
The chr$-function is the opposite of the asc-function. It looks up and returns the character at the given position within the ascii-charset. It's typical use is to construct nonprintable characters which do not occur on your keyboard.
|
|
Nevertheless you won't use chr$ as often as you might think, because the most important nonprintable characters can be constructed using escape-sequences using the \-character (e.g. you might use \n instead of chr$(10) wherever you want to use the newline-character).
|
|
|
|
Example:
|
|
print "a",chr$(10),"b"
|
|
Explanation:
|
|
|
|
This will print the letters 'a' and 'b' in different lines because of the intervening newline-character, which is returned by chr$(10).
|
|
|
|
|
|
Related: asc
|
|
|
|
&
|
|
glob()
|
|
|
|
Name:
|
|
glob() -- check if a string matches a simple pattern
|
|
|
|
Synopsis:
|
|
if (glob(string$,pattern$)) ...
|
|
|
|
Description:
|
|
The glob-function takes two arguments, a string and a (glob-) pattern, and checks if the string matches the pattern. However glob does not employ the powerful rules of regular expressions; rather it has only two special characters: * (which matches any number (even zero) of characters) and ? (which matches exactly a single character).
|
|
|
|
Example:
|
|
for a=1 to 10
|
|
read string$,pattern$
|
|
if (glob(string$,pattern$)) then
|
|
print string$," matches ",pattern$
|
|
else
|
|
print string$," does not match ",pattern$
|
|
endif
|
|
next a
|
|
|
|
data "abc","a*"
|
|
data "abc","a?"
|
|
data "abc","a??"
|
|
data "abc","*b*"
|
|
data "abc","*"
|
|
data "abc","???"
|
|
data "abc","?"
|
|
data "abc","*c"
|
|
data "abc","A*"
|
|
data "abc","????"
|
|
Explanation:
|
|
|
|
This program checks the string abc against various patterns and prints the result. The output is:
|
|
|
|
&exverbatim
|
|
abc matches a*
|
|
abc does not match a?
|
|
abc matches a??
|
|
abc matches *b*
|
|
abc matches *
|
|
abc matches ???
|
|
abc does not match ?
|
|
abc matches *c
|
|
abc does not match A*
|
|
abc does not match ????
|
|
&exverbatim
|
|
|
|
&
|
|
hex$()
|
|
|
|
Name:
|
|
hex$() -- convert a number into hexadecimal
|
|
|
|
Synopsis:
|
|
print hex$(foo)
|
|
|
|
Description:
|
|
The hex$-function converts a number into a string with its hexadecimal representation. hex$ is the inverse of the dec-function.
|
|
|
|
Example:
|
|
open 1,"foo"
|
|
while(!eof(1))
|
|
print right$("0"+hex$(peek(1)),2)," "
|
|
i=i+1
|
|
if (mod(i,10)=0) print
|
|
end while
|
|
print
|
|
Explanation:
|
|
|
|
This program reads the file foo and prints its output as a hex-dump using the hex-function.
|
|
|
|
|
|
Related: dec, bin$
|
|
|
|
&
|
|
instr()
|
|
|
|
Name:
|
|
instr() -- searches its second argument within the first; returns its position if found
|
|
|
|
Synopsis:
|
|
print instr(a$,b$)
|
|
if (instr(a$,b$)) ...
|
|
pos=instr(a$,b$,x)
|
|
|
|
Description:
|
|
The instr-functions requires two string arguments and searches the second argument within the first. If the second argument can be found within the first, the position is returned (counting from one). If it can not be found, the instr-function returns 0; this makes this function usable within the condition of an if-statement (see the example below).
|
|
|
|
If you supply a third, numeric argument to the instr-function, it will be used as a starting point for the search. Therefore instr("abcdeabcdeabcde","e",8) will return 10, because the search for an "e" starts at position 8 and finds the "e" at position 10 (and not the one at position 5).
|
|
|
|
Example:
|
|
input "Please enter a text containing the string 'bumf': " a$
|
|
if (instr(a$,"bumf")) then
|
|
print "Well done!"
|
|
else
|
|
print "not so well ..."
|
|
endif
|
|
Related: rinstr
|
|
|
|
&
|
|
left$()
|
|
|
|
Name:
|
|
left$() -- return (or change) left end of a string
|
|
|
|
Synopsis:
|
|
print left$(a$,2)
|
|
left$(b$,3)="foobar"
|
|
|
|
Description:
|
|
The left$-function accepts two arguments (a string and a number) and returns the part from the left end of the string, whose length is specified by its second argument. Loosely spoken, it simply returns the requested number of chars from the left end of the given string.
|
|
|
|
Note, that the left$-function can be assigned to, i.e. it may appear on the left hand side of an assignment. In this way it is possible to change a part of the variable used within the left$-function. Note, that that way the length of the string cannot be changed, i.e. characters might be overwritten, but not added. For an example see below.
|
|
|
|
Example:
|
|
input "Please answer yes or no: " a$
|
|
l=len(a$):a$=lower$(a$):print "Your answer is "
|
|
if (left$("yes",l)=a$ and l>=1) then
|
|
print "yes"
|
|
elsif (left$("no",l)=a$ and l>=1) then
|
|
print "no"
|
|
else
|
|
print "?"
|
|
endif
|
|
|
|
a$="Heiho World!"
|
|
print a$
|
|
left$(a$,5)="Hello"
|
|
print a$
|
|
Explanation:
|
|
|
|
This example asks a simple yes/no question and goes some way to accept even incomplete input, while still beeing able to reject invalid input. This second example demonstrates the capability to assign to the left$-function.
|
|
|
|
|
|
Related: right$, mid$
|
|
|
|
&
|
|
len()
|
|
|
|
Name:
|
|
len() -- return the length of a string
|
|
|
|
Synopsis:
|
|
x=len(a$)
|
|
|
|
Description:
|
|
The len-function returns the length of its single string argument.
|
|
|
|
Example:
|
|
input "Please enter a password: " a$
|
|
if (len(a$)<6) error "Password too short!"
|
|
Explanation:
|
|
|
|
This example checks the length of the password, that the user has entered.
|
|
|
|
Related: left$, right$, mid$
|
|
|
|
&
|
|
lower$()
|
|
|
|
Name:
|
|
lower$() -- convert a string to lower case
|
|
|
|
Synopsis:
|
|
l$=lower$(a$)
|
|
|
|
Description:
|
|
The lower$-function accepts a single string-argument and converts it to all lower case.
|
|
|
|
Example:
|
|
input "Please enter a password: " a$
|
|
if (a$=lower$(a$)) error "Your password is NOT mixed case!"
|
|
Explanation:
|
|
|
|
This example prompts for a password and checks, if it is really lower case.
|
|
|
|
|
|
Related: upper$
|
|
|
|
&
|
|
ltrim$()
|
|
|
|
Name:
|
|
ltrim$() -- trim spaces at the left end of a string
|
|
|
|
Synopsis:
|
|
a$=ltrim$(b$)
|
|
|
|
Description:
|
|
The ltrim$-function removes all whitespace from the left end of a string and returns the result.
|
|
|
|
Example:
|
|
input "Please answer 'yes' or 'no' : " a$
|
|
a$=lower$(ltrim$(rtrim$(a$)))
|
|
if (len(a$)>0 and a$=left$("yes",len(a$))) then
|
|
print "Yes ..."
|
|
else
|
|
print "No ..."
|
|
endif
|
|
Explanation:
|
|
|
|
This example prompts for an answer and removes any spaces, which might precede the input; therefore it is even prepared for the (albeit somewhat patological case), that the user first hits space before entering his answer.
|
|
|
|
|
|
Related: rtrim$, trim$
|
|
|
|
&
|
|
rtrim$()
|
|
|
|
Name:
|
|
rtrim$() -- trim spaces at the right end of a string
|
|
|
|
Synopsis:
|
|
a$=rtrim$(b$)
|
|
|
|
Description:
|
|
The rtrim$-function removes all whitespace from the right end of a string and returns the result.
|
|
|
|
Example:
|
|
input "Please answer 'yes' or 'no' : " a$
|
|
a$=lower$(ltrim$(rtrim$(a$)))
|
|
if (len(a$)>0 and a$=left$("yes",len(a$))) then
|
|
"Yes ..."
|
|
else
|
|
print "No ..."
|
|
endif
|
|
Explanation:
|
|
|
|
This example prompts for an answer and removes any spaces, which might precede the input; therefore it is even prepared for the (albeit somewhat patological case), that the user first hits space before entering his answer.
|
|
|
|
|
|
Related: ltrim$, trim$
|
|
|
|
&
|
|
mid$()
|
|
|
|
Name:
|
|
mid$() -- return (or change) characters from within a string
|
|
|
|
Synopsis:
|
|
print mid$(a$,2,1)
|
|
print mid$(a$,2)
|
|
mid$(a$,5,3)="foo"
|
|
mid$(a$,5)="foo"
|
|
|
|
Description:
|
|
The mid$-function requires three arguments: a string and two numbers, where the first number specifies a position within the string and the second one gives the number of characters to be returned; if you omit the second argument, the mid$-function returns all characters up to the end of the string.
|
|
Note, that you may assign to the mid$-function, i.e. mid$ may appear on the left hand side of an assignment. In this way it is possible to change a part of the variable used within the mid$-function. Note, that that way the length of the string cannot be changed, i.e. characters might be overwritten, but not added. For an example see below.
|
|
|
|
Example:
|
|
input "Please enter a string: " a$
|
|
for a=1 to len(a$)
|
|
if (instr("aeiou",lower$(mid$(a$,a,1)))) mid$(a$,a,1)="e"
|
|
next a
|
|
print "When you turn everything to lower case and"
|
|
print "replace every vowel with 'e', your input reads:"
|
|
print
|
|
print a$
|
|
Explanation:
|
|
|
|
This example transforms the input string a bit, using the mid$-function to retrieve a character from within the string as well as to change it.
|
|
|
|
|
|
Related: left$, right$
|
|
|
|
&
|
|
right$()
|
|
|
|
Name:
|
|
right$() -- return (or change) the right end of a string
|
|
|
|
Synopsis:
|
|
print right$(a$,2)
|
|
right$(b$,2)="baz"
|
|
|
|
Description:
|
|
The right$-function requires two arguments (a string and a number) and returns the part from the right end of the string, whose length is specified by its second argument. So, right$ simply returns the requested number of chars from the right end of the given string.
|
|
Note, that the right$-function can be assigned to, i.e. it may appear on the left hand side of an assignment. In this way it is possible to change a part of the variable used within the right$-function. Note, that that way the length of the string cannot be changed, i.e. characters might be overwritten, but not added. For an example see below.
|
|
|
|
Example:
|
|
print "Please enter a length either in inch or centimeter"
|
|
print "please add 'in' or 'cm' to mark the unit."
|
|
input "Length: " a$
|
|
if (right$(a$,2)="in") then
|
|
length=val(a$)*2.56
|
|
elsif (right$(a$,2)="cm") then
|
|
length=val(a$)
|
|
else
|
|
error "Invalid input: "+a$
|
|
endif
|
|
|
|
a$="Heiho World!"
|
|
print a$
|
|
right$(a$,7)="dwarfs."
|
|
print a$
|
|
Explanation:
|
|
|
|
This program allows the user to enter a length qulified with a unit (either inch or centimeter).
|
|
The second example demonstrates the capability to assign to the right$-function.
|
|
|
|
|
|
Related: right$, mid$
|
|
|
|
&
|
|
split()
|
|
|
|
Name:
|
|
split() -- split a string into many strings
|
|
|
|
Synopsis:
|
|
dim w$(10)
|
|
...
|
|
num=split(a$,w$())
|
|
num=split(a$,w$(),s$)
|
|
|
|
Description:
|
|
The split-function requires a string (containing the text to be split), a reference to a string-array (which will receive the resulting strings, i.e. the tokens) and an optional string (with a set of characters, at which to split, i.e. the delimiters).
|
|
|
|
The split-function regards its first argument (a string) as a list of tokens separated by delimiters and it will store the list of tokens within the array-reference you have supplied. Note, that the array, which is passed as a reference (w$() in the synopsis), will be resized accordingly, so that you don't have to figure out the number of tokens in advance. The element at position zero (i.e. w$(0)) will not be used.
|
|
|
|
Normally (i.e. if you omit the third, which is the delimiter-argument) the function will regard space or tab as delimiters for tokens; however by supplying a third argument, you may split at any single of the characters within this string. E.g. if you supply ":;" as the third argument, then colon (:) or semicolon (;) will delimit tokens.
|
|
Note, that a sequence of separator-characters will produce a sequence of empty tokens; that way, the number of tokens returned will always be one plus the number of separator characters contained within the string. Refer to the closely related token-function, if you do not like this behaviour. In some way, the split-function focuses on the separators (other than the token-function, which focuses on the tokens), hence its name.
|
|
|
|
The second argument is a reference on a string-array, where the tokens will be stored; this array will be expanded (or shrinked) to have room for all tokens, if necessary.
|
|
The first argument finally contains the text, that will be split into tokens. The split-function returns the number of tokens that have been found.
|
|
|
|
Please see the examples below for some hints on the exact behaviour of the split-function and how it differs from the token-function:
|
|
|
|
Example:
|
|
print "This program will help you to understand, how the"
|
|
print "split()-function exactly works and how it behaves"
|
|
print "in certain special cases."
|
|
print
|
|
print "Please enter a line containing tokens separated"
|
|
print "by either '=' or '-'"
|
|
dim t$(10)
|
|
do
|
|
print
|
|
input "Please enter a line: " l$
|
|
num=split(l$,t$(),"=-")
|
|
print num," Tokens: "
|
|
for a=1 to num
|
|
if (t$(a)="") then
|
|
print "(EMPTY)"
|
|
else
|
|
print t$(a);
|
|
endif
|
|
if (a<num) print ","
|
|
next a
|
|
print
|
|
loop
|
|
Explanation:
|
|
|
|
This program prints the following output:
|
|
|
|
&exverbatim
|
|
Please enter a line: a
|
|
1 Tokens: a
|
|
|
|
Please enter a line:
|
|
0 Tokens:
|
|
|
|
Please enter a line: ab
|
|
1 Tokens: ab
|
|
|
|
Please enter a line: a=b
|
|
2 Tokens: a,b
|
|
|
|
Please enter a line: a-
|
|
2 Tokens: a,(EMPTY)
|
|
|
|
Please enter a line: a-=
|
|
3 Tokens: a,(EMPTY),(EMPTY)
|
|
|
|
Please enter a line: =a-
|
|
3 Tokens: (EMPTY),a,(EMPTY)
|
|
|
|
Please enter a line: a=-b
|
|
3 Tokens: a,(EMPTY),b
|
|
|
|
Please enter a line: a--b-
|
|
4 Tokens: a,(EMPTY),b,(EMPTY)
|
|
|
|
Please enter a line: -a==b-c==
|
|
7 Tokens: (EMPTY),a,(EMPTY),b,c,(EMPTY),(EMPTY)
|
|
&exverbatim
|
|
|
|
|
|
Related: token
|
|
|
|
&
|
|
str$()
|
|
|
|
Name:
|
|
str$() -- convert a number into a string
|
|
|
|
Synopsis:
|
|
a$=str$(a)
|
|
b$=str$(x,"##.###")
|
|
b$=str$(x,"###,###.##")
|
|
b$=str$(x,"###,###.##","_.")
|
|
|
|
Description:
|
|
The str$-function accepts a numeric argument and returns it as a string. This conversion between number and string can be controlled with the optional third argument (the format argument). See the following table of examples to learn about valid values of this argument. Note, that those examples fall in one of two categories: C-style and basic-style; the first 4 examples in the table below are C-style, the rest of the examples are basic-style.
|
|
|
|
For more information on the C-style formats, you may refer to your favorite documentation on the C programming language. The basic-style formats are much simpler, they just depict the desired output, marking digits with '#'; groups of (usually three) digits may be separated with colons (','), the decimal dot must be marked by a literal dot ('.'). Moreover these characters (colons and dot) may be replaced by other characters to satisfy the needs of non-English (e.g. German) languages; see the examples below.
|
|
|
|
Note, that for clarity, each space in the result has been replaced by the letter 'x', because it would be hard to figure out, how many spaces are produced exactly otherwise.
|
|
|
|
Examples for the format argument
|
|
|
|
&exverbatim
|
|
string | Result for converting 1000*pi | Description
|
|
|
|
%2.5f 3141.59265 The '2' determines the minimum
|
|
length of the output; but if
|
|
needed (as in the example) the
|
|
output can be longer.
|
|
The '5' is the number of digits
|
|
after the decimal point.
|
|
|
|
%12.5f xx3141.59265 Two spaces (which appear as 'x')
|
|
are added to pad the output to
|
|
the requested length of 12 characters.
|
|
|
|
%012.5g 0000003141.6 The 'g' requests, that the precision
|
|
('5') specifies the overall number of
|
|
digits (before and after the decimal
|
|
point).
|
|
|
|
%-12.5f 3141.59265xx The '-' requests the output to be
|
|
left-centered (therefor the filling
|
|
space appears at thi right).
|
|
|
|
#####.## x3141.59 Each '#' specifies a digit
|
|
(either before or after the dot),
|
|
the '.' specifies the position of
|
|
the dot. As 1000*pi does not
|
|
have enough digits, the 5 requested
|
|
digits before the dot are filled up
|
|
with a space (which shows up as an 'x').
|
|
|
|
##,###.## x3,141.59 Nearly the same as above, but the colon
|
|
from the format shows up within the
|
|
result.
|
|
|
|
##,###.##
|
|
and an addtional
|
|
argument of ".," x3.141,59 Similar to the example above, but
|
|
colon and dot are replaced with dot
|
|
and colon respectivly.
|
|
|
|
##,###.##
|
|
and an addtional
|
|
argument of "_," x3_141,59 Similar to the example above, but
|
|
colon and dot are replaced with
|
|
underscore and colon respectivly.
|
|
|
|
##### x3142 The format string does not contain
|
|
a dot, and therefore the result does
|
|
not have any fractional digits.
|
|
|
|
##.### ##.### As 1000*pi has 4 digits infront of
|
|
the decimal dot and the format only
|
|
specifies 2, yab does not know
|
|
what to do; therefore it chooses just
|
|
to reproduce the format string.
|
|
&exverbatim
|
|
|
|
Example:
|
|
do
|
|
input "Please enter a format string: " f$
|
|
a$=str$(1000*pi,f$)
|
|
for a=1 to len(a$)
|
|
if (mid$(a$,a,1)=" ") mid$(a$,a,1)="x"
|
|
next a
|
|
print a$
|
|
loop
|
|
Explanation:
|
|
|
|
This is the program, that has been used to get the results shown in the table above.
|
|
|
|
|
|
Related: print, using
|
|
|
|
&
|
|
token()
|
|
|
|
Name:
|
|
token() -- split a string into multiple strings
|
|
|
|
Synopsis:
|
|
dim w$(10)
|
|
...
|
|
num=token(a$,w$())
|
|
num=token(a$,w$(),s$)
|
|
|
|
Description:
|
|
The token-function accepts a string (containing the text to be split), a reference to a string-array (which will receive the resulting strings, i.e. the tokens) and an optional string (with a set of characters, at which to split, i.e. the delimiters).
|
|
|
|
The token-function regards its first argument as a list of tokens separated by delimiters and it will store the list of tokens within the array-reference that has been supplied. Note, that the array, which is passed as a reference (w$() in the synopsis), will be resized accordingly, so that you don't have to figure out the number of tokens in advance. The element at position zero (i.e. w$(0)) will not be used.
|
|
|
|
Normally (i.e. if you omit the third, the delimiter-argument) the function will regard space or tab as delimiters for tokens; however by supplying a third argument, you may split at any single of the characters within this string. E.g. if you supply ":;" as the third argument, then colon (:) or semicolon (;) will delimit tokens.
|
|
Note, that token will never produce empty tokens, even if two or more separators follow in sequence. Refer to the closely related split-function, if you do not like this behaviour. In some way, the token-function focuses on the tokens and not on the separators (other than the split-function, which focuses on the separators).
|
|
|
|
The second argument is a reference on a string-array, where the tokens will be stored; this array will be expanded (or shrinked) as necessary to have room for all tokens.
|
|
The first argument finally contains the text, that will be split into tokens. The token-function returns the number of tokens, that have been found.
|
|
|
|
Please see the examples below for some hints on the exact behaviour of the token-function and how it differs from the split-function:
|
|
|
|
Example:
|
|
print "This program will help you to understand, how the"
|
|
print "token()-function exactly works and how it behaves"
|
|
print "in certain special cases."
|
|
print
|
|
print "Please enter a line containing tokens separated"
|
|
print "by either '=' or '-'"
|
|
dim t$(10)
|
|
do
|
|
print
|
|
input "Please enter a line: " l$
|
|
num=token(l$,t$(),"=-")
|
|
print num," Tokens: "
|
|
for a=1 to num
|
|
if (t$(a)="") then
|
|
print "(EMPTY)"
|
|
else
|
|
print t$(a);
|
|
endif
|
|
if (a<num) print ","
|
|
next a
|
|
print
|
|
loop
|
|
Explanation:
|
|
|
|
This program prints the following output:
|
|
|
|
&exverbatim
|
|
Please enter a line: a
|
|
1 Tokens: a
|
|
|
|
Please enter a line:
|
|
0 Tokens:
|
|
|
|
Please enter a line: ab
|
|
1 Tokens: ab
|
|
|
|
Please enter a line: a=b
|
|
2 Tokens: a,b
|
|
|
|
Please enter a line: a-
|
|
1 Tokens: a
|
|
|
|
Please enter a line: a-=
|
|
1 Tokens: a
|
|
|
|
Please enter a line: =a-
|
|
1 Tokens: a
|
|
|
|
Please enter a line: a=-b
|
|
2 Tokens: a,b
|
|
|
|
Please enter a line: a--b-
|
|
2 Tokens: a,b
|
|
|
|
Please enter a line: -a==b-c==
|
|
3 Tokens: a,b,c
|
|
&exverbatim
|
|
|
|
|
|
Related: split
|
|
|
|
&
|
|
trim$()
|
|
|
|
Name:
|
|
trim$() -- remove leading and trailing spaces from its argument
|
|
|
|
Synopsis:
|
|
a$=trim$(b$)
|
|
|
|
Description:
|
|
The trim$-function removes all whitespaces from the left and from the right end of a string and returns the result. Calling trim$ is equivalent to calling rtrim$(ltrim$()).
|
|
|
|
Example:
|
|
do
|
|
input "Continue ? Please answer yes or no: " a$
|
|
a$=lower$(trim$(a$))
|
|
if (len(a$)>0 and a$=left$("no",len(a$)) exit
|
|
loop
|
|
Explanation:
|
|
|
|
This example asks for an answer (yes or no) and removes spaces with trim$ to make the comparison with the string "no" more bulletproof.
|
|
|
|
|
|
Related: ltrim$, rtrim$
|
|
|
|
&
|
|
upper$()
|
|
|
|
Name:
|
|
upper$() -- convert a string to upper case
|
|
|
|
Synopsis:
|
|
u$=upper$(a$)
|
|
|
|
Description:
|
|
The upper$-function accepts a single string argument and converts it to all upper case.
|
|
|
|
Example:
|
|
line input "Please enter a sentence without the letter 'e': " l$
|
|
p=instr(upper$(l$),"E")
|
|
if (p) then
|
|
l$=lower$(l$)
|
|
mid$(l$,p,1)="E"
|
|
print "Hey, you are wrong, see here!"
|
|
print l$
|
|
else
|
|
print "Thanks."
|
|
endif
|
|
Explanation:
|
|
|
|
This program asks for a sentence and marks the first (if any) occurence of the letter 'e' by coverting it to upper case (in contrast to the rest of the sentence, which is converted to lower case).
|
|
|
|
|
|
Related: lower$
|
|
|
|
&
|
|
val()
|
|
|
|
Name:
|
|
val() -- converts a string to a number
|
|
|
|
Synopsis:
|
|
x=val(x$)
|
|
|
|
Description:
|
|
The val-function checks, if the start of its string argument forms a floating point number and then returns this number. The string therefore has to start with digits (only whitespace infront is allowed), otherwise the val-function returns zero.
|
|
|
|
Example:
|
|
input "Please enter a length, either in inches (in) or centimeters (cm) " l$
|
|
if (right$(l$,2)="in") then
|
|
l=val(l$)*2.51
|
|
else
|
|
l=val(l$)
|
|
endif
|
|
print "You have entered ",l,"cm."
|
|
Explanation:
|
|
|
|
This example queries for a length and checks, if it has been specified in inches or centimeters. The length is then converted to centimeters.
|
|
|
|
|
|
Related: str$
|
|
|
|
&Input and Output
|
|
&
|
|
at()
|
|
|
|
Name:
|
|
at() -- can be used in the print-command to place the output at a specified position
|
|
|
|
Synopsis:
|
|
clear screen
|
|
...
|
|
print at(a,b)
|
|
print @(a,b)
|
|
|
|
Description:
|
|
The at-clause takes two numeric arguments (e.g. at(2,3)) and can be inserted after the print-keyword. at() can be used only if clear screen has been executed at least once within the program (otherwise you will get an error).
|
|
|
|
The two numeric arguments of the at-function may range from 0 to the width of your terminal minus 1, and from 0 to the height of your terminal minus 1; if any argument exceeds these values, it will be truncated accordingly. However, yab has no influence on the size of your terminal (80x25 is a common, but not mandatory), the size of your terminal and the maximum values acceptable within the at-clause may vary. To get the size of your terminal you may use the peek-function: peek("screenwidth") returns the width of your terminal and peek("screenheight") its height.
|
|
|
|
Example:
|
|
clear screen
|
|
maxx=peek("screenwidth")-1:maxy=peek("screenheight")-1
|
|
for x=0 to maxx
|
|
print at(x,maxy*(0.5+sin(2*pi*x/maxx)/2)) "*"
|
|
next x
|
|
Explanation:
|
|
|
|
This example plots a full period of the sine-function across the screen. Start this program in a terminal.
|
|
|
|
|
|
Related: print, clear screen, color
|
|
|
|
&
|
|
clear screen
|
|
|
|
Name:
|
|
clear screen -- erases the text window
|
|
|
|
Synopsis:
|
|
clear screen
|
|
|
|
Description:
|
|
clear screen erases the text window (the window where the output of print appears).
|
|
It must be issued at least once, before some advanced screen-commands (e.g. print at or inkey$) may be called; this requirement is due to some limititations of the curses-library, which is used by yab for some commands.
|
|
|
|
Example:
|
|
clear screen
|
|
print "Please press a key : "
|
|
a$=inkey$
|
|
print a$
|
|
Explanation:
|
|
|
|
The clear screen command is essential here; if it would be omitted, yab would issue an error ("need to call 'clear screen' first") while trying to execute the inkey$-function.
|
|
|
|
Start this program in a terminal.
|
|
|
|
|
|
Related: inkey$
|
|
|
|
&
|
|
close
|
|
|
|
Name:
|
|
close -- close a file, which has been opened before
|
|
|
|
Synopsis:
|
|
close filenum
|
|
close # filenum
|
|
|
|
Description:
|
|
The close-command closes an open file. You should issue this command as soon as you are done with reading from or writing to a file.
|
|
|
|
Example:
|
|
open "my.data" for reading as 1
|
|
input #1 a
|
|
print a
|
|
close 1
|
|
Explanation:
|
|
|
|
This program opens the file "my.data", reads a number from it, prints this number and closes the file again.
|
|
|
|
|
|
Related: open
|
|
|
|
&
|
|
color
|
|
|
|
Name:
|
|
color -- print with color
|
|
|
|
Synopsis:
|
|
print color(fore$) text$
|
|
print color(fore$,back$) text$
|
|
|
|
Description:
|
|
Not a seperate command, but part of the print-command; may be included just after print and can only be issued after clear screen has been executed.
|
|
|
|
color() takes one or two string-arguments, specifying the color of the text and (optionally) the background.
|
|
The one or two strings passed to color() can be one of these: "black", "white", "red", "blue", "green", "yellow", "cyan" and "magenta" (which can be abbreviated as "bla", "whi", "red", "blu", "gre", "yel", "cya" and "mag" respectively). color() can only be used, if clear scren has been issued at least once.
|
|
|
|
Note, that color() can be written as colour() too.
|
|
|
|
Example:
|
|
clear screen
|
|
dim col$(7):for a=0 to 7:read col$(a):next a
|
|
do
|
|
print color(col$(ran(7)),col$(ran(7))) " Hallo "
|
|
pause 0.01
|
|
loop
|
|
data "black","white","red","blue"
|
|
data "green","yellow","cyan","magenta"
|
|
Explanation:
|
|
|
|
This prints the word " Hallo " in all colors accross your screen.
|
|
Start this program in a terminal.
|
|
|
|
Related: print, clear screen, at
|
|
|
|
&
|
|
colour
|
|
|
|
Name:
|
|
colour -- see color
|
|
|
|
Synopsis:
|
|
print colour(fore$) text$
|
|
print colour(fore$,back$) text$
|
|
|
|
Description:
|
|
See color.
|
|
|
|
Related: color
|
|
|
|
&
|
|
eof
|
|
|
|
Name:
|
|
eof -- check, if an open file contains data
|
|
|
|
Synopsis:
|
|
open 1,"foo.bar"
|
|
if (eof(1)) then
|
|
...
|
|
end if
|
|
|
|
Description:
|
|
The eof-function checks, if there is still data left within an open file. As an argument it expects the file-number as returned by (or used within) the open-function (or statement).
|
|
|
|
Example:
|
|
a=open("foo.bar")
|
|
while(not eof(a))
|
|
input #a,a$
|
|
print a$
|
|
end while
|
|
Explanation:
|
|
|
|
This example will print the contents of the file "foo.bar". The eof-function will terminate the loop, if there is no more data left within the file.
|
|
|
|
|
|
Related: open
|
|
|
|
&
|
|
getscreen$()
|
|
|
|
Name:
|
|
getscreen$() -- returns a string representing a rectangular section of the text terminal
|
|
|
|
Synopsis:
|
|
a$=getscreen$(2,2,20,20)
|
|
|
|
Description:
|
|
The getscreen$ function returns a string representing the area of the screen as specified by its four arguments (which specify two corners). I.e. everything you have printed within this rectangle will be encoded in the string returned (including any colour-information).
|
|
Like most other commands dealing with advanced text output, getscreen$ requires, that you have called clear screen before.
|
|
|
|
Example:
|
|
clear screen
|
|
|
|
for a=1 to 1000:
|
|
print color("red") "1"
|
|
print color("green") "2"
|
|
print color("blue") "3"
|
|
next a
|
|
screen$=getscreen$(10,10,40,10)
|
|
print at(10,10) " Please Press 'y' or 'n'! "
|
|
a$=inkey$
|
|
putscreen screen$,10,10
|
|
Explanation:
|
|
|
|
This program fills the screen with coloured digits and afterwards asks the user for a choice ( Please press 'y' or 'n'! ). Afterwards the area of the screen, which has been overwritten by the question will be restored with its previous contents, whhch had been saved via getscreen$.
|
|
|
|
Start this program in a terminal.
|
|
|
|
Related: putscreen$
|
|
|
|
&
|
|
inkey$
|
|
|
|
Name:
|
|
inkey$ -- wait, until a key is pressed
|
|
|
|
Synopsis:
|
|
clear screen
|
|
foo$=inkey$
|
|
inkey$
|
|
foo$=inkey$(bar)
|
|
inkey$(bar)
|
|
|
|
Description:
|
|
The inkeys$-function waits, until the user presses a key on the keyboard or a button of his mouse, and returns this very key. An optional argument specifies the number of seconds to wait; if omitted, inkey$ will wait indefinitely. inkey$ may only be used, if clear screen has been called at least once.
|
|
|
|
For normal keys, yab simply returns the key, e.g. a, 1 or !. For function keys you will get f1, f2 and so on. Other special keys will return these strings respectively: enter, backspace, del, esc, scrnup (for screen up), scrndown and tab. Modifier keys (e.g. ctrl, alt or shift) by themself can not be detected (however, if you press shift and e.g. a simultaniously, inkey$ will return the letter A instead of a of course).
|
|
|
|
Example:
|
|
clear screen
|
|
print "Press any key or press 'q' to stop."
|
|
repeat
|
|
a$=inkey$
|
|
print a$
|
|
until(a$="q")
|
|
Explanation:
|
|
|
|
This program simply returns the key pressed. You may use it, to learn, which strings are returned for the special keys on your keyboard (e.g. function-keys).
|
|
|
|
Start this program in a terminal.
|
|
|
|
Related: clear screen
|
|
|
|
&
|
|
input
|
|
|
|
Name:
|
|
input -- read input from the user (or from a file) and assign it to a variable
|
|
|
|
Synopsis:
|
|
input a
|
|
input a,b,c
|
|
input a$
|
|
input "Hello" a
|
|
input #1 a$
|
|
|
|
Description:
|
|
input reads the new contents of one or many (numeric- or string-) variables, either from the keyboard (i.e. from you) or from a file. An optional first string-argument specifies a prompt, which will be issued before reading any contents.
|
|
|
|
If you want to read from an open file, you need to specify a hash ('#'), followed by the number, under which the file has been opened.
|
|
|
|
Note, that the input is split at spaces, i.e. if you enter a whole line consisting of many space-seperated word, the first input-statement will only return the first word; the other words will only be returned on subsequent calls to input; the same applies, if a single input reads multiple variables: The first variable gets only the first word, the second one the second word, and so on. If you don't like this behaviour, you may use line input, which returns a whole line (including embedded spaces) at once.
|
|
|
|
Example:
|
|
input "Please enter the name of a file to read: " a$
|
|
open 1,a$
|
|
while(!eof(1))
|
|
input #1 b$
|
|
print b$
|
|
wend
|
|
Explanation:
|
|
|
|
If this program is stored within a file test.yab and you enter this name when prompted for a file to read, you will see this output:
|
|
|
|
&exverbatim
|
|
Please enter the name of a file to read: test.yab
|
|
input
|
|
"Please
|
|
enter
|
|
the
|
|
name
|
|
of
|
|
a
|
|
file
|
|
to
|
|
read:
|
|
"
|
|
a$
|
|
open
|
|
1,a$
|
|
while(!eof(1))
|
|
input
|
|
#1
|
|
b$
|
|
print
|
|
b$
|
|
wend
|
|
&exverbatim
|
|
|
|
|
|
Related: line input
|
|
|
|
&
|
|
line input
|
|
|
|
Name:
|
|
line input -- read in a whole line of text and assign it to a variable
|
|
|
|
Synopsis:
|
|
line input a
|
|
line input a$
|
|
line input "Hello" a
|
|
line input #1 a$
|
|
|
|
Description:
|
|
In most respects line input is like the input-command: It reads the new contents of a variable, either from keyboard or from a file. However, line input always reads a complete line and assigns it to its variable. line input does not stop reading at spaces and is therefore the best way to read in a string which might contain whitespace. Note, that the final newline is stripped of.
|
|
|
|
Example:
|
|
line input "Please enter your name (e.g. Frodo Beutelin): " a$
|
|
print "Hello ",a$
|
|
Explanation:
|
|
|
|
Note that the usage of line input is essential in this example; a simple input-statement would only return the string up to the first space, e.g. Frodo.
|
|
|
|
|
|
Related: input
|
|
|
|
&
|
|
open
|
|
|
|
Name:
|
|
open -- open a file
|
|
|
|
Synopsis:
|
|
open a,"file","r"
|
|
open #a,"file","w"
|
|
open "file" for reading as a
|
|
open "file" for writing as #a
|
|
a=open("file")
|
|
a=open("file","r")
|
|
if (open(a,"file")) ...
|
|
if (open(a,"file","w")) ...
|
|
|
|
Description:
|
|
The open-command opens a file for reading or writing for printing text. open comes in a wide variety of ways; it requires these arguments:filenumber In the synopsis this is a or #a. In yab each file is associated with a number between 1 and a maximum value, which depends on the operating system.
|
|
|
|
For historical reasons the filenumber can be preceded by a hash ('#'). Note, that specifying a filenumber is optional; if it is omitted, the open-function will return a filenumber, which should then be stored in a variable for later reference. This filenumber can be a simple number or an arbitrary complex arithmetic expression, in which case braces might be necessary to save yab from getting confused.
|
|
|
|
filename -- In the synopsis above this is "file". This string specifies the name of the file to open (note the important caveat on specifying these filenames).
|
|
accessmode -- In the synopsis this is "r", "w", for reading or for writing. This string or clause specifies the mode in which the file is opened; it may be one of: "r"Open the file for reading (may also be written as for reading). If the file does not exist, the command will fail. This mode is the default, i.e. if no mode is specified with the open-command, the file will be opened with this mode.
|
|
|
|
"w" -- Open the file for writing (may also be written as for writing). If the file does not exist, it will be created.
|
|
|
|
"a" -- Open the file for appending, i.e. what you write to the file will be appended after its initial contents. If the file does not exist, it will be created.
|
|
|
|
"b" -- This letter may not appear alone, but may be combined with the other letters (e.g. "rb") to open a file in binary mode (as opposed to text mode).
|
|
|
|
As you may see from the synopsis, the open-command may either be called as a command (without braces) or as a function (with braces). If called as a function, it will return the filenumber or zero if the operation fails. Therefore the open-function may be used within the condition of an if-statement.
|
|
|
|
If the open-command fails, you may use peek("error") to retrieve the exact nature of the error.
|
|
Finally you may read the description for peek("error") to learn which errors may have happened during an open-call.
|
|
|
|
Example:
|
|
open "foo.bar" for writing as #1
|
|
print #1 "Hallo!"
|
|
close #1
|
|
if (not open(1,"foo.bar")) error "Could not open 'foo.bar' for reading"
|
|
while(not eof(1))
|
|
line input #1 a$
|
|
print a$
|
|
wend
|
|
Explanation:
|
|
|
|
This example simply opens the file foo.bar, writes a single line, reopens it and reads its contents again.
|
|
|
|
|
|
Related: close, print, peek
|
|
|
|
&
|
|
print
|
|
|
|
Name:
|
|
print -- Write to terminal or file
|
|
|
|
Synopsis:
|
|
print "foo",a$,b
|
|
print "foo","a$,b;
|
|
print #a "foo",a$
|
|
print #a "foo",a$;
|
|
print foo using "##.###"
|
|
print reverse "foo"
|
|
print at(10,10) a$,b
|
|
print @(10,10) a$,b
|
|
print color("red","blue") a$,b
|
|
print color("magenta") a$,b
|
|
print color("green","yellow") at(5,5) a$,b
|
|
|
|
Description:
|
|
The print-statement outputs strings or characters, either to your terminal (also known as console) or to an open file.
|
|
|
|
To understand all those uses of the print-statement, let's go throught the various lines in the synopsis above:print "foo",a$,bPrint the string foo as well as the contents of the variables a$ and b onto the screen, silently adding a newline.
|
|
|
|
print "foo",a$,b;
|
|
(Note the trailing semicolon!) This statement does the same as the one above; only the implicit newline is skipped, which means that the next print-statement will append seamlessly.
|
|
|
|
print #a "foo",a$
|
|
This is the way to write to files. The file with the number a must be open already, an implicit newline is added. Note the file-number #a, which starts with a hash ('#') amd is separated from the rest of the statement by a space only. The file-number (contained in the variable a) must have been returned by a previous open-statement (e.g. a=open("bar")).
|
|
|
|
print #a "foo",a$;
|
|
The same as above, but without the implicit newline.
|
|
|
|
print foo using "##.###"
|
|
Print the number foo with as many digits before and after the decimal dot as given by the number of '#'-signs. See the entries for using and str$ for a detailed description of this format.
|
|
|
|
print reverse "foo"
|
|
As all the print-variants to follow, this form of the print-statement can only be issued after clear screen has been called. The strings and numbers after the reverse-clause are simply printed inverse (compared to the normal print-statement).
|
|
|
|
print at(10,10) a$,b
|
|
Print at the specified (x,y)-position. This is only allowed after clear screen has been called. You may want to query peek$("screenwidth") or peek$("screenheight") to learn the actual size of your screen. You may add a semicolon to suppress the implicit newline.
|
|
|
|
print @(10,10) a$,b
|
|
This is exactly the same as above, however, at may be written as @.
|
|
|
|
print color("red","blue") at(5,5) a$,b
|
|
Print with the specified fore- ("red") and background ("blue") color (or colour). The possible values are "black", "white", "red", "blue", "green", "yellow", "cyan" or "magenta". Again, you need to call clear screen first and add a semicolon if you want to suppress the implicit newline.
|
|
|
|
print color("magenta") a$,b
|
|
You may specify the foreground color only.
|
|
|
|
print color("green","yellow") a$,b
|
|
A color and a position (in this sequence, not the other way around) may be specified at once.
|
|
|
|
Example:
|
|
clear screen
|
|
columns=peek("screenwidth")
|
|
lines=peek("screenheight")
|
|
dim col$(7)
|
|
for a=0 to 7:read col$(a):next a
|
|
data "black","white","red","blue","green","yellow","cyan","magenta"
|
|
|
|
for a=0 to 2*pi step 0.1
|
|
print colour(col$(mod(i,8))) at(columns*(0.8*sin(a)+0.9)/2,lines*(0.8*cos(a)+0.9)/2) "*"
|
|
i=i+1
|
|
next a
|
|
Explanation:
|
|
|
|
This example draws a cloured ellipse within the text window.
|
|
Start this program in a terminal.
|
|
|
|
Related: at, color, input, clear screen, using, ;
|
|
|
|
&
|
|
putscreen
|
|
|
|
Name:
|
|
putscreen -- draw a rectangle of characters into the text terminal
|
|
|
|
Synopsis
|
|
clear screen
|
|
...
|
|
a$=getscreen$(5,5,10,10)
|
|
...
|
|
putscreen a$,7,7
|
|
|
|
Description:
|
|
The putscreen-command is the counterpart of the getscreen$-function. putscreen requires a string as returned by the getscreen-function. Such a string contains a rectangular detail from the terminal; the putscreen-function puts such a region back into the terminal-window.
|
|
Note, that clear screen must have been called before.
|
|
|
|
Example:
|
|
clear screen
|
|
for a=1 to 200
|
|
print color("red") "Hallo!"
|
|
print color("blue") "Welt!"
|
|
next a
|
|
r$=getscreen$(0,0,20,20)
|
|
for x=0 to 60
|
|
putscreen r$,x,0
|
|
sleep 0.1
|
|
next x
|
|
Explanation:
|
|
|
|
This example prints the string "Hallo!Welt!" all over the screen and then moves a rectangle from one side to the other.
|
|
Start this program in a terminal.
|
|
|
|
Related: getscreen$, clear screen
|
|
|
|
&
|
|
reverse
|
|
|
|
Name:
|
|
reverse -- print reverse (background and foreground colors exchanged)
|
|
|
|
Synopsis:
|
|
clear screen
|
|
...
|
|
print reverse "foo"
|
|
|
|
Description:
|
|
reverse may be used to print text in reverse. reverse is not a seperate command, but part of the print-command; it may be included just after the print and can only be issued once that clear screen has been issued.
|
|
|
|
Example:
|
|
clear screen
|
|
|
|
print "1 "
|
|
c=3
|
|
do
|
|
prim=true
|
|
for a=2 to sqrt(c)
|
|
if (frac(c/a)=0) then
|
|
prim=false
|
|
break
|
|
endif
|
|
next a
|
|
if (prim) then
|
|
print
|
|
print reverse c;
|
|
else
|
|
print c;
|
|
endif
|
|
print " "
|
|
c=c+1
|
|
loop
|
|
Explanation:
|
|
|
|
This program prints numbers from 1 on and marks each prime number in reverse.
|
|
Start this program in a terminal.
|
|
|
|
Related: at, color, print, clear screen
|
|
|
|
&
|
|
screen
|
|
|
|
Name:
|
|
screen -- as clear screen clears the text window
|
|
|
|
Synopsis:
|
|
clear screen
|
|
|
|
Description:
|
|
The keyword screen appears only within the sequence clear screen; please see there for a description.
|
|
|
|
Related: clear screen
|
|
|
|
&
|
|
seek()
|
|
|
|
Name:
|
|
seek() -- change the position within an open file
|
|
|
|
Synopsis:
|
|
open 1,"foo"
|
|
seek #1,q
|
|
seek #1,x,"begin"
|
|
seek #1,y,"end"
|
|
seek #1,z,"here"
|
|
|
|
Description:
|
|
The seek-command changes the position, where the next input (or peek) statement will read from an open file. Usually files are read from the beginning to the end sequentially; however sometimes you may want to depart from this simple scheme. This can be done with the seek-command, allowing you to change the position, where the next piece of data will be read from the file.
|
|
|
|
seek accepts two or three arguments: The first one is the number of an already open file. The second one is the position where the next read from the file will start. The third argument is optional and specifies the the point from where the position (the second argument) will count. It can be one of:
|
|
|
|
begin -- Count from the beginning of the file.
|
|
|
|
end -- Count from the end of the file.
|
|
|
|
here -- Count from the current position within the file.
|
|
|
|
|
|
Example:
|
|
open #1,"count.dat","w"
|
|
for a=1 to 10
|
|
print #1,"00000000"
|
|
if (a<10) print #1,""
|
|
next a
|
|
|
|
dim count(10)
|
|
do
|
|
x=int(ran(10))
|
|
i=i+1
|
|
if (mod(i,1000)=0) print "."
|
|
count(x)=count(x)+1
|
|
curr$=right$("00000000"+str$(count(x)),8)
|
|
seek #1,9*x,"begin"
|
|
print #1,curr$;
|
|
loop
|
|
Explanation:
|
|
|
|
This example increments randomly one of ten counters (in the array count()); however, the result is always kept and updated within the file count.dat, so even in case of an unexpected interrupt, the result will not be lost.
|
|
|
|
|
|
Related: tell, open, print, peek
|
|
|
|
&
|
|
tell
|
|
|
|
Name:
|
|
tell -- get the current position within an open file
|
|
|
|
Synopsis:
|
|
open #1,"foo"
|
|
...
|
|
position=tell(#1)
|
|
|
|
Description:
|
|
The tell-function requires the number of an open file as an argument. It returns the position (counted in bytes, starting from the beginning of the file) where the next read will start.
|
|
|
|
Example:
|
|
open #1,"foo","w"
|
|
print #1 "Hello World!"
|
|
close #1
|
|
|
|
open #1,"foo"
|
|
seek #1,0,"end"
|
|
print tell(#1)
|
|
close 1
|
|
Explanation:
|
|
|
|
This example (mis)uses tell to get the size of the file. The seek positions the file pointer at the end of the file, therefor the call to tell returns the total length of the file.
|
|
|
|
|
|
Related: tell, open
|
|
|
|
&
|
|
using
|
|
|
|
Name:
|
|
using -- Specify the format for printing a number
|
|
|
|
Synopsis:
|
|
print a using "##.###"
|
|
print a using("##.###",",.")
|
|
|
|
Description:
|
|
The using-keyword may appear as part of the print-statement and specifies the format (e.g. the number of digits before and after the decimal dot), which should be used to print the number.
|
|
|
|
The possible values for the format argument ("##.###" in the synopsis above) are described within the entry for the str$-function; especially the second line in the synopsis (print a using("##.###",",.")) will become clear after referring to str$. In fact the using clause is closely related to the str$-function; the former can always be rewritten using the latter; i.e. print foo using bar$ is always equivalent to print str$(foo,bar$). Therefore you should check out str$ to learn more.
|
|
|
|
Example:
|
|
for a=1 to 10
|
|
print sqrt(ran(10000*a)) using "#########.#####"
|
|
next a
|
|
Explanation:
|
|
|
|
This example prints a column of square roots of random number, nicely aligned at the decimal dot.
|
|
|
|
|
|
Related: print, str$
|
|
|
|
&
|
|
#
|
|
|
|
Name:
|
|
# -- either a comment or a marker for a file-number
|
|
|
|
Synopsis:
|
|
# This is a comment, but the line below not!
|
|
open #1,"foo"
|
|
|
|
Description:
|
|
The hash ('#') has two totally unrelated uses:A hash might appear in commands related with file-io. yab uses simple numbers to refer to open files (within input, print, peek or eof). In those commands the hash may precede the number, which species the file. Please see those commands for further information and examples; the rest of this entry is about the second use (as a comment).
|
|
|
|
As the very first character within a line, a hash introduces comments (similar to rem).
|
|
'#' as a comment is common in most scripting languages and has a special use under BeOS: If the very first line of any BeOS-program begins with the character sequence '#!' ("she-bang", no spaces allowed), the rest of the line is taken as the program that should be used to execute the script. I.e. if your yab-program starts with '#!/boot/home/config/bin/yab', the program /boot/home/config/bin/yab will be invoked to execute the rest of the program.
|
|
|
|
Example:
|
|
# This line is a valid comment
|
|
print "Hello " : # But this is a syntax error, because
|
|
print "World!" : # the hash is not the first character!
|
|
Explanation:
|
|
|
|
Note, that this example will produce a syntax error and is not a valid program!
|
|
|
|
|
|
Related: input, print, peek, eof, //, rem
|
|
|
|
&
|
|
at()
|
|
|
|
Name:
|
|
at() -- can be used in the print-command to place the output at a specified position
|
|
|
|
Synopsis:
|
|
clear screen
|
|
...
|
|
print at(a,b)
|
|
print @(a,b)
|
|
|
|
Description:
|
|
The at-clause takes two numeric arguments (e.g. at(2,3)) and can be inserted after the print-keyword. at() can be used only if clear screen has been executed at least once within the program (otherwise you will get an error).
|
|
|
|
The two numeric arguments of the at-function may range from 0 to the width of your terminal minus 1, and from 0 to the height of your terminal minus 1; if any argument exceeds these values, it will be truncated accordingly. However, yab has no influence on the size of your terminal (80x25 is a common, but not mandatory), the size of your terminal and the maximum values acceptable within the at-clause may vary. To get the size of your terminal you may use the peek-function: peek("screenwidth") returns the width of your terminal and peek("screenheight") its height.
|
|
|
|
Example:
|
|
clear screen
|
|
maxx=peek("screenwidth")-1:maxy=peek("screenheight")-1
|
|
for x=0 to maxx
|
|
print at(x,maxy*(0.5+sin(2*pi*x/maxx)/2)) "*"
|
|
next x
|
|
Explanation:
|
|
|
|
This example plots a full period of the sine-function across the screen.
|
|
Start this program in a terminal.
|
|
|
|
Related: print, clear screen, color
|
|
|
|
&
|
|
;
|
|
|
|
Name:
|
|
; -- suppress the implicit newline after a print-statement
|
|
|
|
Synopsis:
|
|
print "foo",bar;
|
|
|
|
Description:
|
|
The semicolon (';') may only appear at the last position within a print-statement. It supresses the implicit newline, which yab normally adds after each print-statement.
|
|
|
|
Put another way: Normally the output of each print-statement appears on a line by itself. If you rather want the output of many print-statements to appear on a single line, you should end the print-statement with a semicolon.
|
|
|
|
Example:
|
|
print "Hello ":print "World!"
|
|
Explanation:
|
|
|
|
This example prints Hello World! in a single line.
|
|
|
|
|
|
Related: print
|
|
|
|
&Subroutines
|
|
&
|
|
end sub
|
|
|
|
Name:
|
|
end sub -- ends a subroutine definition
|
|
|
|
Synopsis:
|
|
sub foo(...)
|
|
...
|
|
end sub
|
|
|
|
Description:
|
|
Marks the end of a subroutine-definition (which starts with the sub-keyword). The whole concept of subroutines is explained within the entry for sub.
|
|
Example:
|
|
print foo(3)
|
|
|
|
sub foo(a)
|
|
return a*2
|
|
end sub
|
|
Explanation:
|
|
|
|
This program prints out 6. The subroutine foo simply returns twice its argument.
|
|
|
|
|
|
Related: sub
|
|
|
|
&
|
|
export
|
|
|
|
Name:
|
|
export -- mark a function as globally visible
|
|
|
|
Synopsis:
|
|
export sub foo(bar)
|
|
...
|
|
end sub
|
|
|
|
Description:
|
|
The export-statement is used within libraries to mark a user defined subroutine as visible outside the library wherein it is defined. Subroutines, which are not exported, must be qualified with the name of the library, e.g. foo.baz (where foo is the name of the library and baz the name of the subroutine); exported subroutines may be used without specifying the name of the library, e.g. bar.
|
|
|
|
Therefore export may only be useful within libraries.
|
|
|
|
Example:
|
|
export sub bar()
|
|
print "Hello"
|
|
end sub
|
|
|
|
sub baz()
|
|
print "World"
|
|
end sub
|
|
Explanation:
|
|
|
|
The library foo.bar (which is listed above) defines two functions bar and baz, however only the function bar is exported and therefore visible even outside the library; baz is not exported and may only be used within the library foo.yab.
|
|
|
|
Now within your main program cux.yab (which imports the library foo.yab); note that this program produces an error:
|
|
&exverbatim
|
|
import foo
|
|
|
|
print "Calling subroutine foo.bar (okay) ..."
|
|
foo.bar()
|
|
print "done."
|
|
|
|
print "Calling subroutine bar (okay) ..."
|
|
bar()
|
|
print "done."
|
|
|
|
print "Calling subroutine foo.baz (okay) ..."
|
|
foo.baz()
|
|
print "done."
|
|
|
|
print "Calling subroutine baz (NOT okay) ..."
|
|
baz()
|
|
print "done."
|
|
&exverbatim
|
|
|
|
The output when executing yab foo.yab is this:
|
|
|
|
&exverbatim
|
|
Calling subroutine foo.bar (okay) ...
|
|
Hello
|
|
done.
|
|
Calling subroutine bar (okay) ...
|
|
Hello
|
|
done.
|
|
Calling subroutine foo.baz (okay) ...
|
|
World
|
|
done.
|
|
Calling subroutine baz (NOT okay) ...
|
|
---Error in main.yab, line 16: can't find subroutine 'baz'
|
|
---Dump: sub baz() called in main.yab,16
|
|
---Error: Program stopped due to an error
|
|
&exverbatim
|
|
|
|
As the error message above shows, the subroutine baz must be qualified with the name of the library, if used outside the library, wherein it is defined (e.g. foo.baz. I.e. outside the library foo.yab you need to write foo.baz. baz alone would be an error.
|
|
|
|
The subroutine bar (without adding the name of the library) however may (and probably should) be used in any program, which imports the library foo.yab.
|
|
Note: In some sense the set of exported subroutines constitutes the interface of a library.
|
|
|
|
|
|
Related: sub, import
|
|
|
|
&
|
|
import
|
|
|
|
Name:
|
|
import -- import a library
|
|
|
|
Synopsis:
|
|
import foo
|
|
|
|
Description:
|
|
The import-statment imports a library. It expects a single argument, which must be the name of a library (without the trailing .yab). This library will then be read and parsed and its subroutines (and variables) will be made available within the main program.
|
|
|
|
Libraries will first be searched within the current directory (i.e. the directory within which you have invoked yab), then within the special directory /boot/home/config/lib/yab. The location of this second directory may be changed with the option -library.
|
|
|
|
Example:
|
|
import lib
|
|
|
|
rem This works ...
|
|
lib.x(0)
|
|
|
|
rem This works too ..
|
|
x(1)
|
|
|
|
rem And this.
|
|
lib.y(2)
|
|
|
|
rem But this not!
|
|
y(3)
|
|
Explanation:
|
|
|
|
Lets say you have a yab-program foo.yab, which imports a library lib.yab.
|
|
|
|
Now the library lib.yab reads:
|
|
|
|
&exverbatim
|
|
rem Make the subroutine x easily available outside this library
|
|
export sub x(a)
|
|
print a
|
|
return
|
|
end sub
|
|
|
|
rem sub y must be referenced by its full name
|
|
rem outside this library
|
|
sub y(a)
|
|
print a
|
|
return
|
|
end sub
|
|
&exverbatim
|
|
|
|
This program produces an error:
|
|
|
|
&exverbatim
|
|
0
|
|
1
|
|
2
|
|
---Error in foo.yab, line 13: can't find subroutine 'y'
|
|
---Dump: sub y() called in foo.yab,13
|
|
---Error: Program stopped due to an error
|
|
&exverbatim
|
|
|
|
As you may see from the error message, yab is unable to find the subroutine y without specifying the name of the library (i.e. lib.y). The reason for this is, that y, other than x, is not exported from the library lib.yab (using the export-statement).
|
|
|
|
|
|
Related: export, sub
|
|
|
|
&
|
|
local
|
|
|
|
Name:
|
|
local -- mark a variable as local to a subroutine
|
|
|
|
Synopsis:
|
|
sub foo()
|
|
|
|
local a,b,c$,d(10),e$(5,5)
|
|
|
|
...
|
|
|
|
end sub
|
|
|
|
Description:
|
|
The local-command can (and should be) used to mark a variable (or array) as local to the containing subroutine. This means, that a local variable in your subroutine is totally different from a variable with the same name within your main program. Variables which are known everywhere within your program are called global in contrast.
|
|
Declaring variables within the subroutine as local helps to avoid hard to find bugs; therefore local variables should be used whenever possible.
|
|
|
|
Note, that the parameters of your subroutines are always local.
|
|
|
|
As you may see from the example, local arrays may be created without using the keyword dim (which is required only for global arrays).
|
|
|
|
Example:
|
|
a=1
|
|
b=1
|
|
print a,b
|
|
foo()
|
|
print a,b
|
|
|
|
sub foo()
|
|
local a
|
|
a=2
|
|
b=2
|
|
end sub
|
|
Explanation:
|
|
|
|
This example demonstrates the difference between local and global variables; it produces this output:
|
|
1 1
|
|
1 2
|
|
As you may see, the content of the global variable a is unchanged after the subroutine foo; this is because the assignment a=2 within the subroutine affects the local variable a only and not the global one. However, the variable b is never declared local and therefore the subroutine changes the global variable, which is reflected in the output of the second print-statement.
|
|
|
|
|
|
Related: sub, static, dim
|
|
|
|
&
|
|
numparams
|
|
|
|
Name:
|
|
numparams -- return the number of parameters, that have been passed to a subroutine
|
|
|
|
Synopsis:
|
|
sub foo(a,b,c)
|
|
if (numparams=1) ...
|
|
...
|
|
end sub
|
|
|
|
Description:
|
|
Within a subroutine the local variable numparam or numparams contains the number of parameters, that have been passed to the subroutine. This information can be useful, because the subroutine may have been called with fewer parameters than actually declared. The number of values that actually have been passed while calling the subroutine, can be found in numparams.
|
|
|
|
Note, that arguments which are used in the definition of a subroutine but are left out during a call to it (thereby reducing the value of numparams) receive a value of 0 or "" (empty string) respectively.
|
|
|
|
Example:
|
|
a$="123456789"
|
|
print part$(a$,4)
|
|
print part$(a$,3,7)
|
|
|
|
sub part$(a$,f,t)
|
|
if (numparams=2) then
|
|
return mid$(a$,f)
|
|
else
|
|
return mid$(a$,f,t-f+1)
|
|
end if
|
|
end sub
|
|
Explanation:
|
|
|
|
When you run this example, it will print 456789 and 34567. Take a look at the subroutine part$, which returns part of the string which has been passed as an argument. If (besides the string) two numbers are passed, they define the starting and end position of the substring, that will be returned. However, if only one number is passed, the rest of the string, starting from this position will be returned. Each of these cases is recognized with the help of the numparams variable.
|
|
|
|
|
|
Related: sub
|
|
|
|
&
|
|
return
|
|
|
|
Name:
|
|
return -- return from a subroutine or a gosub
|
|
|
|
Synopsis:
|
|
gosub foo
|
|
...
|
|
label foo
|
|
...
|
|
return
|
|
|
|
sub bar(baz)
|
|
...
|
|
return quertz
|
|
end sub
|
|
|
|
Description:
|
|
The return-statement serves two different (albeit somewhat related) purposes. The probably more important use of return is to return control from within a subroutine to the place in your program, where the subroutine has been called. If the subroutine is declared to return a value, the return-statement might be accompanied by a string or number, which constitutes the return value of the subroutine.
|
|
|
|
However, even if the subroutine should return a value, the return-statement need not carry a value; in that case the subroutine will return 0 or the empty string (depending on the type of the subroutine). Moreover, feel free to place multiple return-statements within your subroutine; it's a nice way of controlling the flow of execution.
|
|
The second (but historcially first) use of return is to return to the position, where a prior gosub has left off. In that case return may not carry a value.
|
|
|
|
Example:
|
|
do
|
|
read a$
|
|
if (a$="") then
|
|
print
|
|
end
|
|
endif
|
|
print mark$(a$)," "
|
|
loop
|
|
|
|
data "The","quick","brown","fox","jumped"
|
|
data "over","the","lazy","dog",""
|
|
|
|
sub mark$(a$)
|
|
if (instr(lower$(a$),"q")) return upper$(a$)
|
|
return a$
|
|
end sub
|
|
Explanation:
|
|
|
|
This example features a subroutine mark$, that returns its argument in upper case, if it contains the letter "q", or unchanged otherwise. In the test-text the word quick will end up beeing marked as QUICK.
|
|
The example above demonstrates return within subroutines; please see gosub for an example of how to use return in this context.
|
|
|
|
|
|
Related: sub, gosub
|
|
|
|
&
|
|
static
|
|
|
|
Name:
|
|
static -- preserves the value of a variable between calls to a subroutine
|
|
|
|
Synopsis:
|
|
sub foo()
|
|
|
|
static a
|
|
|
|
...
|
|
|
|
end sub
|
|
|
|
Description:
|
|
The static keyword can be used within subroutines to mark variables as static. This has two effects: First, the variable is local to the subroutine, i.e. its value is not know outside the subroutine (this is the effect of the local keyword). Second, the static-keyword arranges things, so that the variable keeps its value between invocations of the subroutine (this is different from the local-keyword).
|
|
|
|
Example:
|
|
foo()
|
|
foo()
|
|
foo()
|
|
|
|
sub foo()
|
|
static a
|
|
local b
|
|
a=a+1
|
|
b=b+1
|
|
print a,b
|
|
end sub
|
|
Explanation:
|
|
|
|
This program shows the difference between static and local variables within a subroutine; it produces this output:
|
|
|
|
&exverbatim
|
|
1 1
|
|
2 1
|
|
3 1
|
|
&exverbatim
|
|
|
|
The output shows, that the static variable a keeps its value between subroutine calls, whereas b is initialized with the value 0 at every call to the subroutine foo.
|
|
|
|
|
|
Related: sub, local
|
|
|
|
&
|
|
sub
|
|
|
|
Name:
|
|
sub -- declare a user defined subroutine
|
|
|
|
Synopsis:
|
|
foo(2,"hello")
|
|
|
|
...
|
|
|
|
sub foo(bar,baz$)
|
|
...
|
|
return qux
|
|
...
|
|
end sub
|
|
|
|
Description:
|
|
The sub-keyword starts the definition of a user defined subroutine. With user defined subroutines you are able to somewhat extend yab with your own commands or functions. A subroutine accepts arguments (numbers or strings) and returns a number or a string (however, you are not required to assign the value returned to a variable). The name of the subroutine follows after the keyword sub. If the name (in the synopsis: foo) ends on a '$', the subroutine should return a string (with the return-statement), otherwise a number.
|
|
|
|
After the name of the subroutine yab requires a pair of braces; within those braces you may specify a list of parameters, for which values can (but need not) be included when calling the subroutine. If you omit one of those parameters when calling such a subroutine, it assumes the value zero (for numeric parameters) or the empty string (for string parameters). However with peek("argument") you may find out, how many arguments have really been passed while calling the subroutine.
|
|
|
|
Parameters of a subroutine are always local variables (see the keyword local for more explanation).
|
|
From within the subroutine you may return any time with the keyword return; along with the return-keyword you may specify the return value. Note that more than one return is allowed within a single subroutine.
|
|
|
|
Finally, the keyword end sub ends the subroutine definition. Note, that the definition of a subroutine need not appear within the program before the first call to this sub.
|
|
|
|
Note: As braces have two uses in yab (i.e. for supplying arguments to a subroutine as well as to list the indices of an array). yab can not tell apart an array from a subroutine with the same name. Therefore you cannot define a subroutine with the same name as an array!
|
|
|
|
Example:
|
|
p=2
|
|
do
|
|
if (is_prime(p)) print p
|
|
p=p+1
|
|
loop
|
|
|
|
sub is_prime(a)
|
|
local b
|
|
for b=2 to sqrt(a)
|
|
if (frac(a/b)=0) return false
|
|
next b
|
|
return true
|
|
end sub
|
|
Explanation:
|
|
|
|
This example is not the recommended way to compute prime numbers. However it gives a nice demonstration of using a subroutine.
|
|
|
|
|
|
Related: local, static, peek
|
|
|
|
&System
|
|
&
|
|
bind()
|
|
|
|
Name:
|
|
bind() -- Binds a yab-program and the yab-interpreter together into a standalone program.
|
|
|
|
Synopsis:
|
|
bind("foo.exe")
|
|
|
|
Description:
|
|
The bind-command combines your own yab-program (plus all the libraries it does import) and the interpreter by copying them into a new file, whose name is passed as an argument. This new program may then be executed on any computer, even if it does not have yab installed.
|
|
|
|
Note: With the current version of yab, bind should not be used anymore, use the Build Factory instead.
|
|
|
|
Example:
|
|
if (!peek("isbound")) then
|
|
bind "foo"
|
|
print "Successfully created the standalone executable 'foo'!"
|
|
exit
|
|
endif
|
|
|
|
print "Hello World!"
|
|
Explanation:
|
|
|
|
This example creates a standalone program foo from itself.
|
|
|
|
|
|
Related: peek
|
|
&
|
|
clipboard copy
|
|
|
|
Name:
|
|
clipboard copy -- copy a string to the clipboard
|
|
|
|
Synopsis:
|
|
CLIPBOARD COPY Text$
|
|
|
|
Description:
|
|
Clipboard copy simply copies the string Text$ to the system clipboard. Note: This will overwrite all text currently stored in the clipboard.
|
|
|
|
Example:
|
|
print "This is the content of the clipboard: "+clipboard paste$
|
|
print "Now we copy \"Foo Bar\" to the clipboard"
|
|
clipboard copy "Foo Bar"
|
|
print "This is the content of the clipboard: "+clipboard paste$
|
|
Explanation:
|
|
|
|
The example will first display whatever is written in the clipboard (might be empty too), and then copies the string "Foo Bar" to the clipboard. Another output shows, it actually worked.
|
|
|
|
Related: clipboard paste$
|
|
&
|
|
clipboard paste$
|
|
|
|
Name:
|
|
clipboard paste$ -- read out the clipboard
|
|
|
|
Synopsis:
|
|
Text$ = CLIPBOARD PASTE$
|
|
|
|
Description:
|
|
This command will read out ("paste") the content of the system clipboard.
|
|
|
|
Example:
|
|
print "This is the content of the clipboard: "+clipboard paste$
|
|
print "Now we copy \"Foo Bar\" to the clipboard"
|
|
clipboard copy "Foo Bar"
|
|
print "This is the content of the clipboard: "+clipboard paste$
|
|
Explanation:
|
|
|
|
The example will first display whatever is written in the clipboard (might be empty too), and then copies the string "Foo Bar" to the clipboard. Another output shows, it actually worked.
|
|
|
|
Related: clipboard copy
|
|
&
|
|
compile
|
|
|
|
Name:
|
|
compile -- compile a string with yab-code on the fly
|
|
|
|
Synopsis:
|
|
compile(code$)
|
|
|
|
Description:
|
|
This is an advanced command (closely related with the execute-command). It allows you to compile a string of yab-code (which is the only argument). Afterwards the compiled code is a normal part of your program.
|
|
Note, that there is no way to remove the compiled code.
|
|
|
|
Example:
|
|
compile("sub mysub(a):print a:end sub")
|
|
mysub(2)
|
|
Explanation:
|
|
|
|
This example creates a function named mysub, which simply prints its single argument.
|
|
|
|
|
|
Related: execute
|
|
|
|
&
|
|
date$
|
|
|
|
Name:
|
|
date$ -- returns a string with various components of the current date
|
|
|
|
Synopsis:
|
|
a$=date$
|
|
|
|
Description:
|
|
The date$-function (which must be called without parantheses; i.e. date$() would be an error) returns a string containing various components of a date; an example would be 4-05-27-2004-Thu-May. This string consists of various fields seperated by hyphens ("-"):The day within the week as a number in the range 0 (=sunday) to 6 (=saturday) (in the example above: 4, i.e. thursday).
|
|
|
|
The month as a number in the range 1 (=january) to 12 (=december) (in the example: 5 which stands for may).
|
|
The day within the month as a number in the range 1 to 31 (in the example: 27).
|
|
The full, 4-digit year (in the example: 2004, which reminds me that I should adjust the clock within my computer ...).
|
|
The abbreviated name of the day within the week (Mon to Sun).
|
|
The abbreviated name of the month (Jan to Dec).
|
|
|
|
Therefore the whole example above (4-05-27-2004-Thu-May) would read: day 4 in the week (counting from 0), May 27 in the year 2004, which is a thursday in May.
|
|
Note, that all fields within the string returned by date$ have a fixed with (numbers are padded with zeroes); therefore it is easy to extract the various fields of a date format with mid$.
|
|
|
|
Example:
|
|
rem Two ways to print the same ...
|
|
|
|
print mid$(date$,3,10)
|
|
|
|
dim fields$(6)
|
|
a=split(date$,fields$(),"-")
|
|
print fields$(2),"-",fields$(3),"-",fields$(4)
|
|
Explanation:
|
|
|
|
This example shows two different techniques to extract components from the value returned by date$. The mid$-function is the preferred way, but you could just as well split the return-value of date$ at every "-" and store the result within an array of strings.
|
|
|
|
|
|
Related: time$
|
|
|
|
&
|
|
doc
|
|
|
|
Name:
|
|
doc -- special comment, which might be retrieved by the program itself
|
|
|
|
Synopsis:
|
|
doc This is a comment
|
|
docu This is another comment
|
|
|
|
Description:
|
|
Introduces a comment, which spans up to the end of the line. But other than the rem-comment, any docu-comment is collected within the special docu$-array and might be retrieved later on. Moreover you might invoke yab -docu foo.yab on the commandline to retrieve the embedded documentation within the program foo.yab.
|
|
Instead of doc you may just as well write docu or even documentation.
|
|
|
|
Example:
|
|
rem Hi, this has been written by me
|
|
rem
|
|
doc This program asks for a number and
|
|
doc prints this number multiplied with 2
|
|
rem
|
|
rem Print out rhe above message
|
|
for a=1 to arraysize(docu$()):print docu$(a):next a
|
|
|
|
rem Read and print the number
|
|
input "Please input a number: " x
|
|
print x*2
|
|
Explanation:
|
|
|
|
This program uses the comments within its code to print out a help message for the user.
|
|
The contents of the doc-lines are retrieved from the docu$-array; if you do not want a comment to be collected within this array, use the rem-statement instead.
|
|
|
|
|
|
Related: docu$, rem
|
|
|
|
&
|
|
docu$
|
|
|
|
Name:
|
|
docu$ -- special array, containing the contents of all docu-statement within the program
|
|
|
|
Synopsis:
|
|
a$=docu$(1)
|
|
|
|
Description:
|
|
Before your program is executed, yab collects the content of all the doc-statements within your program within this 1-dimensional array (well only those within the main-program, libraries are skipped).
|
|
You may use the arraysize function to find out, how many lines it contains.
|
|
|
|
Example:
|
|
docu
|
|
docu This program reads two numbers
|
|
docu and adds them.
|
|
docu
|
|
|
|
rem retrieve and print the embedded documentation
|
|
for a=1 to arraysize(docu$(),1)
|
|
print docu$(a)
|
|
next a
|
|
|
|
input "First number: " b
|
|
input "Second number: " c
|
|
|
|
print "The sum of ",b," and ",c," is ",b+c
|
|
Explanation:
|
|
|
|
This program uses the embedded documentation to issue a usage-message.
|
|
|
|
|
|
Related: arraydim, rem
|
|
|
|
&
|
|
error
|
|
|
|
Name:
|
|
error -- raise an error and terminate your program
|
|
|
|
Synopsis:
|
|
error "Wrong, wrong, wrong!!"
|
|
|
|
Description:
|
|
Produces the same kind or error messages, that yab itself produces (e.g. in case of a syntax-error). The single argument is issued along with the current line-number.
|
|
|
|
Example:
|
|
input "Please enter a number between 1 and 10: " a
|
|
if (a<1 or a>10) error "Oh no ..."
|
|
Explanation:
|
|
|
|
This program is very harsh in checking the users input; instead of just asking again, the program terminates with an error, if the user enters something wrong.
|
|
The error message would look like this:
|
|
|
|
&exverbatim
|
|
---Error in t.yab, line 2: Oh no ...
|
|
---Error: Program stopped due to an error
|
|
&exverbatim
|
|
|
|
|
|
&
|
|
execute$()
|
|
|
|
Name:
|
|
execute$() -- execute a user defined subroutine, which must return a string
|
|
|
|
Synopsis:
|
|
print execute$("foo$","arg1","arg2")
|
|
|
|
Description:
|
|
execute$ can be used to execute a user defined subroutine, whose name may be specified as a string expression.
|
|
This feature is the only way to execute a subroutine, whose name is not known by the time you write your program. This might happen, if you want to execute a subroutine, which is compiled (using the compile command) during the course of execution of your program.
|
|
Note however, that the execute$-function is not the preferred method to execute a user defined subroutine; almost all cases you should just execute a subroutine by writing down its name within your yab program (see the example).
|
|
|
|
Example:
|
|
print execute$("foo$","Hello","world!")
|
|
sub foo$(a$,b$)
|
|
return a$+" "+b$
|
|
end sub
|
|
Explanation:
|
|
|
|
The example simply prints Hello world!, which is the return value of the user defined subroutine foo$. The same could be achieved by executing:
|
|
|
|
&exverbatim
|
|
print foo$(a$,b$)
|
|
&exverbatim
|
|
|
|
|
|
Related: compile, execute
|
|
|
|
&
|
|
execute()
|
|
|
|
Name:
|
|
execute() -- execute a user defined subroutine, which must return a number
|
|
|
|
Synopsis:
|
|
print execute("bar","arg1","arg2")
|
|
|
|
Description:
|
|
The execute-function is the counterpart of the execute$-function (please see there for some caveats). execute executes subroutines, which returns a number.
|
|
|
|
Example:
|
|
print execute("bar",2,3)
|
|
sub bar(a,b)
|
|
return a+b
|
|
end sub
|
|
Related: compile, execute$
|
|
|
|
&
|
|
exit
|
|
|
|
Name:
|
|
exit -- terminate your program
|
|
|
|
Synopsis:
|
|
exit
|
|
exit 1
|
|
|
|
Description:
|
|
Terminate your program and return any given value to the operating system. exit is similar to end, but it will terminate your program immediately, no matter what.
|
|
|
|
Example:
|
|
print "Do you want to continue ?"
|
|
input "Please answer y(es) or n(o): " a$
|
|
if (lower$(left$(a$,1))="n") exit 1
|
|
Related: end
|
|
|
|
&
|
|
iscomputeron
|
|
|
|
Name:
|
|
iscomputeron -- tells you whether the computer is on
|
|
|
|
Synopsis:
|
|
IsItTurnedOn = ISCOMPUTERON
|
|
|
|
Description:
|
|
Returns 1 if the computer is on. If the computer isn't on, the value returned by this function is undefined.
|
|
|
|
Example:
|
|
print "This program will run until the computer is shut down :)"
|
|
while(iscomputeron)
|
|
wend
|
|
Explanation:
|
|
|
|
Iscomputeron looks nice for endless loops.
|
|
|
|
&
|
|
pause
|
|
|
|
Name:
|
|
pause -- pause, sleep, wait for the specified number of seconds
|
|
|
|
Synopsis:
|
|
pause 5
|
|
|
|
Description:
|
|
The pause-command has many different names: You may write pause, sleep or wait interchangable; whatever you write, yab will always do exactly the same.
|
|
|
|
The pause-command will simply wait for the specified number of seconds. This may be a fractional number, so you may well wait less than a second. However, if you try to pause for a smaller and smaller interval (e.g. 0.1 seconds, 0.01 seconds, 0.001 seconds and so on) you will find that at some point yab will not wait at all.
|
|
The pause-command cannot be interrupted. However, sometimes you may want the wait to be interuptible by simply pressing a key on the keyboard. In such cases you should consider using the inkey$-function, with a number of seconds as an argument).
|
|
|
|
Example:
|
|
deg=0
|
|
do
|
|
maxx=44+40*sin(deg)
|
|
for x=1 to maxx
|
|
print "*"
|
|
next x
|
|
pause 0.1+(maxx*maxx/(4*84*84))
|
|
print
|
|
deg=deg+0.1
|
|
loop
|
|
Explanation:
|
|
|
|
This example draws a sine-curve; due to the pause-statement the speed of drawing varies in the same way as the speed of a ball might vary, if it would roll along this curve under the influence of gravity.
|
|
|
|
|
|
Related: sleep, wait
|
|
|
|
&
|
|
peek
|
|
|
|
Name:
|
|
peek -- retrieve various internal informations
|
|
|
|
Synopsis:
|
|
print peek("foo")
|
|
a=peek(#1)
|
|
|
|
Description:
|
|
The peek-function has many different and mostly unrelated uses. It is a kind of grabbag for retrieving all kinds of numerical information, internal to yab. The meaning of the numbers returned be the peek-function depends on the string or number passed as an argument.
|
|
|
|
peek always returns a number, however the closely related peek$-function exists, which may be used to retrieve string information from among the internals of yab. Finally note, that some of the values which are retrieved with peek may even be changed, using the poke-function.
|
|
|
|
There are two variants of the peek-function: One expects an integer, positive number and is described within the first entry of the list below. The other variant expects one of a well defined set of strings as described in the second and all the following entries of the list below.
|
|
|
|
peek(a), peek(#a)
|
|
Read a single character from the file a (which must be open of course).
|
|
|
|
peek("screenheight")
|
|
Return the height in characters of the window, wherein yab runs. If you have not called clear screen yet, this peekwill return 0, regardless of the size of your terminal.
|
|
|
|
peek("screenwidth")
|
|
Return the width in characters of the window, wherein yab runs. If you have not called clear screen yet, this peekwill return 0, regardless of the size of your terminal.
|
|
|
|
peek("argument")
|
|
Return the number of arguments, that have been passed to yab at invocation time. E.g. if yab has been called like this:
|
|
yab foo.yab bar baz
|
|
then peek("argument") will return 2. This is because foo.yab is treated as the name of the program to run, whereas bar and baz are considered arguments to the program, which are passed on the commandline. The function peek("argument") can be written as peek("arguments") too.
|
|
You will want to check out the corresponding function peek$("argument") to actually retrieve the arguments. Note, that each call to peek$("argument") reduces the number returned by peek("argument").
|
|
|
|
peek("isbound")
|
|
Return true, if the executing yab-program is part of a standalone program; see the section about creating a standalone-program for details.
|
|
|
|
peek("version")
|
|
Return the version number of yab (e.g. 1).
|
|
|
|
peek("error")
|
|
Return a number specifying the nature of the last error in an open- or seek-statement. Normally an error within an open-statement immediately terminates your program with an appropriate error-message, so there is no chance and no need to learn more about the nature of the error. However, if you use open as a condition (e.g. if (open(#1,"foo")) ...) the outcome (success or failure) of the open-operation will determine, if the condition evaluates to true or false. If now such an operation fails, your program will not be terminated and you might want to learn the reason for failure. This reason will be returned by peek("error") (as a number) or by peek$("error") (as a string)The table below shows the various error codes; the value returned by peek$("error") explains the nature of the error. Note, that the codes 10,11 and 12 refer to the seek-command.
|
|
|
|
Error codes
|
|
|
|
peek("error")| peek$("error") | Explanation
|
|
2 Stream already in use Do not try to open one and the same
|
|
filenumber twice; rather close it first.
|
|
|
|
3 'x' is not a valid filemode The optional filemode argument, which may
|
|
be passed to the open-function, has an
|
|
invalid value
|
|
|
|
4 could not open 'foo' The open-call did not work, no further
|
|
explanation is available.
|
|
|
|
5 reached maximum number
|
|
of open files You have opened more files than your
|
|
operating system permits.
|
|
|
|
9 invalid stream number An attempt to use an invalid
|
|
(e.g. negative) stream number;
|
|
example: open(-1,"foo")
|
|
|
|
10 could not position stream x
|
|
to byte y seek did not work.
|
|
|
|
11 stream x not open You have tried to seek within a stream,
|
|
that has not been opened yet.
|
|
|
|
12 seek mode 'x' is none of
|
|
begin,end,here The argument, which has been passed to
|
|
seek is invalid.
|
|
|
|
Example:
|
|
open "foo" for reading as #1
|
|
open "bar" for writing as #2
|
|
while(not eof(#1))
|
|
poke #2,chr$(peek(#1));
|
|
wend
|
|
Explanation:
|
|
|
|
This program will copy the file foo byte by byte to bar.
|
|
Note, that each peek does something entirely different, and only one has been demonstratedabove. Therefore you need to make up examples yourself for all the other peeks.
|
|
|
|
|
|
Related: peek$, poke, open
|
|
|
|
&
|
|
peek$
|
|
|
|
Name:
|
|
peek$ -- retrieve various internal string-informations
|
|
|
|
Synopsis:
|
|
print peek$("foo")
|
|
|
|
Description:
|
|
The peek$-function has many different and unrelated uses. It is a kind of grabbag for retrieving all kinds of string information, internal to yab; the exact nature of the strings returned be the peek$-function depends on the string passed as an argument.
|
|
|
|
peek$ always returns a string, however the closely related peek-function exists, which may be used to retrieve numerical information from among the internals of yab. Finally note, that some of the values which are retrieved with peek$ may even be changed, using the poke-function.
|
|
|
|
The following list shows all possible arguments to peek$:peek$("infolevel")Returns either "debug", "note", "warning", "error" or "fatal", depending on the current infolevel. This value can be specified with an option on the commandline or changed during the execution of the program with the corresponding poke; however, normally only the author of yab would want to change this from its default value "warning".
|
|
|
|
peek$("error")
|
|
Return a string describing the nature of the last error in an open- or seek-statement. See the corresponding peek("error") for a detailed description.
|
|
|
|
peek$("library")
|
|
Return the name of the library, this statement is contained in. See the import-command for a detailed description or for more about libraries.
|
|
|
|
peek$("os")
|
|
This peek returns the name of the operating system, where your yab version was compiled on. This can be either "BeOS" or "ZETA". On BeOS R5 it will always be "BeOS" while on ZETA it can be both. To check whether the system is really running ZETA do: RealOS$ = upper$(system$("uname -o"))
|
|
|
|
peek$("env","NAME")
|
|
Return the environment variable specified by NAME (which may be any string expression). Which kind of environment variables are available on your system depends, as well as their meaning, on your system; however typing env on the commandline will produce a list. Note, that peek$("env",...) can be written as peek$("environment",...) too.
|
|
|
|
peek$("argument")
|
|
Return one of the arguments, that have been passed to yab at invocation time (the next call will return the the second argument, and so on). E.g. if yab has been called like this: yab foo.yab bar baz, then the first call to peek$("argument") will return bar. This is because foo.yab is treated as the name of the program to run, whereas bar and baz are considered arguments to this program, which are passed on the commandline. The second call to peek$("argument") will return baz. Note, that peek$("argument") can be written as peek$("arguments").
|
|
Finally you will want to check out the corresponding function peek("argument").
|
|
|
|
Example:
|
|
print "You have supplied these arguments: "
|
|
while(peek("argument"))
|
|
print peek("argument"),peek$("argument")
|
|
wend
|
|
Explanation:
|
|
|
|
If you save this program in a file foo.yab and execute it via yab t.yab a b c, your will get this output:
|
|
|
|
&exverbatim
|
|
3a
|
|
2b
|
|
1c
|
|
&exverbatim
|
|
|
|
|
|
Related: peek, poke, open
|
|
|
|
&
|
|
poke
|
|
|
|
Name:
|
|
poke -- change selected internals of yab
|
|
|
|
Synopsis:
|
|
poke "foo","bar"
|
|
poke "foo",baz
|
|
poke #a,"bar"
|
|
poke #a,baz
|
|
|
|
Description:
|
|
The poke-command may be used to change details of yabs behaviour. Like the related function peek, poke does many different things, depending on the arguments supplied.
|
|
|
|
Here are the different things you can do with poke:poke "infolevel","debug"Change the amount of internal information, that yab outputs during execution.
|
|
The second argument can be either "debug", "note", "warning", "error" or "fatal". However, normally you will not want to change this from its default value "warning". See also the related peek$("infolevel").
|
|
|
|
poke #1,a
|
|
Write the given byte (a in the example above) to the specified stream (#a in the example).
|
|
|
|
See also the related function peek(#1).
|
|
|
|
Example:
|
|
print "Hello, now you will see, how much work"
|
|
print "a simple for-loop involves ..."
|
|
input "Please press return " a$
|
|
poke "infolevel","debug"
|
|
for a=1 to 10:next a
|
|
Explanation:
|
|
|
|
This example only demonstrates one of the many pokes, which are described above: The program switches the infolevel to debug, which makes yab produce a lot of debug-messages during the subsequent for-loop.
|
|
|
|
|
|
Related: peek, peek$
|
|
|
|
&
|
|
rem
|
|
|
|
Name:
|
|
rem -- start a comment
|
|
|
|
Synopsis:
|
|
rem Hey, this is a comment
|
|
# this is a comment too
|
|
// even this
|
|
print "Not a comment" # This is an error!!
|
|
print "Not a comment":// But this is again a valid comment
|
|
print "Not a comment" // even this.
|
|
print "Not a comment" rem and this!
|
|
|
|
Description:
|
|
rem introduces a comment (like # or //), that extends up to the end of the line.
|
|
Those comments do not even need a colon (':' infront of them); they (rem, # and //) all behave alike except for #, which may only appear at the very beginning of a line; therefore the fourth example in the synopsis above (print "Not a comment" # This is an error!!) is indeed an error.
|
|
Note, that rem is an abbreviation for remark. remark however is not a valid command in yab.
|
|
Finally note, that a comment intoduced with '#' may have a special meaning under BeOS; see the entry for # for details.
|
|
|
|
Example:
|
|
#
|
|
rem comments on data structures
|
|
# are more useful than
|
|
// comments on algorithms.
|
|
rem
|
|
Explanation:
|
|
|
|
This program does nothing, but in a splendid and well commented way.
|
|
|
|
|
|
Related: #, //
|
|
|
|
&
|
|
sleep
|
|
|
|
Name:
|
|
sleep -- pause, sleep, wait for the specified number of seconds
|
|
|
|
Synopsis:
|
|
sleep 4
|
|
|
|
Description:
|
|
The sleep-command has many different names: You may write pause, sleep or wait interchangable; whatever you write, yab will always do exactly the same.
|
|
Therefore you should refer to the entry for the pause-function for further information.
|
|
|
|
&
|
|
system$()
|
|
|
|
Name:
|
|
system$() -- hand a statement over to your operating system and return its output
|
|
|
|
Synopsis:
|
|
print system$("dir")
|
|
|
|
Description:
|
|
The system$-command accepts a single string argument, specifying a command, that can be found and executed by your operating system. It returns the output of this command as one big string.
|
|
|
|
Example:
|
|
input "Please enter the name of a directory: " d$
|
|
print
|
|
print "This is the contents of the '"+d$+"':"
|
|
print system$("ls -l "+d$)
|
|
Explanation:
|
|
|
|
This example lists the contents of a directory, employing the ls-command.
|
|
|
|
|
|
Related: system
|
|
|
|
&
|
|
system()
|
|
|
|
Name:
|
|
system() -- hand a statement over to your operating system and return its exitcode
|
|
|
|
Synopsis:
|
|
ret=system("foo")
|
|
system("bar")
|
|
|
|
Description:
|
|
The system-command accepts a single string argument, which specifies a command to be executed. The function will return the exitcode of the command; its output (if any) will be lost.
|
|
|
|
Example:
|
|
print "Please enter the name of the file, that should be deleted."
|
|
input f$
|
|
if (system("rm "+f$+" >/dev/null 2>&1")) then
|
|
print "Error!"
|
|
else
|
|
print "okay."
|
|
endif
|
|
Explanation:
|
|
|
|
This program uses the commandline command rm to remove a file.
|
|
|
|
Related: system$
|
|
|
|
&
|
|
thread get
|
|
|
|
Name:
|
|
thread get -- get the thread identification for a team or program
|
|
|
|
Synopsis:
|
|
Id = THREAD GET Option$, Program$
|
|
|
|
Description:
|
|
For more advanced control of the running threads, this command provides you with ID a given program named Program$. Option$ can be set as follows:
|
|
|
|
Option$ = "TeamID" -- returns the team ID for the program named Program$. Specify the whole path with parameters (only the first 64 characters are important) for the team, the ID of the first team with this path and parameters will be returned.
|
|
|
|
Option$ = "ThreadID" -- returns the thread ID for the program named Program$. Specify the program name, the ID of the first thread with this name will be returned.
|
|
|
|
Thread get will return -1 when the program was not found. This helps you to find out whether a program e.g. started with the system command is still running or not.
|
|
|
|
Note: Using thread get is much better than trying to parse "ps" from the command line.
|
|
|
|
Example:
|
|
print thread get "teamid", "/boot/home/config/bin/yab"
|
|
print thread get "threadid", "yab"
|
|
Explanation:
|
|
|
|
The first statement prints the team ID number of the first yab program running. The second statement prints the first thread ID of the first yab program running. Note: The team ID takes the whole path while the thread ID only takes the program name.
|
|
|
|
Related: thread remove
|
|
&
|
|
thread remove
|
|
|
|
Name:
|
|
thread remove -- kill a running thread or team
|
|
|
|
Synopsis:
|
|
Success = THREAD REMOVE Option$, ID
|
|
|
|
Description:
|
|
For a given ID this command kills either the team or the thread. Thus Option$ is either "TeamID" or "ThreadID". If the team or thread was killed successfully Success is set to true, otherwise it is set to false.
|
|
|
|
Note: You can crash your system with this command! If you do not know what this command is meant for, then do not use it!
|
|
|
|
Example:
|
|
id = thread get "teamid", "/boot/home/config/bin/yab kamikaze.yab"
|
|
print "Commiting suicide..."
|
|
success = thread remove "teamid", id
|
|
print "This line is never reached."
|
|
Explanation:
|
|
|
|
Save this example in the file kamikaze.yab and start it from the command line (not from the IDE). It first gets the ID from itself and then kills its own team. Thus the last print command is not executed anymore. This is a very unelegant way to exit.
|
|
|
|
Related: thread get
|
|
&
|
|
time$
|
|
|
|
Name:
|
|
time$ -- return a string containing the current time
|
|
|
|
Synopsis:
|
|
print time$
|
|
print time$()
|
|
|
|
Description:
|
|
The time$ function returns the current time in four fields separated by hyphens '-'. The fields are:The current hour in the range from 0 to 23, padded with zeroes (e.g. 00 or 04) to a length of two characters.
|
|
|
|
The number of minutes, padded with zeroes.
|
|
The number of seconds, padded with zeroes.
|
|
The number of seconds, that have elapsed since the program has been started. This value encreases as long as your program runs and is therefore unbound and not padded with zeroes.
|
|
|
|
At the time of writing this documentation, time$ returns 22-58-53-0. Note, that the first three of the four fields returned by time$ have a fixed width; therefore it is easy to extract some fields with the usual string-functions mid$ (and others).
|
|
|
|
Example:
|
|
print "Hello it is ",time$
|
|
print "An empty for-loop with ten million iterations takes "
|
|
s=val(mid$(time$,10))
|
|
for a=1 to 10000000:next a
|
|
e=val(mid$(time$,10))
|
|
print e-s," seconds"
|
|
Explanation:
|
|
|
|
This program benchmarks the for-loop and uses the fourth field of the string returned by time$.
|
|
|
|
|
|
Related: date$
|
|
|
|
&
|
|
to
|
|
|
|
Name:
|
|
to -- this keyword appears as part of other statements
|
|
|
|
Synopsis
|
|
for a=1 to 100 step 2
|
|
...
|
|
next a
|
|
draw line x,y to a,b, View$
|
|
|
|
Description:
|
|
The to-keyword serves two purposes (which are not related at all):within for-statements, to specify the upper bound of the loop.
|
|
Within any graphical command (e.g. line), that requires two points (i.e. four numbers) as arguments, a comma ',' might be replaced with the keyword to. I.e. instead of 100,100,200,200 you may write 100,100 to 200,200 in such commands.
|
|
|
|
Related: for, draw line, view
|
|
|
|
&
|
|
//
|
|
|
|
Name:
|
|
// -- starts a comment
|
|
|
|
Synopsis:
|
|
// This is a comment!
|
|
|
|
Description:
|
|
The double-slash ('//') is (besides REM and '#') the third way to start a comment. '//' is the latest and greatest in the field of commenting and allows yab to catch up with such cool languages like C++ and Java.
|
|
|
|
Example:
|
|
// Another comment.
|
|
print "Hello world!" // Another comment
|
|
Explanation:
|
|
|
|
Unlike the example given for '#' this example is syntactically correct and will not produce an error.
|
|
|
|
|
|
Related: #, rem
|
|
|
|
&
|
|
:
|
|
|
|
Name:
|
|
: -- separate commands from each other
|
|
|
|
Synopsis:
|
|
print "Hello ":print "World"
|
|
|
|
Description:
|
|
The colon (':') separates multiple commands on a single line.
|
|
The colon and the newline-character have mostly the same effect, only that the latter, well, starts a new line too. The only other difference is their effect within the (so-called) short if, which is an if-statement without the keyword then. Please see the entry for if for more details.
|
|
|
|
Example:
|
|
if (a<10) print "Hello ":print "World!"
|
|
Explanation:
|
|
|
|
This example demonstrates the difference between colon and newline as described above.
|
|
|
|
|
|
Related: if
|
|
|
|
&GUI
|
|
&Drawing
|
|
&
|
|
draw circle
|
|
|
|
Name:
|
|
draw circle -- draw a circle
|
|
|
|
Synopsis:
|
|
DRAW CIRCLE x,y, Radius, Target$
|
|
|
|
Description:
|
|
This command will draw a circle on Target$. Target$ has to be either a valid view, bitmap or canvas. The center of the circle is (x,y) and the circle has a radius of Radius.
|
|
|
|
At default it will draw a filled circle in the current highcolor. With the draw set command you can change the filling settings.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
draw set true, "HighSolidFill"
|
|
draw circle 150,150, 75, "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Related: draw curve, draw dot, draw ellipse, draw flush, draw line, draw rect, draw set
|
|
&
|
|
draw curve
|
|
|
|
Name:
|
|
draw curve -- draw a Bezier curve with four reference points
|
|
|
|
Synopsis:
|
|
DRAW CURVE x1,y1, x2,y2, x3,y3, x4,y4, Target$
|
|
|
|
Description:
|
|
Bezier curves are defined by a number of points. They will always start in the first point and end in the last one. The curve will always be within the four sides if you connect the points directly. For our command, the curve is defined by four points (x1,y1) ... (x4,y4) and it is drawn on Target$. Target$ has to be either a valid view, bitmap or canvas.
|
|
|
|
At default it will draw a filled curve in the current highcolor. With the draw set command you can change the filling settings. Note: A filled curve might have refresh problems due to a bug in the app-server.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
draw set true, "HighSolidFill"
|
|
draw curve 10,150, 75,60, 150,20, 250,140, "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Related: draw circle, draw dot, draw ellipse, draw flush, draw line, draw rect, draw set
|
|
&
|
|
draw dot
|
|
|
|
Name:
|
|
draw dot -- draw a single dot
|
|
|
|
Synopsis:
|
|
DRAW DOT x,y, View$
|
|
|
|
Description:
|
|
Draw a single dot at (x,y) on Target$. Target$ has to be either a valid view, bitmap or canvas.
|
|
|
|
At default the dot is drawn in the current highcolor.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
for i = 0 to 300 step 0.5
|
|
draw dot i, sin(i*50)*50+150, "Example"
|
|
next i
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This program draws a sinus curve with single dots.
|
|
|
|
Related: draw circle, draw curve, draw ellipse, draw flush, draw line, draw rect, draw set
|
|
&
|
|
draw ellipse
|
|
|
|
Name:
|
|
draw ellipse -- draw an ellipse
|
|
|
|
Synopsis:
|
|
DRAW ELLIPSE x,y, RadiusX, RadiusY, View$
|
|
|
|
Description:
|
|
This command will draw an ellipse on Target$. Target$ has to be either a valid view, bitmap or canvas. The center of the ellipse is (x,y) and the ellipse has a horizontal radius of RadiusX and a vertical radius of RadiusY.
|
|
|
|
At default it will draw a filled ellipse in the current highcolor. With the draw set command you can change the filling settings.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
draw set true, "HighSolidFill"
|
|
draw ellipse 150,150, 75, 30, "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Related: draw circle, draw curve, draw dot, draw flush, draw line, draw rect, draw set
|
|
&
|
|
draw flush
|
|
|
|
Name:
|
|
draw flush -- clear all prior draw commands
|
|
|
|
Synopsis:
|
|
DRAW FLUSH View$
|
|
|
|
Description:
|
|
Draw flush clears the view named View$ from all drawings.
|
|
|
|
In yab, all draw commands are stored in a list for every view. If the window is updated, e.g. when resized, all prior drawing is repeated. If you do a lot of drawing in a view, you might notice the redrawing due to flickering. if you want to clear your view, it is much better to clear it with draw flush than e.g. drawing a big rectangle over the other drawings. For flickerfree drawing consider to draw on a canvas instead of a view.
|
|
|
|
Note: This does not work for canvas and bitmaps.
|
|
|
|
Note: Widgets are not affected by draw flush.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
draw line 0,0 to 300,300, "Example"
|
|
draw circle 100,50, 20, "Example"
|
|
draw rect 10,200 to 200,250, "Example"
|
|
sleep 1
|
|
draw flush "Example"
|
|
sleep 3
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
In this example, some things are drawn on the window and then cleared by the draw flush command.
|
|
|
|
Related: draw circle, draw curve, draw dot, draw ellipse, draw line, draw rect, draw set
|
|
&
|
|
draw get
|
|
|
|
Name:
|
|
draw get -- retrieve font properties
|
|
|
|
Synopsis:
|
|
Width = DRAW GET FontProperty$, Text$, Target$
|
|
Height = DRAW GET FontProperty$, Target$
|
|
|
|
Description:
|
|
The draw get command provides you with some information about the width or height of a string with the current font settings that are used for the draw text command.
|
|
|
|
If FontProperty$ is set to "Text-Width", you have to provide a string Text$ too. The resulting Width is the width of Text$ in the current font setting. The width of a string e.g. helps you to align text. Note: Text$ will not be localized automatically, you have to translate it yourself with translate$(Text$). Target$ has to be either a valid view, bitmap or canvas.
|
|
|
|
If FontProperty$ is set to "Max-Text-Height" you get the maximum height of the font as return value. The normal font size is the size starting at the baseline. The maximum height gives you the size plus how far the characters can descend below the baseline.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
// set font
|
|
draw set "Zurich, Roman, 25", "Example"
|
|
draw text 50,150, "yab Example", "Example"
|
|
// the string length
|
|
width = draw get "text-width", "yab Example", "Example"
|
|
// baseline
|
|
draw set "highcolor", 0,0,255, "Example"
|
|
draw line 40,150 to width+60,150, "Example"
|
|
// font size
|
|
draw set "highcolor", 255,0,255, "Example"
|
|
draw line 40,150-25 to width+60,150-25, "Example"
|
|
// descend below baseline
|
|
maxheight = draw get "max-text-height", "Example"
|
|
draw set "highcolor", 255,0,0, "Example"
|
|
draw line 40,150-25+maxheight to width+60,150-25+maxheight, "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The example shows the baseline (blue line), the font size (pink line) and the lower boundary (red line) for the given string. The lower boundary is calculated by: baseline - font size + maximum text height. If you respect these distances, you can align text pretty well.
|
|
|
|
Related: draw get$, draw set, draw text
|
|
&
|
|
draw get$
|
|
|
|
Name:
|
|
draw get$ -- retrieve information about the installed fonts
|
|
|
|
Synopsis:
|
|
FontFamilies$ = DRAW GET$ "FontFamily"
|
|
FontStyles$ = DRAW GET$ FontFamily$
|
|
|
|
Description:
|
|
The draw get$ command reads out the information about all installed fonts and their styles.
|
|
|
|
Use the parameter "FontFamily" first to get all font families. For a given font family, get the possible styles with the family name as parameter.
|
|
|
|
Use draw set or textedit set to set the font for a draw text or textedit.
|
|
|
|
Example:
|
|
dim fonts$(1)
|
|
dim styles$(1)
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
menu "File", "Quit", "Q", "Example"
|
|
fontfamilies$ = draw get$ "fontfamily"
|
|
numFonts = token(fontfamilies$, fonts$(), "|")
|
|
for i = 1 to numFonts
|
|
menu "Fonts", fonts$(i), "", "Example"
|
|
fontstyles$ = draw get$ fonts$(i)
|
|
numStyles = token(fontstyles$, styles$(), "|")
|
|
for j = 1 to numStyles
|
|
submenu "Fonts", fonts$(i), styles$(j), "", "Example"
|
|
next j
|
|
submenu set "Fonts", fonts$(i), true, "Example"
|
|
next i
|
|
while(not instr(message$, "Quit"))
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This example sets up a whole menu with all fonts installed and their styles. Note: It is up to you to deselect old submenu items in this example whenever a new item is selected. In other words, this simple example allows several font selections, which is probably not what you want.
|
|
|
|
Related: draw get, draw set, draw text, textedit set
|
|
&
|
|
draw image
|
|
|
|
Name:
|
|
draw image -- load and display an image file
|
|
|
|
Synopsis:
|
|
LoadError = DRAW IMAGE x,y, ImageFile$, Target$
|
|
LoadError = DRAW IMAGE x1,y1 TO x2,y2, ImageFile$, Target$
|
|
|
|
Description:
|
|
The image with the filename ImageFile$ is loaded and put on Target$. Target$ has to be either a valid view, bitmap or canvas. Any image files that are understood by the system can be used. Transparent images are supported, however they might cause problems when printed with the printer command.
|
|
|
|
If only one coordinate pair is given, the image will be displayed in its full size where (x,y) is the upper left corner. If the second coordinates are given too, the image will be resized from (x1,y1) to (x2,y2).
|
|
If x2 is set to -1, the width is scaled according to the height;
|
|
if y2 is set to -1, the height is scaled according to the width;
|
|
if x2 and y2 are set to -1, the image is not scaled at all.
|
|
|
|
Draw image returns information about the success of the loading procedure:
|
|
LoadError = 0, image successfully loaded
|
|
LoadError = 1, the file was not found
|
|
LoadError = 2, the translator roster was not found, i.e. the system does not understand the image type
|
|
LoadError = 3, translation failed, maybe the file is corrupted?
|
|
LoadError = 4, detaching the bitmap failed, maybe out of memory?
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
err = draw image 10,10, "mypicture.png", "Example"
|
|
switch(err)
|
|
case 1: alert "File not found!", "Ok", "stop"
|
|
exit(1)
|
|
case 2: alert "Translator not found!", "Ok", "stop"
|
|
exit(1)
|
|
case 3: alert "Translation failed!", "Ok", "stop"
|
|
exit(1)
|
|
case 4: alert "Detaching failed!", "Ok", "stop"
|
|
exit(1)
|
|
default:
|
|
break
|
|
end switch
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The example program will try to load and display the file "mypicture.png" from the current directory. If the load process failed, an error message is produced.
|
|
|
|
Related: draw flush
|
|
&
|
|
draw line
|
|
|
|
Name:
|
|
draw line -- draw a line
|
|
|
|
Synopsis:
|
|
DRAW LINE x1,y1 TO x2,y2, Target$
|
|
|
|
Description:
|
|
This command draws a line from (x1,y1) to (x2,y2) on Target$ in the current highcolor. Target$ has to be either a valid view, bitmap or canvas.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
for i = 0 to 300 step 10
|
|
draw line 0,i to i,300, "Example"
|
|
draw line 300,i to i,0, "Example"
|
|
next i
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Draws some nice lines.
|
|
|
|
Related: draw circle, draw curve, draw dot, draw ellipse, draw flush, draw rect, draw set
|
|
&
|
|
draw rect
|
|
|
|
Name:
|
|
draw rect -- draw a rectangle
|
|
|
|
Synopsis:
|
|
DRAW RECT x1,y1 TO x2,y2, Target$
|
|
|
|
Description:
|
|
This command will draw a rectangle from (x1,y1) to (x2,y2) on Target$. Target$ has to be either a valid view, bitmap or canvas.
|
|
|
|
At default it will draw a filled rectangle in the current highcolor. With the draw set command you can change the filling settings.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
draw set true, "HighSolidFill"
|
|
draw rect 10,10, 290, 290, "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Display a rectangle.
|
|
|
|
Related: draw circle, draw curve, draw dot, draw ellipse, draw flush, draw line, draw set
|
|
&
|
|
draw set
|
|
|
|
Name:
|
|
draw set -- set various drawing parameters
|
|
|
|
Synopsis:
|
|
DRAW SET Color$, r,g,b, Target$
|
|
DRAW SET "Alpha", Alpha-Value
|
|
DRAW SET IsStroke, Pattern$
|
|
DRAW SET Font$, Target$
|
|
|
|
Description:
|
|
Draw set allows you to set various parameters for the other draw commands.
|
|
|
|
Draw set with a Color$ allows you to set three different colors: the background color of Target$, the so-called lowcolor and the highcolor. At default, everything is drawn with the current highcolor, the lowcolor is useful for patterns which can have two colors. The background color can only be set for views, otherwise Target$ has to be either a valid view, bitmap or canvas.
|
|
If Color$ = "BGColor", the background color of the view Target$ is set, default is grey (216,216,216),
|
|
if Color$ = "LowColor", the lowcolor of Target$ is set, default is grey (216,216,216),
|
|
if Color$ = "HighColor", the highcolor of Target$ is set, default is black (0,0,0).
|
|
|
|
A short note about colors: On BeOS and ZETA, colors are notated with their three component colors red (r), green (g) and blue (b). These component colors are values between 0 (dark) and 255 (light) and mixed together (additive mixture) they represent a 32bit color space. Have a look at the colorcontrol widget to learn more about colors.
|
|
|
|
Draw set with "Alpha" as option sets the alpha channel value. At default it is set to 255 which is completly opaque. The smaller the alpha value gets, the more translucent following drawings will become. Note: This only affects the graphic primitives as dot, line, rect, text etc. but not draw image.
|
|
Note: When Alpha-Value is below 255, use only HighSolidFill to draw, patterns are ignored!
|
|
Note: Transparent drawing (that is Alpha-Value below 255) is not printed (see printer) correctly!
|
|
|
|
Draw set can also set the stroke or fill parameter and a pattern. If IsStroke is true, only the outline of circle, ellipse, rectangle and curve are drawn, otherwise they are filled up (which is the default setting). The Pattern$ specifies a pattern that is used for drawing and filling. The following patterns are predefined:
|
|
If Pattern$ = "HighSolidFill" solid fill is used with the current high color (default),
|
|
if Pattern$ = "LowSolidFill" solid fill is used with the current low color,
|
|
if Pattern$ = "CheckeredFill" checkered fill is used as a combination of low- and highcolor,
|
|
otherwise Pattern$ is a 8x8 1bit map where one line is one character which is written out as its ASCII code.
|
|
Use the pattern editor to draw and calculate patterns for your convenience.
|
|
|
|
Draw set with a parameter Font$ sets the font for Target$. The Font$ consists of the font family, the font style and the font size separated with commas. E.g. the following is a valid font string:
|
|
Font$ = "Zurich, Roman, 25"
|
|
Note: Use the correct spelling of the font families and styles keeping existing spaces; they are case sensitive too.
|
|
Three special Font$ are available, namely the system fonts:
|
|
If Font$ = "system-plain", the plain system font is used (default),
|
|
if Font$ = "system-fixed", the fixed-sized system font is used,
|
|
if Font$ = "system-bold", the bold system font is used.
|
|
See the command draw get$ for more information about font families and styles.
|
|
|
|
Example:
|
|
"127191223239215187109214"
|
|
Explanation:
|
|
|
|
Related: draw circle, draw curve, draw dot, draw ellipse, draw get, draw get$, draw line, draw rect, draw text, view
|
|
&
|
|
draw text
|
|
|
|
Name:
|
|
draw text -- draw a text string in the current font
|
|
|
|
Synopsis:
|
|
DRAW TEXT x,y, Text$, Target$
|
|
|
|
Description:
|
|
Draw the string Text$ in the current font and highcolor on Target$. Target$ has to be either a valid view, bitmap or canvas. The left baseline (!) starts at (x,y). Please refer to the example of the command draw get to learn more about the font height and its baseline.
|
|
|
|
Note: The text will be anti-aliased (smoothed) with the current lowcolor. If your text looks strange and blocky, you probably should set the lowcolor to the background color.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
// set the colors, ajust lowcolor to background color
|
|
draw set "bgcolor", 0,0,125, "Example"
|
|
draw set "lowcolor", 0,0,125, "Example"
|
|
draw set "highcolor", 255,255,0, "Example"
|
|
// set the font
|
|
draw set "Zurich, Roman, 25", "Example"
|
|
// draw the text
|
|
draw text 80,150, "yab Example", "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This program sets the colors to a blue background and a yellow textcolor. It sets the font and then displays the string "yab Example".
|
|
|
|
Related: draw flush, draw get, draw get$, draw set
|
|
|
|
&Input and Messages
|
|
&
|
|
ismousein()
|
|
|
|
Name:
|
|
ismousein() -- reports whether the mouse is currently in a view
|
|
|
|
Synopsis:
|
|
State = ISMOUSEIN(View$)
|
|
|
|
Description:
|
|
Ismousein reports true whenever it is called and the mouse pointer is currently over the view named View$. This is independend of whether the window containing the view is active or not.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
while(not instr(message$, "Quit"))
|
|
if(ismousein("Example")) print "Mouse is in window"
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
After opening the window named "Example", this program checks if the mouse is currently over the window. Then a message is printed on the console.
|
|
|
|
|
|
Related: mouse message$(), mousemove$, mouse set
|
|
|
|
&
|
|
keyboard message$()
|
|
|
|
Name:
|
|
keyboard message$() -- check the keyboard for pressed buttons
|
|
|
|
Synopsis:
|
|
Msg$ = KEYBOARD MESSAGE$(View$)
|
|
|
|
Description:
|
|
With keyboard message$(), you can receive key strokes. These key strokes are always sent to the view that currently has focus, so you should make sure, that you set the focus for the view named View$. This avoids trouble with textedit or textcontrol widgets that rely on user input too.
|
|
|
|
For normal keys, yab simply returns the key, e.g. a, 1 or !. For function keys you will get f1, f2 and so on. Other special keys will return these strings respectively: enter, backspace, del, esc, pageup, pagedown and tab. Modifier keys (e.g. ctrl, alt or shift) by themself can not be detected (however, if you press shift and e.g. a simultaniously, keyboard message$ will return the letter A instead of a of course).
|
|
|
|
If you are interested in getting the key strokes in a terminal, have a look at the inkey$ command. Note, other than inkey$, keyboard message$() does not wait for a key to be pressed. It will simply return an empty string ("") when no key is pressed.
|
|
|
|
Design:
|
|
It is quite hard to use keyboard message$() for a input method that behaves like e.g. a textcontrol because you have to control the key repeat rate yourself. So rather use a textcontrol, spincontrol or a textedit widget for more complex editing.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
option set "Example", "Focus", true
|
|
while(not instr(message$, "Quit"))
|
|
k$ = keyboard message$("Example")
|
|
if(k$<>"" and k$<>old_k$) then
|
|
print "You pressed "+k$
|
|
old_k$ = k$
|
|
endif
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
This simple example first sets the focus on the view that should get the keyboard messages. Whenever a key is pressed, and it is not similar to the pressed key before, we show a text message.
|
|
|
|
Related: inkey$, mouse message$(), option set, shortcut
|
|
&
|
|
message$
|
|
|
|
Name:
|
|
message$ -- receive a system message
|
|
|
|
Synopsis:
|
|
msg$ = MESSAGE$
|
|
|
|
Description:
|
|
Message$ is one of the most important commands for graphical user interfaces. It checks the message queue for new messages that might have arrived from open windows or graphical widgets.
|
|
|
|
Most of the time the message queue is empty and message$ will return an empty string "". However, when some window or widget is selected or clicked on you probably will receive a message.
|
|
|
|
Note, once message$ is called, the queue is emptied. So you receive a message only once! It is therefore a good idea to store the message in a string (e.g. msg$) or in an array (see example below) so you can evaluate it further.
|
|
|
|
Messages are separated by the pipe symbol "|". Normally, you only receive one message. However, when there is some time passing between two message calls (e.g. because of a long calculation or a sleep command), several messages might have been coming in. Therefore you should always split the whole message into its message parts with the token() command (split() will do too). Use a loop to go through all messages then.
|
|
|
|
The kind of message is related to the window or widget sending the messgae. Check the different widget entries for more information on the type of message they send.
|
|
|
|
Currently, there is one general system message that you always should process:
|
|
"_QuitRequested" -- this means that your program was asked to quit by another program (e.g. by ProcessController or the system shutdown)
|
|
|
|
Example:
|
|
// set DEBUG to true to have the messages printed on the console
|
|
// set it to false to disable this feature
|
|
DEBUG = true
|
|
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
|
|
dim msg$(1)
|
|
while(not quitting)
|
|
// get all messages and split them immediatly
|
|
numMessages = token(message$, msg$(), "|")
|
|
|
|
// go through all messages
|
|
for i = 1 to numMessages
|
|
// if DEBUG is set, print the current message
|
|
if(DEBUG) print msg$(i)
|
|
switch(msg$(i))
|
|
case "_QuitRequested"
|
|
case "Example:_QuitRequested"
|
|
quitting = true
|
|
break
|
|
end switch
|
|
next i
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
This example shows a message loop as it is recommended for most programs. The message$ is split into parts by the token command. Using a switch(), the different messages can be examined.
|
|
|
|
Related: message send
|
|
&
|
|
message send
|
|
|
|
Name:
|
|
message send -- send a system message
|
|
|
|
Synopsis:
|
|
Arrived = MESSAGE SEND Application$, Message$
|
|
|
|
Description:
|
|
This is an rather advanced command for sending messages to other yab programs.
|
|
|
|
The target program should have the signature Application$. The default signature is: "application/x-vnd.yab-app".
|
|
|
|
You can change the signature for yab scripts when you add a comment in the first or second line of your program like this:
|
|
// mimetype "application/x-vnd.myapp"
|
|
|
|
For binaries, change the signature using the external QuickRes program.
|
|
|
|
The command returns one of the following error codes:
|
|
0: Message was delivered
|
|
1: The destination program was not found
|
|
2: The target's message queue is full
|
|
3: Time out, the message never made it to the target
|
|
4: An other error occurred
|
|
|
|
Message:
|
|
The destination yab application will produce a message$ stating:
|
|
|
|
&exverbatim
|
|
_Scripting:...|
|
|
&exverbatim
|
|
|
|
(The ... is the Message$.)
|
|
|
|
See the files Ping.yab and Pong.yab for a nice example of message send. As you have to start both, use the tracker or the terminal to run them, but not the IDE.
|
|
|
|
Related: message$
|
|
&
|
|
mouse message$()
|
|
|
|
Name:
|
|
mouse message$() -- check the mouse for its position and the state of the buttons
|
|
|
|
Synopsis:
|
|
Mouse$ = MOUSE MESSAGE$(View$)
|
|
|
|
Description:
|
|
Mouse message$() returns a string containing information of the mouse coordinates (relative to View$) and the state of the mouse buttons.
|
|
|
|
The mouse string has the format "X:Y:LMB:MMB:RMB" where MB is the corresponding left, middle, right mousebutton and X and Y are the coordinates relative to the view named View$. Use the token() command to split the string into an array and use val() to get the actual numerical values (see the example below).
|
|
|
|
Design:
|
|
Using the mouse message$() is not recommended for beginners. Also the advanced programmer should use it not too intensivly, but rather rely on the existing widgets. However, controlling the mouse gives you some means to create some own sort of widgets or some cool mouse-over effects.
|
|
|
|
Example:
|
|
window open 100,100 to 500,500, "Example", "Example"
|
|
x = 100
|
|
y = 100
|
|
draw rect x,y to x+50,y+50, "Example"
|
|
text 10,10, "mytext", "Drag the square with the mouse", "Example"
|
|
dim mouse$(1)
|
|
while(not instr(message$, "Quit"))
|
|
GetMouse()
|
|
|
|
// the button is pressed and the mouse is over the rectangle, start drag
|
|
if(mlmb and mx>=x and mx<=x+50 and my>=y and my<=y+50) then
|
|
while(mlmb)
|
|
GetMouse()
|
|
x = mx-25
|
|
y = my-25
|
|
draw flush "Example"
|
|
draw rect x,y to x+50,y+50, "Example"
|
|
wend
|
|
endif
|
|
wend
|
|
window close "Example"
|
|
|
|
sub GetMouse()
|
|
n = token(mouse message$("Example"), mouse$(), ":")
|
|
mx = val(mouse$(1))
|
|
my = val(mouse$(2))
|
|
mlmb = val(mouse$(3))
|
|
end sub
|
|
Explanation:
|
|
This example lets you drag a rectangle with the mouse. It gets the current position and button state in the sub GetMouse(). Now when the left mouse button is pressed and the mouse is over the rectangle, the rectangle will be moved as long as the button is pressed. The redrawing of the rectangle can be improved by checking whether the mouse actually moved.
|
|
|
|
|
|
Related: ismousein(), keyboard message$(), mousemove$, mouse set
|
|
&
|
|
mousemove$
|
|
|
|
Name:
|
|
mousemove$ -- returns more detailed mouse messages
|
|
|
|
Synopsis:
|
|
Mouse$ = MOUSEMOVE$
|
|
|
|
Description:
|
|
This command is somewhat a duplicate to mouse message$(). However, it does not require a view to be given, but reports the name of the view back as part of the message Mouse$. The following messages can occur:
|
|
|
|
Control$+":_InsideView"
|
|
Control$+":_EnteredView"
|
|
Control$+":_ExitedView"
|
|
Control$+":_MouseDown"
|
|
Control$+":_MouseUp"
|
|
Control$+":_LeftMouseButton"
|
|
Control$+":_RightMouseButton"
|
|
Control$+":_MiddleMouseButton"
|
|
where Control$ is the ID of the widget or view where the event occured.
|
|
|
|
Related: ismousein(), mouse message$(), mouse set
|
|
&
|
|
MOUSE SET Option$
|
|
|
|
Name:
|
|
mouse set -- show or hide the mouse cursor
|
|
|
|
Synopsis:
|
|
MOUSE SET Option$
|
|
|
|
Description:
|
|
Sometimes (e.g. games) the mouse cursor is just in the way. To get rid of it for your application windows, this command allows you to hide it (or later show it again). Use Option$ as described:
|
|
|
|
Option$ = "Hide" -- hide the mouse cursor
|
|
Option$ = "Show" -- show the mouse cursor
|
|
Option$ = "Obscure" -- hide the mouse cursor until the mouse is moved
|
|
|
|
Related: ismousein(), mouse message$(), mousemove$
|
|
&
|
|
shortcut
|
|
|
|
Name:
|
|
shortcut -- sends a message when a specified shortcut key is pressed
|
|
|
|
Synopsis:
|
|
|
|
SHORTCUT View$, Shortcut$, MyMessage$
|
|
|
|
Description:
|
|
For adding keyboard shortcuts to your program that are not related to menu entries, use the shortcut command. It sends the message MyMessage$ whenever the key combination Shortcut$ is pressed and the view named View$ has focus.
|
|
|
|
The first letter of Shortcut$ specifys the shortcut key for this menu item. It is always combined with the command key which is ALT normally (or CTRL when CTRL and ALT are switched in the preferences). E.g. consider a Shortcut$ of "O" then ALT-O will send MyMessage$ to the message queue. Additionaly to the command key you can specify further modifiers which are set before the shortcut letter:
|
|
|
|
&exverbatim
|
|
"S" for the shift key
|
|
"C" for the control key (CTRL, or ALT if CTRL and ALT are switched)
|
|
"O" for the option key (on most keyboards probably the Windows button)
|
|
&exverbatim
|
|
|
|
These modifiers can be combined, but the following combinations do not work: "SO", "SC" and "SCO"
|
|
|
|
Some Shortcut examples:
|
|
|
|
&exverbatim
|
|
"O" for ALT-O
|
|
"SO" for Shift-ALT-O
|
|
"COO" for Control-Option-ALT-O
|
|
&exverbatim
|
|
|
|
Message:
|
|
Shortcut sends MyMessage$.
|
|
|
|
Design:
|
|
To use shortcuts is good but to use shortcuts in menus is much better. In menus the user can see the shortcut and does not have to memorize it. Furthermore he can select the according action by mouse too.
|
|
|
|
Use the default shortcuts as described for the menu command. Note: Other than with menu, the following shortcuts are reserved and cannot be overwritten:
|
|
|
|
&exverbatim
|
|
ALT-X
|
|
ALT-C
|
|
ALT-V
|
|
ALT-A
|
|
ALT-W
|
|
ALT-Q
|
|
&exverbatim
|
|
|
|
Example:
|
|
window open 100,100 to 300,200, "Example", "Example"
|
|
|
|
draw text 10,20, "Press Alt-B for an about window", "Example"
|
|
draw text 10,40, "Press Alt-Shift-Q to quit", "Example"
|
|
|
|
shortcut "Example", "B", "About"
|
|
shortcut "Example", "SQ", "MyQuit"
|
|
|
|
option set "Example", "focus", true
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "About")) alert "An easy shortcut example", "Dooh", "info"
|
|
if(instr(m$, "MyQuit")) then
|
|
quitting = true
|
|
elsif(instr(m$,"Quit")) then
|
|
alert "Use the shortcut to quit!", "Ok", "info"
|
|
endif
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Here two shortcuts are setup, ALT-B (or CTRL-B if ALT and CTRL are switched in your preferences) sends the message "About" and Shift-ALT-Q to send the message "MyQuit". Additionally other quit messages are rejected telling the user to only use the shortcut.
|
|
|
|
Related: keyboard message$, menu, message$
|
|
&
|
|
&Printing
|
|
&
|
|
printer
|
|
|
|
Name:
|
|
printer -- send a view to the printer
|
|
|
|
Synopsis:
|
|
PrintingError = PRINTER JobName$, SetupFile$, View$
|
|
|
|
Description:
|
|
Printer is a powerful but yet simple command to print a view named View$. The view is send to the currently active printer and put into the spooling queue. There, it is visible under the name JobName$.
|
|
|
|
SetupFile$ gives a files as saved by the printer setup command. If the setup file is not valid or empty (""), the printing setup is called first automatically. Otherwise the saved setup is used for the printing.
|
|
|
|
Printer returns one of the following numbers:
|
|
0 = No Problems
|
|
1 = Page setup failed (probably communication problems with the print server)
|
|
2 = The configuration file was loaded but page setup failed
|
|
3 = The view View$ was not found
|
|
4 = The number of pages is 0 or less
|
|
5 = The printing was canceled or something went wrong with printing
|
|
|
|
Note: PrintingError = 4 can happen because of a bug in the PDF printing driver; although a page size is shown, none is selected. If this happens, you may want to call a PRINTER SETUP for the user and try to print again.
|
|
|
|
Note: When an error with code 1,2,3 or 4 occurs, you can be shure that nothing was sent to the printer yet.
|
|
|
|
Note: Alpha transparency is not printed correctly!
|
|
|
|
Note: Due to a bug in BeOS and ZETA, there are probably problems printing CHECKBOX IMAGE and BUTTON IMAGE images, use DRAW IMAGE instead!
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
|
|
view 10,10 to 190,160, "PrintMe", "Example"
|
|
draw set "bgcolor", 255,255,255, "PrintMe"
|
|
draw text 50,50, "Print Me!", "PrintMe"
|
|
|
|
button 50,170 to 150,190, "PrintButton", "Print...", "Example"
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "PrintButton")) then
|
|
errcode = printer "Example Printjob", "", "PrintMe"
|
|
if(errcode>1) alert "Printing Problem: "+str$(errcode), "Ok", "Warning"
|
|
endif
|
|
if(instr(m$, "Quit")) quitting = true
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
First a window is opened and then a white view named "PrintMe" is put upon it. Of course it makes perfect sence to have a white background for your view that is to be printed. When the "Print..." button is pressed, the PrintMe view is send to the printer with the job name "Example Printjob". In case of an error, the user is informed.
|
|
|
|
Related: printer setup
|
|
&
|
|
printer setup
|
|
|
|
Name:
|
|
printer setup -- setup the current printer
|
|
|
|
Synopsis:
|
|
PRINTER SETUP SetupFile$
|
|
|
|
Description:
|
|
Printer setup call the setup window of the currently active printer. Here, the user can specify printing parameters like paper size or a border width. The setup is saved in the file called SetupFile$. No file is created when the user cancels the setup.
|
|
|
|
Note: At least one window has to be open before printer setup can be called.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
menu "File", "Printer Setup...", "", "Example"
|
|
menu "File", "--", "", "Example"
|
|
menu "File", "Quit", "Q", "Example"
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "Printer Setup...")) printer setup "ExamplePrinterConfig"
|
|
if(instr(m$, "Quit")) quitting = true
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
The example shows a window with a menu. When printer setup is selected from this menu, the setup is called. If the user saves the config, it will be stored in the file named "ExamplePrinterConfig".
|
|
|
|
Related: printer
|
|
&Menus
|
|
&
|
|
menu
|
|
|
|
Name:
|
|
menu -- create a menu item for the menubar
|
|
|
|
Synopsis:
|
|
MENU Head$, Menu$, Shortcut$, View$
|
|
|
|
Description:
|
|
To add a menubar with menus to a window or a view named View$ is very easy. Simply call menu with the menu entry Head$ and a menu item called Menu$. If there is no menubar yet, a new one will be created. If the entry Head$ already exists, the item Menu$ will be added to the existing items at the end.
|
|
|
|
If Menu$ is set as follows:
|
|
&exverbatim
|
|
Menu$ = "--"
|
|
&exverbatim
|
|
then the menu item will be a separator line.
|
|
|
|
The first letter of Shortcut$ specifys the shortcut key for this menu item. It is always combined with the command key which is ALT normally (or CTRL when CTRL and ALT are switched in the preferences). E.g. consider a Shortcut$ of "O" then ALT-O will appear in the menu and the user has to press ALT-O to activate this menu item. Additionaly to the command key you can specify further modifiers which are set before the shortcut letter:
|
|
|
|
&exverbatim
|
|
"S" for the shift key
|
|
"C" for the control key (CTRL, or ALT if CTRL and ALT are switched)
|
|
"O" for the option key (on most keyboards probably the Windows button)
|
|
&exverbatim
|
|
These modifiers can be combined, but the following combinations do not work: "SO", "SC" and "SCO"
|
|
|
|
Some Shortcut examples:
|
|
&exverbatim
|
|
"O" for ALT-O
|
|
"SO" for Shift-ALT-O
|
|
"COO" for Control-Option-ALT-O
|
|
&exverbatim
|
|
|
|
The height of the menubar (which depends on the size of the system menu font) can be checked with the peek command.
|
|
|
|
Message:
|
|
The menu when selected or called by the shortcut key will return a message of the format:
|
|
|
|
View$+":"+Head$+":"+Menu$
|
|
|
|
Note, when you have switched on localization, you get the translated message. Have a look at the example below, how to handle such translations.
|
|
|
|
Design:
|
|
Although views can have a menubar too, you should only give windows a menu. Use capitalized words for English menu entries (like for headings). A menu item should have three dots (...) always when the user can expect a further dialog and not an immediate action. Use the default menu head entries: File, Edit, View, Help
|
|
|
|
Use the following default shortcuts:
|
|
&exverbatim
|
|
For the menu Head$ "File":
|
|
"N" -- New
|
|
"O" -- Open
|
|
"S" -- Save
|
|
"W" -- Close
|
|
"Q" -- Quit
|
|
|
|
For the menu Head$ "Edit":
|
|
"Z" -- Undo
|
|
"X" -- Cut
|
|
"C" -- Copy
|
|
"V" -- Paste
|
|
"A" -- Select All
|
|
|
|
Further default shortcuts:
|
|
"F" -- Find
|
|
"G" -- Find Again
|
|
"H" -- Help
|
|
"P" -- Print
|
|
&exverbatim
|
|
|
|
Example:
|
|
localize
|
|
window open 100,100 to 400,300, "Example", "Example"
|
|
menu "File", "About...", "", "Example"
|
|
menu "File", "--", "", "Example"
|
|
menu "File", "Quit", "Q", "Example"
|
|
|
|
menu "Action", "My Action Menu", "COA", "Example"
|
|
|
|
dim msg$(1)
|
|
while(not quitting)
|
|
n = token(message$, msg$(), "|")
|
|
for i = 1 to n
|
|
switch(msg$(i))
|
|
case "_QuitRequested"
|
|
case "Example:_QuitRequested"
|
|
case translate$("Example:File:Quit")
|
|
quitting = true
|
|
break
|
|
case translate$("Example:File:About...")
|
|
alert "Menu example", "Ok", "info"
|
|
break
|
|
case translate$("Example:Action:My Action Menu")
|
|
press = press + 1
|
|
draw flush "Example"
|
|
draw text 50,100, translate$("Menu call: ")+str$(press), "Example"
|
|
break
|
|
end switch
|
|
next i
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
We open a window and allow localization. This should explain the usage of translating the messages in the loop. After initializing the menus, we check the messages. When a message arrives, we compare it to the translated (!) counterpart.
|
|
|
|
Related: menu set, peek, submenu, submenu set
|
|
&
|
|
menu set
|
|
|
|
Name:
|
|
menu set -- set options for the menu
|
|
|
|
Synopsis:
|
|
MENU SET MenuHead$, SetRadioMode, View$
|
|
MENU SET MenuHead$, MenuItem$, Option$, View$
|
|
|
|
Description:
|
|
This lets you set some options for the first level menu.
|
|
|
|
Given a MenuHead$ you can put the entire menu in radio mode, i.e. only one item can be selected at a time. Set SetRadioMode to true to allow radio mode, set it to false to return to a normal behavior again. Note, you have to select the first item yourself after switching to radio mode. Use the following option to do so.
|
|
|
|
Given a MenuHead$ and a MeniItem$ you can disable or enable the item or you can select it by putting a mark to it or remove the mark again. Thus the following options are valid:
|
|
|
|
&exverbatim
|
|
Option$ = "Disable" -- grey out the item so it cannot be selected anymore
|
|
Option$ = "Enable" -- enable a formerly disabled item again
|
|
Option$ = "Mark" -- mark this item
|
|
Option$ = "Plain" -- remove a mark again
|
|
&exverbatim
|
|
|
|
Example:
|
|
window open 100,100 to 400,300, "Example", "Example"
|
|
menu "Test", "Foo", "", "Example"
|
|
menu "Test", "Bar", "", "Example"
|
|
menu set "Test", "Foo", "mark", "Example"
|
|
menu set "Test", "Bar", "disable", "Example"
|
|
fooMarked = true
|
|
|
|
menu "Radio", "1", "", "Example"
|
|
menu "Radio", "2", "", "Example"
|
|
menu "Radio", "3", "", "Example"
|
|
menu set "Radio", true, "Example"
|
|
menu set "Radio", "2", "mark", "Example"
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "Quit")) quitting = true
|
|
if(instr(m$, "Foo")) then
|
|
fooMarked = not fooMarked
|
|
if(fooMarked) then
|
|
menu set "Test", "Foo", "mark", "Example"
|
|
else
|
|
menu set "Test", "Foo", "plain", "Example"
|
|
endif
|
|
endif
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
The first menu has two items, the first item is selectable. As you see in the message loop you are responsable yourself to apply or remove the mark from this item. The second item is disabled.
|
|
|
|
The second menu is in radio mode, so only one item can be selected. The user will do that for you, however you have to select an item for the first time.
|
|
|
|
Related: menu, submenu, submenu set
|
|
&
|
|
popupmenu
|
|
|
|
Name:
|
|
popupmenu -- open a popup menu
|
|
|
|
Synopsis:
|
|
Selected$ = POPUPMENU x,y, MenuItems$, View$
|
|
|
|
Description:
|
|
This function pops up a menu at the position (x,y) as upper left corner on View$. The menu contains several menu items which are given as MenuItems$. The items are separated by a pipe "|". If a menu item is a double minus, it will be used as a separator.
|
|
|
|
Your program will wait until an item is selected from the menu or the user clicks somewhere else. The command will then return either the selected item name or an empty string "" when nothing was selected.
|
|
|
|
Note, you cannot add submenus, have a radio mode or select items which is possible for menus in a menubar.
|
|
|
|
Similar to the menu, the Selected$ will contain the translation of the selected item when localization is used. Use translate$ where necessary, as explained for the menu command.
|
|
|
|
Design:
|
|
Remember to give the user a hint so he can expect a popup menu. E.g. add a small down-arrow to a button image, if this button opens a popup menu.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
button 10,10 to 100,30, "MyButton", "Popup", "Example"
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "Quit")) quitting = true
|
|
if(instr(m$, "MyButton")) then
|
|
selected$ = popupmenu 10,31, "About...|--|Quit", "Example"
|
|
if(selected$ = "About...") alert "Popupmenu example.", "Ok", "Info"
|
|
if(selected$ = "Quit") quitting = true
|
|
endif
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
The example opens a window with a button. Whenever the button is clicked on, a popup menu appears. The selection of the popup menu is then processed immediately.
|
|
|
|
Related: dropbox
|
|
&
|
|
submenu
|
|
|
|
Name:
|
|
submenu -- create a submenu item for an existing menu
|
|
|
|
Synopsis:
|
|
SUBMENU MenuHead$, MenuItem$, SubMenuItem$, Shortcut$, View$
|
|
|
|
Description:
|
|
To have a submenu to an existing menu, you have to specify the menu title MenuHead$, the menu item that will contain the submenu MenuItem$ and the new name for the submenu entry SubMenuItem$. If MenuHead$ or MenuItem$ do not exist, they are created. Similar to the menu command the submenu item can be called by a shortcut key Shortcut$. This again explained below in detail.
|
|
|
|
If SubMenuItem$ is set as follows:
|
|
&exverbatim
|
|
Menu$ = "--"
|
|
&exverbatim
|
|
then the submenu item will be a separator line.
|
|
|
|
The first letter of Shortcut$ specifys the shortcut key for this submenu item. It is always combined with the command key which is ALT normally (or CTRL when CTRL and ALT are switched in the preferences). E.g. consider a Shortcut$ of "O" then ALT-O will appear in the menu and the user has to press ALT-O to activate this menu item. Additionaly to the command key you can specify further modifiers which are set before the shortcut letter:
|
|
|
|
&exverbatim
|
|
"S" for the shift key
|
|
"C" for the control key (CTRL, or ALT if CTRL and ALT are switched)
|
|
"O" for the option key (on most keyboards probably the Windows button)
|
|
&exverbatim
|
|
These modifiers can be combined, but the following combinations do not work: "SO", "SC" and "SCO"
|
|
|
|
Some Shortcut examples:
|
|
&exverbatim
|
|
"O" for ALT-O
|
|
"SO" for Shift-ALT-O
|
|
"COO" for Control-Option-ALT-O
|
|
&exverbatim
|
|
|
|
Message:
|
|
The submenu when selected or called by the shortcut key will return a message of the format:
|
|
|
|
View$+":"+Head$+":"+MenuItem$+":"+SubMenuItem$
|
|
|
|
Note, when you have switched on localization, you get the translated message. Have a look at the example below, how to handle such translations.
|
|
|
|
Design:
|
|
Use submenus sparsely. Even a complex program like the yab IDE contains only one submenu (for the online resources). Most often submenus should only be used for a list of similar items. Use capitalized words for English menu entries (like for headings). A menu item should have three dots (...) always when the user can expect a further dialog and not an immediate action.
|
|
|
|
Example:
|
|
localize
|
|
window open 100,100 to 400,300, "Example", "Example"
|
|
|
|
submenu "File", "Alert Types", "Empty Alert...", "", "Example"
|
|
submenu "File", "Alert Types", "Info Alert...", "", "Example"
|
|
submenu "File", "Alert Types", "Idea Alert...", "", "Example"
|
|
submenu "File", "Alert Types", "Warning Alert...", "", "Example"
|
|
submenu "File", "Alert Types", "Stop Alert...", "", "Example"
|
|
|
|
menu "File", "--", "", "Example"
|
|
menu "File", "Quit", "Q", "Example"
|
|
|
|
dim msg$(1)
|
|
while(not quitting)
|
|
n = token(message$, msg$(), "|")
|
|
for i = 1 to n
|
|
switch(msg$(i))
|
|
case "_QuitRequested"
|
|
case "Example:_QuitRequested"
|
|
case translate$("Example:File:Quit")
|
|
quitting = true
|
|
break
|
|
case translate$("Example:File:Alert Types:Empty Alert...")
|
|
alert "Empty alert.", "Ok", "empty"
|
|
break
|
|
case translate$("Example:File:Alert Types:Info Alert...")
|
|
alert "Info alert.", "Ok", "info"
|
|
break
|
|
case translate$("Example:File:Alert Types:Idea Alert...")
|
|
alert "Idea alert.", "Ok", "idea"
|
|
break
|
|
case translate$("Example:File:Alert Types:Warning Alert...")
|
|
alert "Warning alert.", "Ok", "warning"
|
|
break
|
|
case translate$("Example:File:Alert Types:Stop Alert...")
|
|
alert "Stop alert.", "Ok", "stop"
|
|
break
|
|
end switch
|
|
next i
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
Here the important part is the declaration of the submenu. With the first submenu command the menubar, the menu head named "File" and the menu item named "Alert Types" are created. Because of localization we have to check the submenu message with the translate$() otherwise we would miss them.
|
|
|
|
Related: menu, menu set, submenu set
|
|
&
|
|
submenu set
|
|
|
|
Name:
|
|
submenu set -- set options for the submenu
|
|
|
|
Synopsis:
|
|
SUBMENU SET MenuHead$, MenuItem$, SetRadioMode, View$
|
|
SUBMENU SET MenuHead$, MenuItem$, SubMenuItem$, Option$, View$
|
|
|
|
Description:
|
|
This lets you set some options for the second level menu.
|
|
|
|
Given a MenuHead$ and a MenuItem$ you can put the entire submenu in radio mode, i.e. only one item can be selected at a time. Set SetRadioMode to true to allow radio mode, set it to false to return to a normal behavior again. Note, you have to select the first item yourself after switching to radio mode. Use the following option to do so.
|
|
|
|
Given a MenuHead$, a MeniItem$ and a SubMenuItem$ you can disable or enable the item or you can select it by putting a mark to it or remove the mark again. Thus the following options are valid:
|
|
|
|
&exverbatim
|
|
Option$ = "Disable" -- grey out the item so it cannot be selected anymore
|
|
Option$ = "Enable" -- enable a formerly disabled item again
|
|
Option$ = "Mark" -- mark this item
|
|
Option$ = "Plain" -- remove a mark again
|
|
&exverbatim
|
|
|
|
Example:
|
|
window open 100,100 to 400,300, "Example", "Example"
|
|
|
|
submenu "Test", "My Favorite OS", "BeOS", "", "Example"
|
|
submenu "Test", "My Favorite OS", "Haiku", "", "Example"
|
|
submenu "Test", "My Favorite OS", "ZETA", "", "Example"
|
|
|
|
submenu set "Test", "My Favorite OS", true, "Example"
|
|
submenu set "Test", "My Favorite OS", "BeOS", "mark", "Example"
|
|
submenu set "Test", "My Favorite OS", "ZETA", "disable", "Example"
|
|
|
|
while(not instr(message$, "Quit"))
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
The submenu is in radio mode, so only one item can be selected. The user will do that for you, however you have to select an item for the first time. The last item cannot be selected because it is disabled.
|
|
|
|
Related: menu, menu set, submenu
|
|
&Views
|
|
&
|
|
boxview
|
|
|
|
Name:
|
|
boxview -- a boxview is view with a labeled border
|
|
|
|
Synopsis:
|
|
BOXVIEW x1,y1 TO x2,y2, ID$, Label$, LineType, View$
|
|
|
|
Description:
|
|
This command sets up a view named ID$ with a border and a label. While the boxview is constructed at the coordinates (x1,y1) to (x2,y2) on the view named View$, the own coordinates of a boxview start at (x1+3,y1+12) to (x2-3,y2-3) so that the border can not be overwritten. This is independent of the line type.
|
|
|
|
If Label$ is not "", it will be displayed on the upper left corner of the boxview. Otherwise no label is shown.
|
|
|
|
There are three possible line types for the border style:
|
|
For LineType = 0 the boxview has no border.
|
|
For LineType = 1 the boxview has a simple line border.
|
|
For LineType = 2 the boxview has a fancy line border.
|
|
|
|
Other than commands like stackview, tabview or splitview, you can simply remove a boxview just as a normal view with the view remove command.
|
|
|
|
Layout:
|
|
The boxview will follow all sides as in standard layout.
|
|
|
|
Design:
|
|
Use boxviews to group similar entries. Do not use too much boxviews in a window, as this looks too cluttered.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
boxview 10,10 to 190,190, "MyBox", "Hello Box", 2, "Example"
|
|
sleep 7
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The example opens a window and sets up a boxview with the label "Hello Box" and a fancy border style (2).
|
|
|
|
Related: view, view remove
|
|
&
|
|
stackview
|
|
|
|
Name:
|
|
stackview -- create views above each other
|
|
|
|
Synopsis:
|
|
STACKVIEW x1,y1 TO x2,y2, ID$, NumberOfViews, View$
|
|
|
|
Description:
|
|
Stackview creates several views on top of each other. All views have the same coordinates (x1,y1)-(x2,y2) on the view named View$. NumberOfViews specifies how many views should be created. Obviously it should be greater or equal to 2 to be useful.
|
|
|
|
All stacked views get a own ID which is ID$ and the number of the view. E.g. if ID$ = "MyStack" and NumberOfViews = 3, then the stacked views have the IDs "MyStack1", MyStack2" and "MyStack3". Use the command stackview set to switch between these views.
|
|
|
|
Layout:
|
|
The stackview and all views it contains will follow all sides as in standard layout.
|
|
|
|
Design:
|
|
You can think of a stackview as a tabview without tabs. Therefore it is up to the programmer to provide a method to switch between the stacked views.
|
|
|
|
Stackviews are useful in typical BeOS style option windows (e.g. in the yab IDE). Have a look at the code below for an example.
|
|
|
|
Example:
|
|
window open 100,100 to 400,300, "Example", "Option Example"
|
|
|
|
listbox 10,10 to 100,190, "List", 1, "Example"
|
|
listbox add "List", "First Option"
|
|
listbox add "List", "Second Option"
|
|
listbox add "List", "Third Option"
|
|
|
|
stackview 110,10 to 290,190, "Stack", 3, "Example"
|
|
draw set "bgcolor", 255,200,200, "Stack1"
|
|
draw text 10,10, "This is view \"Stack1\"", "Stack1"
|
|
draw set "bgcolor", 200,255,200, "Stack2"
|
|
draw text 10,10, "This is view \"Stack2\"", "Stack2"
|
|
draw set "bgcolor", 200,200,255, "Stack3"
|
|
draw text 10,10, "This is view \"Stack3\"", "Stack3"
|
|
|
|
while(not quitting)
|
|
msg$ = message$
|
|
if(instr(msg$, "List")) then
|
|
n = listbox get "List"
|
|
stackview set "Stack", n
|
|
elsif(instr(msg$, "Quit")) then
|
|
quitting = true
|
|
endif
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This window has a listbox on the left-hand side and a stackview with three views on the right. Each view has a own background color and text. When an item is selected in the list, we get its number and then switch the stackview to the corresponding view.
|
|
|
|
Related: stackview get, stackview set, tabview
|
|
&
|
|
stackview get
|
|
|
|
Name:
|
|
stackview get -- get the number of the shown view in a stackview
|
|
|
|
Synopsis:
|
|
ViewNumber = STACKVIEW GET StackView$
|
|
|
|
Description:
|
|
Stackview get will return you the number of the currently shown view. Remember: Numbering starts with 1.
|
|
|
|
Related: stackview, stackview set
|
|
&
|
|
stackview set
|
|
|
|
Name:
|
|
stackview set -- set the shown view in a stackview
|
|
|
|
Synopsis:
|
|
STACKVIEW SET StackView$, ViewNumber
|
|
|
|
Description:
|
|
To switch the views of a stackview, yoy have to use this command. Simply provide it with the ID of the stackview (here: StackView$) and the number of the view you want it to show. Remember: The first view on the stack has the number 1. If you provide an invalid number, nothing will happen.
|
|
|
|
Related: stackview, stackview get
|
|
&Widgets
|
|
&
|
|
button
|
|
|
|
Name:
|
|
button -- create a new button
|
|
|
|
Synopsis:
|
|
BUTTON x1,y1 TO x2,y2, ID$, Label$, View$
|
|
|
|
Description:
|
|
The button command creates a button from the coordinates (x1,y1) to (x2,y2) on the window or view named View$. It has a text label Label$ and the identifier ID$.
|
|
|
|
With the option set command you can modify the button, as setting the background color, the focus, enabling or diabling it or resizing it to its preferred size.
|
|
|
|
Message:
|
|
The button when pressed will send a message string with ID$.
|
|
|
|
Layout:
|
|
In standard layout, the button will follow the lower, right corner of the view or window.
|
|
|
|
Design:
|
|
Always use meaningful labels for buttons. If you care for localization (on ZETA you should!), remember that labels can be much longer in other languages. So either provide enough space or use the option set command to auto-resize the button.
|
|
|
|
Example:
|
|
window open 100,100 to 300,200, "Example", "Example"
|
|
button 20,40 to 180,60, "MyButton", "Hello World", "Example"
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(m$ = "MyButton|") alert "You pressed the button", "Ok", "info"
|
|
if(instr(m$, "_QuitRequested")) quitting = true
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
In this example, a button is set on the window. If the button is pressed, an alert window pops up.
|
|
|
|
Related: button image, option set
|
|
&
|
|
button image
|
|
|
|
Name:
|
|
button image -- create a new button with images
|
|
|
|
Synopsis:
|
|
BUTTON IMAGE x,y, ID$, EnabledPressed$, EnabledNormal$, Disabled$, View$
|
|
|
|
Description:
|
|
This command lets you create a button with images named ID$ on the view View$. The position (x,y) is the upper left corner of the images and the size of the first image (EnabledPressed$) is taken.
|
|
|
|
You have to provide at least two image files:
|
|
EnabledPressed$ -- the image file name of the pressed button
|
|
EnabledNormal$ -- the image file name of the released button
|
|
The images can be of any format that BeOS or ZETA can translate.
|
|
|
|
If you want to disable the button, you should provide the additional image file:
|
|
Disabled$ -- the image file name of the disabled button
|
|
You can put in an empty string "" if you don't need a disabled button.
|
|
|
|
Just be aware that image files with relative path might be not found when you start your program as a script from tracker.
|
|
|
|
Message:
|
|
The button when pressed will send a message string with ID$.
|
|
|
|
Layout:
|
|
In standard layout, the button will follow the lower, right corner of the view or window.
|
|
|
|
Design:
|
|
Be creative but do not use offensive images. For icons, try to use BeOS-like icons always. Ask in the community if you need assistence in creating new icons.
|
|
|
|
Example:
|
|
window open 100,100 to 300,200, "Example", "Example"
|
|
button image 10,10, "MyIconButton", "icon_pressed.png", "icon_released", "icon_disabled", "Example"
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(m$ = "MyIconButton|") alert "You pressed the button", "Ok", "info"
|
|
if(instr(m$, "_QuitRequested")) quitting = true
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The button is only shown correctly, when the images "icon_pressed.png" and "icon_released" exist.
|
|
|
|
Related: button
|
|
&
|
|
calendar
|
|
|
|
Name:
|
|
calendar -- create a new calendar
|
|
|
|
Synopsis:
|
|
CALENDAR x,y, ID$, Format$, SetDate$, View$
|
|
|
|
Description:
|
|
Calendar is a nifty widget that gives you a date textcontrol with a dropdown calendar window. It is created at (x,y) as upper left corner on the view View$. With the default font size, it always has a width of 80 pixels and a height of 20 pixels.
|
|
|
|
You have to provide a date format Format$ which must be either "DDMMYYYY" for day, month, year or "MMDDYYYY" for month, day, year. Futhermore, you have to add a divider to the Format$ which can be either ".", "/" or "-". Thus, the default Format$ looks like this: "DDMMYYYY."
|
|
|
|
The SetDate$ should give the starting date in the format you have chosen. Default is the current day, when SetDate$ = "". Note: this SetDate$ has a different format than the yab command date$. However, it is not too difficult to convert these formats.
|
|
|
|
The calendar can be disabled or enabled with the option set command.
|
|
|
|
Layout:
|
|
In standard layout, the calendar will follow the lower, right corner of the view or window.
|
|
|
|
Example:
|
|
window open 100,100 to 300,200, "Example", "Example"
|
|
calendar 10,10, "MyCalendar", "MMDDYYYY/", "04.06.1975", "Example"
|
|
while(not quitting)
|
|
if(instr(message$, "_QuitRequested")) then
|
|
alert "You selected: "+calendar get$ "MyCalendar", "Duh", "info"
|
|
quitting = true
|
|
endif
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
In this example, a calendar is set on the window with an American date format, month, day, year and the / as separator. When the window is closed, an alert window shows the selected date with calendar get$.
|
|
|
|
Related: calendar get$, calendar set, date$, option set
|
|
&
|
|
calendar get$
|
|
|
|
Name:
|
|
calendar get$ -- returns the selected date of a calendar
|
|
|
|
Synopsis:
|
|
GetDate$ = CALENDAR GET$ Calendar$
|
|
|
|
Description:
|
|
The command will return the currently selected date of the calendar widget named Calendar$. Note: the calendar does not send any messages, so use this command to read out a calendar.
|
|
|
|
Note: This GetDate$ has a different format than the yab command date$. However, it is not too difficult to convert these formats.
|
|
|
|
Related: calendar, calendar set, date$
|
|
&
|
|
calendar set
|
|
|
|
Name:
|
|
calendar set -- sets the date for a calendar
|
|
|
|
Synopsis:
|
|
CALENDAR SET Calendar$, SetDate$
|
|
|
|
Description:
|
|
This lets you set the date of the calendar named Calendar$. Note: SetDate$ has to use the format, that is defined for the calendar.
|
|
|
|
Note: this SetDate$ has a different format than the yab command date$. However, it is not too difficult to convert these formats.
|
|
|
|
Related: calendar, calendar get$, date$
|
|
&
|
|
checkbox
|
|
|
|
Name:
|
|
checkbox -- create a new checkbox
|
|
|
|
Synopsis:
|
|
CHECKBOX x,y, ID$, Label$, IsSelected, View$
|
|
|
|
Description:
|
|
Set up a checkbox named ID$ at the position (x,y). It will display the label Label$ next to the box. If IsSelected is set to true, the checkbox will be selected.
|
|
|
|
You can use option set to disable the checkbox or to change the label.
|
|
|
|
Message:
|
|
The checkbox when selected will send a message string with ID$+":ON", and when deselected with the message string ID$+":OFF".
|
|
|
|
Layout:
|
|
In standard layout, the checkbox will follow the lower, right corner of the view or window.
|
|
|
|
Design:
|
|
Try to align checkboxes below each other. Also put them in groups (e.g. in a boxview) when you have many checkboxes.
|
|
|
|
Example:
|
|
window open 100,100 to 400,200, "Example", "Example"
|
|
checkbox 10,10, "MyCheckBox", "Select this checkbox", false, "Example"
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(m$ = "MyCheckBox:OFF|") alert "The checkbox is deselected", "Ok", "info"
|
|
if(m$ = "MyCheckBox:ON|") alert "The checkbox is selected", "Ok", "info"
|
|
if(instr(m$, "Quit")) quitting = true
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Whenever the checkbox is selected or deselected, an alert window will tell you.
|
|
|
|
Related: checkbox image, checkbox set, option set
|
|
&
|
|
checkbox image
|
|
|
|
Name:
|
|
checkbox image -- create a new checkbox with images
|
|
|
|
Synopsis:
|
|
CHECKBOX IMAGE x,y, ID$, EnabledOn$, EnabledOff$, DisabledOn$, DisabledOff$, IsSelected, View$
|
|
|
|
Description:
|
|
This command lets you create a checkbox with images named ID$ on the view View$. The position (x,y) is the upper left corner of the images and the size of the first image (EnabledOn$) is taken. If IsSelected is set to true, the checkbox will be selected.
|
|
|
|
You have to provide at least two image files:
|
|
EnabledOn$ -- the image file name of the selected checkbox
|
|
EnabledOff$ -- the image file name of the deselected checkbox
|
|
The images can be of any format that BeOS or ZETA can translate.
|
|
|
|
If you want to disable the checkbox, you should provide the additional image files:
|
|
DisabledOn$ -- the image file name of the disabled selected checkbox
|
|
DisabledOff$ -- the image file name of the disabled deselected checkbox
|
|
You can put in an empty string "" if you don't need a disabled checkbox.
|
|
|
|
Just be aware that image files with relative path might be not found when you start your program as a script from tracker.
|
|
|
|
You can use option set to disable the checkbox.
|
|
|
|
Message:
|
|
The checkbox when selected will send a message string with ID$+":ON", and when deselected with the message string ID$+":OFF".
|
|
|
|
Layout:
|
|
In standard layout, the checkbox will follow the lower, right corner of the view or window.
|
|
|
|
Design:
|
|
Be creative but do not use offensive images. For icons, try to use BeOS-like icons always. Ask in the community if you need assistence in creating new icons.
|
|
|
|
Example:
|
|
window open 100,100 to 400,200, "Example", "Example"
|
|
checkbox 10,10, "MyCheckBox", "enabled_icon_on.png", "enabled_icon_off.png",
|
|
"disabled_icon_on.png", "disabled_icon_off.png", false, "Example"
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(m$ = "MyCheckBox:OFF|") alert "The checkbox is deselected", "Ok", "info"
|
|
if(m$ = "MyCheckBox:ON|") alert "The checkbox is selected", "Ok", "info"
|
|
if(instr(m$, "Quit")) quitting = true
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Whenever the checkbox is selected or deselected, an alert window will tell you. The checknox is only shown correctly, when the images exist.
|
|
|
|
Related: checkbox, checkbox set, option set
|
|
&
|
|
checkbox set
|
|
|
|
Name:
|
|
checkbox set -- (de-)select the checkbox
|
|
|
|
Synopsis:
|
|
CHECKBOX SET CheckBox$, IsSelected
|
|
|
|
Description:
|
|
If IsSelected is set to true, the checkbox named CheckBox$ will be selected. If IsSelected is set to false, the checkbox will be deselected.
|
|
|
|
Related: checkbox, checkbox image
|
|
&
|
|
colorcontrol
|
|
|
|
Name:
|
|
colorcontrol -- create a new control for choosing a color
|
|
|
|
Synopsis:
|
|
COLORCONTROL x,y, ID$, View$
|
|
|
|
Description:
|
|
Colorcontrol gives you a basic color selection tool in only one command. The colorcontrol named ID$ has its upper left corner at the position (x,y) of the view View$. It always has a width of 276 pixels and a height of 54 pixels.
|
|
|
|
Note: The colorcontrol will look differently on 8 bit displays than on displays with 16 or more bit. However, this should not concern you, the system will take care of that. On BeOS, the colorcontrol will have an additional deactivated selection for alpha channel selection. This is not functional, so again, do not care.
|
|
|
|
The colorcontrol does not send any message, you have to check with colorcontrol get what the user selected.
|
|
|
|
You can use option set to disable the colorcontrol. Use colorcontrol set, to set a color.
|
|
|
|
Layout:
|
|
In standard layout, the colorcontrol will follow the lower, right corner of the view or window.
|
|
|
|
Design:
|
|
Always give feedback to the user, how the color looks like, he is currently selecting. The example below shows how to do that.
|
|
|
|
Example:
|
|
window open 100,100 to 426,176, "Example", "Example"
|
|
view 10,10 to 40,66, "Color", "Example"
|
|
colorcontrol 50,10, "MyColorControl", "Example"
|
|
|
|
// set color to white
|
|
colorcontrol set "MyColorControl", 255,255,255
|
|
|
|
while(not quitting)
|
|
if(instr(message$, "Quit")) quitting = true
|
|
r = colorcontrol get "MyColorControl", "red"
|
|
g = colorcontrol get "MyColorControl", "green"
|
|
b = colorcontrol get "MyColorControl", "blue"
|
|
|
|
// check if the color was changed
|
|
if(r<>old_r or g<>old_g or b<>old_b) then
|
|
old_r = r: old_g = g: old_b = b
|
|
draw set "bgcolor", r,g,b, "Color"
|
|
endif
|
|
wend
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The example shows a colorcontrol and view. The view always takes the color that is selected by the user. Note: The color is only set, when the selection changed. This avoids flickering on slow machines.
|
|
|
|
Related: colorcontrol get, colorcontrol set, option set
|
|
&
|
|
colorcontrol get
|
|
|
|
Name:
|
|
colorcontrol get -- return a color component of the currently selected color in a colorcontrol
|
|
|
|
Synopsis:
|
|
Value = COLORCONTROL GET ColorControl$, ColorComponent$
|
|
|
|
Description:
|
|
Returns the current selected color component of the colorcontrol ColorControl$. Value is always between 0 and 255, where lower values represent darker colors and higher values represent lighter colors.
|
|
|
|
ColorComponent$ has to be one of the following:
|
|
"Red" -- the value of the red color
|
|
"Green" -- the value of the green color
|
|
"Blue" -- the value of the blue color
|
|
|
|
Related: colorcontrol, colorcontrol set
|
|
&
|
|
colorcontrol set
|
|
|
|
Name:
|
|
colorcontrol set -- set the color in a colorcontrol
|
|
|
|
Synopsis:
|
|
COLORCONTROL SET ColorControl$, r,g,b
|
|
|
|
Description:
|
|
Sets the color in the colorcontrol ColorControl$ to its RGB values r, g and b. Read the part on the draw set command to learn more about RGB color space in yab.
|
|
|
|
Related: colorcontrol, colorcontrol get
|
|
&
|
|
columnbox
|
|
|
|
Name:
|
|
columnbox -- create a list widget with columns
|
|
|
|
Synopsis:
|
|
COLUMNBOX x1,y1 TO x2,y2, ID$, HasHScrollbar, Option$, View$
|
|
|
|
Description:
|
|
The columnbox ist created at (x1,y1) to (x2,y2) on the target view named View$. It gets an own ID i.e. ID$. If it should have a horizontal scrollbar, set HasHScrollbar to true otherwise set it to false. Note: a columnbox always has a vertical scrollbar.
|
|
|
|
There are several options regarding the behaviour of the columns. These options affect all columns:
|
|
"movable" -- the columns can be dragged
|
|
"resizable" -- the columns can be resized
|
|
"popup" -- clicking on the columns with the right mouse button brings up a popup menu with all column names
|
|
"removable" -- the columns can be removed
|
|
|
|
An addtional options is "no-border" which draws the columnbox without a borderline.
|
|
|
|
Several options can be combined, e.g. "movable, resizable, no-border". Note: If "removable" is allowed, you should allow "popup" too, so that removed columns can be brought back again.
|
|
|
|
After setting up a columnbox you have to add columns with the columnbox column command before adding items.
|
|
|
|
Note: A columnbox cannot be sorted.
|
|
|
|
Message:
|
|
The columnbox provides two messages. The first kicks in when a row is selected by clicking once on it or by the up and down keys. This then has the format ID$+":_Select:"+SelectedRow$ where SelectedRow$ contains the number of the row selected. The second message is send, when a row is invoked, i.e. by double-clicking at a row or pressing the Enter key. It has the format ID$+":_Invoke:"+SelectedRow$.
|
|
|
|
Layout:
|
|
The columbox will follow all sides as in standard layout.
|
|
|
|
Design:
|
|
To use a columnbox is almost always a good idea. It helps to present a lot of data in an organized way. Additionally it allows bitmaps and icons as list entries and it is the most customizable list widget in yab.
|
|
|
|
Example:
|
|
window open 100,100 to 400,500, "Example", "Example"
|
|
|
|
columnbox 10,10 to 290,390, "MyColumnbox", true, "movable, resizable, popup, removable", "Example"
|
|
|
|
columnbox column "MyColumnbox", " ", 1, 20, 20, 20, "align-center"
|
|
columnbox column "MyColumnbox", "Name", 2, 140, 60, 80, "align-right"
|
|
columnbox column "MyColumnbox", "Address", 3, 250, 60, 180, "align-left"
|
|
columnbox column "MyColumnbox", "Age", 4, 250, 60, 50, "align-center"
|
|
|
|
columnbox add "MyColumnbox", 1, 1, 18, "__Mime__=application/x-person"
|
|
columnbox add "MyColumnbox", 2, 1, 18, "John"
|
|
columnbox add "MyColumnbox", 3, 1, 18, "Cape Town"
|
|
columnbox add "MyColumnbox", 4, 1, 18, "30"
|
|
|
|
columnbox add "MyColumnbox", 1, 2, 18, "__Mime__=application/x-person"
|
|
columnbox add "MyColumnbox", 2, 2, 18, "Mary"
|
|
columnbox add "MyColumnbox", 3, 2, 18, "Omaruru"
|
|
columnbox add "MyColumnbox", 4, 2, 18, "27"
|
|
|
|
columnbox color "MyColumnbox", "text", 0,0,200
|
|
columnbox color "MyColumnbox", "selection", 200,200,255
|
|
columnbox color "MyColumnbox", "row-divider", 255,255,255
|
|
|
|
columnbox select "MyColumnbox", 2
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "_Select")) then
|
|
currentRow = columnbox get "MyColumnbox"
|
|
print columnbox get$ "MyColumnbox", 2, currentRow
|
|
endif
|
|
if(instr(m$, "_Invoke")) then
|
|
currentRow = columnbox get "MyColumnbox"
|
|
currentItem$ = columnbox get$ "MyColumnbox", 2, currentRow
|
|
alert "You selected "+currentItem$, "Ok", "info"
|
|
endif
|
|
if(instr(m$, "Quit")) quitting = true
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
In this example, first a columnbox is created. It has a horizontal scrollbar. Due to the options, the columns can be moved by clicking and dragging on the column title, they can be removed by dragging a title out of the columnbox, the columns can be resized by dragging the mouse at the border of the column titles and by right clicking on the column title a popup window appears.
|
|
|
|
Next the column are defined with columnbox column. All four columns have a title and a column number. Ideally this number starts at one and it increases with every column. Furthermore we specify the width of the column and its maximum and minimum width. This is important when the columnbox allows the "resizable" option.
|
|
|
|
Several items are inserted into the columnbox with the columnbox add command. Here the column number has to be given and the row number too. The row height is set by the first columnbox add command for a row and here it is set to 18 because we use icons with a 16 pixel height. We obtain the icon from the mimetype of the type "application/x-person" which is given by the system.
|
|
|
|
Several colors are set to personalize our columnbox a bit and the second row is selected with the columnbox select command.
|
|
|
|
In the message loop we check for the "_Select" and the "_Invoke" messages of the columnbox. When a row is selected, e.g. by clicking on it once, we first obtain the row where the click happened with columnbox get (this can also be obtain from the message itself using the right$ and val commands). Then the item string itself is retrieved with the columnbox get$ command.
|
|
|
|
Related: columnbox add, columnbox clear, columnbox column, columnbox count, columnbox get, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox add
|
|
|
|
Name:
|
|
columnbox add -- add an item to a columnbox
|
|
|
|
Synopsis:
|
|
COLUMNBOX ADD ColumnBox$, Column, Row, Height, Item$
|
|
|
|
Description:
|
|
To add an item named Item$ to a columnbox named ColumnBox$, you have to specify the column and the row where the item should be located in the columnbox table. An existing item will be overwritten. If Row is larger than the number of rows in the columnbox, a new row is created. Furthermore, you have to specify the height of the row in pixels, a normal value should be Height = 14 or Height = 16 for text items.
|
|
|
|
To have images or icons as items, you have to specify that with special identifiers in Item$:
|
|
If Item$ = "__Icon__="+FileName$ then the image file FileName$ will be shown,
|
|
if Item$ = "__Path__="+FileName$ then the large Trackericon of the file FileName$ will be shown
|
|
if Item$ = "__Mime__="+Signature$ then the small icon of the mime type Signature$ will be shown.
|
|
|
|
Note: These identifiers are case sensitive!
|
|
|
|
Have a look at the columnbox command for an example.
|
|
|
|
Related: columnbox, columnbox clear, columnbox color, columnbox column, columnbox count, columnbox get, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox clear
|
|
|
|
Name:
|
|
columnbox clear -- deletes everything in a columnbox
|
|
|
|
Synopsis:
|
|
COLUMNBOX CLEAR ColumnBox$
|
|
|
|
Description:
|
|
Use columnbox clear to remove all rows and items in the columnbox named ColumnBox$.
|
|
|
|
Related: columnbox, columnbox add, columnbox color, columnbox column, columnbox count, columnbox get, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox color
|
|
|
|
Name:
|
|
columnbox color -- change the colors of a columnbox
|
|
|
|
Synopsis:
|
|
COLUMNBOX COLOR ColumnBox$, Option$, r,g,b
|
|
|
|
Description:
|
|
The colors in a columnbox can be changed easily. This distinguishes the columnbox from other list widgets like listbox, dropbox or treebox. Given an option string Option$ the colors can be set to the RGB value (r,g,b). Read the part on the draw set command to learn more about RGB color space in yab.
|
|
|
|
The following values for Option$ are valid:
|
|
"selection-text" -- set the color of the text in the selected row
|
|
"non-focus-selection" -- set the color of the selection when the columnbox is not focussed
|
|
"selection" -- set the color for the selected row
|
|
"text" -- set the general text color
|
|
"row-divider" -- set the color of the line between the rows
|
|
"background" -- set the background color
|
|
|
|
Have a look at the columnbox command for an example.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox column, columnbox count, columnbox get, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox column
|
|
|
|
Name:
|
|
columnbox column -- add a new column to a columnbox
|
|
|
|
Synopsis:
|
|
COLUMNBOX COLUMN ColumnBox$, Name$, ColumnNumber, MaxWidth, MinWidth, Width, Option$
|
|
|
|
Description:
|
|
This command takes quite a number of parameters. Here ColumnBox$ is the columnbox where the column should be added. Name$ is the string that shows up in the title of the column.
|
|
|
|
ColumnNumber gives the position relative to the other columns. Ideally ColumnNumber starts at 1 for the first column and with every new column it is incremented by 1. The column gets the width Width (thus the next column will start at Position+Width). MaxWidth and MinWidth declare the boundaries for the column when resizing was specified in the construction of the columnbox.
|
|
|
|
Finally the alignment of all items in the column has to be defined in Option$. Possible values are "align-left" for left alignment, "align-center" for center alignment and "align-right" for right alignment.
|
|
|
|
Have a look at the columnbox command for an example.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox color, columnbox count, columnbox get, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox count
|
|
|
|
Name:
|
|
columnbox count -- returns the number of rows in a columnbox
|
|
|
|
Synopsis:
|
|
NumberOfRows = COLUMNBOX COUNT ColumnBox$
|
|
|
|
Description:
|
|
For a existing columnbox named ColumnBox$, this command simply returns the number of rows it contains and stores it in NumberOfRows.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox color, columnbox column, columnbox get, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox get
|
|
|
|
Name:
|
|
columnbox get -- returns the number of the currently selected row in a columnbox
|
|
|
|
Synopsis:
|
|
ItemNumber = COLUMNBOX GET ColumnBox$
|
|
|
|
Description:
|
|
To obtain the row that is currently selected in the columnbox named ColumnBox$, simply use this command. If no row is selected, ItemNumber will be set to 0.
|
|
|
|
Have a look at the columnbox command for an example.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox color, columnbox column, columnbox count, columnbox get$, columnbox remove, columnbox select
|
|
&
|
|
columnbox get$
|
|
|
|
Name:
|
|
columnbox get$ -- get a specific item in a columnbox
|
|
|
|
Synopsis:
|
|
Item$ = COLUMNBOX GET$ ColumnBox$, Column, Row
|
|
|
|
Description:
|
|
In the given columnbox named ColumnBox$, the item text at the position (Column, Row) will be stored in Item$. For icons and images, this will return the identifier and the file path.
|
|
|
|
Have a look at the columnbox command for an example.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox color, columnbox column, columnbox count, columnbox get, columnbox remove, columnbox select
|
|
&
|
|
columnbox remove
|
|
|
|
Name:
|
|
columnbox remove -- delete a line in a columnbox
|
|
|
|
Synopsis:
|
|
COLUMNBOX REMOVE ColumnBox$, Row
|
|
|
|
Description:
|
|
In the given columnbox named ColumnBox$, the specified row is deleted.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox color, columnbox column, columnbox count, columnbox get, columnbox get$, columnbox select
|
|
&
|
|
columnbox select
|
|
|
|
Name:
|
|
columnbox select -- select a row in a columnbox
|
|
|
|
Synopsis:
|
|
COLUMNBOX SELECT ColumnBox$, Row
|
|
|
|
Description:
|
|
In the given columnbox named ColumnBox$, the specified row is selected. If Row is set to 0, any former selection is revoked.
|
|
|
|
Have a look at the columnbox command for an example.
|
|
|
|
Related: columnbox, columnbox add, columnbox clear, columnbox color, columnbox column, columnbox count, columnbox get, columnbox get$, columnbox remove
|
|
&
|
|
listbox
|
|
|
|
Name:
|
|
listbox -- create a list widget
|
|
|
|
Synopsis:
|
|
LISTBOX x1,y1 TO x2,y2, ID$, ScrollbarType, View$
|
|
|
|
Description:
|
|
The listbox provides a list widget that can be filled with text items. It is set up at the position (x1,y1) to (x2,y2) on the view named View$. It gets an own identifier ID$. Additionally you have to specify whether the listbox should get scrollbars. This is given by ScrollbarType as follows:
|
|
|
|
ScrollbarType = 0 -- no scrollbar
|
|
ScrollbarType = 1 -- the listbox has a vertical scrollbar
|
|
ScrollbarType = 2 -- the listbox has a horizontal scrollbar
|
|
ScrollbarType = 3 -- the listbox has a vertical and a horizontal scrollbar
|
|
|
|
Message:
|
|
The listbox provides two messages. The first kicks in when an item is selected by clicking once on it or by the up and down keys. This then has the format ID$+":_Select:"+SelectedItem$ where SelectedItem$ contains the number of the item selected. The second message is send, when a item is invoked, i.e. by double-clicking at a item or pressing the Enter key. It has the format ID$+":_Invoke:"+SelectedItem$.
|
|
|
|
Layout:
|
|
The listbox will follow all sides as in standard layout.
|
|
|
|
Design:
|
|
The listbox is an easy method to present a lot of data well-structured in a list. Use it instead of a dropbox when you have enough space or the list of data gets too long. For having icons or images in a list, use the columnbox instead.
|
|
|
|
Example:
|
|
window open 100,100 to 400,400, "Example", "Example"
|
|
|
|
listbox 10,10 to 290,260, "MyList", 1, "Example"
|
|
button 10,270 to 290,290, "MyButton", "Sort List", "Example"
|
|
|
|
listbox add "MyList", "Apple"
|
|
listbox add "MyList", "8088"
|
|
listbox add "MyList", "80286"
|
|
listbox add "MyList", "ZX81"
|
|
listbox add "MyList", 1, "BeOS"
|
|
|
|
listbox select "MyList", 2
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "MyButton")) then
|
|
listbox sort "MyList"
|
|
endif
|
|
if(instr(m$, "_Select")) then
|
|
currentItem = listbox get "MyList"
|
|
print listbox get$ "MyList", currentItem
|
|
endif
|
|
if(instr(m$, "_Invoke")) then
|
|
currentItem = listbox get "MyList"
|
|
item$ = listbox get$ "MyList", currentItem
|
|
alert "You selected "+item$, "Ok", "info"
|
|
endif
|
|
if(instr(m$, "Quit")) quitting = true
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This program opens a window with a listbox named "MyList" and a button named "MyButton". Several items are added, note the order of the items. The last item is put into the first position of the list. Then the second item is selected, this will generate a message which will be processed immendiatly. You can see the name of the selected item on the console output. When the sort button is pressed, the list is sorted. When double clicking on an item, an alert window pops up showing the selected item.
|
|
|
|
Related: listbox add, listbox clear, listbox count, listbox get, listbox get$, listbox remove, listbox select, listbox sort
|
|
&
|
|
listbox add
|
|
|
|
Name:
|
|
listbox add -- add an item to a listbox
|
|
|
|
Synopsis:
|
|
LISTBOX ADD ListBox$, Item$
|
|
LISTBOX ADD ListBox$, Position, Item$
|
|
|
|
Description:
|
|
This command adds a string here named Item$ to the listbox with the ID ListBox$. If Position is given too, the item will be inserted at that position.
|
|
|
|
Have a look at the listbox command for an example.
|
|
|
|
Related: listbox, listbox clear, listbox count, listbox get, listbox get$, listbox remove, listbox select, listbox sort
|
|
&
|
|
listbox clear
|
|
|
|
Name:
|
|
listbox clear -- remove all items of a listbox
|
|
|
|
Synopsis:
|
|
LISTBOX CLEAR ListBox$
|
|
|
|
Description:
|
|
Listbox clear deletes and removes all items in a listbox.
|
|
|
|
Related: listbox, listbox add, listbox count, listbox get, listbox get$, listbox remove, listbox select, listbox sort
|
|
&
|
|
listbox count
|
|
|
|
Name:
|
|
listbox count -- returns the number of items in a listbox
|
|
|
|
Synopsis:
|
|
NumberOfItems = LISTBOX COUNT ListBox$
|
|
|
|
Description:
|
|
For an existing listbox named ListBox$, this command simply returns the number of items it contains and stores it in NumberOfItems.
|
|
|
|
Related: listbox, listbox add, listbox clear, listbox get, listbox get$, listbox remove, listbox select, listbox sort
|
|
&
|
|
listbox get
|
|
|
|
Name:
|
|
listbox get -- returns the number of the currently selected item in a listbox
|
|
|
|
Synopsis:
|
|
ItemNumber = LISTBOX GET ListBox$
|
|
|
|
Description:
|
|
To obtain the item that is currently selected in the listbox named ListBox$, simply use this command. If no item is selected, ItemNumber will be set to 0.
|
|
|
|
Have a look at the listbox command for an example.
|
|
|
|
Related: listbox, listbox add, listbox clear, listbox count, listbox get$, listbox remove, listbox select, listbox sort
|
|
&
|
|
listbox get$
|
|
|
|
Name:
|
|
listbox get$ -- get a specific item string in a listbox
|
|
|
|
Synopsis:
|
|
Item$ = LISTBOX GET$ ListBox$, Position
|
|
|
|
Description:
|
|
In the given listbox named ListBox$, the item text at the position Position will be stored in Item$.
|
|
|
|
Have a look at the listbox command for an example.
|
|
|
|
Related: listbox, listbox add, listbox clear, listbox count, listbox get, listbox remove, listbox select, listbox sort
|
|
&
|
|
listbox remove
|
|
|
|
Name:
|
|
listbox remove -- delete a line in a listbox
|
|
|
|
Synopsis:
|
|
LISTBOX REMOVE ListBox$, Position
|
|
|
|
Description:
|
|
In the given listbox named ListBox$, the specified item at the position Position is deleted.
|
|
|
|
Related: listbox, listbox add, listbox clear, listbox count, listbox get, listbox get$, listbox select, listbox sort
|
|
&
|
|
listbox select
|
|
|
|
Name:
|
|
listbox select -- select an item in a listbox
|
|
|
|
Synopsis:
|
|
LISTBOX SELECT ListBox$, Position
|
|
|
|
Description:
|
|
In the given listbox named ListBox$, the specified item at the position Position is selected. If Position is set to 0, any former selection is revoked.
|
|
|
|
Have a look at the listbox command for an example.
|
|
|
|
Message:
|
|
Using the listbox select command will generate a selection message. This then has the format ID$+":_Select:"+SelectedItem$ where SelectedItem$ contains the number of the item selected.
|
|
|
|
Related: listbox, listbox add, listbox clear, listbox count, listbox get, listbox get$, listbox remove, listbox sort
|
|
&
|
|
listbox sort
|
|
|
|
Name:
|
|
listbox sort -- sort all items in a listbox
|
|
|
|
Synopsis:
|
|
LISTBOX SORT ListBox$
|
|
|
|
Description:
|
|
This command sorts the given listbox named ListBox$ alphabetically. Items starting with a number will be set before items starting with a letter. However, please note that items containing numbers will NOT be sorted as numbers. E.g. The items "1", "2", "10" will be sorted according to the ASCII codes and the length of the strings, thus they are sorted to: "1", "10", "2"
|
|
|
|
Note: After sorting, any former selection is removed.
|
|
|
|
Have a look at the listbox command for an example.
|
|
|
|
Related: listbox, listbox add, listbox clear, listbox count, listbox get, listbox get$, listbox remove, listbox select
|
|
&
|
|
radiobutton
|
|
|
|
Name:
|
|
radiobutton -- create a new radiobutton
|
|
|
|
Synopsis:
|
|
RADIOBUTTON x,y, ID$, Label$, IsActivated, View$
|
|
|
|
Description:
|
|
Set up a radiobutton named ID$ at the position (x,y). It will display the label Label$ next to the button. If IsActivated is set to true, the radiobutton will be selected. All radiobuttons on one view will act as a group. Thus on a view only one radiobutton will be active.
|
|
|
|
Note: On setup it is up to you to preselect a radiobutton. You can even make more than one radiobutton active but this is hardly useful. When the user selects a radiobutton, all others will be deselected automatically.
|
|
|
|
You can use option set to disable the radiobutton or to change the label.
|
|
|
|
Message:
|
|
The radiobutton when selected will send a message string with its ID$.
|
|
|
|
Layout:
|
|
In standard layout, the radiobutton will follow the lower, right corner of the view or window.
|
|
|
|
Design:
|
|
Try to align radiobuttons below each other.
|
|
|
|
Example:
|
|
window open 100,100 to 200,200, "Example", "Music"
|
|
radiobutton 10,10, "Radio1", "Classic", true, "Example"
|
|
radiobutton 10,30, "Radio2", "Jazz", false, "Example"
|
|
radiobutton 10,50, "Radio3", "Pop", false, "Example"
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "_QuitRequested")) then
|
|
quitting = true
|
|
elsif(instr(m$, "Radio")) then
|
|
n$ = mid$(m$,instr(m$, "Radio")+5,1)
|
|
alert "You selected the "+n$+". radiobutton", "Ok", "info"
|
|
endif
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Here we have a window with three radiobuttons. Because they are all on one view (the window view) they act as a group. When selected, the number of the radiobutton ID will be extracted with mid$ and stored in n$. It is then shown in an alert window.
|
|
|
|
Related: radiobutton set, option set
|
|
&
|
|
radiobutton set
|
|
|
|
Name:
|
|
radiobutton set -- (de-)activate the radiobutton
|
|
|
|
Synopsis:
|
|
RADIOBUTTON SET RadioButton$, IsActivated
|
|
|
|
Description:
|
|
If IsActivated is set to true, the radiobutton named RadioButton$ will be selected. If IsActivated is set to false, the radiobutton will be deselected. Note: This allows you to activate more than one radiobutton in a group which is not recommended.
|
|
|
|
Related: radiobutton
|
|
&
|
|
statusbar
|
|
|
|
Name:
|
|
statusbar -- create a progress or status bar
|
|
|
|
Synopsis:
|
|
STATUSBAR x1, y1 TO x2, y2, ID$, LeftLabel$, RightLabel$, View$
|
|
|
|
Description:
|
|
Use the statusbar to visualize the progress of a long computation process, e.g. installation or search. The statusbar is simply set up with the identifier ID$ at (x1,y1) to (x2,y2) on the view named View$. It takes two labels, LeftLabel$ is shown on the left side above of the statusbar and RightLabel$ is shown on the right side above of the statusbar.
|
|
|
|
Layout:
|
|
The statusbar will follow the lower right corner of a window in standard layout.
|
|
|
|
Design:
|
|
The statusbar should give the user an idea how long a specific process takes. This of course is only useful for processes that take some time. Also having a statusbar that stays for one minute at 5% and then immediatly jumps to 100% should be avoided although this sometimes is not in control of the programmer.
|
|
|
|
Example:
|
|
window open 100,100 to 300,150, "Example", "Example"
|
|
statusbar 10,10 to 190,40, "MyStatus", "Start", "End", "Example"
|
|
|
|
while(not instr(message$, "Quit") and i<100)
|
|
i = i + 2
|
|
statusbar set "MyStatus", "Start", "End", i
|
|
sleep 0.05
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The statusbar is put on top of the example window with the two labels "Start" and "End". Using the statusbar set command, the statusbar is updated regularly to the new calculated value i which is between 0 and 100.
|
|
|
|
Related: statusbar set
|
|
&
|
|
statusbar set
|
|
|
|
Name:
|
|
statusbar -- set the value for a status bar
|
|
|
|
Synopsis:
|
|
STATUSBAR SET Statusbar$, LeftLabel$, RightLabel$, State
|
|
|
|
Description:
|
|
Use statusbar set to actually set the bar to a specific value. This value named State here is a number between 0 and 100. Thus, 0 is the empty statusbar while 100 is the full statusbar. During your update, you can change the labels at the left and right (LeftLabel$ and RightLabel$).
|
|
|
|
Have a look at the statusbar command for an example.
|
|
|
|
Related: statusbar
|
|
&
|
|
text
|
|
|
|
Name:
|
|
text -- create a text label
|
|
|
|
Synopsis:
|
|
TEXT x,y, ID$, Text$, View$
|
|
TEXT x1,y1 TO x2,y2, ID$, Text$, View$
|
|
|
|
Description:
|
|
The text command sets up a text label Text$ at the position (x,y) or (x1,y1) of the view named View$. Providing second coordinates (x2,y2) is useful for the alignment of the text, see text set for details. The text label has an ID$ which is needed for text set or for changing the text itself with option set.
|
|
|
|
So how does this compare to the draw text command?
|
|
A text cannot be flushed and it will never flicker.
|
|
A text can be aligned.
|
|
The label of a text can change.
|
|
On a canvas only draw text can be used.
|
|
The font and color can only be changed for draw text.
|
|
|
|
Note: (x,y) is the upper left corner, this is different to draw text, where y is the baseline of the text.
|
|
|
|
Design:
|
|
Text should be used for labels on a view. Use the alignment to make clean interfaces.
|
|
|
|
Example:
|
|
window open 100,100 to 200,150, "Example", "Example"
|
|
text 10,10, "Text", "Hello World", "Example"
|
|
|
|
while(not instr(message$, "Quit"))
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
A simple yab program, just a window and a text label.
|
|
|
|
Related: draw text, option set, text set
|
|
&
|
|
text set
|
|
|
|
Name:
|
|
text set -- set the alignment of a text widget
|
|
|
|
Synopsis:
|
|
TEXT SET Text$, Alignment$
|
|
|
|
Description:
|
|
For a text label named Text$ you can change the alignment so that it is aligned to the left, center or right. This only works when you have used the text command with the (x2,y2) parameters because the alignment refers to x1 for left alignment und x2 for right alignment.
|
|
|
|
The alignment is given as:
|
|
Alignment$ = "Align-Left" -- align to the left
|
|
Alignment$ = "Align-Center" -- align to the center
|
|
Alignment$ = "Align-Right" -- align to the right
|
|
|
|
Example:
|
|
window open 100,100 to 300,200, "Example", "Example"
|
|
text 10,40 to 190,60, "Text", "Hello", "Example"
|
|
align = 1
|
|
|
|
while(not instr(message$, "Quit"))
|
|
switch align
|
|
case 1:
|
|
text set "Text", "Align-Left"
|
|
break
|
|
case 2:
|
|
text set "Text", "Align-Center"
|
|
break
|
|
case 3:
|
|
text set "Text", "Align-Right"
|
|
break
|
|
end switch
|
|
if align = 3 dir = -1
|
|
if align = 1 dir = 1
|
|
align = align + dir
|
|
sleep 0.5
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
This fun program changes the alignment of the text every half second.
|
|
|
|
Related: text
|
|
&
|
|
textedit
|
|
|
|
Name:
|
|
textedit -- create a multiline text editor
|
|
|
|
Synopsis:
|
|
TEXTEDIT x1,y1 TO x2,y2, ID$, ScrollbarType, View$
|
|
|
|
Description:
|
|
|
|
Layout:
|
|
|
|
Design:
|
|
|
|
Example:
|
|
Explanation:
|
|
|
|
Related: textcontrol, textedit add, textedit clear, textedit color, textedit get, textedit get$, textedit set
|
|
&
|
|
textedit add
|
|
|
|
Name:
|
|
textedit add -- add text to a textedit
|
|
|
|
Synopsis:
|
|
TEXTEDIT ADD TextEdit$, Text$
|
|
|
|
Description:
|
|
|
|
Related: textedit, textedit clear, textedit color, textedit get, textedit get$, textedit set
|
|
&
|
|
textedit clear
|
|
|
|
Name:
|
|
textedit clear -- delete all text of a textedit
|
|
|
|
Synopsis:
|
|
TEXTEDIT CLEAR TextEdit$
|
|
|
|
Description:
|
|
This command removes all text within a textedit named TextEdit$. This also works when the textedit is not editable by the user.
|
|
|
|
Related: textedit, textedit add, textedit color, textedit get, textedit get$, textedit set
|
|
&
|
|
textedit color
|
|
|
|
Name:
|
|
textedit color -- set the colors of a textedit or provide syntax highlighting
|
|
|
|
Synopsis:
|
|
TEXTEDIT COLOR TextEdit$, Option$, r,g,b
|
|
TEXTEDIT COLOR TextEdit$, Option$, Command$
|
|
|
|
Description:
|
|
|
|
Related: textedit, textedit add, textedit clear, textedit get, textedit get$, textedit set
|
|
&
|
|
textedit get
|
|
|
|
Name:
|
|
textedit get -- retrieve various information from a textedit
|
|
|
|
Synopsis:
|
|
LineNumber = TEXTEDIT GET TextEdit$, Option$
|
|
LineNumber = TEXTEDIT GET TextEdit$, Option$, Search$
|
|
Result = TEXTEDIT GET TextEdit$, Option$, LineNumber
|
|
|
|
Description:
|
|
|
|
Related: textedit, textedit add, textedit clear, textedit color, textedit get$, textedit set
|
|
&
|
|
textedit get$
|
|
|
|
Name:
|
|
textedit get$ -- retrieve text from a textedit
|
|
|
|
Synopsis:
|
|
EnteredText$ = TEXTEDIT GET$ TextEdit$
|
|
TextLine$ = TEXTEDIT GET$ TextEdit$, LineNumber
|
|
|
|
Description:
|
|
|
|
Related: textedit, textedit add, textedit clear, textedit color, textedit get, textedit set
|
|
&
|
|
textedit set
|
|
|
|
Name:
|
|
textedit set -- set various options for a textedit
|
|
|
|
Synopsis:
|
|
TEXTEDIT SET TextEdit$, Option$
|
|
TEXTEDIT SET TextEdit$, Option$, Value
|
|
TEXTEDIT SET TextEdit$, Option$, Value$
|
|
|
|
Description:
|
|
Textedit set allows you to apply standard editing operations, cut, copy, paste, clear, select-all, undo. It allows you set various options for the textedit, e.g. wordwrap, editable, autoindent. And it handles the autocompletion. Let us have a look in detail:
|
|
|
|
Given only two parameters, the following options are valid for the textedit named TextEdit$:
|
|
Option$ = "cut" -- cut out the selected text and put it into the clipboard
|
|
Option$ = "clear" -- cut out the selected text but do not put it into the clipboard
|
|
Option$ = "copy" -- copy the selected text to the clipboard
|
|
Option$ = "paste" -- paste the content of the clipboard at the cursors position
|
|
Option$ = "select-all" -- select the whole text
|
|
Option$ = "undo" -- undo the last operation, note: undo remembers only one operation
|
|
|
|
Given three parameters, the following options are valid for the textedit named TextEdit$ when the third parameter Value is either true or false:
|
|
Option$ = "autoindent" -- turn auto indent on or off, default is off (false)
|
|
Option$ = "changed" -- mark the textedit as changed or unchanged, default is false
|
|
Option$ = "color-case-sensitive" -- should the syntax highlighting be case-sensitive? default is false
|
|
Option$ = "editable" -- allow the user to edit the textedit, default is true
|
|
Option$ = "has-autocompletion" -- turn auto-completion on or off, default is on (true)
|
|
Option$ = "wordwrap" -- turn on/off word wrap at the end of a line, default is on (true)
|
|
|
|
Some remarks:
|
|
Making a textedit not editable is useful when you want to show long text (or scrollable text).
|
|
The textedit will notice when text was changed since the last time the option "changed" was set to false. So when you saved the content of the textedit, remember to set back the "changed" option to false again. Then you know when the text should be saved again.
|
|
|
|
Given three parameters, the following options are valid for the textedit named TextEdit$ when the third parameter Value is a number:
|
|
Option$ = "autocomplete-start" -- set the number of characters when auto-completion should kick in (default is 4)
|
|
Option$ = "gotoline" -- put the cursor to the line with number Value
|
|
Option$ = "select" -- select the line with number Value
|
|
Option$ = "tabwidth" -- set the tab width to Value (in pixel!), default is 28
|
|
Option$ = "textwidth" -- set the maximum width of the text in pixel
|
|
|
|
Given three parameters, the following options are valid for the textedit named TextEdit$ when the third parameter Value$ is a string:
|
|
Option$ = "font" -- set the font to Value$ (see draw set for details), default is "system-plain"
|
|
Option$ = "autocomplete" -- add the word Value$ to the auto-completion list
|
|
|
|
Related: textedit, textedit add, textedit clear, textedit color, textedit get, textedit get$
|
|
&
|
|
tooltip
|
|
|
|
Name:
|
|
tooltip -- add a tooltip to a view or widget
|
|
|
|
Synopsis:
|
|
TOOLTIP View$, Text$
|
|
|
|
Description:
|
|
A tooltip is a small popup that appears when the mouse moves over a widget to give some more information.
|
|
|
|
To have a tooltip to any sort of view or widget named View$, simply add the tooltip string Text$. Text$ should be only one line without linebreaks. If Text$ is set to the empty string "", the tooltip is removed again from View$.
|
|
|
|
Note: The tooltips look and behave slightly different on BeOS and ZETA.
|
|
|
|
Design:
|
|
Tooltips can be of great help for the user to understand icons or buttons and the like. However, it does not make sence to add a tooltip "New" to a button that already has the label "New". Rather be more descriptive and provide additional information, e.g. "Open a new image file". For tooltips only the first word should be written with a capital letter.
|
|
|
|
And remember, too many tooltips can be annoying too.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
|
|
button 10,10 to 190,30, "Button", "We all...", "Example"
|
|
listbox 10,40 to 95,190, "List", 1, "Example"
|
|
listbox add "List", "...have own..."
|
|
slider 120,40 to 190,190, "Slider", "...tooltips.", 1,10, "triangle, vertical", "Example"
|
|
|
|
tooltip "Example", "A tooltip for the whole window"
|
|
tooltip "Button", "A tooltip for the button"
|
|
tooltip "List", "A tooltip for the listbox"
|
|
tooltip "Slider", "A tooltip for the slider"
|
|
|
|
while(not instr(message$, "Quit"))
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The example shows how easily a tooltip can be applied to any kind of widget. Here, to the button, the listbox, the slider and the window view itself too.
|
|
|
|
Related: tooltip color
|
|
&
|
|
tooltip color
|
|
|
|
Name:
|
|
tooltip color -- set the color for all tooltips
|
|
|
|
Synopsis:
|
|
TOOLTIP COLOR Option$, r,g,b
|
|
|
|
Description:
|
|
To change the textcolor or the background color of all your tooltips, use this command. Given the option "bgcolor" or "textcolor" either the background color or the text color of the tooltips will be changed to the RGB color (r,g,b). Read the part on the draw set command to learn more about RGB color space in yab.
|
|
|
|
Note: This command only works with the BeOS yab. The colors for the ZETA tooltips are set generally in the ZETA preferences and thus cannot be changed for a single app. So on ZETA with the ZETA yab interpreter this command simply does nothing.
|
|
|
|
Example:
|
|
window open 100,100 to 300,140, "Example", "Example"
|
|
|
|
button 10,10 to 190,30, "Button", "I have a tooltip", "Example"
|
|
|
|
tooltip color "bgcolor", 0,0,0
|
|
tooltip color "textcolor", 255,255,255
|
|
|
|
tooltip "Button", "A black and white tooltip for the button on BeOS"
|
|
|
|
while(not instr(message$, "Quit"))
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
Here, the color of the tooltips are changed from the default yellow background and black text color to a black background (RGB color values: 0,0,0) and from the default black text color to a white text (RGB color values: 255,255,255).
|
|
|
|
Related: tooltip
|
|
&
|
|
&Localization
|
|
&
|
|
localize
|
|
|
|
Name:
|
|
localize -- enable the automatic localization of ZETA
|
|
|
|
Synopsis:
|
|
LOCALIZE
|
|
LOCALIZE Filename$
|
|
|
|
Description:
|
|
Not everyone speaks English thus having multiple language support improves the usability of your program. yab provides a very simple language interface with the localize command. Use it once to turn automatic localization on. Now all strings in GUI widgets will be translated automatically if there is a dictionary entry for them. All you have to do, is to make a dictionary for your program.
|
|
|
|
Dictionaries for stand-alone programs are normally put into the subdirectory Language/Dictionaries of your program. But if a filename Filename$ is given, the (absolute) path of this filename is used as dictionary directory. Note: As long as the yab program is not compiled with the build factory, you should specify the path.
|
|
|
|
In the dictionary directory there should be files named like the programs name or like file name in Filename$. The files have a language code as ending. The language code consists of a two letter code for the language and a capitalized two letter code of the country. For a sample program named foobar.yab, some example dictionaries: foobar.deDE (language German (de) and country Germany (DE)), foorbar.enUS (language English (en) and country United States (US)), foobar.nlBE (language Dutch (nl) and country Belgium (BE)).
|
|
|
|
The dictionary contains the English term in paranthesis ("") some spaces as separator and the translated text in the target language in paranthesis too. Example:
|
|
&exverbatim
|
|
# A comment starts with a #
|
|
# English German
|
|
"File" "Datei"
|
|
"Quit" "Beenden"
|
|
"This is a sentence." "Dies ist ein Satz."
|
|
&exverbatim
|
|
|
|
This all looks complicated, but the reader is encouraged to have a look at the localization of the yab IDE and other tools to understand localization completly.
|
|
|
|
Note: Menus and dropboxes return messages that contain a string that might be translated. Use the translate$() function to handle these.
|
|
|
|
Note: The strings are case sensitive!
|
|
|
|
Note: Currently localization is only supported on ZETA. However, supporting the localization of your program is a good idea for BeOS users too because localization support might be added soon to BeOS yab.
|
|
|
|
Design:
|
|
It is good design to support localization.
|
|
|
|
Example:
|
|
// this examples works with the example localization file above
|
|
// name it "foobar.deDE" in your home directory
|
|
localize "/boot/home/foobar"
|
|
window open 100,100 to 200,200, "Win", "Foobar"
|
|
menu "File", "Quit", "Q", "Win"
|
|
draw text 10,50, "This is a sentence.", "Win"
|
|
|
|
while(not quitting)
|
|
msg$ = message$
|
|
if(instr(msg$, "Quit") or instr(msg$, translate$("Quit"))) quitting = true
|
|
wend
|
|
|
|
window close "Win"
|
|
Explanation:
|
|
This shows automatic translation of the menu strings "File" and "Quit" and the draw text string. Change the language settings to German in your ZETA preferences. Note: The menu strings are also translated when you do not provide the translation file because ZETA comes with some translations for typical strings used in applications.
|
|
|
|
Further, we have to check the translation of the message$ too with translate$ because the menu now reports the message string "Datei:Beenden|" when selected in German.
|
|
|
|
Related: translate$()
|
|
&
|
|
translate$()
|
|
|
|
Name:
|
|
translate$() -- translate a string on ZETA
|
|
|
|
Synopsis:
|
|
Translation$ = TRANSLATE$(Source$)
|
|
|
|
Description:
|
|
The counterpart to the localize command is translate$(). It translates the string Source$ according to known dictionaries (see localize for more information about dictionaries) into the language currently set as default in ZETA.
|
|
|
|
Note: Currently localization is only supported on ZETA. However, supporting the localization of your program is a good idea for BeOS users too because localization support might be added soon to BeOS yab.
|
|
|
|
Example:
|
|
print translate$("File")
|
|
Explanation:
|
|
Using only the system dictionaries, we can obtain the translation of "File" according to the language set in the ZETA preferences.
|
|
|
|
Related: localize
|
|
&
|
|
&Sound
|
|
&
|
|
beep
|
|
|
|
Name:
|
|
beep -- ring the bell within your computer; a synonym for bell
|
|
|
|
Synopsis:
|
|
beep
|
|
|
|
Description:
|
|
The beep-command rings the bell once. beep is a synonym for bell.
|
|
|
|
Example:
|
|
beep:print "This is a problem ..."
|
|
Related: bell
|
|
&
|
|
bell
|
|
|
|
Name:
|
|
bell -- ring the bell within your computer (just as beep)
|
|
|
|
Synopsis:
|
|
bell
|
|
|
|
Description:
|
|
The bell-command rings the bell within your computer once. This command is not a sound-interface, so you can neither vary the length or the height of the sound. bell is exactly the same as beep.
|
|
|
|
Example:
|
|
print "This is a problem ...":bell
|
|
Related: beep
|
|
&
|
|
sound play
|
|
|
|
Name:
|
|
sound play -- play a sound file
|
|
|
|
Synopsis:
|
|
Id = SOUND PLAY Filename$
|
|
|
|
Description:
|
|
To play a sound file named Filename$ which can be of any supported format (e.g. WAV, MP3, etc.) sound play will return a number Id. Use Id to have basic control with the two other sound commands: sound wait and sound stop.
|
|
|
|
If the file could not load, Id will be set to -1.
|
|
|
|
Design:
|
|
In a GUI context use sound wisely. Remember that not everyone can hear the sound, e.g. because sound is turned off, not supported or the user is deaf or hard-of-hearing. Thus, do not put important information for your application in speech files only. Additionally, remember that bells and whistles on each mouse click can become very annoying.
|
|
|
|
Example:
|
|
id = sound play "bach.mp3"
|
|
while(1)
|
|
wend
|
|
Explanation:
|
|
|
|
This loads the file "bach.mp3" and then waits forever (use Ctrl-C or Break to end the program).
|
|
|
|
Related: sound stop, sound wait
|
|
&
|
|
sound stop
|
|
|
|
Name:
|
|
sound stop -- stop playing a sound file
|
|
|
|
Synopsis:
|
|
SOUND STOP Id
|
|
SOUND STOP(Id)
|
|
|
|
Description:
|
|
Stop a sound that is playing with the valid identification number Id.
|
|
|
|
Example:
|
|
id = sound play "bach.mp3"
|
|
sleep 3
|
|
sound stop id
|
|
Explanation:
|
|
|
|
This first loads the file "bach.mp3", plays it for three seconds and then stops it.
|
|
|
|
Related: sound play, sound wait
|
|
&
|
|
sound wait
|
|
|
|
Name:
|
|
sound wait -- waits until a sound file is finished playing
|
|
|
|
Synopsis:
|
|
SOUND WAIT Id
|
|
SOUND WAIT(Id)
|
|
|
|
Description:
|
|
After the a sound file named Id started playing, use this command to wait until the file finished playing.
|
|
|
|
Example:
|
|
id = sound play "bach.mp3"
|
|
sound wait id
|
|
Explanation:
|
|
|
|
This first loads the file "bach.mp3" and then plays it until it ends.
|
|
|
|
Related: sound play, sound stop
|
|
&
|
|
&Window
|
|
&
|
|
alert
|
|
|
|
Name:
|
|
alert -- show an alert window
|
|
|
|
Synopsis:
|
|
ALERT Text$, ButtonLabel$, Type$
|
|
Selected = ALERT Text$, Button1$, Button2$, Button3$, Type$
|
|
|
|
Description:
|
|
By simply calling alert, you can always display an alert window.
|
|
|
|
It always has a message Text$ and it can either have one, two or three buttons.
|
|
|
|
For the second syntax, the alert window will return the number of pressed button, where Button1$ is the label of the most left button and Button3$ is the label or the most right one. If you specify Button2$ or Button3$ as empty string (""), the according button is not shown.
|
|
|
|
Type$ specifies the icon displayed on the left side of the alert window. It has to be one of the following strings:
|
|
"None" for no icon
|
|
"Info" for the information icon
|
|
"Idea" for the light bulb icon
|
|
"Warning" for the yellow exclamation mark
|
|
"Stop" for the red exclamation mark
|
|
|
|
Design:
|
|
Use a warning icon to warn the user that something might go wrong (e.g. ask whether to save before quitting) and the stop icon to inform the user that something already went wrong (e.g. saving failed).
|
|
|
|
For the dialog box, always use complete sentences, while for the buttons use understandable labels. Capitalize the buttons in English.
|
|
|
|
Note: the right button always has the focus in the multi-button alert. Do not put a dangerous action on this button. E.g. for a dialog "Your data will be lost!", do not put the "Proceed" button on the right position, but rather the "Cancel" button.
|
|
|
|
Example:
|
|
alert "Warning! All your base are belong to us.", "Ok", "warning"
|
|
selected = alert "Choose a button", "Left", "Middle", "Right", "info"
|
|
print "You selected button number: ", selected
|
|
Explanation:
|
|
|
|
In the last line, the number of the selected button will be printed on screen.
|
|
|
|
Related: window open
|
|
&
|
|
filepanel
|
|
|
|
Name:
|
|
filepanel -- open a file or directory selection window
|
|
|
|
Synopsis:
|
|
Filename$ = FILEPANEL Mode$, Title$, Directory$
|
|
Filename$ = FILEPANEL Mode$, Title$, Directory$, DefaultFile$
|
|
|
|
Description:
|
|
In BeOS there is a default window for selecting files or directories to load or save. This so-called filepanel is easily accessable with the filepanel command in yab. The filepanel will open the selection window for you, it lets the user browse, select etc. in the directory tree and returns the selected or newly entered filename. Note: The filepanel just gives you the filename, it does not open, save or process this filename in any way; you have to do that on your own of course.
|
|
|
|
First have a look at the parameters. Filename$ will contain the resulting path and name of the selected or newly created directory or filename. If the filepanel is canceled, the Filename$ will be empty ("").
|
|
|
|
There are different modes Mode$ for a filepanel. Depending on the mode it will act differently:
|
|
|
|
Mode$ = "Load-File" -- the user is able to select any file
|
|
Mode$ = "Load-Directory" -- the user is able to select any directory
|
|
Mode$ = "Load-File-and-Directory" -- the user is able to select any file or directory
|
|
Mode$ = "Save-File" -- the user is able to select either an existing file or enter a name for a new file; when selecting an existing file a popup window will ask whether the file should really be overwritten
|
|
|
|
Furthermore, the title for the window tab has to specified in Title$. Ideally this should be something like "Open" or "Save" according to the mode.
|
|
|
|
The starting directory for browsing is set with Directory$. If this is an invalid directory, "/boot/home" will be used instead.
|
|
|
|
Only for the "Save-File" mode, you additionally can provide a default filename that is put into the textcontrol field of the filepanel in this mode. If you call the filepanel without DefaultFile$, the textcontrol field will be empty.
|
|
|
|
Design:
|
|
Having filepanels for the file selection is always a good idea. They are much easier to handle than self constructed columnboxes for browsing directories. To use them is just the BeOS way of doing things.
|
|
|
|
Example:
|
|
window open 100,100 to 300,200, "Example", "Example"
|
|
button 10,10 to 190,30, "OpenFile", "Open a file...", "Example"
|
|
button 10,40 to 190,60, "OpenDir", "Open a directory...", "Example"
|
|
button 10,70 to 190,90, "Save", "Save a file...", "Example"
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "OpenFile")) filename$ = filepanel "load-file", "Open File", ""
|
|
if(instr(m$, "OpenDir")) filename$ = filepanel "load-directory", "Open Directory", ""
|
|
if(instr(m$, "Save")) filename$ = filepanel "save-file", "Save File", "", "SuggestedFile"
|
|
|
|
if(instr(m$, "Quit")) quitting = true
|
|
|
|
if(filename$ <> "") then
|
|
alert "You haven chosen "+filename$, "Ok", "info"
|
|
filename$ = ""
|
|
endif
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
The example above opens a window with three buttons. According to the button the filepanel is started in a different mode. Try to understand the difference in the behaviour of the three modes above. Finally, when a valid file or directory is chosen, an alert popup window opens to display the full path of that selected entry.
|
|
|
|
&
|
|
window open
|
|
|
|
Name:
|
|
window open -- open a window
|
|
|
|
Synopsis:
|
|
WINDOW OPEN x1,y1 TO x2,y2, ID$, Title$
|
|
|
|
Description:
|
|
The window open command is a very basic and very important command for most yab programs. As it name says, a window is opened on the current desktop. The coordinates (x1,y1) to (x2,y2) of the window are related to the screen coordinates of the current desktop; thus (0,0) is the upper left corner of the screen. The window gets a title named Title$ which is displayed in the tab of the window. Title$ is allowed to be empty ("") aswell. Additionally, the window gets an own ID named ID$. You can use it like any other view and draw on it or put widgets on it. However, you cannot delete it with the view remove command, use window close instead.
|
|
|
|
Message:
|
|
A window will send several messages to the message queue:
|
|
ID$+":_QuitRequested" -- the close button was pressed or the window received any other message to close itself
|
|
ID$+":_Activated" -- the window was activated
|
|
ID$+":_Deactivated" -- the window was deactivated
|
|
|
|
If your application gets the general message "_QuitRequested" it is asked to close down completly. This is more general than the window "_QuitRequested" above which only should shut down the window itself.
|
|
|
|
Design:
|
|
Use capitalized words for the title tab in English as in headings (but not in German!). Your window should always act as expected when the close button is pressed. Have a look at the window set command to learn about different look and feel parameters for your window.
|
|
|
|
When your window has quite a lot of widgets and drawings on startup to do, it might look quite ugly with lots of flickering. To avoid this, simply construct the window with negative coordinates (e.g. window open -400,-400 to -100,-100, "Example", "Example"). Then move it to its real position on the workspace with the "MoveTo" option of the window set command when the setup is done.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
button 10,90 to 190,110, "Button", "My First Window", "Example"
|
|
|
|
while(not quitting)
|
|
m$ = message$
|
|
if(instr(m$, "Example:_QuitRequested")) then
|
|
alert "You pressed the window close button", "Ok", "info"
|
|
quitting = true
|
|
elsif(instr(m$, "_QuitRequested")) then
|
|
alert "The application should now shut down", "Ok", "info"
|
|
quitting = true
|
|
elsif(instr(m$, "Button")) then
|
|
alert "The button was pressed", "Ok", "info"
|
|
endif
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
A simple window with a button. Try to close it with the close button and then try to shut it down with the Alt-Q shortcut key. This shows how the different "_QuitRequested" messages should be handled.
|
|
|
|
Related:
|
|
alert, window close, window count, window get, window set
|
|
&
|
|
window close
|
|
|
|
Name:
|
|
window close -- close a window
|
|
|
|
Synopsis:
|
|
WINDOW CLOSE WindowID$
|
|
|
|
Description:
|
|
Window close of course closes the window named WindowID$. All widgets and views in the window will be deleted. Their IDs and the window ID will no longer be valid, if you call them, yab will exit with an error message.
|
|
|
|
Design:
|
|
It is good style to close all windows before exiting. Always keep track of the windows currently open.
|
|
|
|
Related:
|
|
window open, window count, window get, window set
|
|
&
|
|
window count
|
|
|
|
Name:
|
|
window count -- return the number of open windows
|
|
|
|
Synopsis:
|
|
n = WINDOW COUNT
|
|
|
|
Description:
|
|
To get the number n of currently open windows of your application, simply invoke window count.
|
|
|
|
Example:
|
|
for i=1 to 10
|
|
window open 10+i*10, 10+i*10 to 200+i*10, 200+i*10, "Win"+str$(i), "Win"
|
|
sleep 0.5
|
|
next i
|
|
|
|
n = window count
|
|
|
|
while(n>0)
|
|
window close "Win"+str$(n)
|
|
n = window count
|
|
sleep 0.5
|
|
wend
|
|
Explanation:
|
|
|
|
This funky program first opens ten windows and then closes them using the window count to obtain the number ID of the last opened window.
|
|
|
|
Related:
|
|
window open, window close, window get, window set
|
|
&
|
|
window get
|
|
|
|
Name:
|
|
window get -- request information about a window
|
|
|
|
Synopsis:
|
|
Result = WINDOW GET WindowID$, Option$
|
|
|
|
Description:
|
|
To obtain some properties of the window with the ID WindowID$, the following options are allowed:
|
|
|
|
Option$ = "Position-X" -- Result will contain the horizontal position of the upper left corner of the window relative to the screen
|
|
Option$ = "Position-Y" -- Result will contain the vertical position of the upper left corner of the window relative to the screen
|
|
Option$ = "Width" -- Result will contain the width of the window
|
|
Option$ = "Height" -- Result will contain the height of the window
|
|
Option$ = "Minimum-Width" -- Result will contain the minimum width of the window that is allowed when resizing
|
|
Option$ = "Minimum-Height" -- Result will contain the minimum height of the window that is allowed when resizing
|
|
Option$ = "Maximum-Width" -- Result will contain the maximum width of the window that is allowed when resizing
|
|
Option$ = "Maximum-Height" -- Result will contain the maximum height of the window that is allowed when resizing
|
|
Option$ = "Exists" -- Result will be true if a window with this WindowID$ exits and false otherwise
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
|
|
w = 200
|
|
h = 200
|
|
|
|
while(not instr(message$, "Quit"))
|
|
if(window get "Example", "Width" <> w) then
|
|
w = window get "Example", "Width"
|
|
print "New Width: ", w
|
|
endif
|
|
if(window get "Example", "Height" <> h) then
|
|
h = window get "Example", "Height"
|
|
print "New Height: ", h
|
|
endif
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
When the window is resized, the new width and the new height are printed on the standard output.
|
|
|
|
Related:
|
|
window open, window close, window count, window set
|
|
&
|
|
window set
|
|
|
|
Name:
|
|
window set -- set the properties of a window
|
|
|
|
Synopsis:
|
|
WINDOW SET WindowID$, Option$
|
|
WINDOW SET WindowID$, Option$, x,y
|
|
WINDOW SET WindowID$, Option$, Value$
|
|
|
|
Description:
|
|
This command allows the flexible ajustment of the look and feel of a window. We first inspect the options that require no further parameter other than Option$:
|
|
|
|
Option$ = "Activate" -- activate the window, so it is in the foreground.
|
|
Option$ = "Deactivate" -- deactivate the window, so it is in the background.
|
|
Option$ = "Minimize" -- minimize the window, or restore the window if it is already minimized.
|
|
Option$ = "Maximize" -- maximize (zoom) the window.
|
|
Option$ = "Enable-Updates" -- updates the window again after a "Disable-Updates".
|
|
Option$ = "Disable-Updates" -- disables the automatic window updates.
|
|
|
|
To disable updates is normally not needed, this just means that after this command no drawing even from widgets will be shown.
|
|
|
|
Given two additional parameters x and y, the following options are valid:
|
|
|
|
Option$ = "ResizeTo" -- resize the window to (x,y) relative screen coordinates
|
|
Option$ = "MoveTo" -- move the window to (x,y) relative screen coordinates
|
|
Option$ = "MinimumTo" -- when resizing, the minimum width and height is given by (x,y)
|
|
Option$ = "MaximumTo" -- when resizing, the maximum width and height is given by (x,y)
|
|
|
|
Given an additional parameter Value$, the following options are valid:
|
|
|
|
Option$ = "Look" -- this changes the appearance of the window accroding to the following values:
|
|
Value$ = "Document" -- large title bar, thick border, draggable resize box
|
|
Value$ = "Titled" -- same as the document window, but with a less substantial resize corner, default
|
|
Value$ = "Floating" -- small title bar, thin border, resize corner
|
|
Value$ = "Modal" -- no title bar, thick border, no resize control
|
|
Value$ = "Bordered" -- no title bar, line border, no resize control
|
|
Value$ = "No-Border" -- a borderless white rectangle
|
|
|
|
Option$ = "Feel" -- this sets the behaviour of the window in relation to other windows
|
|
Value$ = "Normal" -- behaves like a normal window (non-modal, non-floating), default
|
|
Value$ = "Modal-App" -- the window blocks all other windows of this application
|
|
Value$ = "Modal-All" -- the window blocks all other windows on the system, the window is visible on all workspaces
|
|
Value$ = "Floating-App" -- the window floats on top of all other windows of this application
|
|
Value$ = "Floating-All" -- the window floats on top of all other windows on the system, the window is visible on all workspaces
|
|
|
|
Option$ = "Flags" -- this sets special properties of a window, flags can be used accumulative, simply write all wanted flags in the Value$
|
|
Value$ = "Not-Closable" -- the window does not have the close button in the tab
|
|
Value$ = "Not-Zoomable" -- the window does not have the zoom button in the tab
|
|
Value$ = "Not-Minimizable" -- the window cannot be minimized
|
|
Value$ = "Not-H-Resizable" -- the window cannot be resized horizontally
|
|
Value$ = "Not-V-Resizable" -- the window cannot be resized vertically
|
|
Value$ = "Not-Resizable" -- the window cannot be resized
|
|
Value$ = "Accept-First-Click" -- when the window is inactive it still accepts the first click
|
|
Value$ = "Reset" -- reset all flags back to none
|
|
|
|
Option$ = "Workspace" -- sets where the window is shown:
|
|
Value$ = "All" -- the window is shown on all workspaces
|
|
Value$ = "Current" -- the window is shown on the current workspace, default
|
|
|
|
Option$ = "Title" -- set the window title to Value$
|
|
|
|
Design:
|
|
Look:
|
|
For most application the default "Titled" look will be sufficient. However, heavy apps with big windows, e.g. the IDE, should have the "Document" look. Use "Floating" for toolboxes and other options that stay around, as done e.g. in Refraction. "Modal" is meant to be used for alert windows that block the main application. "Bordered" and "No-Border" are for more creative applications like games and eye candy stuff.
|
|
|
|
Feel:
|
|
Always try to avoid windows with a "Modal-All" feel because they block the whole system.
|
|
|
|
Resizable:
|
|
Try to set appropriate minimum and maximum width and height parameters so your application always looks good.
|
|
|
|
Example:
|
|
window open 100,100 to 300,300, "Example", "Example"
|
|
window set "Example", "MinimumTo", 150,150
|
|
window set "Example", "Look", "Floating"
|
|
window set "Example", "Feel", "Floating-All"
|
|
|
|
while(not instr(message$, "Quit"))
|
|
wend
|
|
|
|
window close "Example"
|
|
Explanation:
|
|
|
|
A small demo window is opened with the floating look and feel. It can only be resized to a width and height of (150,150).
|
|
|
|
Related:
|
|
window open, window close, window count, window get
|
|
&
|