Buffer Object

The Buffer object provides a way to manipulate data at a very basic level. It is needed whenever the relative location of data in memory is important. Any type of data may be stored in a Buffer object. A new Buffer object may be created from scratch, from a string, another Buffer object, or from most any data type or object (see global.ToBuffer()).

(See the helper file buffer.jsh for enhancements to the Buffer object.)

ScriptEase 5.00 introduced an important change in buffers. Prior to version 5.00 ScriptEase JavaScript had a buffer data type, as well as, a Buffer object. Beginning with ScriptEase 5.00, buffer data types no longer exist, only the Buffer object. The scripts distributed with ScriptEase Desktop have been updated to reflect the changes, but users might have some personal scripts that need changing. So, some key differences in working with buffers as objects only, without a unique data type, are discussed now.

First, many (probably most) script statements, using buffers, do need to be changed. All of the Buffer and Blob methods still work as they did before. The primary difference is in the use of the Buffer() function without the new constructor, the use of the data property in a Buffer object, and the use of the length and size properties.

Previously, the Buffer() function returned a buffer data type and the new Buffer() constructor returned a Buffer object. The data property of the Buffer object could be used to access the actual buffer data in the object. The length property could be used with a buffer data type to get the length of a buffer. Now both Buffer() and new Buffer() return a Buffer object, and the data property no longer exists. Plus, only the size property may be used to get the size or length of a buffer. The following fragments illustrate these differences.

Prior to ScriptEase 5.00

var b1 = Buffer("abc");     // b1 is buffer data type

var b2 = new Buffer("abc"); // b2 is Buffer object

Screen.writeln(b1);         // abc

Screen.writeln(b1.data);    // abc

Screen.writeln(b1.length);  // 3

Screen.writeln(b2.length);  // 3

Screen.writeln(b2);         // abc

Screen.writeln(b2.data);    // abc

Screen.writeln(b1.size);    // 3

Screen.writeln(b2.size);    // 3

Starting with ScriptEase 5.00

var b1 = Buffer("abc");     // b1 is Buffer object

var b2 = new Buffer("abc"); // b2 is Buffer object

Screen.writeln(b1);         // abc

Screen.writeln(b1.data);    // undefined

Screen.writeln(b1.length);  // undefined

Screen.writeln(b2.length);  // undefined

Screen.writeln(b2);         // abc

Screen.writeln(b2.data);    // undefined

Screen.writeln(b1.size);    // 3

Screen.writeln(b2.size);    // 3

Most ScriptEase functions and methods are now smart enough to handle Buffer objects as they once did buffer data types, but small changes might be needed in some places. For example, previously, some SElib.dynamicLink() calls required a buffer data type. But now a Buffer object may be used. So if you have code (prior to ScriptEase 5.00) like:

var buf = Buffer(256); // creates a buffer data type

SElib.dynamicLink("user32", "GetClassNameA", STDCALL,

                  this.handle, buf, buf.length);

this.className = buf.getString();

return this.className;

With code starting after ScriptEase 5.00, the fragment above should work with the one correction, length to size, as shown in bold.

var buf = Buffer(256); // creates a Buffer object

SElib.dynamicLink("user32", "GetClassNameA", STDCALL,

                  this.handle, buf, buf.size);

this.className = buf.getString();

return this.className;

The example above is taken from the Window.prototype.getClassName() instance method definition in winobj.jsh. To illustrate changes due to the use of the data property, we take our example from the Window.prototype.getClientRect() instance method defined in winobj.jsh. Prior to ScriptEase 5.00 it was defined as:

var rtn;

var Rect = new Buffer(4+4+4+4);  // hold 4 integers of 4 bytes

if (rtn = SElib.dynamicLink("user32", "GetClientRect", STDCALL,

                            this.handle, Rect.data))

{

   this.client.left   = Rect.getValue(4);

   this.client.top    = Rect.getValue(4);

   this.client.right  = Rect.getValue(4);

   this.client.bottom = Rect.getValue(4);

}

In ScriptEase 5.00 it needs to be corrected in one place: the removal of the data property.

return rtn != NULL;

var rtn;

var Rect = new Buffer(4+4+4+4);  // hold 4 integers of 4 bytes

if (rtn = SElib.dynamicLink("user32", "GetClientRect", STDCALL,

                            this.handle, Rect))

{

   this.client.left   = Rect.getValue(4);

   this.client.top    = Rect.getValue(4);

   this.client.right  = Rect.getValue(4);

   this.client.bottom = Rect.getValue(4);

}

return rtn != NULL;

Buffer object instance properties

Buffer object instance methods

Buffer object static methods