What's New in APL+Win 6.4?
(+ detailed description of Release 6.2 & 6.0 enhancements)
This document is an overview of the new features in APL+Win version 6 and covers releases 6.0, 6.2 & 6.4. Features covered are extensions to the language, improvements and changes to the session manager, additions to the graphical user interface (GUI), system interface and other non-GUI related facilities. Much of this document was originally written for the “What’s New in APL+Win version 6.x” document distributed with their respective releases of APL+Win.
APL+Win 6.4
Released October 13, 2006
The xPrintOptions property enables the printing of header rows and columns in APL Grid. You can set this property to 1 for column headers, 2 for row headers or 3 for both column and row headers.
W_Def is used in the same way as W_Ini except that it lets you create WCALL definitions and other strings in your application that are stored into a local cache (memory) rather than written into the INI file.
These strings should also execute faster than W_Ini because no INI file reading or writing is involved. This permits setting WCALL definitions in a running application that might have a read-only INI file.
Note: These definitions are cleared with W_Reset.
The order of reading to access strings for WCALL used to be: Look in INI and if not found then look in ADF (unless the [Config]IniFirst=1 is defined in INI file in which case ADF is accessed before INI). The order of reading to access strings for WCALL always checks the W_Def cache first and then checks the INI and ADF as before. You can get a list of all strings in a section by calling: ŒWCALL'W_Def' '[SectionName]'
You can get a list of all strings in all sections by calling: ŒWCALL'W_Def' '[]' When you reference a string value with W_Ini it has historically never differentiated between strings defined in the INI file versus those defined in ADF file. It returned the value found in either INI or ADF file. I followed that same pattern and referencing a string via W_Ini returns the first definition found in W_Def-cache, INI, or ADF.
W_Reset is a built-in function that resets the WCALL sub-system. This is used to reset the WCALL definition bindings so they can be reloaded without restarting APL+Win.
In this version, the Recent Lines dialog box is non-modal, resizable and can be made to remain on top (via push-pin). Figure 9 shows the Recent Lines dialog.
Figure 9 Recent Lines dialog
The Fetch Objects and Open Objects dialogs now have a resize grip in the lower right corner of the window.
The purpose of this property is to control the behavior of a tooltip set for a control on a Form. The tooltipstyle property must be set before creating any controls on a Form or MDIForm or else the setting might be ignored.
The default value for this property is 0. The settings currently available are:
| 1 |
= |
Always display tooltip when mouse is over the control regardless if the form is not activate. |
| 2 |
= |
Suppress special handling of ampersands (&) in the tooltip property; without this value, a single ampersand will appear as an underscore in the tooltip |
| 64 |
= |
Display tooltip in a balloon style.
Note: this value is experimental in this release.
Known issues:
1) The balloon style tooltip on occasion flicker where the balloon displays, hides, and reappears;
2) the Page doesn’t respect this style value |
Setting ŒWRES[1] set to ¯1 suppresses this message. This also restores the previous cursor (rather than leaving the hourglass showing) when editing doesn't restart.
In version 5.0 of APL Grid, the xNumber property was updated to store full precision numbers without being constrained by limits of text representation. But this precision was not represented in XML data as expected.
This was addressed by adding the hex attribute to the <value> element that stores the numeric value as a hex string if it differs from the formatted value. This is in addition to the raw attribute when the formatted representation and/or raw attribute don't accurately represent the full precision of the data. For example,
Œwself„'form.grid'
Œwi 'xValue' 1 1 (1.23456789012345)
Œwi 'xXml'
...
<row index="1">
<cell row="1" col="1">
<value hex="3ff3c0ca428c59e1" type="number">1.23456789012345</value>
</cell>
...
The xFormatMode property is used to control how currency values are formatted for display in cells in the APL Grid. This is the helpstring for the xFormatMode property:
xFormatMode property:
Value „ ŒWI 'xFormatMode' Rows Cols
ŒWI 'xFormatMode' Rows Cols Value
Cell code; default ¯1;
controls xLocale-based formatting when xFormat not specified
Value: matrix of codes:
¯1 = inherit;
0 = disable
1 = enable for currency
2 = enable for currency (with user overrides)
The value 1 gives formatting according to international locale standards. The value 2 gives formatting that may have been customized by the user on their computer via the regional settings.
This enhancement was inspired by the old behavior of the grid which returned the conversion error value (controlled by the xConversionErrorValue property:
default = ¯2147352572) when a cell containing a non-numeric value were referenced. For example, if a cell had been edited to contain a value such as "abc" or "" and you reference it with xNumber property, it would return the conversion error value.
Users requested that they be able to store error values back into the grid by specifying a numeric value matching the conversion error value. For example, if the conversion error value was 999.999 and you used the xNumber property to reference a cell containing "abc" then the value 999.999 would be returned. They wanted to be able to set the xNumber property with 999.999 and have an error value stored back into the cell in its place. However, since there is no way of knowing from the generic conversion error value what string had actually caused conversion error it is impossible to replace that string back into the grid.
For this reason it did not make sense to use the conversion error value as a signal for storing some error marker back into the grid. Instead we introduced the concept of "missing values" and introduced the xMissingValue and xMissing properties. A cell is considered to have a "missing value" when either of the following conditions is true:
- The cell is undefined (no properties ever set for the cell or it has been deleted)
- The cell contains an empty string value (i.e., the xText property would return an empty string value for that cell).
A cell can get into the second missing state (defined with an empty string value) in several ways:
- Set the xText property with an empty string value ("")
- Set the xNumber, xDate or xCurrency property with an empty string value (''). Note that this used to give an error. However, trying to store a string that is not empty but contains all blanks is not considered a missing value and still causes an error.
- Set the xNumber, xDate or xCurrency property with a numeric value that matches the xMissingValue state of the grid.
- Paste an empty string value into a cell from the clipboard.
- Edit cell value and store an empty string into cell.
xMissingValue property:
Value „ ŒWI 'xMissingValue'
ŒWI 'xMissingValue' Value
Grid value; (default=0);
Value used to denote missing numeric values;
Zero (default) means no missing value
Value: numeric scalar or empty string ("")
The xMissingValue property allows you to control what value is returned when you reference a cell containing an empty string value using the xNumber, xDate, or xCurrency properties. As with the xConversionErrorValue, the xMissingValue property applies to the whole grid. This value is also returned when you reference the xValue property for a numeric type cell that is missing. However, the xMissingValue is NOT returned when you reference an empty cell with the xText property. In that case an empty string ("") is always returned. Similarly, referencing an empty text cell via the xValue property returns an empty string ("").
The xMissingValue property has a default value of zero (0) which means "not defined". In this case the missing value is not defined and no numeric value is recognized as "missing". However, you can still store missing values into cells by setting the xNumber, xDate, or xCurrency property with empty string values (""). However, when such numeric missing cells are referenced via xNumber, xDate, xCurrency, or xValue they return the xConversionErrorValue when xMissingValue is undefined since they cannot be represented by a numeric value.
However, if the xMissingValue is not defined, then a xConversionErrorValue is returned (as before) for the cases above that would have returned an xMissingValue. The xConversionErrorValue is never returned by the xText property nor by the xValue property when referencing text type cells. This means that unless you set the xMissingValue the behavior is exactly as before with the exception that you can specify empty string argument values with the xNumber, xDate and xCurrency properties.
The xMissingValue property also controls what value is recognized as the missing value when you set a numeric value in the xNumber, xDate, xCurrency, or xValue property. However, when you set the xText property with a numeric value it is NOT recognized as a missing value even if its value matches the xMissingValue setting. This is done for historical reasons since numeric values stored into the xText property have always been converted into string values representing the number. So a 999 is stored as a "999" text string. Similarly, but with the opposite effect, string values such as "999" have always been accepted as an argument when setting the xNumber, xDate, or xCurrency property and converted to a numeric value. Therefore string values whose numeric representation matches the xMissingValue are interpreted as missing when setting the xNumber, xDate, and xCurrency properties.
xMissing property:
Value „ ŒWI 'xMissing' Rows Cols
ŒWI 'xMissing' Rows Cols Value
Cell flag; boolean flag indicating whether cell
is not loaded (empty) or contains a missing value;
1 = missing; 0 = not missing;
Value: boolean matrix of flags (one value per cell)
The xMissing property allows you to query which cells are missing or to make cells missing. It specifies a set of rows and columns on the current page to be set or queried regarding their missing state.
Querying the xMissing property returns 1 for any cell that is considered missing (based on the rules outlined above). Namely this means cells that are not defined (empty) or has an empty string value stored in them (""). It returns 0 for cells that contain non-empty string values (including values for numeric cells that are not valid numbers and would result in a conversion error).
Setting the xMissing property clears the string content of any cells you specify as one (1) to an empty state. It does not touch cells you specify as zero (0). So you can view this as doing a logical OR operation on the missing state of the cells.
APL+Win 6.2
Released July 17, 2006
Unique is a monadic function that selects the unique elements of a vector. Its result is a compression of its argument with all but the first instance of each distinct element removed. Unique is mapped to the ALT+V key. For example,
ž (123 'abc' 'def') ('a b c') ('abc') (1 2 3) ('a b c')
123 abc def a b c abc 1 2 3
When printing an APL session or an Edit session from the Session Manager, you can now specify the margins to be used on the printed page. The printer margins can be specified in the Editor Options dialog. The margins can be specified in inches (default), points, or millimeters by following the number with the desired units; in, mm, and pt. The default margins are 0.75”, 0.5”, 0.75”, and 0.5” for Left, Right, Top, and Bottom, respectively. Figure 8 shows the Printer Margins settings in the Editor Options dialog.
Figure 8 Editor Options dialog
)OUTPUT STRICT
This command also locates expressions that generate implicit output, but gives slightly different behavior. The )OUTPUT ERROR state may produce IMPLICIT OUTPUT errors on some implicit output that is not visible. The )OUTPUT STRICT command produces errors only when visible implicit output is generated. In addition, this state produces the IMPLICIT OUTPUT error message after the output has been generated, so the effect of the output can be seen.
Note: All previous )OUTPUT command behavior remains unchanged.
Delocalization of ŒWSELF to a non-existent name now sets ŒWSELF to an empty vector instead of producing an error message.
The Zip Class is an object programming model that provides facility for building archives of files and extracting files from those archives. The Zip class provides an interface to the Info-ZIP dynamic load libraries zip32.dll and unzip32static.dll. The Zip class is manipulated with ŒWI.
This works just like the ordinary ŒFX except that it defines the function inside the referenced object. For example:
obj_ref„ ŒMOM 'DLB' 'DEB' 'DTB' 'kind'
obj_ref.ŒNL 2 3
DEB
DLB
DTB
obj_ref.ŒCR 'DLB'
z„ DLB x
z„ (Ÿ/ x ¬ ' ') \ x
obj_ref.ŒFX œ 'z„ DAB x' 'z„ (z ¬ " ") / x'
DAB
obj_ref.ŒNL 3
DAB
DEB
DLB
DTB
APL+Win 6.0
Released April 26, 2006
Note: The MOM object system is evolving and its implementation is not complete.
The MOM object system extends APL with simple basic facilities for object based programming, a predominant design and structuring paradigm for modern programming languages. MOM objects are typeless, classless, and inherently polymorphic.
A MOM object system is a simple container enclosing a set of named APL functions and variables, where each Mom object is distinct from every other MOM object. MOM objects themselves are neither named nor directly referred to in programs.
Syntactically, MOM object members are accessed as objref.member where objref is a variable holding an object reference and member is the name of the member within the object. For example,
For a more in‑depth description of the MOM object system, refer to Bill Rutiser’s (the designer of the MOM object system) session “The MOM Object System”.
The Try-Catch exception handling extends the APL+Win control structure family to address static exception handling. It was designed to be compatible with and interact with the existing ŒELX handlers and should help facilitate clearer and more reliable code.
Syntax:
:TRY
Statements to try
:CATCHIF first condition expression
Statements to handle exceptions satisfying the first condition
:CATCHIF second condition expression
Statements to handle exceptions satisfying the second condition
:CATCHALL
Statements to handle all other exceptions
:ENDTRY
The structure always begins with a :TRY clause and ends with a :ENDRY statement. As with other control structures, the keywords are case insensitive and :END may be substituted for :ENDTRY.
There must be at least one :CATCHIF or :CATCHALL clause. There may be no more than one :CATCHALL clause, which must be the last.
The :CATCHIF statement consists of its keyword followed by an expression that yields 1 or 0. The other control statements consist of only a keyword.
Each control statement except :ENDTRY is followed by a block of APL statements (which may be empty). These blocks may contain additional try-catch and other control structures. They must be properly nested.
The filter option in the Open and Fetch dialogs that controls the contents of the function and variable list. The filter is in a drop-down at the bottom of the dialog. The filtering is case insensitive and has a very simple syntax. Asterisks may be used to denote zero or more characters. The filter drop-down stores new filters (up to eight) when objects are opened from the dialog. The drop-down contents are not saved across sessions. Figures 1 and 2 illustrate filter use.
 |
 |
| Figure 1 Empty filter box, all functions listed |
Figure 2 List functions starting with “Get” |
The [Session]Logging System Info entry in APLW.INI stores additional information in the log file such as the contents of Œsysver, the executable’s full path and file names, and its modification time and the user and computer names. Including any of the following keywords, separated by commas will display the corresponding information at the beginning of the session:
| sysver |
the contents of Œsysver |
| exe |
the executable’s full path and file names, and its modification time |
| user |
the user and computer name |
With
[Session]
Logging System Info=sysver,exe,user
set in APLW.INI, Figure 3 illustrates this use.
Figure 3 Session logging info.
Code that generates unintended implicit output has always been difficult to find in an APL application. A new command: )OUTPUT helps to manage implicit output. This command allows the programmer to turn implicit output off or on. It also provides a means for locating code which performs implicit output. The command sets a three state switch in the active workspace. This switch is workspace relative. It is saved with the workspace on a )Save command and loaded with the workspace on a )LOAD command. The )CLEAR command resets )OUTPUT to the default value.
Note: Implicit output states only apply to expressions executed within a function or an event handler. They do not apply to immediate execution statements.
)OUTPUT
This command prints the current implicit output state. The other three commands (ON, OFF, and ERROR) print the previous implicit output state.
The three states are set by the following arguments to the system command:
)OUTPUT ON
This is the default state. Implicit output is generated by any APL expression that does not assign its result.
)OUTPUT OFF
In this state Implicit output is not generated.
)OUTPUT ERROR
This state is used to locate expressions that generate implicit output. In this state execution of any expression that would generate implicit output in the default state causes an “IMPLICIT OUTPUT ERROR”. An expression beginning with 0 0½ by definition generates no output and so does not cause an “IMPLICIT OUTPUT ERROR”.
Scrolling speed control has been added to the system for highlighted scrolling. When using the mouse to highlight text, the scrolling speed is determined by the distance of the mouse from the client area of the session. The further the mouse is from the client area, the faster the text is scrolled. The rate of change is inversely dependant on the distance. So slow scrolling changes quickly as the mouse is moved and fast scrolling changes less quickly. If the mouse is moved all the way to the top or bottom of the screen, control of the scroll speed is released and scrolling speed proceeds at its maximum rate.
The session manager editor has new events on the system object ('#') that supports dynamic loading of functions and variables when you edit them.
The onEditLoad event fires when you start an edit session or fetch an object into the edit session. ŒWARG contains the name of the object.
The onEditStart event fires when an edit session is about to start. This event fires before onEditStart and gives you the opportunity to affect the way the edit session starts with setting ŒWARG and ŒWRES.
The onEditNL event fires when the functions and variables dialog box is being initialized. You use ŒWARG and ŒWRES to control the contents of the dialog box.
The onEditSaved event fires after you save the contents of the edit session. ŒWARG contains the name of the object.
The onEditEnd event fires after exiting the edit session. ŒWARG contains the name of the object.
dirty Property (Printer Object)
Setting the dirty property to 1 will force the Printer object to print a page even when it detects that it has not been printed to or drawn on.
This control (AplFileShExt.dll), when registered, adds the Component Summary page to the Properties sheet obtained by selecting Properties from the context menu for a component file (.sf and .cf) in the Windows Explorer. Figures 4 and 5 illustrates this use.
 |
 |
| Figure 4: Component Summary page for an APL+Win file |
Figure 5: Same for a colossal component file with data in comp 0. |
Reference the File Tie State Information for a File
The ŒNTIE, ŒXNTIE, ŒXFTIE, ŒFTIE, and ŒCFTIE functions allow you to reference the file tie state information for a component file. You reference the file tie state by calling a function monadically with the tie number as the right argument. The result is a two‑element integer vector indicating the file tie state. The value of the first element is the same as the open mode arguments to the dyadic version of ŒNTIE and indicates what the current open mode of the file is. The open mode values are sums of the following:
| Access Requested |
Access granted to other users |
| |
|
<
APL+Win 8.0 