Lotus 1-2-3 ADK - CMDID.TXT

This file includes information about:
 - using command IDs to access 1-2-3 specific functionality.
 - how to find the ID for a given LotusScript property.
 - inheritance used in 1-2-3 classes and 1-2-3 collections.
 - using flat properties to get quick access to 1-2-3 data.

================================================================================
Using the Command IDs

The file l123cmds.h defines various IDs that can be used to access 1-2-3 methods and properties from an LSX.  These are not individually documented.  Generally there is no need, because they correspond directly to documented Script methods and properties.  If there is a Script 123 method or property named FOO, there will be a corresponding ID named TRTxxxxx_yyyy_FOO.  yyyy will be PROP, CMD or FUNC.  xxxxx might be one of a number of things, but normally there will only be one such.  There are, however, some duplications.  To make the right choice, use the trait associated with the object to be accessed.  The associations between traits and 1-2-3 objects is documented in the files SRTTRTLS.TXT and SRTOBJLS.TXT, sorted by trait and object respectively.  There are some constants defined that are no longer used.  If the trait name contained in a define cannot be found associated with an object, the constants associated with that trait will have no use.

================================================================================
Object Organization

Chart objects and other 123 objects are separate families.  Chart objects have traits named TRTCHxxxx, other 123 objects do not.  (Some Chart objects also share some 123 traits, but no other 123 objects use TRTCHxxxx traits.)  Within the other 123 objects there are script-defined inheritances.  All 123 collections are BaseCollections; in fact most have no other functions.  All other 123 objects are BaseObjects.  Many of the Draw Layer objects are DrawObjects, which then are also BaseObjects.   More information on inheritances is given in the Script documentation.

================================================================================
Flat properties

The Lotus Script interface makes use of objects for ease and uniformity of access among the various suite interfaces.

Subobjects were devised to try to unify the object model for the user across applications that had quite different implementations.  From that standpoint the script user has a more uniform usage across the different suite applications.

Examples include Color, Font and Background.

The documented way of accessing the background color of a range is via MyRange.Background.BackColor and since this itself is an object, one has to refer to MyRange.Background.BackColor.ColorName or .ColorIndex to get or set a scalar property.

In a performance-critical task this is expensive - a canonical color set as above can take about 6 times as long as directly accessing the property.     For cases involving only one depth of subobject (the above has two layers) a factor of 2 to 3 could be expected.

When performance is more critical than uniform usage and documentation the flat properties can be directly accessed.  A table of flat properties and their IDs appears in FLATABLE.TXT.   Using these can perhaps avoid obtaining a subobject handle and avoids the subobject access overhead.

Underline, for instance, is a boolean property of a font object.  So to be objectively proper, you would get a font object for the text in the cell and set its underline property to true.  Instead, look up Underline in FLATABLE.TXT.  One finds that it corresponds to TRTTEXTSTYLE_PROP_TEXTUNDERLINE.  So setting that property on the object that contains a Font subobject is equivalent to setting Underline on the contained Font.

