& 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 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:canvas
Views:Boxview
Boxview:boxview set
Boxview: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:bitmap save
Bitmaps:bitmap remove
Bitmaps:bitmap image
Bitmaps:bitmap get
Bitmaps:bitmap color
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()
System:Attributes
Attributes:attribute clear
Attributes:attribute get
Attributes:attribute get$
Attributes:attribute set
& 
& 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", "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.

"r" -- Open the file for reading (may also be written as for reading). If the file does not exist, the command will fail.

"r+" -- Open the file for reading and writing. If the file does not exist, it will be created. Writing is limited to poke, print #a will not work in 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
&Attributes
&
attribute clear

Name:
attribute clear -- Deletes an attrinbute from a file.

Synopsis:
attribute clear Name$, Filename$

Description:

Delete the attribute Name$ from file Filename$.

Related: attribute set, attribute get, attribute get$
&
attribute get

Name:
attribute get -- Get the number value of the attribute.

Synopsis:

Value = ATTRIBUTE GET Name$, Filename$

Description:

Value = ATTRIBUTE GET Name$, Filename$
  Get the number value of the attribute Name$ for file Filename$.
  For "Bool" type attributes:
  Value = 1|0

Example:

attribute set "bool","Saved", "false", "foobar" 

if (attribute get "Saved","foobar") then
print "foobar is saved"
else
print "foobar is not saved"
end if

Explanation:

This example saves a false (0) attribute named Saved on the file "foobar" then checks to see if the Saved attribute is true(1) or false(0) and prints the result. in this case "foobar is not saved."

Related: attribute clear, attribute set, attribute get$
&
attribute get$

Name:

attribute get$ -- Get the string value of an attribute.

Synopsis:

Value$ = ATTRIBUTE GET$ Name$, Filename$
  Get the string value of the attribute Name$ for file Filename$.
  For "Bool" type attributes:
  Value$ ="true|false"
  To get a list of attribute names and their types separated by " | ": 
  Name$ = "" 
  To get  the current program directory:
   Name$ = "" and Filename$= ""

Description:

Gets the string value of an attribute, or the list of attributes attatched to a file, or the directory that the program was executed from.

If the attribute is a bool type, the string returned is "true" or "false"

If the attribute name is "" a list of attributes attatched to the file is returned.

if both the attribute name and filename are "",  the current program directory is returned.

Example:

dir$ = attribute get$ "",""
dir$=dir$+"/"

attribute set "string","attribute1", "This is the first attribute,", dir$+"foobar"
attribute set "int","attribute2", "127", dir$+"foobar"
attribute set "bool", "attribute3", "false",  dir$+"foobar"
a$=attribute get$ "", dir$+"foobar"
print a$
a$=attribute get$ "attribute1",  dir$+"foobar"
print "attribute1 \""+a$+"\""


Output:

attribute1 | String | attribute2 | Int | attribute3 | Bool | 
attribute1 "This is the first attribute."


Explanation:

This program uses attrribute get$ to find the program directory, then saves three attributes to the file foobar located in the program directory. Next it gets and prints a list of the attribute names and types associated with the file, then it prints the contents of attribute1.

Related: attribute clear, attribute set, attribute get
&
attribute set

Name:

attribute set --  sets ( adds or overwrites ) an attribute of a file.


Synopsis:

ATTRIBUTE SET Type$, Name$, Value$, Filename$
  Set the attribute Name$ of type Type$ for the file Filename$ with the string Value$.
  These are valid types:
  Type$ = "String|Int|Long|Double|Float|Mime|Bool"
  For Bool type attributes:
  Value$ = "true|false"

Description:

Attribute set sets, adds or overwrites, file attributes. The attributes can be strings, integer, long.double, or float numbers, or boolian true/false.

 
Related: attribute clear, attribute get, attribute get$
&
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 internal information

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("desktopheight")
Return the height in pixels of the curent Desktop. 

peek("desktopwidth")
Return the width in pixels of the curent Desktop. 

peek("menuheight")
Return the height in pixels based on the font for a menu. 

peek("scrollbarwidth")
Return the width in pixels for a virtical scrollbar.

peek("tabheight")
Return the height in pixels based on the font for a tabview tab.

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 internal string-information

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
&Bitmaps
&
bitmap

Name:
bitmap -- creates a bitmap in memory

Synopsis:
BITMAP Width, Height, ID$

Description:
Bitmap creates a new bitmap in memory. A bitmap can be drawn on like a view or canvas.  A bitmap is always initialized with a white transparent background

Related:  bitmap color, bitmap get, bitmap image, bitmap remove, bitmap save, draw bitmap  

&
bitmap color

Name:
bitmap color -- Gets the color of a pixel on a bitmap

Synopsis:
color = BITMAP COLOR x, y, ID$, ColorPart$
	ColorPart$ = "red|green|blue"

Description:
Returns the red, green, or blue color value of the pixel at position (x,y) of the bitmap ID$

Related: bitmap, bitmap get, bitmap image, bitmap remove, bitmap save, draw bitmap  
&
bitmap get

Name:
bitmap get -- get heitht/width information or insert an icon or portion of a bitmap or canvas view  to bitmap

Synopsis:
BITMAP GET x1, y1 TO x2, y2, Target_bitmap$, Source_bitmap$
BITMAP GET IconSize, Bitmap$, File$
BITMAP GET ID$, Option$, Path$
BITMAP GET ID$, Option$

Description:
Get a portion of an image:

BITMAP GET x1, y1 TO x2, y2, Target_bitmap$, Source_bitmap$

x1,y1 and x2, y2 describe the bounding rectangle for the data in Source_bitmap$ to be copied to Target_bitmap$. Source_bitmap$ must be a bitmap or canvas. the Target_bitmap$ is created.

get an icon and copy it to a bitmap:

BITMAP GET IconSize, Bitmap$, File$

Copies the icon, shown in Tracker, of File$ in the specified IconSize onto Bitmap$.
The icon will be resized to IconSize, and properly scaled if it is an hvicon.

Bitmap$ is created.

Note: icons are square, IconSize 40 gives an image 40 * 40.

BITMAP GET ID$, Option$, Path$

Copies an icon to bitmap ID$.
  
Option$ =  "Path|Mime|Mime16|Mime32"
 
If Option$ = "Path",  Path$ must be the path to a file. The icon returned is 32 * 32
If Option$ = "Mime" or "Mime16", Path$ must be the mimetype of the file which icon is to be swown. The resulting bitmap is 16 to 16.
If Option$ = "Mime32", Path$ must be the mimetype of the file which icon is to be swown.The resulting bitmap is 32 to 32.

the bitmap ID$, is created.

x=BITMAP GET ID$, Option$
Option$ = "Height|Width"
Delivers height or width of bitmap ID$

Example:

#!yab

window open 100,100 to 600,600, "MainWindow", "IconWorld"
canvas 0,0 to 500,500, "Main","MainWindow"
systempath$ = "/boot/system/apps/Mail"

draw text 70,30, "bitmap get \"BMP_icon\", \"path\", \"" + systempath$ +"\"", "Main"
bitmap get "BMP_icon", "path", systempath$
draw bitmap 10, 10, "BMP_icon", "alpha", "Main"
bitmap remove "BMP_icon"
 
draw text 70,70, "bitmap get \"BMP_icon\", \"mime16\", \"application/x-vnd.Be-MAIL\"", "Main"
bitmap get "BMP_icon", "mime16", "application/x-vnd.Be-MAIL"
draw bitmap 10, 60, "BMP_icon", "alpha", "Main"
bitmap remove "BMP_icon"

draw text 70,110, "bitmap get \"BMP_icon\", \"mime32\", \"application/x-vnd.Be-MAIL\"", "Main"
bitmap get "BMP_icon", "mime32", "application/x-vnd.Be-MAIL"
draw bitmap 10, 90, "BMP_icon", "alpha", "Main"
bitmap remove "BMP_icon"

draw text 70,150, "bitmap get 62, \"BMP_icon\", \"" + systempath$ + "\"", "Main"
bitmap get 62, "BMP_icon", systempath$
draw bitmap 10, 130, "BMP_icon", "alpha", "Main"

x=bitmap get "BMP_icon","width"
draw text 70,190, "x=bitmap get 62, \"BMP_icon\", \"width\" :"+str$(x), "Main"
bitmap remove "BMP_icon"

BITMAP GET 0, 130 TO 60, 150,"BMP_icon","Main"
draw bitmap 0, 200, "BMP_icon", "alpha", "Main"
draw text 70,220, "bitmap get 0,130 TO 60, 150, \"BMP_icon\", \"Main\"","Main" 

x=bitmap get "BMP_icon","width"
draw text 70,240, "x=bitmap get, \"BMP_icon\", \"width\" :"+str$(x), "Main"

while(not instr(message$, "Quit"))
wend

window close "Main"


Explanation:

This program uses all forms of bitmap get and displays the output in a Window.

Related: bitmap, bitmap color, bitmap image, bitmap remove, bitmap save, draw bitmap  
&
bitmap image

Name:
bitmap image -- copies an image file to a bitmap.

Synopsis:
ErrCode = BITMAP IMAGE ImageFile$, Bitmap$

Explanation:

Load image file ImageFIle$ into a new Bitmap called Bitmap$

Related: bitmap, bitmap color, bitmap get, bitmap remove, bitmap save, draw bitmap

&
bitmap remove

Name:
bitmap remove -- removes a bitmap from memory

Synopsis:
BITMAP REMOVE Bitmap$

Explanation:
Removes Bitmap$ from memory

Related: bitmap, bitmap color, bitmap get, bitmap image, bitmap save, draw bitmap  

&
bitmap save

Name:
bitmap save -- saves a bitmap to an image file.

Synopsis:
ErrCode = BITMAP IMAGE ImageFile$, Bitmap$

Description:
Saves a bitmap as FileName$ (overwrites existing ones!) in  Format$ 
Format$ = "png|tiff|ppm|bmp|jpeg|tga"
ErrCode = 0|1 , everything worked fine | file could not be saved


Related: bitmap, bitmap color, bitmap get, bitmap image, bitmap remove, draw bitmap  

&
screenshot

Name:
screenshot -- copies the specified region of the desktop onto a bitmap

Synopsis:
SCREENSHOT x1, y1 to x2, y2, Bitmap$

Description:
Takes a screenshot and copies the specified region of the desktop onto Bitmap$, which will be created!
&

&Drawing

&
draw bitmap

Name:
draw bitmap -- Draw a bitmap on a view, another bitmap or a canvas.

Synopsis:
DRAW BITMAP x,y, Bitmap$, Mode$, View$
DRAW BITMAP x1,y1 TO x2,y2, Bitmap$, Mode$, View$

Description:

DRAW BITMAP x,y, Bitmap$, Mode$, View$
Draw a bitmap on a view, another bitmap or a canvas.

Possible Mode$:

"Copy" -- copy the bitmap to the target ignoring transparency
"Alpha" -- copy the bitmap to the target supporting transparency

DRAW BITMAP x1,y1 TO x2,y2, Bitmap$, Mode$, View$
Draws and scales the bitmap Bitmap$.
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. 

Possible Mode$:

"Copy" -- copy the bitmap to the target ignoring transparency
"Alpha" -- copy the bitmap to the target supporting transparency

&
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:


_Scripting:...|


(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

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
&
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
&
boxview set

Name:
boxview set -- set the label and boarder for a boxview

Synopsis:
BOXVIEW SET  ID$, Option$, Value$

Description:
Option$ = "Label",  Value$ = new label
Option$ = "Line",  Value$ = "0|1|2" no |simple | fancy border
&
canvas

Name:
canvas -- creates a special flicker-free drawing view.

Synopsis:
CANVAS x1, y1 TO x2, y2, ID$, View$

Description:

CANVAS x1, y1 TO x2, y2, ID$, View$
A canvas is a special view for flicker-free drawing. It always shows a bitmap
and thus cannot be resized. However, it does not have a drawing queue, so you
do not need DRAW FLUSH
A canvas is always initialized with a white background.

related: draw bitmap, bitmap get
&
layout

Name:
layout -- Set the layout for all views on a window.

Synopsis:
LAYOUT Layout$, WindowOfView$

Description:

Set the layout for all views on the window of View$. The layout will affect all following new widgets, but not the already created. Draw commands are not affected by the layout.
Layout$ (not case sensitive):
"Standard" = default layout, all widgets follow bottom and right side of the window
	except for listboxes and textedit which follow all sides.
"All" = follow all sides (widgets resize)
"None" = follow the top and the left side (equals "top, left")

 -OR- Layout$ is a combination of  horizontal , vertical  (e.g. "Right, Top" etc.).

NOTE:

In combination, horizontal is first and virtical is second. "Right,Top" is ok, "Top, Right" is not.

Horizontal:
"Left" = follow left side (default, when no other horizontal layout is given)
"Right" = follow the right side
"Left, Right" = follow the left and the right side (resize)
"H-Center" = follow the horizontal center
 Vertical:
"Top" = follow the top side (default, when no other vertical layout is given)
"Bottom" = follow the bottom side
"Top, Bottom" = follow the top and bottom side (resize)
"V-Center" = follow the vertical center

&Scrollbar
&
scrollbar

Name:
scrollbar -- make a view scrollable

Synopsis:
SCROLLBAR ID$, ScrollbarType, View$

Description:
SCROLLBAR ID$, ScrollbarType, View$
  Make View$ scrollable.

Related: scrollbar get, scrollbar set
&
scrollbar get

Name:
scrollbar get --  Get the current position of the scrollbar.

Description:
Position = SCROLLBAR GET Scrollbar$, "Horizontal"
Position = SCROLLBAR GET Scrollbar$, "Vertical"
  Get the current position of the scrollbars.

Related: scrollbar, scrollbar set

& 
scrollbar set

Name: scrollbar set --  set various settings for the scrollbars.

Synopsis:
SCROLLBAR SET Scrollbar$, Borderoption$
SCROLLBAR SET Scrollbar$, "Vertical Position", Position
SCROLLBAR SET Scrollbar$, "Horizontal Position", Position
SCROLLBAR SET Scrollbar$, "Vertical Range", Min, Max
SCROLLBAR SET Scrollbar$, "Horizontal Range", Min, Max
SCROLLBAR SET Scrollbar$, "Vertical Steps", SmallSteps, BigSteps
SCROLLBAR SET Scrollbar$, "Horizontal Steps", SmallSteps, BigSteps

Description:
SCROLLBAR SET Scrollbar$, Borderoption$
Borderoption$ = "no-border" or "plain-border" or "fancy-border" (default)

SCROLLBAR SET Scrollbar$, "Vertical Position", Position

SCROLLBAR SET Scrollbar$, "Horizontal Position", Position
Set the scrollbar to the position Position. Default is (0,0).

SCROLLBAR SET Scrollbar$, "Vertical Range", Min, Max

SCROLLBAR SET Scrollbar$, "Horizontal Range", Min, Max
Set the scrollbars to a maximum range, default is (1000,1000).
Note: the Max value will be added to the view's actual width/height.

SCROLLBAR SET Scrollbar$, "Vertical Steps", SmallSteps, BigSteps

SCROLLBAR SET Scrollbar$, "Horizontal Steps", SmallSteps, BigSteps
Set the scrollbar steps. 
SmallSteps are the scrolling steps when the user clicks on the arrow buttons (default is 1.0).
BigSteps are the scrolling steps when the user clicks on the empty part of the scrollbar (default is 10.0).

Related: scrollbar, scrollbar get


&Splitview
&
splitview

Name:
splitview -- Set up the new view and split it into two new views.

Synopsis:
SPLITVIEW x1,y1 TO x2,y2, ID$, IsVerticalSplit, NormalStyle, View$

Description:
Set up the new view ID$ and split it into two new views ID$+"1" and ID$+"2".
If IsVerticalSplit = true, a vertical splitter is set
if IsVerticalSplit = false, a horizontal splitter is set
If NormalStyle = true, the splitter is 10 pixels thick
If NormalStyle = false, the splitter is 4 pixels thick

Example:

splitview 120,110 to 260,195, "Split", true, false, "Box2"
draw set "bgcolor", "Panel-Background-Color, Darken-1-Tint", "Split1"
draw set "bgcolor", "Panel-Background-Color, Lighten-1-Tint", "Split2"
tooltip "Split", "SPLITVIEW"

Explanation:

This snippet from then AllInOne.yab example program opens a splitview and changes the background colors of each pannel so it is easy to see the two suib-views.

related: splitview set, stackview, tabview
&
splitview get

Name: splitview get --  Get the current position of the divider

Synopsis:
Position = SPLITVIEW GET SplitView$, "Divider"

Description:
Get the current position of the divider.

Related: splitview, splitview set

&
splitview set

Name:
splitview set --   Set the position of the divider, or the minimum sizes of the view

Synopsis:
SPLITVIEW SET SplitView$ "Divider", Position
SPLITVIEW SET SplitView$ "MinimumSizes", LeftOrTop, RightOrBottom

Description:

SPLITVIEW SET SplitView$ "Divider", Position
Set the position of the divider, default is the half of the total split view.

SPLITVIEW SET SplitView$ "MinimumSizes", LeftOrTop, RightOrBottom
Set the minimum sizes of the left (or top) view and the right (or bottom) view.

Related: slpitview

&Stackview
&
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
&Tabview
&
tabview

Name:
tabview -- Open a tabview and chose top/bottom for the tabs

Synopsys:
TABVIEW x1,y1 TO x2,y2, ID$, Option$, View$

Description:
Open a tabview and chose top/bottom for the tabs:
Option$ = "top, bottom" where to place the tabs.

Related: splitview, stackview
&
tabview add

Name:
tabview add -- Adds a new view and new tab to a tabview.

Synopsys:
TABVIEW ADD TabView$, TabName$

Description:
For each tab, a new view is created; you can add widgets or draw on these views as ususal.
The ids for the views ist TabView$+"1" for the first, TabView$+"2" for the second view, etc.

example:

// make the tabview
tabview 10,60 to 530,390, "Box", "top", "Win"
tabview add "Box", "Widgets"
tabview add "Box", "Views and More"

// button
button 10,10 to 100,30, "Button", "Button", "Box1"
tooltip "Button", "BUTTON"

Explanation:

This snippet from the AllInOne.yab example program sets up a tabview called Box on the main Window view "Win" with the tabs at the top, then adds two tabs. "Widgets" is the first tab, "Box1", and "Views and More" is the second tab, "Box2". the button is added to the tab labeled "Widgets."

Related: tabview tabview get, tabview set
&
tabview get

Name:
tabview get -- get the curent open tab number

Synopsis:
TabNumber = TABVIEW GET TABVIEW$

Description:
Get the current opened tab. 

Related: tabview, tabview sdd tasbview set

&
tabview set

Name:
tabview set -- Chose the current tab

Synopsys:
TABVIEW SET TabView$, TabNumber

Description:
Open the tab number TabNumber.

Related: tabview tabview add, tabview get

&View
&
view

Name:
view -- add a view

Synopsis:
VIEW x1,y1 TO x2,y2, ID$, View$

Description:
 Adds a view

Related: view get, view remove
&
view dropzone

Name:
view dropzone --  Definea view as a drop zone that accepts dropped files.

synopsis:
VIEW DROPZONE View$

Description:
Define View$ as a drop zone that accepts dropped files.
DROPZONE accepts multiple files (and sends them in inversed order as message)
Related: view
&
view get

Name:
view get -- gets information about a view

Synopsis:
Result = VIEW GET View$, Option$

Description:
Option$ = "Position-X/Position-Y/Width/Height/Exists/Focused"
Returns the requested property or if used with Exists/Focused returns 1 if so and 0 if not.
&
view remove

Name:
view remove -- remove a view

Synopsis:
VIEW REMOVE View$

Description:
Remove View$. The window view cannot be removed. Should be much more stable now.
Warning: Currently clears all internal information about menues and drop boxes. It is only safe to use it, when you don't have any menues or drop boxes on views that will not be removed.
  
Warning:

Never remove menus with shortcuts, otherwise yab will crash when the shortcut key is pressed!

Related: view, view 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
&Dropbox
&
dropbox

Name:
dropbox -- Adds an empty dropbox.

Synopsis:
DROPBOX x1,y1 TO x2,y2, ID$, Label$, View$

Description:
Adds an empty dropbox (BMenuField) at (x1,y1) to (x2,y2) known as ID$ and with a label on View$. 

Example:

snippet

DROPBOX 290,60 TO 480,80, "category", "Category:", "Mainview1"
	DROPBOX ADD "category", "Audio"
	DROPBOX ADD "category", "Business"
	DROPBOX ADD "category", "Development"
	DROPBOX ADD "category", "Education"
	DROPBOX ADD "category", "Games"
	DROPBOX ADD "category", "Graphics"
	DROPBOX ADD "category", "Internet and Network"
	DROPBOX ADD "category", "Productivity"
	DROPBOX ADD "category", "Science and Matyhematics"
	DROPBOX ADD "category", "System and Utilities"
	DROPBOX ADD "category", "Video"
	DROPBOX SELECT "category", 8

end snippet

Explanation:

The dropbox "category" is created with a label of "Categorty" in "MainView1." Next the categories to select from are added, and "Productivity" is set as the default category. When a different category is selectedm the dropbox returns a message:    

category:Science and Matyhematics

if selection 9 is made.


Related: dropbox add, dropbox clear, dropbox count, dropbox get$, dropbox remove, dropbox select
&
dropbox add

Name:
dropbox add -- adds an item to a dropbox.

Synopsis:
DROPBOX ADD DropBox$, Item$

Description:
Add Item$ to the dropbox. Use Item$ = "--" for a separator. 

Related: dropbox , dropbox clear, dropbox count, dropbox get$, dropbox remove, dropbox select
&
dropbox clear

Name:
dropbox clear -- Clear all items from  a dropbox.

Synopsis:
DROPBOX CLEAR DropBox$

Description:
Clear dropbox DropBox$ of all items.

Related: dropbox , dropbox add, dropbox count, dropbox get$, dropbox remove, dropbox select
&
dropbox count

Name:
dropbox count -- count the number of items in a dropbox.

Synopsis:
n = DROPBOX COUNT DropBox$

Description
Count the number of items.

Related: dropbox , dropbox add, dropbox clear, dropbox get$, dropbox remove, dropbox select
&
dropbox get$

Name:
dropbox get$ -- Get the string of the item at a position.

Synopsis:
Item$ = DROPBOX GET$ DropBox$, Position

Description:
Get the item$ at Position fior the dropbox Dropbox$.

Related: dropbox , dropbox add, dropbox clear, dropbox count, dropbox remove, dropbox select
&
dropbox remove

Name:
dropbox remove -- removes an item from a  dropbox.

Synopsis:
DROPBOX REMOVE DropBox$, Position

Description:
Removes item number Position. 
Note: If the removed item was marked, the item before it will be marked instead. You will NOT get
a message that the marked item has changed. If the first item will be deleted, the next item in
the drop box will be marked.

Note:

Each time an item was removed, the drop box count will change as well!

Related: dropbox , dropbox add, dropbox clear, dropbox count, dropbox get$, dropbox select
&
dropbox select

Name:
dropbox select -- Select a dropbox item.

Synopsis:
DROPBOX SELECT DropBox$, Position

Description:
Select the item at position Position.

Note: 

Counting starts at 0.

Related: dropbox , dropbox add, dropbox clear, dropbox count, dropbox get$, dropbox 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
&Options
&
option color

Name:
option color -- Set the background color of a view.

Synopsis:
OPTION COLOR View$, "BGColor", r,g,b

Description:
Set the background color of any view (note: this is different to DRAW SET!)
&
option set

Name:
option set -- set various options for views and controls.

Synopsis:
OPTION SET View$, "Auto-Resize"
OPTION SET View$, "Focus", HasFocus
OPTION SET Control$, "Enabled", IsEnabled 
OPTION SET Control$, "Label", NewLabel$
OPTION SET Control$, "Visible", IsVisible

Description:
OPTION SET View$, "Auto-Resize"
Automatically resize the view View$ to preferred (when this is supported by the view).

OPTION SET View$, "Focus", HasFocus
Set/remove the focus of View$ (when this is supported by the view).

OPTION SET Control$, "Enabled", IsEnabled 
Enable/disable the control Control$.

OPTION SET Control$, "Label", NewLabel$
Give a Control a new label.

OPTION SET Control$, "Visible", IsVisible
Set the control Control$ invisible or visible

Note:

The following widgets are controls:
CHECKBOX, RADIOBUTTON, SLIDER, TEXTCONTROL, BUTTON, COLORCONTROL, SPINCONTROL, CALENDAR
&
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
&Slider
&
slider

Name:
slider -- Add a slider control

Synopsis:
SLIDER x1,y1 TO x2,y2, ID$, Label$, Min, Max, View$
SLIDER x1,y1 TO x2,y2, ID$, Label$, Min, Max, Option$, View$

Description:
SLIDER x1,y1 TO x2,y2, ID$, Label$, Min, Max, View$
Add a slider with a minimum and and a maximum value (Min, Max).

SLIDER x1,y1 TO x2,y2, ID$, Label$, Min, Max, Option$, View$
Option$ = "block/triangle, horizontal/vertical"


Example:

see SliderWorld.yab for example usage.

NOTE:

The label, Label$ must be shorter than the slider or yab will re-size the slider to fit the label. This can cause the slider to be wider than the view. it is best to use short labels.

Related: slider color, slider get, slider label, slider set
&
slider color

Name:
slider color -- set the colors for a slider

Synopsis:
SLIDER COLOR Silder$, Part$, r,g,b

Description:
Sets the rgb color for the Part$ of Slider$
Part$ = "barcolor" -- The color to the left or bottom, representing the slider's value.
Part$ = "fillcolor" -- The color to the right or top, representing the remainder of the posible slider value.  

Related: slider, slider get, slider label, slider set
&
slider get

Name:
slidet get -- get the curent value of a slider

Synopsis:
Value = SLIDER GET Slider$

Description:
Get the currently selected value of the slider.

Related: slider, slider color, slider label, slider set

&
slider label

Name:
slider label -- Set start and end limit labels

Synopsis:
SLIDER LABEL Slider$, StartLabel$, EndLabel$

Description:
Sets the StartLabel$ and  EndLabel$ for the slider Slider$

Related: slider, slider color, slider get, slider set
&
slider set

Name:
slider set -- set the slider value or hashmarks location and numnber

Synopsis:
SLIDER SET Silder$, Location$, Count
SLIDER SET Silder$, Value

Description:
SLIDER SET Silder$, Location$, Count

Set the hashmarks.
Location$ = "none/bottom/top/both" use these valuse for hashmarks for horizontal sliders
Location$ = "none/left/rigth/both" use  these valuse for hashmarks for vertical sliders
Count = number of hashmarks

SLIDER SET Silder$, Value

Set the slider to Value. Moves the slider indicator block to this location.

Related: slider, slider color, slider get, slider label
&Spincontrol
spincontrol

Name:
spincontrol -- Add a spincontrol to a view.

Synopsis:
SPINCONTROL x,y, ID$, Label$, Min, Max, Step, View$

Description:
Add  a spin control at x,y, named ID$, labeled Label$ with  the range (Min,Max), counting by Step on View$.

Related: spincontrol get, spincontrol set
&
spincontrol get

Name:
spincontrol get -- Get the value of a spincontrol.

Synopsis:
Value = SPINCONTROL GET SpinControl$

Description:
Get the current spin control value for SpinControl$.

Related: spincontrol, spincontrol set
&
spincontrol set

Name:
spincontrol set -- set the spincontrol to a value

Synopsis:
SPINCONTROL SET SpinControl$, Value

Description:
Sets the spin control SpinControl$ to value Value.

Related: spincontrol, spincontrol get
&
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
&Textcontrol
&
textcontrol

Name:
textcontrol -- Add a textcontrol to a view.

Synopsis:
TEXTCONTROL x1,y1 TO x2,y2, ID$, Label$, Text$, View$

Description:
Opens a textcontrol from (x1,y1) to (x2,y2) with Label$ and preset it with Text$ on View$

The distance from x1 to x2 needs to be long enough for the label Label$ and the textcontrol view.

Message:
The textcontrol will return a message on invocation, ( by pressing tsb or enter after entering text.)

id$:text$

Related: textcontrol clear, textcontrol get$, textcontrol set
&
textcontrol clear

Name:
textcontrol clear -- Clears the text data from a textcontrol.

Synopsis:
TEXTCONTROL CLEAR TextControl$

Description:
Delete the text of the text control.

Related: textcontrol, textcontrol get$, textcontrol set
&
textcontrol get$

Name:
textcontrol get$ -- get the text held by a textcontrol.

Synopsis:
Text$ = TEXTCONTROL GET$ TextControl$


Description:
Get the entry of the text control TextControl$. Even works, when Return was not pressed.

Related: textcontrol, textcontrol clear, textcontrol set
&
textcontrol set

Name:
textcontrol set -- Set various options for a textcontrol.

Synopsis:
TEXTCONTROL SET TextControl$, IsPassword 
TEXTCONTROL SET TextControl$, Text$
TEXTCONTROL SET TextControl$, Option$, Value$

Description:

TEXTCONTROL SET TextControl$, IsPassword 
IsPassword = false Normal typing
IsPassword = true Hide typing with *

TEXTCONTROL SET TextControl$, Text$
Set the text control's text to Text$.

TEXTCONTROL SET TextControl$, Option$, Value$
Option$="align" Value$= "left" / "right" / "center"
*** note *** Haiku has issues align right. There are open tickets. 
Option$="exclude", Value$=characters to disallow.
Option$="include", Value$=characters to allow.
Option$="length", Value$=str$(number) of characters allowed.
Sets the font used to the system fixed font.
Option$="type"
Value$="number" Only allow  to characters 0-9 and  ".", full stop.
Value$=""alphanumeric" allow all characters.
Option$="focus" Value$ = "true" / "false" Set the focus of TextControl$.
Option$="Curser", Value$=str$(number) positions the curser, sets the focus to true.

Related: textcontrol, textcontrol clear, textcontrol get$
&
textedit

Name:
textedit -- create a multiline text editor

Synopsis:
TEXTEDIT x1,y1 TO x2,y2, ID$, ScrollbarType, View$

Description:
Opens an editor at (x1,y1) to (x2,y2) with ID$ (not displayed) on View$.

ScrollbarType = 0 -- no scrollbar
ScrollbarType = 1 -- the textedit has a vertical scrollbar
ScrollbarType = 2 -- the textedit has a horizontal scrollbar
ScrollbarType = 3 -- the textedit has a vertical and a horizontal scrollbar

TEXTEDIT follows all sides in standard layout.

Example: 
See Tedit.yab or AllInOne.yab example programs.

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:
Adds ( appends ) Text$ to textedit TextEdit$. 
This command works when the textedit is not editable by the user.

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$, Command$
TEXTEDIT COLOR TextEdit$, Option$, r,g,b

Description:

TEXTEDIT COLOR TextEdit$, Option$, Command$
Option$ = "color1, color2, color3, color4, char-color", Command$

Add the command Command$ to the list of words that are checked for syntax highlighting
The char-color behaves differently and highlights only the first character of Command$
(this happens after the highlighting of the other colors).


TEXTEDIT COLOR TextEdit$, Option$, r,g,b
Option$ = "bgcolor, textcolor, color1, color2, color3, color4, char-color", r,g,b

Default colors are:
bgcolor = 255,255,255 (white)
textcolor = 0,0,0 (black)
color1 = 0,0,255 (blue)
color2 = 255,0,0 (red)
color3 = 0,250,0 (green)
color4 = 185,185,185 (gray)
char-color = 200,0,255 (magenta)

Related: textedit, textedit add, textedit clear, textedit get, textedit get$, textedit set
&
textedit get

Name:
textedit get -- retrieve various information from a textedit

Synopsis:
Width = TEXTEDIT GET TextEdit$, "Line-Width", LineNumber
Height = TEXTEDIT GET TextEdit$, "Line-Height", LineNumber
return = TEXTEDIT GET TextEdit$, Option$
LineNumber = TEXTEDIT GET TextEdit$, Option$, Search$
Result = TEXTEDIT GET TextEdit$, Option$, LineNumber

Description:

return = TEXTEDIT GET TextEdit$, Option$
Option$ = "hasChanged" -- returns IsChanged 0 not changed, 1 changed
	
This is a hook function that is set once the user changes the text, reset it to false by using:
	 "textedit set TextEdit$, "changed", false

Then use this hook to see if the user has changed the text. 


Option$ = "countlines" --  returns the number of lines
Option$ = "currentline" -- returns the curent lLineNumber
Option$ = "vertical-scrollbar" -- returns the virtical ofset of the scrollbar
Option$ = "horizontal-scrollbar" -- returns the horizontal ofset of the scrollbar
Option$ = "cursor-position" -- returns the cursor position
Option$ = "textlength" -- returns the length of the text.


Width = TEXTEDIT GET TextEdit$, "Line-Width", LineNumber
Get the width in pixels of the line.

Height = TEXTEDIT GET TextEdit$, "Line-Height", LineNumber
Get the height in pixels of the line.

LineNumber = TEXTEDIT GET TextEdit$, Option$, Search$
Option$ = "Find", Search$
Option$ = "Case-Sensitive-Find", Search$

Specifys the type of search and returns the linenumber that the search string is found in. returns 0 if not found.


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:
EnteredText$ = TEXTEDIT GET$ TextEdit$
Get the entire contents of a textedit.

TextLine$ = TEXTEDIT GET$ TextEdit$, LineNumber
Get the contents of a line of text.



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
Option$ = "align" and  value$ = "left|center|right" -- set the alignment for text in the textedit view.

Related: textedit, textedit add, textedit clear, textedit color, textedit get, textedit get$
&TextURL
&
texturl

Name:
texturl -- Add a text link to a url.

Synopsis:
TEXTURL x,y, ID$, Label$, Address$, View$

Description:
Set the web/email/ftp address at (x,y) with the label Label$ and the url Address$.
This widget is quite nice, it launches the appropriate application when clicked, it supports
a right-click popup-menu and you can drag the url to create either a person file or a bookmark.
Email can be either of the style: "mailto:foo@bar.com" or just "foo@bar.com"
A web url starts either with "http://" or with "file://"
And a ftp address starts with "ftp://"

Related: texturl color
&
texturl color

Name:
texturl color -- Set the color used for the text of a texturl.

Synopsis:
TEXTURL COLOR TextURL$, Option$, r,g,b


Description:
Set the colors for the URL. Valid options are:
"Label" for the color of the label,
"Click" for the color of the label, when clicked and
"Mouse-over" for the color of the label, when the mouse is moved over the label.

Related: texturl
&
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
&Treebox
&
treebox

Name:
treebox -- Adds a treebox to a view.

Sybopsis:
TREEBOX x1,y1 to x2,y2, ID$, ScrollbarType, View$

Description:
Adds a tree box. This behaves just like a LISTBOX but is able to show nested trees.

Related: treebox add, treebox clear, treebox collapse, treebox count, treebox expand, treebox get$, treebox remove, treebox select, treebox sort
&
treebox add

Name:
treebox add -- Add an item to a treebox.

Synopsis:
TREEBOX ADD TreeBox$, RootItem$
TREEBOX ADD TreeBox$, HeadItem$, ListItem$, IsExpanded

Description:

TREEBOX ADD TreeBox$, RootItem$
Add the item RootItem$ to the top level of the tree.

TREEBOX ADD TreeBox$, HeadItem$, ListItem$, IsExpanded
Add the item ListItem$ under the level of HeadItem$ of the tree.

Related: treebox, treebox clear, treebox collapse, treebox count, treebox expand, treebox get$, treebox remove, treebox select, treebox sort
&
treebox clear

Name:
treebox clear -- clear a treebox

Synopsis:
TREEBOX CLEAR TreeBox$

Description:
Clear the tree.

Related: treebox, treebox add, treebox collapse, treebox count, treebox expand, treebox get$, treebox remove, treebox select, treebox sort
&
treebox collapse

Name:
treebox collapse -- Collapse a top level category.

Synopsis:
TREEBOX COLLAPSE TreeBox$, Head$

Description:
Collapses Head$ in TreeBox$.

Related: treebox, treebox add, treebox clear, treebox count, treebox expand, treebox get$, treebox remove, treebox select, treebox sort
&
treebox count

Name:
treebox count --  count the entries in a treebox.

Synopsis:
n = TREEBOX COUNT TreeBox$

Description:
Returns the number of entries in TreeBox$

Related: treebox, treebox add, treebox clear, treebox collapse, treebox expand, treebox get$, treebox remove, treebox select, treebox sort
&
treebox expand

Name:
treebox expand -- Expand a category.

Synopsis:
TREEBOX EXPAND TreeBox$, Head$

Description:
Expands Head$ in TreeBox$.

Related: treebox, treebox add, treebox clear, treebox collapse, treebox count, treebox get$, treebox remove, treebox select, treebox sort


&
treebox get$

Name:
treebox get$ --  Get an item from a treebox.

Synopsis:
Item$ = TREEBOX GET$ TreeBox$, Position

Description:
Returns the Item$ at position Position in TreeBox$.

Related: treebox, treebox add, treebox clear, treebox collapse, treebox count, treebox expand, treebox remove, treebox select, treebox sort
&
treebox remove

Name:
treebox remove -- Remove an item from a treebox.

Synopsis:
TREEBOX REMOVE TreeBox$, Position
TREEBOX REMOVE TreeBox$, Head$, ListItem$

Description:
TREEBOX REMOVE TreeBox$, Position
Removes the entry at position Position in TreeBox$.

TREEBOX REMOVE TreeBox$, Head$, ListItem$
Removes ListItem$ under Head$ in TreeBox$.

Related: treebox, treebox add, treebox clear, treebox collapse, treebox count, treebox expand, treebox get$, treebox select, treebox sort
&
treebox select

Name:
treebox select -- Select an item

Synopsis:
TREEBOX SELECT TreeBox$, Position

Description:
Selects theitem at position Position in TreeBox$.

Related: treebox, treebox add, treebox clear, treebox collapse, treebox count, treebox expand, treebox get$, treebox remove, treebox sort
&
treebox sort

Name:
treebox sort -- Sort the treebox.

Synopsis:
TREEBOX SORT TreeBox$

Description:
Sorts the entries of TreeBox$ alphabetically.


Related: treebox, treebox add, treebox clear, treebox collapse, treebox count, treebox expand, treebox get$, treebox remove, treebox select


&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
&
