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

TIP 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()
Topic revision: r1 - 2008-02-29 - LiXizhi
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback