---++!! !CommonCtrl.os %TOC{title="Contents:"}% %STARTINCLUDE% ---++ emulating operating system message queue, windows hook, and windows behavior | *Title* | emulating operating system message queue, windows hook, and windows behavior | | *Author(s)* | LiXizhi | | *Date* | 2007/10/7 | | *File* | script/ide/os.lua | ---+++ Description %T% __Sample Code__ <verbatim> NPL.load("(gl)script/ide/os.lua"); local app = CommonCtrl.os.CreateGetApp("MyAPP"); local wnd = app:RegisterWindow("MainWindow", nil, function (window, msg) if(msg.type == CommonCtrl.os.MSGTYPE.WM_CLOSE) then -- Do your code elseif(msg.type == CommonCtrl.os.MSGTYPE.WM_SIZE) then -- Do your code end end); local childwnd = app:RegisterWindow("ChildWindow", "MainWindow", function (window, msg) if(msg.type == CommonCtrl.os.MSGTYPE.WM_CLOSE) then -- Do your code elseif(msg.type == CommonCtrl.os.MSGTYPE.WM_SIZE) then -- Do your code end end); -- send using a window object childwnd:SendMessage("MainWindow", CommonCtrl.os.MSGTYPE.WM_CLOSE); -- send a message to this window childwnd:SendMessage(nil, {type = CommonCtrl.os.MSGTYPE.WM_CLOSE}); -- or one can send a message using app object app:SendMessage({type = CommonCtrl.os.MSGTYPE.WM_CLOSE}); -- one can unregister at any time app:UnRegisterWindow("ChildWindow"); -- one can delete app. if it is not used. CommonCtrl.os.DestroyApp("MyApp") </verbatim> ---+++ Member Functions ---++++ !CommonCtrl.os.window:SendMessage <verbatim> for hook definitions. CommonCtrl.os.hook = { HookType = { -- Installs a hook procedure that monitors messages before the system sends them to the destination window procedure. WH_CALLWNDPROC = 1, -- Installs a hook procedure that monitors messages after they have been processed by the destination window procedure. WH_CALLWNDPROCRET = 2, -- Installs a hook procedure that receives notifications useful to a computer-based training (CBT) application. WH_CBT = 3, -- Installs a hook procedure useful for debugging other hook procedures. WH_DEBUG = 4, -- Installs a hook procedure that monitors keystroke messages. WH_KEYBOARD = 5, -- Installs a hook procedure that monitors mouse messages. WH_MOUSE = 6, -- Installs a hook procedure that receives notifications useful to shell applications. WH_SHELL = 7, -- last one WH_LAST = 8, }, -- single hook object template Hook = { -- Specifies the type of hook procedure to be installed. see CommonCtrl.os.hook.HookType hookType = nil, -- Pointer to the hook procedure, see CommonCtrl.os.hook.HookType for how each hook type's call back should be defined. callback = nil, -- unique identifier of this hook, this will prevent hook of the same name to be created multiple times. hookName = nil, -- application name for which we are hooking, if nil it will hook to all active apps. appName = nil, -- window name for which we are hooking, if nil we will hook to all windows of a given app. wndName = nil, }, -- a list of hooks of the same type. HookChain = {}, -- all hook chains. use HookType as its index. HookChains = {}, -- a template hook call back function. HookProc = function (nCode, appName, msg) -- return the nCode to be passed to the next hook procedure in the hook chain. -- in most cases, if nCode is nil, the hook procedure should do nothing. if(nCode==nil) then return end -- TODO: do your code here return nCode end, }</verbatim>; local HookType = CommonCtrl.os.hook.HookType; ------------------------------------------------------------- os.window functions: public ------------------------------------------------------------- send and process a message immediately * _param_ __targetWndName__ : if nil, the current window is used. * _param_ __typeOrMsg__ : it should be an interger for param1, param2, ... to take effect. if it is a table, all paramN is ignored and this is the msg object. * _return_ ____ : result is returned __syntax__ <verbatim>function CommonCtrl.os.window:SendMessage(targetWndName, typeOrMsg, param1, param2, param3, param4)</verbatim> __parameters__ | *targetWndName* | if nil, the current window is used. | | *typeOrMsg* | | | *param1* | | | *param2* | | | *param3* | | | *param4* | | | *return* | result is returned | ---++++ !CommonCtrl.os.window:GetParent get parent window struct. it may return nil __syntax__ <verbatim>function CommonCtrl.os.window:GetParent()</verbatim> ---++++ !CommonCtrl.os.window:GetParentName get parent window name. it may return nil __syntax__ <verbatim>function CommonCtrl.os.window:GetParentName()</verbatim> ---++++ !CommonCtrl.os.window:GetWindowFrame -------------------------------------------- windows frame related functions -------------------------------------------- get the windows frame object for displaying a UI windows for the window object. more information, please see ide/windowframe.lua __syntax__ <verbatim>function CommonCtrl.os.window:GetWindowFrame()</verbatim> ---++++ !CommonCtrl.os.window:IsVisible get whether the windows frame is visible more information, please see ide/windowframe.lua __syntax__ <verbatim>function CommonCtrl.os.window:IsVisible()</verbatim> ---++++ !CommonCtrl.os.window:DestroyWindowFrame destroy windows frame. so that self:GetWindowFrame() will return nil. both UI and window frame parameters will be destoryed. if you just want to hide the windows, use ShowWindowFrame(). __syntax__ <verbatim>function CommonCtrl.os.window:DestroyWindowFrame()</verbatim> ---++++ !CommonCtrl.os.window:CreateWindowFrame Create a new windows frame for the current window. You can not create multiple window frames for the same window. * _param_ __winParams__ : windows frame parameters. it is the same as first parameter passed to WindowFrame:new2() in ide/windowframe.lua. Except that winParams.wnd does not needs to be specified. * _return_ ____ : the created window frame object is returned if succeed. __syntax__ <verbatim>function CommonCtrl.os.window:CreateWindowFrame(winParams)</verbatim> __parameters__ | *winParams* | windows frame parameters. it is the same as first parameter passed to WindowFrame:new2() in ide/windowframe.lua. Except that winParams.wnd does not needs to be specified. | ---++++ !CommonCtrl.os.window:CloseWindow send the WM_CLOSE message to the target window. it's up to the message processor to define its behavior either Destroy() or Show(false) of its associated window frame __syntax__ <verbatim>function CommonCtrl.os.window:CloseWindow()</verbatim> ---++++ !CommonCtrl.os.window:ShowWindowFrame show or hide the windows frame UI. * _param_ __bShow__ : boolean, show or hide the window __syntax__ <verbatim>function CommonCtrl.os.window:ShowWindowFrame(bShow)</verbatim> __parameters__ | *bShow* | boolean, show or hide the window | ---++++ !CommonCtrl.os.window:MoveWindow Changes the position of the control. NOTE: this function will send a WM_SIZE message to the os.window object * _param_ __x__ : new position of the left side of the window. * _param_ __y__ : new position of the top side of the window. * _param_ __width__ : new client area width of the window * _param_ __height__ : new client area height of the window __syntax__ <verbatim>function CommonCtrl.os.window:MoveWindow(x, y, width, height)</verbatim> __parameters__ | *x* | new position of the left side of the window. | | *y* | | | *width* | new client area width of the window | | *height* | | ---++++ !CommonCtrl.os.window:SetWindowText set window frame text and icon * _param_ __text__ : windows title text. __syntax__ <verbatim>function CommonCtrl.os.window:SetWindowText(text, icon)</verbatim> __parameters__ | *text* | windows title text. | | *icon* | | ---++++ !CommonCtrl.os.app:GetMainAppWndName ------------------------------------------------------------- os.app functions:public ------------------------------------------------------------- get the main application's main window name. __syntax__ <verbatim>function CommonCtrl.os.app:GetMainAppWndName()</verbatim> ---++++ !CommonCtrl.os.app:SendMessage send and process a message immediately * _return_ ____ : result is returned __syntax__ <verbatim>function CommonCtrl.os.app:SendMessage(msg)</verbatim> __parameters__ | *msg* | | | *return* | result is returned | ---++++ !CommonCtrl.os.app:PostMessage post to message queue and return, it does not process it immediately __syntax__ <verbatim>function CommonCtrl.os.app:PostMessage(msg)</verbatim> __parameters__ | *msg* | | ---++++ !CommonCtrl.os.app:FindWindow find a window by its name * _param_ __wndName__ : nil or string. if nil, the GetMainAppWndName() is used. * _return_ ____ : the window struct is returned. __syntax__ <verbatim>function CommonCtrl.os.app:FindWindow(wndName)</verbatim> __parameters__ | *wndName* | nil or string. if nil, the GetMainAppWndName() is used. | ---++++ !CommonCtrl.os.app:RegisterWindow register a window. * _param_ __wndName__ : the window name to register. * _param_ __parentWndName__ : the parent window name of wndName. it can be nil, which means no parent * _param_ __msg__ :_handler: nil or function: function MsgProc(message:{wndName, type, param1, param2, ...}) * _return_ __window__ : is returned; __syntax__ <verbatim>function CommonCtrl.os.app:RegisterWindow(wndName, parentWndName, msg_handler)</verbatim> __parameters__ | *wndName* | the window name to register. | | *parentWndName* | | | *msg* | _handler: nil or function: function MsgProc(message:{wndName, type, param1, param2, ...}) | | *handler* | | ---++++ !CommonCtrl.os.app:run CODE is NOT TESTED called as many times as possible in each frame * _return_ ____ : return the number of messages processed. __syntax__ <verbatim>function CommonCtrl.os.app:run()</verbatim> __parameters__ | *return* | return the number of messages processed. | ---++++ !CommonCtrl.os.app:ProcessMessage ------------------------------------------------------------- os.app functions: private ------------------------------------------------------------- process a single message __syntax__ <verbatim>function CommonCtrl.os.app:ProcessMessage(msg)</verbatim> __parameters__ | *msg* | | ---++++ !CommonCtrl.os.CreateApp ------------------------------------------------------------- os functions:public * _param_ __o__ : string or an os.app table e.g. CommonCtrl.os.CreateApp({name="3dscene"}) or CommonCtrl.os.CreateApp("3dscene"); __syntax__ <verbatim>function CommonCtrl.os.CreateApp(o)</verbatim> __parameters__ | *o* | string or an os.app table e.g. CommonCtrl.os.CreateApp({name="3dscene"}) or CommonCtrl.os.CreateApp("3dscene"); | ---++++ !CommonCtrl.os.GetApp Get App. it may return nil __syntax__ <verbatim>function CommonCtrl.os.GetApp(name)</verbatim> __parameters__ | *name* | | ---++++ !CommonCtrl.os.DestroyApp Destory App __syntax__ <verbatim>function CommonCtrl.os.DestroyApp(name)</verbatim> __parameters__ | *name* | | ---++++ !CommonCtrl.os.CreateGetApp first get app and if it does not exist, we will create a new one. * _param_ __name__ : string: app name __syntax__ <verbatim>function CommonCtrl.os.CreateGetApp(name)</verbatim> __parameters__ | *name* | string: app name | ---++++ !HookProc ------------------------------------------------------------- [[ Hook: A hook is a point in the system message-handling mechanism where an application can install a subroutine to monitor the message traffic in the system (including all other applicatoins) and process certain types of messages before they reach the target window procedure or after it. About hook: Hooks tend to slow down the system because they increase the amount of processing the system must perform for each message. You should install a hook only when necessary, and remove it as soon as possible. >> Hook Chains The system supports many different types of hooks; each type provides access to a different aspect of its message-handling mechanism. For example, an application can use the WH_MOUSE Hook to monitor the message traffic for mouse messages. The system maintains a separate hook chain for each type of hook. A hook chain is a list of pointers to special, application-defined callback functions called hook procedures. When a message occurs that is associated with a particular type of hook, the system passes the message to each hook procedure referenced in the hook chain, one after the other. The action a hook procedure can take depends on the type of hook involved. The hook procedures for some types of hooks can only monitor messages; others can modify messages or stop their progress though the chain, preventing them from reaching the next hook procedure or the destination window. >> Hook Procedures To take advantage of a particular type of hook, the developer provides a hook procedure and uses the SetWindowsHookEx function to install it into the chain associated with the hook. A hook procedure must have the following syntax: __syntax__ <verbatim>function HookProc(nCode, appName, msg) end</verbatim> __parameters__ | *nCode* | | | *appName* | | | *msg* | | ---++++ !CommonCtrl.os.hook.Hook:new create a new hook __syntax__ <verbatim>function CommonCtrl.os.hook.Hook:new(o)</verbatim> __parameters__ | *o* | | ---++++ !CommonCtrl.os.hook.Hook:release remove this hook from the hook chain. __syntax__ <verbatim>function CommonCtrl.os.hook.Hook:release()</verbatim> ---++++ !CommonCtrl.os.hook.HookChain.AddHook add a new hook to the chain, it will override hook with the same hookName(swap the new hook to the beginning as well). return the hook added or nil. __syntax__ <verbatim>function CommonCtrl.os.hook.HookChain.AddHook(self, hook)</verbatim> __parameters__ | *self* | | | *hook* | | ---++++ !CommonCtrl.os.hook.HookChain.DeleteHook delete a hook from the chain. * _param_ __hook__ : it needs to contain {hookName="MyHook"} or the hook object returned by SetWindowsHook() __syntax__ <verbatim>function CommonCtrl.os.hook.HookChain.DeleteHook(self, hook)</verbatim> __parameters__ | *self* | | | *hook* | it needs to contain {hookName="MyHook"} or the hook object returned by SetWindowsHook() | ---++++ !CommonCtrl.os.hook.HookChain.Invoke invoke hook chain __syntax__ <verbatim>function CommonCtrl.os.hook.HookChain.Invoke(self, nCode, appName, msg)</verbatim> __parameters__ | *self* | | | *nCode* | | | *appName* | | | *msg* | | ---++++ !CommonCtrl.os.hook.Invoke return nil if hook chain is empty. __syntax__ <verbatim>function CommonCtrl.os.hook.Invoke(hookType, nCode, appName, msg)</verbatim> __parameters__ | *hookType* | | | *nCode* | | | *appName* | | | *msg* | | ---++++ !CommonCtrl.os.hook.SetWindowsHook it installs an application-defined hook procedure at the beginning of a hook chain. You would install a hook procedure to monitor the system for certain types of events. These events are associated either with a specific app or window or with all apps in the desktop. * _param_ __hook__ : the init hook parameters. see CommonCtrl.os.hook.Hook. e.g. {hookType=CommonCtrl.os.hook.HookType.WH_CALLWNDPROC, callback = MyHookProc, hookName = "myhook", appName="paraworld", wndName = "creation"} * _return_ ____ : If the function succeeds, the return value is the hook object. otherwise nil is returned. __syntax__ <verbatim>function CommonCtrl.os.hook.SetWindowsHook(hook)</verbatim> __parameters__ | *hook* | the init hook parameters. see CommonCtrl.os.hook.Hook. e.g. {hookType=CommonCtrl.os.hook.HookType.WH_CALLWNDPROC, callback = MyHookProc, hookName = "myhook", appName="paraworld", wndName = "creation"} | ---++++ !CommonCtrl.os.hook.UnhookWindowsHook removes a hook procedure installed in a hook chain by the SetWindowsHook function * _param_ __hook__ : it needs to contain {hookName="myhook", hookType = CommonCtrl.os.hook.HookType.WH_CALLWNDPROC} or the hook object returned by SetWindowsHook() __syntax__ <verbatim>function CommonCtrl.os.hook.UnhookWindowsHook(hook)</verbatim> __parameters__ | *hook* | it needs to contain {hookName="myhook", hookType = CommonCtrl.os.hook.HookType.WH_CALLWNDPROC} or the hook object returned by SetWindowsHook() | %STOPINCLUDE%
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r1 - 2008-02-29
-
LiXizhi
Home
Site map
CCWeb web
HaqiTeen web
Main web
ParaEngine web
TWiki web
Main Web
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
导航页WebTopMenu
Preferences
开发指南
Getting Started
ParacraftSDK
NPL
MCML
NPL Reference Manual
美术Mod
Account
Log In
English
简体中文
簡體中文
E
dit
A
ttach
Copyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki?
Send feedback