This text contains all the functions of flib, read Readme for a more general presentation.
How to use Flib:
You only have to type, in a basic program usually,
example: flib("command1" [,"command2",...])
If you use functions from flib2, then:
example: flib2("version","mkhs:10,500,fl,sc","hide:sc")
The list returned by flib is stored in the variable 'fl'.
'fl' can be declared as a local variable, in as many programs at a time as you want.
Flib will always return a list, empty if the functions called don't return a value or if an error occurred, else it will return all the values returned by the functions, in the right order.
So that people stop asking me this question:
No, you CAN'T write
100->a: flib("apd:a")
You must write
100->a: flib("apd:"&string(a))
Of course, this is worth for any function using numbers.
If you don't understand a function, look at the examples given with Flib, 99% of the problems can be saved this way, thanks !
Info:
Functions of the second library (flib2) are preceded by a star.
All the function names are in small letters and the shorter possible so they are easier and shorter to remember and to write.
I've now included all kinds of protection, so I think flib can't throw an error any more, even if the arguments are wrong.
General functions:
"off"
Turns the calculator off.
"breakoff"
Disables the break (ON key). Attention, using getkey(), calling a program or function string() will enable the break again, that's why I haven't included another function to enable it.
"wait:value"
Waits without doing anything, value is a time in tenth of a second. This function is parameterized to fit exactly on HW2 calculators.
*"apd:value"
Sets the value of the automatic power-down (APD) rate, value is a time in seconds. Returns the previous value.
*"error:num"
Throws the error num, see the TI manual to find the meaning the of the different error codes. The advantage of throwing an error manually is that you can inform the user of the error without exiting the program.
*"reset"
Resets the calculator. This function isn't the most useful, but it's the funniest for sure!
(*)"version"
Returns a string containing Flib's version.
"getcont"
Gets the current contrast, which is a integer between 0 and 15.
"setcont:value"
Set the current contrast. value has to be a number between 0 (very low contrast) and 15 (very high contrast).
"+"
Increases the contrast.
"-"
Decreases the contrast.
Graphical functions:
The argument 'mode' is always optional, it will be replaced by 1 if it is omitted.
The coordinates begin at the upper left corner (0,0) to the lower right corner (159,99) ( (239,127) on a 92+).
"gray"
Allows you to use gray levels : activates the gray levels, clears the screen on the two planes, and activates plane 1. At the end of Flib's call, the library waits for the user to push a key, then returns the value of the pushed key, turns the gray levels off and restores the original screen.
"gray2"
Same thing as 'gray', but the calculator does not wait for a key-press at the end.
"plane:x"
Sets the active plane to x : all the graphical function calls that you'll make after will draw on this plane. x can take the values 0 and 1.
A * pixel corresponds to planes * on/off :
"clrscr"
Clears the screen.
"sprite:[x,][y,][mode,]pic"
Puts the bitmap pic to the screen at position (x, y).
mode can take the values:
x and y are worth 0 by default.
"savpic:x1,y1,x2,y2,pic"
Saves in variable pic the part of the screen between the points (x1, y1) and (x2, y2).
"picsize:pic"
Returns in a list the horizontal and vertical dimensions of pic.
"savscr:pic"
Saves the LCD screen and puts it in pic.
"rclscr:pic"
Restores the LCD screen saved in pic with 'savpic'.
"rect:x1,y1,x2,y2[,mode]"
Draws a empty rectangle with (x1, y1) and (x2, y2) as corners.
mode can take the values:
In fact, if you're looking for a particular effect, just try other arguments, you can have rounded and inverted rectangles, double rectangles with the corners cut...
Moreover, the values indicated above will draw white rectangles, you'll have to add one of the three first values to draw a black or inverted rectangle.
Ex: 97 ( = 64 + 32 + 1 ) for a black double rounded rectangle.
"fillrect:x1,y1,x2,y2[,mode]"
Draws a filled rectangle with (x1, y1) and (x2, y2) as corners.
mode can take the values:
"filltri:x1,y1,x2,y2,x3,y3[,mode]"
Draws a filled triangle between the points (x1, y1), (x2, y2) and (x3, y3).
mode can take the same values as 'line'.
"fillpoly:x1,y1,x2,y2,x3,y3,x4,y4[,mode]"
Draws a filled quadrilateral between the lines (x1, y1)-(x2, y2) and (x3, y3)-(x4, y4).
The first line has to be nearer to the bottom of the screen than the second one, or nothing will be drawn.
mode can take the same values as 'line'.
"ellipse:x,y,r1,r2[,mode]"
Draws an ellipse with center at (x, y), and with semi axes r1 and r2.
mode can take the values:
"line:x1,y1,x2,y2[,mode]"
Draws a line between (x1, y1) and (x2, y2).
mode can take the values:
In fact, shadings will work only with lines more than 45°.
"pix:x,y[,mode]"
Draws a pixel at (x, y).
mode can take the values:
"pixtest:x,y"
Returns 0 if the pixel (x, y) is off and 1 if it's on.
"mkpic:width,height,var,data"
Creates in variable var a picture of width width and height height, where the picture itself is directly given as a string.
The data structure is defined as following: each line is given by a whole number of character, each character contains 8 pixels (if the width of the picture is not a multiple of 8, the last bits of the last character of each line won't be used).
The lines are written one after the other.
To avoid the problem of characters that aren't accessible to BASIC, replace character n°0 by '00', n°2 by '02' and n°13 by '13'.
If you don't understand, look at the small BASIC program that automatically converts an area of the graphical screen in a string for 'mkpic'; you should also look at my BASIC Othello so you can have an example of how to use it.
If I did such a function, it's because I always see BASIC programmers who distribute their program with thousands of little pictures in several folders. With this function, it's possible to create pictures easily and with little memory.
"map:[width,][x,][y,][horiz,][vert,][mode,][time,],prefix,data"
Displays a succession if sprites in one pass, one after the other in ordered lines.
width is the number of sprites per horizontal line; when this number is reached, sprites will be drawn on the next line.
Sprites will be drawn from the point (x, y); this point is (0, 0) by default.
mode can take the same values as 'sprite'.
horiz and vert indicate what size is left to each sprite: if some sprites are bigger than this size, they'll overlap. When horiz and vert are omitted, 'map' takes the size of the current sprite as arguments, but in this case, sprites should all have the same size, otherwise strange shifts could appear.
All sprites must have their name made of prefix + 'one character': data is the succession of the characters standing for all the sprites you want to display.
Last but not least, time is a subtle argument: 'map' becomes an evolved CyclePic if you use it. Indeed, the function is then going to loop till a key is pressed by the user, time is the time given in hundredth of a second it is going to wait between two picture drawings. If horiz and vert are worth 0, all the pictures will be drawn at the same place.
Ex : flib("map:,x,y,0,,4,time,pic,123456")
where pic1, pic2,... make a little video, and x, y and time have to be replaced by numbers.
By setting time to 0, you can even make gray levels (see example 'grayex'), practical to display a gray image in a black & white interface, what you can't do with 'gray' (but quality is not as good).
Text functions:
"font:num"
Sets the current font.
num can take the values:
"drawstr:x,y,[mode,]str"
Prints the string str at (x, y).
If x is worth 999, the string will be centered horizontally on the screen.
mode can take the values:
Attention, if you omit the argument mode, str shouldn't begin with a number, or Flib will think it is mode. Another solution is to write a coma without any argument behind.
"drawstrv:x,y,[mode,]str"
Prints the string str vertically at (x, y).
mode can take the same values as in 'drawstr'.
"width:num,str"
Returns the width in pixels of the string str using the font num.
"msg:string"
Prints string inverted in a black box and waits for the user to press a key, then restores the screen and returns the value of the pressed key (see 'keywait').
You can print the message on more than one line by separating each line with '|', each line will be truncated after 25 chars (38 on a 92+) and centered on the screen. The screen is limited to 8 lines (12 on a 92+).
Do not use this function when gray levels are activated, because both functions use the same memory place so save the screen, so Flib will no restore correctly the screen at the end. But you can do it manually if really you want to...
*"menu:[height,][x,][y,]title,options..."
Displays a rectangular menu with as many options and suboptions as you wish, with it's left upper corner at (x, y). The three first arguments are optional, the menu will have just the right height and will be centered if they are omitted. If height is insufficient to show all the elements, you can scroll the menu.
Each option is preceded by a coma, and each suboption by a '|'.
The value returned in 'fl' is the number of the element where the user has pressed ENTER, or 0 if he has pressed ESC.
Try for example on your calculator
flib2("menu:20,title,option1,option2|suboption1|suboption2")
to understand, or look at the program 'menu' given as example.
*"numline:var"
Returns the number of lines in the text variable var.
If there is a problem - var doesn't not exist or isn't a text -, the function doesn't return anything.
*"getline:n,var"
Returns the n-th line of the text variable var.
If there is a problem - var doesn't exist, or is not a text, or doesn't have enough lines -, the function doesn't return anything.
High-scores functions:
A high-score table is a symbol containing several high-scores, each of them formed with a number between 0 and 65535 and a string, 10 characters maximum.
The symbol is a string, but you don't have access to the data, you will only see 'highscores by flib'.
*"mkhs,n,score,name,var"
Creates in var a high-score table containing n high-scores, initialized to the value score and to the name name.
If name is more than 10 characters long, it will be truncated.
*"puths:score,name,var"
Automatically inserts in the high-score table var the record given by its value score and a name name.
Returns the place of the new record, or 0 if score wasn't good enough to be in the high-scores.
If name is more than 10 characters long, it will be truncated.
*"geths:n,var"
Returns in 'fl' the n-th high-score of var, a number followed by a string for the name.
Status Line functions:
"slclr"
Erases the status line's content.
"slrcl"
Redraws the line above the status line.
"slmsg:string"
Displays string in the status line.
"busy:mode"
Sets the BUSY indicator in the status line.
mode can take the values:
Key functions:
"keywait"
Waits for the user to press a key and returns the value of the pressed key.
Attention, following codes are different from the ones returned by getkey() in BASIC, the other ones are the same:
Attention: on a 92+, keys Up and Left are inverted.
"keylow"
keylow is used for low-level key reading: it detects only when the arrows or the keys 2nd, Shift, Diamond or Alpha are being held down.
Moreover, it doesn't flush the keyboard queue: it is independent with all the getkey() and other key functions that you can call, it just returns the actual keyboard state.
Finally, it detects when more than a key are pressed at the same time.
It returns a string where the successive chars represent the keys 2nd, Shift, Diamond, Alpha (Lock on the 92+), Left, Right, Up and Down.
For example, "10001010" means that 2nd, Left and Up are being held down, and that the other keys are not.
"initdelay:time"
Sets the time (395th of a second) a key has to be held down before it starts to repeat.
The default value is 336, but it is reseted each time you turn your calc off/on. Returns the previous value.
"delay:rate"
Sets the rate (395th of a second) at which a key auto repeats.
The default value is 48, but it is reseted each time you turn your calc off/on. Returns the previous value.
TIOS functions:
*"hide:var"
Hides the symbol or folder var (the symbol will be hidden for the TIOS).
Attention: if var is a folder, it will hide it, but not the symbols that are inside!
*"unhide:var"
Unhides the symbol or folder var.
Attention: if var is a folder, it will unhide it, but not the symbols that are inside!
*"size:var"
Returns the size of var.
*"state:var"
Returns a number of 3 bits representing the state of var: the first bit tells if var is archived, the second if it's locked and the last one if it's hidden.
More clearly, you must do this if you want to get the different characteristics independently:
flib("state:var")
fl[1] and 1->archived
fl[1] and 2->locked
fl[1] and 4->hidden
*"folder:var"
Returns the list of all the folders containing the symbol var.
*"getfolder"
Returns a list containing all the folders in the calc.
*"getfile:[type,]folder"
Returns in a list all the files of the folder folder.
Moreover, you can add another argument, a number that represents a variable type, then getfile will return only the symbols of the type type.
type can take the following values:
Expressions don't have an assigned value, that's why they don't appear here.
*"getbyte:num[,n],var"
Returns the byte number num of var.
If the argument n is present, Flib will return in a string n bytes of the variable var, beginning with the byte num.
This argument is much more powerful and practical to program a editor than getting the bytes one by one, but it often throws an error (no crash, don't worry), so use it with moderation!
num has to be a number between 0 and 'size(var)-3'.
*"setbyte:num,value,var"
Sets the byte number num of var to value.
num has to be between 0 and 'size(var)-3', value between 0 and 255.
*"komp:var"
Compresses variable var : it creates a variable of type KOMP, but smaller in size.
The function returns a number, who can take the following values :
*"dekomp:var"
Decompresses the compressed variable var.
The function returns a number, who can take the following values :
*"kinfo:var"
Returns the original type (see function 'getfile') and size of a KOMP variable.