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.