---------------------------------------------------------
The Liberty Basic Newsletter - Issue #93 - FEB 2002
    2002, http://groups.yahoo.com/group/lbnews/
             All Rights Reserved
---------------------------------------------------------
"Apparently there is nothing that cannot happen today."
                                      - Mark Twain
---------------------------------------------------------
In this issue:
	A new direction for the newsletter.
	Contest Update
	Introducing Liberty BASIC 3!
	Updating the Open Source Editor
	Tip Corner... COLORDIALOG
	Callbacks Explained
	Drag 'n' Drop API Functions
	Drag 'n' Drop in LB3 by Mitchel Kottler
	Spotlight - the Gnu/Liberty BASIC Compiler System
	                by Anthony Liguori
		    - LB2BCX
---------------------------------------------------------
A NEW DIRECTION FOR THE NEWSLETTER

With the publication of this issue, the [lbnews] Yahoo 
Group is returning to its original format, as a 
forum for distribution and discussion of The Liberty BASIC
Newsletter.  Feel free to post comments, corrections,
suggestions and questions about the newsletter here.

For a general discussion forum, be sure to check out the
official Liberty BASIC Yahoo Group:
http://groups.yahoo.com/group/libertybasic/

For discussion of the beta test version of LB3:
http://groups.yahoo.com/group/lb3beta/

For discussion of the more complex aspects of 
LB programming:
http://groups.yahoo.com/group/lbexp/

The FILES area now contains archives of all past 
newsletters for download.

The Liberty BASIC Newsletter is always looking for
submissions and articles to publish.  Send them to 
alycewatson@charter.net  Articles submitted within one 
week of the publication date may be held over for 
inclusion in the next months's newsletter.

You don't need to be an expert to contribute an article!
Articles can be about anything that would be of interest
to Liberty BASIC programmers, including, but not limited to:

- explanations of Liberty BASIC commands
- demonstration routines
- information on API functions
- showcase on programming tools such as image editors,
      sound recorders, install programs, etc.
- in-depth discussion of LB program creation utilities,
      such as Freeform.
- information about add-on DLLs
- algorithms
- informational resources for programmers
- serial communications
- creating games
- file handling
- multimedia in LB
- dates and calenders
- converting code from another language to LB syntax
- window and control manipulation via API
- creating applications for public distribution
- open source projects
- Programmer's Spotlight on an LB programmer
- FAQ's
- tips and tricks
- using math and trig functions
- program design
- database programming
- website review of a notable LB-oriented website
- Blue Ribbon Programs - reviewing the best programs
      written in Liberty BASIC
- using the new features of LB3
- debugging your code
---------------------------------------------------------
CONTEST UPDATE

Don't forget to log in to the lbnews website and cast
your votes in the Liberty BASIC Oddyssey Contest!
Polls close on February 15, and winners receive their
choice of LB registration or T-shirt and mug, provided
by Carl Gundel.

There will be a new contest starting shortly.  Please
post suggestions and comments about the format, duration,
categories, rules, etc. here!

---------------------------------------------------------
INTRODUCING LIBERTY BASIC 3!

Liberty BASIC 3 is for Windows 95+ and it is now 
available for public beta testing.  It has many
exciting new features.  If you haven't tried it yet, be 
sure to visit the Liberty BASIC website and download
the latest beta test version:
http://www.libertybasic.com/

Beta test versions compile a limited amount of code and
they expire approximately two weeks after their release.
You can avoid these limitations by registering Liberty
BASIC 3 right now.  You can purchase a full registration,
or you can get a discount.  If you have registered a
previous version of Liberty BASIC you may purchase the 
upgrade, which gives you a registration at a reduced fee.

Join in discussions, make comments and report bugs here:
http://groups.yahoo.com/group/lb3beta/

New features of Liberty BASIC v3.0 include:

- New 32-bit engine!
- 3x faster (even faster for some things)!
- Make 32-bit API calls and use 32-bit DLLs!
- Long filename support!
- Colordialog support!
- IDE toolbar buttons for print, search+replace, and release notes.
- Added the ability to use a Windows bitmap handle with the loadbmp
      command
- Tweaked the visual appearance of borders on some controls
- Added an inputto$(#handle, delim$) function 
- Modified the using() function so that it rounds its output 
- Added a squareroot function sqr()
- Adds a shorthand for printing to handles.  Now you can omit the
      PRINT statement and the comma 
- Added a callback statement 
- Added select/case, with support for multiple cases, separated 
      by a comma and for nested select case statements
- Added compiler reporting.  
- Added EXIT FOR and EXIT WHILE commands.
- Added tooltips to the editor and debugger windows.
- Added Lite Debug
- For/next change.  Now next does not require a variable
- Tabbing supported in non-dialog windows

---------------------------------------------------------
---------------------------------------------------------
UPDATING THE OPEN SOURCE EDITOR

API CALLS
To make the Open Source Editor LB3 compliant, it is necessary
to change all API calls.  The first step in doing that is to
change the DLL names in the "open" statement.  For 32-bit use,
we must open "user32", "shell32", "kernel32", "gdi32", "comctl32",
and so on.  It is also necessary to change many of the type 
parameters used in the calls.  Most "shorts" will be changed to
"longs" for instance.  Previously, there was no boolean type, so 
we used ushort in its place.  Now we may use boolean where needed.
In addition, some function calls have changed their names.  This
occurs for calls that have a text (ptr) parameter.  The function 
name gains a final "A", which stands for "ascii".  In this program, 
we changed the API calls for ShellExecuteA, SetWindowTextA,
and ModifyMenuA.

Another notable update is the change in the tooltip routine.
For the original explanation of tooltips in the Open Source
Editor, please see The Liberty BASIC Newsletter, Issue #60.
In addition to changing some types and changing the function name
from "SendMessage" to "SendMessageA", we are able to streamline
the code quite a bit.  For some reason, in 16-bit Liberty BASIC,
it was necessary to have a separate struct for each tooltip.  That
duplication is no longer needed.  A single struct suffices for all
tooltips.  The general members of this struct need to be filled
only one time.  The struct members specific to each tooltip are
filled just before we send a message to add a tool.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
    '** LB3 NOW ONLY REQUIRES A SINGLE STRUCT
    '   FOR ALL TOOLTIPS
    struct toolinfo, cbSize as long, uFlags as long,_
        hwnd as long, uId as long, x as long, y as long,_
        w as long, h as long, _
        hInst as long, lpstrText$ as ptr

    'THESE STRUCT MEMBERS ONLY NEED TO BE FILLED ONCE:
    toolinfo.cbSize.struct = len(toolinfo.struct)
    toolinfo.uFlags.struct = TTF.IDISHWND or TTF.SUBCLASS
    toolinfo.hwnd.struct = h

    'THESE STRUCT MEMBERS NEED TO BE FILLED ANEW
    'FOR EACH TOOTLIP ADDED:

    toolinfo.uId.struct = hwnd(#1.new)
    toolinfo.lpstrText$.struct = "New File"
    calldll #user, "SendMessageA", hwndTT as long,_
    TTM.ADDTOOL as long, 0 as long,_
    toolinfo as struct, re as long


    toolinfo.uId.struct = hwnd(#1.open)
    toolinfo.lpstrText$.struct = "Open File"
    calldll #user, "SendMessageA", hwndTT as long,_
    TTM.ADDTOOL as long, 0 as long,_
    toolinfo as struct, re as long
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

More changes: 

* removed code library, which was LB2 syntax
* fixed look of array maker for LB3
* changed bmp dimension functions for bmp previewer
* fixed drawing bmpbutton for LB3 - added fill 
	and backcolor of buttonface
* condensed font commands for controls in bmp previewer
* added pen color tattletale to bmp previewer
* changed color choice in bmp previewer to colordialog
* removed help-tutorial menu and button
* removed dummy EDIT menu
* changed helpfile engine to winhlp32

In previous versions of Liberty BASIC, we ran Windows
Helpfiles like this (the exe extension is assumed if
it is not included):

run "winhelp.exe myhelp.hlp"
or
run "winhelp myhelp.hlp"

We now use the 32-bit help engine:

run "winhlp32.exe myhelp.hlp"
or
run "winhlp32 myhelp.hlp"

The updated Open Source Editor for LB3 is attached
as source code and as a tkn.

---------------------------------------------------------
TIPCORNER - COLORDIALOG

We've taken advantage of the new colordialog in LB3 for
the updated Open Source Editor.  The syntax is:

colordialog color$, chosen$

The parameter color$ can be an empty string, but it must be 
included.  The color chosen by the user is contained in the 
variable, chosen$ after the dialog is closed.  The input 
parameter may be in one of two forms.  It can be a named 
Liberty BASIC color, or a string containing the red, green, 
blue values of the desired color with which to seed the 
colordialog.  Remember that this is a string, and that the
values are NOT separated by commas.

color$="red"
or
color$="255 0 0"
colordialog color$, chosen$

The color specification can be placed directly into the 
colordialog:

colordialog "red", chosen$
or
colordialog "255 0 0", chosen$

Red, green and blue values must each be in the range of 0 to 255.  
0 is the absence of a color, and 255 is total saturation.  The 
RGB for red is 255 0 0, while blue is 0 0 255.  Black has an 
RGB of 0 0 0, and white is 255 255 255.  Any RGB where the values
for red, green and blue are equal will be a shade of gray.  Example:
RGB 127 127 127.

If the user chooses a named, Liberty BASIC color, then chosen$ 
will contain both the red, green, blue values and the name.  
If the chosen color is not a named color, then the return will 
contain only the red, green and blue values:

color$="255 0 0"
colordialog color$, chosen$
print chosen$

'will print RGB and name for a named color

255 255 0 yellow

'will print RGB only for a non-named color:
250 230 190

The colordialog opens to the simple view, allowing the user to
choose a color from one of the standard color boxes.  The user
can click the button "Define Custom Colors" to open the panel
that provides access to all possible RGB combinations.

Here is a little demo to help you parse the returned string.
The first word$() in the string will be the red value.  The
second word$() will be the green value and the third word$()
will be the blue value.  If there is a fourth word$(), it will
be the Liberty BASIC named color.

color$="52 202 113"
colordialog color$, chosen$

print "Red is ";word$(chosen$,1)
print "Green is ";word$(chosen$,2)
print "Blue is ";word$(chosen$,3)

if word$(chosen$,4)<>"" then
    print "Name is ";word$(chosen$,4)
end if

If you are going to fill a graphicbox with the color chosen by
the user, then check for the fourth word$().  If it exists, then
the command will look like this:

print #1.gbox, "fill ";word$(chosen$,4)

If the user didn't choose a named color, then make a color out
of the red, green and blue.

color$=word$(chosen$,1)+" "+word$(chosen$,2)+" "+word$(chosen$,3)

print #1.gbox, "fill ";color$

---------------------------------------------------------
CALLBACKS EXPLAINED

Callbacks require Liberty BASIC 3.

Callbacks are one of the more complex aspects or Liberty 
BASIC programming.  If you are new to programming, or if you
do not have a thorough knowledge of making API calls, then
you might want to put this article away for future consideration.

A 'callback' is the address of a program function that is used 
as a parameter in API call.  The API function contacts your
program's function and sends it information, in the form
of a parameter list.  Your program's function then performs
the desired action.  Your program's function may make use of
the parameters in the list.  When your program's function is
finished, it should return a value to the calling function.
If it returns 0, the calling function will stop itself from
running and return control to your program.  Your program's
function should return nonzero if it wants to let the API 
function to continue to execute.

API calls with "Enum" in their names generally require
callbacks.  These functions will enumerate some system
entities, sending the list to your function one at a time.
Your function processes each of these items as they are
sent to it by the API function.  When the input parameters
from the API function give no further information to your
program's function, or when your program has processed some
set maximum number of items, then it returns 0 to the calling
API function to cause the API function to quit execution and
return control to your program.


The syntax is:

callback addressPTR, functionName(type1, type2...), returnValue

Usage:

addressPTR - assigns a name to the memory address of the function.
	This memory address will be passed into the API function
	that requires a callback.  

functionName - is the name of the function in the Liberty BASIC 
	program that will be called by the API function.  

(type1, type2...) - a comma-separated list of parameters, which will be 
	specific to the function used.  The parameters must be valid data 
	TYPES such as "ulong" and "long".  API functions require different 
	numbers of parameters, depending upon the individual function.

returnValue - the type of return value is listed after the closing 
	parenthesis.  The Liberty BASIC function may return a value to 
	the calling function.  Some calling functions evaluate this
	return, and when YOUR function returns 0 to the calling
	function, it stops itself from running and returns control
	to your program.

Some API functions that require callbacks:
	EnumChildWindows
	EnumFontFamilies
	EnumWindows
	EnumPrinters

Look in the documentation provided by Microsoft in its Software
Developers Kits or on the MSDN to discover the correct format
for the function your program must provide for the API function.
The functions you must provide for the above sample list are:

	EnumChildWindowsProc
	EnumFontFamiliesProc
	EnumWindowsProc
	EnumPrintersProc

For a working example of using an Enum Function with a callback,
see the LB3 helpfile "EnumWindows" example in the CALLBACK 
section.

Here is a generic program to demonstrate callbacks.  This
is NOT a REAL program!

'generic, non-working code example:
texteditor #win.te, 10, 10, 250, 250
open "Enum Something Example" for window as #win
print #win, "trapclose [quit]"

'set the variable named address to be the memory address for
'EnumSomethingProc() using types long and ulong, and set
'the return type of EnumSomethingProc() to be a boolean

callback myAddress, EnumSomethingProc(long, ulong), boolean

open "mydll" for dll as #dummy

'call EnumWindows, which in turn calls back into the
'BASIC function at address.

calldll #dummy, "EnumSomething", _
    myAddress as ulong, _
    0 as long, _
    result as boolean

close #dummy

wait

[quit]
close #win
end

function EnumSomethingProc(wParam, lParam)
    print #win.te, "wParam is ";wParam
    print #win.te, "lParam is ";lParam

    'check conditions to choose a return
    'value based upon the param list values
    'returning 0 causes EnumSomething to 
    'return control to the program

    if lParam=0 or wParam=0 then
        EnumSomethingProc = 0   
      else
        EnumSomethingProc = 1
    end if

    'if your program returns nonzero to
    'EnumSomething, then it will continue
    'running and send your function
    'another callback and list of params.

end function

Callbacks are required for the wmliberty.dll which is used
in the Drag 'n' Drop example later in the newsletter,
written by Mitchell Kotler.

---------------------------------------------------------
DRAG 'N' DROP API FUNCTIONS

This technique is for use with Liberty BASIC 3. 

These functions are part of shell32.dll.  They are used
in the drag 'n' drop examples explained by Mitchel
Kotler later in the newsletter.  This technique is for
more experienced Liberty BASIC programmers.  It requires
a thorough knowledge of API calling in LB.  It also
requires the wmliberty.dll, which requires callbacks.


DragAcceptFiles
***************
Syntax:

calldll #shell32, "DragAcceptFiles",_
hWnd as long,_      'handle to the registering window
fAccept as boolean, 'acceptance option
ret as void

The DragAcceptFiles function registers whether a window 
accepts dropped files. 

- hWnd
Identifies the window registering whether it accepts 
dropped files. 

- fAccept
Specifies whether the window identified by the hWnd 
parameter accepts dropped files. This value is TRUE to 
accept dropped files; it is FALSE to discontinue accepting 
dropped files.  (Editor's note:  In the examples by Mitch,
this parameter is passed as a short.  It should be
passed as boolean.)

- Return Values
This function does not return a value. 

Remarks
An application that calls DragAcceptFiles with the fAccept 
parameter set to TRUE has identified itself as able to 
process the WM_DROPFILES message from File Manager. 


DragQueryFileA
**************
Syntax:

calldll #shell32, "DragQueryFileA",_
hDrop as long,_    'handle to structure for dropped files
iFile as ulong,_   'index of file to query
lpszFile$ as ptr,_ 'buffer for returned filename
cch as ulong,_     'size of buffer for filename
ret as ulong


The DragQueryFile function retrieves the filenames of 
dropped files.

- hDrop
Identifies the structure containing the filenames of the 
dropped files. 

- iFile
Specifies the index of the file to query. If the value of 
the iFile parameter is 0xFFFFFFFF, DragQueryFile returns a 
count of the files dropped. If the value of the iFile parameter 
is between zero and the total number of files dropped, 
DragQueryFile copies the filename with the corresponding 
value to the buffer pointed to by the lpszFile parameter. 

- lpszFile$
Points to a buffer to receive the filename of a dropped 
file when the function returns. This filename is a 
null-terminated string. If this parameter is NULL, 
DragQueryFile returns the required size, in characters, 
of the buffer. 

- cch
Specifies the size, in characters, of the lpszFile buffer. 

- Return Values
When the function copies a filename to the buffer, the return 
value is a count of the characters copied, not including the 
terminating null character. If the index value is 0xFFFFFFFF, 
the return value is a count of the dropped files.  If the 
index value is between zero and the total number of dropped 
files and the lpszFile$ buffer address is NULL, the return 
value is the required size, in characters, of the buffer, 
not including the terminating null character. 


DragQueryPoint
**************
syntax:

struct point, x as long, y as long

calldll #shell32, "DragQueryPoint",_
hDrop as long,_    'handle to structure for dropped file
point as struct,_  'pointer to structure for mouse coordinates
result as boolean

The DragQueryPoint function retrieves the position of 
the mouse pointer at the time a file was dropped. 

- hDrop

Identifies the structure describing the dropped file. 

- point
Points to a POINT structure that the function fills with 
the coordinates of the mouse pointer at the time the 
file was dropped. 

- Return Values
If the drop occurred in the client area of the window, 
the return value is nonzero.  If the drop did not occur 
in the client area of the window, the return value is zero. 
(Editor's note:  in Mitch's example, this is improperly
passed as a ulong.  It should be a boolean.)

Remarks

The DragQueryPoint function fills the POINT structure with 
the coordinates of the mouse pointer at the time the user 
released the left mouse button. The window for which 
coordinates are returned is the window that received 
the WM_DROPFILES message.  In LB3, this is provided by
the wmliberty.dll.


DragFinish
**********
Syntax:

calldll #shell32, "DragFinish",_
hDrop as long,_  'handle to memory to free
result as void

The DragFinish function releases memory that Windows 
allocated for use in transferring filenames to the 
application. 

- hDrop
Identifies the structure describing dropped files. 
This handle is retrieved from the wParam parameter 
of the WM_DROPFILES message.  In LB, this is
furnished by the wmliberty.dll.

Return Values

This function does not return a value. 

---------------------------------------------------------
DRAG 'N' DROP IN LB3

(* Editor's note:  this technique requires LB3 and uses  *)
(* callbacks.  Callbacks are explained in detail above.  *)
(* The API calls for drag 'n' drop are also explained in *)
(* detail above.                                         *)
(* This technique also requires the wmliberty.dll by     *)
(* Brent Thorn, which will be spotlighted in a future    *)
(* newsletter.  This DLL is still under development.     *)
(* An early version of the DLL is supplied with this     *)
(* newsletter to be used with the drag 'n' drop demos.   *)


LB Drag n Drop
by Mitchell Kotler smartestmanal1ve@netscape.net
http://xenolith4.tripod.com/new/index.html

Version of LB required for this Article:
LB3

Files that go with this Article:
dnd1.bas
dnd2.bas
dnd3.bas
dnd4.bas
(These all require the WMLiberty.dll to run)
(v1.0 of DLL included by permission of Brent Thorn)

This article shows how Drag n Drop works, and how to implement 
it in LB.  The simplest sample, dnd1.bas, will simply display 
the path of the file dragged onto it.  Open dnd1.bas, take a 
look at the code to see how it works, and run it.  Now open 
Explorer, click on a file, and drag it to the gray area of the 
window.  If the window is hidden by Explorer, drag the file 
to the taskbar (at the bottom of your screen) over the title 
of your window.  It should be brought to the front after a 
second, where you can continue your drag and drop.  after 
dropping the file you should see the path of the file you 
just dropped.

Now, open dnd2.bas.  Look over the changes in the code.  
This file will accept multiple files, all dragged on dropped 
at once.  Select multiple files in Explorer by holding down 
the shift or control key and click on the files you want to 
select.  Now, with them all selected, drag them over to the 
window.  All the paths shoud appear in the listbox.

Dnd3.bas will simply open any file you drag onto it in the text 
window.  You can try it out.  Dnd4.bas will draw any bmp you 
drag onto it, at the point that you drop it.  Test this one 
out with the bmp's that come with LB.  Also be sure to look 
at the changes in the code for this one.

If you need any help with drag n drop code in your applications, 
I'll be more then willing to help.  Just post it to the Liberty 
Basic or LBExp (this is pretty advanced stuff) group, or 
e-mail me, and I'll try to help you out.  Have fun, and I hope 
to see this used in your programs!

mailto:smartestmanal1ve@netscape.net

---------------------------------------------------------
GNU/LIBERTY BASIC COMPILER SYSTEM

A collection of user-friendly, open sourced BASIC
Linux ~ Win32 Compilers by Anthony Liquori.

This open source project is online at The Source Forge:
http://lbpp.sourceforge.net/

The users group is here:
http://groups.yahoo.com/group/glbcc-users/

From the GLBCC Home Page, by Anthony Liguori,
used by permission:


ABOUT
The GNU/Liberty Basic Compiler Collection (GLBCC) is a 
suite of tools designed to allow Windows and Linux users to 
compile Liberty Basic code to a standalone application. GLBCC 
uses entirely independent and entirely free libraries to generate 
super small and super fast executables that have no external 
dependency. The project originally started as a single utility 
to convert Liberty Basic code to C but quickly became an integrated 
compiler system.

The GLBCC suite is composed entirely of Free Software and 
can be downloaded at the download page . There is a great 
deal of documentation available on installing, using, and 
contributing to GLBCC at the documentation page .  If you 
have a question about installing or using GLBCC, please consult 
the appropriate Frequently Asked Question file on the 
documentation page.  If that does not answer your question, you 
can either post a message to the help forum at the SourceForge 
page, or if your problem is of a technical nature, you can post 
to the GLBCC mailing list. Otherwise, you can contact the current 
maintainer of GLBCC Anthony Liguori.  mailto:ajl13@bellatlantic.net 


WHY
There has for many years been a strong need for a real compiler 
for Liberty Basic.  Liberty Basic programs traditionally were 
quite slow and distribution required distributing your code in 
a tokenized format along with a run time engine, and a bunch of 
dll's that all together topped 1.5MB.  Liberty Basic also does 
not exist in any form on Linux.  The one thing Linux has always 
seemed to lack, was a simple language for creating GUIs.

Most importantly, this project is a prime example of the why not 
philosphy.  It's a pretty cool concept and it is pretty fun to 
work on, so why not do it. 


HOW
Normally, a compiler consists of a pre-processor, a language 
compiler that generates assembly code, an assembler that generates 
object files, and a linker that actually generates an executable.  
GLBCC works by adding another tool that allows Liberty Basic code 
to be compiled by GCC.  This tool is called LBPP.  There is also 
a runtime library that provides all the necessary run time functionality.   
This library is called libLB.  Another tool by the name of GLBCC 
(GNU/Liberty Basic Common Compiler) is included that acts as a front 
end to allow for a user friendly development environment. 


WHO
This project is currently being maintained by Anthony Liguori .  
For a complete list of all contributors, see the AUTHORS file in 
the top level of the GLBCC distribution.

---------------------------------------------------------
LB2BCX

There is another open source project that is in the works
to create a compiled executable from Liberty BASIC code.
This one first converts the Liberty BASIC code into the
BCX language, which then compiles using the 
lccwin32-compiler.  BCX is a free Basic to C translator.

Join in and learn about or help with the project here:
http://groups.yahoo.com/group/cgicellLB/

The BCX forum is here:
http://groups.yahoo.com/group/bcx/

Get the free lccwin32 compiler here:
http://www.cs.virginia.edu/~lcc-win32/

Visit MeKanixx Designs Software by Doyle Whisenant for more 
information about Liberty BASIC, lccwin32 and BCX.
http://mechanic.0catch.com/

---------------------------------------------------------
    Comments, requests, submissions or corrections: 
            Simply reply to this message!

			The Team:
Alyce Watson, Publisher and Editor: alycewatson@charter.net
Carl Gundel, Author of Liberty BASIC: carlg@libertybasic.com
Bill Jennings, Contents and Indexes: bbjen@bigfoot.com
Andrew Sturges, Contributing Editor: andrew@britcoms.com
---------------------------------------------------------