Brosco's DLL - Release 1.05 - October 1998

Requires Win 3.11 or above, some functions require LB1.41

You may have notice that each DLL that I have produced is
a minimum of 100Kb - even if the DLL only has a couple of
functions.  The reason for this is the size of the standard
support code that is automatically included in every DLL.

By making one DLL - with several functions - they all share
the same support functions, and thus, is significantly 
smaller than the combined size of the separate DLLs.  The
current size of this DLL is now 130Kb - only slightly 
bigger than the DLL containing just one of these functions!

NOTE:  In making this change - I have made slight changes
to several of the functions.  Names of functions and the
parameters may have changed also.

(Functions below all assume that the DLL has been opened in
Liberty Basic with the command:

    Open "brosco.dll" for dll as #brosco

Functions in this release of Brosco's DLL:

1)  GetVersion
2)  Timer Callback Functions.
3)  StatusBar Functions.
4)  Progess Bar Functions
5)  PickColor Function
6)  'Round About Window'
7)  'Invisible' Windows

               *************************

1)  GetVersion

   CallDll #brosco, "GetVersion", versionNum as word

   Returns the Version Number of this DLL.  This number 
should be stated in correspondence when reporting problems
with the DLL functions.  Current version number of the DLL
supplied in the ZIP file is "105".

               *************************

2)  Timer Callback Functions.

For smooth animation in games it is necessary to have a timed 
delay between the displaying of an image sequence.  Previously,
to do this in LB required that the LB program used SCAN and 
constantly check the TickCount to determine if sufficient time
had ellapsed before displaying the next image.  This meant that
the program used 100% of CPU resources.  (Other timing techniques
can also be used - such as timed FOR-NEXT loops - but all suffer 
from the same problem - 100% CPU ulitisation).

The Timer functions in this DLL use the Windows 'SetTimer' function,
which use a CallBack technique to inform the program when a 
specified time has ellapsed.   During this interval, the program
may perform other tasks, or allow Windows to give control to
another program.   

The DLL issues the SetTimer on behalf of the LB program and also 
receives the CallBack from Windows.  It then simulates a CallBack 
in a way that the LB program can handle.

Since Liberty Basic does not support Callbacks directly - the DLL
simulates Callbacks via the Resizehandler in LB (Version 1.41 and
above).  You need to Open a small window (may be hidden) which 
has a TextBox control.  This control is used to pass information 
from the DLL to the LB program.  When the DLL wishes to 
communicate with the LB program - it places a message in the 
TextBox and then sends a message to Windows to force it to 
activate LB's ResizeHandler.

The sample programs attached demonstrate how this is implemented.

The message placed in the TextBox is in the form of:
  "tt cc"
where:
  tt is a number from 1-32, representing the TimerID.
  cc is a count of the times that a callback has been
     received for this TimerID 

The SetTimer function can accept a time interval (in theory) between
1 mSec (millisecond) and 65535 mSecs.  1000 mSecs = 1 second.

However, the Windows' timer users the basic underlying PCtimer 
which is only updated every 54.925 mSecs - or about 18.2 times
per second.  SetTimer will round (down) any time interval that
is not a multiple of 54.925.  So by specifying an interval of
1000 mSecs - the callback will actually occur after an 989mSec
interval.

Windows only allows a MAXIMUM of 32 timers to be active at
the same time.  This count is System-wide, so be aware that
other programs may have timers active also.  Where possible,
use the same timer to control multiple actions.

Function calls:

     CallDll #brosco, "InitTimer", _
                hw as word, _    ' handle of the "callback" window
                ht as word, _    ' handle of the textbox for msgs
		option as word, _ ' Reserved for future use - set to zero
                result as word 

InitTimer should be Called after the 'CallBack' window has
been opened and before any other timer functions are called.

    CallDll #brosco, "StartTimer", _
               timerID as word, _ ' a number beween 1 and 32
               interval	as word, _ ' Delay time in mSecs
               result as word
StartTimer causes the DLL to issue the SetTimer function and
start the timing process.  A count of the CallBacks received
is kept updated and is part of the message sent to the LB 
program.

    CallDll #brosco, "EndTimer", _
               timerID as word, _  ' ID of timer to be stopped
               result as word
EndTimer should be called when a Timer is no longer required.


Some processes that are activated by the timer Callback may take
longer to process than the timing interval.  In these cases, it
is recommended that the Timer be 'paused' so that callbacks don't 
stack up on the queue.
    CallDll #brosco, "PauseTimer", _
               timerID as word, _   ' ID of timer to be Paused
               result as word
Note: PauseTimer is identical code to the "EndTimer" function
and is only implemented to create a logical match to go with
"ResumeTimer".


After a Timer has been Paused and the appropriate action(s)
have been processed - the program should issue a "ResumeTimer":
    CallDll #brosco, "ResumeTimer", _
               timerID as word, _  ' ID of timer to be Resumed
               interval as word, _ ' time interval in mSecs
               result as word
The ResumeTimer function is identical to the StartTimer function
EXCEPT that the Counter for the number of CallBacks is NOT
reset to zero.

Two LB programs are included with this ZIP to demonstrate the
above functions.  TimeCB.bas simply issues a callback every 5
seconds.  When received, the LB program displays a MessageBox
and waits for the user to click "OK".  Since it may take longer
than 5 seconds for the user to respond - the Timer is Paused.
After "OK" has been clicked - the Timer is Resumed.  The
window used to simulate the CallBack is placed as "AlwaysOnTop"
to demonstrate the way it is used.

Anim1.bas cycles through a sequence of 14 BMPs to create some
simple animation (similar to GIF animation).  There is a Radio
Button available to change the speed of the animation.  The
'CallBack' window is hidden.

               *************************

3)  StatusBar Functions.

These functions allow you to display a Windows StatusBar on
your window, change its size and position, and display text.
If the window is resized - the StatusBar can be automatically
resized also, by issuing a command from the LB ResizeHandler.

All functions have been demonstrated in the Statbar.bas
program included with this zip.

    calldll #brosco, "CreateStatusbar", _
                hw as word, _    ' handle of parent window
                hSB as word      ' handle of created stus bar

hSB is the handle of the created Statusbar - this handle is 
required for all subsequent Statusbar functions.


If your Window may be resized - place the following function
call in your ResizeHandler to resize the statusbar:
    CallDll #brosco, "ResizeStatusbar", _
               hSB as word, r as word

To write a message on the Statusbar:
    CallDll #brosco, "SetTextStatusbar", hSB as word, _
               "A sample message." as ptr, r as long

You may change the height of the status bar.  The Height 
that you specify is the height of the FONT to be used -
the statusbar height will be changed to accomodate the
height:
    height = 12
    CallDll #brosco, "SetHeightStatusbar", _
               hSB as word, _
               height as word, r as long

The Statusbar may be placed at either the top or the bottom
of the window:
    pos = 0    '0 = top, 1 = bottom
    CallDll #brosco, "SetPositionStatusbar", _
               hSB as word, _
               pos as word, r as long

               *************************

4)  Progess Bar Functions

This function implements the Windows common control for a
Progress bar.  The functions are demonstrated in Progress.bas.

    CallDll #brosco, "CreateProgressbar", _
            hw as word, _           ' handle of parent window
            110 as word, _          ' Upper leftX of control
            10 as word, _           ' Upper leftY of control
            420 as word, _          ' width of control
            25 as word, _           ' height of control
            0 as word, _            ' Lower Limit of the bar
            1000 as word, _         ' Upper limit
            hP as word              ' handle of the control

To update the 'progress' express the progress as a percentage:

    pos = int(i / 1000 * 100)   ' Express progress as a percentage
    CallDll #brosco, "UpdateProgressbar", _
            hP as word, _           ' handle of the Progress bar
            pos as word, _          ' new position (%age of the total)
            r as word

(This example also includes examples of using the StatusBar functions.

               *************************
5)  PickColor Function

This Function was fully documented and demostrated in the
LB Newsletter Issue #16.  Following is an extract fron the
article.  (Please note the name change of the DLL and the 
Function - all other information remains the same).

The PickColor Function provides access to this Windows color
dialog.  To use it in a program, you must first build a
struct.

A struct is simply an array of values that you will pass
into the api call to be filled.  There are 16 items in
the struct for this dll that correspond to those 16 empty
custom color boxes in the common color dialog.

Here is the struct to build before making the call:

    open "brosco.dll" for dll as #brosco

    struct custcol, _   ' You can define upto 16 Custom colours
        c1 as long,_
        c2 as long,_
        c3 as long,_
        c4 as long,_
        c5 as long,_
        c6 as long,_
        c7 as long,_
        c8 as long,_
        c9 as long,_
        c10 as long,_
        c11 as long,_
        c12 as long,_
        c13 as long,_
        c14 as long,_
        c15 as long,_
        c16 as long

When you write "c1 as long" you are telling the dll that
you want to reserve the first 32 bits of information to
store the custom color in the first box.  c2 will contain
the 32 bit value of the color in the second box, and so on.
Any unfilled box, will simply return a value of 0, which
is BLACK.

Now that you have the struct to hold the color values, you
may make the call:

    CallDll #brosco, "PickColor", custcol as struct, result as long

    close #brosco

Its really a simple call to make.  You need only send it your
struct and it returns a value for the last color chosen.

This means that "result" will contain the value of the last
color clicked in the gradiant box, whether it was added
to the custom colors or not.  So, the dll can be used to
define a palette of 16 custom colors, or to retrieve only
one color - the last color chosen.

               *************************

6) and 7)  Round and Invisible Windows

These haven't been documented at this stage because they will
probably change as more feedback is received (hint, hint).

Documentation for the way they currently operate can be found
in the sample programs - RoundW.bas, InvWin.bas and InvWin00.bas.

               *************************



Bug reports, comments, suggestions, etc:
               - Mail to: brosco@orac.net.au

