UPDATE: New Version 0.1.0.369 beta
Changes v0.1.0.369 beta: -- Feb. 20, 2008
Added some premade core events for mouse, keyboard, and joystick.
Added event queue throttling commands for all event queues.
Added commands to turn core event queues on and off.
Updated Example code with some new commands.
Changes v0.0.2.77 beta: -- Feb. 12, 2008
Now accepts up to 10 parameters instead of just 8 on RAISE DBP EVENT.
Fixed error in example code that kept results of Test3() event handler from printing.
Added new parameters to Test3() event handler to reflect the above change.
I would be most interested in know the frame rates you get when using this plugin on the test code. Also if you can think of event related features you would like added, I am all ears.
-----------------------------------------------------------------------------
Ok... unlike my other plugin, this one is being released first as a beta with no source.
Purpose: Creates a set of commands to let the user declare, raise, and handle events in the style of VB6, VB.NET, and C#. It is capable of raising core events such as "OnMouseMove", "OnKeyDown", and "OnJoystickXChanged". The user can set up multiple event queues which can be set to process at different times in the loop. Each queue can be throttled to only process events after a specified number of loops. Core events such as the mouse, keyboard, and joystick can be turned on and off at will by the user.
It uses the function pointer capabilities provided by IanM's Matrix1Util_20 plug-in, and as such this plugin is REQUIRED for this plug-in to work. Because of this requirement, the VC++ redistributables may be needed as well. His Matrix1 plug-ins, and the VC++ redistributables can be found here at the bottom of the first post:
http://forum.thegamecreators.com/?m=forum_view&t=85209&b=18
Why An Event Handler?
The goal of this plugin was to make things easier for the DBPro programmer that is coming from a VB6 or .NET background. However, once the concepts of events and how they can be used are grasped, pretty much anyone can benefit from them.
DBPro is a procedural language. That is to say it processes commands in a linear fashion. Because of this, code tends to be actionary. You have to make things happen. On the other hand, event based programming is
reactionary. Things happen, and you design code to respond to those events.
An illustration of the difference is in handling a mouse click:
In a procedural language like DBPro you would set up a loop, and poll the mouse every loop checking to see if the mouse has been clicked. Once it is clicked, then you perform the appropriate action.
In an event based language, you would make a function that does something when the mouse is clicked. You declare that function as a handler for mouseclick events. Then when the mouse is clicked and event call is fired. The appropriate function is automatically called to handle that event. There is no need to constantly check for these things to happen; it is all done behind the scenes. You just design code to react to it.
That is what this is what this plugin does.
Here is the current function list. You will need IanM's plugin mentioned above to get the function pointer for the DECLARE statment:
DECLARE DBP EVENT HANDLER DBP EventName as String, FunctionPtr as Long
RAISE DBP EVENT Index as Integer, EventName as String, [param1, param2, param3,.... param10]
DBP DO EVENTS Index as Integer
DBP DO CORE EVENTS *no parameters*
MOUSE EVENTS ON *no parameters*
KEYBOARD EVENTS ON *no parameters*
JOYSTICK EVENTS ON *no parameters*
SET EVENT QUEUE THROTTLE Index as Integer, NumberofLoops as Integer
SET MOUSE EVENT THROTTLE NumberofLoops as Integer
SET KEYBOARD EVENT THROTTLE NumberofLoops as Integer
SET JOYSTICK EVENT THROTTLE NumberofLoops as Integer
The recognized core events are as follows (these are the premade events. No need to raise them, just declare a handler for them. Some events send parameters to your handler function. If a handler needs to send parameters, the necessary declarations are next to the event name. These would be placed as arguments in your handler function:
Mouse Events:
OnMouseMove MovedX as Integer, MovedY as Integer, MovedZ as Integer, PosX as Integer, PosY as Integer, PosZ as Integer
OnMouseDown Buttons as Integer
OnMouseUp Buttons as Integer
OnMouseLeftDown *no parameters*
OnMouseLeftUp *no parameters*
OnMouseRightDown *no parameters*
OnMouseRightUp *no parameters*
OnMouseMiddleDown *no parameters*
OnMouseMiddleUp *no parameters*
OnMouseFourDown *no parameters*
OnMouseFourUp *no parameters*
OnKeyDown Key as Integer
OnKeyUp Key as Integer
OnUp Key as Integer
OnDown Key as Integer
OnRight Key as Integer
OnLeft Key as Integer
OnReturn Key as Integer
OnSpace Key as Integer
OnTab Key as Integer
OnRightShift Key as Integer
OnLeftShift Key as Integer
OnRightCtrl Key as Integer
OnLeftCtrl Key as Integer
OnRightAlt Key as Integer
OnLeftAlt Key as Integer
OnEscape Key as Integer
OnJoystickUp *no parameters*
OnJoystickDown *no parameters*
OnJoystickLeft *no parameters*
OnJoystickRight *no parameters*
OnJoystickFireA *no parameters*
OnJoystickFireB *no parameters*
OnJoystickFireC *no parameters*
OnJoystickFireD *no parameters*
OnJoystickXChanged Value as Integer
OnJoystickYChanged Value as Integer
OnJoystickZChanged Value as Integer
OnJoystickSliderAChanged Value as Integer
OnJoystickSliderBChanged Value as Integer
OnJoystickSliderCChanged Value as Integer
OnJoystickTwistXChanged Value as Integer
OnJoystickTwistYChanged Value as Integer
OnJoystickTwistZChanged Value as Integer
OnJoystickHatAngle1Changed Value as Integer
OnJoystickHatAngle2Changed Value as Integer
OnJoystickHatAngle3Changed Value as Integer
OnJoystickHatAngle4Changed Value as Integer
You might have noticed a few events missing, such as key up events for some of the named keys (OnUp, OnTab, etc.) and a "OnJoystickFireX" event. Those will be coming in a later update. Also at this time, core events can be turned on and off, but there is no corresponding function for custom event queues. This will also be coming in a later update.
Ok... a brief explanation and then some example code.
You declare your event handlers at the beginning of your code. If you wish to use core events you must turn them on. To get the function pointer for the handler declaration you must use IanM's Matrix1Util_20.dll plugin. Make the function you want to be your event handler. Right before that function in your code, make another function with one command in it like so:
function fp_Test1()
value = Get PTR to Next Function()
endfunction value
function Test1()
`This function will be your actual event handler.
`The one before simply grabs and returns a pointer to it.
endfunction
Your declaration should now look like this:
DECLARE DBP EVENT HANDLER "MyEvent1", fp_Test1()
Now put the DBP DO EVENTS code in your main loop where you want it to handle your events. In any of your code you can raise an event like this:
RAISE DBP EVENT 1, "MyEvent1"
The number 1 is the index of the event queue your events will go into it. The DBP DO EVENTS function with a matching index will process that event. Optionally you can have up to 10 parameters sent with your event, but the handler function must be set up to take the same number and types of parameters.
Here is an example program that should run fine using this plugin. It isn't fancy, but it should give you an idea of how it works. Try left clicking the mouse when running it. Also take special notice of the last function of the program. Something like this is necessary if you are using core events as it forces the compiler to include the necessary DLL by using a command from it. That code never gets run so it doesn't matter which Input command you put in there.
autocam off
disable escapekey
position camera 0,0, -100
`used to denote line height for printing text.
global OFFSET as integer = 15
`mouse move globals
global mmx as integer
global mmy as integer
global mmz as integer
`mouse position globals
global mpx as integer
global mpy as integer
global mpz as integer
`last key pressed global
global keypressed as integer
`last mouse buttons pressed
global mousebuttons as integer
global event1works as boolean
global event2works as boolean
global MouseVisible as boolean
`Tells DBPro that we want to use mouse and keyboard events.
MOUSE EVENTS ON
KEYBOARD EVENTS ON
`throttle the mouse to only be polled every 10 loops.
SET MOUSE EVENT THROTTLE 10
`Sets a throttle on custom event queue 2
`This queue will only be updated once every two loops
`Notice that the text on the left flickers badly.
`This is an example of why you should not throttle event queues
`that have handlers which print text or render 2D graphics.
SET EVENT QUEUE THROTTLE 2, 2
`Declare your events here.
`first parameter is the name of your event.
`second parameter is the function pointer to it
DECLARE DBP EVENT HANDLER "MyEvent1", fp_Test1()
DECLARE DBP EVENT HANDLER "MyEvent2", fp_Test2()
DECLARE DBP EVENT HANDLER "MyEvent3", fp_Test3()
DECLARE DBP EVENT HANDLER "OnMouseMove", fp_onmousemove()
DECLARE DBP EVENT HANDLER "OnKeyDown", fp_onkeydown()
DECLARE DBP EVENT HANDLER "OnKeyUp", fp_onkeyup()
DECLARE DBP EVENT HANDLER "OnMouseDown", fp_onmousedown()
DECLARE DBP EVENT HANDLER "OnMouseLeftDown", fp_onmouseleftdown()
DECLARE DBP EVENT HANDLER "OnMouseLeftUp", fp_onmouseleftup()
`make a few object to manipulate.
Make Object Cube 1, 50
Make Object Cone 2, 15
Position object 2, 0, 0, -50
color object 1, rgb(255,0,0)
color object 2, rgb(0,0,255)
`Our main loop.
do
`this function shows raising a custom event with 10 arguments
CallingFunction()
`Handles default events like "OnMouseMove"
DBP DO CORE EVENTS
`these will handle your custom events and call any handlers when needed.
`they don't need to be together, and are just together here for the demo
DBP DO EVENTS 1
DBP DO EVENTS 2
`print out some results.
Text 10,(0*OFFSET), "FPS = " + Str$(Screen FPS())
Text 0, (30*OFFSET), "MoveX = " + str$(mmx)
Text 150, (30*OFFSET), "MoveY = " + str$(mmy)
Text 300, (30*OFFSET), "MoveZ = " + str$(mmz)
Text 0, (31*OFFSET), "MouseX = " + str$(mpx)
Text 150, (31*OFFSET), "MouseY = " + str$(mpy)
Text 300, (31*OFFSET), "MouseZ = " + str$(mpz)
Text 500, (0*OFFSET), "KeyPressed = " + str$(keypressed)
Text 500, (3*OFFSET), "MouseClick = " + str$(mousebuttons)
loop
end
`This is how you get the function pointer.
`The command is from IanM's Matrix1Util_20 plugin.
`The return value simply points to the next function in your code.
function fp_Test1()
value = Get PTR to Next Function()
endfunction value
`The last function gets a pointer to this one.
`Notice that this function never gets called directly in code.
`This rotates our cube based on mousemovements through core events.
function Test1()
if event1works = 0
color object 1, rgb(0,255,0)
event1works = 1
endif
Rotate Object 1, Object Angle X(1) - mmy, Object Angle Y(1) - mmx, 0
endfunction
`Yet another pointer to a handler function.
function fp_Test2()
value = Get PTR to Next Function()
endfunction value
`This rotates our cone based on mousemovements through core events.
function Test2()
if event2works = 0
color object 2, rgb(255,0,255)
event2works = 1
endif
Rotate Object 2, Object Angle X(2) + mmy, Object Angle Y(2) + mmx, 0
endfunction
`One more handler function
function fp_Test3()
value = Get PTR to Next Function()
endfunction value
`Notice all the parameters. This function recieves the parameters sent with
`your RAISE DBP EVENT function.
function Test3(num1 as integer, num2 as integer, num3 as integer, num4 as integer, num5 as integer, num6 as integer, num7 as integer, num8 as integer, num9 as integer, num10 as integer)
Text 10,(2*OFFSET), "num1 = " + Str$(num1)
Text 10,(3*OFFSET), "num2 = " + Str$(num2)
Text 10,(4*OFFSET), "num3 = " + Str$(num3)
Text 10,(5*OFFSET), "num4 = " + Str$(num4)
Text 10,(6*OFFSET), "num5 = " + Str$(num5)
Text 10,(7*OFFSET), "num6 = " + Str$(num6)
Text 10,(8*OFFSET), "num7 = " + Str$(num7)
Text 10,(9*OFFSET), "num8 = " + Str$(num8)
Text 10,(10*OFFSET), "num9 = " + Str$(num9)
Text 10,(11*OFFSET), "num10 = " + Str$(num10)
endfunction
`a pointer to our OnMouseMove event handler.
function fp_onmousemove()
value = Get PTR to Next Function()
endfunction value
`Notice that this doesn't get called in code, and has no
`associated RaiseEvent in any code. It gets called by
`the core events engine when the mouse is moved.
`The arguments are hard coded for this event and MUST be included
`even if they are not used in the code.
function OnMouseMove(mx as integer, my as integer, mz as integer, px as integer, py as integer, pz as integer)
mmx = mx
mmy = my
mmz = mz
mpx = px
mpy = py
mpz = pz
RAISE DBP EVENT 1, "MyEvent1"
RAISE DBP EVENT 1, "MyEvent2"
endfunction
function fp_onkeydown()
value = Get PTR to Next Function()
endfunction value
function KeyDown(key as integer)
If key = 50
if MouseVisible = 1
Hide Mouse
MouseVisible = 0
else
Show Mouse
MouseVisible = 1
endif
endif
endfunction
function fp_onkeyup()
value = Get PTR to Next Function()
endfunction value
`Notice that this doesn't get called in code, and has no
`associated RaiseEvent in any code. It gets called by
`the core events engine when a key is pressed and then released.
`The arguments are hard coded for this event and MUST be included
`even if they are not used in the code.
function KeyUp(key as integer)
keypressed = key
endfunction
function fp_onmousedown()
value = Get PTR to Next Function()
endfunction value
function OnMouseDown(buttons as integer)
mousebuttons = buttons
endfunction
function fp_onmouseleftdown()
value = Get PTR to Next Function()
endfunction value
function OnMouseLeftDown()
color object 1, rgb(255,128,0)
color object 2, rgb(255,255,0)
endfunction
function fp_onmouseleftup()
value = Get PTR to Next Function()
endfunction value
function OnMouseLeftUp()
color object 1, rgb(0,255,0)
color object 2, rgb(255,0,255)
endfunction
`This will simply raises a custom event with 10 arguments (the maximum).
function CallingFunction()
`define some numbers to use as parameters.
t1 as integer = 1
t2 as integer = 2
t3 as integer = 3
t4 as integer = 4
t5 as integer = 5
t6 as integer = 6
t7 as integer = 7
t8 as integer = 8
t9 as integer = 9
t10 as integer = 10
`Here is how you raise an event. Notice this uses a different Event Queue (2).
`Text will flicker because we previously set Event Queue 2 to only update
`every 2 loops.
RAISE DBP EVENT 2, "MyEvent3", t10, t9, t8, t7, t6, t5, t4, t3, t2, t1
endfunction
`This may not be necessary in future releases,
`but for now, something like this must be included.
`It forces the compiler to include the DBProInputDebug.dll
`for mouse and key commands.
function DUMMYFUNC()
z as integer
z = Mousemovex()
endfunction
Just download the attached zip file and extract the contents to your DarkBASIC Professional directory.
Enjoy.
Design documents?!? What design documents??? I thought we were just going to wing it!!!
