CommonCtrl.os

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

Sample Code

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")

Member Functions

CommonCtrl.os.window:SendMessage

 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,
}

; 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

function CommonCtrl.os.window:SendMessage(targetWndName, typeOrMsg, param1, param2, param3, param4)

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

function CommonCtrl.os.window:GetParent()

CommonCtrl.os.window:GetParentName

get parent window name. it may return nil

syntax

function CommonCtrl.os.window:GetParentName()

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

function CommonCtrl.os.window:GetWindowFrame()

CommonCtrl.os.window:IsVisible

get whether the windows frame is visible more information, please see ide/windowframe.lua

syntax

function CommonCtrl.os.window:IsVisible()

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

function CommonCtrl.os.window:DestroyWindowFrame()

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

function CommonCtrl.os.window:CreateWindowFrame(winParams)

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

function CommonCtrl.os.window:CloseWindow()

CommonCtrl.os.window:ShowWindowFrame

show or hide the windows frame UI.

• param bShow : boolean, show or hide the window

syntax

function CommonCtrl.os.window:ShowWindowFrame(bShow)

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

function CommonCtrl.os.window:MoveWindow(x, y, width, height)

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

function CommonCtrl.os.window:SetWindowText(text, icon)

parameters

text	windows title text.
icon

CommonCtrl.os.app:GetMainAppWndName

---

os.app functions:public

---

get the main application's main window name.

syntax

function CommonCtrl.os.app:GetMainAppWndName()

CommonCtrl.os.app:SendMessage

send and process a message immediately

• return __ : result is returned

syntax

function CommonCtrl.os.app:SendMessage(msg)

parameters

msg
return	result is returned

CommonCtrl.os.app:PostMessage

post to message queue and return, it does not process it immediately

syntax

function CommonCtrl.os.app:PostMessage(msg)

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

function CommonCtrl.os.app:FindWindow(wndName)

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

function CommonCtrl.os.app:RegisterWindow(wndName, parentWndName, msg_handler)

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

function CommonCtrl.os.app:run()

parameters

return	return the number of messages processed.

CommonCtrl.os.app:ProcessMessage

---

os.app functions: private

---

process a single message

syntax

function CommonCtrl.os.app:ProcessMessage(msg)

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

function CommonCtrl.os.CreateApp(o)

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

function CommonCtrl.os.GetApp(name)

parameters

name

CommonCtrl.os.DestroyApp

Destory App

syntax

function CommonCtrl.os.DestroyApp(name)

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

function CommonCtrl.os.CreateGetApp(name)

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

function HookProc(nCode, appName, msg) end

parameters

nCode
appName
msg

CommonCtrl.os.hook.Hook:new

create a new hook

syntax

function CommonCtrl.os.hook.Hook:new(o)

parameters

o

CommonCtrl.os.hook.Hook:release

remove this hook from the hook chain.

syntax

function CommonCtrl.os.hook.Hook:release()

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

function CommonCtrl.os.hook.HookChain.AddHook(self, hook)

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

function CommonCtrl.os.hook.HookChain.DeleteHook(self, hook)

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

function CommonCtrl.os.hook.HookChain.Invoke(self, nCode, appName, msg)

parameters

self
nCode
appName
msg

CommonCtrl.os.hook.Invoke

return nil if hook chain is empty.

syntax

function CommonCtrl.os.hook.Invoke(hookType, nCode, appName, msg)

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

function CommonCtrl.os.hook.SetWindowsHook(hook)

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

function CommonCtrl.os.hook.UnhookWindowsHook(hook)

parameters

hook	it needs to contain {hookName="myhook", hookType = CommonCtrl.os.hook.HookType.WH_CALLWNDPROC} or the hook object returned by SetWindowsHook()