Chaining Actions and Specifying Parameters

In order to use the hierarchy of objects in complicated ActiveX servers, and to accommodate some of the syntax you may find in examples of their documentation, APL+Win provides some alternate syntax possibilities for use with these objects. (The statements in this section are a shortening of the sequential steps in the example above that use redirection.) To see the examples, invoke Excel and make it visible:

      'xl' Œwi 'Create' 'Excel.Application'
xl

      'xl' Œwi 'xVisible' 1

Chaining Actions

Instead of using multiple steps or calling Œwi recursively in the same statement, you can chain a series of actions separated by periods as the right argument to Œwi. Each action except the last must result in an ActiveX object, either one you create or one you identify. The first action is taken on the named object identified (either explicitly or implicitly) as Œwself. Each subsequent action is taken on the object resulting from its immediate predecessor action. 

The first statement below demonstrates two steps explicitly by using two invocations of Œwi. The first invocation, inside the parentheses, creates a Workbooks collection, which becomes the left argument to the second, which adds a single Workbook. The subsequent statement is equivalent, doing the same thing by chaining actions. 

      © ('xl' Œwi 'xWorkbooks') Œwi 'XAdd'

      'xl' Œwi 'xWorkbooks.XAdd'
1685900

For purposes of this ActiveX discussion, an action can be either a property or a method. While it may not be obvious that referencing a property is an "action," simply invoking the property name can have the effect of creating (or identifying) an object, in this example, a Workbooks collection. The method that follows is an action upon that collection, but the new object, the one being added, is a single member of that collection, a Workbook. When you are chaining actions, there can be any number (so long as there is a meaningful sequence) of properties and/or methods, but they must be properties or methods of the ActiveX objects themselves, not the APL+Win properties or methods that are added to ActiveX objects.

As mentioned earlier, Microsoft built the Excel application as a cascade of ActiveX objects. You can identify an object in various ways; most collections (of which Workbooks is an example) have a property named Item that identifies an instance of a member of the collection (a single Workbook in this case). Each instance has a name, not surprisingly contained in a property called Name. These three statements are equivalent:

      'xl' Œwi 'xWorkbooks.xItem(1).xName'
Book1

      'xl' Œwi 'xWorkbooks(1).xName'
Book1

      'xl' Œwi 'xWorkbooks().xName' 1
Book1

Specifying Parameter Values

Although a range of cells is really a part of a Worksheet, which is an item of a Worksheets collection object, which in turn is part of the Workbook item, you can identify a range as a property of the application. You can reference or set the values of a range using its Value2 property. The next three statement show equivalent ways of identifying a range, by nesting Œwi calls, by specifying the range with the property name, and by specifying the range parameters as a separate argument. 

      ('xl' Œwi 'xRange' 'A1:C4') Œwi 'xValue2' (³4 3½¼12)

      'xl' Œwi 'xRange("A1:C4").xValue2' (³4 3 ½10+¼12)

      'xl' Œwi 'xRange().xValue2' "A1:C4" (³4 3½100+¼12)

In some cases, you can use parameters with the property or method and associate the arguments with them. Here are two examples of saving the workbook. In the first, you save with the name XXX.XLS and add the name to the "most recently used" files list. In the second, you save with the name FOO.XLS, but do not add the name to the MRU list. (As a reminder, the prefatory 'x' is not necessary unless the name would conflict with a built-in APL WI action name.)

      'xl' Œwi 'DisplayAlerts' 0

      'xl' Œwi 'ActiveWorkbook.SaveAs(FileName,AddToMru)' 'xxx.xls' 1
1

      'xl' Œwi 'ActiveWorkbook>.wkbk'

      'xl.wkbk' Œwi 'SaveAs(AddtoMru,FileName)' 0 'foo.xls'
1

Note that when you specify the names and the values, you can specify them in any order. In some cases, the interface has a default sequence of arguments. When this is the case, you can simply supply the values, in the established order, without specifying the names at all.

When you are specifying a single parameter within parentheses, you can also use the "property=value" notation. In this case, property is the name of the parameter to be assigned, and value can be any of a numeric value, a named constant, or a string. You can use the equal sign as a separator between the name and the value; or you can use a colon (name:number); or you can use the colon and equal sign (name:=string). Note that the colon used in separating a property name from the value is a different kind of separator than in the earlier example of specifying the range, where it is distinguishing the parts of a two-part value.

Chaining and Specifying Parameter Values

You can also use the "property=value" notation in chaining actions; in these cases, you must use the equal sign as the separator between the property name and its value.

      'xl' Œwi 'xRange("A1:C4").xColumnWidth=10.5'

      'xl' Œwi 'xRange("D1:E2").xWrapText=True'

      'xl' Œwi 'xWorksheets(1).xName="Examples"'

Chaining with Multiple Names on Both Sides of Œwi

When you have multiple names in both the left and right arguments to Œwi, there are more possibilities with ActiveX objects than with the built-in APL+Win classes. The differences hinge on the nature of the first name in the right argument (whether it is an object name or an action, such as a property or method) and whether there is a leading period. Note that it is the first name in the right argument; that is, whether it is established as the APL+Win name of an object. There is a difference between the 'xItem' property of a collection that represents the current "Item" of a collection, which item is, in fact, an ActiveX object, and the name 'item' which can be the APL WI name of an object, which may or may not be an item of a collection.

Consider the following statements, where item may have varying meanings; the action of the interpreter is explained in the three conditional steps below each statement. 

With leading period in the right argument	Without leading period in the right argument
'app.collection' Œwi '.item.action'	'app.collection' Œwi 'item.action'
Search for object named app.collection.item; apply action.	Search for object named app.item; apply action (note 1).
If app.collection.item is not defined,       see if action is an "existence" type (note 2); if so, apply action on app.collection.item       treating item as a pending object name.	If app.item is not defined,       see if action is an "existence" type (note 2); if so, apply action on app.item       treating item as a pending object name.
Otherwise, see if app.collection             is an ActiveX object; apply item as an action on app.collection,             followed by action on the result.	Otherwise, see if app.collection             is an ActiveX object; apply item as an action on app.collection,             followed by action on the result.

Note 1. If you do not recognize that an APL+Win statement of this form, where item is an object name, applies to the object 'app.item', review the "Using Relative Object Naming" section in the Programming the Windows Interface: Introduction chapter in this manual.

Note 2. An "existence" action is one of the built-in methods, New, Create, or Delete, or built-in properties, def or self. These actions do not signal an error if the object to which they are applied does not exist.

Note 3. When you are chaining actions on an ActiveX object, you may not use multiple consecutive periods in the right argument.

Note 4. You may supply more than two actions in the right argument, or you may supply multiple object names in a parentage chain followed by one or more actions. However, each action prior to the last must return an ActiveX object as a result; that is, it must either create or identify an ActiveX object upon which the next action is valid.