Syntax

bSucceeded = SetBusyHandler(xtra"VbScriptXtra",objHandler)
or
bSucceeded = xtra("VbScriptXtra").SetBusyHandler(objHandler)

Parameters

objHandler - an instance of a parent script that will handle "busy state" messages or VOID.

Returns

true: if successful.

false: if failed.

Description

This method sets the instance of a parent script as a "busy state" handle, which is called when xtra
detects busy condition.

When COM server returns the busy state, xtra calls a method of a handler instance:
on ServerBusy me, milliseconds
where milliseconds indicates the time elapsed since the initial call of the method. The handler can return:
-1 to cancel the call, it most probably produces a Lingo error
0 to immediately retry the call
1 to display system "Server Busy" dialog
>1 to retry the call in the specified number of milliseconds.

While call to COM server is in progress, xtra can detect whether any messages are waiting to be processed by Director application. If so, it calls another method of a handler instance:
on MessagePending me, milliseconds, category
where milliseconds indicates a time elapsed since initial call to the server, category indicates the type of waiting message:
0 - menu or other Windows-level message
1 - keyboard
2 - mouse
This handler should return either 0 (false) to do nothing or 1(true) to display a busy dialog.

To use xtra's default handler set it to void:
xtra("VbScriptXtra").SetBusyHandler(void)

The xtra's default behavior is to wait 10 seconds on ServerBusy by retrying call every 200 milliseconds. Then xtra shows the "Busy" dialog. If important messages (system-level, mouse, keyboard) are detected while COM call is in progress for more than 3 seconds, the xtra also shows "Busy" dialog.

Sample

-- Parent script
on new me
  return me
end

-- Called when server application returned a busy status
-- milliseconds indicates a time passed since initial call to the server
-- Method should return either:
-- -1 to cancel the call, it most probably produces a Lingo error
-- 0 to immediately retry the call
-- 1 to display system "Server Busy" dialog
-- >1 to retry the call in the specified number of milliseconds
on ServerBusy me, milliseconds
  if milliseconds>25000 then
    return 1
  end if
  return 1000
end

-- Called when messages come to Director (keyboard, mouse) while waiting for
server to respond for a call
-- milliseconds indicates a time passed since initial call to the server
-- category indicates the type of waiting message:
-- 0 - menu or other Windows-level message
-- 1 - keyboard
-- 2 - mouse
-- Method should return either 0 (false) to do nothing
-- or 1(true) to display a busy dialog
on MessagePending me, milliseconds, category
  case category of
    0:
      put "Menu or other Windows-level message"
      return 1
    1:
      put "KeyPressed"
      return 0
    2:
      put "Mouse:"&&the mouseLoc
      return 0
  end case
  return 0
end

-- And then somewhere in Lingo:
bSucceeded = xtra("VbScriptXtra").SetBusyHandler(script("BusyHandler").new())