Alfa
F.L. Addition v2.0a BETA
Copyright © 1999-2000 Alfaware.
Visit our homepage at http://www.alfaware.8m.com.
Please also visit Future Software at http://www.qb45.com.
Thank you for downloading the Alfa Future Library Addition. This version uses the Future.Library (available from Future Software) to support it's graphic reuqirements and to give you powerful new features! As the system is quite big, it seems right of me to write documentation on how to do things in AlfaFLA. So if you get stuck or don't feel like starting without reading a little about the system first, then read this. Also, you might notice that this guide is in the same style as the Future.Library guide, that's because I like the style of their guide! So many thanks to Future software...
This version of AlfaFLA (v2.0a BETA) was released at www.alfaware.8m.com on the Thursday, the 13th of July, 2000.
Main
Screens
Available
modes
Recommended settings
Setting
the color (automatic function)
Setting
the font
Setting
the mode
Windows
Creating
a window
Closing
a window
Drawing on a window
Giving the user control
Identification
and Identification Number
Moving
a window to the front
Moving
a window to the back
Resizing
a window
Retitling a window
Selecting a window
Graphical User Interface
Creating
gadgets (in general)
Creating
a button (sub parameters)
Creating a checkbox (sub parameters)
Creating radio gadgets (sub parameters)
Creating an input box (sub parameters)
Creating a close gadget (sub parameters)
Creating a maximize gadget (sub parameters)
Creating a depth gadget (sub parameters)
Creating
a horizontal slider (or scrollbar) (sub parameters)
Creating
a vertical slider (or scrollbar) (sub parameters)
Creating
a multi-slider (or multi-scrollbar) (sub parameters)
Giving the user control
Identification
and Identification Number
Removing any gadget
Selecting a radio gadget
Enhanced Disk Access
Changing
the current drive
Checking to see if a drive exists
Getting the current drive
Getting the current path
Getting the full drive and path
How to read the directory of a disk
Using the File Selector
Communicating with AlfaFLA
How to check which window is selected
How to check to see if a window has been clicked
on
How to check to see if a gadget has been clicked
on
How to check the mouse co-ordinates on a window (if
clicked on)
Enhanced Graphics
Vertical
Gradient (or shaded)
Horizontal Gradient (or shaded)
How to use texture and gradient presets
System Explanations
Activities
SUB
Controls
SUB
Initialise
SUB
NewImage% FUNCTION
PrefString$ FUNCTION
PrefVariable& FUNCTION
Miscellaneous
Detecting
collisions between two rectangular areas
Hiding
the mouse pointer
Showing
the mouse pointer
AlfaFLA v2.1 Questions
What new features will it offer?
When
will it be released?
Where do I get the Future.Library from?
Where
do I get it from?
When you install AlfaFLA (with install.exe) you will encounter a few problems. So here are the problems and how to solve them. =)
The first problem will most probably be something to do with where you installed AlfaFLA... make sure you install to where your Qb.exe program is, otherwise it will not function correctly because it cannot locate basic files such as Prefs.txt or Textures.bmp.
Another problem you may encounter is Qbasic reporting "Out of memory". If this does happen, open the Prefs.txt file and lower the Maximum variables. This will decrease memory requirements. The Layers can be worked out generally as MaximumLayers=MaximumWindowsx4+8 - to be on the safe side!
Qbasic may report "Bitmap not found". This could be caused by a bitmap not existing, but something referring to it, or it does exist but the File Selector has been used and the main path has been changed - meaning if you have just enter "mypic.bmp" then it will not find it. Dunno how to solve this one... Any ideas? =(
The last problem I can imagine you encountering, is either "VESA could not be found" or the mouse does not work. Either way, they are Future.Library problems. If you have problems with your computer and the Future.Library then please, please report them!! It is very important that people know bugs in their software.
Although the Future.Library supports lots of different modes, there didn't seem to be much point of including support for all of them. So, rather than wasteing our time adding support for modes that nobody is going to use, we selected the most typical modes. Although, please note, we did not put any restrictions on the color depth (8 bit, 15 bit, 16 bit, 24 bit, 32 bit).
These are the available modes:
SVGA: 640x350xDepth
SVGA: 640x400xDepth
SVGA: 640x480xDepth
SVGA: 800x600xDepth
SVGA: 1024x768xDepth
SVGA: 1280x1024xDepth
SVGA: 1600x1200xDepth
The screen mode is determined by text data in the Prefs.txt file. Load notepad and open the Prefs.txt file and edit it according to what you require.
Some screen modes may not be directly supported by your video card. For these modes to work you will need the UniVBE driver developed by Scitech. The newest version of the driver can be found at www.scitechsoft.com.
We recommend that you use an 800x600 screen, on either 15 bit, 16 bit or 24 bit (if supported). 15 bit should be the minimum used by any computer, as it makes finding colors close to those you want very easy. I have found that I could only use 15 bit graphics, as 16 bit goes down to 15 it and 24 bit goes down to 8 bit. Sorry guys if it's the same for you!
As selecting colors is something not everybody knows how to do in the Future.Library, we have decided to make a new function called AutoColor&. To use this, you must provide the amount of red, green and blue you want in your color. For example:
Color1& = AutoColor&(255,
255, 255) is white
Color2& = AutoColor&(0, 0, 0) is black
Color3& = AutoColor&(255, 0, 0) is red
Color4& = AutoColor&(0, 255, 0) is green
Color5& = AutoColor&(0, 0, 255) is blue
The Future.Library offers three different sizes of font. You can either load your own font, which I do not document upon here, or you can use the Future.Library default font - but size 8, 13 or 14. To set your font, edit the Prefs.txt file and change the FontSize variable to match the font size you require.
There are two different ways of setting the screen mode. If you do not want to give the user control over the screen mode, then you can alter the "SetScreen Width, Height, Color Depth" sub within the source code. But if you do want to give the user control over the screen mode, then leave the SetScreen function as it is and edit the ScreenWidth, ScreenHeight, and ScreenDepth variables in the Prefs.txt file.
Once AlfaFLA has finished initialising (which it will do if there are no problems) then Windows can be opened. A rule that should always be followed is that you never create a window before the initialising has finished. You should also only open your windows after the Desktop has been created; which is always the first window. =)
I have made creating a window of great ease, all you need to do is pick a identification number (like Win1%) and an identification up to 10 characters long (like "mywindow" or "maximum10!") - make sure there are no spaces in the windows identification. Then you use this like and replace the appropriate headings with the information...
Identification Number = DefWindow%("Title", "Identification", X, Y, Width, Height, Gadgets)
The Gadgets heading should be replaced with a binary solution. But to make it easier, I have made it so you can just add together variables. So if you want a close gadget and a maximize gadget then you replace the Gadgets with GadClose% + GadMax%. These are the other variables:
GadClose% - Close gadget
GadMax% - Maximize gadget
GadMin% - Minimize (or depth gadget)
GadSize% - Sizer
GadAutoSize% - Makes your Width and Height the total space inside
the window's outside bars.
The simplest way to close a window is to use the provided sub; which is CloseWindow Identification. Replace the Identification with your window's variable (like Win1%). All the gadgets will be removed and memory will be freed.
Because windows use EMS, the best way to alter one's image is to use the EMS buffer routines. The SetEMSwin sub makes this easy for you, have a look at the following code and use it as you require:
SetEMSwin Identification
SetEMSpage 0
'/* Do your image editing here! */
SetPage 0
'/* Now redraw the part of the window you want (X, Y, Width and
Height is the area of the window for redrawing) */
Redraw Wind(Identification).X + X, Wind(Identification).Y
+ Y, Width, Height
Yet again, something easy. To give the user control over the windows and the GUI, you have to run a sub called Controls. This sub will automatically check to move windows, resize them, use gadgets and anything else that goes under the category of user control. The Controls sub should also be featured in main loops (like in a game, you will require it in the main loop where controls are picked up).
Identification and Identification Number
The Identification and Identification Number are two different things which represents the same thing. The Identification Number will be the more accurate as it will always be unique (because it is specified by AlfaFLA itself), but the Identification can be much more useful - especially for gadgets which means you can have simple Identifications like "ok" and "cancel".
When you define something, it will always be defined by a function. And somewhere in the functions parameters is the Id$, which you must replace with an identification up to 10 characters long. So, generally, each definition function is like this:
Identification% = Def......%(......, Id$, ......)
Another simple and effective sub, WinToFront Variable. Replace the Variable with the window's number and it will be pushed in front of all the other available windows.
Another simple and effective sub, rather like WinToFront, but WinToBack Variable. Replace the Variable with the window's number and it will be pushed behind all of the other available windows, but not behind the Desktop window.
Resizing a window is very easy indeed. The ResizeWindow sub deals with the hard bits, you just have to enter the information and attributes you want for the window. Replace them as follows:
ResizeWindow Identification, Width, Height, Attributes.
The Attributes might have the GadAutoSize% within it, include it if you want the Width & Height to be the area within the window's outer bars.
If your window title needs to be replaced, then it is easily done with the RetitleWindow sub. Replace the variables and strings as follows:
RetitleWindow Identification, Title$
When you want a window to become important, you'll often require to move it to the front and have it automatically selected - hence moving the users focus on to the particular window. Yet again, it is easily done with the SelectWin sub! Just replace the variables as follows:
SelectWin Identification
A gadget is anything like a button, or a close gadget. Before you can use a gadget, it has to be defined (just like you define a window before it appears). All you need do is replace the variables and strings with what you require then they will function correctly.
Also notice that the Hole% is either equal to True% (for a hole) or False% (for no hole). When creating sliders (or scrollbars) you will need to know about the units, draglen and position for the variables. The units are the amount of items on the list (or pixels), the draglen is the amount of items or pixels visible, and the position is the position the draggable bar should go (if 5 items or 5 pixels down the list then you make position equal 5).
Creating a button (sub parameters)
Replace and use:
Identification% = DefButton%(Window Identification, Title$, Id$, X, Y, Width, Height, Hole%)
Creating a checkbox (sub parameters)
Active% should be False% if the checkbox is not checked, and True% if it is checked.
Replace and use:
Identification% = DefCheckbox%(Window Identification, Text$, Id$, X, Y, Width, Height, Active%, Hole%)
Creating radio gadgets (sub parameters)
Grp$ will allow you to specify which radio gadgets are linked (if two have the same Grp$ then if one is pressed the other one will pop out). The Active% variable is False% is the new radio gadget is not pushed in, and True% if it is pushed in - any pushed in radio gadgets with the same Grp$ will be automatically pushed out when this is created.
Replace and use:
Identification% = DefRadio%(Window Identification, Title$, Id$, Grp$, X, Y, Width, Height, Active%, Hole%)
Creating an input box (sub parameters)
Replace and use:
Identification% = DefInput%(Window Identification, Text$, Id$, X, Y, Width, Height, Hole%)
Creating a close gadget (sub parameters)
Replace and use:
Identification% = DefCloseGad%(Window Identification, Id$, X, Y, Width, Height)
Creating a maximize (sub parameters)
Replace and use:
Identification% = DefMaxGad%(Window Identification, Id$, X, Y, Width, Height)
Creating a depth gadget (sub parameters)
Replace and use:
Identification% = DefMinGad%(Window Identification, Id$, X, Y, Width, Height)
Creating a horizontal slider (sub parameters)
Replace and use:
Identification% = DefHSlide%(Window Identification, Id$, X, Y, Width, Height, Units!, Draglen!, Position!, Hole%)
Creating a vertical slider (sub parameters)
Replace and use:
Identification% = DefVSlide%(Window Identification, Id$, X, Y, Width, Height, Units!, Draglen!, Position!, Hole%)
Creating a multi-slider (sub parameters)
A multi-slider will automatically drag two other sliders (one vertical and one horizontal) when pressed, held and dragged. Although it is only really a button (does not move itself), it could be made to be very useful. VSlide% is the vertical slider's identification that you would like to link to the multi-slider, and HSlide% is the horizontal slider's identification that you would like to link to the multi-slider.
Replace and use:
Identification% = DefMSlide(Window Identification, Id$, X, Y, Width, Height, VSlide%, HSlide%, Hole%)
When you need to delete a gadget, you should use DeleteGadget Identification Number, Identification. You can provide either of the parameters, as long as you provide one of them.
After you have created a radio gadgets group, you may need to select one of the gadgets in that group. Use the SelectRadio sub. Replace and use as follows:
SelectRadio Win%, Gad%, Grp$
To change the current drive (ie. "C:", "D:" etc.), use ChangeDrive Drive$. Replace Drive$ with the drive that you require.
Checking to see if a drive exists
If you would like to know whether or a not a drive is actually there, you can check it using LogicalDrives%(Drive$). Replace the Drive$ with the drive of your choice. Remember that it is only the letter that should be put in to Drive$, not the ":" or anything else.
This is easy, replace and use:
A$ = CurrentDrive$
This is easy as well, replace and use:
A$ = CurrentPath$
Getting the full drive and path
This is basically CurrentDrive$ + ":\" + CurrentPath$. But it makes it that bit easier... Replace and use:
A$ = RealPath$
How to read the directory of a disk
Although I'm sure many people could figure this one out themselves, I'd prefer to explain still just for those people who can't. The GetDir sub reads any directory on any available disk, it also checks to make sure the drive is read - otherwise your computer will freeze. This is how you use it...
GetDir DirNum%, Path$, Status%
Firstly, do not CALL this sub, just do it as it says above. Choose any variable for DirNum% and Status%, and enter the path in to Path$. When the sub returns, DirNum% will tell you how many files & directories there are (-1 is there are none) and Status% will tell you if any problems occured while attempting to read the directory.
When the directory is read, all of the files will be put in to an XMS array function called GetFileList$(DirNum%). The first file or directory name will start at FileList$(0). Remember this, do not make the mistake of missing one whole file or directory. Copy and use:
A$ = GetFileList$(DirNum%)
Yes!! It's true!!
AlfaFLA comes with it's own File Selector making selecting files
much much easier for you and the user. =)
It's a function which makes it a little easier to find your
result. The File$ can be nothing, and so can the Path$, but if
File$ is something then if that file is in the file list it will
be automatically selected. There is also a minimum width and
height for the file selector. And if you put -1 in to X or Y,
then that co-ordinate will automatically centre. Replace and use:
MyFile$ = FileSelector$(Title$, X, Y, Width, Height, File$, Path$)
How to check which window is selected
You can check to see which window is selected by looking at the variable CWin%. It will equal the currently selected window's identification number. If it is equal to DesktopWindow% then the desktop is selected.
How to check if a window has been clicked on
After the Controls sub has finished, the following will be returned:
DirectWindow%
DirectWindowId$
The DirectWindow% is equal to the clicked on windows' identification number, and DirectWindowId$ is equal to the clicked on windows' identification. If DirectWindow% is equal to -1, then no window was clicked on.
How to check if a gadget has been clicked on
After the Controls sub has finished, the following will be returned:
DirectGadget%
DirectGadgetId$
The DirectGadget% is equal to the clicked gadgets' identification number, and DirectGadgetId$ is equal to the clicked gadgets' identification. If DirectWindow% is equal to -1, then no gadget was clicked.
How to check the mouse co-ordinates on a window (if clicked on)
After the Controls sub has finished, the following will be returned:
DirectWindowXM%
DirectWindowYM%
DirectWindowXM% is equal to that of the mouse X co-ordinate on the window, and DirectWindowYM% is equal to that of the mouse Y co-ordinate on the window.
The AlfaFLA has advanced graphics which you can use - this includes gradients. Gradients are bars where one color will fade to another color. This is called 'shaded' in many cases, but I prefer calling it 'gradient'. It is very easy to use, and will most probably be of great use to you. Replace and use:
GradientV X, Y, Width, Height, Red A, Green A, Blue A, Red B, Green B, Blue B
Horizontal gradient (or shaded)
The AlfaFLA has advanced graphics which you can use - this includes gradients. Gradients are bars where one color will fade to another color. This is called 'shaded' in many cases, but I prefer calling it 'gradient'. It is very easy to use, and will most probably be of great use to you. Replace and use:
GradientH X, Y, Width, Height, Red A, Green A, Blue A, Red B, Green B, Blue B
How to use texture and gradient presets
Gradients, textures and colors can be pasted in a rectangular area using one sub, the FillArea sub. Firstly, you need to know how to select what you are going to use. For a color, use AutoColor&(Red, Green, Blue). For a texture, you can choose a number between 1 and 20, but make it negative - so it's -1 to -20. For a gradient, you must use -21 and below. Textures and gradients are preset, because they be changed - but colors will always be the same.
The Origin X and Origin Y variables only apply to the textures. If you move the FillArea X and Y co-ordinates around, you will notice that the textures always start from the X and Y. If you increase Origin X and Origin Y then the textures will be shifted around by the value you give them.
Replace and use:
FillArea X, Y, Width, Height, Origin X, Origin Y, Inner, C&
The Activities SUB runs internal system components or internal program components. If you make software, and you find something that needs to be done all the time then you can use the Activities SUB to repeatitevly perform the task. One such example is the Future.UpdateMouse that is required to keep the mouse pointer moving with the mouse.
The Controls SUB gives control to the user. While in progress, it checks for user actions and responds to them appropriately - this is how all of the windows and gadgets are given function. This SUB is required in most main loops, any loop requiring user activity must have this SUB.
It seems vital to tell you what this SUB does. The Initialise SUB initialises some of the system components; hence it's name!
If you require to make an EMS image of any kind, then use this FUNCTION. It will define an image of any size (according to the screens color depth) and return the image memory reference. For more information on how to draw on to your images, please refer to the Future.Library help file. Replace and use:
A% = NewImage%(Width, Height)
When the Prefs.txt file is loaded, the variables and strings are stored in an array. This array might hold some information you want. If it does, then you can retrieve the information using PrefString$. For example, to retrieve the backdrop bitmap that the Prefs.txt file refers, you would replace String name with backdrop - as it stated in the Prefs.txt file. Replace and use:
A$ = PrefString$("String name")
When the Prefs.txt file is loaded, the variables and strings are stored in an array. This array might hold some information you want. If it does, then you can retrieve the information using PrefVariable&. For example, to retrieve the screen width that the Prefs.txt file refers, you would replace Variable name with screenwidth - as it stated in the Prefs.txt file. Replace and use:
A& = PrefString&("Variable name")
Detecting collisions between two rectangular areas
If you find that you need to see if two areas (rectangular) collide then you can use the Collide function. Each set of co-ordinates and sizes is one area. Replace and use:
A% = Collide%(X, Y, Width, Height, X 2, Y 2, Width 2, Height 2)
To be System Friendly with your programs, you should hide the mouse pointer to correct way. To hide the mouse pointer, simply use the sub HideMouse.
To be System Friendly with your programs, you should show the mouse pointer to correct way. To hide the mouse pointer, simply use the sub ShowMouse.
What new features will it offer?
The Autolayout System is going to be the main new feature of AlfaFLA v2.1, and again - it's free!
We are hoping that the next release is in less than two months.
Where do I get the Future.Library from?
The Future.Library can be downloaded for free from Future Software's webpage at www.qb45.com. It is required to use the Alfa Future.Library Addition and is also a very highly recommended library for most everyday tasks in Qbasic.
Either the Alfaware website (www.alfaware.8m.com) or the Dimension SOFT website (www.kiwikid.com).