API Adventure

[Walt Decker]

I originally attempted to do this within the LB framework but I could not get the class registration to work so I put that in a dll since I would need a dll anyway.

For those who are adventurous here is a little bit of code.  The attached zip contains

API_ADVTUR._BAS (below code) and LBFD_0.dll.

SEE END OF POST.

'
OPEN "user32.dll" FOR DLL AS #USER
OPEN "kernel32.dll" FOR DLL AS #KERN
OPEN "LBFD_0" FOR DLL AS #LBFD

GWL.HINSTANCE     = -6
GWL.WNDPROC       = -4

GLOBAL ToolHndl

Instance = 0
WinHndl  = 0
ToolHndl = 0
Code.Ptr = 0

WinSizeX = DisplayWidth * 0.75
WinSizeY = DisplayHeight * 0.75

WinHndl = FN.CreateBaseWin(WinSizeX, WinSizeY, "TEST WIN")

'<======= get info to create a window class ===========>
Instance = FN.GetWindowParams(WinHndl, GWL.HINSTANCE)
Code.Ptr = FN.GetWindowParams(WinHndl, GWL.WNDPROC)

ToolHndl = FN.CreateToolWin(Instance, Code.Ptr)

RetVal = FN.WAIT(150)
WAIT

'------------------------------------
'------------------------------------

SUB BAS.CLOSE BasHndl$
'#############################################
'  Destroy the forms and release DLLs
'
'  NOTE:  The LB IDE does not properly release
'  non-API DLLs if the dll contains a function
'  associated with a callback
'#############################################

GWL.HINSTANCE = -6

RetVal   = 0
WinHndl  = 0
Instance = 0 'application instance

WinHndl = FN.GetHndl(BasHndl$)

Instance = FN.GetWindowParams(WinHndl, GWL.HINSTANCE)

'<============ release the pop-up window from the dll ===============>
CALLDLL #LBFD, "FN_ReleaseCallBack", ToolHndl AS ULONG, RetVal AS ULONG

CLOSE #LBFD
CLOSE #BasHndl$

CALLDLL #KERN, "Sleep", 0 AS LONG, RetVal AS VOID

'<================ destroy the tool pop-up class ================>
CALLDLL #USER, "UnregisterClassA", "LB_BUTTONS" AS PTR, Instance AS ULONG, _
              RetVal AS LONG

CLOSE #USER
CLOSE #KERN

END

END SUB

'------------------------------------
'------------------------------------

FUNCTION FN.WAIT(Ms)
'#############################################
' Acts as a TIMER function
' Ms = milliseconds
'#############################################

RetVal = 0

 [MORE.SLEEP]
CALLDLL #KERN, "Sleep", Ms AS LONG, RetVal AS VOID
SCAN

GOTO [MORE.SLEEP]
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.CreateBaseWin(Szx, Szy, Title$)
'#############################################
'  Create Base form
'  Szx = width of form
'  Szy = height of form
'  Title = form caption
'#############################################

Cx = 0
Cy = 0
Ux = 0
Uy = 0

WinHndl = 0
RetVal  = 0

Cx = DisplayWidth * 0.5
Cy = DisplayHeight * 0.5
Ux = INT(Cx - Szx * 0.5) - 1
Uy = INT(Cy - Szy * 0.5) - 1

RetVal = FN.SetLbPos(Ux, Uy)
RetVal = FN.SetLbSize(Szx, Szy)

OPEN Title$ FOR WINDOW AS #BAS
#BAS, "TRAPCLOSE BAS.CLOSE"

WinHndl = FN.GetHndl("#BAS")
FN.CreateBaseWin = WinHndl
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.CreateToolWin(Inst, CodePtr)
'########################################################
'  Regiseter and create a form and controls independant
'  of Liberty Basic.
'
'  Inst = application instance
'  CodePtr = code address of the base form
'########################################################

DATA "BUTTON 1"   'title of buttons
DATA "BUTTON 2"
DATA "BUTTON 3"
DATA "BUTTON 4"
DATA "BUTTON 5"

'<========== window and control styles ==========>
WS.POPUP        = HEXDEC("&H80000000")
WS.CHILD        = HEXDEC("&H40000000")
WS.VISIBLE      = HEXDEC("&H10000000")
WS.CLIPSIBLINGS = HEXDEC("&H04000000")
WS.CLIPCHILDREN = HEXDEC("&H02000000")
WS.CAPTION      = HEXDEC("&H00C00000")
WS.TABSTOP        = HEXDEC("&H00010000")

'<========== extended styles ===============>
WS.EX.DLGMODALFRAME  = HEXDEC("&H00000001")
WS.EX.TRANSPARENT    = HEXDEC("&H00000020")
WS.EX.LTRREADING     = HEXDEC("&H00000000")
WS.EX.APPWINDOW      = HEXDEC("&H00040000")

'<=========== button styles =============>
BS.CHECKBOX        = HEXDEC("&H00000002")
BS.AUTOCHECKBOX    = HEXDEC("&H00000003")
BS.TEXT            = HEXDEC("&H00000000")
BS.VCENTER         = HEXDEC("&H00000C00")
BS.PUSHLIKE        = HEXDEC("&H00001000")
BS.NOTIFY          = HEXDEC("&H00004000")

'<=========== class registration styles ============>
CS.VREDRAW    = HEXDEC("&H0001")
CS.HREDRAW    = HEXDEC("&H0002")
CS.OWNDC      = HEXDEC("&H0020")
CS.PARENTDC   = HEXDEC("&H0080")
CS.DROPSHADOW = HEXDEC("&H00020000")

PALETURQUOISE = HEXDEC("&HEEEEAF") 'background form color

RegStyle = 0 'class registration style
Wnstyle  = 0 'form/control style
Exstyle  = 0 'form/control extened style

WinHndl  = 0

Code.Ptr = 0 'callback code pointer

BtnId = 999 'button ids

Ok = 0

Ux = 0 'coordinates
Uy = 0
Ix = 0
Iy = 0

WinHndl = FN.GetHndl("#BAS")

RetVal = FN.MapPoints(WinHndl, 0, 0, 0, 0, 0)
Ux = tRect.X.struct  'client coords of upper left corner of base window
Uy = tRect.Y.struct

'<=============== set class style ==================>
RegStyle = CS.VREDRAW OR CS.HREDRAW OR CS.OWNDC OR CS.DROPSHADOW

'<=================== set form style ==================>
Wnstyle = WS.POPUP OR WS.CAPTION OR WS.VISIBLE OR WS.CLIPCHILDREN OR _
         WS.CLIPSIBLINGS
Exstyle = WS.EX.CONTROLPARENT OR WS.EX.LEFT OR WS.EX.LTRREADING OR WS.EX.APPWINDOW

'<=========== register a new class ===================>
CALLDLL #LBFD, "FN_RegisterWindow", "LB_BUTTONS" AS PTR, CodePtr AS ULONG, _
               Inst AS ULONG, RegStyle AS ULONG, PALETURQUOISE AS ULONG, _
               Ok AS ULONG

'<=============== create a pop-up form ===================>
WinHndl = FN.CreateWindow(Exstyle, "LB_BUTTONS", "BUTTONS", Wnstyle, Ux, Uy, 105, 160, WinHndl, 0, Inst)

'<================== set styles for check box buttons ===============>
Wnstyle = WS.CHILD OR WS.TABSTOP OR WS.VISIBLE OR WS.CLIPSIBLINGS OR _
         BS.AUTOCHECKBOX OR BS.PUSHLIKE OR BS.NOTIFY OR BS.VCENTER OR _
         BS.TEXT
Exstyle = WS.EX.DLGMODALFRAME OR WS.EX.TRANSPARENT

'<=============== create check box button on form ===========>
Ix = 5
Iy = 5
FOR I = 1 TO 5
 READ Txt$
 BtnId = BtnId + 1 'give each button a different ID number
 RetVal = FN.CreateWindow(Exstyle, "BUTTON", Txt$, Wnstyle, Ix, Iy, 90, 22, WinHndl, BtnId, Inst)
 Iy = Iy + 20 + 5
NEXT I

'<================ get address of our, not LB's callback function ===========>
CALLBACK Code.Ptr, FN.App.CB(ULONG, ULONG, LONG, LONG), LONG

'<====== set dll callback function to access our callback function ======>
CALLDLL #LBFD, "FN_InitCallBack", WinHndl AS ULONG, Code.Ptr AS ULONG, _
               Ok AS ULONG

FN.CreateToolWin = WinHndl
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.CheckHndl$(WinTag$)

WinTag$ = TRIM$(WinTag$)
IF LEFT$(WinTag$, 1) <> "#" THEN WinTag$ = "#" + WinTag$

FN.CheckHndl$ = WinTag$
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.GetHndl(WinTag$)

Hndl = 0

WinTag$ = FN.CheckHndl$(WinTag$)

ON ERROR GOTO [HNDL.ERROR]

Hndl = HWND(#WinTag$)

FN.GetHndl = Hndl
EXIT FUNCTION

 [HNDL.ERROR]
PRINT "HANDLE ERROR = "; WinTag$
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.SetLbPos(Ux, Uy)

UpperLeftX = Ux
UpperLeftY = Uy

FN.SetLbPos = Ux * Uy
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.SetLbSize(Szx, Szy)

WindowWidth = Szx
WindowHeight = Szy

FN.SetLbSize = Szx * Szy
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.GetWindowParams(WinHndl, ParamIdx)
'########################################################
'  API function GetWindowLong() obtains information about
'  a form or control based on an index parameter.
'########################################################

RetVal = 0
CALLDLL #USER, "GetWindowLongA", WinHndl AS ULONG, ParamIdx AS LONG, _
               RetVal AS ULONG
FN.GetWindowParams = RetVal
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.ClientSize(WinTag$, BYREF Bx, BYREF By)
'########################################################
'  API function GetClientRect() obtains the coordinates of
'  that portion of a form or control that is not caption or
'  border.
'########################################################

STRUCT tRect, _
 X  AS LONG, _
 Y  AS LONG, _
 X1 AS LONG, _
 Y1 AS LONG

WinHndl = 0
RetVal  = 0

WinHndl = FN.GetHndl(WinTag$)
CALLDLL #USER, "GetClientRect", WinHndl AS ULONG, tRect AS STRUCT, RetVal AS VOID
Bx = tRect.X.struct
By = tRect.Y.struct

FN.ClientSize = WinHndl
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.ClientRect(WinHndl)
'########################################################
'  API function GetClientRect() obtains the coordinates of
'  that portion of a form or control that is not caption or
'  border.
'########################################################

STRUCT tRect, _
 X  AS LONG, _
 Y  AS LONG, _
 X1 AS LONG, _
 Y1 AS LONG

RetVal = 0
CALLDLL #USER, "GetClientRect", WinHndl AS ULONG, tRect AS STRUCT, RetVal AS VOID

FN.ClientRect = tRect.X1.struct * tRect.Y1.struct
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.WindowRect(WinTag$)
'########################################################
'  API function GetWindowRect() obtains the display coordinates
'  of a form or a control on a form.
'########################################################

STRUCT tRect, _
 X  AS LONG, _
 Y  AS LONG, _
 X1 AS LONG, _
 Y1 AS LONG

WinHndl = 0
RetVal = 0

WinHndl = FN.GetHndl(WinTag$)
CALLDLL #USER, "GetWindowRect", WinHndl AS ULONG, tRect AS STRUCT, RetVal AS VOID

FN.WindowRect = WinHndl
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.MapPoints(Wfrom, Wto, Ptx, Pty, Ptx1, Pty1)
'########################################################
'  API function MapWindowPoints() translates coordinates from
'  one object to another object, e.g. display coordinates to
'  form coordinates.
'########################################################

STRUCT tRect, _
 X  AS LONG, _
 Y  AS LONG, _
 X1 AS LONG, _
 Y1 AS LONG

tRect.X.struct = Ptx
tRect.Y.struct = Pty
tRect.X1.struct = Ptx1
tRect.Y1.struct = Pty1

RetVal = 0

CALLDLL #USER, "MapWindowPoints", Wfrom AS ULONG, Wto AS ULONG, tRect AS STRUCT, _
               2 AS LONG, RetVal AS LONG

FN.MapPoints = RetVal
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.App.CB(Hndl, Msg, wParam, lParam)
'#################################################
'  This is like an API application CALLBACK FUNCTION
'  Hndl = Numeric handle assigned by the windows os
'  Msg = What happened, i.e. action by the user or application
'  wParam = information concerning what happened
'  lParam = more info about what happened
'
'  In an API app when a button is pressed, windows sends:
'  WM_KILLFOCUS
'  WM_SETFOCUS
'  WM_COMMAND
'
'  The notification message BN_CLICKED is in the HI(WORD) of wParam and the
'  button id assigned by the programmer is in the LO(WORD) of wparam.  The
'  handle of the button assigned by windows is in lParam
'
'  Here the notification path is changed to the BN_CLICKED
'  notification because this module is dealing with buttons only,
'  so the Msg parameter is not WM_COMMAND but BN_CLICKED, wParam
'  is the control ID number, and lParam is the handle of the
'  button clicked.
'#################################################

BN.CLICKED = 0

NumChrs = 0

BtnId = 1000

Txt$ = ""
SELECT CASE Msg
 CASE BN.CLICKED
   SELECT CASE wParam
     IF (wParam >= BtnId) AND (wParam < BtnId + 6) THEN
       Txt$ = SPACE$(32)
       CALLDLL #USER, "GetWindowTextA", lParam AS ULONG, Txt$ AS STRUCT, _
                      32 AS LONG, NumChrs AS LONG
       Txt$ = LEFT$(Txt$, NumChrs)
       PRINT "YOU CLICKED "; Txt$
     END IF
   END SELECT
END SELECT
END FUNCTION

'------------------------------------
'------------------------------------

FUNCTION FN.CreateWindow(StyleEx, ClassName$, Title$, NormStyle, Ux, Uy, Bx,By, Phndl, CtrlId, AppInst)

Hndl = 0
CALLDLL #USER, "CreateWindowExA", _
        StyleEx AS ULONG, _   ' extended styles
        ClassName$ AS PTR, _  ' window class name
        Title$ AS PTR, _      ' window caption
        NormStyle AS ULONG, _ ' window/control style
        Ux AS LONG, _         ' initial x position; zero is a valid position
        Uy AS LONG, _         ' initial y position; zero is a valid position
        Bx AS LONG, _         ' initial x size
        By AS LONG, _         ' initial y size
        Phndl AS ULONG, _     ' parent/owner window handle
        CtrlId AS LONG, _     ' window menu handle or ctrl id
        AppInst AS LONG, _    ' program instance handle
         0 AS LONG, _         ' creation parameters
         Hndl AS ULONG

FN.CreateWindow = Hndl
END FUNCTION

'---------------------------------------------------------------
'---------------------------------------------------------------
'
ADVENTURE.ZIP CONTENTS:
API_ADVTUR._BAS
API_ADVTUR_V2._BAS
LBFD_0.DLL

ADVENTURE.ZIP (14.82 KB)

[Walt Decker]

Some programmers prefer to create one class for all their forms, others prefer the creation of multiple classes with a common callback function, while others prefer the creation of multiple classes with multiple callback fuctions. I prefer the last. I have found that it is easier to redirect and debug with multiple callback functions. Therefore, I have upgraded the app with API_ADVTUR_V2._BAS to illustrate the process. The DLL is directed to forward messages to one of two callback functions based on the form handle assigned by the windows operating system.

A few words concerning the combobox control. This control is a combination of three controls, an edit control(editbox), a button, and a listbox. Each has a different handle assigned by the windows OS, so if you want to give the edit control and listbox a different color you have to obtain the handles for the edit control and listbox. This is illustrated at the bottom of function FN.CreateControl() in API_ADVTUR_V2._BAS and is handled in function FN.FORM.CB of that code.

NOTE!!!!!
If you make changes in API_ADVTUR_V2._BAS SAVE your changes, even if the changes are comments, before executing in the IDE. The IDE will crash with an "Unrecoverable protection violation" message before tkn compilation is complete. This is a glitch in the IDE tokenizer, not an error in the code.

ADVENTURE.ZIP CONTENTS:
API_ADVTUR._BAS
API_ADVTUR_V2._BAS
LBFD_0.DLL

The zip is in the first post.

[tsh73]

Hello Walt
probably I have some other definition of adventure / adventurous on my system.

Please say what this thing does (or shows how to do)?

I run it but it did not get me any wiser.

[Walt Decker]

May 4, 2023 4:17:22 GMT -5 tsh73 said:

Hello Walt
probably I have some other definition of adventure / adventurous on my system.

Please say what this thing does (or shows how to do)?

I run it but it did not get me any wiser.

Oh?  Did you look at the code?  Have you created classes, forms, and controls outside of LB control and controlled the events using callback procedures?

Showing how to do so, and, perhaps, moving others to grow and think out of the box is, to me, an adventure.  Doing this did not make me any wiser, but it did make me more knowledgeable.

[gaslouk]

May 4, 2023 4:17:22 GMT -5 tsh73 said:

Hello Walt
probably I have some other definition of adventure / adventurous on my system.

Please say what this thing does (or shows how to do)?

I run it but it did not get me any wiser.

tsh73 I think Walt is doing something that you from the forum may not have thought to do. because it is very difficult. So I think you need our help to achieve it. At the same time, not all of us can benefit from it. And we are left to gain knowledge about the Windows API and Walt too. Hence the title "API Adventure."

For my part I will help as much as I can because I am also interested in understanding the API'S. I don't know how deep I've fallen Walt, but I'll try my best I repeat it.

[Rod]

Yeah, api v basic. I am a basic coder, I don’t use classes or callbacks. I know they are in the background but I don’t need to care. What I use are events and handlers, to get four buttons on a floating window can be done in basic and there are options to make the event handler more informative.

But I don’t understand what the original problem was that could not be achieved natively.

[gaslouk]

May 4, 2023 10:06:30 GMT -5 Rod said:

Yeah, api v basic. I am a basic coder, I don’t use classes or callbacks. I know they are in the background but I don’t need to care. What I use are events and handlers, to get four buttons on a floating window can be done in basic and there are options to make the event handler more informative.

But I don’t understand what the original problem was that could not be achieved natively.

Now Rod, speaking of you, not only is my English bad, but my Greek isn't much better either.
I say this because google translator knows Greek better than me. I think the problem is how we go about building a multi-editor for forms. I think with liberty basic this is not possible without Windows API's. And with freeform, workshop, LB Toolbox, LB Builder and more, it was not possible.
However, Liberty Basic has such multiform capabilities, but they have not been revealed yet.

I think that's the point.

Gaslouk.

[Rod]

Well I didn’t understand it, still don’t, and others didn’t understand it, but some clearly do.

It needs to be described in basic terms. Multi form display? Is that the adventure?

I am a man, classically described as unable to multitask. So multiform for me means one form in focus at a time. I can do that without api.

But again I am not really understanding what this adventure is. I would actually like to.

[gaslouk]

May 4, 2023 11:31:23 GMT -5 Rod said:

Well I didn’t understand it, still don’t, and others didn’t understand it, but some clearly do.

It needs to be described in basic terms. Multi form display? Is that the adventure?

I am a man, classically described as unable to multitask. So multiform for me means one form in focus at a time. I can do that without api.

But again I am not really understanding what this adventure is. I would actually like to.

I think only Walt Rodd can give that answer, Rodd.

[Walt Decker]

Yeah, api v basic. I am a basic coder, I don’t use classes or callbacks. I know they are in the background but I don’t need to care.

Then you limit yourself. It is not a matter of API V BASIC(in reference to Liberty Basic), it is a matter of extending LB and gaining knowledge by exploring what can be achieved. All basic systems are not as limited as Liberty Basic.

What I use are events and handlers, ...

What do you think a callback procedure is?

... there are options to make the event handler more informative.

What are those options? Menu items provide no information, SUB event handles supply only the handle of the control or, in the case of graphics the handle of the control and the mouse position.

But I don’t understand what the original problem was that could not be achieved natively.

What is not native about CALLBACK and CALLDLL?

[gaslouk]

I think I'm leaning towards Walt. Besides, I think a few more knowledge wouldn't hurt any of us. And as our ancient ancestors used to say "as long as I live I learn."

[Brandon Parker]

This is not a productive conversation any longer...siding with one person or another here is not relevant.

I believe I understand both sides... Forgive me for being frank here.

Walt understands the Windows API very well and can implement productive DLLs for use with LB, but, in my opinion, sometimes goes straight for an API solution when a native LB solution can/does exist.

Rod primarily programs in native LB code with minimal use of API calls and those constructs built into LB to interface with them, but has time and again shown that LB can do some very fantastic things with its native constructs.


Both sides are perfectly fine to be on. We grow as a community when everyone shares new and interesting things.


I will say stating that LB is incapable of building a "multi-editor for forms" is, I think, a little off the mark. Sure, you might have to compromise on certain things, but anything is possible when you get creative.


I think what Rod is asking for is just a better description of what the BAS programs and associated DLLs do. More people are apt to download and try out the code if there is a better description of what it does and how it can be applied for at least one use case. I for one fall into this group. I saw/read the post, but was not really interested due to the vagueness of the original post. I am not saying that anything Walt posted is bad/uninteresting, but I always have adventures with APIs and was thus not sprung into action just by that title.


So, maybe Walt can give us a better synopsis of what is going on with the stuff he posted and everyone can keep an open mind about what is possible when we all cooperate and share new programming adventures.


{:0)

Brandon Parker

[Walt Decker]

I must appologize. I am in my 8th decade, 90% blind, and have a 5 month old aortic heart valve. At this stage of my life the only adventure I have is a quest for knowledge, either new or that which I have forgotten and it does not matter whether that knowledge concerns the universe or a computer programming system.

Before a form can be displayed by the Windows OS an application must first register at least one "class" with the OS. The class has various properties; the most important is the callback procedure. When a form is created a control on the form uses the callback procedure to notify the form of the control's state. The callback procedure also receives notifications concerning the state of the form itself. A change in state is an event, thus a callback procedure is an event trap. The programmer monitors events of interest and directs the application to perform appropriate tasks. And now to the adventure.

The adventure is five fold:

1) show others what an application callback procedure looks like and how to use one to perform tasks.

2) determine if a "class" can be registered with the Windows OS and piggy-back that class onto the Liberty Basic callback procedure. Normally classes are created before forms are created.

3) create forms that behave as one, that is, when the owner form is minimized the owned form is also minimized; when the owner form is moved the to background by an unrelatd form, the owned form also moves to the background. In addition, the owned form is always on top of the owner form but can be moved anywhere on the desktop. Liberty Basic forms can not do this because they are all owned by the desktop and are independant of each other.

4) draw something on a form, not a graphic control, and make it persistant. This can be done on an LB form, but it takes forever because LB appears to create a memory meta-file that it plays back when a form is resized in any way. This is relavant because of an idea I have concerning OpenGL.

5) design a small procedure that monitors events for one or many forms and directs the notification to the appropriate Liberty Basic event trap (callback procedure).

Accomplishing this was quite an adventure. I gained a lot of knowledge about Liberty Basic, the most important is, it will not work.

The app works fine as is in the LB IDE.

When creating a TNK and executing the TKN in the IDE it works until one clicks on a button and the notification message is cleared. The IDE then crashes with a notification that the collection is empty.

When attemptiing to create an "exe" while in the IDE it crashes with an unnormalized integer message.

Oh well, back to the drawing board.

[tsh73]

Walt, thank you very much for describing this.
Reading code without general undestanding what it does cannot beat human words.

[Rod]

Yes, callback support has been poor up to now. We have relied on wmliberty.dll Anything you can do to demystify callbacks will be great. Things like middle mouse scroll and gestures and even loss of textbox focus. If they can be demonstrated that would be a great addition.

Less sure about classes and such since these are all new concepts and would need thoroughly explained.