TUTOR.TXT By Steven McGranahan(mcgrnhns@mc.net)

    +-------+     +---+  +---+     +-------+       +-----+       +------+
    |       |     |   |  |   |     |       |      /       \      |  +-+  \
    +-+   +-+     |   |  |   |     +-+   +-+     +   +-+   +     |  +-+  /
      |   |       |   |  |   |       |   |       |   | |   |     |      +
      |   |       |   +--+   |       |   |       +   +-+   +     |      \
      |   |       \         /        |   |        \       /      |   |\  \
      +---+        +-------+         +---+         +-----+       +---+ +--+
                         +-------+ +---+ +---+ +-------+
                         |       |  \   +   /  |       |
                         +-+   +-+   \     /   +-+   +-+
                           |   |      |   |      |   |
                           |   |     /     \     |   |
                        ++ |   |    /   +   \    |   |
                        ++ +---+   +---+ +---+   +---+

These tutorials are for mid to advanced programmers. If you want beginners
tutorials then goto qbasic.com or something.

Remember to visit the KAOS Soft-Ware home page:
http://user.mc.net/mcgrnhns/

Contents:
1. ARRAYS and DATA TYPES
2. GET and PUT
3. Subs and Functions
4. Last thoughts


1. ARRAYS and DATA TYPES
Arrays,
An array is a group of variables indexed by the same name. It's kinda like a
list containing many variables in an orderly fassion. Lets look at the
fallowing example:
'cut here
a$ = "Hello world"
b$ = "By by world"
c$ = "Die Scumbag"
d$ = "Kiss my @$$"
'end cut'

this program has four string variables. Here is where arrays come in,
'cut here'
DIM a$(1 to 4)
a$(1) = "Hello world"
a$(2) = "By by world"
a$(3) = "Die Scumbag"
a$(4) = "Kiss my @$$"
'end cut'

You see? All of thoes variables are stored in the same array. The number inside
the ()s is called the subscript, this number defines how the data is arranged
and stored. This can help you with many things. Consider the fallowing example:
'cut here'
monster1x% = 1
monster1y% = 1
monster2x% = 1
monster2y% = 1
monster3x% = 1
monster3y% = 1
monster4x% = 1
monster4y% = 1
monster5x% = 1
monster5y% = 1
monster6x% = 1
monster6y% = 1
'End cut'

This code stored the positions of mosters in 12 integer variables. This can be
cut way down to two arrays:
'cut here'
DIM monsterx%(1 to 6)
DIM monstery%(1 to 6)
'End Cut'

Ok now here is how to make mulit-indexed arrays(Just bare with me). Lets say
you want to make a tile rpg(and you have to make a map) how would you hold all
that map data? And whats worse is that the maps all have different sizes! Look
at the fallowing code(I say that alot don't I?):
'cut here'
x% = 80
y% = 50
dim map(x%, y%) as integer
'end cut'

In the example just given, the array had two subscripts that where defined by
two integers (x% and y%) x and y could be any other value and that's how big
the array would be. x% and y% could have been inputed from a file or something.
Note: Always use the '$DYNAMIC metta command when using arrays, there are many
reasons to do this but just trust me on this.

Data-Types,
Ok now that you understand why you need to make arrays and how, I have
something else to show you. Consider the fallowing example:
'cut here'
x% = 10: y% = 10
dim mapblock(x%, y%) as integer
dim blockname(x%,y%) as string * 4
'end cut'

How can you put these arrays together? They have different data types. The
answer is, user defined Data Types. Look at the fallowing:
'cut here'
x% = 10: y% = 10
TYPE map_parts
	block as integer
	name as string * 4
end type
dim map(x%, y%) as map_parts
'end cut'

Inside the Type/End Type markers we created "elements" to be used in our
arrays. An element can be any kind of data, INTEGER, LONG, SINGLE, DOUBLE and
STRING(All string elements must be fixed lenth e.g STRING * 4). The string is
four letters(bytes) long. This is grate but how do I access the elements inside
my arrays? Simple(using the arrays we have just defined):
'cut here'
map(1, 1).block = 10
map(5, 3).name = "HELL"
'end cut'

The elements have to be added to the end of the array like this:
array_name(subscripts).element_name
This has many very helpful uses but like I said before, just trust me and use
them (after a while you will se how useful they are).


2. GET and PUT (Graphics)

What is does,
The GET and PUT statements capture an image on the screen and store it in an
array(read 1.) the display the image on the screen. These statements create
what is often reffered to as a 'Sprite'. A sprite is nothing more than a flat,
square picture that is displayed in the screen.

How to use it,
DIM array%(size)
GET (x1, y1)-(x2, y2), array%
PUT (x, y), array%

size   - the size of the array(depends on the size of x1y1,x2y2)
x1,y1  - the upper-left corner of the sprite to get.
x2,y2  - the lower-right corner of the sprite to get.
x,y    - the screen position of the sprite(in plxies) to put.
array% - an integer array to store the sprite in(created by the DIM statement)

Some examples,
Ok, lets say you have a GIF or BMP file about 10x10 pixles big you want to
display on the screen so you load it using a GIF or BMP loader. Now how do you
make this sprite jump down on the screen 10 pixles? You could make another
GIF/BMP or you could use the GET/PUT statements(remember we have already loaded
a 10 by 10 image, or just create one on the top left corner of the screen):
'cut here'
DIM a1%(10)
GET (0, 0)-(9, 9), a1%
CLS
PUT (18, 19), a1%
'end cut'

But this code makes an error! Oh yeah :) you have to make sure the array is big
enough to hold the sprite! Try this code again but change the first line to:
DIM a1%(52)
Try this, it should work.

Now you are wondering "How do I figure out how big the array needs to be for
the image?!". Use this formula:
size = ((x_size * y_size) / 2) + 2

size is the size of the array to DIM
x_size is the size (left to right) of the sprite
y_size is the size (top to bottom) of the sprite

If you can't figure out how big your sprite is the just use these formulas:
x_size = x2 - x1
y_size = y2 - y1

That is about it. This is a somewhat confusing subject so if you have any
questions then e-mail me at: mcgrnhns@mc.net


3. Subs and Functions

Subs and functions are a vital part of more complex programs. I know that for
many subs and functions are a blur and they do not look that usefull.

First of all you need some theory behind the purpose of subs and functions...so
here it is: Subs and functions are like defignable qbasic commands. In other
words it gives you the ability to create commands for use in your programs.

"So that's grate and all but how do I make and use them?" you ask? Simple, first type:
SUB NewSub

After hitting return you will see a blank window. Don't worry you did'nt kill
you program..you just created a sub. The window should look like this:
SUB NewSub

END SUB

Move the curser to the empty line and start entering code:
locate 1, 1
print "My first QBasic sub!"
print "Is'nt this cool?"

Ok..Now press F2..A big window just poped up! Using the arrow keys select the
name of your program..Now you are back in the main section of your code.
Now type:
screen 0
call newsub ()

Run that program.
You see a sub is like a tiny program inside a program(that's where they get
thier name 'subs'). Ok. Now add some lines of code to that program:
'Cut here
screen 0
a% = 1
newsub

sub newsub ()
locate 1, 1
if a% = 1 then print "My first QBasic sub!"
print "Is'nt this cool?"
end sub

This should work! a% = 1, we assigned that value in the main program! Oh yeah..
I kinda just forgot. Sub programs are (as I said before) subs are like small programs...This means that it does not take variables from the main program.
Note: See how I did not use the call and () in my program? That is because it is not necessary to use this.

"Ok....Now what? Why would I use this insted of just typing that code inside of my main program and how can I pass variables to my subs?". Look at the fallowing code:
'Cut here
'New PSet.bas by Steven McGranahan
'KAOS Soft-Ware:
'http://user.mc.net/mcgrnhns/
declare sub NPset (x%, y%, pcolor%)
screen 13: def seg = &ha000
NPset 0, 0, 15
NPset 0, 1, 15
NPset 0, 2, 15
NPset 0, 3, 15
NPset 1, 1, 15
NPset 2, 0, 15
NPset 2, 2, 15
NPset 3, 3, 15
sleep 0: cls
end

sub NPset (x%, y%, pcolor%)
if x% >= 0 and x% <= 319 then 'Check the x% position
	if y% >= 0 and y% <= 199 then 'Check the y% position
		if pcolor% >= 0 and pcolor% <= 255 then poke x% + y% * 320&, pcolor%
	end if
end if
end sub
'End cut

NOW! Which would YOU rather do? Use the sub or have to type the sub out over
and over and over again? 
Note: the declare statement is created automaticly by QBasic.

And that is what a SUB is.

Functions:
Functions are just like subs accept that a value can be assigned to them. Look
at the next piece of code:
'Detect.BAS by Steven McGranahan
'KAOS Soft-Ware:
'http://user.mc.net/mcgrnhns/
declare function arrowkey%(i$)
declare sub clearinkey()
clearinkey 'Clears the inkey$ keyboard buffer
sleep 0: i$ = inkey$ 'Gets input from keyboard and stores it in i$
if arrowkey%(i$) = 1 then
? "Up has been pressed"
elseif arrowkey%(i$) = 2 then 
? "Down has been pressed"
elseif arrowkey%(i$) = 3 then 
? "Left has been pressed"
elseif arrowkey%(i$) = 4 then 
? "Right has been pressed"
end if

function arrowkey%(i$)
if i$ = chr$(0) + "H" then
	arrowkey% = 1
elseif i$ = chr$(0) + "P" then
	arrowkey% = 2
elseif i$ = chr$(0) + "K" then
	arrowkey% = 3
elseif i$ = chr$(0) + "M" then
	arrowkey% = 4
else
	arrowkey% = 0
endif
end fuction

sub clearinkey ()
do until inkey$ = "": loop
end sub

'End cut

Note: the '?'s will turn into PRINT when this program is run in QBasic.
Also note: the integer sign(%) at the end of the function name. This indicates the data type of the function.

Now do you understand subs and functions? That's all for now folks...

4. Last thoughts
If you have found this txt file helpfull then e-mail me: mcgrnhns@mc.net

And as always,
Get some KAOS:
http://user.mc.net/mcgrnhns/