Windows 3.x Library

DESCRIPTION

Call base procedure of ScriptEase-made or subclassed window.

SYNTAX

int BaseWindowFunction(int Handle, int Message, int Param1,
int Param2)

COMMENTS

This calls the base procedure of a window created with a WindowFunction in MakeWindow() or subclassed with SubclassWindow(). This function would normally be used within your ScriptEase window function to pass the window parameter to the base procedure before handling it in your own code. Remember that if your window function returns no value, ScriptEase will call the base procedure automatically. This is the preferred method.

Handle : Window handle for window receiving this message. This must be the window handle of a window created with MakeWindow() or subclassed with SubclassWindow().

Message : The message ID

Param1 : First parameter for this Message ID

Param2 : Second parameter for this Message ID

RETURN

Returns the value returned by the base window function. If Handle is not a window with a WindowFunction created with MakeWindow() or is not window subclassed with SubclassWindow() then returns 0.

SEE ALSO

BreakWindow(), DoWindows(), MakeWindow(), SubclassWindow()

DESCRIPTION

Destroy a window created with MakeWindow(), or remove SubClass.

SYNTAX

bool BreakWindow([int WindowHandle])

COMMENTS

If WindowHandle is a window created with MakeWindow(), then this destroys the window, calling all appropriate Windows' internal DestroyWindow() functions. Any child windows of WindowHandle, as created by earlier calls to MakeWindow() with WindowHandle as the parent, will be automatically destroyed with BreakWindow() before WindowHandle is destroyed. If WindowHandle is a window controlled by SubclassWindow() then this will remove the WindowFunction from the message function loop.

WindowHandle is a handle of a window created with a previous call to MakeWindow(). It is not an error for WindowHandle to be no-longer-valid. If WindowHandle is not supplied, then all windows created with MakeWindow() will be removed. Child windows are always removed before the parent.

RETURN

Returns True if the window was destroyed or un-subclassed, else False. If WindowHandle is not specified then returns True if all windows created with MakeWindow() were destroyed, else False. If WindowHandle is specified and WindowHandle window does not exist, then returns True.

NOTE

If this is a window controlled by ScriptEase using the SubclassWindow() function, and if that window was in turn subclassed by some other program (i.e, subclasses after this ScriptEase subclassed it) then this function cannot remove the window function and BreakWindow() will not succeed.

EXAMPLE

See DoWindows() for an example.

SEE ALSO

BaseWindowFunction(), DoWindows(), MakeWindow(), SubclassWindow()

DESCRIPTION

Process windows messages.

SYNTAX

bool DoWindows([bool Peek = False])

COMMENTS

This function processes windows messages for this application and also allows multitasking to other applications. If Peek is non-zero (default is FALSE) then this returns immediately whether there were messages for this application or not.

If Peek is not supplied or is False, then this function yields control to other applications until a message has been processed (subject to filtering by the MessageFilter() messages) for this application or for any window SubClassed by this application.

NOTE

This function should not be called recursively. That is, you should not call DoWindows() while within a message function processed during a previous call to DoWindows().

RETURN

Returns TRUE if any of the windows created with MakeWindow() are still open (i.e., have not received WM_NCDESTROY), else returns FALSE if no windows are still valid.

EXAMPLE

The following sample ScriptEase program will display a standard Windows window. All messages sent to that window will be logged to the ScriptEase text window. When that window is closed, through any standard Windows closing method, then this program will terminate.

#define WS_OVERLAPPEDWINDOW 0x00CF0000

#define WS_VISIBLE 0x10000000

#define CW_USEDEFAULT 0x8000

if ( MakeWindow(NULL,NULL,"WindowFunction",

"Display Windows' mesages",

WS_OVERLAPPEDWINDOW | WS_VISIBLE,

CW_USEDEFAULT, CW_USEDEFAULT,

CW_USEDEFAULT,CW_USEDEFAULT, NULL,0) ) {

while ( DoWindows() ) ;

}

WindowFunction(hwnd,msg,wparm,lparm,counter)

{

printf("\nMessage: hwnd = %04X, msg = %04X,

wparm =%04X, lparm = %08X", hwnd, msg, wparm, lparm);

}

SEE ALSO

BaseWindowFunction(), MakeWindow(), MessageFilter(), SubclassWindow()

DESCRIPTION

Call a function in a Dynamic Link Library (DLL).

SYNTAX

int DynamicLink(string LibraryName, string ProcedureName,

int ReturnType, int CallingConvention,...)

int DynamicLink(string LibraryName, int ProcedureOrdinal,

int ReturnType, int CallingConvention,...)

COMMENTS

There are three versions of DynamicLink(): one for OS/2, one for Windows 3.x, and one for Windows `95 or NT. These three versions differ slightly in the way they are called, so if you wish to use the function in a script that will be run on different platforms you must create an operating system filter with the preprocessor directives #if, #ifdef, #elif, #else, and #endif.

DynamicLink() is a flexible method for making calls to dynamic link libraries (DLLs). If an operating-system function is needed but is not provided explicitly by ScriptEase. If you know the proper conventions for the call, then you can wrap a ScriptEase routine around a call to DynamicLink, and the call becomes available.

LibraryName is the name of the dynamic link library that the procedure is located in.

ProcedureName is the name of the procedure in the ModuleName dynamic link library, if this procedure can be referenced by name.

ProcedureOrdinal is the ordinal number of this procedure in the ModuleName dynamic link library.

ReturnType tells ScriptEase what type of value the procedure returns, so that it can be properly converted into an int. The Return Types (such as SWORD16, UWORD32, etc...) are defined in the fread() function in the ScriptEase standard library.

CallingConvention may be any of the following:

CDECL Push right parameter first; Caller pops parameters.

PASCAL Push left parameter first; Callee pops parameters. This is the most common type.

All parameters following CallingConvention will be passed to the dynamically-linked function. If the parameter is a blob or a byte-array or an undefined value, it will be passed as a far pointer. Otherwise, all numeric values will be passed as 16-bit values. If 32-bits are needed the parameter will have to be passed in parts, with the low word first and the high word second for CDECL calls, and the high word first and low word second for PASCAL calls.

COMMENTS

If a parameter is undefined when DynamicLink() is called, then it is assumed that the parameter is a far pointer that will be filled in (i.e., the far address of a data element is passed to the function, and that function will set the value). If any parameter is a structure, then it must be a structure that defines the binary data types in memory to represent the following variable. Before calling the DLL function, the structure will be copied to a binary buffer as described in BLObPut() and fwrite(). After calling the DLL function, the binary data will be converted back into the data structure according to the rules defined in BLObGet() and fread(). Data conversion will be performed according to the current _BigEndianMode setting (see fread()).

RETURN

Any of these calls return the value returned by the dynamically-linked function as interpreted according to ReturnType.

EXAMPLE

This example function would call the Windows MessageBeep() function:

#define MESSAGE_BEEP_ORDINAL 104 DynamicLink("USER.EXE",MESSAGE_BEEP_ORDINAL,SWORD16,

PASCAL,0);

This example displays a simple message box, and waits for user to press Enter:

#define MESSAGE_BOX_ORDINAL 1

#define MB_OK 0x0000

// Message box contains one push button: OK.

#define MB_TASKMODAL 0x2000

// Must respond to this message

DynamicLink("USER.EXE",MESSAGE_BOX_ORDINAL,SWORD16,

PASCAL, NULL,"This is a simple message box",

"Title of box", MB_OK | MB_TASKMODAL);

This accomplishes the same thing:

#define MB_OK 0x0000

// Message box contains one push button: OK. #define MB_TASKMODAL 0x2000

// Must respond to message

DynamicLink("USER","MESSAGEBOX",SWORD16,PASCAL,

NULL,"This is a simple message box",

"Title of box", MB_OK | MB_TASKMODAL);

DESCRIPTION

Get ScriptEase instance for this session.

SYNTAX

int Instance()

RETURN

Returns instance for this ScriptEase session.

DESCRIPTION

Define and create a window.

SYNTAX

int MakeWindow(int Parent, struct Class OR string Class,
string WindowFunction, string Text,
int Style, int Column, int Row, int Width,
int Height, BLOb CreateParm[,var UtilityVar])

Make a window for processing during later calls to DoWindows(). The WindowClass is registered if it is an unknown class, and the WindowFunction is called by Windows for every Windows message. This is a complex function and forms the basis for all that you generally see in a Windows program.

Parent is the window handle of the parent for this new window. It is NULL to make the Window not have a parent (the desktop is the parent).

Class identifies the behavior of this window. If Class is a string then it must be the name of a pre-existing Windows class, such as "edit" or "button". If class is a structure then the window behavior is taken from the fields you choose to set in the structure. Any structure members that you don't set or are undefined get the default value as described below. If struct Class is undefined or is NULL then all structure elements get default values.

The member elements of struct Class are:

.style Windows class style; default CS_HREDRAW | CS_VREDRAW

.icon Icon to appear when window is minimized; default NULL for no bitmap icon

.cursor Cursor to appear when over this window; default is LoadCursor(NULL,IDC_ARROW)

.background Background color of this window; default is GetStockObject(WHITE_BRUSH)

WindowFunction is the name of a ScriptEase function that will be called every time Windows sends a message to this new window. If WindowFunction is NULL then no ScriptEase function is called. The Windows default functions will be called.

Your defined WindowFunction should return an integer or return nothing, and must have this format:

int WindowFunction(Handle, Message, Param1, Param2,

UtilityVar)

COMMENTS

Handle : Window handle for window receiving this message

Message : The message ID

Param1 : First parameter for this Message ID

Param2 : Second parameter for this Message ID

UtilityVar : This is the variable optionally supplied to the MakeWindow() function for this window. Any structure member defined there is available here. If UtilityVar was undefined, NULL, or not given to MakeWindow() then this will be an undefined variable.

You can handle Windows messages however you wish. Act upon them or ignore them. You can also use or alter UtilityVar. If your function returns a value, then the default Windows function is not called. If your WindowFunction DOES NOT return a value, then the default Window function or the string Class default function is called. WindowFunction is always called before the default function, except when the String Class is used. When the String Class is used, WM_CREATE messages (and other messages sent during Windows' calls to the CreateWindow() function) are not received by your function.

Note that MultiTask is OFF when this function is called; no other window will get processor time until your routine is done.

Text is the window caption or text. This may be set to NULL.

Style is the window style, as defined by the WS_xxxx values in Windows.lib.

Col and Row describe the upper-left corner for the window when it is created. Use CW_USEDEFAULT to let Windows choose the position.

Width and Height describe the window size. Use CW_USEDEFAULT to let Windows choose the position.

CreateParm is an integer or a BLOb to data to pass with the WM_CREATE message. It is usually NULL.

UtilityVar is any variable that you choose to make available to the WindowFunction. This may be any kind of variable, including a structure if you want to pass many values to the WindowFunction. WindowFunction may also alter UtilityVar. If this parameter is not supplied, then no such function will be available to the WindowFunction().

ExtendedAttributes is one or more of the following, joined with a bitwise or (|):

WS_EX_DLGMODALFRAME 0x00000001L

WS_EX_NOPARENTNOTIFY 0x000000004L

WS_EX_TOPMOST 0x000008L

WS_EX_ACCEPTFILE 0x000000010L

WS_EX_TRANSPARENT 0x000000020L

MODIFY

Your WindowFunction() may modify UtilityVar.

RETURN

On success, returns WindowHandle of the created window. Returns NULL for failure.

EXAMPLE

See DoWindows() for an example.

SEE ALSO

DoWindows(), BaseWindowFunction(), MessageFilter(), SubclassWindow()

DESCRIPTION

Restrict message handled by ScriptEase window functions.

SYNTAX

int[] MessageFilter(int WinHandle ,int MessageID1
[, int MessageID2 [, int MessageID3[,...]]])

int[] MessageFilter(int WinHandle, int[] MessageIDs)

int[] MessageFilter(int WinHandle) // remove all message filters

COMMENTS

This function restricts the messages handled by ScriptEase for a window created with MakeWindow() or subclassed with SubclassWindow(). When Windows sends lots of messages, but you're only interested in handling a few of them within ScriptEase code, you can increase performance by specifying only those messages you want to handle in MessageFilter(). Any messages that have not been specified to MessageFilter() will not be handle by your WindowFunction and might not cause DoWindows() to return immediately (if Peek==False). Initially, there are no message filters so all messages are processed by ScriptEase.

To remove all message filters, so that all messages are passed through to the ScriptEase handler, use the third form of MessageFilter().

WinHandle is handle for a windows created with MakeWindow() or subclassed with SubclassWindow().

MessageID1 , MessageID2 ,... are messages to be added to those being filtered.

MessageIDs is an array of messages to be added to those being filtered.

RETURN

Returns an array of messages begin filtered prior to taking this call. Returns NULL if no messages are in the filter (i.e., all messages are passed through to ScriptEase functions) or if WinHandle is not a handle from a MakeWindow() or SubclassWindow() window.

SEE ALSO

DoWindows(), BaseWindowFunction(), MakeWindow(), SubclassWindow()

DESCRIPTION

Turn Windows multitasking on or off

SYNTAX

void MultiTask(bool)

COMMENTS

Normally, multitasking is enabled. You should only turn multitasking off for very brief, critical sections of code. No messages are received by this program or any other program while multitasking is off.

MultiTask() is additive, meaning that if you call MultiTask(FALSE) twice, then you must call MultiTask(TRUE) twice before multitasking is resumed.

EXAMPLE

The following section of code empties the clipboard. Multitasking is turned off during this brief interval to ensure that no other program tries to open the clipboard while this program is accessing it.

MultiTask(FALSE);

DynamicLink("USER","OPENCLIPBOARD",SWORD16,

PASCAL,ScreenHandle());

DynamicLink("USER","EMPTYCLIPBOARD",SWORD16,PASCAL);

DynamicLink("USER","CLOSECLIPBOARD",SWORD16,PASCAL);

MultiTask(TRUE);

DESCRIPTION

Get Windows' handle for the ScriptEase text screen.

SYNTAX

int ScreenHandle()

RETURN

Returns handle the for ScriptEase text window corresponding to stdout.

DESCRIPTION

Get or set the height and width of the screen.

SYNTAX

struct ScreenSize() // this version is the same as the one in the
// ScriptEase extended library

struct ScreenSize(int col, int row [, int RowsRemembered])

COMMENTS

Gets or set the size of the visible screen in rows and columns. If no parameters are supplied, this simply gets the screen size, else sets screen size to column width and row height. RowsRemembered specifies how many rows the user can scroll to above the visible screen. If RowsRemembered is not supplied, then this parameter does not change from earlier calls. When ScriptEase initializes, this value defaults to 100.

RETURN

Returns the screen size as a structure with the two elements:

.col screen width, in characters

.row screen height, in characters

SubClassWindow

DESCRIPTION

Hook into Window function for any window.

SYNTAX

bool SubclassWindow(int WindowHandle,
string WindowFunction[,var UtilityVar])

COMMENT

This function will hook the specified WindowFunction() into the message loop for this window such that your function is called before the window's default or previously-defined function. WindowHandle is the window handle of the existing window to subclass.

WindowFunction is the same as in the MakeWindow() function. See MakeWindow(). Note that, as in the MakeWindow()function, if this function returns a value, then the default or subclassed function is not called. If this function returns no value then call is passed on to the previous function. This function may be used to subclass any Window that is not already being managed by a WindowFunction for this ScriptEase instance. If the windows was created with MakeWindow() or is already SubClassed then this function will fail.

Note that this function may be used (but only once) with the window handle returned by ScreenHandle(). If you want to SubClass the main ScriptEase window, it is best to open another instance of ScriptEase and SubClass that rather than to subclass the instance that is powering your script. (Although it is possible to subclass that window, if you try to do anything with it you'll most likely get caught up in an infinite loop and hang). To undo the window subclassing, or remove WindowFunction from the message loop, then use BreakWindow().

MODIFY

Your WindowFunction() may modify UtilityVar.

WARNING

In your function that handles messages for another process, certain limits are set as to what you can do with system resources. For example, an open file handle will be invalid while processing another program's message, because Windows will map any file handles into a table for that other program. To work around this problem, you may want to send a message to one of your ScriptEase windows to handle the processing; this will switch Windows' tables to your program while handling that SendMessage() to yourself.

RETURN

Returns boolean False if WindowHandle is invalid, was created with MakeWindow(), or is already Subclassed with this function; else return boolean True.

SEE ALSO

DoWindows(), BaseWindowFunction(), BreakWindow(), MakeWindow(), MessageFilter()

DESCRIPTION

Retrieve list of window handles.

SYNTAX

int[] WindowList([int WinHandle])

COMMENTS

This function returns a list of parent window handles if WinHandle is not supplied or if WinHandle is NULL, else it returns an array of all child windows of WinHandle.

RETURN

Returns NULL if no window handles, else returns array of handles.