OKScript Status Report #15

November 4, 2001

Dear OKScript User,

The OKScript Status Report is sent to OKScript licensees,
developers and friends when significant updates have been made
to the program. Interesting techniques and applications for the
program will also be distributed in the report periodically. To
update or be removed from the distribution list please see the
links at the bottom of this message.

This issue details how to use OKScript's new mouse features 
(reflected in the 11/1/2001 upload, which is required to run
the example scripts) to automate messages and alerts in the 
e-bridge online service. The methods discussed can be adapted 
to the Zone and any other applications that are resistant to 
the keyboard navigation techniques available in OKbridge.

Although this discussion is lengthy, I believe that you will
find it straightforward to apply and, once the groundwork is 
in place, you will be able to create familiar looking panels
with the same effort as before. 

Let's begin with a typical OKScript BUTTON declaration that we 
will adapt to the e-bridge client:

  BUTTON capp-2D blue OKbridge =Hearts and spades{enter}

(Note, the 'equals sign" restricts the message to just the
opponents, as you would want for a system alert message.)
To make this work with e-bridge we first need to activate 
e-bridge's chat target control and chat bar. Unlike OKbridge, 
e-bridge doesn't have an easy keyboard method to make this 
happen - it expects a mouse click on the desired control. 
OKScript's new mouse features make this possible. Our first
task in making this happen is to determine the X-Y coordinates 
of these e-bridge controls so that we can position the mouse 
correctly. This coordinate value depends on your system's 
screen resolution so rather than just tell you where it is 
on MY screen (which would be of no use to you unless your 
screen resolution is 1024 x 768) I am including the method 
that I used to determine it. This method can also be used to 
setup scripts for the Zone and other services. To start, enter 
(or copy-and-paste) the following instructions into a new 
OKScript page:

  PROC ebmouse
    WINDOW e-bridge
    MOUSE WINXYLOW 275 220
  BUTTON capp-2D blue *ebmouse =Hearts and spades{enter}

The first three lines of this code is a PROCedure that
activates e-bridge's client window and moves the mouse to a 
coordinate relative to the window's lower left corner.
PROCedures allow us to write one piece of script and
use it from many different places which will be very 
handy, as you will see shortly. The BUTTON line has been 
modified to call this PROC by replacing the "OKbridge" field 
with "*ebmouse". The asterisk changes the meaning of this 
particular field in a BUTTON instruction to a PROC call.

To use this script to find the X-Y coordinate of e-bridge's
chat target control (which is the pull-down box to the
left of the chat bar) start by running this panel, 
logging into e-bridge and click the OKScript button.
(Should OKScript disappear behind e-bridge you can use
Window's alt-tab feature to get it back - just hold down
the alt key and hit tab repeatedly until OKScript's icon 
is highlighted and then release the alt key.) You should 
see the mouse pointer jump to SOMEWHERE in the lower part 
of your screen. You want the mouse to land on the chat 
target control - if it doesn't then edit the x-y arguments 
of the MOUSE instruction and try again until it does, 
noting that the mouse moves to the right and up as the 
values of these arguments increase. Zero-ing in may take 
a few tries to get it right - don't worry about precision, 
anywhere in the chat target control will work fine. 

Ok, when you have the mouse landing on the chat target
control add the following three instructions right after 
the MOUSE instruction that you have been playing with:

  MOUSE LEFTDOWN
  MOUSE LEFTUP
  PUT {up}{up}{up}{down}{down}{down}

The new MOUSE instructions simulate a click of the left mouse 
button, the PUT instruction sends three "up arrow"s and three
"down arrow"s to the active input control, which we hope at this 
point will be the chat target control! If everything went 
well the control should have a word highlighted, either "lobby"
if you are in the lobby, or "opponents" if at a table. The 
{up}{up}{up} sequence sets this control to a known state (the
top element of the list) regardless of how it was set initially. 
The subsequent {down}s make a selection from this now initialized 
pull-down list. Controlling this aspect of e-bridge's interface 
allows you to restrict messages to just the opponents (e.g. for 
alerts), to the lobby (for player advertising) or to the table or
the kibitzers, depending on the number of {down}s used.

To send the actual text we will simply extend this technique. 
The chat bar is some distance to the right of the chat target 
control that we've been working with. It can be activated for 
input with another mouse positioning instruction whose X coordinate 
is about 150 units larger. REMEMBER TO USE THE COORDINATES THAT
YOU FOUND ABOVE FOR THE CHAT TARGET CONTROL AS A BASIS, NOT THE 
VALUES SHOWN HERE! Let's add this code to our program - here is 
the whole script with these additions:

  PROC ebmouse
    WINDOW e-bridge
    MOUSE WINXYLOW 275 220
    MOUSE LEFTDOWN
    MOUSE LEFTUP
    PUT {up}{up}{up}{down}{down}{down}
    MOUSE WINXYLOW 425 220
    MOUSE LEFTDOWN
    MOUSE LEFTUP
    PUT test text
  BUTTON capp-2D blue *ebmouse =Hearts and spades{enter}

Clicking this button will insert the words "test text" into the chat
bar but will not send it without an {enter} at the end. Try it now to 
ensure it is working.

So now we can send text to e-bridge. "But it's a nightmare" you 
say, and I agree. Thankfully it is a very simple last step that 
will make most of this messiness go away. I used OKScript's 
PROCedure mechanism in this demonstration instead of putting this 
code directly in the BUTTON handler for a good reason, and that is 
about to pay off. 

In its current form, the ebmouse PROC always sends the same message -
"test text". We would like to have each BUTTON be able to send it's 
own message. This is easy, as a PROC can recieve arguments from the 
BUTTON instructions that call it. The arguments are accessed
with special pre-defined macros - we will use %-args% here. Two simple 
changes to our script are required:

1. replace "test text" with "%-args%" (remove the quotes), thus
  PUT %-args%
2. put the desired message after the *ebridge field in the BUTTON 
  instruction, PRECEEDED BY ONE UNIQUE CHARACTER - we will use the
  hash mark (#) for this purpose. In our test script this means
  simply changing the equal sign (=) to a hash mark.

Here is the whole modified script:

  PROC ebmouse
    WINDOW e-bridge
    MOUSE WINXYLOW 275 220
    MOUSE LEFTDOWN
    MOUSE LEFTUP
    PUT {up}{up}{up}{down}{down}{down}
    MOUSE WINXYLOW 425 220
    MOUSE LEFTDOWN
    MOUSE LEFTUP
    PUT %-args%
  BUTTON capp-2D blue *ebmouse #Hearts and spades{enter}

Notice the changes in the second PUT and BUTTON lines and in 
particular the hash preceeding the message text in the BUTTON line 
that looks odd compared to typical scripts used for OKbridge. This 
character is not sent as a part of the message. The purpose of 
this hash mark involves the posibility of multiple PROC arguments 
and is unnecessary to fully understand for our present discussion. 
For now, use the following rule as a guide:

  PROC arguments MUST be prefixed by a character
  that isn't an OKScript metacharacter and doesn't 
  appear in the actual argument text. (one of 
  < > ; , ? # should work fine.)

Using this framework you can build button panels pretty much just 
like before - simply place the PROC code that we've been working 
on in this discussion ONCE at the top of your script file and add 
as many BUTTON lines as desired. If a BUTTON is to send a multi-line 
message additional PUT lines can be added to a BUTTON in the normal 
fashion.

Most users have some messages that are intended for the table, and 
some for the lobby, and some for just the opponents (e.g. alerts.) 
This is easily accomodated by creating one PROC for each case, the 
only difference between them being the number of {down}s in the PUT 
instruction that selects the chat target item. These PROCs could be 
named, for example, EBlobby, EBtable and EBopps. To adapt your script 
to the Zone you will only need to update these PROCs, the rest of 
your script can probably remain unchanged.

One final simplification is possible. The PROC code can be 
moved to a separate script file named, for example, "procs.oks". 
Whenever this file is loaded into an OKScript editor page you can 
use it in another file by simply including the line:

  USE PROCS

at the top of that file. If you expect to have many different panels 
for use with e-bridge you may want to include procs.oks in the list 
of files that are loaded when OKScript is launched by editing its 
shortcut (icon).  If you are going to use other bridge services that 
require special treatment (e.g. the Zone) it could make sense to put 
their (unique) activation PROCs in this file, or possibly create
separate proc files for each service.


For more information, suggestions or interesting techniques or
applications for OKScript, write me at yweare@gte.net, or visit
the website at http://home1.gte.net/yweare/index.htm

Thank you for supporting the development of OKScript.

Michael Mardesich
okb://mikezzz