BASIC! for Android

Graphics Commands

Version  11

5/24/2011

Changes from previous release

A new command, gr.bitmap.delete, has been added. This command deletes a bitmap and free up its memory.

The Graphics Screen and Graphics Mode

Graphics are displayed on a new screen that is different than the standard BASIC! text output screen. The text output screen still exists and can be returned to from the graphics screen using the Back Key. The gr.open command opens the graphics screen and puts BASIC! into the graphics mode. BASIC must be in graphics mode before any other graphics commands can be executed. Attempting to execute any graphics command when not in the graphics mode will result in a run time error. The Graphics mode automatically turns off when the BACK Key or MENU key is pressed. BASIC! will continue to run after the BACK key or MENU key is pressed. The BASIC! text output screen is hidden when the graphics screen is being displayed. . Run time error message will not be observable. A Haptic feedback alert signals a run time error. This Haptic  feedback will be a distinct, three short buzzes. Hit the Back Key to close the Graphics Screen upon feeling this alert.  The error messages can then read from the BASIC! text output screen. The gr.front command can be used to programmically swap the front most screen between the text output screen and the graphics screen. I recommend that your program always ends with the END command when doing graphics.  The END command displays END on the the output text screen. END shown on the output text screen gives notice that the program has correctly ended. If the program  has not stopped then it may be in a loop.  Hit Menu-Stop to stop the program.

Display Lists

BASIC! uses a Display List. The Display List contains all the graphics objects (circles, lines, etc) commanded to be drawn. The Display List objects will not be rendered on the screen when the "gr.render" command is called. Each draw object command returns the object's Object Number in the display list. This Object Number can be used to change the object on the fly. You can change any of  the parameters of any object in the display list with the gr.modify command. This feature allows you easily create animations without the overhead of having of recreating every object in the display list.

Color

Android colors consist of a mixture of Red, Green and Blue. Each of the colors can have values ranging from 0 to 255. Black occurs when all three values are zero. White occurs when all three values are 255. Solid Red would occur with Red having a value of 255 while Blue and Green are zero. Colors also have what is called an Alpha Channel. The Alpha Channel describes the level of opaqueness of the color. An Alpha value of 255 is totally non-opaque. No object of any color can show through an object with an Alpha value of 255. An Alpha value of zero will render the object  invisible.

Graphics Preparatory Commands gr.Open alpha, red, green, blue

Opens the Graphics Screen and puts BASIC! into the Graphics Mode. The color values become the background color of the graphics screen.

Gr.Color alpha, red, green, blue, fill

Sets the current color. The current color will be used for whatever graphics objects are newly drawn until the next color command is executed. The BASIC! color command has an additional parameter, fill. The fill parameter is applied to enclosed objects such as circles or rectangles. If fill is false (0) then any enclosed object using that color will be displayed as an out line of the object. If fill is true ( Not 0), then the enclosed object will be filled with the color.

Gr.Orientation mode

Forces the screen into Landscape or Portrait mode regardless of the the device's orientation. If mode = 0, Landscape mode will be forced. If mode<>0, Portrait mode will be forced.

Gr.Screen width, height

Returns the screen's width and height is the variables. This command should be executed after (not before) any gr.orientation command. This is because the gr.orientation command swaps the height and width.

gr.cls

Clears the screen of all objects by disposing of the current Display List. Creates a new Display List.  Any previous gr.color or gr.text{size|align|bold|strike|underline|skew} setting are reset. The "gr.render" command must be called to make the cleared screen visible to the user.

Gr.Close

Closes the opened graphics mode. The program will continue to run. The graphics screen will be removed. The text output screen will be displayed.

Gr.Front flag

Commands which screen, the graphics screen or the text output screen, will be the front most screen. If flag = 0, the text output screen will be the front most screen and seen by the user. If flag <>0. the graphics screen will be the front most screen and seen by the user. This command is very useful for getting input from the user while in graphics mode. Executing "gr.front 0" will cause the text output screen to be seen by the user. The INPUT command can thus be executed. When the input is received, executing "gr.front 1" while cause the graphics screen to be seen by the user. Note: When the text output screen is in front, you can still draw and render onto the graphics screen but the effects will not be seen until "gr.front 1" is commanded. The same is true in reverse.