LScript v2.7 Release Notes

Features | Bug Fixes

New Features

      Scripts can now use the StatusMsg() CS command (added to LightWave 8).  This command allows
      a script to display a message in Layout's "tooltip" area on the main interface without requiring
      any user interaction (e.g., pressing a button to dismiss a dialog box).

      In addition, the text message you provide can be prefaced by a meta-character sequence consisting
      of a floating point value between 0.0 and 1.0, enclosed within curly braces.  If this value is
      present, it will cause the message displayed to have a background progress bar drawn as well.
      For example:

                "{.25}Loading object..."

      This message would be displayed with 25% of the text background in a different color.  By
      repeatedly calling StatusMsg() with an increasing value in this area, your script can
      animate a progress status bar along with the message.

                  generic
                  {
                      for(x = 1;x <= 100;x++)
                      {
                          StatusMsg("{" + x/100.0 + "}This is a test");
                          sleep(100);
                      }

                      StatusMsg("Done!");
                  }
      Starting with this version of LScript, scripts are full-fledged members of the Communication Ring
      system.  The Communication Ring is a mechanism that has been added to LightWave 8, and it allows
      plug-ins to effeciently intercommunicate events, and even exchange data along with those events.
      LScripts can also partake in that mechanism.  (Please refer to the LightWave plug-in SDK
      documentation for a more robust explanation of the Communciation Ring system.)

      To support this system, several new commands have been added:

          comringattach(<topic>,<callback>)

              Opens a channel to the specified Communication Ring.  Each ComRing is identified by a
              unique topic, which is a character string.  The first subscriber to a ring creates it,
              and the last to detach causes its destruction.

              In addition, you must define a callback UDF to be invoked whenever events are generated
              on that particular ComRing by other subscribers.  This callback will accept two values,
              the event code (integer) and a data pointer (internal type) for the generated event.
              The internal data pointer is processed using the comringencode() and comringdecode()
              functions (explained later).

          comringdetach(<topic>)

              When a script is completed with its subscription to a ComRing (such as when it terminates),
              it should detach from each ComRing to which it is attached.

          comringmsg(<topic>,<code[,<data>])

              Generates an event on the specified ComRing.  All other subscribers on the ring will
              receive notification of the event, and process the event at that time.  It is important
              to point out that events are not cached -- events are processed when they arrive.  So,
              processing of a ring event should be completed as quickly as possible.

              The event code is simply an integer value that has some meaning as an identifier
              for the event.  This value is completely user-defined.

              The data value is optional.  However, if you do wish to transmit data to another
              plug-in, the value you provide here can only have come from the comringencode()
              function.  Any other kind of data will generate a run-time error.

          comringencode(<datalist>,...)

              This function will take a variable list of data and encode it into an in-memory form that
              can be accessed by other plug-ins.  The arrangement of the data will allow it to be
              accessed by a structure type-cast in a C plug-in.  If you are sending the data to
              any other active LScript on the ring, that LScript should use the comringdecode()
              function to extract the data.

              The datalist is an array of character strings that identify the target data
              types.  Data types can be "s" for string, "i" for integer, "f" for float, and "d" for
              double.  In the case of string values, you must specify a size for the character buffer.
              This size value is specified by appending a colon and an integer size value to the data
              type metacharacter.  For example, a string value to be stored in a character buffer of
              200 bytes would be specified as "s:200".

              In addition, you can specify a count for the data types to be processed.  A count
              value is specified using a pound sign.  So, for example, if the data you need to
              process consists of an array of three strings, each contained in a 200-byte buffer,
              an integer value, and five floating-point values, your datalist would look like
              the following:

                  "s:200#3","i","f#5"

              The above datalist sequence would encode to an internal memory value that could
              be accessed with the following C structure:

                  struct
                  {
                      char    buf[3][200];
                      int     ival;
                      float   fval[5];
                  };

              When you specify a count for a particular data data type, you must provide an array or
              initblock in that position of the provided data list to be processed.  A run-time error
              will occur if an array or initblock is not found where a count value is specified.

              The data value returned by comringencode() can only be used in the call to
              comringmsg() as the data value.

          comringdecode(<datalist,<data>)

              This function is used to extract data from a data value included with a ComRing
              event.  The datalist provided should define the type and order of the data found
              in the data value.

              Values decoded are returned as a stream of elements, so you can store them all into a
              single array variable, or you can use associative assignment to extract elements into
              individual variables.

      The "ComRing" SDK sample project shows this mechanism in action.  A Master LScript controls the
      appearance of a C-code Custom Object plug-in in real-time, and illustrates two-way data exchange.

      LScript v2.7 provides hooks in its functionality for a rather interesting new feature: URL file
      referencing.  Currently, this functionality will be employed by LScript in cases where external
      script components are referenced (Object Agents, include files, etc.).

      In order to activate this functionality, you must first acquire the shared-library build for
      your platform of the W3C code distribution called libwww.

      Once you have these files (numbering approximately 26 *.dll files for the Windows distribution),
      they must be placed in the "w3c" subdirectory of the LScripts/ installation directory.  For
      example, if you have installed LightWave in "C:\LightWave", then the libwww files must be
      placed in "C:\LightWave\LScripts\W3C" in order to activate this dormant LScript functionality.

      Once the W3C files are correctly located and loaded into LScript, your script can specify URL
      references for script components instead of local filenames.  For instance, a script could then
      reference an Object Agent include file published on an HTTP server as:

                ...
                @include "http://www.myobjectagents.com/cooloa.inc"
                ...

      Further, inside the referenced include file, the Object Agent declaration line would then utilize
      a URL instead of a file path to bring down the actual Object Agent binary file from the HTTP
      server:

                ...
                use "http://www.myobjectagents.com/cooloa.oal" as class CoolOA;
                ...

      As with Web pages in your favorite brower, files retrieved from an HTTP server in this fashion are
      cached locally on your machine (in the same folder as the W3C directory).  Each time the files are
      referenced by URL, the local file dates are checked with the HTTP server, and files with newer dates
      are refreshed locally.  In this way, the component publisher has only to update the files on their
      HTTP server, and all people using them will receive the updates automatically the next time any
      script referencing them is executed.

      URL file referencing is really more of an experimental feature
      because cross-platform usage is not necessarily guaranteed (it
      has only been successfully tested under the Windows operation system).
      Requester Control Object Agents now have a size(<w>,<h>) method that will allow you to
      change the width and height attributes of a control.  For best results, you should first hide
      the control before you change these attributes, and then make it visible once again.

| Bug Fixes | (top)

      The matchdirs() command was miscounting found subdirectories on the Mac, resulting
      in a nil return value.
      Requesters that used Icon Objects were not properly clearing those icons from
      the system when the Requester was dismissed.  This left the system progressively
      unstable as the same script was run over and over, leading a display of garbage
      instead of icons, or a crash of the application.