Version 12.1 Key Features

Key Features of Version 12.1

Enhanced Editor

The Editor has been enhanced to improve the ease with which individual functions and classes can be edited. More...

Table function

The new Table function (monadic ⍪) turns any array into a 2-dimensional matrix. More...

XML

The ⎕XML system function converts an XML character vector into an APL array and vice-versa. As a built-in system function it is naturally much faster than an equivalent defined function written in APL. More...

Faster Primitive Functions

A number of primitive functions have been modified to deliver significantly improved performance. More...

Parallel Execution on multi-cpu / multi-core systems

If your computer has more than one cpu or is a multi-core processor, many scalar dyadic functions now execute in parallel in separate system threads each running on a separate cpu or core. This delivers very significant performance on large arrays. More...

Component File Journaling and CheckSum

Version 12.1 provides enhanced Journaling for Dyalog APL component files and includes the facility to check sum components. More...

User Commands

Version 12.1 provides an easy mechanism to define User Commands.

A User Command is a name prefixed by a closing square bracket, which may be niladic or take an argument. A User Command executes APL code that is typically stored somewhere outside the current active workspace. More...

Standalone Executables

In Version 12.1 it is possible to export a workspace as a single .exe file that includes a copy of the Dyalog APL interpreter. This allows you to implement and deploy a stand-alone Dyalog APL application as a single .exe file. More ...

.Net Controls

Whereas previously it was possible to use Microsoft .Net GUI by creating a .Net Form and populating it with .Net controls, it was not possible to mix .Net GUI components with the Dyalog APL GUI.

In Version 12.1, the new NetControl object allows you to include any control that derives from System.Windows.Forms.Control as a child of a Dyalog APL GUI container such as a Form, SubForm, or Group. More...

      ⎕using←'System.Windows.Forms,system.windows.forms.dll'

      'f'⎕wc'Form' ('Coord' 'Pixel')
      'f.wb'⎕WC'NetControl' 'WebBrowser' ('Size' f.Size)

      f.wb.GoHome ⍝ Display user's home page

Many .Net controls can also be used as input objects for the Dyalog Grid.

In addition classes defined within the workspace that derive from System.Windows.Forms.Control can also be embedded into the Dyalog GUI. More...

Tracer Syntax Colouring

The Tracer may now optionally be coloured in the same way as the Editor. If you choose this option, the appearance of a function inside the Tracer window is almost identical to that of the Editor. The only difference is that the current line is identified by a bright red rectangle. More...

Keyboard Changes

More...

I-Beam

The I-Beam function (⌶) provides access to certain specialised system services. More...

Miscellaneous Changes

Version 12.1 includes some minor changes to outer-product, ⎕EX and ⎕SIZE and ⎕AVU. More...


Version 12.1 System Requirements

System Requirements

Microsoft Windows

Dyalog APL Version 12.1 supports the following Versions of Windows:

  • Windows Vista
  • Windows XP
  • Windows 2000
  • Windows Server 2003

Note that Dyalog APL Version 12.1 is not supported under Windows 95, Windows 98, Windows ME or Windows NT4.

Microsoft .Net Interface

Dyalog APL Version 12.0 ,Net Interface requires Version 2.x or greater of the Microsoft .Net Framework. It does not operate with .Net Version 1.0.


V12.1 Interoperability

Interoperability and Compatibility

Introduction

Workspaces and component files are stored on disk in a binary format (illegible to text editors). This format differs between machine architectures and among versions of Dyalog. For example a file component written by a PC will almost certainly have an internal format that is different from one written by a UNIX machine. Similarly, a workspace saved from Dyalog Version 12.1 will differ internally from one saved by a previous version of Dyalog APL.

It is convenient for versions of Dyalog APL running on different platforms to be able to interoperate by sharing workspaces and component files. From Version 11.0, component files and workspaces can generally be shared between Dyalog interpreters running on different platforms. However, this is not always possible. For example, component files created by Version 10.1 can often not be shared across platforms, even when used by later versions (the system function ⎕FCOPY can be used to make a logically identical copy of an old file, which is fully inter-operable).

The following sections describe other limitations in inter-operability:

Code

Code which is saved in workspaces, or embedded within ⎕ORs stored in component files, can generally only be read by the version which saved them and later versions of the interpreter. In the case of workspaces, a load (or copy) from an older version would fail with the message:

 this WS requires a later version of the interpreter.

In the case of ⎕OR, unpredictable behaviour may result if an older version reads a ⎕OR saved by a later version of the system. Thus, ⎕OR is not recommended as a mechanism for sharing code or objects between different versions of APL.

“Ordinary” Arrays

With the exception of the Unicode restrictions described in the following paragraphs, Dyalog APL provides complete inter-operability for arrays which only contain (nested) character and numeric data. Such arrays can be stored in component files - or transmitted using TCPSocket objects and Conga connections, and shared between all versions and across all platforms.

As mentioned in the introduction, full cross-platform interoperability of component files is only available for large component files (see the following section), and for small component files created by Version 11.0 or later.

32 vs 64-bit Component Files

Large (64-bit-addressing) component files are inaccessible to versions of the interpreter that pre-dated their introduction (versions earlier than 10.1).

The second item in the right argument of ⎕FCREATE determines the addressing type of the file.

      'small'⎕fcreate 1 32 ⍝ create small file.
      'large'⎕fcreate 1 64 ⍝ create large file.

If the second item is missing, the file type defaults to 64-bit-addressing. In versions prior to 12.0, the default was 32-bit addressing.

Note that small (32-bit-addressing) cannot contain Unicode data. Unicode editions of Dyalog APL can only write character data which would be readable by a Classic edition (consisting of elements of ⎕AV).

External Variables

External variables are implemented as small (32-bit -adressing) component files, and subject to the same restrictions as these files. External variables are unlikely to be developed further; Dyalog recommends that applications which use them should switch to using mapped files or traditional component files. Please contact Dyalog if you need further advice on this topic.

32 vs. 64-bit Interpreters

From Dyalog APL Version 11.0 onwards, there are two separate versions of programs for 32-bit and 64-bit machine architectures (in general, the 32-bit versions will also run on 64-bit machines running 64-bit operating systems). There is complete inter-operability between 32- and 64-bit interpreters.

Unicode vs. Classic Editions

From Version 12.0 onwards, a Unicode edition is available, which is able to work with the entire Unicode character set. Classic editions (a term which includes versions prior to 12.0) are limited to the 256 characters defined in the atomic vector, ⎕AV). Large (64-bit-addressing) component files have a Unicode property; when this is enabled, Unicode data may be stored in the file. The Unicode property is always off for small (32-bit addressing) files, which may not contain Unicode data. When a Unicode edition writes to a component file which may not contain Unicode data, character data is mapped to ⎕AV, and can therefore be read without problems by Classic editions.

A TRANSLATION ERROR will occur if a Unicode edition writes to a non-Unicode component file, if the data being written contains characters which are not in ⎕AV (see ⎕AVU for more details). Likewise, a Classic edition (Version 12.0 or later) will issue a TRANSLATION ERROR if it reads Unicode data from a component file, and is unable to map it to ⎕AV. Version 10.1 cannot read components containing Unicode data.

A TRANSLATION ERROR will also issued when a Classic edition )LOADs or )COPYs a workspace containing Unicode data which cannot be mapped to ⎕AV.

TCPSocket objects have an APL property which corresponds to the Unicode property of a file, if this is set to Classic (the default) the data in the socket will be restricted to ⎕AV, if Unicode it will contain Unicode character data. As a result, TRANSLATION ERRORs can occur on transmission or reception in the same way as when updating or reading a file component.

File Journaling

Version 12.0 introduces File Journaling (level 1), and 12.1 adds levels 2 and 3. Versions earlier than 12.0 cannot tie files which have any form of journaling enabled. Version 12.0 cannot tie files with journaling levels other than 1. Files can be shared with earlier versions by using ⎕FPROPS to switch journaling off.

Auxiliary Processors

A Dyalog APL process is restricted to starting an AP of exactly the same architecture. In other words, the AP must share the same word-width and byte-ordering as its interpreter process.

Session Files

Session (.dse) files may only be used on the platform on which they were created and saved.


V12.1 Performance Improvements

Faster Primitive Functions

A number of primitive functions have been modified to deliver significantly improved performance in Version 12.1.

Boolean Scan and Reduce

Many scans and reductions on Boolean arrays perform a lot faster in Version 12.1. These include the following derived functions:

∧/ ∨/ =/ ≠/ +/ ∧\ ∨\ =\ ≠\ <\

Many inner products where one of the above functions is used as the left function operand are also significantly faster, as they use Boolean reduction.

Grade up and down

The performance of Grade Up and Grade Down has been improved, especially for small-range vectors. A small-range array is a simple integer or character array where the difference between its minimum and maximum value is less than twice its number of items.

In addition, the following expressions have been implemented as idioms for small-range vectors and narrow small-range matrices (less than 8 bytes per row):

{⍵[⍋⍵]} {⍵[⍒⍵]} {⍵[⍋⍵;]} {⍵[⍒⍵;]}

Note that it is only these precise expressions that have been optimized by idiom recognition; expressions such as X[⍋X;] are not recognized as idioms.

Compress

Compress on the leading axis has been tuned

Matrix Multiplication

Matrix multiplication (+.×) has been rewritten and is substantially faster in Version 12.1.

Basic Arithmetic Functions

The basic arithmetic dyadic functions (+ - ×) have been rewritten in assembler (x86 platforms) using SSE2 operations where possible.

The new code is implemented in Dyalog APL Version 12.1 for Windows (32 and 64-bit) and for Linux (32 and 64-bit).

On all other platforms and on x86 processors that do not support SSE2, e.g. Intel processors predating Pentium 4 (2001) and AMD processors predating K8 (2003), the previous (Version 12.0) code applies.

Indexing

Simple indexing and indexed assignment have been completely rewritten. They consume much less memory and many special-cases are optimized.

Set Functions

The set functions (index of, membership, union, intersect, without, unique) now use improved algorithms for certain data types:

Small-range arrays, including all single-byte data types, use a table look-up algorithm that is considerably faster than the old hashing algorithm.

In cases where one argument has a small number of elements, the functions now use an optimised linear search mechanism.

Outer products (e.g. ∘.∩) use retained hash or index tables where relevant.

Transpose

Transpose has been optimized.


Parallel Execution

Parallel Execution (multi-cpu)

If your computer has more than one cpu or is a multi-core processor, many scalar dyadic functions (÷ ≥ = ≤ ⍟ | ! ○ ∨ ∧) now execute in parallel in separate system threads each running on a separate cpu or core, when the argument size exceeds a configurable limit, the parallel execution threshold.

For example, by default if you have a 4-cpu computer and execute an expression such as (A÷B) where A and/or B contain more than 32768 elements, Dyalog will start 4 separate threads running on the 4 separate cpus each performing the division on ¼ of the elements of the array(s) and simultaneously creating the corresponding ¼ of the result array. The threads are only started once, and reused for subsequent multi-threaded operations.

The maximum number of cpus to use can be controlled using 1111⌶, and the parallel execution threshold) is changed using 1112⌶. These “tuning” I-beams should be considered experimental, and may be changed or replaced by automated tuning in a future release.

Note that the functions (+ - ×) are NOT executed using multiple cpus. This is because a single cpu is able to perform these operations so fast that memory is barely able to keep up. Tests show that multi-threading on separate cpus does not increase the speed of these operations.


Enhanced Editor

The Editor has been enhanced to improve the ease with which individual functions and classes can be edited.

Functions

For single functions, the most obvious improvement is the outlining feature. Outlining identifies the blocks of code within control structures, and allows you to collapse and expand these blocks so that you can focus your attention on particular parts of the code

The picture below shows the result of opening the function ⎕SE.cbtop.TB_POPUP.

      )ed ⎕SE.cbtop.TB_POPUP

Notice that the various control structure blocks are delineated by a treeview diagram.

  • When you hover the mouse pointer over one of the boxes that mark the start of a block , the line marking the extent of that block becomes highlighted, as shown above.
  • If you click on a [image] box, the corresponding section collapses, so that only the first line of the block is displayed, as shown below.
  • If you click on a [image] box, the corresponding section is expanded.

Editing Classes

The picture below shows the result of opening the ComponentFile class. Notice how each function is delineated separately and that each function is individually line-numbered.

      )ed ComponentFile

The outlining feature really comes into its own when editing classes because you can collapse and expand whole functions. The picture below shows the effect of collapsing all but the Append method.

When you edit a class, a separate treeview is optionally displayed in the left pane to make it easy to navigate within the class. When you click on a name in the treeview, the editor automatically scrolls the appropriate section into view (if necessary) and positions the edit cursor at its start. The picture below illustrates the result of opening the [Methods] section and then clicking on Rename.

Editing from the Workspace Explorer

If you double-click on the name of a Class in the Workspace Explorer, the same treeview is displayed to assist in navigation, as shown below.

The View Menu

The View menu, illustrated above, has been extended to allow you to control the new editor features, and now provides the following actions.

Trace | Displays a column to the left of the function that displays ⎕TRACE settings
Stop | Displays a column to the left of the function that displays ⎕STOP settings
Monitor | Displays a column to the left of the function that displays ⎕MONITOR settings
Line Numbers | Toggles the display of line numbers on/off.
Function Line Numbers | Toggles the display of line numbers on individual functions on/off. This option is only enabled when editing a Class, Namespace script or Interface.
Tree View | Toggles the display of the treeview in the left-hand pane
Outlining | Turns outlining on and off.
Expand All Outlines | Expands all outlines.
Collapse All Outlines | Collapses all outlines
Expand all Outlines below here | Expands all outlines below the level of the current line.

Line-numbering

The manner in which the line numbering option works has changed.

In Version 12.1.the user’s line-numbering preferences are stored in the Registry (in the Editor\Columns section) on a per object type basis. In other words, the system remembers the last line-numbering setting separately for a Class, function/operator, and each type of array; character vector, character matrix, vector of character vectors, and so forth.

The Line Numbers (Num-) menu item on the pop-up menu, and the button on the Session toolbar (both of which are associated with the system action [LineNumbers]) toggle line-numbering on/off on the current edit window as before. However, line numbering is not changed globally but only for the type of object in that window.

So, for example, if you have two Edit windows open, one on a function and the other on a character matrix, toggling the line numbers on and off in one window will have no effect on the line-numbering in the other window. However, if you opened a third window on a defined operator, toggling the line-numbering in that window would affect the line-numbering in the function window.

Whenever you change line-numbering, the corresponding value in the Registry for the type of object in the currently active edit window is immediately updated.

The lines_on_functions parameter, which used to control line-numbering on a global basis, has been removed.

Function Line Numbers

The Function Line Numbers option in the pop-up Editor menu provides an additional level of line-numbering. If selected, line numbers are displayed independently on each individual function (or operator) in the Class. This option is only enabled when you are editing a Class, Namespace script or Interface, and is disabled for all other types of object.

Note that function line-numbering and general line-numbering are independent options and it is possible to have the entire Class numbered (from [0] to the number of lines in the Class) in addition to having line-numbering on each individual function.

Refactoring

Version 12.1 provides some simple refactoring tools.

If the input cursor is positioned on a word somewhere in the body of a script, and you select one of the options from the Refactoring menu:

  • Add text as Field
  • Add text as Property
  • Add text as Method

the Editor inserts the appropriate template for a Field, Property or Method of the same name. The template is inserted immediately above the line containing the word. So, for example, if you position the input cursor on the word xvar, and then choose Add text as Property, the Editor will insert the following lines above the line in the script containing that xvar:

:Property xvar

∇r←get
r←0
∇

∇set args
∇
:EndProperty

Miscellaneous

The following additional improvements have been made to the Editor:

  • The speed with which the Editor displays and refreshes its contents has been very substantially improved. The effect is immediate, even for very large classes, functions and variables.
  • The limit on the number of lines that the Editor could effectively and correctly number, has been removed. This was previously 9999.
  • If you are editing a script and you press Shift+Enter or double-click on the name of a function that is defined within the same script, the Editor will move the input cursor to that function.
  • If you open the Editor on a specific name in a script, the Editor will open on the script as a whole but position the input cursor on the chosen name. For example if you enter the command:
    )ed myclass.myfn
    The Editor will open a window on myclass and position the input cursor on myfn, creating a new function if it doesn’t already exist.
  • When you use the Editor to view a nested array character data is displayed in the colours associated with Character Constant and numeric data in the colours associated with Numeric Constant. The same syntax colours are used to display data in the Value Tip window; the pop-up window that appears when you hover the mouse-pointer over a name.


V12.1 Journalling

Component File Journaling and CheckSum

Version 12.1 provides enhanced Journaling for Dyalog APL component files and includes the facility to check sum components.

The latter is highly recommended as it enables component files to be repaired using the new system function ⎕FCHK. However, component files written with Checksum enabled cannot be read by versions of Dyalog APL prior to Version 12.1.

In addition to the level of Journaling provided in Version 12.0 (now called Level 1 Journaling), two further levels are introduced.

Level 2 journaling provides protection not just against the possibility that the APL process terminates abnormally, but that the Operating System itself fails. However, a damaged component file must be explicitly repaired using the new system function ⎕FCHK which will repair any damaged components by rolling them back to their previous states.

Level 3 provides the same level of protection as Level 2, but following the abnormal termination of either APL or the Operating System, the rollback of an incomplete update will be automatic and no explicit repair will be needed.

Higher levels of Journaling inevitably reduce the performance of component file updates.

For further information, see ⎕FPROPS and ⎕FCHK.


User Commands

Version 12.1 provides an easy mechanism to define User Commands.

User commands are developer tools, written in APL, which can be executed without having to explicitly copy code into your workspace and/or save it in every workspace in which you want to use it.

A User Command is a name prefixed by a closing square bracket, which may be niladic or take an argument. A User Command executes APL code that is typically stored somewhere outside the current active workspace.

By default, the existing SPICE command processor is hooked up to the user command mechanism, and a number of new SPICE commands have been added. For example:

      ]display 'hello' (⍪'world')
┌→────────────┐
│ ┌→────┐ ┌→┐ │
│ │hello│ ↓w│ │
│ └─────┘ │o│ │
│         │r│ │
│         │l│ │
│         │d│ │
│         │w│ │
│         └─┘ │
└∊────────────┘

The implementation of User Commands is very simple: If a line of input begins with a closing square bracket (]), and there exists a function by the name ⎕SE.UCMD, then the interpreter will call that function, passing the input line (without the bracket) as the right argument.

To add a user command, drop a new Spice command file in the folder SALT\Spice.


NetControl Object

Properties

Purpose | The NetControl object provides the means to instantiate a .Net control in the Dyalog GUI.
Parents | Form, Grid, Group, PropertyPage, SubForm
Children | NetClient, OLEClient, Timer

Description

In principle, you may use the NetControl to embed any class that derives from System.Windows.Forms.Control (from system.windows.forms.dll), including derived classes written in Dyalog APL.

To load a particular .Net control, the appropriate .Net Assembly must be specified in ⎕USING; otherwise the expression will cause a LIMIT ERROR. For example, to load one of the standard .Net controls:

      ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'

The ClassName property specifies the name of the .Net control to be instantiated and to which the new object named by the left argument of ⎕WC is to be connected. ClassName may only be specified by ⎕WC.

Once you have created an instance of a particular NetControl, the properties, events and methods it supports may be obtained using ⎕NL. These are the properties, events and methods defined for the control by its author. The “Dyalog” properties listed above, are not reported by ⎕NL, but take precedence over (i.e. mask) any members of the same name that may be exposed by the class itself.

The following example illustrates the use of the Button class. In this case, the FlatStyle property of the button is set to “Popup”. This gives the button a flat appearance until the mouse is hovered over it, when its appearance it changes to 3-dimensional.

      ⎕USING←'System'
      ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'
      ⎕USING,←⊂'System.Drawing,system.drawing.dll'

      an←⎕NEW FontFamily(⊂'Arial')
      myfont←⎕NEW Font(an 24 FontStyle.Bold GraphicsUnit.Point)

      'f'⎕WC'Form'('Coord' 'Pixel')('Size' 120 200)
      f.Caption←'NetControl'
      'f.l'⎕WC'Label' 'Button with FlatStyle=Popup'(2 2)

      'f.b'⎕WC'NetControl' 'Button'('Size' 60 160)

      f.b.⎕nl -2
 AutoSizeMode DialogResult AutoEllipsis AutoSize BackColor FlatStyle FlatAppearance ...

      f.b.⎕nl -3
 BeginInvoke BringToFront Contains CreateControl CreateGraphics CreateObjRef Dispose DoDragDrop ...

      f.b.⎕nl -8
 DoubleClick MouseDoubleClick AutoSizeChanged ImeModeChanged BackColorChanged ...

      f.b.Text←'Popup'
      f.b.Font←myfont

      f.b.(FlatStyle←FlatStyle.Popup)
Normal appearance (Flat) | Appearance when mouse over

In most cases, you may use a NetControl in the cells of a Grid object. Unless you specify otherwise, using the InputProperties property of the Grid, the default property of the NetControl will be associated with the corresponding element of Values. The following example illustrates the use of a TextBox control. In this example, the CharacterCasing property of the TextBox is set to Upper, causing all text to be converted to upper-case.

      ⎕USING←'System'
      ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'
      ⎕USING,←⊂'System.Drawing,system.drawing.dll'

      an←⎕NEW FontFamily(⊂'Arial Narrow')
      myfont←⎕NEW Font(an 11 FontStyle.Bold GraphicsUnit.Point)

      'f'⎕WC'Form' ('Coord' 'Pixel')('Size' 130 500)
      f.Caption←'Grid using .Net TextBox Control'

      'f.g'⎕WC'Grid'('Posn' 0 0)f.Size
      f.(ShowInput TitleWidth)' 1) ← 1 0

      'f.g.tb'⎕WC'NetControl' 'TextBox'
      f.g.tb.Font←myfont
      f.g.tb.(CharacterCasing←CharacterCasing.Upper)

      f.g.Input←'f.g.tb'

      wds←'All' 'TeXt' 'Is' 'Changed' 'to' 'Upper' 'casE'
      wds,← 'ακομα' 'kai' 'τα' 'Ελληνικα'

      f.g.Values←5 5⍴wds

Implementation note: The instance of the .Net control is actually placed inside an instance of the .Net class System.Windows.Forms.ContainerControl.This ContainerControl is then embedded in the Dyalog parent, such as a Form. This "extra level" should have no affect on how the control is used or on how it behaves.


Tracer and Syntax Colouring

The Tracer and Syntax Colouring

The Tracer may now optionally be coloured in the same way as the Editor. If you choose this option, the appearance of a function inside the Tracer window is almost identical to that of the Editor. The only difference is that the current line is identified by a bright red rectangle. For example:

If, while tracing, you decide to edit the function, the colours don’t change, but the Edit toolbar replaces the Trace Tools, as shown below.

The option to apply syntax colouring to the Tracer is set by checking the Function Tracer button on the Syntax tab of the Colour Selection dialog box. If you check this option, the Tracer colour scheme defined from the Session/Trace tab is overridden.


Keyboard Changes

The Dyalog Input Mode Editor was “retired” in version 12.0, because it was believed that the new “standard” keyboards rendered it obsolete. However, many Windows applications use APL keystrokes as accelerator keys, which makes it impossible to enter many symbols into popular applications. The IME uses a technology which completely takes control of the keyboard and generates APL characters even for keystrokes which are defined as accelerators. Naturally, this means that those accelerator keys do not work when the IME is enabled.

The version 12.1 IME no longer has the “APL” toggle button, it is just another keyboard that you can select and deselect using standard features of Windows. For example, you could make a Dyalog Ctrl keyboard the default Windows keyboard, which should enable you to operate Windows normally, generating APL symbols using ctrl combinations. You can set Windows up so that a hot-key switches to the IME if you need to enter APL characters without having them “stolen” and used as accelerators, and switch back to the “normal” keyboard when you want accelerators to take precedence.

In the version 12.1 “Dyalog Ctrl” keyboards (and the IME keyboard layout), Ctrl X-C-V are interpreted as Cut-Copy-Paste. To get disclose, intersection and union, use Ctrl+Shift.

I-Beam has been added as Ctrl+Shift+I

Instructions on how to download and install old keyboard layouts “if you can’t stand it” to follow.


Standalone Executables

In Version 12.1 it is possible to export a workspace as a single .exe file that includes a copy of the Dyalog APL interpreter. This allows you to implement and deploy a stand-alone Dyalog APL application as a single .exe file.

Note however, that if your application requires.Net support you must to deploy 2 Dyalog dynamic link libraries, namely dyalognet.dll and the appropriate Bridge dll according to the following table.

 | 32-bit | 64-bit
Unicode Edition | bridge121_unicode.dll | bridge121-64_unicode
Classic Edition | bridge121.dll | bridge121-64.dll

This facility has been added to the Save as type drop-down menu on the Create bound file dialog box, accessed via File->Export from the Session menu bar.

The operation to export the current active workspace as a stand-alone executable may also be actioned programmatically using 2110⌶.


RadiusMode Property

Applies to: Circle, Root

Description

A perfectly round circle can only be drawn if the diameter is an odd number of pixels. The RadiusMode property specifies whether or not a circle is adjusted by a single pixel, if necessary, so as to appear perfectly round.

If RadiusMode is 1 or ¯1, and the diameter is an even number of pixels, the circle is actually drawn with a diameter of 1 pixel more or less than specified. If RadiusMode is 0 (the default), no such adjustment is made.

RadiusMode may be set on the Root object to be inherited by all Circle objects.


APLFormatBias Parameter

In Version 11.0, ⎕FMT and dyadic ⍕ were changed to improve the accuracy of the display of floating-point numbers. The gain in accuracy has necessarily been achieved at the cost of a reduction in performance. The difference in performance is significant, but may only be noticeable in an application that does a lot of numeric formatting.

In versions prior to Version 11.0, there was a significant performance optimisation whereby numbers which would display in fewer than 10 digits were scaled and then treated as integers.

A second consequence of the optimisation was that numbers smaller than but indistinguishable (in terms of the accuracy of internal representation) from n.5 were rounded up. In other words, any number whose decimal part (the part of the number after the decimal point) is in the range (0.49999999999999987 to 0.49999999999999999 will be rounded as if it were 0.5 (i.e., rounded up). This effect, although potentially desirable, may be regarded as being not strictly correct.

For example, consider the number 0.015 which is internally represented as the value 1.4999999...

      2 ⍕0.015 ⍝ Versions prior to 11.0
0.02
      2 ⍕0.015 ⍝ Version 11.0 onwards
0.01

A new parameter APLFormatBias has been introduced (in Version 12.0 Release 4) to allow you to select the old, pre-Version 11.0 behaviour.

If you wish to get the old pre-Version 11.0 behaviour, including significantly better performance, you should set APLFormatBias to 1. The default is 0 (slower but mathematically more “correct”).


Miscellaneous Changes

Miscellaneous

Change to Outer-Product

In Version 12.1, the way that outer-product produces a null result has changed.

Outer-product now applies its operand function once between the first items of its arguments to determine the prototype of the result. In previous versions, the function was not applied, and the prototype of the result was the same as that of the right argument. This lead to anomalies such as ∘.≡ producing a (null) character result.

Change to ⎕EX and ⎕SIZE

⎕EX and ⎕SIZE now accept a vector of character vectors as their argument.

Change to ⎕AVU

In version 12.1, there is a small change to the default ⎕AVU as follows:

⎕AVU[⎕IO+219 237]←180 96

Previously, these two elements had the value 8217 8218.

The Unicode code points involved are:

0096: U+0060 GRAVE ACCENT
0180: U+00B4 ACUTE ACCENT
8216: U+2018 LEFT SINGLE QUOTATION MARK
8217: U+2019 RIGHT SINGLE QUOTATION MARK


I-Beam

R←{X}(A⌶)Y

I-Beam is a monadic operator that provides a range of system related services.

WARNING: Although documentation is provided for I-Beam functions, any service provided using I-Beam should be considered as “experimental” and subject to change – without notice - from one release to the next. Any use of I-Beams in applications should therefore be carefully isolated in cover-functions that can be adjusted if necessary.

A is an integer that specifies the type of operation to be performed as shown in the table below. Y is an array that supplies further information about what is to be done.

X is currently unused.

R is the result of the derived function.

A | Derived Function
200 | Syntax Colouring
1111 | Number of Threads
1112 | Parallel Execution Threshold
1113 | Thread Synchronisation Mechanism
2000 | Memory Manager Statistics
2110 | Export to Memory


Syntax Colouring (I-Beam)

Syntax Colouring

R←200⌶Y

This function obtains syntax colouring information for a function.

Y is a vector of character vectors containing the ⎕NR representation of a function or operator.

R is a vector of integer vectors with the same shape and structure of Y in which each number identifies the syntax colour element associated with the corresponding character in Y.

Example

      {(↑⍵),↑ 200⌶⍵} 'foo; local' 'global' 'local←⍴⍴''hello'''

foo; local 21 21 21 19 3 31 31 31 31 31 0 0 0 0 0
global 7 7 7 7 7 7 0 0 0 0 0 0 0 0 0
local←⍴⍴'hello' 31 31 31 31 31 19 23 23 4 4 4 4 4 4 4
In this example:
21 is the syntax identifier for “function name”
19 is the syntax identifier for “primitive”
3 is the syntax identifier for “white space”
31 is the syntax identifier for “local name”
7 is the syntax identifier for “global name”
23 is the syntax identifier for “idiom”


Number of Threads (I-Beam)

Number of Threads

R←1111⌶Y

Specifies how many threads are to be used for parallel execution.

Y is an integer that specifies the number of threads that are to be used henceforth for parallel execution. Prior to this call, the default number of threads is specified by an environment variable named APL_MAX_THREADS. If this variable is not set, the default is the number of CPUs that the machine is configured to have.

R is the previous value

Note that (unless APL_MAX_THREADS is set), the number of CPUs for which the machine is configured is returned by the first execution of 1111⌶. The following expression obtains and resets the number of threads back to this value.

      {}1111⌶ ncpu←1111⌶1


Parallel Execution Threshold (I-Beam)

Parallel Execution Threshold

R←1112⌶Y

Y is an integer that specifies the array size threshold at which parallel execution takes place. If a parallel-enabled function is invoked on an array whose number of elements is equal to or greater than this threshold, execution takes place in parallel. If not, it doesn’t.

Prior to this call, the default value of the threshold is specified by an environment variable named APL_MIN_PARALLEL. If this variable is not set, the default is 32768.

R is the previous value


Thread Synchronisation Mechanism (I-Beam)

Thread Synchronisation Mechanism

R←1113⌶Y

Y is Boolean and specifies whether or not the main thread does a busy wait for the others to complete or uses a semaphore when a function is executed in parallel.

The default and recommended value is 0 (use a semaphore). This function is provided only for Operating Systems that do not support semaphores.

A value of 1 must be set if you are running AIX Version 5.2 which does not support Posix semaphores. Later versions of AIX do not have this restriction.

R is the previous value


Memory Manager Statistics (I-Beam)

Memory Manager Statistics

R←2000⌶Y

This function returns information about the state of the workspace. This I-Beam is provided for performance tuning and is VERY LIKELY to change in the next release.

Y is a simple scalar or vector containing up to 5 elements.

The result R is an array with the same structure as Y, but any elements of Y that contain values other than ¯1, are replaced by the following values according to their position.

Index | Description
1 | Workspace available (a "quick" ⎕WA)
2 | Workspace used
3 | Number of compactions since the workspace was loaded
4 | Number of garbage collections that found garbage
5 | Current number of garbage pockets in the workspace

Note that while the first 4 operations are relatively fast, the fifth operation may take a noticeable amount of time, depending upon the size and state of the workspace.

Examples

      2000⌶0
65374272

      2000⌶5⍴0
65374272 184256 2 1 0

      2000⌶¯1 ¯1 0 0
¯1 ¯1 2 1


Export to Memory (I-Beam)

Export to Memory

R←2100⌶Y

This function exports the current active workspace as an in-memory .NET.Assembly.

Y may be any array and is ignored.

The result R is 1 if the operation succeeded or 0 if it failed.


Outer Product

{R}←X∘.gY

g may be any dyadic function. The left operand of the operator is the symbol ∘. X and Y may be any arrays whose elements are appropriate to the function g.

Function g is applied to all combinations of the elements of X and Y. If function g returns a result, the shape of R is (⍴X),⍴Y. Each element of R is the item returned by function g when applied to the particular combination of elements of X and Y.

Examples:

      1 2 3∘.×10 20 30 40
10 20 30  40
20 40 60  80
30 60 90 120

      1 2 3∘.⍴'AB'
 A    B
 AA   BB
 AAA  BBB

      1 2∘.,1 2 3
 1 1  1 2  1 3
 2 1  2 2  2 3

      (⍳3)∘.=⍳3
1 0 0
0 1 0
0 0 1

If X or Y is empty, the result R is a conformable empty array, and the operand function is applied once between the first items of X and Y to determine the prototype of R.


File Check and Repair

R←{X} ⎕FCHK Y

⎕FCHK validates and repairs component files following an abnormal termination of the APL process or operating system.

Y must be a simple character scalar or vector which specifies the name of the file to be exclusively checked or repaired. For component files, the file must be named in accordance with the operating system's conventions, and may be a relative or absolute pathname. The file must exist and must not be tied. For files associated with external variables, any filename extension must be specified even if ⎕XT would not require it. See User Guide for file naming conventions under Windows and UNIX. The file must exist and must not be associated with an external variable.

The optional left-argument X must be a vector of zero or more character vectors from among 'force', 'repair' and 'rebuild', which determine the detailed operation of the function. Note that these options are case-sensitive.

• If X contains 'force' ⎕FCHK will validate the file even if it appears to have been cleanly untied.

• If X contains 'repair' ⎕FCHK will repair the file, following validation, if it appears to be damaged. This option may be used in conjunction with 'force'.

• If X contains 'rebuild' ⎕FCHK will repair the file unconditionally.

If X is omitted, the default behaviour is as follows:

  1. If the file appears to have been cleanly untied previously, return ⍬, i.e. report that the file is OK.
  2. Otherwise, validate the file and return the appropriate result. If the file is corrupt, no attempt is made to repair it.

The result R is a vector of the numbers of missing or damaged components. R may include non-positive numbers of "pseudo components" that indicate damage to parts of the file other than in specific components:

0 | ACCESS MATRIX.
¯1 | Free-block tree.
¯2 | Component index tree

Other negative numbers represent damage to the file metadata; this set may be extended in the future.

Following a check of the file, a non-null result indicates that the file is damaged.

Following a repair of the file, the result indicates those components that could not be recovered. Un-recovered components will give a FILE COMPONENT DAMAGED error if read but may be replaced without error.

Repair can recover only check-summed components from the file, i.e. only those components that were written with the checksum option enabled (see ⎕FPROPS).

Following an operating system crash, repair may result in one or more individual components being rolled back to a previous version or not recovered at all, unless Journaling levels 2 or 3 were also set when these components were written.


Atomic Vector - Unicode

R←⎕AVU

⎕AVU specifies the contents of the atomic vector, ⎕AV, and is used to translate data between Unicode and non-Unicode character formats when required, for example when:

  • Unicode Edition loads or copies a Classic Edition workspace or a workspace saved by a Version prior to Version 12.0.
  • Unicode Edition reads character data from a non-Unicode component file, or receives data type 82 from a TCP socket.
  • Unicode Edition writes data to a non-Unicode component file
  • Unicode Edition reads or writes data from or to a Native File using conversion code 82.
  • Classic Edition loads or copies a Unicode Edition workspace
  • Classic Edition reads character data from a Unicode component file, or receives data type 80, 160, or 320 from a TCP socket.
  • Classic Edition writes data to a Unicode component file.

⎕AVU is an integer vector with 256 elements, containing the Unicode code points which define the characters in ⎕AV.

Note
In Versions of Dyalog prior to Version 12.0 and in the Classic Edition, a character is stored internally as an index into the atomic vector, ⎕AV. When a character is displayed or printed, the index in ⎕AV is translated to a number in the range 0-255 which represents the index of the character in an Extended ASCII font. This mapping is done by the Output Translate Table which is user-configurable. Note that although ASCII fonts typically all contain the same symbols in the range 0-127, there are a number of different Extended ASCII font layouts, including proprietary APL fonts, which provide different symbols in positions 128-255. The actual symbol that appears on the screen or on the printed page is therefore a function of the Output Translate Table and the font in use. Classic Edition provides two different fonts (and thus two different ⎕AV layouts) for use with the Development Environment, named Dyalog Std (with APL underscores) and Dyalog Alt (without APL underscores).

The default value of ⎕AVU corresponds to the use of the Dyalog Alt font in combination with the standard Output Translate Table (win.dot) in the Classic Edition or in earlier versions of Dyalog APL.

      2 13⍴⎕AVU[97+⍳26]
193 194 195 199 200 202 203 204 205 206 207 208 210
211 212 213 217 218 219 221 254 227 236 240 242 245
      ⎕UCS 2 13⍴⎕AVU[97+⍳26]
ÁÂÃÇÈÊËÌÍÎÏÐÒ
ÓÔÕÙÚÛÝþãìðòõ

⎕AVU has namespace scope and can be localised, in order to make it straightforward to write access functions which receive or read data from systems with varying atomic vectors. If you have been using Dyalog Alt for most things but have some older code which uses underscores, you can bring this code together in the same workspace and have it all look “as it should” by using the Alt and Std definitions for ⎕AVU as you copy each part of the code into the same Unicode Edition workspace.

      )COPY avu.dws Std.⎕AVU
C:\Program Files\Dyalog\Dyalog APL 12.0 Unicode\ws\avu saved Thu Dec 06 11:24:32 2007

      2 13⍴⎕AVU[97+⍳26]
9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410
9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423
      ⎕UCS 2 13⍴⎕AVU[97+⍳26]
ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂ
ⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ

Rules for Conversion on Import

When the Unicode Edition imports APL objects from a non-Unicode source, function comments and character data of type 82 are converted to Unicode. When the Classic Edition imports APL objects from a Unicode source, this translation is performed in reverse.

If the objects are imported from a Version 12.0 (or later) workspace (i.e. from a workspace that contains its own value of ⎕AVU) the value of #.⎕AVU (i.e. the value of ⎕AVU in the root) of the source workspace is used. Otherwise, such as when APL objects are imported from a pre-Version 12.0 workspace, from a component file, or from a TCP socket, the local value of ⎕AVU in the target workspace is used.

Rules for Conversion on Export

When the Unicode Edition exports APL objects to a non-Unicode destination, such as a non-Unicode Component File or non-Unicode TCPSocket Object, function comments (in ⎕ORs) and character data of type 82 are converted to ⎕AV indices using the local value of ⎕AVU.

When the Classic Edition exports APL objects to a Unicode destination, such as a Unicode Component File or Unicode TCPSocket Object, function comments (in ⎕ORs) and character data of type 82 are converted to Unicode using the local value of ⎕AVU.

In all cases, if a character to be translated is not defined in ⎕AVU, a TRANSLATION ERROR (event number 92) will be signaled.


Expunge Objects

{R}←⎕EX Y

Y must be a simple character scalar, vector or matrix or a vector of character vectors containing a list of names. R is a simple logical vector with one element per name in Y.

Each name in Y is disassociated from its value if the active referent for the name is a defined function, operator, variable or namespace.

The value of an element of R is 1 if the corresponding name in Y is now available for use. This does not necessarily mean that the existing value was erased for that name. A value of 0 is returned for an ill-formed name or for a distinguished name in Y. The result is suppressed if not used or assigned.

Examples

      ⎕EX'VAR'
      +⎕EX 'FOO' '⎕IO' 'X' '123'
 1  0  1  0

If a named object is being executed the existing value will continue to be used until its execution is completed. However, the name becomes available immediately for other use.

Examples

      )SI
FOO[1]*

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇
      +⎕EX'FOO'
1
      )SI
FOO[1]*

      ∇FOO[⎕]
defn error

      FOO←1 2 3
      →⎕LC
10
      FOO
1 2 3

If a named object is an external variable, the external array is disassociated from the name:

      ⎕XT'F'
FILES/COSTS
      ⎕EX'F' ⋄ ⎕XT'F'

If the named object is a GUI object, the object and all its children are deleted and removed from the screen. The expression ⎕EX'.' deletes all objects owned by the current thread except for the Root object itself. In addition, if this expression is executed by thread 0, it resets all the properties of '.' to their default values. Furthermore, any unprocessed events in the event queue are discarded.

If the named object is a shared variable, the variable is retracted.

If the named object is the last remaining external function of an auxiliary process, the AP is terminated.

If the named object is the last reference into a dynamic link library, the DLL is freed.


File Properties

{R}←X ⎕FPROPS Y

Access Code 1 or 8192

⎕FPROPS reports and sets the properties of a component file.

Y must be a simple integer scalar or a 1 or 2-element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted, it is assumed to be 0.

X must be a simple character scalar or vector containing one or more valid Identifiers listed in the table below, or a vector of 2-element vectors, each of which contains an Identifier and a (new) value for that property.

If the left argument is a simple character array, the result R contains the current values for the properties identified by X. If the left argument is nested, the result R contains the previous values for the properties identified by X

Identifier | Property | Description / Legal Values
S | File Size (read only) | 32 = Small Component Files (<4Gb)
 |  | 64 = Large Component Files
E | Endian-ness (read only) | 0 = Little-endian
 |  | 1 = Big-endian
U | Unicode | 0 = Characters must be written as type 82 arrays
 |  | 1 = Characters must be written as Unicode arrays
J | Journaling | 0 = Disable Journaling
 |  | 1 = Enable APL crash proof Journaling
 |  | 2 = Enable System crash proof Journaling; repair needed on recovery
 |  | 3 = Enable full System crash proof Journaling
C | Checksum | 0 = Disable checksum
 |  | 1 = Enable checksum

The default properties for a newly created file are as follows:

  • S = 64
  • U = 1 (Unicode Edition and 64-bit file) or 0 (otherwise)
  • J = 0
  • C=0
  • E depends upon the computer architecture.

Journaling Levels

Level 1 journaling (APL crash-proof) automatically protects a component file from damage in the event of abnormal termination of the APL process. The file state will be implicitly committed between updates and an incomplete update will automatically be rolled forward or back when the file is re-tied. In the event of an operating system crash the file may be more seriously damaged. If checksum was also enabled it may be repaired using ⎕FCHK but some components may be restored to a previous state or not restored at all.

Level 2 journaling (system crash-proof – repair needed on recovery) extends level 1 by ensuring that a component file is fully repairable using ⎕FCHK with no component loss in the event of an operating system failure. If an update was in progress when the system crashed the affected component will be rolled back to the previous state. Tying and modifying such a file without first running ⎕FCHK may however render it un-repairable.

Level 3 journaling (system crash-proof) extends level 1 further by protecting a component file from damage in the event of abnormal termination of the APL process and also the operating system. Rollback of an incomplete update will be automatic and no explicit repair will be needed.

Enabling journaling on a component file will reduce performance of file updates; higher journaling levels have a greater impact.

Journaling levels 2 and 3 cannot be set unless the checksum option is also enabled.

Checksum Option

Enabling the checksum option for a component file will enable a damaged file to be repaired using ⎕FCHK. It will however will reduce the performance of file updates slightly and result in larger component files. The use of Check Sums is highly recommended, but in order to provide compatibility with earlier versions of Dyalog, it is not enabled by default. When version 12.1 becomes the oldest supported version, Check Sums will probably be enabled by default.

Enabling the checksum option on an existing non-empty component file, will mean that all components that had previously been written without a checksum, will be check-summed and converted. This operation which will take place when ⎕FPROPS is changed, may not, therefore, be instantaneous.

Journaling and checksum settings may be changed at any time a file is exclusively tied.

Component files written with Checksum enabled cannot be read by versions of Dyalog APL prior to Version 12.1.

Examples

      tn←'myfile64' ⎕FCREATE 0
      'SEUJ' ⎕FPROPS tn
64 0 1 0

      tn←'myfile32' ⎕FCREATE 0 32
      'SEUJ' ⎕FPROPS tn
32 0 0 0

The following expression disables Unicode and switches Journaling on. The function returns the previous settings:

      ('U' 0)('J' 1) ⎕FPROPS tn
1 0

The Unicode property applies only to 64-bit component files. 32-bit component files may not contain Unicode character data. To convert a 32-bit component file to a 64-bit component file, use ⎕FCOPY.

Properties may be read by a task with ⎕FREAD permission (access code 1), and set by a task with ⎕FSTAC access (8192). To set the value of the Journaling property, the file must be exclusively tied.

If Journaling or Unicode properties are set, the file cannot be tied by Versions prior to Version 12.0. If journaling is set to a value higher than 1, or checksums are enabled, the file cannot be tied by versions prior to 12.1.


Object Size

Size of Objects

R←⎕SIZE Y

Y must be a simple character scalar, vector or matrix, or a vector of character vectors containing a list of names. R is a simple integer vector of non-negative elements with the same length as the number of names in Y.

If the name in Y identifies an object with an active referent, the workspace required in bytes by that object is returned in the corresponding element of R. Otherwise, 0 is returned in that element of R.

The result returned for an external variable is the space required to store the external array. The result for a system constant, variable or function is 0. The result returned for a GUI object gives the amount of workspace needed to store it, but excludes the space required for its children.

Note: Wherever possible, Dyalog APL 'shares' the whole or part of a workspace object rather than generates a separate copy.

Examples:

      ⎕VR 'FOO'
     ∇ R←FOO
[1]    R←10
     ∇

      A←⍳10

      'EXT/ARRAY' ⎕XT'E' ⋄ E←⍳20

      ⎕SIZE 'A' 'FOO' 'E' 'UND'
28 76 120 0


Version 12 Key Features

Key Features of Version 12.0

Unicode

Version 12.0 allows applications to store and manipulate Unicode character data. Applications can now accept entry of data in any of the worlds writing systems - from Amharic over APL, Chinese and Tolkiens Elvish Runes to Zulu. All components of Dyalog support Unicode: The Development Environment itself, the Dyalog language and file systems, built-in GUI objects, and interfaces to COM/OLE, Microsoft.Net and ODBC.

The adoption of Unicode also means that data is no longer translated as it enters and leaves the Dyalog interpreter. APL source code can be stored in Unicode text files and edited using any editor which supports these files. A simple source code management system and an interface to the popular SubVersion system is included.

Built-in charting

Version 12.0 includes the Causeway product series: RainPro (including the .NET version, SharpPlot for high quality Business Graphics, and NewLeaf for reporting and typesetting. You can produce a graphical representation of numerical data in seconds by clicking on a chart icon whilst running your session - or write your own APL scripts to produce high quality reports with integrated business graphics.

Journaling Component Files

The built-in array file system is now a journaling file system, which means that component files can no longer be damaged by network failures or system crashes which occur in the middle of a file update.

Simplified Communications

Version 12.0 contains Conga, a new mechanism for developing client and server components which communicate with other web or network components. Conga supports client/server programming, and includes sample code to implement web clients and servers. From version 12.0.2 (April), Conga will include support for Secure communications using the Secure Socket Layer (SSL).

Language bar

All APL symbols are presented in a Language Bar in the session, with tips to remind you of the definition of each - and a link to comprehensive on-line help. The language bar can be completely configured to provide help for your own functions.

Integrated APL Keyboard

Unicode Edition supports the use of standard Windows keyboards that have the additional capability to generate APL characters when the user presses Ctrl, Alt, AltGr (or some other combination of meta keys) in combination with the normal character keys.

Version 12.0 is supplied with a two sets of such keyboards (one using Ctrl and one using AltGr) for a range of different languages. These keyboards were created using the Microsoft Keyboard Layout Creator (MSKLC) and you may use the same tool to customise one of the supplied keyboards or to create a new one.

The AltGr set of APL keyboards supplied by Dyalog are designed to work with any application, and you should be able to use the one that corresponds to your own language as your default Windows keyboard. If so, you will not have to switch to a different keyboard every time you start Dyalog APL.

On-Screen Keyboard

Press a user-selectable keystroke or hold down Shift, Ctrl or Alt and you will be presented with a pop-up keyboard which shows the location of APL symbols on your keyboard, and allows you to pick them off using the mouse. Furthermore, the On-Screen keyboard, which is distributed under licence from Comfort Software, is a really useful tool that works with any Windows application.


Version 12.0 System Requirements

System Requirements

Microsoft Windows

Dyalog APL Version 12.0 supports the following Versions of Windows:

  • Windows Vista
  • Windows XP
  • Windows 2000
  • Windows Server 2003

Note that Dyalog APL Version 12.0 is not supported under Windows 95, Windows 98, Windows ME or Windows NT4.

Microsoft .Net Interface

Dyalog APL Version 12.0 ,Net Interface requires Version 2.0 or 3.0 of the Microsoft .Net Framework. It does not operate with .Net Version 1.0.


Classic and Unicode Editions

Unicode and Classic Editions

The defining feature of Version 12.0 is support for Unicode character data. This necessarily entails a change in the internal format of character arrays stored in the workspace and on component files and in external variables.

This in turn means that the adoption of Unicode may require code changes and data conversions in applications.

For this reason, Version 12.0 and a limited number of future Versions of Dyalog will be available in two separate editions; Unicode and Classic.

  • The Unicode edition is intended for users who need to develop Unicode applications now, and are prepared to make the necessary (usually small) changes to existing applications in order to support new Unicode character types.
  • The Classic edition is intended for customers who want to take advantage of other product enhancements, but do not wish to use Unicode at this time.

The two different editions are maintained from the same source code, and every effort will be made to ensure that they are identical except for the handling of character arrays, and the transfer of data into and out of the workspace.


Converting to Unicode

The adoption of Unicode is an important milestone in the evolution of Dyalog APL and the change to the way that character data is represented is fundamental. Although we have tried to minimise the impact, the requirement for users to make some changes in application code is inevitable.

If you use any of the features listed below, you will probably have to change your code to convert to Version 12.0 Unicode Edition.

  • Monadic Grade Up and Grade Down
  • Name Association
  • Data Representation
  • Native File Operations
  • Custom written DLLs and Auxiliary Processors
  • Mapped Files
  • External Data

Monadic Grade Up and Grade Down

Monadic Grade Up and Grade Down are based on the internal representation of characters. This means that Unicode arrays will sort in a different order than AVcode arrays. For example ⍋'aA' returns (2 1) in the Unicode Edition and (1 2) in the Classic Edition and all previous versions of Dyalog APL.

It will be necessary to re-evaluate the use of monadic ⍋ and ⍒ in Unicode Edition. Backwards compatibility and compatibility with Classic Edition can be achieved (if desired) by supplying ⎕AV as a left argument.

Name Association

Windows DLLs typically contain two versions of functions that process character arguments; one for ASCII and one for Unicode. They are distinguished by appending either "A" (ASCII) or "W" (Wide) to the name of the function in the argument to ⎕NA. For example, the specific name for the MessageBox() function is MessageBoxA (ASCII) or MessageBoxW (Unicode).

To convert to Unicode Edition, You will have to change all your ⎕NA statements that specify "A" as the function suffix. Further details.

Data Representation

In the Unicode Edition, the data type for character arrays is 80, 160 or 320; and not 82. This means that the results from ⎕DR will change. In particular, code which determines whether an array is a character array using expressions like {82=⎕DR ⍵} will not work in the Unicode Edition. Further details.

Native File Operations

Although the default data type for file operations involving character arrays will remain unchanged (80), in converting to Unicode Edition you should consider changing your code to handle characters that are not present in ⎕AVU. You may need to specify different data types for ⎕NAPPEND, ⎕NREPLACE, and ⎕NREAD.

Custom DLLs and Auxiliary Processors

Custom written DLLs and Auxiliary Processors which receive and return data in internal APL format need to be rewritten to recognise and use the new data types. Data type 82 may be returned and will be translated by Version 12.0. Thus, if an AP or DLL recognizes all the character types, it can work with both the Unicode and Classic Editions.

Mapped Files

Character data in raw mapped files will be interpreted differently in Unicode Edition. Further Details.

External Data

If you start using Unicode characters which are not in ⎕AVU in your application, and you use external forms of storage like SQL databases or native files, you need to consider which representation, or encoding, that you wish to use. For relational databases, SQAPL supports new Unicode data types, but your database may not have native support for these types. Very often, an encoding called UTF-8 is used to store Unicode characters, both in flat files but also in relational databases which do not have “native” Unicode support.

Version 12.0 provides tools for converting data to and from UTF-8, but you need to decide on a format and possibly convert your existing databases to use new data types and representations. If you use a lot of external data, these conversions may require more planning and implementation work than the changes required to move APL application code to the Unicode edition.


Interoperability

Workspaces and component files are stored on disk in a binary format (illegible to text editors). This format differs between machine architectures and among versions of Dyalog. For example a file component written by a PC will almost certainly have an internal format that is different from one written by a UNIX machine. Similarly, a workspace saved from Dyalog APL Version 12 will differ internally from one saved by a previous version of the interpreter.

It is convenient for versions of Dyalog running on different platforms to be able to “interoperate” by sharing workspaces and component files. However, this is not always possible. For example, if a new internal data structure is introduced in a particular version of Dyalog, previous versions could not be expected to make sense of it. In this case the load (or copy) from the older version would fail with the message:

this WS requires a later version of the interpreter.

Similarly, “large” (64-bit-addressing) component files are inaccessible to versions of the interpreter that pre-dated their introduction.

The second item in the right argument of ⎕FCREATE determines the addressing type of the file.

    'small'⎕fcreate 1 32    ⍝ create small file.
    'large'⎕fcreate 1 64    ⍝ create large file.

If the second item is missing, the file type defaults to 64-bit addressing

From Dyalog APL Version 11 onwards, there are two separate versions of programs for 32-bit and 64-bit machine architectures.

Interoperability is summed up in the following tables. Table rows show the version that is attempting to access the file or workspace and columns show the version that saved it:

This version can access files created by this version →
↓

The row and column titles show the Dyalog version 10.0, 10.1, etc; (32) and (64) indicate a version running on a 32-bit or 64-bit machine architecture, respectively.

Implementation

The following tables document compatibility between different versions of Dyalog APL. Each row represents a system which is accessing or receiving data, each column represents a system which has saved (or created, or sent) the data.

In each cell, “Yes” means that all data can be transferred successfully. “-“ means that data cannot be accessed or is not possible. “~” followed by one or more letters means that data can be read, with one or more exceptions:

o | Cannot read ⎕ORs. Note ⎕NULL is represented as a namespace.
t | Cannot tie files created on machines with different byte ordering.
r | Cannot read a component with different byte ordering.
w | Can read from but cannot write to files created on machines with different byte ordering (attempting to write generates FILE ACCESS ERROR).
u | Cannot tie a file with the Unicode property, cannot read components containing Unicode data. For sockets: Cannot read data in encoding Unicode.
j | Cannot tie a file with journaling enabled. Note that no versions prior to Version 12.0 can tie a journaled file.

In general, data is written, saved or transmitted in the format that is native to the writer. Readers do the work of any necessary translation. The exceptions to this rule are that:

  • A 64-bit system writing to a 32-bit file will write components in 32-bit format
  • Version 12 and above will write character data in either Unicode or non-Unicode format, depending on the Unicode bit of the file. 32-bit files are always non-Unicode.

Workspaces

Workspaces cannot be loaded if saved by “higher” versions.

 | 10.0 | 10.1 | 11.0 (32) | 11.0 (64) | 12.0 (32) | 12.0 (64)
10.0 | Yes | - | - | - | - | -
10.1 | Yes | Yes | - | - | - | -
11.0 (32) | Yes | Yes | Yes | Yes | - | -
11.0 (64) | - | Yes | Yes | Yes | - | -
12.0 (32 | Yes | Yes | Yes | Yes | Yes | Yes
12.0 (64) | - | Yes | Yes | Yes | Yes | Yes

Small (32-bit) Component Files and External variables

Small component files are limited in size to 4Gb and are limited to having the same architecture in all components.

 | 10.0 | 10.1 | 11.0 | 12.0
10.0 | ~t | ~t | ~ot | ~ot
10.1 | ~t | ~t | ~ot | ~ot
11.0 | ~w | ~w | ~w | ~ow
12.0 | ~w | ~w | ~w | ~w

Large (64-bit) Component files

Large component files were introduced in version 10.1, and are the default architecture used by 12.0. In large component files, each component has its own architecture information (byte order, 32/64 data size, Unicode).

 | 10.1 | 11.0 | 12.0
10.1 | Yes | ~ot | ~otu
11.0 | Yes | Yes | ~obu
12.0 | Yes | Yes | Yes

Sockets (Type 'APL')

 | 10.0 | 10.1 | 11.0 (32) | 11.0 (64) | 12.0 (32) | 12.0 (32)
10.0 | Yes | ~o | ~o | - | ~ou | -
10.1 | Yes | Yes | ~o | - | ~ou | -
11.0 (32) | Yes | Yes | Yes | Yes | ~ou | ~ou
11.0 (64) | Yes | Yes | Yes | Yes | ~ou | ~ou
12.0 (32) | Yes | Yes | Yes | Yes | Yes | Yes
12.0 (64) | Yes | Yes | Yes | Yes | Yes | Yes

Auxiliary Processes

A Dyalog process is restricted to starting an AP of exactly the same architecture. In other words, the AP must share the same word-width and byte-ordering as its interpreter process.

Session Files

Session (.dse) files may only be used on the platform on which they were created and saved.


Component Files

Version 12.0 introduces two new options for Component Files; journaling and Unicode support.

Default Address Size for ⎕FCREATE

From Version 12.0 onwards, the default address size for a component file is 64. In previous Versions it was 32.

The address size is of a component file is an optional parameter specified in the right argument of ⎕FCREATE. A value of 32 causes the internal component addresses to be represented by 32-bit values which allow a maximum file size of 4GB. A value of 64 (which is now the default) causes the internal component addresses to be represented by 64-bit values which allows file sizes up to operating system limits.

Note that a 32-bit component file may not contain Unicode character data.

Journaling File System

Version 12.0 allows journaling to be enabled for selected component files (see ⎕FPROPS). When journaling is enabled, files are updated using a journal which effectively prevents system or network failures from causing file damage. Enabling journaling will cause file write operations to run a little slower (the exact impact on performance will depend on the specific file operations being performed).

Versions of Dyalog prior to Version 12.0 will not be able to access files which have journaling enabled, but journaling can be switched off if this is necessary (see ⎕FPROPS).

Unicode Support

64-bit component files now possess a Unicode Property which determines whether or not character data will be stored as Unicode character data or using the internal representation employed by all previous Versions of Dyalog and by Version 12.0 Classic Edition (data type 82).

32-bit component files do not have this property and may not contain Unicode character data.

⎕FCOPY System Function

A new system function, ⎕FCOPY, is provided. This may be used to generate 64-bit component files from 32-bit component files, and as a generally useful tool to copy component files. The key point is that ⎕FCOPY replicates component time-stamps and user information in the files.


Development Environment

APL Language Bar

Version 12.0 provides an optional Window which is docked to the Session Window, to make it easy to pick APL symbols without using the keyboard. Furthermore, if you hover the mouse pointer over a symbol in the APL Language Bar, a pop-up tip is displayed to remind you of its usage.

Keyboard Shortcuts

The Dyalog Development Environment provides a number of shortcut keys that may be used to perform actions. These are identified by 2-character codes; for example the action to start the Tracer is identified by the code <TC>, and mapped to user-configurable keystrokes.

In all Versions of Dyalog prior to Version 12.0 Unicode Edition and in the Classic Edition, the mapping between keystrokes and actions is defined by the Input Translate Table.

Windows keyboards and IMEs do not support application specific accelerator keys, so for Version 12.0 Unicode Edition, this information is now specified separately using the Keyboard Shortcuts dialog (Options/Configure/Keyboard Shortcuts) and stored in the Windows Registry.

Built-In SharpPlot Graphics

Initially only in the 32-bit Windows version, a session menu will provide access to SharpPlot to produce graphics for the current object.


SharpPlot Graphics Tools

Introduction

Included with Version 12 (32-bit Windows versions only with the Microsoft .Net Framework Version 2.0 or later installed) is the SharpPlot graphics library which is part of the RainPro graphics package..

The Version 12.0 Session includes 4 buttons which use SharpPlot to generate simple graphical pictures of the contents of the Current Object (identified by the name under or to the left of the cursor).

For example, if you have a numerical matrix in a variable called MAT, you can plot it by first positioning the cursor on the name MAT in the Session window, and then clicking one of the 4 graphical buttons in the Session toolbar.

Data Structures

The charting function can plot variables with the following data structures:

  • a simple numeric vector
  • a vector of simple numeric vectors
  • a simple numeric matrix
  • a matrix whose first row contains simple character vectors and whose other elements are simple numerics. In bar and line charts, the column headings in row 1 are used as x-axis labels.
  • a matrix whose first column contains simple character vectors and whose other elements are simple numerics. In bar and line charts, the row headings in column 1 are used as legends to annotate the different series.
  • a matrix whose first row and first column both contain simple character vectors and whose other elements are simple numerics. In bar and line charts, the column headings in row 1 are used as x-axis labels, and the row headings in column 1 are used as legends annotate the different series.

Examples

Bar Chart

      Wine_Prices
1961 1964 1966
Lafite 8800 1342 1210
Latour 15400 2357.5 4600
Margaux 5980 672.5 920
Mouton Rothschild 6710 713 2070
Haut-Brion 13225 1840 1323

Line Chart

      First_Growths
1961 1964 1966 1970 1975 1976 1978 ...
Lafite 8800 1342 1210 605 1380 2070 920 ...
Latour 15400 2357.5 4600 2760 1552 978 1058 ...
Margaux 5980 672.5 920 632 900 800 1208 ...

Implementation

The SharpPlot tools are implemented by four buttons in the Session toolbar. Each button has a Select callback which runs the function ⎕SE.Chart.DoChart. This runs ⎕SE.Chart.Do which constructs and then runs a function named ⎕SE.Chart.MyChart.

⎕SE.Chart.MyChart uses an instance of the SharpPlot graphics class to produce a chart of your data, which it saves as a temporary file. It then calls the SharpPlot viewer to display the file on your screen.

SharpPlot is a library of graphical subroutines, (originally written in APL and machine-translated into C#) which is implemented as a .Net Namespace named Causeway and supplied in \bin\sharpplot.dll in the Dyalog program directory.

Notes

For further information on using SharpPlot, please see http://www.sharpplot.com/Docs.

Although ⎕SE.Chart.MyChart is overwritten by successive uses of the graphical buttons, it is deliberately not erased each time. This allows you to use MyChart as a simple template to develop your own custom graphics function.

The image is stored in Microsoft Enhanced Metafile Format in a temporary file whose name and location are generated automatically. The system does not delete the temporary file after use. For further details, See System.IO.Path.GetTempFileName.

The default program used to display the EMF file is SharpView.exe. You can opt to use a different EMF viewer by setting the Charts\ViewCMD registry key to name another program, such as Windows Picture and Fax Viewer.

An attempt to plot the contents of a variables with an unsupported data structure (see above) is handled entirely by error trapping and will result in an error message box and perhaps messages in the Status window.


Additional Tools

CausewayPro, RainPro, and NewLeaf

In April 2007, Dyalog acquired the Causeway range of productivity tools for APL developers. These tools are now bundled with Dyalog, starting with Version 12.0 for 32-bit Windows.

  • RainPro is a graphics package which produces high quality graphs for business and technical applications.
  • NewLeaf is a printing utility which can produce output in PDF and a number of other popular formats.
  • CausewayPro is a screen designer and application builder for simple applications.

Conga

Conga, also known as the Dyalog Remote Communicator, is a tool for communication between applications. Conga can be used to transfer APL Arrays between two Dyalog applications which are both using Conga, but it can also be used to exchange messages with other partners like HTTP Servers (also known as Web Servers), Web Browsers, or any other web clients or servers including Telnet, SMTP, POP3 and so forth.

Uses of Conga include, but are not limited to the following:

  • Retrieving information from, or posting data to, the internet.
  • Accessing internet-based services like FTP, SMTP, or telnet
  • Writing an APL application that acts as a Web (HTTP) Server, Mail Server or any other kind of service available over an intranet or the internet.
  • APL Remote Procedure Call servers which receive APL arrays from client applications, process data, and return APL arrays as the result.

Conga provides a significantly simpler application programming interface compared to the use of TCPSocket objects, and includes support for secure communications using SSL.

SALTed Utility Libraries

The Simple APL Library Toolkit (SALT) was introduced as an experimental tool with version 11.0. Starting with Version 12.0, Dyalog will gradually move towards using SALT and UTF-8 script files as the distribution mechanism for utilities and code samples. For a time, APL code will be distributed using both workspaces and the UTF-8 script files supported by SALT. In the future, SALT will become the preferred mechanism for this.

Version 12.0 includes tools and documentation on using SALT in combination with SubVersion, a popular source code management system. A public SubVersion server hosted by Dyalog, will allow users to collaborate on the development of open source, shared code libraries.


Miscellaneous

Performance Improvements for Set Functions

Dyadic ⍳ and other set functions (∊, ∩, ∪, and ~) are significantly faster for certain arguments.

Matrix Iota idiom

The matrix iota idiom M{(↓⍺)⍳↓⍵}M which used only to operate on character matrices, now operates on any matrices.

New idiom

There is a new idiom Catenate To (,←).

Atomic Vector Index idiom

The atomic vector index idiom ⎕AV⍳CA is is not implemented in Unicode Edition, and should be replaced in both Editions by ⎕UCS.


Control Characters

It is often necessary to output control characters such as Tab, Newline, Linefeed and Backspace. Traditionally, these have been obtained by indexing into ⎕TC and ⎕AV.

With the advent of Unicode, this practice is now discouraged and it is strongly recommended that you generate control characters using ⎕UCS instead. This recommendation holds true even if you continue to use the Classic Edition.

Control Character | Old | New
Tab | ⎕AV[10] | ⎕UCS 9
Newline | ⎕AV[4] ⎕TC[3] (⎕ML<3) ⎕TC[2] (⎕ML≥3) | ⎕UCS 13
Linefeed | ⎕AV[3] ⎕TC[2] (⎕ML<3) ⎕TC[3] (⎕ML≥3) | ⎕UCS 10
Backspace | ⎕AV[2] ⎕TC[1] | ⎕UCS 8


Unicode Support: Introduction

Introduction

Benefits

Unicode is an industry standard allowing computers to consistently represent and manipulate text expressed in any of the world's writing systems. It assigns a number, or code point, to each of approximately 100,000 characters, including the APL character set.

The adoption of Unicode provides users of Dyalog with two important benefits:

  • It is now possible to write Dyalog applications that fully and properly support not just American and Western European character sets, but all of the world’s languages and writing systems. You can now write applications that input, store, display and print characters in the entire Unicode set. This capability also extends to the Dyalog Development Environment.
  • Character data no longer needs to be translated as it enters or leaves Dyalog during inter-operation with other components like database systems or code libraries written in other languages.

Character Arrays

To support Unicode, the internal form of character arrays has changed

In all Versions of Dyalog APL prior to 12.0 (Unicode Edition), character arrays are stored internally as indices into the Atomic Vector (⎕AV). This contains 256 different characters, so internally, character arrays are represented by sequences of numbers in the range 0-255. Each character consumes 1 byte (8 bits) of storage. The data type of a simple character array, reported by ⎕DR, is 82.

In Version 12.0 Unicode Edition, character arrays are stored internally as Unicode code points, which are integers that the Unicode consortium (currently) guarantees will never consume more than 21 bits.

For arrays which only contain code points between 0 and 255 (more or less the ANSI set), one byte is sufficient to contain the necessary code point for each character. Characters contained in the first plane of Unicode, with code points up to 65,535 (hexadecimal FFFF), can be represented using two bytes per character. Unicode characters beyond the first plane are stored using 4 bytes per character.

In order to conserve space, Version 12.0 Unicode Edition uses three character types, in roughly the same way that Dyalog has three integer types (ignoring Booleans, which can be described as 1-bit integers). The three character types have type numbers 80, 160 and 320. Type 82 is no longer used. The system will select the smallest type required to represent the data in an array.

In the same way as for integers, the conversion between the three types is an internal matter and for the most part invisible to the user. The only occasions on which you need to be aware of the internal format is in considering space requirements for arrays, and when using system functions which are sensitive to the internal form, like ⎕DR and functions for manipulating native files.

Arrays with data type 82 are not supported in a Unicode Edition workspace. Data which has been stored by earlier Versions of Dyalog or by Classic Edition using character type 82 are translated to type 80, 160 or 320 on entry into a Unicode Edition workspace. In most cases, arrays containing APL characters will have type 160, other arrays will have type 80.


Keyboard Input

Introduction

All Versions of Dyalog APL prior to Version 12 employ a proprietary keyboard input mechanism in which the mapping of keystrokes to characters is defined through the Dyalog APL Input and Output Translate tables.

With the adoption of Unicode, it is no longer necessary for Dyalog to support a proprietary mechanism for entering (and displaying) APL symbols. APL characters are handled in the same way as all other Unicode characters, and like other Unicode characters, may be entered using whatever standard tools are provided to cater for unusual languages and special requirements.

Version 12.0 Unicode Edition no longer uses the Dyalog APL Input Translate Tables but instead works directly off standard Operating System keyboards and (under Windows) IMEs.

Version 12.0 Classic Edition, which does not support Unicode, continues to use the same proprietary keyboard input mechanism as before and the Dyalog Development Environment requires an Input Translate Table to specify the mechanism for entering APL symbols.

MSKLC Keyboards for APL Characters

Under Windows, Microsoft provides a tool called the Microsoft Keyboard Layout Creator (MSKLC) . This is intended to allow users to create custom keyboards to cater for requirements that are not covered by the standard sets of keyboards shipped with the different international editions of Windows.

Using the MSKLC Version 1.4, Dyalog has created a set of keyboards which are based upon standard National Language keyboards but which have the additional functionality to support APL characters. Using one of these keyboards, APL characters are entered using a special meta key in combination with the normal character keys. Other keystrokes operate as normal. There are two variants supplied; one in which APL symbols are entered using the Ctrl key in combination with the normal character keys, and one in which the AltGr key is used instead. The former is compatible with the keyboard layouts supported by previous Versions of Dyalog APL and will be familiar to existing users. The latter, which uses AltGr in place of Ctrl has the advantage that it does not override the conventional use of keystrokes such as Ctrl-c (Cut).

The Dyalog APL IME

Since 2001, Dyalog APL for Windows has included an IME for entering APL symbols This IME first appeared in Dyalog.Net and was intended to allow programmers to enter APL symbols into non-APL applications (such as editors and word-processors) to create APLScript files for ASP.NET and other .Net applications.

The Dyalog APL IME may be used with the Unicode Edition although it is effectively replaced by the MSKLC keyboards and will become a deprecated feature.

Keyboard Shortcuts

The Dyalog Development Environment provides a number of shortcut keys that may be used to perform actions. These are identified by 2-character codes; for example the action to start the Tracer is identified by the code <TC>, and mapped to user-configurable keystrokes.

In all Versions of Dyalog prior to Version 12.0 Unicode Edition and in the Classic Edition, the mapping between keystrokes and actions is defined by the Input Translate Table.

Windows keyboards and IMEs do not support application specific accelerator keys, so for Version 12.0 Unicode Edition, this information is now specified separately using the Keyboard Shortcuts dialog (Options/Configure/Keyboard Shortcuts) and stored in the Windows Registry.


APL Keyboard

Unicode Edition supports the use of standard Windows keyboards that have the additional capability to generate APL characters when the user presses Ctrl, Alt, AltGr (or some other combination of meta keys) in combination with the normal character keys.

Version 12.0 is supplied with two sets of such keyboards (one using Ctrl and one using AltGr) for a range of different languages as listed below. These keyboards were created using the Microsoft Keyboard Layout Creator (MSKLC) and you may use the same tool to customise one of the supplied keyboards or to create a new one.

Installation

During the Installation of Dyalog Version 12.0 Unicode Edition, setup installs one or two APL keyboard layouts onto your system. These keyboard layouts are installed as additional services for your default Input Language.

The following table lists the APL keyboards included with Dyalog APL Version 12.0 Unicode Edition at the time of publication. Other keyboards will be included as they are developed.

Ctrl Keyboards | AltGr Keyboards
Danish - Dyalog Ctrl | Danish - Dyalog AtGr
Finnish - Dyalog Ctrl | Finnish - Dyalog AltGr
French - Dyalog Ctrl | French - Dyalog AltGr
German - Dyalog Ctrl | German Dyalog AltGr
Icelandic - Dyalog Ctrl |
Italian - Dyalog Ctrl | Italian - Dyalog AltGr
Norwegian - Dyalog Ctrl |
Russian - Dyalog Ctrl |
Swedish - Dyalog Ctrl |
UK - Dyalog Ctrl | UK - Dyalog AltGr
US - Dyalog Ctrl | US - Dyalog AltGr

Setup automatically installs only those keyboards that correspond to your default Input Language, as specified via Control Panel/Regional and Language Options.

Note that if your default input language is not one of those listed in the table, Seup will not install any APL keyboards. However, you may create your own layout (or adapt one of the existing ones) using MSKLC).

The following picture illustrates the Text Services and Input Languages configuration pane after installing Unicode Edition onto a Windows XP system on which the default Input Language is English (United Kingdom). Incidentally, on this particular system, the Danish and Greek languages are also installed.

Configuring your APL Keyboard for Use

There are 3 different ways to use your APL keyboard:

  1. Make the APL keyboard your default Windows keyboard (for all applications)
  2. Configure APL to select your APL keyboard on start-up
  3. Manually select your APL keyboard for use with your APL session window every time you start APL.

Making your APL Keyboard the default Windows keyboard

Both the Dyalog AltGr and Dyalog Ctrl keyboard layouts are designed to be fully compatible with your standard keyboard and you may adopt one of these as your default Windows keyboard. To do this, simply make it the Default Input Language as illustrated by the next 2 pictures. Note that the default keyboard layout is shown in bold.

To change your default keyboard (Windows XP), open Control Panel/Regional and Languages, select the Languages tab and click Details. This brings up the Text Services and Input Languages dialog box shown below. Select your choice of APL keyboard from the drop-down list as illustrated.

If you wish to, you can select a keystroke to enable you to select it quickly from the keyboard.

Automatic Keyboard Selection

Unicode Edition can optionally select your APL keyboard each time you start APL.

To achieve this, open the Unicode Input configuration pane (Options/Configure/Unicode Input) then:

  1. In the Keyboard drop-drown, select one of your installed APL keyboards.
  2. Enable the Activate selected keyboard checkbox
  3. Click OK

The value of the checkbox and the name of your chosen keyboard are saved in registry keys named InitialKeyboardLayoutInUse and InitialKeyboardLayout.

The choices shown in the above picture will be reflected by the following values:

  • InitialKeyboardLayoutInUse = 1
  • InitialKeyboardLayout = " UK - Dyalog AltGr"

Manual Keyboard Selection

Each time you start APL, the Session window will be associated with your current Windows keyboard layout. This will be either your default keyboard, or the one you most recently selected from the Language Bar.

On startup, Unicode Edition tests your current keyboard to see if it includes any definitions that will generate an APL symbol. If the current keyboard is incapable of capable of generating APL symbols, the system will display the following message box.

You can switch to an APL keyboard using the Language Bar, as illustrated in the following picture:


Character Usage and Restrictions

Atomic Vector ⎕AV

The Unicode Edition continues to support the atomic vector ⎕AV as a character array with 256 elements. To the human eye, its appearance is unchanged, and expressions which index ⎕AV or search it to find the positions of characters, produce the same results in the Unicode Edition as in the Classic Edition and in previous Versions of Dyalog.

Underscores

The underscored APL alphabet ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ is not included in the Unicode standard (presumably because underscore is seen as a display attribute in the same category as strikethrough, bold or italic), although Unicode does include delta-underscore, ⍙. This poses a serious problem because existing Dyalog applications include underscored characters in names (of APL objects) and in character arrays.

To resolve this problem, underscored characters are converted to corresponding characters in the Unicode circled alphabet, which contains the letters from Ⓐ to Ⓩ. Note that the APL 385 Unicode font, supplied with Dyalog displays the Unicode symbols Ⓐ to Ⓩ using the glyphs Ⓐ to Ⓩ, thereby (somewhat artificially) allowing application code and data to have the same visual appearance as before.

Dyalog strongly recommends that you move away from the use of the underscored alphabet, as these symbols now constitute the sole remaining non-standard use of characters in Dyalog applications.

Characters Allowed in User-Defined Names

In the Unicode character set, there are thousands of symbols which represent letters and ideograms. In principle, it would be possible to allow the use of all of these letters in user-defined names.

However, there are a number of interesting anomalies. For example, it might be confusing to allow the use of Greek lower-case letters α ε ι ρ ω in user-defined names, because they so closely resemble the APL symbols ⍺ ∊ ⍳ ⍴ ⍵.

In order to allow time for an orderly discussion and resolution of naming issues, Version 12.0 Unicode Edition takes a conservative approach and only allows letters which were already allowed in previous Versions of Dyalog APL, namely:

0123456789 (but not as the 1st character in a name)
ABCDEFGHIJKLMNOPQRSTUVWXYZ_
abcdefghijklmnopqrstuvwxyz
ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝß
àáâãäåæçèéêëìíîïðñòóôõöøùúûüþ
∆⍙
ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ

Note that using a standard Unicode font (rather than APL385 Unicode used in the table above), the last row above would appear as the circled alphabet, Ⓐ to Ⓩ.


Workspace and Performance Considerations

In the Unicode Edition, character arrays (including constants embedded in functions), which contain characters that are not in the first 256 Unicode code points, will consume twice as much space as in previous Versions of Dyalog.

When a function is imported into the Unicode Edition from a Classic Edition workspace, component file, or a workspace saved by a previous Version of Dyalog, comments in functions are converted to Unicode and the function is re-fixed. This has implications for space and speed.

  • Following conversion to Unicode, the function may consume more space. However, in Version 12.0 comments are stored as references to a table, where identical comments are shared, so this may actually reduce the space requirement.
  • The operation to re-fix the function takes time, more time if the function is very large. It is therefore recommended that you do not dynamically import functions from a Classic Edition workspace into the Unicode Edition (for example, using ⎕CY or by ⎕FX'ing a ⎕OR) in an application.


Name Association Enhancements

Enhancements to ⎕NA

The system function ⎕NA (Name Association) is used to load dynamically linked libraries, and perform name association between entry points in the libraries and function names in the workspace.

Version 12.0 contains a couple of enhancements aimed at making it easier to write name associations that are portable between the Unicode and Classic Editions.

Default width of T arguments

In Version 12.0 Unicode Edition, an argument type of T (without a width specification) is interpreted to mean a wide character according to the convention of the host operating system. This translates to T2 under Windows and T4 under Unix or Linux.

Note therefore that the use of type T with default width (arguments coded as <0T, >0T and =0T) is portable between Classic and Unicode Editions. This is because, in the Classic Edition, T (with no width specifier) implies 1-byte characters, translated from ⎕AV to ASCII, while In the Unicode Edition, T (with no width specifier) implies 2-byte characters.

If arguments or results need to be encoded in or decoded from UTF-8 or other formats, it is the programmer's task to do this using dyadic ⎕UCS.

Automatic Selection of A or W Functions

Under Windows, Win32 library calls are frequently available in two variants:

  • An ANSI (narrow) version with a name ending in A
  • a Unicode (wide) version with a name ending in W

For example, the function to display a message box is available as MessageBoxA and MessageBoxW.

In Version 12.0, you may specify the character * instead of A or W at the end of a function name. This will be replaced by A in the Classic Edition and W in the Unicode Edition. The default name of the associated function (if no left argument is given to ⎕NA), will be without the trailing letter (MessageBox).

For example, the following function will display a Message Box with OK & Cancel buttons in both Editions (under Windows):

   ∇ ok←title MsgBox msg;MessageBox
[1] ⎕NA'I user32∣MessageBox* I <0T <0T I'
[2] ok←1=MessageBox 0 msg title 1 ⍝ 1=OK, 2=Cancel.
   ∇


Data Representation Changes

Changes to ⎕DR

In the Unicode Edition, the data type for character arrays is 80, 160 or 320; and not 82. However, ⎕DR continues to recognise a left argument of 82 (when the right argument contains numeric data) and returns the same characters as in previous Versions of Dyalog, except that the results are converted (and translated) to one of the new character types 80, 160 or 320. A left argument of 82 is not allowed if the right argument contains Unicode character data.

Warning: Conversions of Unicode character data to numeric types will often give different results in the Unicode Edition, as the internal representation of characters is different.

Left arguments of 80, 160 and 320 can be used with ⎕DR in both the Classic and Unicode Editions. In the Classic Edition, a TRANSLATION ERROR will be signalled if the result would contain characters not in ⎕AVU.

Monadic ⎕DR on Character Arrays

Code which determines whether an array is a character array using expressions like {82=⎕DR ⍵} will not work in the Unicode Edition.

The following expression can be used in both Editions:

      ischar←{(10|⎕DR ⍵)∊0 2}

Dyadic ⎕DR on Character Arrays

Because the internal representation of character arrays has changed, the result of dyadic ⎕DR on character arrays has changed:

Classic Edition Unicode Edition
      ⎕DR '⍋'
82
      83 ⎕DR '⍋'
¯109
      163 ⎕DR '⍋'
LENGTH ERROR
      ⎕DR '⍋'
160
      83 ⎕DR '⍋'
75 35
      163 ⎕DR '⍋'
9035


Native File Implications

In the Unicode Edition, a character array will by default be written by ⎕NAPPEND and ⎕NREPLACE using type 80.

If the data will not fit into the implied character width (bytes) ⎕NAPPEND and ⎕NREPLACE will fail with a DOMAIN ERROR.

As a consequence of these two rules, you must specify the data type (either 160 or 320) in order to write Unicode characters whose code-points are in the range 256-65535 and >65535 respectively.

For compatibility with old files, you may specify that the data be converted to type 82 on both input (⎕NREAD) and output (⎕NAPPEND and ⎕NREPLACE). The conversion (to ⎕AV indices) will be determined by the local value of ⎕AVU.


Reading and Writing Unicode Files

Reading and Writing Unicode Native Files

Text files (native files) may be written in a variety of different formats. Notepad, for example, allows you to save files in ANSI, Unicode, Unicode big endian, and UTF-8 encodings.

In ANSI format, each character is stored as a single byte. This format is only suitable for storing ANSI characters (Unicode code point range 0-255) and corresponds directly to Dyalog data type 80.

In Unicode format (UTF-16) a single 16-bitcode unit is used to encode the first 65,536 most commonly used characters, and a pair of 16-bit code units, called surrogates, to encode the remaining less commonly used characters in Unicode.

In UTF-8 format, characters are represented by a mixture of single and multi-byte characters. Some character codes in the range (128-256) are used as lead-bytes to mark the start of multi-byte character codes. Using two or more bytes per character provides plenty of room to represent all the commonly used world characters.

Under Windows, native files are identified as containing Unicode data by the file signature which is a special prefix of 2 or 3 bytes at the beginning of the file. The following Unicode formats are frequently encountered.

Description | Signature
UTF-16 LE (Little Endian) | First 2 bytes are 0xFF, 0xFE (equivalent signed integers ¯1 ¯2)
UTF-8 | First 3 bytes are 0xEF, 0xBB, 0xBF (equivalent signed integers ¯17 ¯69 ¯65)

The following functions ReadFile and WriteFile may be used to read and write files that are compatible with Notepad. Note that the functions do not support files in UTF-32 or Unicode big endian formats, nor 32-bit Unicode characters (data type 320).

     ∇ Chars←ReadFile name;nid;signature;nums
[1]    ⍝ Read ANSI or Unicode character file (Windows)
[2]    nid←name ⎕NTIE 0
[3]    signature←3↑⎕NREAD nid 83 3 0
[4]    :If signature≡¯17 ¯69 ¯65 ⍝ UTF-8
[5]        nums←⎕NREAD nid 83(¯2+⎕NSIZE nid)3
[6]        Chars←'UTF-8'⎕UCS{⍵+256×⍵<0}nums ⍝ Signed ints
[7]    :ElseIf (2↑signature)≡¯1 ¯2 ⍝ Unicode (UTF-16)
[8]        Chars←⎕NREAD nid 160(¯1+⎕NSIZE nid)2
[9]    :Else ⍝ ANSI
[10]       Chars←⎕NREAD nid 80(⎕NSIZE nid)0
[11]   :EndIf
[12]   ⎕NUNTIE nid
     ∇

     ∇ {format}WriteFile(name chars);nid;signature;nums
[1]    ⍝ Write ANSI or Unicode character file (Windows)
[2]    ⍝ format = ANSI or UTF-8 or UTF-16
[3]    ⎕SIGNAL(~∨/80 160=⎕DR chars)/11
[4]    :If 0=⎕NC'format'
[5]        format←(80 160⍳⎕DR chars)⊃'ANSI' 'UTF-16'
[6]    :EndIf
[7]    ⎕SIGNAL(~(⊂format)∊'ANSI' 'UTF-8' 'UTF-16')/11
[8]    :Trap 22
[9]        nid←name ⎕NCREATE 0
[10]   :Else
[11]       nid←name ⎕NTIE 0
[12]       name ⎕NERASE nid
[13]       nid←name ⎕NCREATE 0
[14]   :EndTrap
[15]   :Select format
[16]      :Case 'ANSI'
[17]          chars ⎕NAPPEND nid 80
[18]      :Case 'UTF-8'
[19]          ¯17 ¯69 ¯65 ⎕NAPPEND nid 83
[20]          nums←⎕UCS'UTF-8'⎕UCS chars
[21]          nums ⎕NAPPEND nid 80
[22]      :Else
[23]          ¯1 ¯2 ⎕NAPPEND nid 83
[24]          chars ⎕NAPPEND nid 160
[25]   :EndSelect
[26]   ⎕NUNTIE nid
     ∇


Atomic Vector to Unicode System Function

Atomic Vector to Unicode ⎕AVU

The Dyalog APL atomic vector ⎕AV has always been, to some extent, user definable, as the mapping between extended ASCII symbols (actually, the indices into an ASCII font) and ⎕AV positions was defined by the Output Translate Table. The appearance of the characters in ⎕AV also depended upon which font was used.

In Version 12.0 Unicode Edition, the contents of ⎕AV are defined, not by the Output Translate Table, but by a new system variable ⎕AVU (Atomic Vector – Unicode) . Its purpose is twofold:

  1. To make it possible for each user to ensure that (each element of) ⎕AV contains the same character as before.
  2. To guide the translation of character data read from old files and workspaces to Unicode in such a way that the appearance or content of this data is unchanged.

⎕AVU is an integer vector with 256 elements, containing the Unicode code points corresponding to the symbols represented by ⎕AV.

When the Unicode Edition imports character data from a Classic Edition workspace or from a workspace saved by Version 11 or earlier, the conversion of data from type 82 is controlled by the value of ⎕AVU. This also applies to character data stored in non-Unicode component files or received on non-Unicode TCPSocket connections.

When you load or copy an old workspace into the Unicode Edition, you can control the conversion of character data from that workspace by setting ⎕AVU first.

The default value of ⎕AVU corresponds to the use of the Dyalog Alt font with the default win.dot Output Translate Table in the Classic Edition or in earlier versions of Dyalog APL.


Unicode Convert Introduction

Unicode Convert ⎕UCS

⎕UCS converts (Unicode) characters into integers and vice versa.

Used monadically, it simply converts between Unicode characters and Unicode code points.

Used dyadically, the optional left argument converts a character string to or from its UTF-8, UTF-16 or UTF-32 encoding schemes.


Language Bar

APL Language Bar

The APL Language Bar is an optional window which is docked to the Session Window, to make it easy to pick APL symbols without using the keyboard.

If you hover the mouse pointer over a symbol in the APL Language Bar, a pop-up tip is displayed to remind you of its usage.

Keyboard Shortcuts

The Dyalog Development Environment provides a number of shortcut keys that may be used to perform actions. These are identified by 2-character codes; for example the action to start the Tracer is identified by the code <TC>, and mapped to user-configurable keystrokes.

In the Unicode Edition, Keyboard Shortcuts are defined using the Keyboard Shortcuts Configuration dialog (Options/Configure/Keyboard Shortcuts) and stored in the Windows Registry.

To the right of the last symbol in the Language Bar is the Keyboard Shortcut icon

If you hover the mouse over this icon, a pop-up tip is displayed to remind you of your keyboard shortcuts, as illustrated below. If you click the icon, the Keyboard Shortcuts Configuration dialog is displayed.


On-Screen Keyboard

Included with Dyalog APL Version 12.0 Unicode Edition is the Comfort On-Screen Keyboard 2.1 which has been specially extended for use with Dyalog APL and is distributed under a licence agreement with Comfort Software. The On-Screen keyboard is a really useful tool that works with any Windows application and replaces Kibitzer in the Unicode Edition. Kibitzer remains part of the Classic Edition.

The On-Screen keyboard is highly configurable and supports a wide range of visual effects including different colour schemes and transparency options.

Not only does it support a large number of standard keyboard layouts, but it includes a tool to design your own layout corresponding to the physical keyboard attached to your computer.

You may choose to have the On-Screen keyboard permanently shown or have it pop-up on a specific keystroke or when you press and hold Shift, Ctrl or Alt, and there is a corresponding variety of ways to have it disappear.

The following pictures illustrate the appearance of a UK - Dyalog AltGr keyboard, in Normal, AltGr and AltGr+Shift modes.

Normal

AltGr mode

AltGr+Shift mode


Version 12 Help System

Version 12.0 Help System

The Help Menu

The Dyalog APL Version 12.0 help system is packaged as a single Microsoft HTML Help compiled help file named help\dyalog.chm.

In the same help sub-directory, you will find the complete collection of system documentation in PDF format which may conveniently be accessed via the Documentation Center menu item.

Label | Action | Description
Documentation Centre | [DocCenter] | Opens your web browser on help\index.html which displays an index to the on-line PDF documentation and selected internet links.
Latest Enhancements | [RelNotes] | Opens help\dyalog.chm, starting at the first topic in the Version 12.0 Release Notes section. Note that the Version 11.0 Release Notes are also included for your convenience.
Language Help | [LangHelp] | Opens help\dyalog.chm, starting at the first topic in the Language Reference section.
Gui Help | [GuiHelp] | Opens help\dyalog.chm, starting at the first topic in the Object Reference section.
Dyalog Web Site | [DyalogWeb] | Opens your web browser on the Dyalog home page.
Email Dyalog | [DyalogEmail] | Opens your email client and creates a new message to Dyalog Support, with information about the Version of Dyalog APL you are running.
About Dyalog APL | [About] | Displays an About dialog box.


Edit Window Toolbar

The Edit Window now has a toolbar to simplify frequently used operations, namely:

  • Toggle line numbers
  • Comment selected lines
  • Remove comments from selected lines
  • Search


Unicode Input Dialog

Unicode Input

Unicode Edition can optionally select your APL keyboard each time you start APL.

To choose this option, open Options/Configure/Unicode Input. In the Keyboard drop-drown, select one of your installed APL keyboards, enable the Activate selected keyboard checkbox, then click OK

Label | Parameter | Description
Activate selected keyboard | InitialKeyboardLayoutInUse | 1 = automatically select the specified APL keyboard on startup. 0 = no action.
Keyboard | InitialKeyboardLayout | the name of the APL keyboard to be selected.


Keyboard Shortcut Configuration Dialog

Keyboard Shortcuts

The Dyalog Development Environment provides a number of shortcut keys that may be used to perform actions. These are identified by 2-character codes; for example the action to start the Tracer is identified by the code <TC>, and mapped to user-configurable keystrokes.

In the Unicode Edition, Keyboard Shortcuts are defined using the Keyboard Shortcuts Configuration dialog (Options/Configure/Keyboard Shortcuts) and stored in the Windows Registry.

To alter the keystroke associated with a particular action, simply select the action required and press the keystroke.

For example, to change the keystroke associated with the action <UA> (undo all changes) from (None) to Ctrl+Shift+u, simply select the corresponding row in the list and press Ctrl+Shift+u.

If Confirm before Overwrite is checked, you will be prompted to confirm or cancel before each and every change is written back to the registry.


SALT Configuration Dialog

SALT

SALT is the Simple APL Library Toolkit, a simple source code management system for Classes and script-based Namespaces. SPICE uses SALT to manage development tools which “plug in” to the Dyalog session

Label | Parameter | Description
Enable Salt | AddSALT | Specifies whether or not SALT is enabled
Enable Spice | AddSPICE | Specifies whether or not SPICE is enabled. Note that SPICE cannot be enabled without SALT.
Compare command line | CompareCMD | The command line for a 3rd party file comparison tool to be used to compare two versions of a file. See note.
Editor | Editor | Name of the program to be used to edit script files (default "Notepad").
Class source folders | SourceFolder | Sets the SALT working directory; a list of folders to be searched for source code.

Compare command line

The default value of “apl” for the Compare command line instructs SALT to use built-in APL code when comparing two versions of a file. If you have a 3rd party file comparison tool which can compare UTF-8 files, enter the name of the program here. For example, if you have installed “Compare It!”, you would enter: “[ProgramFiles]\Compare It!\wincmp3” (this assumes that the program will take two parameters containing the names of two files to be compared).

More Information

For more information about using SALT and SPICE, see the SALT and SPICE manuals, which can be most easily located via the Documentation Centre.


Data Representation (Monadic)

R←⎕DR Y

Monadic ⎕DR returns the type of its argument Y. The result R is an integer scalar containing one of the following values:

Unicode Edition Classic Edition
Value | Data Type
11 | 1 bit Boolean
80 | 8 bits Character
83 | 8 bits Signed Integer
160 | 16 bits Character
163 | 16 bits Signed Integer
320 | 32 bits Character
323 | 32 bits Signed Integer
326 | 32 bits Pointer
645 | 64 bits Floating

Value | Data Type
11 | 1 bit Boolean
82 | 8 bits Character
83 | 8 bits Signed Integer
163 | 16 bits Signed Integer
323 | 32 bits Signed Integer
326 | 32 bits Pointer
645 | 64 bits Floating

Note that types 80, 160 and 320, and 83 and 163, are exclusive to Dyalog APL.


Data Representation (Dyadic)

R←X ⎕DR Y

Dyadic ⎕DR converts the data type of its argument Y according to the type specification X. See monadic ⎕DR in the previous topic for a list of data types.

Case 1: X is a single integer value. The bits in the right argument are interpreted as elements of an array of type X. The shape of the resulting new array will typically be changed along the last axis. For example, a character array seen as Boolean will have 8 times as many elements along the last axis.

Case 2: X is a 2-element integer value. The bits in the right argument are interpreted as type X[1]. The system then attempts to convert the elements of the resulting array to type X[2] without loss of precision. The result R is a two element nested array comprised of:

[1] | The converted elements or a fill element (0 or blank) where the conversion failed
[2] | A Boolean array of the same shape indicating which elements were successfully converted.

Case 3: Classic Edition Only. X is a 3-element integer value and X[2 3] is 163 82. The bits in the right argument are interpreted as elements of an array of type X[1]. The system then converts them to the character representation of the corresponding 16 bit integers. This case is provided primarily for compatibility with APL*PLUS. For new applications, the use of the [conv] field with ⎕NAPPEND and ⎕NREPLACE is recommended.

Conversion to and from character (data type 82) uses the translate vector given by ⎕NXLATE. By default this is the mapping defined by the current output translate table (usually WIN.DOT).

Note: The internal representation of data may be modified during workspace compaction. For example, numeric arrays and (in the Unicode Edition) character arrays will, if possible, be squeezed to occupy the least possible amount of memory. However, the internal representation of the result R is guaranteed to remain unmodified until it is re-assigned (or partially re-assigned) with the result of any function.


Grade Down (monadic)

Grade Down

R←⍒Y

Y must be a simple character or simple numeric array of rank greater than 0.  R is an integer vector being the permutation of ⍳1↑⍴Y that places the sub-arrays of Y along the first axis in descending order.  The indices of any set of identical sub-arrays in Y occur in R in ascending order.

If Y is a numeric array of rank greater than 1, the elements in each of the sub-arrays along the first axis are compared in ravel order with greatest weight being given to the first element and least weight being given to the last element.

Example:

     M
2 5 3 2
3 4 1 1
2 5 4 5
2 5 3 2
2 5 3 4

      ⍒M
2 3 5 1 4

      M[⍒M;]
3 4 1 1
2 5 4 5
2 5 3 4
2 5 3 2
2 5 3 2

If Y is a character array, the implied collating sequence is the numerical order of the corresponding Unicode code points (Unicode Edition) or the ordering of characters in ⎕AV
(Classic Edition).

⎕IO  is an implicit argument of Grade Down.

Note that character arrays sort differently in the Unicode and Classic Editions.

      M
Goldilocks
porridge
Porridge
3 bears

    Unicode Edition
    Classic Edition

      ⍒M
2 3 1 4

      ⍒M
3 1 4 2

      M[⍒M;]
porridge
Porridge
Goldilocks
3 bears

      M[⍒M;]
Porridge
Goldilocks
3 bears
porridge


Grade Up (monadic)

Grade Up

R←⍋Y

Y must be a simple character or simple numeric array of rank greater than 0.  R is an integer vector being the permutation of ⍳1↑⍴Y that places the sub-arrays along the first axis in ascending order.

If Y is a numeric array of rank greater than 1, the elements in each of the sub-arrays along the first axis are compared in ravel order with greatest weight being given to the first element and least weight being given to the last element.

Examples:

      ⍋22.5 1 15 3 ¯4
5 2 4 3 1

      M
2 3 5
1 4 7

2 3 5
1 2 6

2 3 4
5 2 4

      ⍋M
3 2 1

If Y is a character array, the implied collating sequence is the numerical order of the corresponding Unicode code points (Unicode Edition) or the ordering of characters in ⎕AV
(Classic Edition).

⎕IO is an implicit argument of Grade Up.

Note that character arrays sort differently in the Unicode and Classic Editions.

      M
Goldilocks
porridge
Porridge
3 bears

    Unicode Edition
    Classic Edition

      ⍋M
4 1 3 2

          ⍋M

      2 4 1 3

      M[⍋M;]
3 bears
Goldilocks
Porridge
porridge

      M[⍋M;]
porridge
3 bears
Goldilocks
Porridge


Unicode Convert

R←{X} ⎕UCS Y

⎕UCS converts (Unicode) characters into integers and vice versa.

The optional left argument X is a character vector containing the name of a variable-length Unicode encoding scheme which must be one of:

  • 'UTF-8'

  • 'UTF-16'

  • 'UTF-32'

If not, a DOMAIN ERROR is issued.

If X is omitted, Y is a simple character or integer array, and the result R is a simple integer or character array with the same rank and shape as Y.

If X is specified, Y must be a simple character or integer vector, and the result R is a simple integer or character vector.

Monadic ⎕UCS

Used monadically, ⎕UCS simply converts characters to Unicode code points and vice-versa.

With a few exceptions, the first 256 Unicode code points correspond to the ANSI character set.

      ⎕UCS 'Hello World'
72 101 108 108 111 32 87 111 114 108 100

      ⎕UCS 2 11⍴72 101 108 108 111 32 87 111 114 108 100
Hello World
Hello World

The code points for the Greek alphabet are situated in the 900's:

      ⎕UCS 'καλημέρα ελλάδα'
954 945 955 951 956 941 961 945 32 949 955 955 940 948 945

Thanks to work done by the APL Standards committee in the previous millennium, Unicode also contains the APL character set. For example:

      ⎕UCS 123 40 43 47 9077 41 247 9076 9077 125
{(+/⍵)÷⍴⍵}

Dyadic ⎕UCS

Dyadic ⎕UCS is used to translate between Unicode characters and one of three standard variable-length Unicode encoding schemes, UTF-8, UTF-16 and UTF-32. These represent a Unicode character string as a vector of 1-byte (UTF-8), 2-byte (UTF-16) and 4-byte (UTF-32) signed integer values respectively.

      'UTF-8' ⎕UCS 'ABC'
65 66 67
      'UTF-8' ⎕UCS 'ABCÆØÅ'
65 66 67 195 134 195 152 195 133
      'UTF-8' ⎕UCS 195 134, 195 152, 195 133
ÆØÅ

      'UTF-8' ⎕UCS 'γεια σου'
206 179 206 181 206 185 206 177 32 207 131 206 191 207 133
      'UTF-16' ⎕UCS 'γεια σου'
947 949 953 945 32 963 959 965
      'UTF-32' ⎕UCS 'γεια σου'
947 949 953 945 32 963 959 965

Because integers are signed, numbers greater than 127 will be represented as 2-byte integers (type 163), and are thus not suitable for writing directly to a native file. To write the above data to file, the easiest solution is to use ⎕UCS to convert the data to 1-byte characters and append this data to the file:

(⎕UCS 'UTF-8' ⎕UCS 'ABCÆØÅ') ⎕NAPPEND tn

Note regarding UTF-16: For most characters in the first plane of Unicode (0000-FFFF), UTF-16 and UCS-2 are identical. However, UTF-16 has the potential to encode all Unicode characters, by using more than 2 bytes for characters outside plane 1.

      'UTF-16' ⎕UCS 'ABCÆØÅ⍒⍋'
65 66 67 198 216 197 9042 9035
      ⎕←unihan←⎕UCS (2×2*16)+⍳3 ⍝ x20001-x20003

      'UTF-16' ⎕UCS unihan
55360 56321 55360 56322 55360 56323


File Copy

R←X ⎕FCOPY Y

Access Code 4609

Y must be a simple integer scalar or 1 or 2-element vector containing the file tie number and optional passnumber. The file need not be tied exclusively.

X is a character vector containing the name of a new file to be copied to.

⎕FCOPY creates a copy of the tied file specified by Y, named X. The new file X will be a 64-bit file, but will otherwise be identical to the original file. In particular all component level information, including the user number and update time, will be the same. The operating system file creation, modification and access times will be set to the time at which the copy occurred.

The result R is the file tie number associated with the new file X.

Example

      told←'oldfile32'⎕FTIE 0
      'S' ⎕FPROPS told
32
      tnew←'newfile64' ⎕FCOPY told

      'S' ⎕FPROPS tnew
64

If X specifies the name of an existing file, the operation fails with a FILE NAME ERROR.

Note: This operation is atomic. If an error occurs during the copy operation (such as disk full) or if a strong interrupt is issued, the copy will be aborted and the new file X will not be created.


Atomic Vector

R←⎕AV

⎕AV is a deprecated feature and is replaced by ⎕UCS.

This is a simple character vector of all 256 characters in the Classic Dyalog APL character set.

In the Classic Edition the contents of ⎕AV are defined by the Output Translate Table.

In the Unicode Edition, the contents of ⎕AV are defined by the system variable ⎕AVU.

Example:

      ⎕AV[48+⍳10]
0123456789

      5 52⍴12↓⎕AV
%'⍺⍵_abcdefghijklmnopqrstuvwxyz__¯.⍬0123456789_¤¥$£¢
∆ABCDEFGHIJKLMNOPQRSTUVWXYZ__ý·⍙ÁÂÃÇÈÊËÌÍÎÏÐÒÓÔÕÙÚÛ
ÝÞãìðòõ{€}⊣⌷¨ÀÄÅÆ⍨ÉÑÖØÜßàáâäåæçèéêëíîïñ[/⌿\⍀<≤=≥>≠∨∧
-+÷×?∊⍴~↑↓⍳○*⌈⌊∇∘(⊂⊃∩∪⊥⊤|;,⍱⍲⍒⍋⍉⌽⊖⍟⌹!⍕⍎⍫⍪≡≢óôöø"#-&_
___________@ùúû_ü`_¶:⍷¿¡⋄←→⍝)] §⎕⍞⍣%'⍺⍵_abcdefghijk

Note: Due to Windows restrictions, the line-drawing symbols in ⎕AV[⎕IO+219+⍳11] are not always displayed or printed correctly, and will often appear as _, as in this document.


Underscored Alphabet

R←⎕Ⓐ

⎕Ⓐ is a deprecated feature.

Dyalog strongly recommends that you move away from the use of ⎕Ⓐ and of the underscored alphabet itself, as these symbols now constitute the sole remaining non-standard use of characters in Dyalog applications.

In Versions of Dyalog APL prior to Version 11.0, ⎕Ⓐ was a simple character vector, composed of the letters of the alphabet with underscores. If the Dyalog Alt font was in use, these symbols displayed as additional National Language characters.

Version 10.1 and Earlier

      ⎕Ⓐ
ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ

For compatibility with previous versions of Dyalog APL, functions that contain references to ⎕Ⓐ will continue to return characters with the same index in ⎕AV as before. However, the display of ⎕Ⓐ is now ⎕Á, and the old underscored symbols appear as they did in previous Versions when the Dyalog Alt font was in use.

Current Version

      ⎕Á
ÁÂÃÇÈÊËÌÍÎÏÐÒÓÔÕÙÚÛÝþãìðòõ


Create File

{R}←X ⎕FCREATE Y

Y must be a simple integer scalar or a 1 or 2 element vector containing the file tie number followed by an optional address size.

The file tie number must not be the tie number associated with another tied file.

The address size is an integer and may be either 32 or 64. A value of 32 causes the internal component addresses to be represented by 32-bit values which allow a maximum file size of 4GB. A value of 64 (the default) causes the internal component addresses to be represented by 64-bit values which allows file sizes up to operating system limits.

Notes:

  • a 32-bit file may not contain Unicode character data.
  • a 64-bit component file may not be accessed by versions of Dyalog APL prior to Version 10.1.0

X must be either

  1. a simple character scalar or vector which specifies the name of the file to be created. See User Guide for file naming conventions under UNIX and Windows.
  2. a vector of length 1 or 2 whose items are:
    1. a simple character scalar or vector as above.
    2. an integer scalar specifying the file size limit in bytes.

The newly created file is tied for exclusive use.

The shy result of ⎕FCREATE is the tie number of the new file.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create or tie operation, allocates, and returns as an explicit result, the first (closest to zero) available tie number. This allows you to simplify code. For example:

from:

      tie←1+⌈/0,⎕FNUMS    ⍝ With next available number,
      file ⎕FCREATE tie   ⍝ ... create file.

to:

      tie←file ⎕FCREATE 0 ⍝ Create with first available..

Examples

      '..\BUDGET\SALES'    ⎕FCREATE 2    ⍝ Windows
      '../budget/SALES.85' ⎕FCREATE 2    ⍝ UNIX

      'COSTS' 200000 ⎕FCREATE 4          ⍝ max size 200000

      'LARGE' ⎕FCREATE 5 64              ⍝ 64-bit file
      'SMALL' ⎕FCREATE 6 32              ⍝ 32-bit file


Map File

R←{X}⎕MAP Y

This function associates a mapped file with an APL array in the workspace.

Two types of mapped files are supported; APL and raw. An APL mapped file contains the binary representation of a Dyalog APL array, including its header. A file of this type must be created using the supplied utility function ∆MPUT. When you map an APL file, the rank, shape and data type of the array is obtained from the information on the file.

A raw mapped file is an arbitrary collection of bytes. When you map a raw file, you must specify the characteristics of the APL array to be associated with this data. In particular, the data type and its shape.

The type of mapping is determined by the presence (raw) or absence (APL) of the left argument to ⎕MAP.

The right argument Y specifies the name of the file to be mapped and, optionally, the access type and a start byte in the file. Y may be a simple character vector, or a 2 or 3-element nested vector containing:

  1. file name (character scalar/vector)
  2. access code (character scalar/vector) : one of : 'R' , 'W', 'r' or 'w'
  3. start byte offset (integer scalar/vector). This must be a multiple of 4 (default is 0)

If X is specified, it defines the type and shape to be associated with raw data on file. X must be an integer scalar or vector. The first item of X specifies the data type and must be one of the following values:

Unicode Edition | 11, 80, 83, 160, 163, 320, 323 or 645
Classic Edition | 11, 82, 83, 163, 323 or 645.

Following items determine the shape of the mapped array. A value of ¯1 on any (but normally the first) axis in the shape is replaced by the system to mean: read as many complete records from the file as possible. Only one axis may be specified in this way.

If no left argument is given, file is assumed to contain a simple APL array, complete with header information (type, rank, shape, etc).

Mapped files may be updated by changing the associated array using indexed assignment: var[a]←b.

Note that a raw mapped file may be updated only if its file offset is 0.

Examples

Map raw file as a read-only vector of doubles:

      vec←645 ¯1 ⎕MAP'c:\myfile'

Map raw file as a 20-column read-write matrix of 1-byte integers:

      mat←83 ¯1 20 ⎕MAP'c:\myfile' 'W'

Replace some items in mapped file:

      mat[2 3;4 5]←2 2⍴⍳4

Map bytes 100-180 in raw file as a 5×2 read-only matrix of doubles:

      dat←645 5 2 ⎕MAP'c:\myfile' 'R' 100

Put simple 4-byte integer array on disk ready for mapping:

      (83 323 ⎕DR 2 3 4⍴⍳24)∆MPUT'c:\myvar'

Then, map a read-write variable:

      var←⎕MAP'c:\myvar' 'w'

Note that a mapped array need not be named. In the following example, a ‘raw’ file is mapped, summed and released, all in a single expression:

      +/163 ¯1 ⎕MAP'c:\shorts.dat'
42

Compatibility between Editions

In the Unicode Edition ⎕MAP will fail with a TRANSLATION ERROR if you attempt to map an APL file which contains character data type 82.

In order for the Unicode Edition to correctly interpret data in a raw file that was written using data type 82, the file may be mapped with data type 83 and the characters extracted by indexing into ⎕AVU.


Name Association

{R}←{X}⎕NA Y

⎕NA provides access from APL to compiled functions within a Dynamic Link Library (DLL). A DLL is a collection of functions typically written in C (or C++) each of which may take arguments and return a result.

Instructional examples using ⎕NA can be found in supplied workspace: QUADNA.DWS.

The DLL may be part of the standard operating system software, purchased from a third party supplier, or one that you have written yourself.

The right argument Y is a character vector that identifies the name and syntax of the function to be associated. The left argument X is a character vector that contains the name to be associated with the external function. If the ⎕NA is successful, a function (name class 3) is established in the active workspace with name X. If X is omitted, the name of the external function itself is used for the association.

The shy result R is a character vector containing the name of the external function that was fixed.

For example, math.dll might be a library of mathematical functions containing a function divide. To associate the APL name div with this external function:

      'div' ⎕NA 'F8 math|divide I4 I4'

where F8 and I4, specify the types of the result and arguments expected by divide. The association has the effect of establishing a new function: div in the workspace, which when called, passes its arguments to divide and returns the result.

      )fns
div
      div 10 4
2.5

Type Declaration

In a compiled language such as C, the types of arguments and results of functions must be declared explicitly. Typically, these types will be published with the documentation that accompanies the DLL. For example, function divide might be declared:

    double divide(long int, long int);

which means that it expects two long (4-byte) integer arguments and returns a double (8-byte) floating point result. Notice the correspondence between the C declaration and the right argument of ⎕NA:

    C:             double      divide (long int, long int);
    APL: 'div' ⎕NA '   F8 math|divide        I4        I4 '

It is imperative that care be taken when coding type declarations. A DLL cannot check types of data passed from APL. A wrong type declaration will lead to erroneous results or may even cause the workspace to become corrupted and crash.

The full syntax for the right argument of ⎕NA is:

[result] library|function [arg1] [arg2] ...

Note that functions associated with DLLs are never dyadic. All arguments are passed as items of a (possibly nested) vector on the right of the function.

Locating the DLL

The DLL may be specified using a full or relative pathname, file extension, and function type.

Pathname: APL uses the LoadLibrary() system function under Windows and dlopen() under UNIX and LINUX to load the DLL. If a full or relative pathname is omitted, these functions search standard operating system directories in a particular order. For further details, see the operating system documentation about these functions.

Alternatively, a full or relative pathname may be supplied in the usual way:

      ⎕NA'... c:\mydir\mydll|foo ...'

Errors: If APL cannot find the specified DLL it will generate:

FILE ERROR 1 No such file or directory

If APL finds the DLL but not the specified library function, it will generate:

VALUE ERROR

File Extension: If the file extension is omitted, .dll is assumed. Note that some DLLs are in fact .exe files, and in this case the extension must be specified explicitly:

      ⎕NA'... mydll.exe|foo ...'

Function Type

On a Windows computer, two distinct conventions, namely ‘C’ and ‘Pascal’ are in use for passing of arguments and receipt of results. If the type of the function you are calling differs from the default, for your version of Dyalog APL (see below) you must specify the function type explicitly immediately following the DLL name. Combinations are

C32 | 32 bit, C calling convention (Default)
P32 | 32 bit, Pascal calling convention

Example

      ⎕NA'... mydll.exe.P32|foo ...'    ⍝ 32 bit Pascal

Call by Ordinal Number

A DLL may associate an ordinal number with any of its functions. This number may then be used to call the function as an alternative to calling it by name. Using ⎕NA to call by ordinal number uses the same syntax but with the function name replaced with its ordinal number. For example:

      ⎕NA'... mydll|57 ...'

Multi-Threading

Appending the ‘&’ character to the function name causes the external function to be run in its own system thread. For example:

      ⎕NA'... mydll|foo& ...'

This means that other APL threads can run concurrently with the one that is calling the ⎕NA function.

Data Type Coding Scheme

The type coding scheme introduced above is of the form:

[direction] [special] type [width] [array]

The options are summarised in the following table and their functions detailed below.

Description | Symbol | Meaning
Direction | < | Pointer to array input to DLL function.
 | > | Pointer to array output from DLL function.
 | = | Pointer to input/output array.
Special | 0 | Null-terminated string.
 | # | Byte-counted string.
Type | I | int
 | U | unsigned int
 | C | char
 | T | Classic Edition: char (translated to/from ANSI)
 |  | Unicode Edition: char
 | F | float
 | A | APL array
 | 1 | 1-byte
 | 2 | 2-byte
 | 4 | 4-byte
 | 8 | 8-byte
Array | [n] | Array of length n elements
 | [] | Array, length determined at call-time.
Structure | {...} | Structure.

In the Classic Edition, C specifies untranslated character, whereas T specifies that the character data will be translated to/from ⎕AV.

In the Unicode Edition, C and T are identical (no translation of character data is performed) except that for C the default width is 1 and for T the default width is "wide" (2 bytes under Windows).

The use of T with default width is recommended to ensure portability between Editions.

Direction

C functions accept data arguments either by value or by address. This distinction is indicated by the presence of a ‘*’ character in the argument declaration:

   int  num1;   // value of num1 passed.
   int *num2;   // Address of num2 passed.

An argument (or result) of an external function of type pointer, must be matched in the ⎕NA call by a declaration starting with one of the characters: <, >, or =.

In C, when an address is passed, the corresponding value can be used as either an input or an output variable. An output variable means that the C function overwrites values at the supplied address. Because APL is a call-by-value language, and doesn’t have pointer types, we accommodate this mechanism by distinguishing output variables, and having them returned explicitly as part of the result of the call.

This means that where the C function indicates a pointer type, we must code this as starting with one of the characters: <, > or =.

< | indicates that the address of the argument will be used by C as an input array and values at the address will not be over-written.
> | indicates that C will use the address as an output variable. In this case, APL must allocate an output array over which C can write values. After the call, this array will be included in the nested result of the call to the external function.
= | indicates that C will use the address for both input and output. In this case, APL duplicates the argument array into an output buffer whose address is passed to the external function. As in the case of an output only array, the newly modified copy will be included in the nested result of the call to the external function.

Examples

<I2 | Pointer to 2-byte integer - input to external function
>C | Pointer to character output from external function.
=T | Pointer to character input to and output from function.
=A | Pointer to APL array modified by function.

Special

In C it is common to represent character strings as null-terminated or byte counted arrays. These special data types are indicated by inserting the symbol 0 (null-terminated) or # (byte counted) between the direction indicator (<, >, =) and the type (T or C) specification. For example, a pointer to a null-terminated input character string is coded as <0T[], and an output one coded as >0T[].

Note that while appending the array specifier ‘[]’ is formally correct, because the presence of the special qualifier (0 or #) implies an array, the ‘[]’ may be omitted: <0T, >0T, =#C, etc.

Note also that the 0 and # specifiers may be used with data of all types and widths. For example, in the Classic Edition <0U2 may be useful for dealing with Unicode.

Type

The data type of the argument is represented by one of the symbols:

I | Integer | The value is interpreted as a 2’s complement signed integer.
U | Unsigned integer | The value is interpreted as an unsigned integer.
C
 Character The value is interpreted as a character

In the Unicode Edition, the value maps directly onto a Unicode code point.

In the Classic Edition, the value is interpreted as an index into ⎕AV. This means that ⎕AV positions map onto corresponding ANSI positions.

For example, with ⎕IO=0,
⎕AV[35] = 's', maps to ANSI[35] = ’#’.

T
 Translated character The value is interpreted as a character.

In the Classic Edition, the value is translated using standard Dyalog ⎕AV to ANSI translation. This means that ⎕AV characters map onto corresponding ANSI characters.

For example, with ⎕IO=0:
⎕AV[35] = 's', maps to ANSI[115] = ’s’.

F
 Floating point number The value is interpreted as an IEEE floating point number.
A | APL array | A pointer to the whole array (including header information) is passed. This type is used to communicate with DLL functions which have been written specifically to work with Dyalog APL. See the User Guide section on Writing Auxiliary Processors. Note that type A is always passed as a pointer, so is of the form <A, =A or >A.

Width

The type specifier may be followed by the width of the value in bytes. For example:

I4 | 4-byte signed integer.
U2 | 2-byte unsigned integer.
F8 | 8-byte floating point number.
F4 | 4-byte floating point number.

Type | Possible values for | Default value for Width
I | 1, 2, 4, 8 | 4 for 32-bit DLLs 8 for 65-bit DLLs
U | 1, 2, 4, 8 | 4 for 32-bit DLLs 8 for 64-bit DLLs
C | 1, 2, 4 | 1
T | 1, 2, 4 | wide characters (see below)
F | 4, 8 | 8
A | Not applicable. |

In the Unicode Edition, the default width is the width of a wide character according to the convention of the host operating system. This translates to T2 under Windows and T4 under Unix or Linux.

Examples

I2 | 16-bit integer
<I4 | Pointer to input 4-byte integer
U | Default width unsigned integer.
=F4 | Pointer to input/output 4-byte floating point number.

Arrays

Arrays are specified by following the basic data type with [n] or [], where n indicates the number of elements in the array. In the C declaration, the number of elements in an array may be specified explicitly at compile time, or determined dynamically at runtime. In the latter case, the size of the array is often passed along with the array, in a separate argument. In this case, n, the number of elements is omitted from the specification. Note that C deals only in scalars and rank 1 (vector) arrays.

int vec[10];             // explicit vector length.
unsigned size, list[];   // undetermined length.

would be coded as:

I[10]vector of 10 ints.
U U[]unsigned integer followed by an array of unsigned integers.

Confusion sometimes arises over a difference in the declaration syntax between C and ⎕NA. In C, an argument declaration may be given to receive a pointer to either a single scalar item, or to the first element of an array. This is because in C, the address of an array is deemed to be the address of its first element.

void foo (char *string);

char ch = ‘a’, ptr = “abc”;

foo(&ch);         // call with address of scalar.
foo(ptr);         // call with address of array.

However, from APL’s point of view, these two cases are distinct and if the function is to be called with the address of (pointer to) a scalar, it must be declared: '<T'. Otherwise, to be called with the address of an array, it must be declared: '<T[]'. Note that it is perfectly acceptable in such circumstances to define more than one name association to the same DLL function specifying different argument types:

      'FooScalar'⎕NA'mydll|foo <T'   ⋄ FooScalar'a'
      'FooVector'⎕NA'mydll|foo <T[]' ⋄ FooVector'abc'

Structures

Arbitrary data structures, which are akin to nested arrays, are specified using the symbols {}. For example, the code {F8 I2} indicates a structure comprised of an 8-byte float followed by a 2-byte int. Furthermore, the code <{F8 I2}[3] means an input pointer to an array of 3 such structures.

For example, this structure might be defined in C thus:

typedef struct
{
      double  f;
      short   i;
     } mystruct;

A function defined to receive a count followed by an input pointer to an array of such structures:

void foo(unsigned count, mystruct *str);

An appropriate ⎕NA declaration would be:

      ⎕NA'mydll.foo U <{F8 I2}[]'

A call on the function with two arguments - a count followed by a vector of structures:

      foo 4,⊂(1.4 3)(5.9 1)(6.5 2)(0 0)

Notice that for the above call, APL converts the two Boolean (0 0) elements to an 8-byte float and a 2-byte int, respectively.

Specifying Pointers Explicitly

⎕NA syntax enables APL to pass arguments to DLL functions by value or address as appropriate. For example if a function requires an integer followed by a pointer to an integer:

void fun(int valu, int *addr);

You might declare and call it:

      ⎕NA'mydll|fun I <I' ⋄ fun 42 42

The interpreter passes the value of the first argument and the address of the second one.

Two common cases occur where it is necessary to pass a pointer explicitly. The first is if the DLL function requires a null pointer, and the second is where you want to pass on a pointer which itself is a result from a DLL function.

In both cases, the pointer argument should be coded as I4. This causes APL to pass the pointer unchanged, by value, to the DLL function.

In the previous example, to pass a null pointer, (or one returned from another DLL function), you must code a separate ⎕NA definition.

      'fun_null'⎕NA'mydll|fun I I4' ⋄ fun_null 42 0

Now APL passes the value of the second argument (in this case 0 - the null pointer), rather than its address.

Using a Function

A DLL function may or may not return a result, and may take zero or more arguments. This syntax is reflected in the coding of the right argument of ⎕NA. Notice that the corresponding associated APL function is niladic or monadic (never dyadic), and that it always returns a vector result - a null one if there is no output from the function. See Result Vector section below. Examples of the various combinations are:

DLL function Non-result-returning:

      ⎕NA    'mydll|fn1'          ⍝ Niladic.
      ⎕NA    'mydll|fn2 <0T'      ⍝ Monadic - 1-element argument.
      ⎕NA    'mydll|fn3 =0T <0T'  ⍝ Monadic - 2-element argument.

DLL function Result-returning:

      ⎕NA 'I4 mydll|fn4'          ⍝ Niladic.
      ⎕NA 'I4 mydll|fn5 F8'       ⍝ Monadic - 1-element argument.
      ⎕NA 'I4 mydll|fn6 >I4 <0T'  ⍝ Monadic - 2-element argument.

When the external function is called, the number of elements in the argument must match the number defined in the ⎕NA definition. Using the example functions defined above:

      fn1                   ⍝ Niladic function.
      fn2 ⊂'Single String'  ⍝ 1-element argument.
      fn3 'This' 'That'     ⍝ 2-element argument.

Note in the second example, that you must enclose the argument string to produce a single item (nested) array in order to match the declaration. Dyalog converts the type of a numeric argument if necessary, so for example in fn5 defined above, a Boolean value would be converted to double floating point (F8) prior to being passed to the DLL function.

Pointer Arguments

When passing pointer arguments there are three cases to consider.

< Input pointer: In this case you must supply the data array itself as argument to the function. A pointer to its first element is then passed to the DLL function.

      fn2 'hello'

> Output pointer: Here, you must supply the number of elements that the output will need in order for APL to allocate memory to accommodate the resulting array.

      fn6 10 'world'  ⍝ 1st arg needs space for 10 ints.

Note that if you were to reserve fewer elements than the DLL function actually used, the DLL function would write beyond the end of the reserved array and may cause the interpreter to crash with a System Error.

= Input/Output: As with the input-only case, a pointer to the first element of the argument is passed to the DLL function. The DLL function then overwrites some or all of the elements of the array, and the new value is passed back as part of the result of the call. As with the output pointer case, if the input array were too short, so that the DLL wrote beyond the end of the array, the interpreter would almost certainly crash.

      fn3 '.....' 'hello'

Result Vector

In APL, a function cannot overwrite its arguments. This means that any output from a DLL function must be returned as part of the explicit result, and this includes output via ‘output’ or ‘input/output’ pointer arguments.

The general form of the result from calling a DLL function is a nested vector. The first item of the result is the defined explicit result of the external function, and subsequent items are implicit results from output, or input/output pointer arguments.

The length of the result vector is therefore: 1 (if the function was declared to return an explicit result) + the number of output or input/output arguments.

⎕NA Declaration | Result | Output Arguments | Result Length
mydll|fn1 | 0 |  | 0
mydll|fn2 <0T | 0 | 0 | 0
mydll|fn3 =0T <0T | 0 | 1 0 | 1
I4 mydll|fn4 | 1 |  | 1
I4 mydll|fn5 F8 | 1 | 0 | 1
I4 mydll|fn6 >I4 <0T | 1 | 1 0 | 2

As a convenience, if the result would otherwise be a 1-item vector, it is disclosed. Using the third example above:

      ⍴fn3 '.....' 'abc'
5

fn3 has no explicit result; its first argument is input/output pointer; and its second argument is input pointer. Therefore as the length of the result would be 1, it has been disclosed.

ANSI/Unicode Versions of Library Calls

Under Windows, most library functions that take character arguments, or return character results have two forms: one Unicode (Wide) and one ANSI. For example, a function such as MessageBox(), has two forms MessageBoxA() and MessageBoxW(). The A stands for ANSI (1-byte) characters, and the W for wide (2-byte Unicode) characters.

It is essential that you associate the form of the library function that is appropriate for the Dyalog Edition you are using, i.e. MessageBoxA() for the Classic Edition, but MessageBoxW() for the Unicode Edition.

To simplify writing portable code for both Editions, you may specify the character * instead of A or W at the end of a function name. This will be replaced by A in the Classic Edition and W in the Unicode Edition.

The default name of the associated function (if no left argument is given to ⎕NA), will be without the trailing letter (MessageBox).

Type Definitions (typedefs)

The C language encourages the assignment of defined names to primitive and complex data types using its #define and typedef mechanisms. Using such abstractions enables the C programmer to write code that will be portable across many operating systems and hardware platforms.

Windows software uses many such names and Microsoft documentation will normally refer to the type of function arguments using defined names such as HANDLE or LPSTR rather than their equivalent C primitive types: int or char*.

It is beyond the scope of this manual to list all the Microsoft definitions and their C primitive equivalents, and indeed, DLLs from sources other than Microsoft may well employ their own distinct naming conventions.

In general, you should consult the documentation that accompanies the DLL in order to convert typedefs to primitive C types and thence to ⎕NA declarations. The documentation may well refer you to the ‘include’ files which are part of the Software Development Kit, and in which the types are defined.

The following table of some commonly encountered Windows typedefs and their ⎕NA equivalents might prove useful.

Windows typedef | ⎕NA equivalent
HWND | I
HANDLE | I
GLOBALHANDLE | I
LOCALHANDLE | I
DWORD | U4
WORD | U2
BYTE | U1
LPSTR | =0T[] (note 1)
LPCSTR | <0T[] (note 2)
WPARAM | U
LPARAM | U4
LRESULT | I4
BOOL | I
UINT | U
ULONG | U4
ATOM | U2
HDC | I
HBITMAP | I
HBRUSH | I
HFONT | I
HICON | I
HMENU | I
HPALETTE | I
HMETAFILE | I
HMODULE | I
HINSTANCE | I
COLORREF | {U1[4]}
POINT | {I I}
POINTS | {I2 I2}
RECT | {I I I I}
CHAR | T or C

Notes

  1. LPSTR is a pointer to a null-terminated string. The definition does not indicate whether this is input or output, so the safest coding would be =0T[] (providing the vector you supply for input is long enough to accommodate the result). You may be able to improve simplicity or performance if the documentation indicates that the pointer is ‘input only’ (<0T[]) or ‘output only’ (>0T[]). See Direction above.
  2. LPCSTR is a pointer to a constant null-terminated string and therefore coding <0T[] is safe.
  3. Note that the use of type T with default width ensures portability of code between Classic and Unicode Editions. In the Classic Edition, T (with no width specifier) implies 1-byte characters which are translated between ⎕AV and ASCII, while In the Unicode Edition, T (with no width specifier) implies 2-byte (Unicode) characters.

Dyalog32.dll

Included with Dyalog APL is a utility DLL which is called dyalog32.dll.

The DLL contains two functions: MEMCPY and STRNCPY.

MEMCPY

MEMCPY is an extremely versatile function used for moving arbitrary data between memory buffers. Its C definition is:

void MEMCPY(            // copy memory
void *to,        // target address
void *fm,        // source address
unsigned size    // number of bytes to copy
);

MEMCPY copies size bytes starting from source address fm, to destination address to. If the source and destination areas overlap, the result is undefined.

MEMCPY’s versatility stems from being able to associate to it using many different type declarations.

Example

Suppose a global buffer (at address: addr) contains (numb) double floating point numbers. To copy these to an APL array, we could define the association:

      'doubles' ⎕NA 'dyalog32|MEMCPY >F8[] I4 U4'
      doubles numb addr (numb×8)

Notice that:

  • As the first argument to doubles is an output argument, we must supply the number of elements to reserve for the output data.
  • MEMCPY is defined to take the number of bytes to copy, so we must multiply the number of elements by the element size in bytes.

Example

Suppose that a database application requires that we construct a record in global memory prior to writing it to file. The record structure might look like this:

typedef struct {
int empno;                 // employee number.
float salary;              // salary.
char name[20];             // name.
} person;

Then, having previously allocated memory (addr) to receive the record, we can define:

      'prec' ⎕NA 'dyalog32|MEMCPY I4 <{I4 F4 T[20]} U4'
      prec addr(99 12345.60 'Charlie Brown       ')(4+4+20)

STRNCPY

STRNCPY is used to copy null-terminated strings between memory buffers.

Its C definition is:

void STRNCPY(     // copy null-terminated string
char *to,         // target address
char *fm,         // source address
unsigned size     // MAX number of chars to copy
);

STRNCPY copies a maximum of size characters from the null-terminated source string at address fm, to the destination address to. If the source and destination strings overlap, the result is undefined.

If the source string is shorter than size, null characters are appended to the destination string.

If the source string (including its terminating null) is longer than size, only size characters are copied and the resulting destination string is not null-terminated

Example

Suppose that a database application returns a pointer (addr) to a structure that contains two pointers to (max 20-char) null-terminated strings.

typedef struct {  // null-terminated strings:
    char *first;  // first name (max 19 chars + 1 null).
    char *last;  // last name. (max 19 chars + 1 null).
} name;

To copy the names from the structure:

      'get'⎕NA'dyalog32|STRNCPY >0T[] I4 U4'
      get 20 addr 20
Charlie
      get 20 (addr+4) 20
Brown

To copy data from the workspace into an already allocated (new) structure:

      'put'⎕NA'dyalog32|STRNCPY I4 <0T[] U4'
      put new 'Bo' 20
      put (new+4) 'Peep' 20

Notice in this example that you must ensure that names no longer than 19 characters are passed to put. More than 19 characters would not leave STRNCPY enough space to include the trailing null, which would probably cause the application to fail.

Examples

The following examples all use functions from the Microsoft Windows ‘USER’. DLL.

This DLL should be located in a standard Windows directory, so you should not normally need to give the full path name of the library. However if trying these examples results in the error message FILE ERROR 1 No such file or directory, you must locate the DLL and supply the full path name (and possibly extension).

Example 1

The Windows function "GetCaretBlinkTime" retrieves the caret blink rate. It takes no arguments and returns an unsigned int and is declared as follows:

UINT GetCaretBlinkTime(void);

The following statements would provide access to this routine through an APL function of the same name. Assuming you are using Windows 95/98.

      ⎕NA 'U User32|GetCaretBlinkTime'
      GetCaretBlinkTime
530

The following statement would achieve the same thing, but using an APL function called BLINK.

      'BLINK' ⎕NA 'U User32|GetCaretBlinkTime'
      BLINK
530

Example 2

The Windows function "SetCaretBlinkTime" sets the caret blink rate. It takes a single unsigned int argument, does not return a result and is declared as follows:

void SetCaretBlinkTime(UINT);

The following statements would provide access to this routine through an APL function of the same name :

      ⎕NA 'User32|SetCaretBlinkTime U'
      SetCaretBlinkTime 1000

Example 3

The Windows function "MessageBox" displays a standard dialog box on the screen and awaits a response from the user. It takes 4 arguments. The first is the window handle for the window that owns the message box. This is declared as an unsigned int. The second and third arguments are both pointers to null-terminated strings containing the message to be displayed in the Message Box and the caption to be used in the window title bar. The 4th argument is an unsigned int that specifies the Message Box type. The result is an int which indicates which of the buttons in the message box the user has pressed. The function is declared as follows:

int MessageBox(HWND, LPCSTR, LPCSTR, UINT);

The following statements provide access to this routine through an APL function of the same name. Note that the 2nd and 3rd arguments are both coded as input pointers to type T null-terminated character arrays which ensures portability between Editions.

      ⎕NA 'I User32|MessageBox* U <0T <0T U'

The following statement displays a Message Box with a stop sign icon together with 2 push buttons labelled OK and Cancel (this is specified by the value 19).

      MessageBox 0 'Message' 'Title' 19

The function works equally well in the Unicode Edition because the <0T specification is portable.

      MessageBox 0 'Το Μήνυμα' 'Ο Τίτλος' 19

Note that a simpler, portable (and safer) method for displaying a Message Box is to use Dyalog APL’s primitive MsgBox object.

Example 4

The Windows function "FindWindow" obtains the window handle of a window which has a given character string in its title bar. The function takes two arguments. The first is a pointer to a null-terminated character string that specifies the window's class name. However, if you are not interested in the class name, this argument should be a NULL pointer. The second is a pointer to a character string that specifies the title that identifies the window in question. This is an example of a case described above where two instances of the function must be defined to cater for the two different types of argument. However, in practice this function is most often used without specifying the class name. The function is declared as follows:

HWND FindWindow(LPCSTR, LPCSTR);

The following statement associates the APL function FW with the second variant of the FindWindow call, where the class name is specified as a NULL pointer. To indicate that APL is to pass the value of the NULL pointer, rather than its address, we need to code this argument as I4.

      'FW' ⎕NA 'U User32|FindWindow* I4 <0T'

To obtain the handle of the window entitled "CLEAR WS - Dyalog APL/W":

      ⎕←HNDL←FW 0 'CLEAR WS - Dyalog APL/W'
59245156

Example 5

The Windows function "GetWindowText" retrieves the caption displayed in a window's title bar. It takes 3 arguments. The first is an unsigned int containing the window handle. The second is a pointer to a buffer to receive the caption as a null-terminated character string. This is an example of an output array. The third argument is an int which specifies the maximum number of characters to be copied into the output buffer. The function returns an int containing the actual number of characters copied into the buffer and is declared as follows:

int GetWindowText(HWND, LPSTR, int);

The following associates the "GetWindowText" DLL function with an APL function of the same name. Note that the second argument is coded as ">0T" indicating that it is a pointer to a character output array.

      ⎕NA 'I User32|GetWindowText* U >0T I'

Now change the Session caption using )WSID :

      )WSID MYWS
was CLEAR WS

Then retrieve the new caption (max length 255) using window handle HNDL from the previous example:

      DISPLAY GetWindowText HNDL 255 255
.→-------------------------.
|    .→------------------. |
| 19 |MYWS - Dyalog APL/W| |
|    '-------------------' |
'∊-------------------------'

There are three points to note. Firstly, the number 255 is supplied as the second argument. This instructs APL to allocate a buffer large enough for a 255-element character vector into which the DLL routine will write. Secondly, the result of the APL function is a nested vector of 2 elements. The first element is the result of the DLL function. The second element is the output character array. Finally, notice that although we reserved space for 255 elements, the result reflects the length of the actual text (19).

An alternative way of coding and using this function is to treat the second argument as an input/output array.

e.g.

      ⎕NA 'I User32|GetWindowText* U =0T I'

      DISPLAY GetWindowTextA HNDL (255⍴' ') 255
.→-------------------------.
|    .→------------------. |
| 19 |MYWS - Dyalog APL/W| |
|    '-------------------' |
'∊-------------------------'

In this case, the second argument is coded as =0T, so when the function is called an array of the appropriate size must be supplied. This method uses more space in the workspace, although for small arrays (as in this case) the real impact of doing so is negligible.

Example 6

The function "GetCharWidth" returns the width of each character in a given range Its first argument is a device context (handle). Its second and third arguments specify font positions (start and end). The third argument is the resulting integer vector that contains the character widths (this is an example of an output array). The function returns a Boolean value to indicate success or failure. The function is defined as follows. Note that this function is provided in the library: GDI32.DLL.

BOOL GetCharWidth(HDC, UINT, UINT, int FAR*);

The following statements provide access to this routine through an APL function of the same name :

      ⎕NA 'U4 GDI32|GetCharWidth* I U U >I[]'

     'P'⎕WC'Printer'

      DISPLAY GetCharWidth ('P' ⎕WG 'Handle') 65 67 3
.→-------------.
|   .→-------. |
| 1 |50 50 50| |
|   '~-------' |
'∊-------------'

Note: 'P'⎕WG'Handle' returns a 32-bit handle which,. if the ‘top bit’ is set, will appear in APL as a negative integer. Attempting to supply such a negative number as an argument to a DLL function when the argument is declared ‘unsigned’ will result in a DOMAIN ERROR. Window handles should therefore be declared as I rather than U.

Example 7

The following example from the supplied workspace: QUADNA.DWS illustrates several techniques which are important in advanced ⎕NA programming. Function DllVersion returns the major and minor version number for a given DLL.

In advanced DLL programming, it is often necessary to administer memory outside APL’s workspace. In general, the procedure for such use is:

  1. Allocate global memory.
  2. Lock the memory.
  3. Copy any DLL input information from workspace into memory.
  4. Call the DLL function.
  5. Copy any DLL output information from memory to workspace.
  6. Unlock the memory.
  7. Free the memory.

Notice that steps 1 and 7, and steps 2 and 6 complement each other. That is, if you allocate global system memory, you must free it after you have finished using it. If you continue to use global memory without freeing it, your system will gradually run out of resources. Similarly, if you lock memory (which you must do before using it), then you should unlock it before freeing it. Although on some versions of Windows, freeing the memory will include unlocking it, in the interests of good style, maintaining the symmetry is probably a good thing.

    ∇ version←DllVersion file;Alloc;Free;Lock;Unlock;Size
                  ;Info;Value;Copy;size;hndl;addr;buff;ok
[1]
[2]   'Alloc'⎕NA'U4 kernel32|GlobalAlloc U4 U4'
[3]   'Free'⎕NA'U4 kernel32|GlobalFree U4'
[4]   'Lock'⎕NA'U4 kernel32|GlobalLock U4'
[5]   'Unlock'⎕NA'U4 kernel32|GlobalUnlock U4'
[6]
[7]   'Size'⎕NA'U4 version|GetFileVersionInfoSize* <0T >U4'
[8]   'Info'⎕NA'U4 version|GetFileVersionInfo* <0T U4 U4 U4'
[9]   'Value'⎕NA'U4 version|VerQueryValue* U4 <0T >U4 >U4'
[10]
[11]  'Copy'⎕NA'dyalog32|MEMCPY >U4[] U4 U4'
[12]
[13]  :If ×size←⊃Size file 0                ⍝ Size of info
[14]  :AndIf ×hndl←Alloc 0 size             ⍝ Alloc memory
[15]    :If ×addr←Lock hndl                 ⍝ Lock memory
[16]      :If ×Info file 0 size addr        ⍝ Version info
[17]        ok buff size←Value addr'\' 0 0  ⍝ Version value
[18]        :If ok
[19]          buff←Copy(size÷4)buff size    ⍝ Copy info
[20]          version←(2/2*16)⊤⊃2↓buff      ⍝ Split version
[21]        :EndIf
[22]      :EndIf
[23]      ok←Unlock hndl                    ⍝ Unlock memory
[24]    :EndIf
[25]    ok←Free hndl                        ⍝ Free memory
[26]  :EndIf
    ∇

Lines [2-11] associate APL function names with the DLL functions that will be used.

Lines [2-5] associate functions to administer global memory.

Lines [7-9] associate functions to extract version information from a DLL.

Line[11] associates Copy with MEMCPY function from dyalog32.dll.

Lines [13-26] call the DLL functions.

Line [13] requests the size of buffer required to receive version information for the DLL. A size of 0 will be returned if the DLL does not contain version information.

Notice that care is taken to balance memory allocation and release:

On line [14], the :If clause is taken only if the global memory allocation is successful, in which case (and only then) a corresponding Free is called on line [25].

Unlock on line[23] is called if and only if the call to Lock on line [15] succeeds.

A result is returned from the function only if all the calls are successful Otherwise, the calling environment will sustain a VALUE ERROR.

More Examples

⎕NA'U4 ADVAPI32 |RegCloseKey       U4'
⎕NA'I  ADVAPI32 |RegCreateKeyEx*   U <0T I <0T I I I >U >U'
⎕NA'U  ADVAPI32 |RegEnumValue*     U U >0T =U U >U >0T =U'
⎕NA'I  ADVAPI32 |RegOpenKey*       U <0T >U'
⎕NA'U4 ADVAPI32 |RegOpenKeyEx*     U4 <0T U4 U4 =U4'
⎕NA'I  ADVAPI32 |RegQueryValueEx*  U <0T U4 >U4 >0T =I4'
⎕NA'I4 ADVAPI32 |RegSetValueEx*    U <0T U4 U4 <0T U4'
⎕NA'I  DOS_U32  |Copy              <0T <0T'
⎕NA'U  DOS_U32  |Dir               <0T U >0T'
⎕NA'U  DOS_U32  |DirMore           U >0T'
⎕NA'   DOS_U32  |DirClose'
⎕NA'I  DOS_U32  |Rename            <0T <0T'
⎕NA'I  DOS_U32  |Erase             <0T'
⎕NA'   dyalog32 |STRNCPY           >0T I4 U4'
⎕NA'   dyalog32 |MEMCPY            >{U1[4]}[16] I4 U4'
⎕NA'I  gdi32    |AddFontResource*  <0T'
⎕NA'   GDI32    |BitBlt            U U U U U U U U U'
⎕NA'U4 gdi32    |GetPixel          U4 U4 U4'
⎕NA'U4 GDI32    |GetStockObject    U4'
⎕NA'I  gdi32    |RemoveFontResource* <0T'
⎕NA'U4 gdi32    |SetPixel          U4 U4 U4 U4'
⎕NA'U4 GLU32    |gluPerspective    F8 F8 F8 F8'
⎕NA'I  kernel32 |_lclose           U'
⎕NA'I  kernel32 |_lcreat           <0T I'
⎕NA'U4 kernel32 |_llseek           I U4 I'
⎕NA'I  kernel32 |_lopen            <0T I'
⎕NA'U  kernel32 |_lread            U >U1[] U'
⎕NA'U  kernel32 |_lwrite           U <U1[] U'
⎕NA'I  kernel32 |CopyFileA         <0T <0T I'
⎕NA'I4 kernel32 |GetEnvironmentStrings'
⎕NA'I4 kernel32 |GetLastError'
⎕NA'I  kernel32 |GetPrivateProfileInt* <0T <0T I <0T'
⎕NA'I  kernel32 |GetProfileString* <0T <0T <0T >0T I'
⎕NA'U2 kernel32 |GetSystemDirectory* >0T U2'
⎕NA'I2 KERNEL32 |GetTempPath*      U4 >0T'
⎕NA'U  KERNEL32 |GetWindowsDirectory* >0T U'
⎕NA'U  kernel32 |GlobalAlloc       U U4'
⎕NA'U  kernel32 |GlobalFree        U'
⎕NA'   Kernel32 |GlobalMemoryStatus ={U4 U4 U4 U4 U4 U4 U4 U4}'
⎕NA'U  KERNEL32 |WritePrivateProfileString* <0T <0T <0T <0T'
⎕NA'U4 OpenGL32 |glClearColor      F4 F4 F4 F4'
⎕NA'U4 OpenGL32 |glClearDepth      F4'
⎕NA'U4 OpenGL32 |glEnable          U4'
⎕NA'U4 OpenGL32 |glMatrixMode      U4'
⎕NA'U4 USER32   |ClientToScreen    U =U4[2]'
⎕NA'I  user32   |FindWindow*       I4 <0T'
⎕NA'   user32   |ShowWindow        I I'
⎕NA'I2 USER32   |GetAsyncKeyState  I'
⎕NA'U4 user32   |GetDC             U4'
⎕NA'I4 User32   |GetDialogBaseUnits'
⎕NA'I  user32   |GetFocus'
⎕NA'U4 user32   |GetSysColor       I'
⎕NA'I  user32   |GetSystemMetrics  I'
⎕NA'   USER32   |InvalidateRgn     I4 U4 U4'
⎕NA'I  user32   |MessageBox*       I <0T <0T I'
⎕NA'U4 user32   |ReleaseDC         U4 U4'
⎕NA'U4 USER32   |SendMessage*      I4 U4 U4 <I[]'
⎕NA'I2 user32   |SetFocus          I'
⎕NA'I  user32   |WinHelpA          I <0T I I4'
⎕NA'U  WINMM    |sndPlaySound*     <0T U'


Native File Append

{R}←X ⎕NAPPEND Y

Appends the ravel of its left argument X to the end of designated native file. X must be a simple homogeneous APL array.

Y is a 1- or 2-element integer vector. Y[1] is a negative integer that specifies the tie number of a native file. The optional second element Y[2] specifies the data type to which the array X is to be converted before it is written to the file.

The shy file index result returned is the position within the file of the end of the record, which is also the start of the following one.

Unicode Edition

Unless you specify the data type in Y[2], a character array will by default be written using type 80.

If the data will not fit into the specified character width (bytes) ⎕NAPPEND will fail with a DOMAIN ERROR.

As a consequence of these two rules, you must specify the data type (either 160 or 320) in order to write Unicode characters whose code-point are in the range 256-65535 and >65535 respectively.

Example

      n←'test'⎕NCREATE 0

      'abc' ⎕nappend n

      'ταβέρνα'⎕nappend n
DOMAIN ERROR
      'ταβέρνα'⎕NAPPEND n
     ∧

      'ταβέρνα'⎕NAPPEND n 160

      ⎕NREAD n 80 3 0
abc
      ⎕NREAD n 160 7
ταβέρνα

For compatibility with old files, you may specify that the data be converted to type 82 on output. The conversion (to ⎕AV indices) will be determined by the local value of ⎕AVU.


Native File Read

R←⎕NREAD Y

Reads data from a native file. Y is a 3- or 4-element integer vector whose elements are as follows:

[1] | Negative tie number
[2] | Conversion code (see below)
[3] | Number of elements (not bytes) to be read
[4] | Start byte, counting from 0

Y[2] specifies conversion to an APL internal form as follows:

Unicode Edition
Value | Number of bytes read | Result Type | Result Shape
11 | count | 1 bit Boolean | 8 x count
80 | count | 8 bits Character | count
82 | count | 8 bits Character | count
83 | count | 8 bits Integer | count
160 | 2 x count | 16 bits Character | count
163 | 2 x count | 16 bits Integer | count
320 | 4 x count | 32 bits Character | count
323 | 4 x count | 32 bits Integer | count
645 | 8 x count | 64 bits Floating | count

Classic Edition
Value | Number of bytes read | Result Type | Result Shape
11 | count | 1 bit Boolean | 8 x count
82 | count | 8 bits Character | count
83 | count | 8 bits Integer | count
163 | 2 x count | 16 bits Integer | count
323 | 4 x count | 32 bits Integer | count
645 | 8 x count | 64 bits Floating | count

Note that types 80, 160 and 320 and 83 and 163 are exclusive to Dyalog APL.

If Y[4] is omitted, data is read starting from the current position in the file (initially, 0).

Example

DATA←⎕NREAD ¯1 160 (⎕NSIZE ¯1) 0 ⍝ Unicode Edition
DATA←⎕NREAD ¯1  82 (⎕NSIZE ¯1) 0 ⍝ Classic Edition


Native File Replace

{R}←X ⎕NREPLACE Y

⎕NREPLACE is used to write data to a native file, replacing data which is already there.

X must be a simple homogeneous APL array containing the data to be written.

Y is a 2- or 3-element integer vector whose elements are as follows:

[1] | negative tie number,
[2] | start byte, counting from 0, at which the data is to be written,
[3] | conversion code (optional).

See ⎕NREAD for a list of valid conversion codes.

The shy result is the position within the file of the end of the record, or, equivalently, the start of the following one. Used, for example, in:

      {⍺ ⎕NREPLACE tie ⍵}/vec,indx       ⍝ Replace sequentially from indx.

Unicode Edition

Unless you specify the data type in Y[2], a character array will by default be written using type 80.

If the data will not fit into the specified character width (bytes) ⎕NREPLACE will fail with a DOMAIN ERROR.

As a consequence of these two rules, you must specify the data type (either 160 or 320) in order to write Unicode characters whose code-point are in the range 256-65535 and >65535 respectively.

Example

      n←'test'⎕NTIE 0 ⍝ See ⎕NAPPEND example

      ⎕NREAD n 80 3 0
abc
      ⎕NREAD n 160 7
ταβέρνα

      ⎕←'εστιατόριο'⎕NREPLACE n 3
DOMAIN ERROR
      ⎕←'εστιατόριο'⎕NREPLACE n 3
     ∧

      ⎕←'εστιατόριο'⎕NREPLACE n 3 160
23
      ⎕NREAD n 80 3 0
abc
      ⎕NREAD n 160 10
εστιατόριο

For compatibility with old files, you may specify that the data be converted to type 82 on output. The conversion (to ⎕AV indices) will be determined by the local value of ⎕AVU.


Native File Translate

{R}←{X}⎕NXLATE Y

This associates a character translation vector with a native file or, if Y is 0, with the use by ⎕DR.

A translate vector is a 256-element vector of integers from 0-255. Each element maps the corresponding ⎕AV position onto an ANSI character code.

For example, to map ⎕AV[17+⎕IO] onto ANSI 'a' (code 97), element 17 of the
translate vector is set to 97.

⎕NXLATE is a non-Unicode (Classic Editon) feature and is retained in the Unicode Edition, only for compatibility.

Y is either a negative integer tie number associated with a tied native file or 0. If Y is negative, monadic ⎕NXLATE returns the current translation vector associated with the corresponding native file. If specified, the left argument X is a 256-element vector of integers that specifies a new translate vector. In this case, the old translate vector is returned as a shy result. If Y is 0, it refers to the translate vector used by ⎕DR to convert to and from character data.

The system treats a translate vector with value (⍳256)-⎕IO as meaning no translation and thus provides raw input/output bypassing the whole translation process.

The default translation vector established at ⎕NTIE or ⎕NCREATE time, maps ⎕AV characters to their corresponding ANSI positions and is derived from the mapping defined in the current output translation table (normally WIN.DOT)

Between them, ANSI and RAW translations should cater for most uses.

Unicode Edition

⎕NXLATE is relevant in the Unicode Edition only to process Native Files that contain characters expressed as indices into ⎕AV, such as files written by the Classic Edition.

In the Unicode Edition, when reading data from a Native File using conversion code 82, incoming bytes are translated first to ⎕AV indices using the translation table specified by ⎕NXLATE, and then to type 80, 160 or 320 using ⎕AVU. When writing data to a Native File using conversion code 82, characters are converted using these two translation tables in reverse.


Terminal Control

 (⎕ML) R←⎕TC

⎕TC is a deprecated feature and is replaced by ⎕UCS (see note).

⎕TC is a simple three element vector. If ⎕ML < 3 this is ordered as follows:

⎕TC[1] | Backspace
⎕TC[2] | Linefeed
⎕TC[3] | Newline

If ⎕ML ≥ 3 the order of the elements of ⎕TC is instead compatible with IBM's APL2:

⎕TC[1] | Backspace
⎕TC[2] | Newline
⎕TC[3] | Linefeed

Elements of ⎕TC beyond 3 are not defined but are reserved.

Note

With the introduction of ⎕UCS in Version 12.0, the use of ⎕TC is discouraged and it is strongly recommended that you generate control characters using ⎕UCS instead. This recommendation holds true even if you continue to use the Classic Edition.

Control Character | Old | New
Backspace | ⎕TC[1] | ⎕UCS 8
Linefeed | ⎕TC[2] (⎕ML<3) ⎕TC[3] (⎕ML≥3) | ⎕UCS 10
Newline | ⎕TC[3] (⎕ML<3) ⎕TC[2] (⎕ML≥3) | ⎕UCS 13


Encoding Property

Applies to: TCPSocket

The Encoding property is a character vector that specifies how character data are encoded or translated. The possible values are 'None', 'UTF-8', 'Classic', or 'Unicode', depending upon the the value of the Style property.

Unicode Edition

Style | Encoding | Description
'Raw' | 'None' (default) | Not applicable. Only integer data may be transmitted/received.
'Char' | 'None' (default) | Transmission is limited to characters with Unicode code points in the range 0-255. Attempting to transmit (or receive) a character outside this range will cause DOMAIN ERROR.
 | 'UTF-8' | Characters are transmitted/received using the UTF-8 encoding scheme.
'APL' | 'Classic' (default) | Characters are transmitted/received as indices of ⎕AV, and translated according to the current value of ⎕AVU. An attempt to transmit or receive a characters not present in ⎕AVU will cause TRANSLATION ERROR
 | 'Unicode' | Characters are transmitted/received as is (as Unicode code points).

Classic Edition

Style | Encoding | Description
'Raw' | 'None' (default) | Not applicable. Only integer data may be transmitted/received.
'Char' | 'None' (default) | Characters (which are represented internally as indices of ⎕AV)are translated to and from ASCII using the Output Translate Table win.dot.
 | 'UTF-8' | Characters are converted to/from Unicode using ⎕AVU and transmitted/received using the UTF-8 encoding scheme. An attempt to transmit or receive a characters not present in ⎕AVU will cause TRANSLATION ERROR.
'Apl' | 'Classic' (default) | Characters are transmitted/received as indices of ⎕AV.
 | 'Unicode' | Characters are converted to/from Unicode using ⎕AVU and transmitted/received as Unicode code points. An attempt to transmit or receive a characters not present in ⎕AVU will cause TRANSLATION ERROR.

The default value of Encoding depends upon the value of Style as indicated in the above tables.

An attempt to set the value of Encoding to a value not valid for the current Style, as implied by the above tables, will cause DOMAIN ERROR.

If you change the value of the Style property, the value of Encoding will remain unchanged if it is valid for the new Style. Otherwise it will revert to the default value for the new value of Style.

      's0'⎕WC'TCPSocket' ('LocalPort' 2001)
      s0.(Style Encoding)
Char  None

      s0.Style←'APL'
      s0.(Style Encoding)
Apl  Classic

Note that the 'Classic' encoding is intended for use in communicating with the Classic Edition, and with programs designed to communicate with Version 11.0 or earlier. This is why it is the default for now. However, it is however intended that the default will change to 'Unicode' in due course.


KeyError Event

KeyError Event 23

Applies to: Edit Spinner

Description

If enabled, this event is generated when the user presses and releases a key on the keyboard that is invalid for the FieldType of the object and has been ignored. This event is reported for information only and you may not disable it or modify it in any way.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'KeyError' or 23
[3] | Character | character scalar
[4] | Character code | integer scalar
[5] | Key Number | integer scalar
[6] | Shift state | integer scalar

In the Classic Edition, the resolution of the keystroke to a character (in ⎕AV) is performed using the Input Translate Table. In the Unicode Edition, the resolution is performed by the Operating System.

In the Unicode Edition, the Character Code is the Unicode code point of the character that the user entered. In the Classic Edition, it is a number in the range 0-255 which specifies the ASCII character that would normally be generated by the keystroke, and is independent of the Input Translate Table. If there is no corresponding ASCII character, the ASCII code reported is 0.

The key number is the physical key number reported by Windows when the key is pressed.

The Shift State indicates which (if any) of the Shift, Ctrl and Alt keys are down at the same time as the key is pressed. It is the sum of the following numbers :

Shift Key down | 1
Ctrl Key down | 2
Alt key down | 4

Thus a Shift State of 3 indicates that the user has pressed the key in conjunction with both the Shift and Ctrl keys. A Shift State of 0 indicates that the user pressed the key on its own.


KeyPress Event

KeyPress Event 22

Applies to: Button Calendar Combo Edit Form Grid List MDIClient RichEdit Scroll Spinner SubForm TabControl TrackBar TreeView

Description

If enabled, this event is generated when the user presses and releases a key on the keyboard. It is reported for whichever object has the keyboard focus at the time.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'KeyPress' or 22
[3] | Input Code | character scalar or vector
[4] | Character code | integer scalar
[5] | Key Number | integer scalar
[6] | Shift state | integer scalar

If the keystroke resolves to a character, the Input Code is a character scalar.

If the keystroke resolves to a command recognised by Dyalog APL, such as UC (Up Cursor) or ER (Enter) the Input Code contains the corresponding 2-element character vector.

In the Classic Edition, the resolution of the keystroke to a character (in ⎕AV) or to a command, is performed using the Input Translate Table.

In the Unicode Edition, the resolution is performed by the Operating System. However, if the keystroke resolves to a navigation or control key (such as Cursor Up or Enter), the same 2-character "command" is reported. Note however that commands that are purely internal to Dyalog APL (such as Trace, commonly Ctrl+Enter) are not reported as such and the Input Code will be empty.

In the Unicode Edition, the Character Code is the Unicode code point of the character that the user entered. In the Classic Edition, it is a number in the range 0-255 which specifies the ASCII character that would normally be generated by the keystroke, and is independent of the Input Translate Table. If there is no corresponding ASCII character, the ASCII code reported is 0.

The key number is the physical key number reported by Windows when the key is pressed.

The Shift State indicates which (if any) of the Shift, Ctrl and Alt keys are down at the same time as the key is pressed. It is the sum of the following numbers :

Shift Key down | 1
Ctrl Key down | 2
Alt key down | 4

Thus a Shift State of 3 indicates that the user has pressed the key in conjunction with both the Shift and Ctrl keys. A Shift State of 0 indicates that the user pressed the key on its own.

Example

     ∇ Key;Form1
[1]    'Form1'⎕WC'Form'('Event' 'KeyPress' 'Keycb')
[2]    ⎕DQ'Form1'
     ∇

     ∇ Keycb msg
[1]    DISPLAY msg
     ∇

On running function Key, the following output will be displayed as a result of the user pressing the following 5 keys in succession:

  1. "a"
  2. Shift+"a"
  3. Cursor Up
  4. β ("b" using a Greek keyboard)
  5. ⍳ (Ctrl+"i" using a UK APL keyboard)

Unicode Edition

.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| a 97 65 0 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| A 65 65 1 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-------------------------------.
| .→----. .→-------. .→-.        |
| |Form1| |KeyPress| |UC| 0 38 0 |
| '-----' '--------' '--'        |
'∊-------------------------------'

.→------------------------------.
| .→----. .→-------.            |
| |Form1| |KeyPress| β 946 66 0 |
| '-----' '--------'            |
'∊------------------------------'
.→-------------------------------.
| .→----. .→-------.             |
| |Form1| |KeyPress| ⍳ 9075 73 2 |
| '-----' '--------' -           |
'∊-------------------------------'

Classic Edition

.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| a 97 65 0 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-----------------------------.
| .→----. .→-------.           |
| |Form1| |KeyPress| A 65 65 1 |
| '-----' '--------' -         |
'∊-----------------------------'
.→-------------------------------.
| .→----. .→-------. .→-.        |
| |Form1| |KeyPress| |UC| 0 38 0 |
| '-----' '--------' '--'        |
'∊-------------------------------'
.→--------------------------------.
| .→----. .→-------. .⊖.          |
| |Form1| |KeyPress| | | 223 66 0 |
| '-----' '--------' '-'          |
'∊--------------------------------'
.→----------------------------.
| .→----. .→-------.          |
| |Form1| |KeyPress| ⍳ 9 73 2 |
| '-----' '--------' -        |
'∊----------------------------'


Interoperability

Workspaces and component files are stored on disk in a binary format (illegible to text editors). This format differs between machine architectures and among versions of Dyalog. For example a file component written by a PC will almost certainly have an internal format that is different from one written by a UNIX machine. Similarly, a workspace saved from Dyalog V11 will differ internally from one saved by a previous version of the interpreter.

It is convenient for versions of Dyalog running on different platforms to be able to “interoperate” by sharing workspaces and component files. However, this is not always possible. For example, if a new internal data structure is introduced in a particular version of Dyalog, previous versions could not be expected to make sense of it. In this case the load (or copy) from the older version would fail with the message:

this WS requires a later version of the interpreter.

Similarly, “large” (64-bit-addressing) component files are inaccessible to versions of the interpreter that pre-dated their introduction.

The second item in the right argument of ⎕FCREATE determines the addressing type of the file.

    'small'⎕fcreate 1 32    ⍝ create small file.
    'large'⎕fcreate 1 64    ⍝ create large file.

For the moment, if the second item is missing, the file type defaults to 32-bit-addressing (max 4GB file size), even on a 64-bit system for maximum inter-operability. We will change the default to 64-bit in version 11.1, by which time we believe the bulk of our users will be running versions which can use 64-bit files (version 10.1 or later)

Dyalog Version 11 adds to the interoperability problem by supplying versions for both 32-bit and 64-bit machine architectures.

Interoperability is summed up in the following tables. Table rows show the version that is attempting to access the file or workspace and columns show the version that saved it:

This version can access files created by this version →
↓

Version 10.1.5

Version 10.1.5 is an update to V10.1 issued specifically to enhance 10.1/11.0 compatibility. Version 10.1.5 is essentially version 10.1.2 with the addition of some Version 11.0 file system code. If Version 10.1 applications are moved to 10.1.5, they will be able to share files with code which has been moved to 64-bit Version 11.0. For example, this would allow a computational server to be moved to 64-bit Version 11.0 and provide data to an application which was still running Version 10.1.

The row and column titles show the Dyalog version 9.0, 10.0, etc; (32) and (64) indicate a version running on a 32-bit or 64-bit machine architecture, respectively.

Implementation

In general all writes are made in the format that is native to the writer. Readers do the work of any necessary translation. The exception is when writing from a 64 bit version to a 32 bit file. This has been allowed provided the machine architecture is the same. 32 bit files are the same architecture for the entire file. 64 bit files can have each component written differently.

Workspace interoperability – “can load/copy from …”

 | 9.0 | 10.0 | 10.1 | 10.1.5 | 11.0(32) | 11.0(64)
9.0 | Yes | - | - | - | - | -
10.0 | Yes | Yes | - | - | - | -
10.1 | Yes | Yes | Yes | Yes | - | -
10.1.5 | Yes | Yes | Yes | Yes | - | -
11.0(32) | Yes | Yes | Yes | Yes | Yes | Yes
11.0(64) | - | - | Yes | Yes | Yes | Yes

Component files small (32-bit addressing) and External variables– “can access …”

 | 9.0 | 10.0 | 10.1 | 10.1.5 | 11.0(32) | 11.0(64)
9.0 | Yes ~t | Yes ~f~n~t | Yes ~f~n~t | Yes ~f~n~t | Yes ~f~n~t | Yes ~f~n~t
10.0 | Yes ~t | Yes ~t | Yes ~t | Yes ~t | Yes ~n~t | Yes ~n~t
10.1 | Yes ~t | Yes ~t | Yes ~t | Yes ~t | Yes ~n~t | Yes ~n~t
10.1.5 | Yes ~w | Yes ~w | Yes ~w | Yes ~w | Yes ~n~w | Yes ~n~w
11.0(32) | Yes ~w | Yes ~w | Yes ~w | Yes ~w | Yes ~w | Yes ~w
11.0(64) | Yes ~w | Yes ~w | Yes ~w | Yes ~w | Yes ~w | Yes ~w

Notes
~f: Cannot read ⎕ORs of functions.
~n: Cannot read ⎕ORs of namespaces.
~t: Cannot tie files created on machines with different byte ordering (e.g. PC/UNIX).
~w: Can read from but cannot write to files created on machines with different byte ordering (attempting to write generates FILE ACCESS ERROR).

Component files large (64-bit addressing) – “can access …”

 | 9.0 | 10.0 | 10.1 | 10.1.5 | 11.0(32) | 11.0(64)
9.0 | - | - | - | - | - | -
10.0 | - | - | - | - | - | -
10.1 | - | - | Yes | Yes ~b | Yes ~n~b | -
10.1.5 | - | - | Yes | Yes | Yes ~n | Yes ~n
11.0(32) | - | - | Yes | Yes | Yes | Yes
11.0(64) | - | - | Yes | Yes | Yes | Yes

Notes
~b: Cannot read a component with the wrong byte-ordering.
~n: Cannot read ⎕ORs of namespaces.

Sockets (type 'APL') – “can decode from …”

 | 9.0 | 10.0 | 10.1 | 10.1.5 | 11.0(32) | 11.0(64)
9.0 | Yes | Yes ~fn | Yes ~f~n | Yes ~f~n | Yes ~f~n | -
10.0 | Yes | Yes | Yes | Yes | Yes ~n | -
10.1 | Yes | Yes | Yes | Yes | Yes ~n | -
10.1.5 | Yes | Yes | Yes | Yes | Yes ~n | -
11.0(32) | Yes | Yes | Yes | Yes | Yes | Yes
11.0(64) | Yes | Yes | Yes | Yes | Yes | Yes

Notes

~f: Cannot read ⎕ORs of functions.
~n: Cannot read ⎕ORs of namespaces.

Auxiliary Processes

A Dyalog process is restricted to starting an AP of exactly the same architecture. In other words, the AP must share the same word-width and byte-ordering as its interpreter process.

Session Files

Session (.dse) files may only be used on the platform on which they were created and saved.


Improved Workspace Management

From version 11.0, Dyalog can reduce its process size by returning unused memory to the operating system.

This happens when one of the following occurs:

      )CLEAR
      )LOAD
      )SAVE
      )RESET
      ⎕WA

Notice that ⎕WA could be called under program control to reduce the process size after returning from a memory-intensive section of an application.

For )LOAD and )CLEAR, the workspace is initialised with a small amount (1/16 of the configured Maximum workspace size) of working memory.

For )SAVE, )RESET and ⎕WA, the following sequence occurs.

  1. Any un-referenced memory is discarded. This process, known as garbage collection, is required because whole cycles of refs (refs.ref←1⌽refs) can become un-referenced.
  2. Numeric arrays are demoted to their tightest form. For example, a simple numeric array that happens to contain only values 0 or 1, is demoted or squeezed to have a ⎕DR type of 11 (Boolean).
  3. All remaining used memory blocks are copied to the low-address end of the workspace, leaving a single free block at the high-address end. This process is known as compaction.
  4. Workspace above a small amount (1/16 of the configured Maximum workspace size) of working memory is returned to the operating system. On a Windows system, you can see the process size changing by using Task Manager.
  5. However, if after compaction, the amount of used workspace is less than 1/16 of the Maximum workspace size (MAXWS), the amount reserved for working memory is reduced to 1/64th MAXWS. This means that workspaces that are operating within 1/16th of MAXWS will be more frugal with memory


Improved Number Conversion

Number Conversion

The conversion of numbers between internal form and display form has been significantly improved for Version 11.0.

Numbers (such as 3.14), input in the session or used as constants in source code, are converted to a binary (IEEE) format for storage in the workspace. If the internal number is subsequently displayed, the reverse conversion takes place as the number is formatted.

The conversion of numbers between internal form and display form has been significantly improved and in Version 11.0:

  1. When ⎕PP is set to its maximum value of 17, distinct numbers have distinct display forms.
  2. Such forms use the smallest number of digits possible.

A consequence of this is that if ⎕PP is set to its maximum value of 17, floating-point numbers may be converted between binary and character representation without loss of precision. In particular, if ⎕PP is 17 and ⎕CT is 0 (to ensure exact comparison), for any floating-point number N the expression N=⍎⍕N is true (except for denormal numbers).

Note that the converse of (a) is not necessarily true: distinct input forms may convert to the same internal binary number. This is clearly the case if we supply more digits than the 64-bit internal format is capable of representing. In particular, a decimal number such as ÷3 (or ÷10), which has an infinite binary representation must necessarily be represented internally, only approximately. This can lead to a slightly surprising (though correct) display, if ⎕PP is set to 17. For example, we might wonder why only 16 digits of accuracy are displayed in the following:

      ⎕PP←17
      ÷3  ⍝ why only 16 digits
0.3333333333333333

We see the reason if we display the internal format of ÷3 together with its display form and the display forms of its immediate IEEE neighbours:

0x3FD5555555555554 -> 0.33333333333333326
0x3FD5555555555555 -> 0.3333333333333333
0x3FD5555555555556 -> 0.33333333333333337

Rule (b) constrains us to format using the smallest number of digits that would convert back to internal number 0x3FD5555555555555 (which is just less than one third).

The Problem

To avoid any loss of precision, literal numbers in source code are displayed with maximum print precision, ⎕PP=17, by the function editor and ⎕CR.

Version 11 input conversion is very slightly more accurate than in previous versions. For example, in Version 10.1, a number input as 0.6 would have been converted to internal binary IEEE format as:

    0.6 -> 0x3FE3333333333334    // V10

where in V11, it is converted to the marginally more accurate:

    0.6 -> 0x3FE3333333333333    // V11

In V11, using ⎕PP=17, IEEE number 0x3FE3333333333333 displays (correctly) as 0.6, while its neighbour 0x3FE3333333333334 displays (correctly) as 0.6000000000000001.

This means that source code from versions prior to Version 11 may occasionally show strange-looking numbers such as 0.6000000000000001, when viewed in Version 11.

Note that this DOES NOT CHANGE the accuracy of any calculations: refixing the function with the longer (0.6000000000000001) number in Version 11 will continue to convert to the same internal number (0x3FE3333333333334) as before. However, changing the number in the source code to 0.6 would convert to a different number (0x3FE3333333333333), which might be very slightly closer to what you had in mind.


Change to )COPY

Version 11 makes a small change to the way that namespaces containing refs are copied using )COPY or ⎕CY.

We can show the change most easily by using a simple example.

Suppose a saved workspace contains two namespaces target and sibling, and target contains a ref to sibling, which contains variable var.

.target-----.  .--> .sibling----.
|           |  |    |           |
|   sibref--+--'    | var       |
|           |       |           |
'-----------'       '-----------'

Old behaviour

Prior to Version 11, target's outward-pointing ref would be inverted on copy.

    )copy myws target
.target----------.
|                |
|  .sibling---.  |
|  |          |  |
|  | var      |  |
|  |          |  |
|  '----------'  |
|                |
'----------------'

New behaviour

    )copy myws target
.target-----.  .--> .(sibling)--.
|           |  |    |           |
|   sibref--+--'    | var       |
|           |       |           |
'-----------'       '-----------'

In this case, the original parent/child relationships are preserved. Note however, that the name 'sibling' is not fixed in the space from which the copy occurred.

More generally, an incoming space, whose ancestry does not include the target of the copy (e.g. sibling in the above example), is fixed as an anonymous child of the current space.


Copying Dependant Objects

)COPY now issues a warning message when it copies dependant objects into the active workspace.

If you )COPY an object without including the names of any objects upon which it depends in the list of names to be copied, such as:

  • an Instance of a Class but not the Class itself
  • a Class but not a Class upon which it depends
  • an array or a namespace that contains a ref to another namespace, but not the namespace to which it refers

the dependant object(s) will also be copied but will be unnamed and hidden. In such as case, the system will issue a warning message.

For example, if a saved workspace named CFWS contains a Class named #.CompFile and an Instance (of CompFile) named icf,

      )COPY CFWS icf
.\CFWS saved Fri Mar 03 10:21:36 2006
copied object created an unnamed copy of class #.CompFile

The existence of a hidden copy can be confusing, especially if it is a hidden copy of an object which had a name which is in use in the current workspace. In the above example, if there is a class called CompFile in the workspace into which icf is copied, the copied instance may appear to be an instance of the visible CompFile, but it will actually be an instance of the hidden CompFile - which may have very different (or perhaps worse: very slightly different) characteristics to the named version.

If you copy a Class without copying its Base Class, the Class can be used (it will use the invisible copy of the Base Class), but if you edit the Class, you will either be unable to save it because the editor cannot find the Base Class, or - if there is a visible Class of that name in the workspace - it will be used as the Base Class. In the latter case, the invisible copy which was brought in by )COPY will now disappear, since there are no longer any references to it - and if these two Base Classes were different, the behaviour of the derived Class will change (and any changes made to the invisible Base Class since it was copied will be lost).


Deferred Prototype Generation

Unlike earlier versions of Dyalog APL, Version 11.0 does not generate a prototype when an empty array is created. The prototype is instead created when an operation on the empty array needs a prototype to generate a result.

This means that Version 11.0 allows the creation of an empty array from an array of namespace references. In previous Versions of Dyalog APL, this gives a NONCE ERROR

      a←0⍴#

The deferred requirement for prototypes is especially useful when making selections from lists of namespaces. For example, if CDDB is a vector of namespaces representing a CD database, an expression such as:

      CDDB←(CDDB.Artist∊⊂'Dylan')/CDDB

.. will always work in version 11.0, while it would have given a NONCE ERROR in earlier versions in the unlikely event that there had been no CD’s by Bob Dylan in the collection. However, the following expressions still gives a NONCE ERROR:

      1↑0⍴#
      (0/CDDB).Title

… because both expressions require inspection of a prototype in order to compute the result. So it may still be necessary to check the length of the result before using the selection.

Note that, if the CDDB was an array of instances of a Class, it would be possible to specify a prototypical CD entry and get the latter expression to return the “expected result” (0⍴⊂''). See Empty Arrays of Instances: How?


Matching Refs

In version 11.0, match (≡) and not match (≢) return 0 and 1 respectively if used to compare two refs which do not point to the same object.

Earlier Versions returned 1 and 0 respectively if the refs were identical, but NONCE ERROR if they were different.

Note: At some point in the future, it is likely that it will be possible for a class definition to contain definitions of comparison functions, and that the existence of such functions would replace pointer matching. This is already the case for instances of .NET Classes, for example:

      (⎕NEW System.DateTime (2006 8 28))≡⎕NEW System.DateTime (2006 8 28)
1

These two instances match, even though they are NOT the same object, because the DateTime class defines a comparison function for instances of this class. Therefore, it is NOT safe to write code which assumes that, if two refs match, they refer to the same object (unless you are the author of the classes being compared).


Name-Class Change on Assignment

Changing Name-Class on Assignment

Version 11 allows you to overwrite a ref (name class 9) with a variable (name class 2) and vice-versa.

For example, if we have:

      ref←⎕ns''     ⍝ class 9 namespace ref.

and

      var←3.14      ⍝ class 2 variable.

We can now do either:

      ref←var       ⍝ change class 9->2.

or

      var←ref       ⍝ change class 2->9.

In particular, if ref is a namespace reference, we can say:

      ref←,ref      ⍝ 1-item vector: class 9->2.

then

      ref←⊃ref      ⍝ scalar ref: class 2->9.

The full table of possible name reassignments is:

 | Ref | Variable | Function | Operator
Ref | Yes | Yes |  |
Variable | Yes | Yes |  |
Function |  |  | Yes | Yes
Operator |  |  | Yes | Yes


Properties that refer to GUI Objects

In the Dyalog GUI, a number of Properties are used to specify and/or report references between GUI objects. For example, the FontObj property of a Label object specifies the Font object used to display its text. In previous versions of Dyalog APL, such objects are referenced by name. In Version 11, all the Properties that are used to reference another object accept/report refs as well as names.

The list of such Properties includes the following:

BtnPix | CellFonts | ColSortImages | CursorObj
DockChildren | FontObj | Fstyle | HintObj
IconObj | ImageListObj | Input | MDIMenu
Picture | Popup | RowTreeImages | SplitObj1
SplitObj2 | TipObj | TabObj | ToolboxBitmap

Note that when you query the value of any of these Properties, APL will report whatever you specified (name or ref) when you set the Property. However, if you have not previously set the value, it will be reported as an empty character vector.

There are however some Properties, whose values are automatically updated by the system, for which this approach would not be appropriate. In these cases, an additional Property is provided with the same name followed by the suffix Object. For example, MDIActive continues to report the name of the active SubForm whereas the new property MDIActiveObject provides a ref to it.

The list of such Properties includes the following:

MDIAtive | MDIActiveObject
PageActive | PageActiveObject


New Fonts and Keyboard Files

Version 11.0 includes a new set of APL fonts and an additional set of keyboard files.

The new fonts include the ⍣ symbol (Power operator) and € symbol which replaces left tack.

The Dyalog APL TrueType fonts (Dyalog Std TT and Dyalog Alt TT) have improved appearance characteristics, especially as larger sizes.

The APL385 Unicode font is also included with Version 11. This font is recommended for use with Notepad and other text editors when viewing and editing APLScript files.

The separate unified and traditional mode keyboards provided in previous versions of Dyalog APL have been combined into a single table. For each supported country, the new table is named cc.din, where cc is the country code. These tables are provided in additional to the ones supplied with previous versions of Dyalog APL.

The keyboards start in unified mode and can be switched to traditional mode (Shift+r for ⍴) by clicking the Uni/Apl field in the status bar or by keying * on the Numeric-Keypad.

The new tables support the entry of the ⍣ and ⌷ symbols by pressing Ctrl+Shift+p and Ctrl+Shift+l in either mode. However, the new tables do not support the entry of APL underscored characters ⍙ÁÂÃÇÈÊËÌÍÎÏÐÒÓÔÕÙÚÛÝÞãìðòõ

During installation, the appropriate new table will be presented as the default choice.

Note that the standard keyboard tables provided with earlier versions of Dyalog APL are provided in the \old sub-directory.


New AutoComplete Feature

Version 11.0 includes an enhancement to AutoComplete that is designed to cater for the use of common prefixes in names

It is not unusual for developers to adopt a convention of prefixing a group of APL names with a common string of characters. To improve the usefulness of the AutoComplete feature in these circumstances, a new Common key has been provided.

If you are typing and the AutoComplete window is displayed, pressing the Common key will auto-complete the common prefix. This is defined to be the longest string of leading characters in the currently selected name that is shared by at least one other name in the list.

For example, if the workspace contains variables AAaa1, AAaa2, AAaa3, ABbb1, ABbb2, ABbb3, ACcc1 and the system is set to AutoComplete on 1 character, typing A will cause the AutoComplete window to display all 7 names.

If AAaa1 is the currently selected name, clicking the Common key will fill in the rest of the common prefix, namely Aaa, and reduce the list to AAaa1, AAaa2 and AAaa3.

If ABbb1 is the currently selected name, clicking the Common key will fill in the characters Bbb, and reduce the list to AAbb1, AAbb2 and AAbb3.

Whereas if the currently selected name is ACcc1, clicking the Common key has no effect.


Isolation Mode

There is a new option on the Create Bound File dialog box, when exporting a Class as a Microsoft .Net Assembly (dll), labelled Isolation Mode.

For each application which uses a class written in Dyalog APL, at least one copy of either dyalog110.dll or dyalog110rt.dll will be started in order to host and execute the appropriate APL code. Each of these engines will have an APL workspace associated with it, and this workspace will contain classes and instances of these classes. The number of engines (and associated workspaces) which are started will depend on the Isolation Mode which was selected when the APL assemblies used by the application were generated. Isolation modes are:

  1. Each host process has a single workspace
  2. Each appdomain has its own workspace
  3. Each assembly has its own workspace

The last two Isolation Modes are new in version 11.0. Previously, each application always used a single engine to run all classes and instances used by that application.

Note that, in this context, Microsoft Internet Information Services (IIS) is a single application, even though it may be hosting a large number of different web pages. Each ASP.Net application will be running in a separate AppDomain, a .NET object which is an isolated subdivision of the application. Other .NET applications may also be divided into different AppDomains.

In other words, if you use the first option, ALL classes and instances used by any IIS web page will be hosted in the same workspace and share a single copy of the interpreter. The second option will start a new Dyalog engine for each ASP.Net application. The final option will start a new Dyalog engine for each assembly containing APL classes.


Export to Memory

There is a new option on the Session File menu labelled Export to Memory.

If you create an APL Class based upon a .Net Type, you must export it as a .Net Assembly before you can use it.

This option allows you to create an in-memory .Net Assembly that you can use to test the Class, without having to repeatedly go through the entire exercise of saving it as a .Net Assembly on disk (as a DLL file) as you develop the code.

Furthermore, using this option, it is not necessary to Close the AppDomain (see next topic) each time you replace the Assembly. However, be aware that each time you export (to memory), additional memory is used and it may be appropriate to free it (using Close AppDomain) periodically.

Note that to use an in-memory Assembly, it is not necessary to set ⎕USING.

You only need to re-export to memory if you make a change to your class which changes the public interface of the class. So changes to functions do not require re-exporting, but if you add a new method or change a signature, you must re-export.

Note that, APL will only allow you to use a Class based upon a .Net Type via a .Net Assembly, either an in-memory Assembly or a DLL file on disk. You may not use a Class directly.


Close AppDomain

There is a new option on the Session File menu labelled Close AppDomain.

When APL uses a Class which is in a .Net Assembly (normally a DLL file), that Assembly is loaded into a .Net memory area known as the Application Domain, or the AppDomain for short. When an assembly is in use by any application, including the current APL workspace, you cannot overwrite the DLL file on disk, so you cannot make changes to classes which need to be exported in order to be used.

Previously, during the development of a Class based upon a .Net Type (NetType) it was necessary to )CLEAR, re-load the workspace or terminate Dyalog APL each time you needed to update the DLL. Note that APL automatically closes the AppDomain when a workspace is loaded, or on )CLEAR.

In order to speed up the development cycle, Version 11 provides a menu item which closes the AppDomain so that you can then overwrite the DLL you were using with a new version.

Note that any instances of .Net classes become null pointers when you do this:

      dt←System.DateTime.Now
      dt
04-05-2006 14:06:46

[Close AppDomain]

      dt
(NULL)


External Object (COM and .Net) Behaviour

External Object Behaviour

Version 11.0 improves the behaviour of COM and .Net objects, but for backwards compatibility it is possible to select old or new behaviour using ⎕WX.

Old behaviour:

  • Character vectors supplied as arguments to external functions, which are defined as String parameters, are automatically enclosed for you. Similarly, string results are automatically disclosed.
  • Properties that take parameters, such as the Item Property in a Collection, are treated as methods.
  • APL provides lists of the Properties, Methods and Events provided by a GUI object by exposing additional properties named PropList, MethodList and EventList.

New behaviour

  • Character vectors supplied as arguments to external functions, which are defined as String parameters, must be enclosed. Strings are returned as enclosed character vectors.
  • Properties that take indices, such as the Item Property in a Collection, are honoured as Numbered or Keyed Properties and may be accessed by indexing.
  • PropList, MethodList and EventList are not exposed. Instead, the information is provided by ⎕NL ¯2,¯3 and ¯8 (but alphabetically sorted).

The actual behaviour of a COM or .Net object is now determined by its value of ⎕WX. If ⎕WX is 0 or 1, the old behaviour will apply. If ⎕WX is 3, the new behaviour will apply.

The behaviour of COM and .Net objects in existing applications will remain the same (because ⎕WX will be 0 or 1) but you may obtain the benefits of the new behaviour by setting ⎕WX to 3 at the appropriate level in your application. Then, everything below that (in the namespace hierarchy) will adopt the new behaviour.

Note that regardless of the value of ⎕WX, Version 11 will honour the Default Property of an external object thereby permitting the direct use of indexing on the object itself.

For example, if xl is an instance of the Excel.Application COM class, the following expression to obtain the contents of the first Sheet in the first Workbook will succeed, whatever the value of ⎕WX.

      xl.Workbooks[1].Sheets[1].UsedRange.Value2

Note that it is the value of ⎕WX which the object acquired when it was created, rather than the current value of ⎕WX, which decide the behaviour.

Like other system variables, ⎕WX is inherited from the environment when a new namespace, class or instance is created. Classes inherit the value of ⎕WX when a class is edited or fixed, unless the class script explicitly sets a value for ⎕WX. In the case of .NET classes, ⎕WX is inherited when the class or namespace is loaded from a .NET assembly. For built-in (GUI) classes, each new instance inherits ⎕WX when it is created.

Examples

      ⎕WX←1
      'XLW' ⎕WC 'OleClient' 'Excel.Application'
      XLW.Workbooks.Add ⍬
      XLW.ActiveWorkbook.Sheets.(Item 'Sheet2').Index
2

      ⎕WX←3
      XL←⎕WC 'OleClient' (⊂'ClassName' 'Excel.Application')
      XL.Workbooks.Add ⍬
      XL.ActiveWorkbook.Sheets[⊂'Sheet2'].Index
2

Note that it is the value of ⎕WX in the object, and not in the calling environment, that decides the behaviour:

      ⎕wx←3
      ⎕using←''
      System.DateTime.Parse⊂'2006-09-12'
12/09/2006 00:00:00
      ⎕wx←1
      System.DateTime.Parse'2006-09-12'
LENGTH ERROR
      System.DateTime.Parse'2006-09-12'
     ∧
      System.DateTime.⎕WX←1
      System.DateTime.Parse'2006-09-12'
12/09/2006 00:00:00

Note that, if we expunged the System.DateTime class instead of setting ⎕WX to 1, and repeated the expression, a new DateTime class would be created but it would inherit ⎕WX from its parent (System), where ⎕WX still has the value 3. Using .NET classes in an application where ⎕WX varies within a single APL namespace can therefore lead to unexpected results. It is recommended that applications only use more than one value for ⎕WX as a temporary measure during a conversion project.


Configuring for different Versions of the .Net Framework

Dyalog APL Version 11.0 is compatible with versions 1.1 and 2.0 of the Microsoft.Net Framework

On a machine that has multiple versions of the .Net framework installed, Dyalog APL will use the most recent version by default. If you have both versions and need to use version 1.1 for any reason, there are two configuration files which are distributed with version 11 but need to renamed in order to take effect:

dyalog.exe.config.1.1 (in the main Dyalog folder, and)
bin\dyalogc.exe.config.1.1 (which controls the script compiler)

If you rename these files and remove the trailing “.1.1”, so that the final file extension becomes “config”, they will take effect, and cause the development environment and the script compiler (respectively) to use version 1.1 of the framework. The contents of these files are as follows:

   <?xml version ="1.0"?>
   <configuration>
     <startup>
       <supportedRuntime version="v1.1.4322" />
     </startup>
   </configuration>

Note that ASP.NET may be configured to assume that version 1.1 of the framework should be used. This can be configured differently for each “virtual folder”, like the dyalog.net virtual folder which contains tutorials and examples distributed with Dyalog APL version 11.0. You can verify the ASP.NET setting by starting the IIS Control Panel, selecting Properties for a virtual folder, and navigating to the ASP.NET tab (see the picture below).

Note that it is not currently possibly for a single version of Dyalog APL to be used to compile and run web pages using different versions of the framework simultaneously. If you have web pages which need to continue to run under version 1.1, but wish to develop new ones under 2.0, you must either host the pages on different machines, or use version 10.1 of Dyalog APL to host the old web pages.

In theory, you could use version 1.1 for the script compiler in order to run web pages under 1.1 and the development environment under 2.0 in order to experiment with non-IIS functionality, but this is not recommended.

We hope to relax this restriction in a future version of Dyalog APL.

For more information, see

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconSide-by-SideExecution.asp

Upgrading to .Net Version 2 (Batch=False)

When upgrading to .Net Version 2, it is necessary to explicitly disable batching in the compilation element for ASP.NET in your own config.web and/or machine.config files that you were using with .Net Version 1.

Note that the compilation element in Dyalog APL 11.0\Samples\asp.net\web.config is as follows:

   <compilation debug="true" batch="false"/>


System Errors

Non-Specific System Errors (previously reported as syserror 999) are the result of Operating System exceptions that can occur due to a fault in Dyalog APL itself, an error in a Windows or other DLL, or even as a result of a hardware fault.

  • System Errors arising from exceptions in DLLs and OLE calls are now separately identified.
  • When a System Error occurs, APL now displays the APL function-calling stack so that you can identify the likely source of the problem in your APL code.
  • It is now possible to pass exceptions on so that they can be debugged by Operating System and other software. This is most relevant if the exception is generated by your own DLL or Auxiliary Processor code.
  • The generation of an aplcore file is now optional, and the name of the aplcore file is now under your control.

System Error Codes

Code | Description | Suggested Action
900 | A Paging Fault has occurred | As the most likely cause is a temporary network fault, recommended course of action is to restart your program.
990 & 991 | An exception has occurred in dyalog11.dll or dyalog11rt.dll |
995 | An exception has occurred in a DLL function called via ⎕NA | Carefully check your ⎕NA statement and the arguments that you have passed to the DLL function
996 | An exception has occurred in a DLL function called via a threaded ⎕NA call | As above
997 | An exception has occurred while processing an incoming OLE call |
999 | An exception has been caused by Dyalog APL or by the Operating System |

System Error Parameters

The following new parameters may be used to control how System Errors are handled.

Parameter | Description
PassExceptionToOpSys | This parameter specifies the default state of the Pass Exception check box in the System Error dialog box
AplcoreName | Specifies the directory and name of the file in which the aplcore should be saved. The optional wild-card character (*) is replaced by a unique string when the file is written. For example: APLCORENAME=C:\mycores\aplcore*.dat
ErrorOnExternalException | If this parameter is set to 1, and an exception occurs in a call on an external DLL. APL generates an EXTERNAL DLL EXCEPTION error (91), instead of terminating with a System Error. This error may be trapped. See below.

System Error Dialog Box

The System Error illustrated below was generated by causing a deliberate exception in the Windows DLL function memcpy(). The functions used were:

     ∇ foo
[1]    goo
     ∇
     ∇ goo
[1]    hoo
     ∇
     ∇ hoo
[1]    crash
     ∇

     ∇ crash
[1]    ⎕NA'dyalog32|MEMCPY u u u'
[2]    MEMCPY 255 255 255
     ∇

Options

Item | Description
Generate complete image core | Dumps a complete core image with the User Mode Process Dumper (a Microsoft tool) - see below.
Create Trappable Error (only enabled on System Error codes 995 and 996) | If you check this box, APL will not terminate but will instead generate an error 91 (EXTERNAL DLL EXCEPTION) when you press Dismiss.
Create an aplcore file | If this box is checked, an aplcore file will be created.
Pass exception on to operating system | If this box is checked, the exception will be passed on to your current debugging tool (e.g. Visual Studio).
Paste to clipboard | Copies the contents of the APL stack trace window to the Clipboard.

Generate complete image core

The Generate complete image core option attempts to execute [SYSDIR]\userdump.exe, where [SYSDIR] is the windows system directory (typically c:\windows\system32, and userdump.exe is the User Mode Process Dumper, a Microsoft tool that can be downloaded from the following url:

http://www.microsoft.com/downloads/details.aspx?FamilyID=e23cd741-d222-48df-9cd8-28796f414256&DisplayLang=en

The process creates a file called dyalog.core in the current directory. This file contains much more debug information than a normal aplcore (and is much larger than an aplcore) and can be sent to Dyalog Limited (zip it first please). Alternatively the file can be loaded into Visual Studio .Net to do your own debugging.

ErrorOnExternalException Parameter

This parameter allows you to prevent APL from displaying the System Error dialog box (and terminating) when an exception caused by an external DLL occurs. The following example illustrates what happens when the functions above are run, but with ErrorOnExternalException set to 1.

      ⎕←2 ⎕NQ'.' 'GetEnvironment' 'ErrorOnExternalException'
1
      foo
EXTERNAL DLL EXCEPTION
crash[2] MEMCPY 255 255 255
        ∧
      ⎕EN
91
      )SI
crash[2]*
hoo[1]
goo[1]
foo[1]

Debugging your own DLLs

If you are using Visual Studio on Microsoft Windows XP (or similar), the following procedure should be used to debug your own DLLs when an appropriate Dyalog APL System Error occurs.

Ensure that the Pass Exception box is checked, then click on Dismiss to close the System Error dialog box.

The system exception dialog box appears. Click on Debug to start the process in the Visual Studio debugger.

After debugging, the system exception dialog box appears again. Click on Don't send to terminate Microsoft Windows XP's exception handling.


WorkspaceLoaded Event

WorkspaceLoaded Event 525

Applies to: Session (⎕SE)

If enabled, this event is reported when a workspace is loaded or on a clear ws. You may not nullify or modify the event with a 0-returning callback, nor may you generate the event using ⎕NQ, or call it as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector ('⎕SE')
[2] | Event name or code | 'WorkspaceLoaded' or 525

This event is fired immediately after a workspace has been loaded and before the execution of ⎕LX.

The callback function you attach should be defined in ⎕SE.


Miscellaneous V11 Enhancements

Miscellaneous

Miscellaneous changes introduced in Version 11.0 are as follows:

Keyboard Viewer

The Version 11 Session includes the Kibitzer keyboard viewer from Kai Jäger.

See Tools-> Keyboard Viewer ...

PassSingletonAsScalar

In Version 11.0, the default value of PassSingletonAsScalar is 0. In previous versions of Dyalog APL it was 1.


Triggers

Triggers provide the ability to have a function called automatically whenever a variable or a Field is assigned. Triggers are actioned by all forms of assignment (←), but only by assignment.

Triggers are designed to allow a class to perform some action when a field is modified – without having to turn the field into a property and use the property setter function to achieve this. Avoiding the use of a property allows the full use of the APL language to manipulate data in a field, without having to copy field data in and out of the class through get and set functions.

Triggers can also be applied to variables outside a class, and there will be situations where this is very useful. However, dynamically attaching and detaching a trigger from a variable is a little tricky at present.

The function that is called when a variable or Field changes is referred to as the Trigger Function. The name of a variable or Field which has an associated Trigger Function is termed a Trigger.

A function is declared as aTrigger function by including the statement:

      :Implements Trigger Name1,Name2,Name3, ...

where Name1, Name2 etc are the Triggers.

When a Trigger function is invoked, it is passed an Instance of the internal Class TriggerArguments. This Class has 3 Fields:

Member | Description
Name | Name of the Trigger whose change in value has caused the Trigger Function to be invoked.
NewValue | The newly assigned value of the Trigger
OldValue | The previous value of the Trigger. If the Trigger was not previously defined, a reference to this Field causes a VALUE ERROR.

A Trigger Function is called as soon as possible after the value of a Trigger was assigned; typically by the end of the currently executing line of APL code. The precise timing is not guaranteed and may not be consistent because internal workspace management operations can occur at any time.

If the value of a Trigger is changed more than once by a line of code, the Trigger Function will be called at least once, but the number of times is not guaranteed.

A Trigger Function is not called when the Trigger is expunged.

Expunging a Trigger disconnects the name from the Trigger Function and the Trigger Function will not be invoked when the Trigger is reassigned. The connection may be re-established by re-fixing the Trigger Function.

A Trigger may have only a single Trigger Function. If the Trigger is named in more than one Trigger Function, the Trigger Function that was last fixed will apply.

In general, it is inadvisable for a Trigger function to modify its own Trigger, as this will potentially cause the Trigger to be invoked repeatedly and forever.

To associate a Trigger function with a local name, it is necessary to dynamically fix the Trigger function in the function in which the Trigger is localised; for example:

     ∇ TRIG arg
[1]    :Implements Trigger A
[2]    ...

     ∇ TEST;A
[1]    ⎕FX ⎕OR'TRIG'
[2]    A←10
[3] ...

See Trigger Fields for information on how a Field (in a Class) may be used as a Trigger.


Trigger Example

The following function displays information when the value of variables A or B changes.

     ∇ TRIG arg
[1]    :Implements Trigger A,B
[2]    arg.Name'is now 'arg.NewValue
[3]    :Trap 6 ⍝ VALUE ERROR
[4]        arg.Name'was    'arg.OldValue
[5]    :Else
[6]        arg.Name' was     [undefined]'
[7]    :EndTrap
     ∇

Note that on the very first assignment to A, when the variable was previously undefined, arg.OldValue is a VALUE ERROR.

      A←10
 A  is now   10
 A   was     [undefined]

      A+←10
 A  is now   20
 A  was      10

      A←'Hello World'
 A  is now   Hello World
 A  was      20

      A[1]←⊂2 3⍴⍳6
 A  is now    1 2 3 ello World
              4 5 6
 A  was      Hello World

      B←⌽¨A
 B  is now    3 2 1 ello World
              6 5 4
 B   was     [undefined]

      A←⎕NEW MyClass
 A  is now   #.[Instance of MyClass]
 A  was       1 2 3 ello World
              4 5 6

      'F'⎕WC'Form'
      A←F
 A  is now   #.F
 A  was      #.[Instance of MyClass]

Note that Trigger functions are actioned only by assignment, so changing A to a Form using ⎕WC does not invoke TRIG.

      'A'⎕WC'FORM' ⍝ Note that Trigger Function is not invoked

However, the connection (between A and TRIG) remains and the Trigger Function will be invoked if and when the Trigger is re-assigned.

      A←99
 A  is now   99
 A  was      #.A

See Trigger Fields for information on how a Field (in a Class) may be used as a Trigger.


Trigger Fields

A Fields may act as a Trigger so that a function may be invoked whenever the value of the Field is changed.

As an example, it is often useful for the Display Form of an Instance to reflect the value of a certain Field. Naturally, when the Field changes, it is desirable to change the Display Form. This can be achieved by making the Field a Trigger as illustrated by the following example.

Notice that the Trigger function is invoked both by assignments made within the Class (as in the assignment in ctor) and those made from outside the Instance.

:Class MyClass
    :Field Public Name
    :Field Public Country←'England'
    ∇ ctor nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇
    ∇ format
      :Implements Trigger Name,Country
      ⎕DF'My name is ',Name,' and I live in ',Country
    ∇
:EndClass ⍝ MyClass
      me←⎕NEW MyClass 'Pete'
      me
My name is Pete and I live in England

      me.Country←'Greece'
      me
My name is Pete and I live in Greece

      me.Name←'Kostas'
      me
My name is Kostas and I live in Greece


Introducing Classes

A Class is a blueprint from which one or more Instances of the Class can be created (instances are sometimes also referred to as Objects).

A Class may optionally derive from another Class, which is referred to as its Base Class.

A Class may contain Methods, Properties and Fields (commonly referred to together as Members) which are defined within the body of the class script or are inherited from other Classes.

This version of Dyalog APL does not support Events although it is intended that these will be provided in a future release. However, Classes that are derived from .Net types may generate events using 4 ⎕NQ.

A Class that is defined to derive from another Class automatically acquires the set of Properties, Methods and Fields that are defined by its Base Class. This mechanism is described as inheritance.

A Class may extend the functionality of its Base Class by adding new Properties, Methods and Fields or by substituting those in the Base Class by providing new versions with the same names as those in the Base Class.

Members may be defined to be Private or Public. A Public member may be used or accessed from outside the Class or an Instance of the Class. A Private member is internal to the Class and (in general) may not be referenced from outside.

Although Classes are generally used as blueprints for the creation of instances, a class can have Shared members which can be used without first creating an instance


Defining Classes

A Class is defined by a script that may be entered and changed using the editor. A class script may also be constructed from a vector of character vectors, and fixed using ⎕FIX.

A class script begins with a :Class statement and ends with a :EndClass statement.

For example, using the editor:

      )CLEAR
clear ws
      )ED ○Animal

[an edit window opens containing the following skeleton Class script …]

:Class Animal
:EndClass

[the user edits and fixes the Class script]

      )CLASSES
Animal
      ⎕NC⊂'Animal'
9.4


Editing Classes

Between the :Class and :EndClass statements, you may insert any number of function bodies, Property definitions, and other elements. When you fix the Class Script from the editor, these items will be fixed inside the Class namespace.

Note that the content of the Class Script defines the Class in its entirety. You may not add or alter functions by editing them independently and you may not add variables by assignment or remove objects with ⎕EX.

When you re-fix a Class Script using the Editor or with ⎕FIX, the original Class is discarded and the new definition, as specified by the Script, replaces the old one in its entirety.

Note:

Associated with a Class (or an instance of a class) there is a completely separate namespace which surrounds the class and can contain functions, variables and so forth that are created by actions external to the class.

For example, if X is not a public member of the class MyClass, then the following expression will insert a variable X into the namespace which surrounds the class:

      MyClass.X←99

The namespace is analogous to the namespace associated with a GUI object and will be re-initialised (emptied) whenever the Class is re-fixed. Objects in this parallel namespace are not visible from inside the Class or an Instance of the Class.


Class Inheritance

Inheritance

If you want a Class to derive from another Class, you simply add the name of that Class to the :Class statement using colon+space as a separator.

The following example specifies that CLASS2 derives from CLASS1.

:Class CLASS2: CLASS1
:EndClass

Note that CLASS1 is referred to as the Base Class of CLASS2.

If a Class has a Base Class, it automatically acquires all of the Public Properties, Methods and Fields defined for its Base Class unless it replaces them with its own members of the same name. This principle of inheritance applies throughout the Class hierarchy. Note that Private members are not subject to inheritance.

Warning: When a class is fixed, it keeps a reference (a pointer) to its base class. If the global name of the base class is expunged, the derived class will still have the base class reference, and the base class will therefore be kept alive in the workspace. The derived class will be fully functional, but attempts to edit it will fail when it attempts to locate the base class as the new definition is fixed.

At this point, if a new class with the original base class name is created, the derived class has no way of detecting this, and it will continue to use the old and invisible version of the base class. Only when the derived class is refixed, will the new base class be detected.

If you edit, refix or copy an existing base class, APL will take care to patch up the references, but if the base class is expunged first and recreated later, APL is unable to detect the substitution. You can recover from this situation by editing or refixing the derived class(es) after the base class has been substituted.

Classes that derive from .Net Types

You may define a Class that derives from any of the .Net Types by specifying the name of the .Net Type and including a :USING statement that provides a path to the .Net Assembly in which the .Net Type is located.

Example

:Class APLGreg: GregorianCalendar
:Using System.Globalization
...
:EndClass

For further details see Writing Classes Based on .Net Typers.

Classes that derive from the Dyalog GUI

You may define a Class that derives from any of the Dyalog APL GUI objects by specifying the name of the Dyalog APL GUI Class in quotes.

For example, to define a Class named Duck that derives from a Poly object, the Class specification would be:

:Class Duck: 'Poly'
:EndClass

The Base Constructor for such a Class is the ⎕WC system function.

For further details see Writing Classes Based on the Dyalog GUI.


Instances

A Class is generally used as a blueprint or model from which one or more Instances of the Class are constructed. Note however that a class can have Shared members which can be used directly without first creating an instance

You create an instance of a Class using the ⎕NEW system function which is monadic.

The 1-or 2-item argument to ⎕NEW contains a reference to the Class and, optionally, arguments for its Constructor function.

When ⎕NEW executes, it first creates an empty instance namespace and tags it with an internal pointer to its Class.

When ⎕NEW executes, it creates a regular APL namespace to contain the Instance, and within that it creates an Instance space, which is populated with any Instance Fields defined by the class (with default values if specified), and pointers to the Instance Method and Property definitions specified by the Class.

If a monadic Constructor is defined, it is called with the arguments specified in the second item of the argument to ⎕NEW. If ⎕NEW was called without Constructor arguments, and the class has a niladic Constructor, this is called instead.

The Constructor function is typically used to initialise the instance and may establish variables in the instance namespace.

The result of ⎕NEW is a reference to the instance namespace. Instances of Classes exhibit the same set of Properties, Methods and Fields that are defined for the Class.


Constructors

A Constructor is a special function defined in the Class script that is to be run when an Instance of the Class is created by ⎕NEW. Typically, the job of a Constructor is to initialise the new Instance in some way.

A Constructor is identified by a :Implements Constructor statement. This statement may appear anywhere in the body of the function after the function header. The significance of this is discussed below.

Note that it is also essential to define the Constructor to be Public, with a :Access Public statement, because like all Class members, Constructors default to being Private. Private Constructors currently have no use or purpose, but It is intended that they will be supported in a future release of Dyalog APL.

A Constructor function may be niladic or monadic and must not return a result.

A Class may specify any number of different Constructors of which one (and only one) may be niladic. This is also referred to as the default Constructor.

There may be any number of monadic Constructors, but each must have a differently defined argument list which specifies the number of items expected in the Constructor argument. See Constructor Overloading for details.

A Constructor function may not call another Constructor function and a constructor function may not be called directly from outside the Class. The only way a Constructor function may be invoked is by ⎕NEW. See Base Constructors for further details.

When ⎕NEW is executed with a 2-item argument, the appropriate monadic Constructor is called with the second item of the ⎕NEW argument.

The niladic (default) Constructor is called when ⎕NEW is executed with a 1-item argument, a Class reference alone, or whenever APL needs to create a fill item for the Class.

Note that ⎕NEW first creates a new instance of the specified Class, and then executes the Constructor inside the instance.

Example

The DomesticParrot Class defines a Constructor function egg that initialises the Instance by storing its name (supplied as the 2nd item of the argument to ⎕NEW) in a Public Field called Name.

:Class DomesticParrot: Parrot
    :Field Public Name

    ∇ egg name
      :Implements Constructor
      :Access Public
      Name←name
    ∇
    ...
:EndClass ⍝ DomesticParrot
      pol←⎕NEW DomesticParrot 'Polly'
      pol.Name
Polly


Constructor Overloading

NameList header syntax is used to define different versions of a Constructor each with a different number of parameters, referred to as its signature. The Clover Class illustrates this principle.

In deciding which Constructor to call, APL matches the shape of the Constructor argument with the signature of each of the Constructors that are defined. If a constructor with the same number of arguments exists (remembering that 0 arguments will match a niladic Constructor), it is called. If there is no exact match, and there is a Constructor with a general signature (an un-parenthesised right argument), it is called. If no suitable constructor is found, a LENGTH ERROR is reported.

There may be one and only one constructor with a particular signature.

A Constructor function may not call another Constructor function and a constructor function may not be called directly from outside the Class. The only way a Constructor function may be invoked is by ⎕NEW. See Base Constructors for further details.

In the Clover Class example Class, the following Constructors are defined:

Constructor | Implied argument
Make1 | 1-item vector
Make2 | 2-item vector
Make3 | 3-item vector
Make0 | No argument
MakeAny | Any array accepted

In the following examples, the Make function (see Clover Class listing for details) displays:

<shape of argument> <name of Constructor called><argument> (see function Make)

Creating a new Instance of Clover with a 1-element vector as the Constructor argument, causes the system to choose the Make1 Constructor.Note that, although the argument to Make1 is a 1-element vector, this is disclosed as the list of arguments is unpacked into the (single) variable arg1.

      (⎕NEW Clover(,1)).Con
   Make1  1

Creating a new Instance of Clover with a 2- or 3-element vector as the Constructor argument causes the system to choose Make2, or Make3 respectively.

      (⎕NEW Clover(1 2)).Con
 2  Make2  1 2
      (⎕NEW Clover(1 2 3)).Con
 3  Make3  1 2 3

Creating an Instance with any other Constructor argument causes the system to choose MakeAny.

      (⎕NEW Clover(⍳10)).Con
 10  MakeAny  1 2 3 4 5 6 7 8 9 10
      (⎕NEW Clover(2 2⍴⍳4)).Con
 2 2  MakeAny  1 2
               3 4

Note that a scalar argument will call MakeAny and not Make1.

      (⎕NEW Clover 1).Con
   MakeAny  1

and finally, creating an Instance without a Constructor argument causes the system to choose Make0.

      (⎕NEW Clover).Con
   Make0  0


Niladic (Default) Constructors

A Class may define a niladic Constructor and/or one or more Monadic Constructors. The niladic Constructor acts as the default Constructor that is used when ⎕NEW is invoked without arguments and when APL needs a fill item.

:Class Bird
    :Field Public Species

    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      Species←spec
    ∇
    ∇ default
      :Access Public Instance
      :Implements Constructor
      Species←'Default Bird'
    ∇
    ∇ R←Speak
      :Access Public
      R←'Tweet, tweet!'
    ∇

:EndClass ⍝ Bird

The niladic Constructor (in this example, the function default) is invoked when ⎕NEW is called without Constructor arguments. In this case, the Instance created is no different to one created by the monadic Constructor egg, except that the value of the Species Field is set to 'Default Bird'.

      Birdy←⎕NEW Bird
      Birdy.Species
Default Bird

The niladic Constructor is also used when APL needs to make a fill item of the Class. For example, in the expression (3↑Birdy), APL has to create two fill items of Birdy (one for each of the elements required to pad the array to length 3) and will in fact call the niladic Constructor twice.

In the following statement:

      TweetyPie←3⊃10↑Birdy

The 10↑ (temporarily) creates a 10-element array comprising the single entity Birdy padded with 9 fill-elements of Class Bird. To obtain the 9 fill-elements, APL calls the niladic Constructor 9 times, one for each separate prototypical Instance that it is required to make.

      TweetyPie.Species
Default Bird


Empty Arrays of Instances: Why ?

In APL it is natural to use arrays of Instances. For example, consider the following example.

:Class Cheese
    :Field Public Name←''
    :Field Public Strength←⍬
    ∇ make2(name strength)
      :Access Public
      :Implements Constructor
      Name Strength←name strength
    ∇
    ∇ make1 name
      :Access Public
      :Implements Constructor
      Name Strength←name 1
    ∇
    ∇ make_excuse
      :Access Public
      :Implements Constructor
      ⎕←'The cat ate the last one!'
    ∇
:EndClass

We might create an array of Instances of the Cheese Class as follows:

      cheeses←{⎕NEW Cheese ⍵}¨('Camembert' 5)('Caephilly' 2) 'Mild Cheddar'

Suppose we want a range of medium-strength cheese for our cheese board.

      board←(cheeses.Strength<3)/cheeses
      board.Name
 Caephilly  Mild Cheddar

But look what happens when we try to select really strong cheese:

      board←(cheeses.Strength>5)/cheeses
      board.Name
The cat ate the last one!

Note that this message is not the result of the expression, but was explicitly displayed by the make_excuse function. The clue to this behaviour is the shape of board; it is empty!

      ⍴board
0

When a reference is made to an empty array of Instances (strictly speaking, a reference that requires a prototype), APL creates a new Instance by calling the niladic (default) Constructor, uses the new Instance to satisfy the reference, and then discards it. Hence, in this example, the reference:

      board.Name

caused APL to run the niladic Constructor make_excuse, which displayed:

The cat ate the last one

Notice that the behaviour of empty arrays of Instances is modelled VERY closely after the behaviour of empty arrays in general. In particular, the Class designer is given the task of deciding what the types of the members of the prototype are.

The full explanation is given in the next topic.


Empty Arrays of Instances: How?

To cater for the need to handle empty arrays of Instances as easily as non-empty arrays, a reference to an empty array of Class Instances is handled in a special way.

Whenever a reference or an assignment is made to the content of an empty array of Instances, the following steps are performed:

  1. APL creates a new Instance of the same Class of which the empty Instance belongs.
  2. the default (niladic) Constructor is run in the new Instance
  3. the appropriate value is obtained or assigned:
    • if it is a reference is to a Field, the value of the Field is obtained
    • if it is a reference is to a Property, the PropertyGet function is run
    • if it is a reference is to a Method, the method is executed
    • if it is an assignment, the assignment is performed or the PropertySet function is run
  4. if it is a reference, the result of step 3 is used to generate an empty result array with a suitable prototype by the application of the function {0⍴⊂⍵} to it
  5. the Class Destructor (if any) is run in the new Instance
  6. the New Instance is deleted

Example

:Class Bird
    :Field Public Species

    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      ⎕DF Species←spec
    ∇
    ∇ default
      :Access Public Instance
      :Implements Constructor
      ⎕DF Species←'Default Bird'
      #.DISPLAY Species
    ∇
    ∇ R←Speak
      :Access Public
      #.DISPLAY R←'Tweet, Tweet, Tweet'
    ∇

:EndClass ⍝ Bird

First, we can create an empty array of Instances of Bird using 0⍴.

      Empty←0⍴⎕NEW Bird 'Robin'

A reference to Empty.Species causes APL to create a new Instance and invoke the niladic Constructor default. This function sets Species to 'Default Bird'and calls #.DISPLAY which displays output to the Session.

      DISPLAY Empty.Species
.→-----------.
|Default Bird|
'------------'

APL then retrieves the value of Species ('Default Bird'), applies the function {0⍴⊂⍵} to it and returns this as the result of the expression.

.⊖---------------.
| .→-----------. |
| |            | |
| '------------' |
'∊---------------'

A reference to Empty.Speak causes APL to create a new Instance and invoke the niladic Constructor default. This function sets Species to 'Default Bird'and calls #.DISPLAY which displays output to the Session.

      DISPLAY Empty.Speak
.→-----------.
|Default Bird|
'------------'

APL then invokes function Speak which returns the result 'Tweet, Tweet, Tweet'.

.→------------------.
|Tweet, Tweet, Tweet|
'-------------------'

APL then applies the function {0⍴⊂⍵} to it and returns this as the result of the expression.

.⊖----------------------.
| .→------------------. |
| |                   | |
| '-------------------' |
'∊----------------------'


Base Constructors

Constructors in a Class hierarchy are not inherited in the same way as other members. However, there is a mechanism for all the Classes in the Class inheritance tree to participate in the initialisation of an Instance.

Every Constructor function contains a:Implements Constructor statement which may appear anywhere in the function body. The statement may optionally be followed by the :Base control word and an arbitrary expression.

The statement:

      :Implements Constructor :Base expr

calls a monadic Constructor in the Base Class. The choice of Constructor depends upon the rank and shape of the result of expr (see Constructor Overloading for details).

Whereas, the statement:

      :Implements Constructor

or

      :Implements Constructor :Base

calls the niladic Constructor in the Base Class.

Note that during the instantiation of an Instance, these calls potentially take place in every Class in the Class hierarchy.

If, anywhere down the hierarchy, there is a monadic call and there is no matching monadic Constructor, the operation fails with a LENGTH ERROR.

If there is a niladic call on a Class that defines no Constructors, the niladic call is simply repeated in the next Class along the hierarchy.

However, if a Class defines a monadic Constructor and no niladic Constructor it implies that that Class cannot be instantiated without Constructor arguments. Therefore, if there is a call to a niladic Constructor in such a Class, the operation fails with a LENGTH ERROR. Note that it is therefore impossible for APL to instantiate a fill item or process a reference to an empty array for such a Class or any Class that is based upon it.

A Constructor function may not call another Constructor function and a constructor function may not be called directly from outside the Class or Instance. The only way a Constructor function may be invoked is by ⎕NEW. The fundamental reason for these restrictions is that there must be one and only one call on the Base Constructor when a new Instance is instantiated. If Constructor functions were allowed to call one another, there would be several calls on the Base Constructor. Similarly, if a Constructor could be called directly it would potentially duplicate the Base Constructor call.


Niladic Example

Base Constructors: Niladic Example

In the following example, DomesticParrot is derived from Parrot which is derived from Bird. They all share the Field Desc (inherited from Bird). Each of the 3 Classes has its own niladic Constructor called egg0.

:Class Bird
    :Field Public Desc
    ∇ egg0
      :Access Public
      :Implements Constructor
      Desc←'Bird'
    ∇
:EndClass ⍝ Bird

:Class Parrot: Bird
    ∇ egg0
      :Access Public
      :Implements Constructor
      Desc,←'→Parrot'
    ∇
:EndClass ⍝ Parrot

:Class DomesticParrot: Parrot
    ∇ egg0
      :Access Public
      :Implements Constructor
      Desc,←'→DomesticParrot'
    ∇
:EndClass ⍝ DomesticParrot

      (⎕NEW DomesticParrot).Desc
Bird→Parrot→DomesticParrot

Explanation

⎕NEW creates the new instance and runs the niladic Constructor DomesticParrot.egg0. As soon as the line:

:Implements Constructor

is encountered, ⎕NEW calls the niladic constructor in the Base Class Parrot.egg0

Parrot.egg0 starts to execute and as soon as the line:

:Implements Constructor

is encountered, ⎕NEW calls the niladic constructor in the Base Class Bird.egg0. When the line:

:Implements Constructor

is encountered, ⎕NEW cannot call the niladic constructor in the Base Class (there is none) so the chain of Constructors ends. Then, as the State Indicator unwinds …

Bird.egg0 | executes | Desc←'Bird?'
Parrot.egg0 | executes | Desc,←'→Parrot'?
DomesticParrot.egg0 | executes | Desc,←'→DomesticParrot?'


Monadic Example

Base Constructors: Monadic Example

In the following example, DomesticParrot is derived from Parrot which is derived from Bird. They all share the Field Species (inherited from Bird) but only a DomesticParrot has a Field Name. Each of the 3 Classes has its own Constructor called egg.

:Class Bird
    :Field Public Species
    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      Species←spec
    ∇
    ...
:EndClass ⍝ Bird

:Class Parrot: Bird
    ∇ egg species
      :Access Public Instance
      :Implements Constructor :Base 'Parrot: ',species
    ∇
    ...
:EndClass ⍝ Parrot

:Class DomesticParrot: Parrot
    :Field Public Name
    ∇ egg(name species)
      :Access Public Instance
      :Implements Constructor :Base species
      ⎕DF Name←name
    ∇
    ...
:EndClass ⍝ DomesticParrot
      pol←⎕NEW DomesticParrot('Polly' 'Scarlet Macaw')
      pol.Name
Polly
      pol.Species
Parrot: Scarlet Macaw

Explanation

⎕NEW creates the new instance and runs the Constructor DomesticParrot.egg. The egg header splits the argument into two items name and species. As soon as the line:

:Implements Constructor :Base species

is encountered, ⎕NEW calls the Base Class constructor Parrot.egg, passing it the result of the expression to the right, which in this case is simply the value in species.

Parrot.egg starts to execute and as soon as the line:

:Implements Constructor :Base 'Parrot: ',species

is encountered, ⎕NEW calls its Base Class constructor Bird.egg, passing it the result of the expression to the right, which in this case is the character vector 'Parrot: ' catenated with the value in species.

Bird.egg assigns its argument to the Public Field Species.

At this point, the State Indicator would be:

       )SI
[#.[Instance of DomesticParrot]] #.Bird.egg[3]*
[constructor]
:base
[#.[Instance of DomesticParrot]] #.Parrot.egg[2]
[constructor]
:base
[#.[Instance of DomesticParrot]] #.DomesticParrot.egg[2]
[constructor]

Bird.egg then returns to Parrot.egg which returns to DomesticParrot.egg.

Finally, DomesticParrot.egg[3] is executed, which establishes Field Name and the Display Format (⎕DF) for the instance.


Destructors

A Destructor is a function that is called just before an Instance of a Class ceases to exist and is typically used to close files or release external resources associated with an Instance.

An Instance of a Class is destroyed when:

  • The Instance is expunged using ⎕EX or )ERASE.
  • A function, in which the Instance is localised, exits.

But be aware that a destructor will also be called if:

  • The Instance is re-assigned (see below)
  • The result of ⎕NEW is not assigned (the instance gets created then immediately destroyed).

APL creates (and then destroys) a new Instance as a result of a reference to a member of an empty Instance. The destructor is called after APL has obtained the appropriate value from the instance and no longer needs it.

The constructor function fails. Note that the Instance is actually created before the constructor is run (inside it), and if the constructor fails, the fledgling Instance is discarded. Note too that this means a destructor may need to deal with a partially constructed instance, so the code may need to check that resources were actually acquired, before releasing them.

On the execution of )CLEAR, )LOAD, ⎕LOAD or ⎕OFF.

Note that an Instance of a Class only disappears when the last reference to it disappears. For example, the sequence:

      I1←⎕NEW MyClass
      I2←I1
      )ERASE I1

will not cause the Instance of MyClass to disappear because it is still referenced by I2.

A Destructor is identified by the statement :Implements Destructor which must appear immediately after the function header in the Class script.

:Class Parrot
    ...
    ∇ kill
      :Implements Destructor
      'This Parrot is dead'
    ∇
    ...
:EndClass ⍝ Parrot
      pol←⎕NEW Parrot 'Scarlet Macaw'
      )ERASE pol
This Parrot is dead

Note that reassignment to pol causes the Instance referenced by pol to be destroyed and the Destructor invoked:

      pol←⎕NEW Parrot 'Scarlet Macaw'
      pol←⎕NEW Parrot 'Scarlet Macaw'
This Parrot is dead

If a Class inherits from another Class, the Destructor in its Base Class is automatically called after the Destructor in the Class itself.

So, if we have a Class structure:

      DomesticParrot => Parrot => Bird

containing the following Destructors (click here for a full listing of the relevant Classes):

:Class DomesticParrot: Parrot
    ...
    ∇ kill
      :Implements Destructor
      'This ',(⍕⎕THIS),' is dead'
    ∇
     ...
:EndClass ⍝ DomesticParrot

:Class Parrot: Bird
    ...
    ∇ kill
      :Implements Destructor
      'This Parrot is dead'
    ∇
    ...
:EndClass ⍝ Parrot

:Class Bird
    ...
    ∇ kill
      :Implements Destructor
      'This Bird is dead'
    ∇
    ...
:EndClass ⍝ Bird

Destroying an Instance of DomesticParrot will run the Destructors in DomesticParrot, Parrot and Bird and in that order.

      pol←⎕NEW DomesticParrot
      )CLEAR
This Polly is dead
This Parrot is dead
This Bird is dead
clear ws


Fields, Methods and Properties

A Class may contain Methods, Fields and Properties (commonly referred to together as Members) which are defined within the body of the Class script or are inherited from other Classes

Methods are regular APL defined functions, but with some special characteristics that control how they are called and where they are executed. D-fns may not be used as Methods.

Fields are just like APL variables. To get the Field value, you reference its name; to set the Field value, you assign to its name, and the Field value is stored in the Field. However, Fields differ from variables in that they possess characteristics that control their accessibility.

Properties are similar to APL variables. To get the Property value, you reference its name; to set the Property value, you assign to its name. However, Property values are actually accessed via PropertyGet and PropertySet functions that may perform all sorts of operations. In particular, the value of a Property is not stored in the Property and may be entirely dynamic.

All three types of member may be declared as Public or Private and as Instance or Shared.

Public members are visible from outside the Class and Instances of the Class, whereas Private members are only accessible from within.

Instance Members are unique to every Instance of the Class, whereas Shared Members are common to all Instances and Shared Members may be referenced directly on the Class itself.


Fields

A Field behaves just like an APL variable.

To get the value of a Field, you reference its name; to set the value of a Field, you assign to its name. Conceptually, the Field value is stored in the Field. However, Fields differ from variables in that they possess characteristics that control their accessibility.

A Field may be declared anywhere in a Class script by a :Field statement. This specifies:

  • the name of the Field
  • whether the Field is Public or Private
  • whether the Field is Instance or Shared
  • whether or not the Field is ReadOnly
  • optionally, an initial value for the Field.

Note that Triggers may be associated with Fields. See Trigger Fields for details.


Public Fields

A Public Field may be accessed from outside an Instance or a Class. Note that the default is Private.

Class DomesticParrot has a Name Field which is defined to be Public and Instance (by default).

:Class DomesticParrot: Parrot
    :Field Public Name

    ∇ egg nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇
    ...
:EndClass ⍝ DomesticParrot

The Name field is initialised by the Class constructor.

      pet←⎕NEW DomesticParrot'Polly'
      pet.Name
Polly

The Name field may also be modified directly:

      pet.Name←⌽pet.Name
      pet.Name
ylloP


Initialising Fields

A Field may be assigned an initial value. This can be specified by an arbitrary expression that is executed when the Class is fixed by the Editor or by ⎕FIX.

:Class DomesticParrot: Parrot
    :Field Public Name←'Dicky'
    :Field Public Talks←1

    ∇ egg nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇
    ...
:EndClass ⍝ DomesticParrot

Field Talks will be initialised to 1 in every instance of the Class.

      pet←⎕NEW DomesticParrot 'Dicky'

      pet.Talks
1
      pet.Name
Dicky

Note that if a Field is ReadOnly, this is the only way that it may be assigned a value.

See also: Shared Fields


Private Fields

A Private Field may only be referenced by code running inside the Class or an Instance of the Class. Furthermore, Private Fields are not inherited.

The ComponentFile Class has a Private Instance Field named tie that is used to store the file tie number in each Instance of the Class.

:Class ComponentFile
    :Field Private Instance tie

    ∇ Open filename
      :Implements Constructor
      :Access Public Instance
      :Trap 0
          tie←filename ⎕FTIE 0
      :Else
          tie←filename ⎕FCREATE 0
      :EndTrap
      ⎕DF filename,'(Component File)'
    ∇

As the field is declared to be Private, it is not accessible from outside an Instance of the Class, but is only visible to code running inside.

      F1←⎕NEW ComponentFile 'test1'
      F1.tie
VALUE ERROR
      F1.tie
     ∧


Shared Fields

If a Field is declared to be Shared, it has the same value for every Instance of the Class. Moreover, the Field may be accessed from the Class itself; an Instance is not required

The following example establishes a Shared Field called Months that contains abbreviated month names which are appropriate for the user's current International settings. It also shows that an arbitrarily complex statement may be used to initialise a Field.

:Class Example
    :Using System.Globalization
    :Field Public Shared ReadOnly Months←12↑(⎕NEW DateTimeFormatInfo).AbbreviatedMonthNames
:EndClass ⍝ Example

A Shared Field is not only accessible from an instance …

      EG←⎕NEW Example
      EG.Months
 Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov  Dec

… but also, directly from the Class itself.

      Example.Months
 Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov  Dec

Notice that in this case it is necessary to insert a :Using statement (or the equivalent assignment to ⎕USING) in order to specify the .Net search path for the DateTimeFormatInfo type. Without this, the Class would fail to fix.

You can see how the assignment works by executing the same statements in the Session:

      ⎕USING←'System.Globalization'
      12↑(⎕NEW DateTimeFormatInfo).AbbreviatedMonthNames
 Jan  Feb  Mar  Apr  May  Jun  Jul  Aug  Sep  Oct  Nov  Dec


Methods

Methods are implemented as regular defined functions, but with some special attributes that control how they are called and where they are executed.

A Method is defined by a contiguous block of statements in a Class Script. A Method begins with a line that contains a ∇, followed by a valid APL defined function header. The method definition is terminated by a closing ∇.

The behaviour of a Method is defined by an :Access control statement.

Public or Private

Methods may be defined to be Private (the default) or Public.

A Private method may only be invoked by another function that is running inside the Class namespace or inside an Instance namespace. The name of a Private method is not visible from outside the Class or an Instance of the Class.

A Public method may be called from outside the Class or an Instance of the Class.

Instance or Shared

Methods may be defined to be Instance (the default) or Shared.

An Instance method runs in the Instance namespace and may only be called via the instance itself. An Instance method has direct access to Fields and Properties, both Private and Public, in the Instance in which it runs.

A Shared method runs in the Class namespace and may be called via an Instance or via the Class. However, a Shared method that is called via an Instance does not have direct access to the Fields and Properties of that Instance.

Shared methods are typically used to manipulate Shared Properties and Fields or to provide general services for all Instances that are not Instance specific.

Overridable Methods

Instance Methods may be declared with :Access Overridable.

A Method declared as being Overridable is replaced in situ (i.e. within its own Class) by a Method of the same name that is defined in a higher Class which itself is declared with the Override keyword. See Superseding Base Class Methods.


Shared Methods

A Shared method runs in the Class namespace and may be called via an Instance or via the Class. However, a Shared method that is called via an Instance does not have direct access to the Fields and Properties of that Instance.

Class Parrot has a Speak method that does not require any information about the current Instance, so may be declared as Shared.

:Class Parrot:Bird

    ∇ R←Speak times
      :Access Public Shared
      R←⍕times⍴⊂'Squark!'
    ∇

:EndClass ⍝ Parrot
      wild←⎕NEW Parrot
      wild.Speak 2
 Squark!  Squark!

Note that Parrot.Speak may be executed directly from the Class and does not in fact require an Instance.

      Parrot.Speak 3
 Squark  Squark  Squark


Instance Methods

An Instance method runs in the Instance namespace and may only be called via the instance itself. An Instance method has direct access to Fields and Properties, both Private and Public, in the Instance in which it runs.

Class DomesticParrot has a Speak method defined to be Public and Instance. Where Speak refers to Name, it obtains the value of Name in the current Instance.

Note too that DomesticParrot.Speak supersedes the inherited Parrot.Speak.

:Class DomesticParrot: Parrot
    :Field Public Name

    ∇ egg nm
      :Access Public
      :Implements Constructor
      Name←nm
    ∇

    ∇ R←Speak times
      :Access Public Instance
      R←⊂Name,', ',Name
      R←↑R,times⍴⊂' Who's a pretty boy,then!'
    ∇

:EndClass ⍝ DomesticParrot
      pet←⎕NEW DomesticParrot'Polly'
      pet.Speak  3
Polly, Polly
 Who's a pretty boy,then!
 Who's a pretty boy,then!
 Who's a pretty boy,then!

      bil←⎕NEW  DomesticParrot'Billy'
      bil.Speak  1
Billy, Billy
 Who's a pretty boy,then!


Superseding Base Class Methods

Normally, a Method defined in a higher Class supersedes the Method of the same name that is defined in its Base Class, but only for calls made from above or within the higher Class itself (or an Instance of the higher Class). The base method remains available in the Base Class and is invoked by a reference to it from within the Base Class. This behaviour can be altered using the Overridable and Override key words in the :Access statement but only applies to Instance Methods.

If a Public Instance method in a Class is marked as Overridable, this allows a Class which derives from the Class with the Overridable method to supersede the Base Class method in the Base Class, by providing a method which is marked Override. The typical use of this is to supersede code in the Base Class which handles an event, with a method provided by the derived Class.

For example, the base class might have a method which is called if any error occurs in the base class:

     ∇ ErrorHandler
[1]    :Access Public Overridable
[2]    ⎕←↑⎕DM
     ∇

In your derived class, you might supersede this by a more sophisticated error handler, which logs the error to a file:

     ∇ ErrorHandler;TN
[1]    :Access Public Override
[2]    ⎕←↑⎕DM
[3]    TN←'ErrorLog'⎕FSTIE 0
[4]    ⎕DM ⎕FAPPEND TN
[5]    ⎕FUNTIE TN
     ∇

If the derived class had a function which was not marked Override, then function in the derived class which called ErrorHandler would call the function as defined in the derived class, but if a function in the base class called ErrorHandler, it would still see the base class version of this function. With Override specified, the new function supersedes the function as seen by code in the base class. Note that different derived classes can specify different Overrides.

In C#, Java and some other compiled languages, the term Virtual is used in place of Overridable, which is the term used by Visual Basic and Dyalog APL.


Properties

A Property behaves in a very similar way to an ordinary APL variable. To obtain the value of a Property, you simply reference its name. To change the value of a Property, you assign a new value to the name.

However, under the covers, a Property is accessed via a Property Get function and its value is changed via a Property Set function.

Furthermore, Properties may be defined to allow partial (indexed) retrieval and assignment to occur.

There are three types of Property, namely Simple, Numbered and Keyed.

  • A Simple Property is one whose value is accessed (by APL) in its entirety and re-assigned (by APL) in its entirety.
  • A Numbered Property behaves like an array (conceptually a vector) which is only ever partially accessed and set (one element at a time) via indices. The Numbered Property is designed to allow APL to perform selections and structural operations on the Property.
  • A Keyed Property is similar to a Numbered Property except that its elements are accessed via arbitrary keys instead of indices.

The following cases illustrate the difference between Simple and Numbered Properties.

If Instance MyInst has a Simple Property Sprop and a Numbered Property Nprop, the expressions

      X←MyInst.SProp
      X←MyInst.SProp[2]

both cause APL to call the PropertyGet function to retrieve the entire value of Sprop. The second statement subsequently uses indexing to extract just the second element of the value.

Whereas, the expression:

      X←MyInst.NProp[2]

causes APL to call the PropertyGet function with an additional argument which specifies that only the second element of the Property is required. Moreover, the expression:

      X←MyInst.NProp

causes APL to call the PropertyGet function successively, for every element of the Property.

A Property is defined by a :Property ... :EndProperty section in a Class Script.

Within the body of a Property Section there may be:

  • one or more :Access statements
  • a single PropertyGet function.
  • a single PropertySet function
  • a single PropertyShape function


Simple Instance Property

Simple Instance Properties

A Simple Instance Property is one whose value is accessed (by APL) in its entirety and re-assigned (by APL) in its entirety. The following examples are taken from the ComponentFile Class Class.

The Simple Property Count returns the number of components on a file.

    :Property Count
    :Access Public Instance
        ∇ r←get
          r←¯1+2⊃⎕FSIZE tie
        ∇
    :EndProperty ⍝ Count
      F1←⎕NEW ComponentFile 'test1'
      F1.Append'Hello World'
1
      F1.Count
1
      F1.Append 42
2
      F1.Count
2

Because there is no set function defined, the Property is read-only and attempting to change it causes SYNTAX ERROR.

      F1.Count←99
SYNTAX ERROR
      F1.Count←99
     ∧

The Access Property has both get and set functions which are used, in this simple example, to get and set the component file access matrix.

         :Property
          Access :Access
        Public
        Instance ∇ r←get
          r←⎕FRDAC
          tie ∇
              ∇setam;mat;OKmat←am.NewValue:Trap0OK←(2=⍴⍴mat)∧(3=2⊃⍴mat)∧∧/,mat=⌊mat
          :Else
              OK←0
          :EndTrap
          'bad arg'⎕SIGNAL(~OK)/11
          mat ⎕FSTAC tie
        ∇
    :EndProperty ⍝ Access

Note that the set function must be monadic. Its argument, supplied by APL, will be an Instance of PropertyArguments. This is an internal Class whose NewValue field contains the value that was assigned to the Property.

Note that the set function does not have to accept the new value that has been assigned. The function may validate the value reject or accept it (as in this example), or perform whatever processing is appropriate.

      F1←⎕NEW ComponentFile 'test1'
      ⍴F1.Access
0 3
        F1.Access←3 3⍴28 2105 16385 0 2073 16385 31 ¯1 0
      F1.Access
28 2105 16385
 0 2073 16385
31   ¯1     0

      F1.Access←'junk'
bad arg
      F1.Access←'junk'
     ∧

      F1.Access←1 2⍴10
bad arg
      F1.Access←1 2⍴10
     ∧


Simple Shared Properties

The ComponentFile Class specifies a Simple Shared Property named Files which returns the names of all the Component Files in the current directory.

The previous examples have illustrated the use of Instance Properties. It is also possible to define Shared properties.

A Shared property may be used to handle information that is relevant to the Class as a whole, and which is not specific to any a particular Instance.

    :Property Files
    :Access Public Shared
        ∇ r←get
          r←⎕FLIB''
        ∇
    :EndProperty

Note that ⎕FLIB (invoked by the Files get function) does not report the names of tied files.

      F1←⎕NEW ComponentFile 'test1'
      ⎕EX'F1'
      F2←⎕NEW ComponentFile 'test2'
      F2.Files ⍝ NB ⎕FLIB does not report tied files
test1
      ⎕EX'F2'

Note that a Shared Property may be accessed from the Class itself. It is not necessary to create an Instance first.

      ComponentFile.Files
test1
test2


Numbered Properties

A Numbered Property behaves like an array which is only ever partially accessed and set (one element at a time) via indices.

To implement a Numbered Property, you must specify a PropertyShape function and either or both a PropertyGet and PropertySet function.

When an expression references or makes an assignment to a Numbered Property, APL first calls its PropertyShape function which returns the dimensions of the Property. Note that the shape of the result of this function determines the rank of the Property, except that a scalar result implies a vector.

Apl then calls the PropertyGet or PropertySet function once for each element in the index set, supplying an argument of type PropertyArguments.

Note that when a numbered property is accessed, APL is responsible for validating the indices and ensuring that the value assigned or retrieved is a scalar. When PropertySet is called, NewValue will always be a scalar, and APL will validate that you return a scalar as the result of a PropertyGet.

If the expression references or assigns the entire Property (without indexing) APL generates a set of indices for every element of the Property and calls the PropertyGet or PropertySet function successively for every element in the Property. Future versions of APL may provide ways to specify that numbered accessor functions work one more than one element at a time.

Note that APL generates a RANK ERROR if an index contains the wrong number of elements or an INDEX ERROR if an index is out of bounds.


Numbered Properties (Example)

The ComponentFile Class Class specifies a Numbered Property named Component which represents the contents of a specified component on the file.

    :Property Numbered Component
    :Access Public Instance
        ∇ r←shape
          r←¯1+2⊃⎕FSIZE tie
        ∇
        ∇ r←get arg
          r←⊂⎕FREAD tie arg.Indexers
        ∇
        ∇ set arg
          (⊃arg.NewValue) ⎕FREPLACE tie,arg.Indexers
        ∇
    :EndProperty
      F1←⎕NEW ComponentFile 'test1'
      F1.Append¨(⍳5)×⊂⍳4
1 2 3 4 5
      F1.Count
5
      F1.Component[4]
 4 8 12 16
      4⊃F1.Component
4 8 12 16
      (⊂4 3)⌷F1.Component
 4 8 12 16  3 6 9 12

Referencing a Numbered Property in its entirety causes APL to call the get function successively for every element.

      F1.Component
 1 2 3 4  2 4 6 8  3 6 9 12  4 8 12 16  5 10 15 20
      ((⊂4 3)⌷F1.Component)←'Hello' 'World'
      F1.Component[3]
 World

Attempting to access a Numbered Property with inappropriate indices generates an error:

      F1.Component[6]
INDEX ERROR
      F1.Component[6]
     ∧
      F1.Component[1;2]
RANK ERROR
      F1.Component[1;2]
     ∧


The Default Property

A single Numbered Property may be identified as the Default Property for the Class.

If a Class has a Default Property, indexing with the ⌷ primitive function and [...] indexing may be applied to the Property directly via a reference to the Class or Instance.

The Numbered Property example of the ComponentFile Class Class can be extended by adding the control word Default to the :Property statement for the Component Property.

Indexing may now be applied directly to the Instance F1. In essence, F1[n] is simply shorthand for F1.Component[n] and n⌷F1 is shorthand for n⌷F1.Component

    :Property Numbered Default Component
    :Access Public Instance
        ∇ r←shape
          r←¯1+2⊃⎕FSIZE tie
        ∇
        ∇ r←get arg
          r←⊂⎕FREAD tie arg.Indexers
        ∇
        ∇ set arg
           (⊃arg.NewValue) ⎕FREPLACE tie,arg.Indexers
        ∇
    :EndProperty
      F1←⎕NEW ComponentFile 'test1'
      F1.Append¨(⍳5)×⊂⍳4
1 2 3 4 5
      F1.Count
5
      F1[4]
 4 8 12 16
      (⊂4 3)⌷F1
 4 8 12 16  3 6 9 12
      ((⊂4 3)⌷F1)←'Hello' 'World'
      F1[3]
 World

Note however that this feature applies only to indexing.

      4⊃F1
DOMAIN ERROR
      4⊃F1
     ∧


Keyed Properties

A Keyed Property is similar to a Numbered Property except that it may only be accessed by indexing (so-called square-bracket indexing) and indices are not restricted to integers but may be arbitrary arrays.

To implement a Keyed Property, only a get and/or a set function are required. APL does not attempt to validate or resolve the specified indices in any way, so does not require the presence of a shape function for the Property.

However, APL does check that the rank and lengths of the indices correspond to the rank and lengths of the array to the right of the assignment (for an indexed assignment) and the array returned by the get function (for an indexed reference). If the rank or shape of these arrays fails to conform to the rank or shape of the indices, APL will issue a RANK ERROR or LENGTH ERROR.

Note too that indices may not be elided. If KProp is a Keyed Property of Instance I1, the following expressions would all generate NONCE ERROR.

      I1.KProp
      I1.KProp[]←10
      I1.KProp[;]←10
      I1.KProp['One' 'Two';]←10
      I1.KProp[;'One' 'Two']←10

When APL calls a monadic get or a set function, it supplies an argument of type PropertyArguments.


Keyed Property Example One

Keyed Property Example 1

The Sparse2 Class illustrates the implementation and use of a Keyed Property.

Sparse2 represents a 2-dimensional sparse array each of whose dimensions are indexed by arbitrary character keys. The sparse array is implemented as a Keyed Property named Values. The following expressions show how it might be used.

      SA1←⎕NEW Sparse2
      SA1.Values[⊂'Widgets';⊂'Jan']←100
      SA1.Values[⊂'Widgets';⊂'Jan']
100
      SA1.Values['Widgets' 'Grommets';'Jan' 'Mar' 'Oct']←10×2 3⍴⍳6
      SA1.Values['Widgets' 'Grommets';'Jan' 'Mar' 'Oct']
10 20 30
40 50 60
      SA1.Values[⊂'Widgets';'Jan' 'Oct']
10 30
      SA1.Values['Grommets' 'Widgets';⊂'Oct']
60
30

Internally, Sparse2 maintains a list of keys and a list of values which are initialised to empty arrays by its constructor.

When an indexed assignment is made, the set function receives a list of keys (indices) in arg.Indexer and values in arg.NewValue. The function updates the values of existing keys, and adds new keys and their values to the internal lists.

When an indexed reference is made, the get function receives a list of keys (indices) in arg.Indexer. The function uses these keys to retrieve the corresponding values, inserting 0s for non-existent keys.

Note that in the expression:

      SA1.Values['Widgets' 'Grommets';'Jan' 'Mar' 'Oct']

the structure of arg.Indexer is:

.→-----------------------------------------------.
| .→---------------------. .→------------------. |
| | .→------. .→-------. | | .→--. .→--. .→--. | |
| | |Widgets| |Grommets| | | |Jan| |Mar| |Oct| | |
| | '-------' '--------' | | '---' '---' '---' | |
| '∊---------------------' '∊------------------' |
'∊-----------------------------------------------'


Keyed Property Example Two

Keyed Properties (Example 2)

A second example of a Keyed Property is provided by the KeyedFile Class which is based upon the ComponentFile Class used previously.

:Class KeyedFile: ComponentFile
    :Field Public Keys
    ⎕ML←0

    ∇ Open filename
      :Implements Constructor :Base filename
      :Access Public Instance
      :If Count>0
          Keys←{⊃⍵⊃⎕BASE.Component}¨⍳Count
      :Else
          Keys←0⍴⊂''
      :EndIf
    ∇

    :Property Keyed Component
    :Access Public Instance
        ∇ r←get arg;keys;sink
          keys←,⊃arg.Indexers
          ⎕SIGNAL(~∧/keys∊Keys)/3
          r←{2⊃⍵⊃⎕BASE.Component}¨Keys⍳keys
        ∇
        ∇ set arg;new;keys;vals
          vals←arg.NewValue
          keys←⊃arg.Indexers
          ⎕SIGNAL((⍴keys)≠⍴vals)/5
          :If ∨/new←~keys∊Keys
              sink←Append¨↓⍉↑(⊂new)/¨keys vals
              Keys,←new/keys
              keys vals/⍨←⊂~new
          :EndIf
          :If 0<⍴keys
              Replace¨↓⍉↑(Keys⍳keys)(↓⍉↑keys vals)
          :EndIf
        ∇
    :EndProperty

:EndClass ⍝ Class KeyedFile
      K1←⎕NEW KeyedFile 'ktest'
      K1.Count
0
      K1.Component[⊂'Pete']←42
      K1.Count
1
      K1.Component['John' 'Geoff']←(⍳10)(3 4⍴⍳12)
      K1.Count
3
      K1.Component['Geoff' 'Pete']
 1  2  3  4  42
 5  6  7  8
 9 10 11 12
      K1.Component['Pete' 'Morten']←(3 4⍴'∘')(⍳⍳3)
      K1.Count
4
      K1.Component['Morten' 'Pete' 'John']
  1 1 1  1 1 2  1 1 3   ∘∘∘∘  1 2 3 4 5 6 7 8 9 10
  1 2 1  1 2 2  1 2 3   ∘∘∘∘
                        ∘∘∘∘


Interfaces

An Interface is defined by a Script that contains skeleton declarations of Properties and/or Methods. These members are only place-holders; they have no specific implementation; this is provided by each of the Classes that support the Interface.

An Interface contains a collection of methods and properties that together represents a protocol that an application must follow in order to manipulate a Class in a particular way.

An example might be an Interface called Icompare that provides a single method (Compare) which compares two Instances of a Class, returning a value to indicate which of the two is greater than the other. A Class that implements Icompare must provide an appropriate Compare method, but every Class will have its own individual version of Compare. An application can then be written that sorts Instances of any Class that supports the ICompare Interface.

An Interface is implemented by a Class if it includes the name of the Interface in its :Class statement, and defines a corresponding set of the Methods and Properties that are declared in the Interface.

To implement a Method, a function defined in the Class must include a :Implements Method statement that maps it to the corresponding Method defined in the Interface:

      :Implements Method <InterfaceName.MethodName>

Furthermore, the syntax of the function (whether it be result returning, monadic or niladic) must exactly match that of the method described in the Interface. The function name, however, need not be the same as that described in the Interface.

Similarly, to implement a Property the type (Simple, Numbered or Keyed) and syntax (defined by the presence or absence of a PropertyGet and PropertySet functions) must exactly match that of the property described in the Interface. The Property name, however, need not be the same as that described in the Interface.


Interface Example

The Penguin Class example illustrates the use of Interfaces to implement multiple inheritance.

In this case, the Penguin Class derives from Animal but additionally supports the BirdBehaviour and FishBehaviour Interfaces, thereby inheriting members from both.

      Pingo←⎕NEW Penguin
      ⎕CLASS Pingo
  #.Penguin  #.FishBehaviour  #.BirdBehaviour    #.Animal
      (FishBehaviour ⎕CLASS Pingo).Swim
I can dive and swim like a fish
      (BirdBehaviour ⎕CLASS Pingo).Fly
Although I am a bird, I cannot fly
      (BirdBehaviour ⎕CLASS Pingo).Lay
I lay one egg every year
      (BirdBehaviour ⎕CLASS Pingo).Sing
Croak, Croak!


Including Namespaces in Classes

Including Namespaces

A Class may import methods from one or more plain Namespaces. This allows several Classes to share a common set of methods, and provides a degree of multiple inheritance.

To import methods from a Namespace NS, the Class Script must include a statement:

     :Include NS

When the Class is fixed by the editor or by ⎕FIX, all the defined functions and operators in Namespace NS are included as methods in the Class. The functions and operators which are brought in as methods from the namespace NS are treated exactly as if the source of each one had been included in the class script at the point of the :Include statement. For example, if a function/operator contains :Signature or :Access statements, these will be taken into account. Note that such declarations have no effect on a function/operator which is in an ordinary namespace.

D-fns and D-ops in NS are also included in the Class but as Private members, because D-fns and D-ops may not contain :Signature or :Access statements. Variables and Sub-namespaces in NS are not included.

Note that objects imported in this way are not actually copied, so there is no penalty incurred in using this feature. Additions, deletions and changes to the functions in NS are immediately reflected in the Class.

If there is a member in the Class with the same name as a function in NS, the Class member takes precedence and supersedes the function in NS.

Conversely, functions in NS will supersede members of the same name that are inherited from the Base Class, so the precedence is:

Class supersedes

Included Namespace, supersedes

Base Class

Any number of Namespaces may be included in a Class and the :Include statements may occur anywhere in the Class script. However, for the sake of readability, it is recommended that you have :Include statements at the top, given that any definitions in the script will supersede included functions and operators.


Including Namespaces - Example

In this example, Class Penguin inherits from Animal and includes functions from the plain Namespaces BirdStuff and FishStuff.

:Class Penguin: Animal
    :Include BirdStuff
    :Include FishStuff
:EndClass ⍝ Penguin

Namespace BirdStuff contains 2 functions, both declared as Public methods.

:Namespace BirdStuff
    ∇ R←Fly
      :Access Public Instance
      R←'Fly, Fly ...'
    ∇
    ∇ R←Lay
      :Access Public Instance
      R←'Lay, Lay ...'
    ∇
:EndNamespace ⍝ BirdStuff

Namespace FishStuff contain a single function, also declared as a Public method.

:Namespace FishStuff
    ∇ R←Swim
      :Access Public Instance
      R←'Swim, Swim ...'
    ∇
:EndNamespace ⍝ FishStuff
      Pingo←⎕NEW Penguin
      Pingo.Swim
Swim, Swim ...
      Pingo.Lay
Lay, Lay ...
      Pingo.Fly
Fly, Fly ...

This is getting silly - we all know that Penguin's can't fly. This problem is simply resolved by overriding the BirdStuff.Fly method with Penguin.Fly. We can hide BirdStuff.Fly with a Private method in Penguin that does nothing. For example:

:Class Penguin: Animal
    :Include BirdStuff
    :Include FishStuff
    ∇ Fly ⍝ Override BirdStuff.Fly
    ∇
:EndClass ⍝ Penguin
      Pingo←⎕NEW Penguin
      Pingo.Fly
VALUE ERROR
      Pingo.Fly
     ∧

or we can supersede it with a different Public method, as follows:

:Class Penguin: Animal
    :Include BirdStuff
    :Include FishStuff
    ∇ R←Fly ⍝ Override BirdStuff.Fly
      :Access Public Instance
      R←'Sadly, I cannot fly'
    ∇
:EndClass ⍝ Penguin
      Pingo←⎕NEW Penguin
      Pingo.Fly
Sadly, I cannot fly


Nested Classes

It is possible to define Classes within Classes (Nested Classes).

A Nested Class may be either Private or Public. This is specified by a :Access Statement, which must precede the definition of any Class contents. The default is Private.

A Public Nested Class is visible from outside its containing Class and may be used directly in its own right, whereas a Private Nested Class is not and may only be used by code inside the containing Class.

However, methods in the containing Class may return instances of Private Nested Classes and in that way expose them to the calling environment.


GolfService Example

The GolfService Example Class illustrates the use of nested classes.

GolfService was originally developed as a Web Service for Dyalog.Net and is one of the samples distributed in samples\asp.net\webservices. This version has been reconstructed as a stand-alone APL Class.

GolfService contains the following nested classes, all of which are Private.

GolfCourse | A Class that represents a Golf Course, having Fields Code and Name.
Slot | A Class that represents a tee-time or match, having Fields Time and Players. Up to 4 players may play together in a match.
Booking | A Class that represents a reservation for a particular tee-time at a particular golf course. This has Fields OK, Course, TeeTime and Message. The value of TeeTime is an Instance of a Slot Class.
StartingSheet | A Class that represents a day's starting-sheet at a particular golf course. It has Fields OK, Course, Date, Slots, Message. Slots is an array of Instances of Slot Class.

The GolfService constructor takes the name of a file in which all the data is stored. This file is initialised by method InitFile if it doesn't already exist.

      G←⎕NEW GolfService 'F:\HELP11.0\GOLFDATA'
      G
#.[Instance of GolfService]

The GetCourses method returns an array of Instances of the internal (nested) Class GolfCourse. Notice how the display form of each Instance is established by the GolfCourse constructor, to obtain the output display shown below.

      C.GetCourses
 St Andrews(1)  Hindhead(2)  Basingstoke(3)

All of the dates and times employ instances of the .Net type System.DateTime, and the following statements just set up some temporary variables for convenience later.

      ⎕←Tomorrow←(⎕NEW DateTime(3↑⎕TS)).AddDays 1
31/03/2006 00:00:00
      ⎕←TomorrowAt7←Tomorrow.AddHours 7
31/03/2006 07:00:00

The MakeBooking method takes between 4 and 7 parameters viz.

  • the code for the golf course at which the reservation is required
  • the date and time of the reservation
  • a flag to indicate whether or not the nearest available time will do
  • and a list of up to 4 players who wish to book that time.

The result is an Instance of the internal Class Booking. Once again, ⎕DF is used to make the default display of these Instances meaningful. In this case, the reservation is successful.

      G.MakeBooking 2 TomorrowAt7 1 'Pete' 'Tiger'
 Hindhead(2)   31/03/2006 07:00:00   Pete  Tiger    OK

Bob, Arnie and Jack also ask to play at 7:00 but are given the 7:10 tee-time instead (4-player restriction).

      G.MakeBooking 2 TomorrowAt7 1 'Bob' 'Arnie' 'Jack'
 Hindhead(2)   31/03/2006 07:10:00   Bob  Arnie  Jack    OK

However, Pete and Tiger are joined at 7:00 by Dave and Al.

      G.MakeBooking 2 TomorrowAt7 1 'Dave' 'Al'
 Hindhead(2)   31/03/2006 07:00:00   Pete  Tiger  Dave  Al    OK

Up to now, all bookings have been made with the tee-time flexibility flag set to 1. Inflexible Jim is only interested in playing at 7:00 …

      G.MakeBooking 2 TomorrowAt7 0 'Jim'
 Hindhead(2)  31/03/2006 07:00:00  Not available

… so his reservation fails (4-player restriction).

Finally the GetStartingSheet method is used to obtain an Instance of the internal Class StartingSheet for the given course and day.

      G.GetStartingSheet 2 Tomorrow
  Hindhead(2)  31/03/2006 00:00:00
  31/03/2006 07:00:00   Pete  Tiger  Dave  Al
  31/03/2006 07:10:00   Bob  Arnie  Jack
  31/03/2006 07:20:00
  ....


Namespace Script

A Namespace Script is a script that begins with a :Namespace statement and ends with a :EndNamespace statement. When a Namespace Script is fixed, it establishes an entire namespace that may contain other namespaces, functions, variables and classes.

The names of Classes defined within a Namespace Script which are parents, children, or siblings are visible both to one another and to code and expressions defined in the same script, regardless of the namespace hierarchy within it. Names of Classes which are nieces or nephews and their descendants are however not visible.

For example:

:Namespace a
    d←⎕NEW a1
    e←⎕NEW bb2

    :Class a1
        ∇ r←foo
          :Access Shared Public
          r←⎕NEW¨b1 b2
        ∇
    :EndClass ⍝ a1

    ∇ r←goo
      r←a1.foo
    ∇

    ∇ r←foo
      r←⎕NEW¨b1 b2
    ∇

    :Namespace b
        :Class b1
        :EndClass ⍝ b1
        :Class b2
            :Class bb2
            :EndClass ⍝ bb2
        :EndClass ⍝ b2
    :EndNamespace ⍝ b
:EndNamespace ⍝ a
      a.d
#.a.[a1]
      a.e
#.a.[bb2]
      a.foo
 #.a.[b1]  #.a.[b2]

Note that the names of Classes b1 (a.b.b1) and b2 (a.b.b2) are not visible from their “uncle” a1 (a.a1).

      a.goo
VALUE ERROR
foo[2] r←⎕NEW¨b1 b2

Notice that Classes in a Namespace Script are fixed before other objects (hence the assignments to d and e are evaluated after Classes a1 and bb2 are fixed), although the order in which Classes themselves are defined is still important if they reference one another during initialisation.

Warning: If you introduce new objects of any type (functions, variables, or classes) into a namespace defined by a script by any other means than editing the script, then these objects will be lost the next time the script is edited and fixed. Also, if you modify a variable which is defined in a script, the script will not be updated.

A practical example using :Namespace is given in the next topic.


Namespace Script Example

The DiaryStuff example illustrates the manner in which classes may be defined and used in a Namespace script.

DiaryStuff defines two Classes named Diary and DiaryEntry.

Diary contains a (private) Field named entries, which is simply a vector of instances of DiaryEntry. These are 2-element vectors containing a .NET DateTime object and a description.

The entries Field is initialised to an empty vector of DiaryEntry instances which causes the invocation of the default constructor DiaryEntry.Make0 when Diary is fixed. See Empty Arrays of Instances for further explanation.

The entries Field is referenced through the Entry Property, which is defined as the Default Property. This allows individual entries to be referenced and changed using indexing on a Diary Instance.

Note that DiaryEntry is defined in the script first (before Diary) because it is referenced by the initialisation of the Diaries.entries Field

Create a new instance of Diary.

      D←⎕NEW DiaryStuff.Diary

Add a new entry "meeting with John at 09:00 on April 30th"

      D.Add(2006 4 30 9 0)'Meeting with John'
 30/04/2006 09:00:00  Meeting with John

Add another diary entry "Dentist at 10:00 on April 30th".

      D.Add(2006 4 30 10 0)'Dentist'
 30/04/2006 10:00:00  Dentist

One of the benefits of the Namespace Script is that Classes defined within it (which are typically related) may be used independently, so we can create a stand-alone instance of DiaryEntry; "Doctor at 11:00"…

      Doc←⎕NEW DiaryStuff.DiaryEntry((2006 4 30 11 0)'Doctor')
      Doc
 30/04/2006 11:00:00  Doctor

… and then use it to replace the second Diary entry with indexing:

      D[2]←Doc

and just to confirm it is there …

      D[2]
 30/04/2006 11:00:00  Doctor

What am I doing on the 30th ?

      D.DoingOn 2006 4 30
  30/04/2006 09:00:00  Meeting with John    30/04/2006 11:00:00  Doctor

Remove the 11:00 appointment …

      D.Remove 2006 4 30 11 0
1

and the complete Diary is …

      ⌷D
  30/04/2006 09:00:00  Meeting with John


Access Statement

:Access <Private|Public><Instance|Shared>Overridable><Override>
:Access <WebMethod>

The :Access statement is used to specify characteristics for Classes, Properties and Methods.

Element | Description
Private|Public | Specifies whether or not the (nested) Class, Property or Method is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | For a Field, specifies if there is a separate value of the Field in each Instance of the Class, or if there is only a single value that is shared between all Instances. For a Property or Method, specifies whether the code associated with the Property or Method runs in the Class or Instance.
WebMethod | Applies only to a Method and specifies that the method is exported as a web method. This applies only to a Class that implements a Web Service.
Overridable | Applies only to an Instance Method and specifies that the Method may be overridden by a Method in a higher Class. See below.
Override | Applies only to an Instance Method and specifies that the Method overrides the corresponding Overridable Method defined in the Base Class. See below.

Overridable/Override

Normally, a Method defined in a higher Class replaces a Method of the same name that is defined in its Base Class, but only for calls made from above or within the higher Class itself (or an Instance of the higher Class). The base method remains available in the Base Class and is invoked by a reference to it from within the Base Class.

However, a Method declared as being Overridable is replaced in situ (i.e. within its own Class) by a Method of the same name in a higher Class if that Method is itself declared with the Override keyword. For further information, see Superseding Base Class Methods.

Nested Classes

The :Access statement is also used to control the visibility of one Class that is defined within another (a nested Class). A Nested Class may be either Private or Public. Note that the :Access Statement must precede the definition of any Class contents..

A Public Nested Class is visible from outside its containing Class and may be used directly in its own right, whereas a Private Nested Class is not and may only be used by code inside the containing Class.

However, methods in the containing Class may return instances of Private Nested Classes and in that way expose them to the calling environment.

WebMethod

Note that :Access WebMethod is equivalent to:

:Access Public
:Attribute System.Web.Services.WebMethodAttribute


Interface Statement

:Interface <interface name>
...
:EndInterface

An Interface is defined by a Script containing skeleton declarations of Properties and/or Methods. The script must begin with a :Interface Statement and end with a :EndInterface Statement.

An Interface may not contain Fields.

The Properties and Methods defined in an Interface may not contain :Access Statements as these will be specified by the :Access declarations within the Classes that implement the Interface.


:Class Statement

:Class <class name><:base class name> <,interface name....>
:Include <namespace>
...
:EndClass

A class script begins with a :Class statement and ends with a :EndClass statement. The elements that comprise the :Class statement are as follows:

Element | Description
class name | Optionally, specifies the name of the Class, which must conform to the rules governing APL names.
base class name | Optionally specifies the name of a Class from which this Class is derived and whose members this Class inherits.
interface name | The names of one or more Interfaces which this Class supports.

A Class may import methods defined in separate plain Namespaces with one or more :Include statements. For further details, see Including Namespaces in Classes

Examples:

The following statements define a Class named Penguin that derives from (is based upon) a Class named Animal and which supports two Interfaces named BirdBehaviour and FishBehaviour.

:Class Penguin: Animal,BirdBehaviour,FishBehaviour
...
:EndClass

The following statements define a Class named Penguin that derives from (is based upon) a Class named Animal and includes methods defined in two separate Namespaces named BirdStuff and FishStuff.

:Class Penguin: Animal
:Include BirdStuff
:Include FishStuff
...
:EndClass


Namespace Statement

:Namespace <namespace name>
...
:EndNamespace

A Namespace Script may be used to define an entire namespace containing other namespaces, functions, variables and Classes.

A Namespace script must begin with a :Namespace statement and end with a :EndNamespace statement.

Sub-namespaces, which may be nested, are defined by pairs of :Namespace and :EndNamespace statements within the Namespace script.

Classes are defined by pairs of :Class and :EndClass statements within the Namespace script, and these too may be nested.

The names of Classes defined within a Namespace Script are visible both to one another and to code and expressions defined in the same script, regardless of the namespace hierarchy within it.

A Namespace script is therefore particularly useful to group together Classes that refer to one another where the use of nested classes is inappropriate.


Implements Statement

:Implements Constructor <[:Base expr]>
:Implements Destructor
:Implements Method <InterfaceName.MethodName>
:Implements Trigger <name1><,name2,name3,...>

The :Implements statement identifies the function to be one of the following types.

Element | Description
Constructor | Specifies that the function is a Class Constructor.
:Base expr | Specifies that the Base Constructor be called with the result of the expression expr as its argument.
Destructor | Specifies that the function is a Class Destructor.
Method | Specifies that the function implements the Method MethodName whose syntax is specified by Interface InterfaceName.
Trigger | Identifies the function as a Trigger Function which is activated by changes to variable name1, name2, etc.


Using Statement

:Using <NameSpace[,Assembly]>

This statement specifies a .NET namespace that is to be searched to resolve unqualified names of .NET types referenced by expressions in the Class.

Element | Description
NameSpace | Specifies a .NET namespace.
Assembly | Specifies the Assembly in which NameSpace is located. If the Assembly is defined in the global assembly cache, you need only specify its name. If not, you must specify a full or relative pathname.

If the Microsoft .Net Framework is installed, the System namespace in mscorlib.dll is automatically loaded when Dyalog APL starts. To access this namespace, it is not necessary to specify the name of the Assembly.

When the class is fixed, ⎕USING is inherited from the surrounding space. Each :Using statement appends an element to ⎕USING, with the exception of :Using with no argument:

If you omit <Namespace>, this is equivalent to clearing ⎕USING, which means that no .NET namespaces will be searched (unless you follow this statement with additional :Using statements, each of which will append to ⎕USING).

To set ⎕USING, to a single empty character vector, which only allows references to fully qualified names of classes in mscorlib.dll, you must write:

      :Using , (note the presence of the comma)

or

      :Using ,mscorlib.dll

(i.e. specify an empty namespace name followed by no assembly, or followed by the default assembly, which is always loaded.


Attribute Statement

:Attribute <Name> [ConstructorArgs]

This statement is used to attach .Net Attributes to a Class or a Method. Attributes are descriptive tags that provide additional information about programming elements. Attributes are not used by Dyalog APL but other applications can refer to the extra information in attributes to determine how these items can be used. Attributes are saved with the metadata of Dyalog APL .NET assemblies.

Element | Description
Name | The name of a .NET attribute
ConstructorArgs | Optional arguments for the Attribute constructor.

Example

The following Class has SerializableAttribute and CLSCompliantAttribute attributes attached to the Class as a whole, and ObsoleteAttribute attributes attached to Methods foo and goo within it.

:Class c1
:using System
    :attribute SerializableAttribute
    :attribute CLSCompliantAttribute 1

    ∇ foo(p1 p2)
      :Access public instance
      :Signature foo Object,Object
      :Attribute ObsoleteAttribute
    ∇

    ∇ goo(p1 p2)
      :Access public instance
      :Signature foo Object,Object
      :Attribute ObsoleteAttribute 'Don''t use this' 1

    ∇

:EndClass ⍝ c1

When this Class is exported as a .Net Class, the attributes are saved in its metadata as shown by ILDASM.

For example, Visual Studio will warn developers if they make use of a member which has the ObsoleteAttribute.


:Field Statement

:Field <Private|Public> <Instance|Shared> <ReadOnly> FieldName <← expr>

A :Field statement is a single statement whose elements are as follows:

Element | Description
Private|Public | Specifies whether or not the Field is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | Specifies if there is a separate value of the Field in each Instance of the Class, or if there is only a single value that is shared between all Instances.
ReadOnly | If specified, this keyword prevents the value in the Field from being changed after initialisation.
FieldName | Specifies the name of the Field (mandatory).
← expr | Specifies an initial value for the Field.

Examples:

The following statement defines a Field called Name. It is (by default), an Instance Field so every Instance of the Class has a separate value. It is a Public Field and so may be accessed (set or retrieved) from outside an Instance.

:Field Public Name

The following statement defines a Field called Months.

:Field Shared ReadOnly Months←12↑(⎕NEW DateTimeFormatInfo).AbbreviatedMonthNames

Months is a Shared Field so there is just a single value that is the same for every Instance of the Class. It is (by default), a Private Field and may only be referenced by code running in an Instance or in the Class itself. Furthermore, it is ReadOnly and may not be altered after initialisation.

It's initial value is calculated by an expression that obtains the short month names that are appropriate for the current locale using the .Net Type DateTimeFormatInfo.

Note that Fields are initialised when a Class script is fixed by the editor or by ⎕FIX. If the evaluation of expr causes an error (for example, a VALUE ERROR), an appropriate message will be displayed in the Status Window and ⎕FIX will fail with a DOMAIN ERROR.

In the second example above, the expression will only succeed if ⎕USING is set to the appropriate path, in this case System.Globalization.

Note that a ReadOnly Field may only be assigned a value by its :Field statement.


:Property Statement

:Property Section

A Property is defined by a :Property ... :EndProperty section in a Class Script.

The syntax of the :Property Statement, and its optional :Access statement is as follows:

:Property <Simple|Numbered|Keyed> <Default> Name <,name,..>
:Access <Private|Public><Instance|Shared>
Element | Description
Name | Specifies the name of the Property by which it is accessed. Additional Properties, sharing the same PropertyGet and/or PropertySet functions, and the same access behaviour may be specified by a comma-separated list of names.
Simple|Numbered|Keyed
 Specifies the type of Property (see below). The default is Simple.
Default
 Specifies that this Property acts as the default property for the Class when indexing is applied directly to an Instance of the Class.
Private|Public
 Specifies whether or not the Property is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | Specifies if there is a separate value of the Property in each Instance of the Class, or if there is only a single value that is shared between all Instances.

A Simple Property is one whose value is accessed (by APL) in its entirety and re-assigned (by APL) in its entirety.

A Numbered Property behaves like an array (conceptually a vector) which is only ever partially accessed and set (one element at a time) via indices.

A Keyed Property is similar to a Numbered Property except that its elements are accessed via arbitrary keys instead of indices.

Numbered and Keyed Properties are designed to allow APL to perform selections and structural operations on the Property.

Within the body of a Property Section there may be:

  • one or more :Access statements
  • a single PropertyGet function.
  • a single PropertySet function
  • a single PropertyShape function

The three functions are identified by case-independent names Get, Set and Shape.

When a Class is fixed by the Editor or by ⎕FIX, APL checks the validity of each Property section and the syntax of PropertyGet, PropertySet and PropertyShape functions within them. If anything is wrong, an error is generated and the Class is not fixed.


PropertyArguments Class

Where appropriate, APL supplies the PropertyGet and PropertySet functions with an argument that is an instance of the internal class PropertyArguments.

PropertyArguments has 2-3 read-only Fields which are as follows:

Name | The name of the property. This is useful when one function is handling several properties.
NewValue | Array containing the new value for the Property or for selected element(s) of the property as specified by Indexers.
Indexers | If present, an array that identifies the element(s) of the Property that are to be referenced or assigned.


:PropertyGet Function Syntax

PropertyGet Syntax: | R←Get
 | R←Get ipa

:The name of the PropertyGet function must be GCet, but is case-independent. For example, get, GCet, gEt and GET are all valid names for the PropertyGet function

The PropertyGet function must be result returning. For a Simple Property, it may be monadic or niladic. For a Numbered or Keyed Property it must be monadic.

For a Simple Property, the result R may be any array. For a Numbered Property, the result R must be a scalar. For a Keyed Property, R must conform to the rank and shape specified by ipa.Indexers.

If monadic, ipa is an instance of the internal class PropertyArguments

In all cases, ipa.Name contains the name of the Property being referenced and NewValue is undefined (VALUE ERROR).

If the Property is Simple, ipa.Indexers is undefined (VALUE ERROR).

If the Property is Numbered, ipa.Indexers is an integer vector of the same length as the rank of the property (as implied by the result of the Shape function) that identifies a single element of the Property whose value is to be obtained. In this case, R must be scalar.

If the Property is Keyed, ipa.Indexers is a vector containing the arrays that were specified within the square brackets in the reference expression. Specifically, ipa.Indexers will contain one more elements than, the number of semi-colon (;) separators.


PropertySet Function Syntax

PropertySet Syntax:

Set ipa

The name of the PropertySet function must be Set, but is case-independent. For example, set, Set, sEt and SET are all valid names for the PropertySet function

The PropertySet function must be monadic and may not return a result.

ipa is an instance of the internal class PropertyArguments.

In all cases, ipa.Name contains the name of the Property being referenced and NewValue contains the new value(s) for the element(s) of the Property being assigned.

If the Property is Simple, ipa.Indexers is undefined (VALUE ERROR).

If the Property is Numbered, ipa.Indexers is an integer vector of the same length as the rank of the property (as implied by the result of the Shape function) that identifies a single element of the Property whose value is to be set.

If the Property is Keyed, ipa.Indexers is a vector containing the arrays that were specified within the square brackets in the assignment expression. Specifically, ipa.Indexers will contain one fewer elements than, the number of semi-colon (;) separators.


PropertyShape Function Syntax

PropertyShape Syntax: | R←Shape
 | R←Shape ipa

The name of the PropertyShape function must be Shape, but is case-independent. For example, shape, Shape, sHape and SHAPE are all valid names for the PropertyShape function

A PropertyShape function is only called if the Property is a Numbered Property.

The PropertyShape function must be niladic or monadic and must return a result.

If monadic, ipa is an instance of the internal class PropertyArguments. ipa.Name contains the name of the Property being referenced and NewValue and Indexers are undefined (VALUE ERROR).

The result R must be an integer vector or scalar that specifies the rank of the Property. Each element of R specifies the length of the corresponding dimension of the Property. Otherwise, the reference or assignment to the Property will fail with DOMAIN ERROR.

Note that the result R is used by APL to check that the number of indices corresponds to the rank of the Property and that the indices are within the bounds of its dimensions. If not, the reference or assignment to the Property will fail with RANK ERROR or LENGTH ERROR..


Using the Dyalog GUI

You may manipulate Dyalog GUI objects as Instances of built-in (GUI) Classes. This approach supplements (but does not replace) the use of ⎕WC, ⎕WS and so forth.

To create a GUI object using ⎕NEW, the Class is given as the GUI Object name and the Constructor Argument as a vector of (Property Name / Property Value) pairs. For example, to create a Form:

      F1←⎕NEW 'Form' (⊂'Caption' 'Hello World')

Notice however that only perfectly formed name/value pairs are accepted. The highly flexible syntax for specifying Properties by position and omitting levels of enclosure, that is supported by ⎕WC and ⎕WS, is not provided with ⎕NEW.

Naturally, you may reference and assign Properties as before:

      F1.Size
50 50
      F1.Size←20 30

Callbacks (to regular defined functions in the Root or in another space, work exactly as before. If function FOO merely displays its argument:

     ∇ FOO M
[1]    ⎕←M
     ∇
      F1.onMouseUp←'#.FOO'
#.[Form]  MouseUp  78.57142639 44.62540817 1 0

Note that the first item in the event message is a ref to the Instance of the Form.

To create a control such as a Button, it is only necessary to run ⎕NEW inside a ref to the appropriate parent object. For example:

      B1←F1.⎕NEW 'Button' (('Caption' '&OK')('Size' (10 10)))

As illustrated in this example, it is not necessary to assign the resulting Button Instance to a name inside the Form (F1 in this case). However, it is a good idea to do so, so that refs to Instances of controls are expunged when the parent object is expunged. In the example above, expunging F1 will not remove the Form from the screen because B1 still exists as a ref to the Button. So, the following is safer:

       F1.B1←F1.⎕NEW 'Button' (('Caption' '&OK')('Size' (10 10)))

Or perhaps better still,

       F1.(B1←⎕NEW 'Button' (('Caption' '&OK')('Size' (10 10))))

The next topic describes the Temperature Converter (see Interface Guide) implemented in this manner.


Using the Dyalog GUI (Example)

The following function illustrates this approach to manipulating the Dyalog APL GUI using the Temperature Converter example that is described in Chapter 2 of the Dyalog APL Interface Guide manual.

     ∇ TempConv;TITLE;TEMP
[1]    TITLE←'Temperature Converter'
[2]    TEMP←⎕NEW'Form'(('Caption'TITLE)('Posn'(10 10))('Size'(30 40)))
[3]
[4]    TEMP.(MB←⎕NEW⊂'MenuBar')
[5]    TEMP.MB.(M←⎕NEW'Menu'(,⊂'Caption' '&Scale'))
[6]    TEMP.MB.M.(C←⎕NEW'MenuItem'(('Caption' '&Centigrade')('Checked' 1)))
[7]    TEMP.MB.M.(F←⎕NEW'MenuItem'(,⊂('Caption' '&Fahrenheit')))
[8]
[9]    TEMP.(LF←⎕NEW'Label'(('Caption' 'Fahrenheit')('Posn'(10 10))))
[10]   TEMP.(F←⎕NEW'Edit'(('Posn'(10 40))('Size'(⍬ 20))('FieldType' 'Numeric')))
[11]
[12]   TEMP.(LC←⎕NEW'Label'(('Caption' 'Centigrade')('Posn'(40 10))))
[13]   TEMP.(C←⎕NEW'Edit'(('Posn'(40 40))('Size'(⍬ 20))('FieldType' 'Numeric')))
[14]
[15]   TEMP.(F2C←⎕NEW'Button'(('Caption' 'F->C')('Posn'(10 70))('Default' 1)))
[16]   TEMP.(C2F←⎕NEW'Button'(('Caption' 'C->F')('Posn'(40 70))))
[17]   TEMP.(Q←⎕NEW'Button'(('Caption' '&Quit')('Posn'(70 30))('Size'(⍬ 40))('Cancel' 1)))
[18]
[19]   TEMP.(S←⎕NEW'Scroll'(⊂('Range' 101)))
[20]
[21]   TEMP.MB.M.C.onSelect←'SET_C'
[22]   TEMP.MB.M.F.onSelect←'SET_F'
[23]   TEMP.F2C.onSelect←'f2c'
[24]   TEMP.F.onGotFocus←'SET_DEF'
[25]   TEMP.C2F.onSelect←'c2f'
[26]   TEMP.C.onGotFocus←'SET_DEF'
[27]   TEMP.onClose←'QUIT'
[28]   TEMP.Q.onSelect←'QUIT'
[29]   TEMP.S.onScroll←'c2f_scroll'
[30]
[31]   ⎕DQ'TEMP'
     ∇

For brevity, only a couple of the callback functions are shown here.

     ∇ f2c
[1]    TEMP.C.Value←(TEMP.F.Value-32)×5÷9
     ∇

     ∇ c2f_scroll MSG
[1]   ⍝ Callback for Centigrade input via scrollbar
[2]    TEMP.C.Value←101-4⊃MSG
[3]    c2f
     ∇


Writing Classes based on the Dyalog GUI

You may create user-defined Classes based upon Dyalog GUI objects. The Temperature Converter Class and Dual Class illustrate how this can be done.

To base a Class on a Dyalog GUI object, you specify the name of the object as its Base Class. For example, the Temperature Converter is based upon a Form:

:Class Temp: 'Form'

and the Dual Control is based upon a SubForm:

:Class Dual: 'SubForm'

Being based upon a top-level GUI object, the Temperature Converter may be used as follows:

      T1←⎕NEW Temp(⊂'Posn'(68 50))

Notice that the :Implements Constructor statement of its Constructor Make:

:Implements Constructor :Base (⊂'Caption' TITLE),pv,⊂('Size' (30 40))

passes on the application-specific property list (pv) given as its argument, but (in this case) specifies Caption and Size as well. The order in which the properties are specified in the :Base call ensures that the former will act as a default (and be overridden by an application-specific Caption requested in pv), whereas the specified Size of(30 40) will override whatever value of Size is requested by the host application in pv.

Other Instances can co-exist with the first:

      T2←⎕NEW Temp(('Caption' 'My Application')('Posn'(10 10))

The Dual Control requires a GUI parent but several Instances can co-exist, quite independently, in the same parent.

For example, function RUN creates a Form and 3 Instances of Dual; one to convert Centigrade to Fahrenheit, one to convert Fahrenheit to Centigrade, and the third to convert centimetres to inches.

     ∇ RUN;F;D1PROPS;D2PROPS;D3PROPS
[1]
[2]    F←⎕NEW'Form'(('Caption' 'Dual Instances')('Coord' 'Pixel')('Size'(320 320)))
[3]
[4]    D1PROPS←('Caption1' 'Centigrade')('Caption2' 'Fahrenheit')
[5]    D1PROPS,←('Intercept' 32)('Gradient'(9÷5))('Value1' 0)('Range'(0 100))
[6]    F.D1←F.⎕NEW Dual(('Coord' 'Pixel')('Posn'(10 10))('Size'(100 300)),D1PROPS)
[7]
[8]    D2PROPS←('Caption1' 'Fahrenheit')('Caption2' 'Centigrade')
[9]    D2PROPS,←('Intercept'(-32×5÷9))('Gradient'(5÷9))('Value1' 0)('Range'(0 212))
[10]   F.D2←F.⎕NEW Dual(('Coord' 'Pixel')('Posn'(110 10))('Size'(100 300)),D2PROPS)
[11]
[12]   D3PROPS←('Caption1' 'Centimetres')('Caption2' 'Inches')
[13]   D3PROPS,←('Intercept' 0)('Gradient'(÷2.54))('Value1' 0)('Range'(0 100))
[14]   F.D3←F.⎕NEW Dual(('Coord' 'Pixel')('Posn'(210 10))('Size'(100 300)),D3PROPS)
[15]
[16]   ⎕DQ'F'
     ∇

Dual's Constructor Make first splits its constructor arguments into those that apply to the Dual Class itself and those that apply to the SubForm. Its :Implements Constructor statement then passes these on to the Base Constructor, together with an appropriate setting for EdgeStyle.

      :Implements Constructor :Base BaseArgs,⊂'EdgeStyle' 'Dialog'


Writing Classes based on .Net Types

In Version 11.0 you may create user-defined Classes based upon .Net Classes. This feature supercedes the NetType object through which this was achieved in previous Versions of Dyalog APL.

To base a Class on a .Net Type, you simply specify the .Net Type as its Base Class. However, you must also specify the .Net search path with one or more :Using statements.

For example, the following Class called APLGreg derives from the .Net Type GregorianCalendar which is located in the System.Globalization .Net namespace.

:Class APLGreg: GregorianCalendar
:Using System.Globalization
...
:EndClass

Exporting the Class

Unlike other Classes, a Class that derives from a .Net Type must be exported to a .Net Assembly before it can be used. It must be turned into a fully fledged .Net Type before you can access it through .Net.

You may either export your Class (or Classes) to a named Assembly file (DLL) on disk, or you may take advantage of the new Version 11.0 feature and export it to memory. This is done using the Export to Memory menu item on the Session File menu. Export to Memory builds a temporary in-memory .Net Assembly and is intended to speed the development cycle. Note however that in order to use the Class in a live application, it will be necessary to save it to file.

Using the Class

An APL Class that derives from a .Net Class is used in the same way as any other .Net Class. In particular, you must specify the correct .Net search path by setting ⎕USING.

To use a Class that you have just exported to memory, ⎕USING (or an element of ⎕USING) must be set to an empty vector (''). To use a Class that you have exported to a file, ⎕USING must include the path to the file.


Writing Classes based on .Net Types (Example)

Example of a Class based on a .Net Type

The following example illustrates an APL Class that is based upon the .Net Type MailMessage.

:Class MultiMail : MailMessage
:Using System
:Using System.Web.Mail,system.web.dll
⍝ Adds "MultiSend" method to System.Web.Mail.MailMessage
⍝ "MultiSend" sends one message to each To address (separated by ";")
⍝ So that each recipient sees self as sole addressee

    ⎕ML←0

    ∇ r←MultiSend;to;all;t
      :Access Public
      :Signature Int32←MultiSend
      r←⍴to←1↓¨(';'=to)⊂to←';',all←To
      :For t :In to
          To←t
          SmtpMail.Send ⎕THIS
      :EndFor
      To←all
    ∇

:EndClass

The MultiMail Class adds a MultiSend method to the basic System.Web.Mail.MailMessage Type. MultiSend sends a separate message to each of the recipients in the semi-colon separated address list. The result is the number of recipients.

To use the Class, you must first export it as a .Net Assembly (in this case, using the Export to Memory menu item on the Session File menu) and set ⎕USING.

[Export to Memory]

      ⎕USING←''

      z←⎕NEW MultiMail
      z.To←'mkrom@dyalog.com;mkrom@insight.dk'
      z.Subject←'hello'
      z.From←'mkrom@dyalog.com'
      z.Body←'????'
      z.MultiSend
2

The following points are noteworthy:

  • The :Signature statement in function MultiSend defines the signature of the method. It specifies that MultiSend takes no argument and returns a result of Type Int32 (which will be resolved to System.Int32 via ⎕USING)
  • Of the two :Using statements, the first one is required to resolve the reference to Int32 to System.Int32.
  • The second :Using statement is required to resolve the references to MailMessage (in the :Class statement) and SmtpMail (in MultiSend).


Browsing Classes

The Workspace Explorer has been extended to allow you to browse Classes.

Classes are represented by [image] icons. The picture below shows 3 classes: Bird, Parrot and DomesticParrot.

If you open Class nodes in the left-hand pane, the Explorer shows the Class hierarchy. In this example, DomesticParrot is based upon Parrot which in turn is based upon Bird.


Browsing Class Scripts

You may browse and edit Class Scripts using the Explorer.

Selecting DomesticParrot in the left-hand pane brings up its Class Script in the right-hand pane.

… and selecting Parrot in the left-hand pane brings up the Class Script for Parrot.

… and finally, selecting Bird in the left-hand pane brings up the Class Script for Bird.


Power Operator

{R}←{X}(f⍣g)Y

If right operand g is a numeric integer scalar, power applies its left operand function f cumulatively g times to its argument. In particular, g may be Boolean 0 or 1 for conditional function application.

If right operand g is a scalar-Boolean-returning dyadic function, then left operand function f is applied repeatedly until ((f Y) g Y) or until a strong interrupt occurs. In particular, if g is = or ≡, the result is sometimes termed a fixpoint of f.

If a left argument X is present, it is bound as left argument to left operand function f:

      X (f ⍣ g) Y → (X∘f ⍣ g) Y

A negative right operand g applies the inverse of the operand function f, (|g) times. In this case, f may be a primitive function or an expression of primitive functions combined with primitive operators:

∘ | compose
¨ | each
∘. | outer product
⍨ | commute
[] | axis
\ | scan
⍣ | power

Defined, dynamic and some primitive functions do not have an inverse. In this case, a negative argument g generates DOMAIN ERROR.

Examples

    (,∘⊂∘,⍣(1=≡,vec))vec    ⍝ ravel-enclose if simple.

    a b c←1 0 1{(⊂⍣⍺)⍵}¨abc ⍝ enclose first and last.

    cap←{(⍺⍺⍣⍺)⍵}           ⍝ conditional application.

    a b c←1 0 1⊂cap¨abc     ⍝ enclose first and last.

    succ←1∘+                ⍝ successor function.

    (succ⍣4)10              ⍝ fourth successor of 10.
14
    (succ⍣¯3)10             ⍝ third predecessor of 10.
7
    1+∘÷⍣=1                 ⍝ fixpoint: golden mean.
1.618033989

    f←(32∘+)∘(×∘1.8)        ⍝ Fahrenheit from Celsius.
    f 0 100
32 212

    c←f⍣¯1                  ⍝ c is Inverse of f.
    c 32 212                ⍝ Celsius from Fahrenheit.
0 100

    invs←{(⍺⍺⍣¯1)⍵}         ⍝ inverse operator.

    +\invs 1 3 6 10         ⍝ scan inverse.
1 2 3 4

    2∘⊥invs 9               ⍝ decode inverse.
1 0 0 1

    dual←{⍵⍵⍣¯1 ⍺⍺ ⍵⍵ ⍵}    ⍝ dual operator.

    mean←{(+/⍵)÷⍴⍵}         ⍝ mean function.

    mean dual⍟ 1 2 3 4 5    ⍝ geometric mean.
2.605171085

    +/dual÷ 1 2 3 4 5       ⍝ parallel resistance.
0.4379562044

    mean dual(×⍨)1 2 3 4 5  ⍝ root-mean-square.
3.31662479

    ⍉dual↑ 'hello' 'world'  ⍝ vector transpose.
 hw  eo  lr  ll  od


Index

R←{X}⌷Y

Dyadic Case

X must be a scalar or vector of depth ≤2 of integers each ≥⎕IO. Y may be any array. In general, the result R is similar to that obtained by square-bracket indexing in that:

(I J ... ⌷ Y) ≡ Y[I;J;...]

The length of left argument X must be equal to the rank of right argument Y.

Note that in common with square-bracket indexing, items of the left argument X may be of any rank and that the shape of the result is the concatenation of the shapes of the items of the left argument:

    (⍴X⌷Y) ≡ ↑,/⍴¨X

Index is sometimes referred to as “squad indexing”.

Note that index may be used with selective specification. ⎕IO is an implicit argument of index.

Examples

      ⎕IO←1

      VEC←111 222 333 444
      3⌷VEC
333
      (⊂4 3)⌷VEC
444 333

      (⊂2 3⍴3 1 4 1 2 3)⌷VEC
333 111 444
111 222 333

      ⎕←MAT←10⊥¨⍳3 4
11 12 13 14
21 22 23 24
31 32 33 34
      2 1⌷MAT
21
      3(2 1)⌷MAT
32 31
      (2 3)1⌷MAT
21 31
      (2 3)(,1)⌷MAT
21
31

      ⍴(2 1⍴1)(3 4⍴2)⌷MAT
2 1 3 4
      ⍴⍬ ⍬⌷MAT
0 0
      (3(2 1)⌷MAT)←0 ⋄ MAT    ⍝ Selective assignment.
11 12 13 14
21 22 23 24
 0  0 33 34

Monadic case

If Y is an array, Y is returned.

If Y is a ref to an instance of a Class with a Default property, all elements of the Default property are returned. For example, if Item is the default property of MyClass, and imc is an Instance of MyClass, then by definition:

      imc.Items≡⌷imc

Version 11.0 issues a NONCE ERROR if the Default Property is Keyed, because in this case APL has no way to determine the list of all the elements. A future version will probably introduce a way for a class to define an ordered "key set" for a Keyed property, at which point monadic squad will be extended to return the corresponding elements

Note that the values of the index set are obtained or assigned by calls to the corresponding PropertyGet and PropertySet functions. Furthermore, if there is a sequence of primitive functions to the left of the Index function, that operate on the index set itself (functions such as dyadic ⍴,↑,↓,⊃) as opposed to functions that operate on the values of the index set (functions such as +,⌈,⌊,⍴¨), calls to the PropertyGet and PropertySet functions are deferred until the required index set has been completely determined. The full set of functions that cause deferral of calls to the PropertyGet and PropertySet functions is the same as the set of functions that applies to selective specification.

If for example, CompFile is an Instance of a Class with a Default Numbered Property, the expression:

       1↑⌽⌷CompFile

would only call the PropertyGet function (for CompFile) once, to get the value of the last element.

Note that similarly, the expression

      10000⍴⌷CompFile

would call the PropertyGet function 10000 times, on repeated indices if CompFile has less than 10000 elements. The deferral of access function calls is intended to be an optimisation, but can have the opposite effect. You can avoid unnecessary repetitive calls by assigning the result of ⌷ to a temporary variable.


Index with Axis

R←{X}⌷[K]Y

X must be a scalar or vector of depth ≤2,of integers each ≥⎕IO. Y may be any array.

K is a simple scalar of vector specifying axes of Y.  The length of K must be the same as the length of X:

(⍴,X) ≡ ⍴,K

In general, the result R is similar to that obtained by square-bracket indexing with elided subscripts. Items of K distribute items of X along the axes of Y. For example:

      I J ⌷[1 3] Y  ←→  Y[I;;J]

Note that index with axis may be used with selective specification.

⎕IO is an implicit argument of index with axis..

Examples

     ⎕IO←1

     ⎕←CUBE←10⊥¨⍳2 3 4
111 112 113 114
121 122 123 124
131 132 133 134

211 212 213 214
221 222 223 224
231 232 233 234

      2⌷[1]CUBE
211 212 213 214
221 222 223 224
231 232 233 234

      2⌷[3]CUBE
112 122 132
212 222 232

      CUBE[;;2] ≡ 2⌷[3]CUBE
1
      (1 3)4⌷[2 3]CUBE
114 134
214 234

      CUBE[;1 3;4] ≡ (1 3)4⌷[2 3]CUBE
1
      (2(1 3)⌷[1 3]CUBE)←0 ⋄ CUBE  ⍝ Selective assignment.
111 112 113 114
121 122 123 124
131 132 133 134

  0 212   0 214
  0 222   0 224
  0 232   0 234


And, Lowest Common Multiple

R←X∧Y

Case 1: X and Y are Boolean

R is Boolean and is determined as follows:

             X   Y  |  R
            --------+----
             0   0  |  0
             0   1  |  0
             1   0  |  0
             1   1  |  1

Example:

      0 1 0 1 ∧ 0 0 1 1
0 0 0 1

Case 2: X and Y are numeric (non-Boolean)

R is the lowest common multiple of X and Y.

Example

      15 1 2 7 ∧ 35 1 4 0
105 1 4 0

⎕CT is an implicit argument in Case 2.


Or, Greatest Common Divisor

R←X∨Y

Case 1: X and Y are Boolean

R is Boolean and is determined as follows:

                X  Y | R
                -----+--
                0  0 | 0
                0  1 | 1
                1  0 | 1
                1  1 | 1

Example:

      0 0 1 1 ∨ 0 1 0 1
0 1 1 1

Case 2: X and Y are numeric (non-Boolean)

R is the Greatest Common Divisor of X and Y.

Examples

      15 1 2 7 ∨ 35 1 4 0
5 1 2 7

      rational←{↑⍵ 1÷⊂1∨⍵} ⍝ rational (⎕CT) approximation
                           ⍝ to floating array.
      rational 0.4321 0.1234 6.66, ÷1 2 3
 4321  617 333 1 1 1
10000 5000  50 1 2 3

⎕CT is an implicit argument in Case 2.


Lengths

Lengths ⊃∘⍴¨A (⎕ml<2)

↑∘⍴¨A (⎕ml>2)

This idiom avoids having to create an intermediate nested array of shape vectors.

For an array of vectors, this idiom quickly returns a simple array of the length of each vector.

      ⊃∘⍴¨ 'Hi' 'Pete' ⍝ Vector Lengths
2 4

For an array of matrices, it returns a simple array of the number of rows in each matrix.

      ⊃∘⍴¨⎕CR¨↓⎕NL 3   ⍝ Lines in functions
5 21...


Base Class

R←⎕BASE.Y

⎕BASE is used to access the base class implementation of the name specified by Y.

Y must be the name of a Public member (Method, Field or Property) that is provided by the Base Class of the current Class or Instance.

⎕BASE is typically used to call a method in the Base Class which has been superseded by a Method in the current Class.

Note that ⎕BASE.Y is special syntax and any direct reference to ⎕BASE on its own or in any other context, is meaningless and causes SYNTAX ERROR.

In the following example, Class DomesticParrot derives from Class Parrot and supersedes its Speak method. DomesticParrot.Speak calls the Speak method in its Base Class Parrot, via ⎕BASE.

:Class Parrot: Bird
    ∇ R←Speak
      :Access Public
      R←'Squark!'
    ∇
:EndClass ⍝ Parrot

:Class DomesticParrot: Parrot
    ∇ R←Speak
      :Access Public
      R←⎕BASE.Speak,' Who's a pretty boy,then!'
    ∇
:EndClass ⍝ DomesticParrot
      Maccaw←⎕NEW Parrot
      Maccaw.Speak
Squark!

      Polly←⎕NEW DomesticParrot
      Polly.Speak
Squark! Who's a pretty boy,then!


Class

R←{X}⎕CLASS Y

Monadic Case

Monadic ⎕CLASS returns a list of references to Classes and Interfaces that specifies the class hierarchy for the Class or Instance specified by Y.

Y must be a reference to a Class or to an Instance of a Class.

R is a vector or vectors whose items represent nodes in the Class hierarchy of Y. Each item of R is a vector whose first item is a Class reference and whose subsequent items (if any) are references to the Interfaces supported by that Class.

Example 1

This example illustrates a simple inheritance tree or Class hierarchy. There are 3 Classes, namely:

  1. Animal
  2. Bird (derived from Animal)
  3. Parrot (derived from Bird)
:Class Animal
...
:EndClass ⍝ Animal

:Class Bird:Animal
...
:EndClass ⍝ Bird

:Class Parrot:Bird
...
:EndClass ⍝ Parrot
      ⎕CLASS Eeyore←⎕NEW Animal
 #.Animal
      ⎕CLASS Robin←⎕NEW Bird
 #.Bird    #.Animal
      ⎕CLASS Polly←⎕NEW Parrot
 #.Parrot    #.Bird    #.Animal

      ⎕CLASS¨ Parrot Animal
  #.Parrot    #.Bird    #.Animal      #.Animal

Example 2

The Penguin Class example illustrates the use of Interfaces.

In this case, the Penguin Class derives from Animal (as above) but additionally supports the BirdBehaviour and FishBehaviour Interfaces, thereby inheriting members from both.

      Pingo←⎕NEW Penguin
      ⎕CLASS Pingo
#.Penguin  #.FishBehaviour  #.BirdBehaviour    #.Animal

Dyadic Case

If X is specified, Y must be a reference to an Instance of a Class and X is a reference to an Interface that is supported by Instance Y or to a Class upon which Instance Y is based.

In this case, R is a reference to the implementation of Interface X by Instance Y, or to the implementation of (Base) Class X by Instance Y,and is used as a cast in order to access members of Y that correspond to members of Interface of (Base) Class X.

Example 1:

Once again, the Penguin Class example is used to illustrate the use of Interfaces.

      Pingo←⎕NEW Penguin
      ⎕CLASS Pingo
#.Penguin  #.FishBehaviour  #.BirdBehaviour    #.Animal

      (FishBehaviour ⎕CLASS Pingo).Swim
I can dive and swim like a fish

      (BirdBehaviour ⎕CLASS Pingo).Fly
Although I am a bird, I cannot fly

      (BirdBehaviour ⎕CLASS Pingo).Lay
I lay one egg every year

      (BirdBehaviour ⎕CLASS Pingo).Sing
Croak, Croak!

Example 2:

This example illustrates the use of dyadic ⎕CLASS to cast an Instance to a lower Class and thereby access a member in the lower Class that has been superseded by another Class higher in the tree.

      Polly←⎕NEW DomesticParrot
      Polly.Speak
Squark! Who's a pretty boy,then!

Note that the Speak method invoked above is the Speak method defined by Class DomesticParrot, which supersedes the Speak methods of sub-classes Parrot and Bird.

You may use a cast to access the (superseded) Speak method in the sub-classes Parrot and Bird.

      (Parrot ⎕CLASS Polly).Speak
Squark!
      (Bird ⎕CLASS Polly).Speak
Tweet, tweet


Display Form

R←⎕DF Y

⎕DF sets the Display Form of a namespace, a GUI object, a Class, or an Instance of a Class.

Y must be a simple character array that specifies the display form of a namespace. If defined, this array will be returned by the format functions and ⎕FMT instead of the default for the object in question. This also applies to the string that is displayed when the name is referenced but not assigned (the default display)

The result R is the previous value of the Display Form which initially is ⎕NULL.

      'F'⎕WC'Form'
      ⍕F
#.F
      ⍴⍕F
3
      ⎕FMT F
#.F
      ⍴⎕FMT F
1 3
      F ⍝ default display uses ⍕
#.F

       F.⎕DF 'Pete's Form'
       ⍕F
Pete's Form
       ⍴⍕F
11
       ⎕FMT F
Pete's Form
       ⍴⎕FMT F
1 11

Notice that ⎕DF will accept any character array, but ⎕FMT always returns a matrix.

      F.⎕DF 2 2 5⍴⎕A
      F
ABCDE
FGHIJ

KLMNO
PQRST
      ⍴⍕F
2 2 5
      ⍴⎕←⎕FMT F
ABCDE
FGHIJ

KLMNO
PQRST
5 5

Note that ⎕DF defines the Display Form statically, rather than dynamically.

      'F'⎕WC'Form' 'This is the Caption'
      F
#.F

      F.(⎕DF Caption)         ⍝ set the display form to the current caption
      F
This is the Caption

      F.Caption←'New Caption' ⍝ changing caption does not change the display form
      F
This is the Caption

You may use the Constructor function to assign the Display Form to an Instance of a Class. For example:

:Class MyClass
    ∇ Make arg
      :Access Public
      :Implements Constructor
      ⎕DF arg
    ∇
:EndClass ⍝ MyClass
      PD←⎕NEW MyClass 'Pete'
      PD
Pete

It is possible to set the Display Form for the Root and for ⎕SE

      )CLEAR
clear ws
      #
#
      ⎕DF ⎕WSID
      #
CLEAR WS

      ⎕SE
⎕SE
      ⎕SE.⎕DF 'Session'
      ⎕SE
Session

Note that ⎕DF applies directly to the object in question and is not automatically applied in a hierarchical fashion.

'X'⎕NS ''

      X
#.X

      'Y'X.⎕NS ''

      X.Y
#.X.Y
      X.⎕DF 'This is X'
      X
This is X

      X.Y
#.X.Y


Fix

{R}←{X}⎕FIX Y

⎕FIX fixes a Class from the script specified by Y.

Y must be a vector of character vectors or character scalars that contains a well-formed Class script. If so, the shy result R is a reference to the new Class fixed by ⎕FIX.

The Class specified by Y may be named or unnamed.

If specified, X must be a numeric scalar. If X is omitted or non-zero, and the Class script Y specifies a name (for the Class), ⎕FIX establishes that Class in the workspace.

If X is 0 or the Class specified by Y is unnamed, the Class is not established per se, although it will exist for as long as a reference to it exists.

In the first example, the Class specified by Y is named (MyClass) but the result of ⎕FIX is discarded. The end-result is that MyClass is established in the workspace as a Class.

⎕←⎕FIX ':Class MyClass' ':EndClass'

#.MyClass

In the second example, the Class specified by Y is named (MyClass) and the result of ⎕FIX is assigned to a different name (MYREF). The end-result is that a Class named MyClass is established in the workspace, and MYREF is a reference to it.

      MYREF←⎕FIX ':Class MyClass' ':EndClass'
      )CLASSES
MyClass MYREF
      ⎕NC'MyClass' 'MYREF'
9.4 9.4
      MYREF
#.MyClass

In the third example, the left-argument of 0 causes the named Class MyClass to be visible only via the reference to it (MYREF). It is there, but hidden.

      MYREF←0 ⎕FIX ':Class MyClass' ':EndClass'
      )CLASSES
MYREF
      MYREF
#.MyClass

The final examples illustrate the use of un-named Classes.

      MYREF←⎕FIX':Class' '∇Make n' ':Implements Constructor' '⎕DF n' '∇' ':EndClass'
      )CLASSES
MYREF
      MYINST←⎕NEW MYREF
      MYINST
#.[Instance of [Unnamed]]
      MYINST←⎕NEW MYREF'Pete'
      MYINST
Pete


Instances System Function

Instances

R←⎕INSTANCES Y

⎕INSTANCES returns a list all the current instances of the Class specified by Y.

Y must be a reference to a Class.

R is a vector of references to all existing Instances of Class Y.

Examples

This example illustrates a simple inheritance tree or Class hierarchy. There are 3 Classes, namely:

  1. Animal
  2. Bird (derived from Animal)
  3. Parrot (derived from Bird)
:Class Animal
...
:EndClass ⍝ Animal

:Class Bird:Animal
...
:EndClass ⍝ Bird

:Class Parrot:Bird
...
:EndClass ⍝ Parrot
      Eeyore←⎕NEW Animal
      Robin←⎕NEW Bird
      Polly←⎕NEW Parrot

      ⎕INSTANCES Parrot
 #.[Parrot]
      ⎕INSTANCES Bird
 #.[Bird]  #.[Parrot]
      ⎕INSTANCES Animal
 #.[Animal]  #.[Bird]  #.[Parrot]

      Eeyore.⎕DF 'eeyore'
      Robin.⎕DF 'robin'
      Polly.⎕DF 'polly'

      ⎕INSTANCES Parrot
 polly
      ⎕INSTANCES Bird
 robin  polly
      ⎕INSTANCES Animal
 eeyore  robin  polly


New Instance

R←⎕NEW Y

⎕NEW creates a new instance of the Class or .Net Type specified by Y.

Y must be a 1- or 2-item scalar or vector. The first item is a reference to a Class or to a .Net Type, or a character vector containing the name of a Dyalog GUI object. The second item, if specified, contains the argument to be supplied to the Class or Type Constructor.

The result R is a reference to a new instance of Class or Type Y.

See also: Using the Dyalog GUI.

Class Example

:Class Animal
    ∇ Name nm
      :Access Public
      :Implements Constructor
      ⎕DF nm
    ∇
:EndClass ⍝ Animal
      Donkey←⎕NEW Animal 'Eeyore'
      Donkey
Eeyore

If ⎕NEW is called with just a Class reference (i.e. without parameters for the Constructor), the default constructor will be called. A default constructor is defined by a niladic function with the :Implements Constructor attribute. For example, the Animal Class may be redefined as:

:Class Animal
    ∇ NoName
      :Access Public
      :Implements Constructor
      ⎕DF 'Noname'
    ∇
    ∇ Name nm
      :Access Public
      :Implements Constructor
      ⎕DF nm
    ∇
:EndClass
      Horse←⎕NEW Animal
      Horse
Noname

.Net Examples

      ⎕USING←'System' 'System.Web.Mail,System.Web.dll'
      dt←⎕NEW DateTime (2006 1 1)
      msg←⎕NEW MailMessage
      ⎕NC 'dt' 'msg' 'DateTime' 'MailMessage'
9.2 9.2 9.6 9.6

Note that .Net Types are accessed as follows.

If the name specified by the first item of Y would otherwise generate a VALUE ERROR, and ⎕USING has been set, APL attempts to load the Type specified by Y from the .Net assemblies (DLLs) specified in ⎕USING. If successful, the name specified by Y is entered into the SYMBOL TABLE with a name-class of 9.6. Subsequent references to that symbol (in this case DateTime) are resolved directly and do not involve any assembly searching.

      F←⎕NEW ⊂'Form'
      F←⎕NEW'Form'(('Caption' 'Hello')('Posn' (10 10)))

      ⎕NEW'Form'(('Caption' 'Hello')('Posn' (10 10)))
#.[Form]


Source

R←⎕SRC Y

⎕SRC returns the script that defines the Class Y.

Y must be a reference to a Class.

R is a vector of character vectors containing the script that was used to define Class Y.

      )ED ○MyClass
:Class MyClass
     ∇ Make Name
       :Implements Constructor
       ⎕DF Name
     ∇
:EndClass ⍝ MyClass
      Z←⎕SRC MyClass
      ⍴Z
6
      ⍴¨Z
 14  15  29  14  5  19
      6 1⍴Z
 :Class MyClass
     ∇ Make Name
       :Implements Constructor
       ⎕DF Name
     ∇
 :EndClass ⍝ MyClass


This

R←⎕THIS

⎕THIS returns a reference to the current namespace, i.e. to the space in which it is referenced.

If NC9 is a reference to any object whose name-class is 9, then:

      NC9≡NC9.⎕THIS
1

Examples

      ⎕THIS
#
      'X'⎕NS ''
      X.⎕THIS
#.X
     'F'⎕WC'Form'
     'F.B'⎕WC'Button'
      F.B.⎕THIS
#.F.B

      Polly←⎕NEW Parrot
      Polly.⎕THIS
#.[Parrot]

An Instance may use ⎕THIS to obtain a reference to its own Class:

    Polly.(⊃⊃⎕CLASS ⎕THIS)
#.Parrot

or a function (such as a Constructor or Destructor) may identify or enumerate all other Instances of the same Class:

      Polly.(⍴⎕INSTANCES⊃⊃⎕CLASS ⎕THIS)
1


Classes System Command

List Classes

)CLASSES

This command lists the names of APL Classes in the active workspace.

Example:

      )CLEAR
clear ws
      )ED ○MyClass

:Class MyClass
    ∇ Make Name
      :Implements Constructor
      ⎕DF Name
    ∇
:EndClass ⍝ MyClass

      )CLASSES
MyClass
      )COPY OO YourClass
.\OO saved Sun Jan 29 18:32:03 2006
      )CLASSES
MyClass YourClass
      ⎕NC 'MyClass' 'YourClass'
9.4 9.4


Name Classification

R←⎕NC Y

Y must be a simple character scalar, vector, matrix, or vector of vectors that specifies a list of names. R is a simple numeric vector containing one element per name in Y.

Each element of R is the name class of the active referent to the object named in Y.

If Y is simple, a name class may be:

Name Class | Description
¯1 | invalid name
0 | unused name
1 | Label
2 | Variable
3 | Function
4 | Operator
8 | Event
9 | Object (GUI, namespace, COM, .Net)

If Y is nested, a more precise analysis of name class is obtained whereby different types of functions (primitive, traditional defined functions, D-fns) are identified by a decimal extension. For example, defined functions have name class 3.1, D-fns have name class 3.2, and so forth. The complete set of name classification is as follows:

 | Array (2) | Functions (3) | Operators (4) | Events (8) | Namespaces (9)
n.1 | Variable | Traditional | Traditional |  | Created using ⎕NS
n.2 | Field | D-fns | D-ops |  | Instances
n.3 | Property | Derived/Primitive |  |  |
n.4 |  |  |  |  | Class
n.5 |  |  |  |  | Interface
n.6 | External/Shared | External |  | External | External Class
n.7 |  |  |  |  | External Interface

In addition, values in R are negative to identify names of methods, properties and events that are inherited through the class hierarchy of the current class or instance.


Name List

R←{X}⎕NL Y

Y must be a simple numeric scalar or vector containing one or more of the values for name-class. See also the system function ⎕NC.

X is optional. If present, it must be a simple character scalar or vector. R is a list of the names of active objects whose name-class is included in Y in standard sorted order.

If any element of Y is negative, positive values in Y are treated as if they were negative, and R is a vector of character vectors. Otherwise, R is simple character matrix.

Furthermore, if ⎕NL is being evaluated inside the namespace associated with a Class or an Instance of a Class, and any element of Y is negative, R includes the Public names exposed by the Base Class (if any) and all other Classes in the Class hierarchy.

If X is supplied, R contains only those names which begin with any character of X. Standard sorted order is the collation order of ⎕AV.

If an element of Y is an integer, the names of all of the corresponding sub-name-classes are included in R. For example, if Y contains the value 2, the names of all variables (name-class 2.1), fields (2.2), properties (2.3) and external or shared variables (2.4) are obtained. Otherwise, only the names of members of the corresponding sub-name-class are obtained.

Examples:

      ⎕NL 2 3
A
FAST
FIND
FOO
V

      'AV' ⎕NL 2 3
A
V

      ⎕NL ¯9
 Animal  Bird  BirdBehaviour  Coin  Cylinder  DomesticParrot  Eeyore  FishBehaviour  Nickel  Parrot  Penguin  Polly  Robin
      ⎕NL ¯9.3 ⍝ Instances
 Eeyore  Nickel  Polly  Robin
      ⎕NL ¯9.4 ⍝ Classes
 Animal  Bird  Coin  Cylinder  DomesticParrot  Parrot  Penguin
      ⎕NL ¯9.5 ⍝ Interfaces
 BirdBehaviour  FishBehaviour

⎕NL can also be used to explore Dyalog GUI Objects, .Net types and COM objects.


Using NameList to Explore Dyalog GUI Objects

⎕NL and Dyalog GUI Objects

⎕NL may be used to obtain lists of the Methods, Properties and Events provided by Dyalog APL GUI Objects.

     'F' ⎕WC 'Form'
      F.⎕NL -2 ⍝ Properties
 Accelerator  AcceptFiles  Active  AlphaBlend  AutoConf  Border  BCol  Caption ...

      F.⎕NL -3 ⍝ Methods
 Animate  ChooseFont  Detach  GetFocus  GetTextSize  ShowSIP  Wait
      F.⎕NL -8 ⍝ Events
Close  Create  DragDrop  Configure  ContextMenu  DropFiles  DropObjects  Expose  Help ...


Using NameList to Explore .Net Classes (Types)

⎕NL and .Net Classes (Types)

⎕NL can be used to explore .Net types.

When a reference is made to an undefined name, and ⎕USING is set, APL attempts to load the Type from the appropriate .Net Assemblies. If successful, the name is entered into the symbol table with name-class 9.6.

      ⎕USING←'System'
      DateTime
(System.DateTime)
      ⎕NL -9
 DateTime
      ⎕NC,⊂'DateTime'
9.6

The names of the Properties and Methods of a .Net Type may then be obtained using ⎕NL.

      DateTime.⎕NL -2 ⍝ Properties
 MaxValue  MinValue  Now  Today  UtcNow

      DateTime.⎕NL -3 ⍝ Methods
 get_Now  get_Today  get_UtcNow  op_Addition  op_Equality  ...

In fact it is not necessary to make a separate reference first, because the expression Type.⎕NL (where Type is a .Net Type) is itself a reference to Type. So, (with ⎕USING still set to 'System'):

      Array.⎕NL -3
 BinarySearch  Clear  Copy  CreateInstance  IndexOf  LastIndexOf  Reverse  Sort

      ⎕NL -9
 Array  DateTime

Another use for ⎕NL is to examine .Net enumerations. For example:

      ⎕USING←'System.Windows.Forms,system.windows.forms.dll'

      FormBorderStyle.⎕NL -2
Fixed3D  FixedDialog  FixedSingle  FixedToolWindow  None  Sizable  SizableToolWindow

      FormBorderStyle.FixedDialog.value__
3

      FormBorderStyle.({⍵,[1.5]⍎¨⍵,¨⊂'.value__'}⎕NL -2)
 Fixed3D            2
 FixedDialog        3
 FixedSingle        1
 FixedToolWindow    5
 None               0
 Sizable            4
 SizableToolWindow  6


Using NameList to Explore COM Objects

⎕NL and COM Objects

Once a reference to a COM object has been obtained, ⎕NL may be used to obtain lists of its Methods, Properties and Events.

      xl←⎕NEW'OLEClient'(⊂'ClassName' 'Excel.Application')

      xl.⎕NL -2 ⍝ Properties
 _Default  ActiveCell  ActiveChart  ActiveDialog  ActiveMenuBar  ActivePrinter  ActiveSheet  ActiveWindow ...

      xl.⎕NL -3 ⍝ Methods
 _Evaluate  _FindFile  _Run2  _Wait  _WSFunction  ActivateMicrosoftApp  AddChartAutoFormat  AddCustomList  Browse  Calculate ...

      ⎕NL -9
 xl


Print Precision

⎕PP

⎕PP is the number of significant digits in the display of numeric output.

⎕PP may be assigned any integer value in the range 1 to 17. The value in a clear workspace is 10. Note that in all Versions of Dyalog APL prior to Version 11.0, the maximum value for ⎕PP was 16.

⎕PP is used to format numbers displayed directly. It is an implicit argument of monadic function Format (⍕), monadic ⎕FMT and for display of numbers via ⎕ and ⍞ output. ⎕PP is ignored for the display of integers.

Examples:

      ⎕PP←10

      ÷3 6
0.3333333333 0.1666666667

      ⎕PP←3

      ÷3 6
0.333 0.167

If ⎕PP is set to its maximum value of 17, floating-point numbers may be converted between binary and character representation without loss of precision. In particular, if ⎕PP is 17 and ⎕CT is 0 (to ensure exact comparison), for any floating-point number N the expression N=⍎⍕N is true (except for denormal numbers).


Expose Windows Object Properties

⎕WX

⎕WX is a system variable that determines:

  1. whether or not the names of properties, methods and events provided by a Dyalog APL GUI object are exposed.
  2. The behaviour of .Net objects that have been created by any means other than ⎕NEW or .New. See External Object behaviour.

The permitted values of ⎕WX are 0, 1, or 3. Considered as a sum of bit flags, the first bit in ⎕WX specifies (a), and the second bit specifies (b).

If ⎕WX is 1 (1st bit is set), the names of properties, methods and events are exposed as reserved names in GUI namespaces and can be accessed directly by name. This means that the same names may not be used for global variables in GUI namespaces.

If ⎕WX is 0, these names are hidden and may only be accessed indirectly using ⎕WG and ⎕WS.

If ⎕WX is 3 (2nd bit is also set) COM and .Net objects adopt the Version 11 behaviour, as opposed to the behaviour in previous versions of Dyalog APL.

Note that it is the value of ⎕WX in the object itself, rather than the value of ⎕WX in the calling environment, that determines its behaviour.

The value of ⎕WX in a clear workspace is defined by the default_wx parameter (see User Guide) which itself defaults to 3.

⎕WX has namespace scope and may be localised in a function header. This allows you to create a utility namespace or utility function in which the exposure of objects is known and determined, regardless of its global value in the workspace.


Copy Enhancement for V11

Copy Objects

)COPY {ws {nms}}

)COPY has been enhanced to copy Classes, Interfaces, and Instances. In addition, you may optionally copy Class and Interface Scripts rather than the binary objects themselves.

When you )COPY a Class that is based upon another Class, APL brings an anonymous copy of each of the Classes upon which that Class depends, into the active workspace.

For example, if a saved workspace PARROTS.DWS contains 3 Classes, DomesticParrot, Parrot and Bird where DomesticParrot is based upon Parrot which in turn is based upon Bird,

      )COPY PARROTS DomesticParrot
PARROTS saved Mon Feb 27 09:40:05 2006
      )CLASSES

DomesticParrot

which the )COPied Class is connected, into the workspace.

If instead you )COPY the Class Script, the Script is copied and fixed in the current workspace.

Example:


Edit Objects

{R}←{X}⎕ED Y

Invokes the Editor. Y is a simple character vector, a simple character matrix, or a vector of character vectors, containing the name(s) of objects to be edited. The optional left argument X is a character scalar or character vector with as many elements as there are names in Y. Each element of X specifies the type of the corresponding (new) object named in Y, where:

∇ | function/operator
→ | simple character vector
∊ | vector of character vectors
- | character matrix
○ | Class script

If an object named in Y already exists, the corresponding type specification in X is ignored.

If ⎕ED is called from the Session, it opens Edit windows for the object(s) named in Y and returns a null result. The cursor is positioned in the first of the Edit windows opened by ⎕ED, but may be moved to the Session or to any other window which is currently open. The effect is almost identical to using )ED.

If ⎕ED is called from a defined function or operator, its behaviour is different. On asynchronous terminals the Edit windows are automatically displayed in "full-screen" mode (ZOOMED). In all implementations, the user is restricted to those windows named in Y. The user may not skip to the Session even though the Session may be visible

⎕ED terminates and returns a result ONLY when the user explicitly closes all the windows for the named objects. In this case the result contains the names of any objects which have been changed, and has the same structure as Y.


Function Declaration Statements: Introdution

Introduction

Function Declaration statements are used to identify the characteristics of a function in some way.

The following declarative statements are provided.

:Access

:Attribute

:Implements

:Signature

With one exception, these statements are not executable statements and may theoretically appear anywhere in the body of the function. However, it is recommended that you place them at the beginning before any executable statements. The exception is:

:Implements Constructor <[:Base expr]>

In addition to being declarative (declaring the function to be a Constructor) this statement also executes the Constructor in the Base Class whether or not it includes :Base expr. Its position in the code is therefore significant.


Access Declaration Statement

:Access Statement

:Access <Private|Public><Instance|Shared>Overridable><Override>
:Access <WebMethod>

The :Access statement is used to specify characteristics for functions exported as Methods. It is also applicable to Classes and Properties.

Element | Description
Private|Public | Specifies whether or not the Method is accessible from outside the Class or an Instance of the Class. The default is Private.
Instance|Shared | Specifies whether the Method runs in the Class or Instance.
WebMethod | Specifies that the method is exported as a web method. This applies only to a Class that implements a Web Service.
Overridable | Applies only to an Instance Method and specifies that the Method may be overridden by a Method in a higher Class. See below.
Override | Applies only to an Instance Method and specifies that the Method overrides the corresponding Overridable Method defined in the Base Class. See below.

Overridable/Override

Normally, a Method defined in a higher Class replaces a Method of the same name that is defined in its Base Class, but only for calls made from above or within the higher Class itself (or an Instance of the higher Class). The base method remains available in the Base Class and is invoked by a reference to it from within the Base Class.

However, a Method declared as being Overridable is replaced in situ (i.e. within its own Class) by a Method of the same name in a higher Class if that Method is itself declared with the Override keyword. For further information, see Superseding Base Class Methods.

WebMethod

Note that :Access WebMethod is equivalent to:

:Access Public
:Attribute System.Web.Services.WebMethodAttribute


Attribute Declaration Statement

:Attribute Statement

:Attribute <Name> [ConstructorArgs]

This statement is used to attach .Net Attributes to a Method (or Class).

Attributes are descriptive tags that provide additional information about programming elements. Attributes are not used by Dyalog APL but other applications can refer to the extra information in attributes to determine how these items can be used. Attributes are saved with the metadata of Dyalog APL .NET assemblies.

Element | Description
Name | The name of a .NET attribute
ConstructorArgs | Optional arguments for the Attribute constructor.

Examples

      :Attribute ObsoleteAttribute
      :Attribute ObsoleteAttribute 'Don''t use' 1


Implements Declaration Statement

:Implements Statement

:Implements Constructor <[:Base expr]>
:Implements Destructor
:Implements Method <InterfaceName.MethodName>
:Implements Trigger <name1><,name2,name3,...>

The :Implements statement identifies the function to be one of the following types.

Element | Description
Constructor | Specifies that the function is a Class Constructor.
:Base expr
 Specifies that the Base Constructor be called with the result of the expression expr as its argument.
Destructor
 Specifies that the function is a Class Destructor.
Method
 Specifies that the function implements the Method MethodName whose syntax is specified by Interface InterfaceName.
Trigger | Identifies the function as a Trigger Function which is activated by changes to variable name1, name2, etc.


Signature Statement

:Signature <rslttype←><name><arg1type arg1name>,...

This statement identifies the name and signature by which a function is exported as a method to be called from outside Dyalog APL. Several :Signature statements may be specified to allow the method to be called with different sets of arguments. This is known as overloading.

Element | Description
rslttype | Specifies the data type for the result of the method..
name | Specifies the name of the exported method.
argntype | Specifies the data type of the nth parameter.
argnname | Specifies the name of the nth parameter.

Argument and result data types are identified by the names of .Net Types which are defined in the .Net Assemblies specified by ⎕USING or by a :USING statement.

In the following examples, it is assumed that the Class contains a

      :Using System

or

      ⎕USING←'System'

Example 1

      :Signature String[]←Format Object Array

Specifies that the function is exported as a method named Format which takes a single parameter of type System.Object named Array. The data type of the result of the method is an array (vector) of type System.String.

Example 2

      :Signature Object←Catenate Double Dimension, Object Arg1, Object Arg2

Specifies that the function is exported as a method named Catenate whose result is of type System.Object and which takes 3 parameters. The first parameter is of type System.Double and is named Dimension. The second is of type System.Object and is named Arg1. The third is of type System.Object and is named Arg2.

Example 3

      Signature Int32[]←IndexGen Int32 N, Int32 Origin

Specifies that the function is exported as a method named IndexGen whose result is an array of type System.Int32 and which takes 2 parameters. The first parameter is of type System.Int32 and is named N. The second is of type System.Int32 and is named Origin.

Example 4

      :Signature Int32[,]←Mix Double Dimension, Int32[] Vec1, Int32[] Vec2
      :Signature Int32[,]←Mix Double Dimension, Int32[] Vec1, Int32[] Vec2, Int32[] Vec3
      :Signature Double[,]←Mix Double Dimension, Double[] Vec1, Double[] Vec2
      :Signature Double[,]←Mix Double Dimension, Double[] Vec1, Double[] Vec2, Double[] Vec3
      :Signature Object←Mix Double Dimension, Object Vec1, Object Vec2
      :Signature Object←Mix Double Dimension, Object Vec1, Object Vec2, Object Vec3
      :Signature Object←Mix Double Dimension, Object Vec1, Object Vec2, Object Vec3, Object Vec4
      :Signature Object←Mix Double Dimension, Object Vec1, Object Vec2, Object Vec3, Object Vec4, Object Vec5

Specifies that the function is exported as a method named Mix with 8 different signatures; i.e. it may be called with 8 different parameter/result combinations.


Language Elements

Primitive Functions
+ | - | × | ÷ | | | ⌈ | ⌊ | * | ⍟ |
○ | ! | ? | ~ | ∧ | ∨ | ⍲ | ⍱ |  |
< | ≤ | = | > | ≥ | ≠ | ≡ | ≢ |  |
⍴ | , | ⍪ | ⌽ | ⊖ | ⍉ | ↑ | ↓ |  |
⊂ | ⊃ | ∊ | ⍷ | / | ⌿ | \ | ⍀ |  |
∩ | ∪ | ⍳ | ⌷ | ⍋ | ⍒ | ⍎ | ⍕ | ⊥ | ⊤
⌹ | ⍬ | → |  |  |  |  |  |  |
Primitive Operators
¨ | ⍨ | ∘ | . | ∘. | /
⌿ | \ | ⍀ | ⍣ | ⌷ | &
Special Syntax
Variables
Namespaces
Defined Fns & Ops
Dynamic Fns & Ops
MultiThreading
Object Oriented Programming
Control Structures
Triggers
System Functions
System Commands
Error Messages


Special Symbols

Hash is a namespace identifier.
# Root | ## Parent
Alpha identifies left arguments of dynamic functions/operators.
⍺ Left Argument | ⍺⍺ Left Operand
Omega identifies right arguments of dynamic functions/operators.
⍵ Right Argument | ⍵ Right Operand
Del is used for self-reference in dynamic functions/operators (as well as for the traditional APL Line Editor).
∇ Function Self | ∇∇ Operator Self
Quotation marks are used to surround character strings.
' APL Quote | '' Empty Vector
Diamond character is used to separate APL statements on one line.
⋄ Statement Separator
Lamp symbol is used to identify following comments.
⍝ Comment Symbol
Colon is used to indicate end of line label or start of control word.
: End of Label | : Start Control Word
Semicolon is used to separate index selection arrays in simple indexing, and to separate local names in the header of defined functions/operators.
; Index Separator | ; Localize Name
High Minus or Overbar is used to indicate that a number is negative.
¯ Negative

The following National Language characters may be used in names:

   À Ä Å Æ É Ñ Ö Ø Ü ß
   à á â ä å æ ç è é ê ë
   í î ï ñ ó ô ö ø ù ú û ü

The three special characters

   _ ∆ ⍙

can also be used in names.


Arrays

A Dyalog APL data structure is called an array. An array is a rectangular arrangement of items, each of which may be a single number, a single character, a namespace reference (ref), another array, or the ⎕OR of an object. An array which is part of another array is also known as a sub-array.

An array has two properties; structure and data type. Structure is identified by rank, shape, and depth.

Rank

An array may have 0 or more axes or dimensions. The number of axes of an array is known as its rank. Dyalog APL supports arrays with a maximum of 15 axes.

  • An array with 0 axes (rank 0) is called a scalar.
  • An array with 1 axis (rank 1) is called a vector.
  • An array with 2 axes (rank 2) is called a matrix.
  • An array with more than 2 axes is called a multi-dimensional array.

Shape

Each axis of an array may contain zero or more items. The number of items along each axis of an array is called its shape. The shape of an array is itself a vector. Its first item is the length of the first axis, its second item the length of the second axis, and so on. An array whose length along one or more axes is zero, is called an empty array.

Depth

An array whose items are all simple scalars (i.e. single numbers, characters or refs), is called a simple array. If one or more items of an array is not a simple scalar (i.e. is another array, or a ⎕OR), the array is called a nested array. A nested array may contain items which are themselves nested arrays. The degree of nesting of an array is called its depth. A simple scalar has a depth of 0. A simple vector, matrix, or multi-dimensional array has depth 1. An array whose items are all depth 1 sub-arrays has depth 2; one whose items are all depth 2 sub-arrays has depth 3, and so forth.

Type

An array whose elements are all numeric, is called a numeric array; its TYPE is numeric. A character array is one in which all items are characters. An array whose items contain both numeric and character elements is of MIXED type.


Numbers

Numbers are entered or displayed in conventional or scaled decimal form. On entry a decimal point is optional if there is no fractional part. On output, a number with no fractional part (an integer) is displayed without a decimal point.

The scaled form consists of:

  • an integer or decimal number called the mantissa
  • the letter E
  • an integer called the scale

The scale specifies the power of 10 by which the mantissa is to be multiplied.

Examples

      12 23.24 23.0 2.145E2
12 23.24 23 214.5

Negative numbers are preceded by the high minus (¯) symbol, not to be confused with the negate or minus (-) functions. In scaled form, both the mantissa and the scale may be negative.

Examples

      ¯22 2.145E¯2 ¯10.25
¯22 0.02145 ¯10.25

The empty vector (⍳0) may be represented by the numeric constant ⍬ called ZILDE.


Characters

Characters are entered within a pair of quotes. The surrounding quotes are not displayed on output. The quote character itself must be entered as a pair of quotes.

Examples

      'DYALOG APL'
DYALOG APL
      'I DON''T KNOW'
I DON'T KNOW
      '*'
*


Enclosed Elements

An array may be enclosed to form a scalar element through any of the following means:

  • by the enclose function (⊂)
  • by inclusion in vector notation
  • as the result of certain functions when applied to arrays

Examples

      (⊂1 2 3),⊂'ABC'
 1 2 3  ABC

      (1 2 3) 'ABC'
 1 2 3  ABC

      ⍳2 3
 1 1  1 2  1 3
 2 1  2 2  2 3


Names

Legal Names

APL objects (functions, operators and variables) may be given names. A name may be any sequence of characters, starting with an alphabetic character, selected from the following:

A to Z

a to z

Á to õ

∆ or _ or ⍙

      National Language Symbols
      viz. ÀÄÅÆÉÑÖØÜßàáâäåæçèéêëíîïñóôöøùúûü

0 to 9

The first five rows of characters are designated as being alphabetic.

Examples

     Legal                Illegal

     THIS∆IS∆A∆NAME       BAD NAME
     X123                 3+21
     SALES                S!H|PRICE
     pjb_1                1_pjb


Specification of Variables

A variable is a named array. An undefined name or an existing variable may be assigned an array by specification with the left arrow (←).

Examples

      A←'CHIPS WITH EVERYTHING'

      A
CHIPS WITH EVERYTHING

      X Y←'ONE' 'TWO'

      X
ONE
      Y
TWO


Vector Notation

A series of two or more adjacent expressions results in a vector whose elements are the enclosed arrays resulting from each expression. This is known as VECTOR (or STRAND) NOTATION. Each expression in the series may consist of one of the following:

  • a single numeric value
  • a single character, within a pair of quotes
  • more than one character, within a pair of quotes
  • the name of a variable
  • the evaluated input symbol ⎕
  • he quote-quad symbol ⍞
  • the name of a niladic, defined function yielding a result
  • any other APL expression which yields a result, within parentheses.

Examples

      ⍴A←2 4 10
3

      ⍴TEXT←'ONE' 'TWO'
2

Numbers and characters may be mixed:

      ⍴X←'THE ANSWER IS ' 10
2

      X[1]
 THE ANSWER IS

      X[2] + 2
12

Blanks, quotes or parentheses must separate adjacent items in vector notation. Redundant blanks and parentheses are permitted. In this manual, the symbol pair '←→' indicates the phrase 'is equivalent to'.

      1  2  ←→ (1)(2) ←→ 1  (2)  ←→ (1)  2
      2'X'3 ←→ 2 'X' 3 ←→ (2) ('X') (3)
      1  (2+2) ←→ (1) ((2+2)) ←→ ((1))  (2+2)

Vector notation may be used to define an item in vector notation:

       ⍴X ← 1 (2 3 4) ('THIS' 'AND' 'THAT')
3

      X[2]
 2 3 4

      X[3]
  THIS  AND  THAT

Expressions within parentheses are evaluated to produce an item in the vector:

      Y ← (2+2) 'IS' 4
      Y
4  IS  4

The following identity holds:

      A  B  C  ←→ (⊂A), (⊂B), ⊂C


Structuring of Arrays

A class of primitive functions re-structures arrays in some way. Arrays may be input only in scalar or vector form. Structural functions may produce arrays with a higher rank. The Structural functions are re-shape (⍴), ravel, laminate and catenate (,), reversal and rotation (⌽), transpose (⍉), mix and take (↑), split and drop (↓), and enclose (⊂).

Examples

      2 2⍴1 2 3 4
1 2
3 4

      2 2 4⍴'ABCDEFGHIJKLMNOP'
ABCD
EFGH

IJKL
MNOP

      ↓2 4⍴'COWSHENS'
 COWS  HENS


Display of Arrays

Simple scalars and vectors are displayed in a single line beginning at the left margin. A number is separated from the next adjacent element by a single space. The number of significant digits to be printed is determined by the system variable ⎕PP whose default value is 10. The fractional part of the number will be rounded in the last digit if it cannot be represented within the print precision. Trailing zeros after a decimal point and leading zeros will not be printed. An integer number will display without a decimal point.

Examples

      0.1 1.0 1.12
0.1 1 1.12

      'A' 2 'B' 'C'
A 2 BC

      ÷3 2 6
0.3333333333 0.5 0.1666666667

If a number cannot be fully represented in ⎕PP significant digits, or if the number requires more than five leading zeros after the decimal point, the number is represented in scaled form. The mantissa will display up to ⎕PP significant digits, but trailing zeros will not be displayed.

Examples

      ⎕PP←3

      123 1234 12345 0.12345 0.00012345 0.00000012345
123 1.23E3 1.23E4 0.123 0.000123 1.23E¯7

Simple matrices are displayed in rectangular form, with one line per matrix row. All elements in a given column are displayed in the same format, but the format and width for each column is determined independently of other columns. A column is treated as numeric if it contains any numeric elements. The width of a numeric column is determined such that the decimal points (if any) are aligned; that the E characters for scaled formats are aligned, with trailing zeros added to the mantissae if necessary, and that integer forms are right-adjusted one place to the left of the decimal point column (if any). Numeric columns are right-justified; a column which contains no numeric elements is left-justified. Numeric columns are separated from their neighbours by a single column of blanks.

Examples

      2 4⍴'HANDFIST'
HAND
FIST

      1 2 3 ∘.× 6 2 5
 6 2  5
12 4 10
18 6 15

      2 3⍴2 4 6.1 8 10.24 12
2  4     6.1
8 10.24 12

      2 4⍴4 'A' 'B' 5 ¯0.000000003 'C' 'D' 123.56
 4E0  AB   5
¯3E¯9 CD 123.56

In the display of non-simple arrays, each element is displayed within a rectangle such that the rows and columns of the array are aligned. Simple items within the array are displayed as above. For non-simple items, this rule is applied recursively, with one space added on each side of the enclosed element for each level of nesting.

Examples

      ⍳3
1 2 3

      ⊂⍳3
 1 2 3

      ⊂⊂⍳3
  1 2 3

      ('ONE' 1) ('TWO' 2) ('THREE' 3) ('FOUR' 4)
  ONE  1   TWO  2   THREE  3   FOUR  4

      2 4⍴'ONE' 1 'TWO' 2 'THREE' 3 'FOUR' 4
 ONE    1  TWO   2
 THREE  3  FOUR  4

Multi-dimensional arrays are displayed in rectangular planes. Planes are separated by one blank line, and hyper-planes of higher dimensions are separated by increasing numbers of blank lines. In all other respects, multi-dimensional arrays are displayed in the same manner as matrices.

Examples

      2 3 4⍴⍳24
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      3 1 1 3⍴'THEREDFOX'
THE

RED

FOX

The power of this form of display is made apparent when formatting reports.

Examples

      +AREAS←'West' 'Central' 'East'
 West  Central  East

      +PRODUCTS←'Biscuits' 'Cakes' 'Buns' 'Rolls'
 Biscuits  Cakes  Buns  Rolls

      SALES←50 5.25 75 250 20.15 900 500
      SALES,←80.98 650 1000 90.03 1200
      +SALES←4 3⍴SALES
  50  5.25   75
 250 20.15  900
 500 80.98  650
1000 90.03 1200

      ' ' PRODUCTS ⍪., AREAS SALES
            West  Central  East
 Biscuits     50     5.25    75
 Cakes       250    20.15   900
 Buns        500    80.98   650
 Rolls      1000    90.03  1200

If the display of an array is wider than the page width, as set by the system variable ⎕PW, it will be folded at or before ⎕PW and the folded portions indented six spaces. The display of a simple numeric or mixed array may be folded at a width less than ⎕PW so that individual numbers are not split across a page boundary.

Example

      ⎕PW←40

      ?3 20⍴100
54 22  5 68 68 94 39 52 84  4  6 53 68
85 53 10 66 42 71 92 77 27  5 74 33 64
66  8 64 89 28 44 77 48 24 28 36 17 49
       1  39  7 42 69 49 94
      76 100 37 25 99 73 76
      90  91  7 91 51 52 32


Prototypes and Fill Items

Every array has an associated prototype which is derived from the array's first item.

If the first item is a number, the prototype is 0. Otherwise, if the first item is a character, the prototype is ' '(space). Otherwise, if the first item is a (ref to) an instance of a Class, the prototype is a ref to that Class.

Otherwise (in the nested case, when the first item is other than a simple scalar), the prototype is defined recursively as the prototype of each of the array's first item.

Examples:

Array | Prototype
1 2 3.4 | 0
2 3 5⍴'hello' | ' '
99 'b' 66 | 0
(1 2)(3 4 5) | 0 0
((1 2)3)(4 5 6) | (0 0)0
'hello' 'world' | ' '
⎕NEW MyClass | MyClass
(88(⎕NEW MyClass)'X')7 | 0 MyClass ' '

Fill Items

Fill items for an overtake operation, are derived from the argument's prototype. For each 0 or ' ' in the prototype, there is a corresponding 0 or ' ' in the fill item and for each class reference in the prototype, there is a ref to a (newly constructed and distinct) instance of that class that is initialised by the niladic (default) constructor for that class, if defined.

Examples:

      4↑1 2
1 2 0 0
      4↑'ab'
ab
      4↑(1 2)(3 4 5)
 1 2  3 4 5  0 0  0 0
      2↑⎕NEW MyClass
 #.[Instance of MyClass]  #.[Instance of MyClass]

In the last example, two distinct instances are constructed (the first by ⎕NEW and the second by the overtake).

Fill items are used in a number of operations including:

  • First (⊃ or ↑) of an empty array
  • Fill-elements for overtake
  • For use with the Each operator on an empty array


Conjugate

Identity

R←+Y

Y is any array. R is the same array unchanged. Identity, also called Conjugate, may be used to generate a printed result after an assignment or from a function with an otherwise suppressed result.

Examples

      +A←⍳5
1 2 3 4 5

      +⎕EX'A'
1


Negative

R←-Y

Y may be any numeric array. R is numeric. R is the negative value of Y.

Example:

      -4 2 0 ¯3 ¯5
¯4 ¯2 0 3 5


Direction

Signum

R←×Y

Y may be any numeric array. R is an integer array whose value indicates whether the value of Y is negative (¯1), zero (0) or positive (1).

Example:

      ×¯15.3 0 101
¯1 0 1


Reciprocal

R←÷Y

Y must be a numeric array. R is numeric. R is the reciprocal of Y; that is 1÷Y. If ⎕DIV=0, ÷0 results in a DOMAIN ERROR. If ⎕DIV=1, ÷0 returns 0.

⎕DIV is an implicit argument of Reciprocal.

Examples:

      ÷4 2 5
0.25 0.5 0.2

      ⎕DIV ← 1

      ÷0 0.5
0 2


Magnitude

R←|Y

Y may be any numeric array. R is numeric composed of the absolute (unsigned) values of Y.

Example:

      |2 ¯3.4 0 ¯2.7
2 3.4 0 2.7


Floor

R←⌊Y

Y must be numeric. R is the largest integer value less than or equal to Y.

Examples:

      ⌊¯2.3 0.1 100 3.3
¯3 0 100 3

      ⌊0.5 + 0.4 0.5 0.6
0 1 1

⎕CT is an implicit argument of Floor.


Ceiling

R←⌈Y

Y must be numeric. R is the least integer greater than or equal to Y.

Example:

      ⌈¯2.3  0.1  100  3.3
¯2 1 100 4

⎕CT is an implied argument of Ceiling.


Exponential

R←*Y

Y must be numeric. R is numeric and is the Yth power e, the base of natural logarithms.

Example:

      *1 0
2.718281828 1


Natural Logarithm

R←⍟Y

Y must be a positive numeric array. R is numeric. R is the natural logarithm of Y whose base is the mathematical constant e.

Example:

      ⍟1  2
0 0.06931471806


Pi Times

R←○Y

Y may be any numeric array. R is numeric. The value of R is the product of the mathematical constant Pi times Y.

Example:

      ○ 0.5 1 2
1.570796327 3.141592654 6.283185307


Factorial

R←!Y

Y must be numeric excluding negative integers. R is numeric. R is the product of the first Y integers for positive integer values of Y. For non-integral values of Y, Y is equivalent to the gamma function of Y+1.

Examples:

      !1 2 3 4 5
1 2 6 24 120

      !¯1.5 0 1.5 3.3
¯3.544907702 1 1.329340388 8.85534336


Not

R←~Y

Y must be a Boolean array. R is Boolean. The value of R is 0 if Y is 1, and R is 1 if Y is 0.

Example:

      ~0 1
1 0


Roll

R←?Y

Y may be any positive integer array. R is an integer, pseudo-randomly selected from the integers ⍳Y with each integer in this population having an equal chance of being selected.

⎕IO and ⎕RL are implicit arguments of Roll. A side effect of Roll is to change the value of ⎕RL.

Examples:

      ?9 9 9
2 7 5


Type

 (⎕ML)

R←∊Y

Migration level must be such that ⎕ML<1.

Y may be any array. R is an array with the same shape and structure as Y in which a numeric value is replaced by zero and a character value is replaced by a space.

Examples:

      ∊(2 3⍴⍳6)(1 4⍴'TEXT')
 0 0 0
 0 0 0

      ' '=∊'X'
1


Plus

Add

R←X+Y

Y must be numeric. X must be numeric. R is the arithmetic sum of X and Y. R is numeric.

Examples

      1 2 + 3 4
4 6

      1 2 + 3,⊂4 5
4  6 7


Minus

Subtract

R←X-Y

Y may be any numeric array.  X may be any numeric array.  R is numeric.  The value of R is the difference between X and Y.

Example:

      3 ¯2 4 0 - 2 1 ¯2 4
1 ¯3 6 ¯4


Times

Multiply

R←X×Y

Y may be any numeric array.  X may be any numeric array.  R is the arithmetic product of X and Y.

Example:

      3 2 1 0 × 2 4 9 6
6 8 9 0


Divide

R←X÷Y

Y must be a numeric array.  X must be a numeric array. R is the numeric array resulting from X divided by Y. System variable ⎕DIV is an implicit argument of Divide.

If ⎕DIV=0 and Y=0 then if X=0, the result of X÷Y is 1; if X<≠0 then X÷Y is a DOMAIN ERROR.

If ⎕DIV=1 and Y=0, the result of X÷Y is 0 for all values of X.

Examples:

      2 0 5÷4 0 2
0.5 1 2.5

      ⎕DIV←1
      2 0 5÷4 0 0
0.5 0 0


Residue

R←X|Y

Y may be any numeric array.  X may be any numeric array.

For positive arguments, R is the remainder when Y is divided by X.  If X = 0, R is Y.  For other argument values, R is Y-N×X where N is some integer such that R lies between 0 and X, but is not equal to X.

⎕CT is an implicit argument of Residue.

Examples:

      3 3 ¯3 ¯3|¯5 5 ¯4 4
1 2 ¯1 ¯2

      0.5|3.12 ¯1 ¯0.6
0.12 0 0.4

      ¯1 0 1|¯5.25 0 2.41
¯0.25 0 0.41


Minimum

R←X⌊Y

Y may be any numeric array.  X may be any numeric array.  R is numeric.  R is the smaller of X and Y.

Example:

      ¯2.1 0.1 15.3 ⌊ ¯3.2 1 22
¯3.2 0.1 15.3


Maximum

R←X⌈Y

Y may be any numeric array. X may be any numeric array. R is numeric. R is the larger of the numbers X and Y.

Example:

      ¯2.01 0.1 15.3 ⌈ ¯3.2 ¯1.1 22.7
¯2.01 0.1 22.7


Power

R←X*Y

Y must be a numeric array.  X must be a numeric array. R is numeric.  The value of R is X raised to the power of Y.

If Y is zero, R is defined to be 1.

If X is zero, Y must be non-negative.

If X is negative, and Y can be approximated as a rational number of the form P÷Q where P and Q are relatively prime integers, then:

  •

     if Q is even, X*Y gives a DOMAIN ERROR

  •

     if Q is odd and P is even, then X*Y ←→ (|X)*Y

  •

     if Q and P are both odd, then X*Y ←→ -(|X)*Y

If X is negative, and Y cannot be approximated as a rational number, then       X*Y ←→ -(|X)*Y.

Examples:

      2*2 ¯2
4 0.25

      9 64*0.5
3 8

      ¯27*2 3,(1 2÷3),1.2
729 ¯19683 3 9  52.19591521


Logarithm

R←X⍟Y

Y must be a positive numeric array.  X must be a positive numeric array.  X cannot be 1 unless Y is also 1.  R is the base X logarithm of Y.

Examples:

      10 ⍟ 100 2
2 0.3010299957

      1 ⍟ 1
1

      2 ⍟ 1
0


Binomial

R←X!Y

X and Y may be any numbers except that if Y is a negative integer then X must be a whole number (integer). R is numeric. An element of R is integer if corresponding elements of X and Y are integers. Binomial is defined in terms of the function Factorial for positive integer arguments:

      X!Y ←→ (!Y)÷(!X)×(!Y-X)

For other arguments, results are derived smoothly from the Beta function:

      Beta(X,Y) ←→ ÷Y×(X-1)!X+Y-1

For positive integer arguments, R is the number of selections of X things from Y things.

Example:

      1 1.2 1.4 1.6 1.8 2!5
5 6.105689248 7.219424686 8.281104786 9.227916704 10


Nand

R←X⍲Y

Y must be a Boolean array.  X must be a Boolean array. R is Boolean.  The value of R is determined as follows:

                X   Y  |  R
                -------+---
                0   0  |  1
                0   1  |  1
                1   0  |  1
                1   1  |  0

Example:

      (0 1)(1 0) ⍲ (0 0)(1 1)
 1 1  0 1


Nor

R←X⍱Y

Y must be a Boolean array.  X must be a Boolean array. R is Boolean.  The value of R is determined as follows:

                X   Y | R
                ------+--
                0   0 | 1
                0   1 | 0
                1   0 | 0
                1   1 | 0

Example:

      0 0 1 1 ⍱ 0 1 0 1
1 0 0 0


Less

R←X<Y

Y may be any numeric array. X may be any numeric array. R is Boolean. R is 1 if X is less than Y and X=Y is 0. Otherwise R is 0.

⎕CT is an implicit argument of Less.

Examples:

      (2 4) (6 8 10) < 6
 1 1  0 0 0

      ⎕CT←1E¯10

      1 1.00000000001 1.000000001 < 1
0 0 1


Less or Equal

R←X≤Y

Y may be any numeric array.  X may be any numeric array.  R is Boolean.  R is 1 if X is less than Y or X=Y.  Otherwise R is 0.

⎕CT is an implicit argument of Less or Equal.

Examples:

      2 4 6 8 10 ≤ 6
1 1 1 0 0

      ⎕CT←1E¯10

      1  1.00000000001 1.00000001 ≤ 1
1 1 0


Equal

R←X=Y

Y may be any array.  X may be any array.  R is Boolean. ⎕CT is an implicit argument of Equal.

If X and Y are character, then R is 1 if they are the same character.  If X is character and Y is numeric, or vice-versa, then R is 0.

If X and Y are numeric, then R is 1 if X and Y are within comparison tolerance of each other.  That is, X is considered equal to Y if (|X⍎Y) is not greater than ⎕CT×(|X)⌈|Y.

Examples:

      3=3.1 3 ¯2 ¯3
0 1 0 0

      'CAT'='FAT'
0 1 1

      'CAT'=1 2 3
0 0 0

      'CAT'='C' 2 3
1 0 0

      ⎕CT←1E¯10
      1=1.000000000001
1

      1=1.0000001
0


Greater or Equal

R←X≥Y

Y must be numeric.  X must be numeric.  R is Boolean. R is 1 if X is greater than Y or X=Y.  Otherwise R is 0.

⎕CT is an implicit argument of Greater or Equal.

Examples:

      1 2 3 4 5 ≥ 3
0 0 1 1 1

      ⎕CT←1E¯10

      1≥1
1

      1≥1.00000000001
1

      1≥1.00000001
0


Greater

R←X>Y

Y must be numeric. X must be numeric. R is Boolean. R is 1 if X is greater than Y and X=Y is 0. Otherwise R is 0.

⎕CT is an implicit argument of Greater.

Examples:

      1 2 3 4 5 > 2
0 0 1 1 1

      ⎕CT←1E¯10

      1  1.00000000001 1.000000001 > 1
0 0 1


Not Equal

R←X≠Y

Y may be any array.  X may be any array.  R is Boolean. R is 0 if X=Y.  Otherwise R is 1.

⎕CT is an implicit argument of Not Equal.

Examples:

      1 2 3 ≠ 1.1 2 3
1 0 0

      ⎕CT←1E¯10

      1≠1 1.00000000001 1.0000001
0 0 1

      1 2 3 ≠'CAT'
1 1 1

For Boolean X and Y, the value of R is the
exclusive or result, determined as follows:

                 X   Y  |  R
                 -------+---
                 0   0  |  0
                 0   1  |  1
                 1   0  |  1
                 1   1  |  0


Circular Function

Circular

R←X○Y

Y must be numeric. X must be an integer in the range ¯7 ≤ X ≤ 7. R is numeric.

X determines which of a family of trigonometric functions to apply to Y, from the following table:

Range | Domain | (-X) ○ Y | X | X ○ Y | Range
0≤R≤1 | (|Y)≤1 | (1-Y*2)*.5 | O | (1-Y*2)*.5 | 0≤R≤1
(-○.5)<R≤○.5 | (|Y)≤1 | Arcsin Y | 1 | Sine Y | (|R)≤1
0≤R≤○1 | (|Y)≤1 | Arccos Y | 2 | Cosine Y | (|R)≤1
(|R)≤○.5 |  | Arctan Y | 3 | Tangent Y |
R≥0 | (|Y)≥1 | (¯1+Y*2)*.5 | 4 | (1+Y*2)*.5 |
 |  | Arcsinh Y | 5 | Sinh Y |
R≥0 | Y≥1 | Arccosh Y | 6 | Cosh Y | R>1
 | (|Y)<1 | Arctanh Y | 7 | Tanh Y | (|R)<1

Examples:

      0 ¯1 ○ 1
0 1.570796327

      1○(PI←○1)÷2 3 4
1 0.8660254038  0.7071067812

      2○PI÷3
0.5


Shape

R←⍴Y

Y may be any array.  R is a non-negative integer vector whose elements are the dimensions of Y.  If Y is a scalar, then R is an empty vector.  The rank of Y is given by ⍴⍴Y.

Examples:

      ⍴10

      ⍴'CAT'
3

      ⍴3 4⍴⍳12
3 4

      +G←(2 3⍴⍳6)('CAT' 'MOUSE' 'FLEA')
 1 2 3   CAT  MOUSE  FLEA
 4 5 6

      ⍴G
2

      ⍴⍴G
1

      ⍴¨G
 2 3  3

      ⍴¨¨G
3  5  4


Ravel

R←,Y

Y may be any array.  R is a vector of the elements of Y taken in row-major order.

Examples:

      M
1 2 3
4 5 6

      ,M
1 2 3 4 5 6

      A
ABC
DEF
GHI
JKL

      ,A
ABCDEFGHIJKL

      ⍴,10
1


Ravel with Axes

R←,[K]Y

Y may be any array.

K is either:

  1. A simple fractional scalar adjacent to an axis of Y, or

  2. A simple integer scalar or vector of axes of Y, or

  3. An empty vector.

Ravel with axis can be used with selective specification.

R depends on the case of K above.

  1. If K is a fraction, the result R is an array of the same shape as Y, but with a new axis of length 1 inserted at the K'th position.
          ⍴⍴R ←→ 1+⍴⍴Y
      ⍴R  ←→ (1,⍴Y)[⍋K,⍳⍴⍴Y]

    Examples:

             ,[0.5]'ABC'
   ABC
         ⍴,[0.5]'ABC'
   1 3
         ,[1.5]'ABC'
   A
   B
   C
         ⍴,[1.5]'ABC'
   3 1

         MAT←3 4⍴⍳12
         ⍴,[0.5]MAT
   1 3 4
         ⍴,[1.5]MAT
   3 1 4
         ⍴,[2.5]MAT
   3 4 1
  2. If K is an integer scalar or vector of axes of Y.

    K must contain contiguous axes of Y in ascending order.

    R contains the elements of Y ravelled along the indicated axes.

    Note that if K is a scalar or single element vector, R ←→ Y.

          ⍴⍴R ←→ 1+(⍴⍴Y)-⍴,K

    Examples:

             M
    1  2  3  4
    5  6  7  8
    9 10 11 12

   13 14 15 16
   17 18 19 20
   21 22 23 24
         ⍴M
   2 3 4

         ,[1 2]M
    1  2  3  4
    5  6  7  8
    9 10 11 12
   13 14 15 16
   17 18 19 20
   21 22 23 24
         ⍴,[1 2]M
   6 4

         ,[2 3]M
    1  2  3  4  5  6  7  8  9 10 11 12
   13 14 15 16 17 18 19 20 21 22 23 24

         ⍴,[2 3]M
   2 12
  3. If K is an empty vector a new last axis of length 1 is created.
          ⍴R ←→ (⍴Y),1

    Examples:

             Q1←'January' 'February' 'March'
         DISPLAY Q1
   .→-----------------------------.
   | .→------. .→-------. .→----. |
   | |January| |February| |March| |
   | '-------' '--------' '-----' |
   '∊-----------------------------'
         DISPLAY ,[⍳0]Q1
   .→-----------.
   ↓ .→------.  |
   | |January|  |
   | '-------'  |
   | .→-------. |
   | |February| |
   | '--------' |
   | .→----.    |
   | |March|    |
   | '-----'    |
   '∊-----------'


Reverse

R←⌽[K]Y

Y may be any array. The axis specification is optional. If present, K must be an integer scalar or one-element vector. The value of K must be an axis of Y. If absent, the last axis is implied. The form R←⊖Y implies the first axis.

R is the array Y rotated about the Kth or implied axis.

Examples:

      ⌽1 2 3 4 5
5 4 3 2 1

      M
1 2 3
4 5 6
      ⌽M
3 2 1
6 5 4

      ×M
4 5 6
1 2 3
      ⌽[1]M
4 5 6
1 2 3


Transpose (monadic)

Transpose

R←⍉Y

Y may be any array. R is an array of shape ⌽⍴Y,

similar to Y with the order of the axes reversed.

Examples:

      M
1 2 3
4 5 6

      ⍉M
1 4
2 5
3 6


Mix

 (⎕ML)

R←↑[K]Y,R←⊃[K]Y

The symbol chosen to represent Mix depends on the current Migration Level.

If ⎕ML < 2, Mix is represented by the symbol: ↑.

If ⎕ML ≥ 2, Mix is represented by the symbol: ⊃

Y may be any array. All of the items of Y must be scalars and/or arrays of the same rank. It is not necessary that non-scalar items have the same shape.

K is an optional axis specification. If present it must be a scalar or unit vector. The value of K must be a fractional number indicating the two axes of Y between which new axes are to be inserted. If absent, new ones are added at the end.

R is an array composed from the items of a Y assembled into a higher order array with one less level of nesting. If items of Y have different shapes, each is padded with the corresponding prototype to a shape that represents the greatest length along each axis of all items in Y. The shape of R is the shape of Y with the shape of a typical (extended) item of Y inserted between the ⌊Kth and the ⌈Kth axes of Y.

Examples:

      ↑(1)(1 2)(1 2 3)
1 0 0
1 2 0
1 2 3

      ↑[0.5](1) (1 2) (1 2 3)
1 1 1
0 2 2
0 0 3

      A←('andy' 19)('geoff' 37)('pauline' 21)

      ↑A
 andy    19
 geoff   37
 pauline 21

      ↑[0.5]A
 andy  geoff  pauline
   19     37       21


Split

R←↓[K]Y

Y may be any array. The axis specification is optional. If present, K must be a simple integer scalar or one-element vector. The value of K must be an axis of Y. If absent, the last axis is implied.

The items of R are the sub-arrays of Y along the Kth axis. R is a scalar if Y is a scalar. Otherwise R is an array whose rank is ¯1+⍴⍴Y and whose shape is (K≠⍳⍴⍴Y)/⍴Y.

Examples:

      ↓3 4⍴'MINDTHATSTEP'
 MIND  THAT  STEP

      ↓2 5⍴⍳10
 1 2 3 4 5  6 7 8 9 10

      ↓[1]2 5⍴⍳10
 1 6  2 7  3 8  4 9  5 10


Enclose

R←⊂Y

Y may be any array. R is a scalar array whose item is the array Y. If Y is a simple scalar, R is the simple scalar unchanged. Otherwise, R has a depth whose magnitude is one greater than the magnitude of the depth of Y.

Examples:

      ⊂1
1

      ⊂'A'
A

      ⊂1 2 3
 1 2 3

      ⊂1,⊂'CAT'
 1  CAT

      ⊂2 4⍴⍳8
 1 2 3 4
 5 6 7 8

      ⊂⍳0

      ⊂⊂⍳0

      ⊂⊂10
10


Enclose with Axes

R←⊂[K]Y

Y may be any array.  K is a vector of zero or more axes of Y.

R is an array of the elements of Y enclosed along the axes K.  The shape of R is the shape of Y with the K axes removed:

      ⍴R ←→ (⍴Y)[(⍳⍴⍴R)~K]

The shape of each element of R is the shape of the K'th axes of Y:

      ⍴⊃R ←→ (⍴Y)[,K]

Examples:

      DISPLAY A←2 3 4⍴'DUCKSWANBIRDWORMCAKESEED'
..→---.
↓↓DUCK|
||SWAN|
||BIRD|
||    |
||WORM|
||CAKE|
||SEED|
''----'
      DISPLAY ⊂[3]A
.→---------------------.
↓ .→---. .→---. .→---. |
| |DUCK| |SWAN| |BIRD| |
| '----' '----' '----' |
| .→---. .→---. .→---. |
| |WORM| |CAKE| |SEED| |
| '----' '----' '----' |
'∊---------------------'
      DISPLAY⊂[2 3]A
.→--------------.
| .→---. .→---. |
| ↓DUCK| ↓WORM| |
| |SWAN| |CAKE| |
| |BIRD| |SEED| |
| '----' '----' |
'∊--------------'
      DISPLAY ⊂[1 3]A
.→---------------------.
| .→---. .→---. .→---. |
| ↓DUCK| ↓SWAN| ↓BIRD| |
| |WORM| |CAKE| |SEED| |
| '----' '----' '----' |
'∊---------------------'


Monadic Thorn

Format

R←⍕Y

Y may be any array.  R is a simple character array which will display identically to the display produced by Y.  The result is independent of ⎕PW.  If Y is a simple character array, then R is Y.

Example:

      +B←⍕A←2 6⍴'HELLO PEOPLE'
HELLO
PEOPLE

      B  A
1

If Y is a simple numeric scalar, then R is a vector containing the formatted number without any spaces.  A floating point number is formatted according to the system variable ⎕PP.  ⎕PP is ignored when formatting integers.

Examples:

      ⎕PP←5

      ⍴C←⍕⍳0
0

      ⍴C←⍕10
2

      C
10

      ⍴C←⍕12.34
5

      C
12.34

      ⍕123456789
123456789

      ⍕123.456789
123.46

Scaled notation is used if the magnitude of the non-integer number is too large to represent with ⎕PP significant digits or if the number requires more than five leading zeroes after the decimal point.

Examples:

      ⍕123456.7
1.2346E5

      ⍕0.0000001234
1.234E¯7

If Y is a simple numeric vector, then R is a character vector in which each element of Y is independently formatted with a single separating space between formatted elements.

Example:

      ⍴C←⍕¯123456 1 22.5 ¯0.000000667 5.00001
27

      C
¯1.2346E5 1 22.5 ¯6.67E¯7 5

If Y is a simple numeric array rank higher than one, R is a character array with the same shape as Y except that the last dimension of Y is determined by the length of the formatted data.  The format width is determined independently for each column of Y, such that:

  •

     the decimal points for floating point or scaled formats are aligned.
    •

  •

     the E characters for scaled formats are aligned, with trailing zeros added to the mantissae if necessary.
    •

  •

     integer formats are aligned to the left of the decimal point column, if any, or right-adjusted in the field otherwise.
    •

  •

     each formatted column is separated from its neighbours by a single blank column.
    •

  •

     the exponent values in scaled formats are left-adjusted to remove any blanks.

Examples:

      C←22 ¯0.000000123 2.34 ¯212 123456 6.00002 0

      ⍴C←⍕2 2 3⍴C
2 2 29

      C
  22    ¯1.2300E¯7  2.3400E0
¯212     1.2346E5   6.0000E0

   0     2.2000E1  ¯1.2300E¯7
   2.34 ¯2.1200E2   1.2346E5

If Y is non-simple, and all items of Y at any depth are scalars or vectors, then R is a vector.

Examples:

      B←⍕A←'ABC' 100 (1 2 (3 4 5)) 10

      ⍴A
4
      A
¯3

      ⍴B
26
      B
1

      A
 ABC  100  1 2  3 4 5   10

      B
 ABC  100  1 2  3 4 5   10

By replacing spaces with ∧, it is clearer to see how the result of ⍕ is formed:

∧ABC∧∧100∧∧1∧2∧∧3∧4∧5∧∧∧10

If Y is non-simple, and all items of Y at any depth are not scalars, then R is a matrix.

Example:

      D←⍕C←1 'AB' (2 2⍴1+⍳4) (2 2 3⍴'CDEFGHIJKLMN')

      C
1  AB  2 3  CDE
       4 5  FGH

            IJK
            LMN

      ⍴C
4

      C
¯2

      D
1  AB  2 3  CDE
       4 5  FGH

            IJK
            LMN

      ⍴D
5 16

      D
1

By replacing spaces with ∧, it is clearer to see how the result of ⍕ is formed:

1∧∧AB∧∧2∧3∧∧CDE∧
∧∧∧∧∧∧∧4∧5∧∧FGH∧
∧∧∧∧∧∧∧∧∧∧∧∧∧∧∧∧
∧∧∧∧∧∧∧∧∧∧∧∧IJK∧
∧∧∧∧∧∧∧∧∧∧∧∧LMN∧

⎕PP is an implicit argument of Monadic Format.


Depth

 (⎕ML≥1)

R←≡Y

Y may be any array. R is a simple integer scalar which indicates the number of levels of nesting for the simple scalar item in the array with the greatest number of levels of nesting. A simple scalar has a depth of 0. A simple array has a depth of 1. An array containing non-simple elements has a depth whose magnitude is greater than 1. The array has uniform depth if all simple scalars in the array have the same depth.

If ⎕ML<2, a negative value R indicates non-uniform depth.

Examples:

      ≡1
0

      ≡'A'
0

      ≡'ABC'
1

      ≡1 'A'
1

      ⎕ML←0

      ≡A←(1 2)(3 (4 5))
¯3

      ≡¨A
1 ¯2

      ≡¨¨A
 0 0  0 1

      ⎕ML←2

      ≡A
3

      ≡¨A
1 2

      ≡¨¨A
 0 0  0 1


Enlist

 (⎕ML≥1)

R←∊Y

Migration level must be such that ⎕ML≥1.

Y may be any array, R is a simple vector created from all the elements of Y in ravel order.

Examples:

      ⎕ML←1         ⍝  Migration level 1

      MAT←2 2⍴'MISS' 'IS' 'SIP' 'PI' ⋄ MAT
MISS  IS
SIP   PI

      ∊MAT
MISSISSIPPI

      M←1 (2 2⍴2 3 4 5) (6(7 8))
      M
1  2 3  6  7 8
   4 5
      ∊M
1 2 3 4 5 6 7 8


Reshape

R←X⍴Y

Y may be any array.  X must be a simple scalar or vector of non-negative integers.  R is an array of shape X whose elements are taken from Y in row-major sequence and repeated cyclically if required.  If Y is empty, R is composed of fill elements of Y (⊂∊⊃Y).  If X contains at least one zero, then R is empty.  If X is an empty vector, then R is scalar.

Examples:

      2 3⍴⍳8
1 2 3
4 5 6

      2 3⍴⍳4
1 2 3
4 1 2

      2 3⍴⍳0
0 0 0
0 0 0


Catenate

Catenate & Laminate

R←X,[K]Y

Y may be any array. X may be any array. The axis specification is optional. If specified, K must be a numeric scalar or unit vector which may have a fractional value. If not specified, the last axis is implied.

The form R←X⍪Y may be used to imply catenation along the first axis.

Two cases of the function catenate are permitted:

  1. With an integer axis specification, or implied axis specification.
  2. With a fractional axis specification, also called Laminate.

Case 1: Catenation with an integer or implied specification.

The arrays X and Y are joined along the required axis to form array R. A scalar or unit vector is extended to the shape of the other argument except that the required axis is restricted to a unit dimension. X and Y must have the same shape (after extension) except along the required axis, or one of the arguments may have rank one less than the other, provided that their shapes conform to the prior rule after augmenting the array of lower rank to have a unit dimension along the required axis.

The rank of R is the greater of the ranks of the arguments, but not less than 1.

Examples:

      'FUR','LONG'
FURLONG

      1,2
1 2

      (2 4⍴'THISWEEK')⍪'='
THIS
WEEK
====

      S,[1]+⌿S←2 3⍴⍳6
1 2 3
4 5 6
5 7 9

If, after extension, exactly one of X and Y have a length of zero along the joined axis, then the data type of R will be that of the argument with a non-zero length. Otherwise, the data type of R will be that of X.

Case 2: Lamination

The arrays X and Y are joined along a new axis created before the ⌈Kth axis. The new axis has a length of 2. K must exceed ⎕IO (the index origin) minus 1, and K must be less than ⎕IO plus the greater of the ranks of X and Y. A scalar or unit vector argument is extended to the shape of the other argument. Otherwise X and Y must have the same shape.

The rank of R is one plus the greater of the ranks of X and Y.

Examples:

      'HEADING',[0.5]'-'
HEADING
-------

      'NIGHT',[1.5]'*'
N*
I*
G*
H*
T*

      ⎕IO←0

      'HEADING,[¯0.5]'-'
HEADING
-------


Rotate

R←X⌽[K]Y

Y may be any array.  X must be a simple integer array. The axis specification is optional.  If present, K must be a simple integer scalar or one-element vector.  The value of K must be an axis of Y.  If absent, the last axis of Y is implied.

The form R←X⊖Y implies the first axis.

If Y is a scalar, it is treated as a one-element vector.  X must have the same shape as the rank of Y excluding the Kth dimension.  If X is a scalar or one-element vector, it will be extended to conform.  If Y is a vector, then X may be a scalar or a one-element vector.

R is an array with the same shape as Y, with the elements of each of the vectors along the Kth axis of Y rotated by the value of the corresponding element of X.  If the value is positive, the rotation is in the sense of right to left.  If the value is negative, the rotation is in the sense of left to right.

Examples:

      3 ⌽ 1 2 3 4 5 6 7
4 5 6 7 1 2 3

      ¯2 ⌽ 1 2 3 4 5
4 5 1 2 3

      M
 1  2  3  4
 5  6  7  8

 9 10 11 12
13 14 15 16

      I
0 1¯1 0
0 3 2 1

      I⌽[2]M
 1  6  7  4
 5  2  3  8

 9 14 11 16
13 10 15 12

      J
2 ¯3
3 ¯2

      J⌽M
 3  4  1  2
 6  7  8  5

12  9 10 11
15 16 13 14


Dyadic Transpose

R←X⍉Y

Y may be any array.  X must be a simple scalar or vector whose elements are included in the set ⍳⍴⍴Y. Integer values in X may be repeated but all integers in the set ⍳⌈/X must be included.  Also the number of elements in X must not exceed the rank of Y.

R is an array formed by the transposition of the axes of Y as specified by X.  The Ith element of X gives the new position for the Ith axis of Y.  If X repositions two or more axes of Y to the same axis, the elements used to fill this axis are those whose indices on the relevant axes of Y are equal.

Examples:

      A
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      2 1 3⍉A
 1  2  3  4
13 14 15 16

 5  6  7  8
17 18 19 20

 9 10 11 12
21 22 23 24

      1 1 1⍉A
1 18

      1 1 2⍉A
 1  2  3  4
17 18 19 20


Partitioned Enclose

(⎕ML<3)

R←X⊂[K]Y

Y may be any array.  X must be a simple Boolean scalar or vector.

The axis specification is optional.  If present, it must be a simple integer scalar or one-element vector. The value of K must be an axis of Y.  If absent, the last axis of Y is implied.

X must have the same length as the Kth axis of Y. However, if X is a scalar or one-element vector, it will be extended to the length of the Kth axis of Y.

R is a vector of items selected from Y.  The sub-arrays identified along the Kth axis of Y at positions corresponding to each 1 in X up to the position before the next 1 in X (or the last element of X) become the successive items of Y.  The length of R is +/X (after possible extension).

Examples:

      0 1 0 0 1 1 0 0 0 ⊂⍳9
 2 3 4  5  6 7 8 9

      1 0 1 ⊂[1] 3 4⍴⍳12
 1 2 3 4  9 10 11 12
 5 6 7 8

      1 0 0 1 ⊂[2]3 4⍴⍳12
 1  2  3   4
 5  6  7   8
 9 10 11  12


Partition (APL2 Form)

Partition

 (⎕ML≥3)

R←X⊂[K]Y

Y may be any non scalar array.

X must be a simple scalar or vector of non-negative integers.

The axis specification is optional.  If present, it must be a simple integer scalar or one element array representing an axis of Y.  If absent, the last axis is implied.

R is an array of the elements of Y partitioned according to X.

A new partition is started in the result whenever the corresponding element in X is greater than the previous one. Items in Y corresponding to 0s in X are not included in the result.

Examples:

      ⎕ML←3

      DISPLAY 1 1 1 2 2 3 3 3⊂'NOWISTHE'
.→-----------------.
| .→--. .→-. .→--. |
| |NOW| |IS| |THE| |
| '---' '--' '---' |
'∊-----------------'

      DISPLAY 1 1 1 0 0 3 3 3⊂'NOWISTHE'
.→------------.
| .→--. .→--. |
| |NOW| |THE| |
| '---' '---' |
'∊------------'

      TEXT←'   NOW     IS      THE      TIME    '
      DISPLAY (' '≠TEXT)⊂TEXT
.→------------------------.
| .→--. .→-. .→--. .→---. |
| |NOW| |IS| |THE| |TIME| |
| '---' '--' '---' '----' |
'∊------------------------'

      DISPLAY CMAT←⎕FMT(' ',ROWS),COLS⍪NMAT
.→-------------------------.
↓           Jan   Feb  Mar |
| Cakes       0   100  150 |
| Biscuits    0     0  350 |
| Buns        0  1000  500 |
'--------------------------'

      DISPLAY (∨⌿' '≠CMAT)⊂CMAT   ⍝ Split at blank cols.
.→------------------------------.
↓ .→-------. .→--. .→---. .→--. |
| |        | |Jan| | Feb| |Mar| |
| '--------' '---' '----' '---' |
| .→-------. .→--. .→---. .→--. |
| |Cakes   | |  0| | 100| |150| |
| '--------' '---' '----' '---' |
| .→-------. .→--. .→---. .→--. |
| |Biscuits| |  0| |   0| |350| |
| '--------' '---' '----' '---' |
| .→-------. .→--. .→---. .→--. |
| |Buns    | |  0| |1000| |500| |
| '--------' '---' '----' '---' |
'∊------------------------------'

      DISPLAY N←4 4⍴⍳16
.→----------.
↓ 1  2  3  4|
| 5  6  7  8|
| 9 10 11 12|
|13 14 15 16|
'~----------'

      DISPLAY 1 1 0 1⊂N
.→-------------.
↓ .→--.   .→.  |
| |1 2|   |4|  |
| '~--'   '~'  |
| .→--.   .→.  |
| |5 6|   |8|  |
| '~--'   '~'  |
| .→---.  .→-. |
| |9 10|  |12| |
| '~---'  '~-' |
| .→----. .→-. |
| |13 14| |16| |
| '~----' '~-' |
'∊-------------'

      DISPLAY 1 1 0 1⊂[1]N
.→------------------------.
↓ .→--. .→--. .→--. .→--. |
| |1 5| |2 6| |3 7| |4 8| |
| '~--' '~--' '~--' '~--' |
| .→-.  .→-.  .→-.  .→-.  |
| |13|  |14|  |15|  |16|  |
| '~-'  '~-'  '~-'  '~-'  |
'∊------------------------'


Dyadic Thorn

Dyadic Format

R←X⍕Y

Y must be a simple numeric array.  X must be a simple integer scalar or vector.  R is a character array displaying the array Y according to the specification X.  R has rank 1⌈⍴⍴Y and ¯1↓⍴R is ¯1↓⍴Y.

Conformability requires that if X has more than two elements, then ⍴X must be 2×¯1↑⍴Y.  If X contains one element, it is extended to (2×¯1↑⍴Y)⍴0,X.  If X contains 2 elements, it is extended to (2×¯1↑⍴Y)⍴X.

X specifies two numbers (possibly after extension) for each column in Y.  For this purpose, scalar Y is treated as a one-element vector.  Each pair of numbers in X identifies a format width (W) and a format precision (P).

If P is 0, the column is to be formatted as integers.

The accuracy and performance of the algorithm used to format floating-point
numbers is controlled by the APLFormatBias
parameter.

Examples:

      5 0 ⍕ 2 3⍴⍳6
    1    2    3
    4    5    6

      4 0⍕1.1 2 ¯4 2.547
   1   2  ¯4   3

If P is positive, the format is floating point with P significant digits to be displayed after the decimal point.

Example:

      4 1⍕1.1 2 ¯4 2.547
 1.1 2.0¯4.0 2.5

If P is negative, scaled format is used with |P digits in the mantissa.

Example:

      7 ¯3⍕5 15 155 1555
5.00E0 1.50E1 1.55E2 1.56E3

If W is 0 or absent, then the width of the corresponding columns of R are determined by the maximum width required by any element in the corresponding columns of Y, plus one separating space.

Example:

      3⍕2 3⍴10 15.2346 ¯17.1 2 3 4
  10.000  15.235 ¯17.100
   2.000   3.000   4.000

If a formatted element exceeds its specified field width when W>0, the field width for that element is filled with asterisks.

Example:

      3 0 6 2 ⍕ 3 2⍴10.1 15 1001 22.357 101 1110.1
 10 15.00
*** 22.36
101******

If the format precision exceeds the internal precision, low order digits are replaced by the symbol '_'.

Example :

      26⍕2*100
12676506002282_________________.__________________________

      ⍴26⍕2*100
59

      0 20⍕÷3
0.33333333333333______

      0 ¯20⍕÷3
3.333333333333333____E¯1

The shape of R is the same as the shape of Y except that the last dimension of Y is the sum of the field widths specified in X or deduced by the function.  If Y is a scalar, the shape of R is the field width.

      ⍴5 2 ⍕ 2 3 4⍴⍳24
2 3 20


Disclose

 (⎕ML)

R←⊃Y

The symbol chosen to represent Disclose depends on the current Migration Level.

If ⎕ML < 2, Disclose is represented by the symbol: ⊃.

If ⎕ML ≥ 2, Disclose is represented by the symbol: ↑

Y may be any array. R is an array. If Y is non-empty, R is the value of the first item of Y taken in ravel order. If Y is empty, R is the prototype of Y.

Disclose is the inverse of enclose. The identity R←→⊃⊂R holds for all R. Disclose is also referred to as FIRST.

Examples:

      ⊃1
1

      ⊃2 4 6
2

      ⊃'MONDAY' 'TUESDAY'
MONDAY

      ⊃(1 (2 3))(4 (5 6))
1  2 3

      ⊃⍳0
0

      ' '=⊃''
1

      ⊃1↓⊂1,⊂2 3
0  0 0


Unique

R←∪Y

Y must be a vector.  R is a vector of the elements of Y omitting non-unique elements after the first.

Examples:

      ∪ 'CAT' 'DOG' 'CAT' 'MOUSE' 'DOG' 'FOX'
 CAT  DOG  MOUSE  FOX

      ∪ 22 10 22 22 21 10 5 10
22 10 21 5


Pick

R←X⊃Y

Y may be any array.  X is a scalar or vector of indices of Y, ⍳⍴Y.  R is an item selected from the structure of Y according to X.

Elements of X select from successively deeper levels in the structure of Y.  The items of X are simple integer scalars or vectors which identify a set of indices, one per axis at the particular level of nesting of Y in row-major order.  Simple scalar items in Y may be picked by empty vector items in X to any arbitrary depth.

⎕IO is an implicit argument of Pick.

Examples:

      G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)

      G←2 3⍴G,('MNO' 5)('PQR' 6)

      G
  ABC  1   DEF  2   GHI  3
  JKL  4   MNO  5   PQR  6

      ((⊂2 1),1)⊃G
JKL

      (⊂2 1)⊃G
 JKL  4

      ((2 1)1 2)⊃G
K

      (5⍴⊂⍳0)⊃10
10


Take

R←X↑Y

Y may be any array.  X must be a simple integer scalar or vector.

If Y is a scalar, it is treated as a one-element array of shape (⍴,X)⍴1.  The length of X must be the same as the rank of Y.  However, if X is a scalar or a one-element vector, it will be extended to conform.

R is an array of the same rank as Y (after possible extension), and of shape |X.  If X[I] (an element of X) is positive, then X[I] sub-arrays are taken from the beginning of the Ith axis of Y.  If X[I] is negative, then X[I] sub-arrays are taken from the end of the Ith axis of Y.

If more elements are taken than exist on axis I, then the extra positions in R are filled with the fill element of Y (⊂∊⊃Y).

Examples:

      5↑'ABCDEF'
ABCDE

      5↑1 2 3
1 2 3 0 0

      ¯5↑1 2 3
0 0 1 2 3

      5↑(⍳3) (⍳4) (⍳5)
 1 2 3  1 2 3 4  1 2 3 4 5  0 0 0  0 0 0

      M
1 2 3 4
5 6 7 8

      2 3↑M
1 2 3
5 6 7

      ¯1 ¯2↑M
7 8


Take with Axes

R←X↑[K]Y

Y may be any non scalar array.  X must be a simple integer scalar or vector.  K is a vector of zero or more axes of Y.

R is an array of the first or last elements of Y taken along the axes K depending on whether the corresponding element of X is positive or negative respectively.

The rank of R is the same as the rank of Y:

      ⍴⍴R ←→ ⍴⍴Y

The size of each axis of R is
determined by the corresponding element of X     :

      (⍴R)[,K] ←→ |,X

Examples:

      ⎕←M←2 3 4⍴⍳24
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      2↑[2]M
 1  2  3  4
 5  6  7  8

13 14 15 16
17 18 19 20

      2↑[3]M
 1  2
 5  6
 9 10

13 14
17 18
21 22
      2 ¯2↑[3 2]M
 5  6
 9 10

17 18
21 22


Drop

R←X↓Y

Y may be any array.  X must be a simple scalar or vector of integers.  If X is a scalar, it is treated as a one-element vector.  If Y is a scalar, it is treated as an array whose shape is (⍴X)⍴1 .  After any scalar extensions, ⍴X must equal ⍴⍴Y (the shape of X must equal the rank of Y).

R is an array with the same rank as Y but with elements removed from the vectors along each of the axes of Y. For the Ith axis:

  1.

        if X[I] is positive, all but the first X[I] elements of the vectors result.

  2.

        if X[I] is negative, all but the last X[I] elements of the vectors result.

If the magnitude of X[I] exceeds the length of the Ith axis, the result is an empty array with zero length along that axis.

Examples:

      4↓'OVERBOARD'
BOARD

      ¯5↓'OVERBOARD'
OVER

      ⍴10↓'OVERBOARD'
0

      M
ONE
FAT
FLY

      0 ¯2↓M
O
F
F

      ¯2 ¯1↓M
ON


Drop with Axes

R←X↓[K]Y

Y may be any non scalar array.  X must be a simple integer scalar or vector.  K is a vector of zero or more axes of Y.

R is an array of the elements of Y with the first or last X[i] elements removed. Elements are removed from the beginning or end of Y according to the sign of X[i].

The rank of R is the same as the rank of Y:

      ⍴⍴R ←→ ⍴⍴Y

The size of each axis of R is determined by the corresponding element of X:

      (⍴R)[,K] ←→ 0⌈(⍴Y)[,K]-|,X

Examples:

      ⎕←M←2 3 4⍴⍳24
 1  2  3  4
 5  6  7  8
 9 10 11 12

13 14 15 16
17 18 19 20
21 22 23 24

      1↓[2]M
 5  6  7  8
 9 10 11 12

17 18 19 20
21 22 23 24

      2↓[3]M
 3  4
 7  8
11 12

15 16
19 20
23 24

      2 1↓[3 2]M
 7  8
11 12

19 20
23 24


Replicate

R←X/[K]Y

Y may be any array.  X is a simple integer vector or scalar.

The axis specification is optional.  If present, K must be a simple integer scalar or unit vector.  The value of K must be an axis of Y.  If absent, the last axis of Y is implied.  The form R←X⌿Y implies the first axis of Y.  If Y is a scalar, it is treated as a one-element vector.

The length of X must be the length of the Kth (or implied) axis of Y.  However, if X is a scalar or one-element vector, it will be extended to the length of the Kth axis.

R is composed from sub-arrays along the Kth axis of Y. If X[I] (an element of X) is positive, then the corresponding sub-array is replicated X[I] times.  If X[I] is zero, then the corresponding sub-array of Y is excluded.  If X[I] is negative, then the fill element of Y (⊂∊⊃Y) is replicated |X[I] times.  Each of the (replicated) sub-arrays and fill items are joined along the Kth axis in the order of occurrence.  The shape of R is the shape of Y except that the length of the (implied) Kth axis is +/|X (after possible extension).

Examples:

      1 0 1 0 1/⍳5
1 3 5

      1 ¯2 3 ¯4 5/⍳5
1 0 0 3 3 3 0 0 0 0 5 5 5 5 5

      M
1 2 3
4 5 6

      2 0 1/M
1 1 3
4 4 6

      0 1⌿M
4 5 6

      0 1/[1]M
4 5 6


Expand

R←X\[K]Y

Y may be any array.  X is a simple integer scalar or vector.  The axis specification is optional.  If present, K must be a simple integer scalar or unit vector.  The value of K must be an axis of Y.  If absent, the last axis of Y is implied.  The form R←X⍀Y implies the first axis.  If Y is a scalar, it is treated as a one-element vector.

The number of positive elements in X must be the length of the Kth (or implied) axis of Y.

R is composed from the sub-arrays along the Kth axis of Y.  If X[I] (an element of X) is the Jth positive element in X, then the Jth sub-array along the Kth axis of Y is replicated X[I] times.  If X[I] is negative, then a sub-array of fill elements of Y (⊂∊⊃Y) is replicated |X[I] times and inserted in relative order along the Kth axis of the result.  If X[I] is zero, it is treated as the value ¯1.  The shape of R is the shape of Y except that the length of the Kth axis is +/1⌈|X.

Examples:

      0\⍳0
0

      1 ¯2 3 ¯4 5\'A'
A  AAA    AAAAA

      M
1 2 3
4 5 6

      1 ¯2 2 0 1\M
1 0 0 2 2 0 3
4 0 0 5 5 0 6

      1 0 1⍀M
1 2 3
0 0 0
4 5 6

      1 0 1\[1]M
1 2 3
0 0 0
4 5 6

      1 ¯2 1\(1 2)(3 4 5)
 1 2  0 0  0 0  3 4 5


Without

Excluding

R←X~Y

Y must be a scalar or vector.  X must be a scalar or vector.  R is a vector of the elements of X excluding those elements which occur in Y taken in the order in which they occur in X.

Elements of X and Y are considered the same if X≡Y returns 1 for those elements.

⎕CT is an implicit argument of Excluding (also called Without).

Examples:

      'HELLO'~'GOODBYE'
HLL
      'MONDAY' 'TUESDAY' 'WEDNESDAY'~'TUESDAY' 'FRIDAY'
 MONDAY  WEDNESDAY

      5 10 15~⍳10
15

For performance information see Search Functions and Hash Tables.


Intersection

R←X∩Y

Y must be a scalar or vector.  X must be a scalar or vector.  A scalar X or Y is treated as a one-element vector.  R is a vector composed of items occurring in both X and Y in the order of occurrence in X.  If an item is repeated in X and also occurs in Y, the item is also repeated in R.

Items in X and Y are considered the same if X≡Y returns 1 for those items.

⎕CT is an implicit argument of Intersection.

Examples:

      'ABRA'∩'CAR'
ARA

      1 'PLUS' 2 ∩ ⍳5
1 2

For performance information see Search Functions and Hash Tables.


Union

R←X∪Y

Y must be a vector.  X must be a vector.  If either argument is a scalar, it is treated as a one-element vector.  R is a vector of the elements of X catenated with the elements of Y which are not found in X.

Items in X and Y are considered the same if X≡Y returns 1 for those items.

⎕CT is an implicit argument of Union.

Examples:

      'WASH' ∪ 'SHOUT'
WASHOUT

      'ONE' 'TWO' ∪ 'TWO' 'THREE'
 ONE  TWO  THREE

For performance information see Search Functions and Hash Tables.


Index Generator

R←⍳Y

Y must be a simple scalar or vector array of non-negative numbers.  R is a numeric array composed of the set of all possible coordinates of an array of shape Y.  The shape of R is Y and each element of R occurs in its self-indexing position in R.  In particular, the following identity holds:

      ⍳Y ←→ (⍳Y)[⍳Y]

⎕IO is an implicit argument of Index Generator.

Examples:

      ⎕IO
1
      ⍴⍳O
0
      ⍳5
1 2 3 4 5

      ⍳2 3
 1 1  1 2  1 3
 2 1  2 2  2 3

      +A←2 4⍴'MAINEXIT'
MAIN
EXIT

      A[⍳⍴A]
MAIN
EXIT

      ⎕IO←O

      ⍳5
0 1 2 3 4

      ⍳2 3
 0 0  0 1  0 2
 1 0  1 1  1 2

      A[⍳⍴A]
MAIN
EXIT


Index Of

R←X⍳Y

Y may be any array. X may be any vector. R is a simple integer array with the same shape as Y identifying where elements of Y are first found in X. If an element of Y cannot be found in X, then the corresponding element of R will be ⎕IO+⍴X.

Elements of X and Y are considered the same if X≡Y returns 1 for those elements.

⎕IO and ⎕CT are implicit arguments of Index Of.

Examples:

      ⎕IO←1

      2 4 3 1 4⍳1 2 3 4 5
4 1 3 2 6

      'CAT' 'DOG' 'MOUSE'⍳'DOG' 'BIRD'
2 4

For performance information see Search Functions and Hash Tables.


Membership

R←X∊Y

Y may be any array.  X may be any array.  R is Boolean. An element of R is 1 if the corresponding element of X can be found in Y.

An element of X is considered identical to an element in Y if X≡Y returns 1 for those elements.

⎕CT is an implicit argument of Membership.

Examples:

      'THIS NOUN' ∊ 'THAT WORD'
1 1 0 0 1 0 1 0 0

      'CAT' 'DOG' 'MOUSE' ∊ 'CAT' 'FOX' 'DOG' 'LLAMA'
1 1 0

For performance information see Search Functions and Hash Tables.


Find

R←X⍷Y

X and Y may be any arrays.  R is a simple Boolean array the same shape as Y which identifies occurrences of X within Y

If the rank of X is smaller than the rank of Y, X is treated as if it were the same rank with leading axes of size 1.  For example a vector is treated as a 1-row matrix.

If the rank of X is larger than the rank of Y, no occurrences of X are found in Y.

⎕CT is an implicit argument to Find.

Examples:

      'AN' ⍷ 'BANANA'
0 1 0 1 0 0
      'ANA' ⍷ 'BANANA'
0 1 0 1 0 0
      'BIRDS' 'NEST' ⍷ 'BIRDS' 'NEST' 'SOUP'
1 0 0
      MAT
IS YOU IS
OR IS YOU
IS'NT
      'IS' ⍷ MAT
1 0 0 0 0 0 0 1 0
0 0 0 1 0 0 0 0 0
1 0 0 0 0 0 0 0 0
      'IS YOU' ⍷ MAT
1 0 0 0 0 0 0 0 0
0 0 0 1 0 0 0 0 0
0 0 0 0 0 0 0 0 0


Grade Up (dyadic)

Dyadic Grade Up

R←X⍋Y

Y must be a simple character array of rank greater than 0. X must be a simple character array of rank 1 or greater. R is a simple integer vector being the permutation of ⍳1↑⍴Y that places the sub-arrays of Y along the first axis in ascending order according to the collation sequence X.

If X is a vector, the following identity holds:

      X⍋Y ←→ ⍋X⍳Y

If X is a higher order array, each axis of X represents a grading attribute in decreasing order of importance. If a character is repeated in X, it is treated as though it were located at the position in the array determined by the lowest index in each axis for all occurrences of the character. The character has the same weighting as the character located at the derived position in X.

For further explanation, see Dyadic Grade Down.

Examples

      (2 2⍴'ABBA') ⍋ 'AB'[?5 2⍴2] ⍝ A AND B ARE EQUIVALENT
1 2 3 4 5

      DISPLAY A←2 14⍴' abcdegiklmnrt ABCDEGIKLMNRT'
.→-------------.
↓ abcdegiklmnrt|
| ABCDEGIKLMNRT|
'--------------'

      V←'Ab' 'AB' 'aba' 'ABA' 'abaca' 'abecedarian'
      V,←'Abelian' 'black' 'blackball' 'black belt'
      V,←'blacking' 'Black Mass'

      DISPLAY M←↑V
.→----------.
↓Ab         |
|AB         |
|aba        |
|ABA        |
|abaca      |
|abecedarian|
|Abelian    |
|black      |
|blackball  |
|black belt |
|blacking   |
|Black Mass |
'-----------'

      DISPLAY¨M (M[(,A)⍋M;]) (M[(,⍉A)⍋M;]) (M[A⍋M;])
 .→----------.  .→----------.  .→----------.  .→----------.
 ↓Ab         |  ↓aba        |  ↓aba        |  ↓Ab         |
 |AB         |  |abaca      |  |abaca      |  |AB         |
 |aba        |  |abecedarian|  |abecedarian|  |aba        |
 |ABA        |  |black      |  |Ab         |  |ABA        |
 |abaca      |  |black belt |  |Abelian    |  |abaca      |
 |abecedarian|  |blackball  |  |AB         |  |abecedarian|
 |Abelian    |  |blacking   |  |ABA        |  |Abelian    |
 |black      |  |Ab         |  |black      |  |black      |
 |blackball  |  |Abelian    |  |black belt |  |black belt |
 |black belt |  |AB         |  |blackball  |  |Black Mass |
 |blacking   |  |ABA        |  |blacking   |  |blackball  |
 |Black Mass |  |Black Mass |  |Black Mass |  |blacking   |
 '-----------'  '-----------'  '-----------'  '-----------'


Grade Down (dyadic)

Dyadic Grade Down

R←X⍒Y

Y must be a simple character array of rank greater than 0. X must be a simple character array of rank 1 or greater. R is a simple integer vector of shape 1↑⍴Y containing the permutation of ⍳1↑⍴Y that places the sub-arrays of Y along the first axis in descending order according to the collation sequence X. The indices of any set of identical sub-arrays in Y occur in R in ascending order.

If X is a vector, the following identity holds:

      X⍒Y ←→ ⍒X⍳Y

A left argument of rank greater than 1 allows successive resolution of duplicate orderings in the following way.

Starting with the last axis:

The characters in the right argument are located along the current axis of the left argument. The position of the first occurrence gives the ordering value of the character.

If a character occurs more than once in the left argument its lowest position along the current axis is used.

If a character of the right argument does not occur in the left argument, the ordering value is one more than the maximum index of the current axis - as with dyadic iota.

The process is repeated using each axis in turn, from the last to the first, resolving duplicates until either no duplicates result of all axes have been exhausted.

For example, if index origin is 1:

   Left argument:                  Right argument:
        abc                             ab
        ABA                             ac
                                        Aa
                                        Ac

Along last axis:

Character:    Value:     Ordering:

ab             1 2        3
ac             1 3       =1 <- duplicate ordering with
Aa             1 1        4
Ac             1 3       =1 <- respect to last axis.

Duplicates exist, so resolve these with respect to the first axis:

Character:    Value:     Ordering:

ac             1 1        2
Ac             2 1        1

So the final row ordering is:

        ab              3
        ac              2
        Aa              4
        Ac              1

That is, the order of rows is 4 2 1 3 which corresponds to a descending row sort of:

        Ac              1
        ac              2
        ab              3
        Aa              4

Examples

      ⍴S1
2 27

      S1
 ABCDEFGHIJKLMNOPQRSTUVWXYZ
 abcdefghijklmnopqrstuvwxyz
      S2
 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
      S3
 AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz
      S4
 ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
 abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ

The following results are tabulated for comparison:

X       X[S1⍒X;]    X[S2⍒X;]    X[S3⍒X;]    X[S4⍒X;]
FIRsT     TAPE        rAT         TAPE        TAPE
TAP       TAP         fIRST       TAP         TAP
RATE      RATE        TAPE        rAT         RATE
FiRST     rAT         TAP         RATE        rAT
FIRST     RAT         RATE        RAT         RAT
rAT       MAT         RAT         MAT         MAT
fIRST     fIRST       MAT         fIRST       FIRsT
TAPE      FiRST       FiRST       FiRST       FiRST
MAT       FIRsT       FIRsT       FIRsT       FIRST
RAT       FIRST       FIRST       FIRST       fIRST

⎕IO is an implicit argument of Grade Down.


Deal

R←X?Y

Y must be a simple scalar or unit vector containing a non-negative integer. X must be a simple scalar or unit vector containing a non-negative integer and X≤Y.

R is an integer unit vector obtained by making X random selections from ⍳Y without repetition.

Examples:

      13?52
7 40 24 28 12 3 36 49 20 44 2 35 1

      13?52
20 4 22 36 31 49 45 28 5 35 37 48 40

⎕IO and ⎕RL are implicit arguments of Deal. A side effect of Deal is to change the value of ⎕RL.


Match

R←X≡Y

Y may be any array. X may be any array. R is a simple Boolean scalar. If X is identical to Y, then R is 1. Otherwise R is 0.

Non-empty arrays are identical if they have the same structure and the same values in all corresponding locations. Empty arrays are identical if they have the same shape and the same prototype (disclosed nested structure).

⎕CT is an implicit argument of Match.

Note that ⎕OR's of functions match only if their canonical representations, attributes and lock status are identical.

Examples:

      ⍬≡⍳0
1
      ''≡⍳0
0
      A
THIS
WORD

      A≡2 4⍴'THISWORD'
1
      A≡⍳10
0
      +B←A A
 THIS  THIS
 WORD  WORD

      A≡⊃B
1

      (0⍴A)≡0⍴B
0

      ' '=⊃0⍴B
1 1 1 1
1 1 1 1

      ' '=⊃0⍴A
1


Not Match

R←X≢Y

Y may be any array.  X may be any array.  R is a simple Boolean scalar.  If X is identical to Y, then R is 0. Otherwise R is 1.

Non-empty arrays are identical if they have the same structure and the same values in all corresponding locations.  Empty arrays are identical if they have the same shape and the same prototype (disclosed nested structure).

⎕CT is an implicit argument of Not Match.

Examples:

      ⍬≢⍳0
0
      ''≢⍳0
1

      +A←⊂(⍳3) 'ABC'
  1 2 3  ABC

      A≢(⍳3)'ABC'
1
      A≢⊂(⍳3) 'ABC'
0
      ⍬≢0⍴A
1
      (1↑0⍴A)≢⊂(0 0 0) '   '
1


Zilde

⍬

Zilde returns the empty numeric vector 0⍴0 or, equivalently, ⍬

The empty character vector is given by ''


Naked Branch

→

This is a special case of the Branch function used in the niladic sense. If it occurs in a statement it must be the only symbol in an expression or the only symbol forming an expression in a text string to be executed by ⍎. It clears the most recently suspended statement and all of its pendent statements from the state indicator.

The Abort function has no explicit result. The function is not in the function domain of operators.

Examples:

     ∇ F
[1]    'F[1]'
[2]    G
[3]    'F[3]'
     ∇

     ∇ G
[1]    'G[1]'
[2]    →
[3]    'G[3]'
     ∇
      F
F[1]
G[1]

      ⎕VR'VALIDATE'
     ∇ VALIDATE
 [1]   →(12=1↑⎕AI)⍴0 ⋄ 'ACCOUNT NOT AUTHORISED' ⋄ →
     ∇

      VALIDATE
ACCOUNT NOT AUTHORISED

      1↑⎕AI
52


Branch

→Y

Y may be a scalar or vector which, if not empty, has a simple numeric scalar as its first element.  The function has no explicit result.  It is used to modify the normal sequence of execution of expressions or to resume execution after a statement has been interrupted.  Branch is not in the function domain of operators.

The following distinct usages of the branch function occur:

        .-------------------+----------------------.
        |                   |                      |
        | Entered in a      | Entered in immediate |
        | statement in a    | execution mode       |
        | defined function  |                      |
        |                   |                      |
.-------+-------------------+----------------------|
|       |                   |                      |
| →LINE | Continue with the | Restart execution at |
|       | specific line     | the specific line of |
|       |                   | the most recently    |
|       |                   | suspended function   |
|       |                   |                      |
|-------+-------------------+----------------------|
|       |                   |                      |
| →⍳0   | Continue with the | No effect            |
|       | next expression   |                      |
|       |                   |                      |
'-------+-------------------+----------------------'

In a defined function, if Y is non-empty then the first element in Y specifies a statement line in the defined function to be executed next.  If the line does not exist, then execution of the function is terminated. For this purpose, line 0 does not exist.  (Note that statement line numbers are independent of the index origin ⎕IO).

If Y is empty, the branch function has no effect.  The next expression is executed on the same line, if any, or on the next line if not.  If there is no following line, the function is terminated.

Example:

        ∇TEST
  [1]    1
  [2]   →4
  [3]    3
  [4]    4
        ∇

         TEST
 1
 4

In general it is better to branch to a LABEL than to a line number.  A label occurs in a statement followed by a colon and is assigned the value of the statement line number when the function is defined.

Example:

        ∇ TEST
 [1]      1
 [2]      →FOUR
 [3]      3
 [4]      FOUR:4
        ∇
          TEST
1
4

The previous examples illustrate unconditional branching.  There are numerous APL idioms which result in conditional branching.  Some popular idioms are identified:

.--------------------+------------------------------.
|                    |                              |
|Branch Expression   |          Comment             |
|                    |                              |
|--------------------+------------------------------|
|                    |                              |
|→TEST/L1            |Branches to label L1 if TEST  |
|                    |results in 1 but not if TEST  |
|                    |results in 0.                 |
|→TEST⍴L1            |Similar to above.             |
|→TEST↑L1            |Similar to above.             |
|→L1⍴⍨TEST           |Similar to above.             |
|→L1⌈⍳TEST           |Similar to above but only if  |
|                    |⎕IO←→1.                       |
|→L1×⍳TEST           |Similar to above but only if  |
|                    |⎕IO←→1.                       |
|→(L1,L2,L3)[N]      |Unconditional branch to a     |
|                    |selected label.               |
|→(T1,T2,T3)/L1,L2,L3|Branches to the first selected|
|                    |label dependent on tests      |
|                    |T1,T2,T3.  If all tests result|
|                    |in 0, there is no branch.     |
|→N⌽L1,L2,L3         |Unconditional branch to the   |
|                    |first label after rotation.   |
'--------------------+------------------------------'

A branch expression may occur within a statement including û separators:

[5]   →NEXT⍴⍨TEST ⋄ A←A+1 ⋄ →END
[6]  NEXT:

In this example, the expressions 'A←A+1' and '→END' are executed only if TEST returns the value 1.  Otherwise control branches to label NEXT.

In immediate execution mode, the branch function permits execution to be continued within the most recently suspended function, if any, in the state indicator.  If the state indicator is empty, or if the argument Y is the empty vector, the branch expression has no effect.  If a statement line is specified which does not exist, the function is terminated.  Otherwise, execution is restarted from the beginning of the specified statement line in the most recently suspended function.

Example:

     ∇ F
[1]    1
[2]    2
[3]    3
[4]    ∇

      F
1

F[2]
      )SI
F[2]*
      →2
2
3

The system constant ⎕LC returns a vector of the line numbers of statement lines in the state indicator, starting with that in the most recently suspended function.  It is convenient to restart execution in a suspended state by the expression:

      →⎕LC


Execute

R←⍎Y

Y must be a simple character scalar or vector.  If Y is an empty vector, it is treated as an empty character vector.  Y is taken to be an APL statement to be executed.  R is the result of the last-executed expression.  If the expression has no value, then ¨Y has no value.  If Y is an empty vector or a vector containing only blanks, then ¨Y has no value.

If Y contains a branch expression which evaluates to a non-empty result, R does not yield a result.  Instead, the branch is effected in the environment from which the Execute was invoked.

Examples:

      ⍎'2+2'
4
      4=⍎'2+2'
1

      A
1 2 3
4 5 6
      ⍎'A'
1 2 3
4 5 6
      ⍎'A←2|¯1↑⎕TS ⋄ →0⍴⍨A ⋄ A'
0
      A
0


Matrix Inverse

R←⌹Y

Y must be a simple array of rank 2 or less.  Y must be non-singular.  If Y is a scalar, it is treated as a one-element matrix.  If Y is a vector, it is treated as a single-column matrix.  Y must have at least the same number of rows as columns.

R is the inverse of Y if Y is a square matrix, or the left inverse of Y if Y is not a square matrix.  That is, R+.×Y is an identity matrix.

The shape of R is ⌽⍴Y.

Examples:

      M
4 ¯1
2  1

      +A←⌹M
 0.1666666667 0.1666666667
¯0.3333333333 0.6666666667

Within calculation accuracy, A+.×M is the identity matrix.

      A+.×M
1 0
0 1


Decode

R←X⊥Y

Y must be a simple numeric array.  X must be a simple numeric array.  R is the numeric array which results from the evaluation of Y in the number system with radix X.

X and Y are conformable if the length of the last axis of X is the same as the length of the first axis of Y. A scalar or unit vector is extended to a vector of the required length.  If the last axis of X or the first axis of Y has a length of 1, the array is extended along that axis to conform with the other argument.

The shape of R is the catenation of the shape of X less the last dimension with the shape of Y less the first dimension.  That is:

      ⍴R ←→ (¯1↓⍴X),1↓⍴Y

For vector arguments, each element of X defines the ratio between the units for corresponding pairs of elements in Y.  The first element of X has no effect on the result.

Examples:

      60 60⊥3 13
193

      0 60⊥3 13
193

      60⊥3 13
193

      2⊥1 0 1 0
10

For higher order array arguments, each of the vectors along the last axis of X is taken as the radix vector for each of the vectors along the first axis of Y.

Examples:

      M
0 0 0 0 1 1 1 1
0 0 1 1 0 0 1 1
0 1 0 1 0 1 0 1

      A
1 1 1
2 2 2
3 3 3
4 4 4

      A⊥M
0 1 1 2  1  2  2  3
0 1 2 3  4  5  6  7
0 1 3 4  9 10 12 13
0 1 4 5 16 17 20 21

Scalar extension may be applied:

      2⊥M
0 1 2 3 4 5 6 7

Extension along a unit axis may be applied:

      +A←2 1⍴2 10
 2
10
      A⊥M
0 1  2  3   4   5   6   7
0 1 10 11 100 101 110 111


Encode

R←X⊤Y

Y must be a simple numeric array.  X must be a simple numeric array.  R is the numeric array which results from the representation of Y in the number system defined by X.

The shape of R is (⍴X),⍴Y (the catenation of the shapes of X and Y).

If X is a vector or a scalar, the result for each element of Y is the value of the element expressed in the number system defined by radix X.  If Y is greater than can be expressed in the number system, the result is equal to the representation of the residue (×/X)|Y. If the first element of X is 0, the value will be fully represented.

Examples:

      10⊤5 15 125
5 5 5

      0 10⊤5 15 125
0 1 12
5 5  5

If X is a higher order array, each of the vectors along the first axis of X is used as the radix vector for each element of Y.

Examples:

      A
2 0  0
2 0  0
2 0  0
2 0  0
2 8  0
2 8  0
2 8 16
2 8 16

      A⊤75
0 0  0
1 0  0
0 0  0
0 0  0
1 0  0
0 1  0
1 1  4
1 3 11

The example shows binary, octal and hexadecimal representations of decimal number 75.

Examples:

      0 1⊤1.25 10.5
 1    10
 0.25  0.5

      4 13⊤13?52
 3 1 0  2 3 2 0 1  3 1 2 3 1
12 2 4 12 1 7 6 3 10 1 0 3 8


Dyadic Execute

R←X⍎Y

Y must be a simple character scalar or vector.  If Y is an empty vector, it is treated as an empty character vector.  X must be a simple character scalar or vector representing the name of a namespace.  Y is then taken to be an APL statement to be executed in namespace X.  R is the result of the last-executed expression.  If the expression has no value, then X⍎Y has no value.

Example

      '⎕SE' ⍎ '⎕NL 9 '


Matrix Divide

R←X⌹Y

Y must be a simple numeric array of rank 2 or less.  X must be a simple numeric array of rank 2 or less.  Y must be non-singular.  A scalar argument is treated as a matrix with one-element.  If Y is a vector, it is treated as a single row matrix.  If X is a vector, it is treated as a single column matrix.  The number of rows in X and Y must be the same.  Y must have at least the same number of rows as columns.

R is the result of matrix division of X by Y.  That is, the matrix product Y+.×R is X.  R is determined such that (X-Y+.×R)*2 is minimised.

The shape of R is (1↓⍴Y),1↓⍴X.

Examples:

      ⎕PP←5

      B
3 1 4
1 5 9
2 6 5

      35 89 79 ⌹ B
2.1444 8.2111 5.0889

      A
35 36
89 88
79 75

      A ⌹ B
2.1444 2.1889
8.2111 7.1222
5.0889 5.5778

If there are more rows than columns in the right argument, the least squares solution results.  In the following example, the constants a and b which provide the best fit for the set of equations represented by P = a + bQ are determined:

      Q
1 1
1 2
1 3
1 4
1 5
1 6

      P
12.03 8.78 6.01 3.75 ¯0.31 ¯2.79

      P⌹Q
14.941 ¯2.9609


Each (monadic)

Each

{R}←f¨Y

f may be any monadic function.  Y may be any array, each of whose items are separately appropriate to function f.

The derived function applies function f separately to each item of Y.  The derived function need not return a result.  If a result is returned, R has the same shape as Y, and its elements are the items produced by the application of function f to the corresponding items of Y.

If Y is empty, the derived function is applied once to the prototype of Y, and the shape of R is the shape of Y.

Examples:

      G←('TOM' (⍳3))('DICK' (⍳4))('HARRY' (⍳5))
      ⍴G
3
      ⍴¨G
 2  2  2

      ⍴¨¨G
  3  3    4  4    5  5

      +⎕FX¨('FOO1' 'A←1')('FOO2' 'A←2')
 FOO1 FOO2


Each (dyadic)

Dyadic Each

{R}←Xf¨Y

f may be any dyadic function.  X and Y may be any arrays whose corresponding items (after scalar extension) are appropriate to function f when applied separately.

The derived function is applied separately to each pair of corresponding elements of X and Y.  If X or Y is a scalar or single-element array, it will be extended to conform with the other argument.  The derived function need not produce an explicit result.  If a result is returned, R has the same shape as Y (after possible scalar extension) whose elements are the items produced by the application of the derived function to the corresponding items of X and Y.

If X or Y is empty and scalar conformable, the derived function is applied once to the prototype s of X and Y, and the shape of R is determined by the rules for scalar conformability.

Examples:

      +G←(1 (2 3))(4 (5 6))(8 9)10
 1  2 3   4  5 6   9 8  10

      1⌽¨G
  2 3  1   5 6  4  9 8  10

      1⌽¨¨G
 1  3 2   4  6 5   8 9  10

      1⌽¨¨¨G
 1  2 3   4  5 6   8 9  10

      1 2 3 4¨G
 1  4  5 6   8 9 0  10 0 0 0

      'ABC',¨'XYZ'
 AX  BY  CZ


Reduce

R←f/[K]Y

f must be a dyadic function. Y may be any array whose items in the sub-arrays along the Kth axis are appropriate to function f.

The axis specification is optional. If present, K must identify an axis of Y. If absent, the last axis of Y is implied. The form R←f⌿Y implies the first axis of Y.

R is an array formed by applying function f between items of the vectors along the Kth (or implied) axis of Y.

For a typical vector Y, the result is:

⊂(1⊃y)f(2⊃y)f......f(n⊃y)

The shape of R is the shape of Y excluding the Kth axis. If Y is a scalar then R is a scalar. If the length of the Kth axis is 1, then R is the same as Y. If the length of the Kth axis is 0, then DOMAIN ERROR is reported unless function f occurs in figure, in which case its identity element is returned in each element of the result. Note that in the Identity Element table shown below, M is largest number that can be represented on the computer.

Identity Elements
Function |  | Identity
Add | + | 0
Subtract | - | 0
Multiply | × | 1
Divide | ÷ | 1
Residue | | | 0
Minimum | ⌊ | M
Maximum | ⌈ | -M
Power | * | 1
Binomial | ! | 1
And | ∧ | 1
Or | ∨ | 0
Less | < | 0
Less or Equal | ≤ | 1
Equal | = | 1
Greater | > | 0
Greater or Equal | ≥ | 1
Not Equal | ≠ | 0
Encode | ⊤ | 0
Union | ∪ | ⍬
Replicate | /⌿ | 1
Expand | \⍀ | 1
Rotate | ⌽⊖ | 0

Examples:

      ∨/0 0 1 0 0 1 0
1

      M
1 2 3
4 5 6

      +/M
6 15

      +⌿M
5 7 9

      +/[1]M
5 7 9

      +/(1 2 3)(4 5 6)(7 8 9)
 12 15 18

      ,/'ONE' 'NESS'
 ONENESS

      +/⍳0
0

      ,/''
DOMAIN ERROR
      ,/''
      ∧


Reduce N-Wise

R←Xf/[K]Y

f must be a dyadic function. X must be a simple scalar or one-item integer array. Y may be any array whose sub-arrays along the Kth axis are appropriate to function f.

The axis specification is optional. If present, K must identify an axis of Y. If absent, the last axis of Y is implied. The form R←Xf⌿Y implies the first axis of Y.

R is an array formed by applying function f between items of sub-vectors of length X taken from vectors along the Kth (or implied) axis of Y.

X can be thought of as the width of a ‘window’ which moves along vectors drawn from the Kth axis of Y.

If X is zero, the result is a (⍴Y)+(⍴⍴Y)=⍳⍴⍴Y array of identity elements for the function f. See
Reduce (Identity Elements).

If X is negative, each sub-vector is reversed before being reduced.

Examples

      ⍳4
1 2 3 4

      3+/⍳4        ⍝ (1+2+3) (2+3+4)
6 9
      2+/⍳4        ⍝ (1+2) (2+3) (3+4)
3 5 7
      1+/⍳4        ⍝ (1) (2) (3) (4)
1 2 3 4

      0+/⍳4        ⍝ Identity element for +
0 0 0 0 0
      0×/⍳4        ⍝ Identity element for ×
1 1 1 1 1

      2,/⍳4        ⍝ (1,2) (2,3) (3,4)
 1 2  2 3  3 4
      ¯2,/⍳4        ⍝ (2,1) (3,2) (4,3)
 2 1  3 2  4 3


Scan

R←f\[K]Y

f may be any dyadic function that returns a result.  Y may be any array whose items in the sub-arrays along the Kth axis are appropriate to the function f.

The axis specification is optional.  If present, K must identify an axis of Y.  If absent, the last axis of Y is implied.  The form R←f⍀Y implies the first axis of Y.

R is an array formed by successive reductions along the Kth axis of Y.  If V is a typical vector taken from the Kth axis of Y, then the Ith element of the result is determined as f/I↑V.

The shape of R is the same as the shape of Y.  If Y is an empty array, then R is the same empty array.

Examples:

      ∨\0 0 1 0 0 1 0
0 0 1 1 1 1 1

      ∧\1 1 1 0 1 1 1
1 1 1 0 0 0 0

      +\1 2 3 4 5
1 3 6 10 15

      +\(1 2 3)(4 5 6)(7 8 9)
 1 2 3  5 7 9  12 15 18

      M
1 2 3
4 5 6

      +\M
1 3  6
4 9 15

      +⍀M
1 2 3
5 7 9

      +\[1]M
1 2 3
5 7 9

      ,\'ABC'
A AB  ABC

      T←'ONE(TWO) BOOK(S)'

      ≠\T∊'()'
0 0 0 1 1 1 1 0 0 0 0 0 0 1 1 0

      ((T∊'()')⍱≠\T∊'()')/T
ONE BOOK


Commute

{R}←X f⍨Y

f may be any dyadic function. X and Y may be any arrays whose items are appropriate to function f.

The derived function is equivalent to YfX. The derived function need not return a result.

If left argument X is omitted, the right argument Y is duplicated in its place, i.e. f⍨Y ←→ Y f⍨Y

Examples

      N
3 2 5 4 6 1 3

      N/⍨2|N
3 5 1 3

      ⍴⍨3
3 3 3

      mean←+/∘(÷∘⍴⍨) ⍝ mean of a vector
      mean ⍳10
5.5

The following statements are equivalent:

      F/⍨←I
      F←F/⍨I
      F←I/F

Commute often eliminates the need for parentheses


Compose On

Composition (Form I)

{R}←f∘g Y

f may be any monadic function. g may be any monadic function which returns a result. Y may be any array whose items are appropriate to function g. The items of gY must be appropriate to function f.

The derived function is equivalent to fgY. The derived function need not return a result.

Composition allows functions to be 'glued' together to build up more complex functions.

Examples:

      RANK ← ⍴∘⍴
      RANK ¨ 'JOANNE' (2 3⍴⍳6)
 1  2
      +/∘⍳¨2 4 6
3 10 21

      ⎕VR'SUM'
     ∇ R←SUM X
[1]    R←+/X
     ∇

      SUM∘⍳¨2 4 6
3 10 21


Compose By

Composition (Form II)

{R}←A∘g Y

g may be any dyadic function. A may be any array whose items are appropriate to function g. Y may be any array whose items are appropriate to function g.

The derived function is equivalent to AgY. The derived function need not return a result.

Examples:

      2 2∘⍴ ¨ 'AB'
 AA  BB
 AA  BB

      SINE ← 1∘○

      SINE 10 20 30
¯0.5440211109 0.9129452507 ¯0.9880316241

The following example uses composition forms I and II to list functions in the workspace:

      ⎕NL 3
ADD
PLUS

      ⎕∘←∘⎕VR¨↓⎕NL 3
     ∇ ADD X
[1]    →LAB⍴⍨0≠⎕NC'SUM' ⋄ SUM←0
[2]   LAB:SUM←SUM++/X
     ∇
     ∇ R←A PLUS B
[1]    R←A+B
     ∇


Compose With

Composition (Form III)

{R}←(f∘B)Y

f may be any dyadic function. B may be any array whose items are appropriate to function f. Y may be any array whose items are appropriate to function f.

The derived function is equivalent to YfB. The derived function need not return a result.

Examples:

      (*∘0.5)4 16 25
2 4 5

      SQRT ← *∘.5

      SQRT 4 16 25
2 4 5

The parentheses are required in order to distinguish between the operand B and the argument Y.


Compose Over

Composition (Form IV)

{R}←Xf∘gY

f may be any dyadic function. c may be any monadic function which returns a result. Y may be any array whose items are appropriate to function g. Also gY must return a result whose items are appropriate as the right argument of function f. X may be any array whose items are appropriate to function f.

The derived function is equivalent to XfgY. The derived function need not return a result.

Examples:

      +∘÷/40⍴1       ⍝ Golden Ratio! (Bob Smith)
1.618033989

      0,∘⍳¨⍳5
0 1  0 1 2  0 1 2 3  0 1 2 3 4  0 1 2 3 4 5


Inner Product

R←Xf.gY

f must be a dyadic function.  c may be any dyadic function which returns a result.  The last axis of X must have the same length as the first axis of Y.

The result of the derived function has shape (¯1↓⍴X),1↓⍴Y.  Each item of R is the result of f/xg¨y where x and y are typical vectors taken from all the combinations of vectors along the last axis of X and the first axis of Y respectively.

Function f (and the derived function) need not return a result in the exceptional case when 2=¯1↑⍴X.  In all other cases, function f must return a result.

If the result of xg¨y is empty, for any x and y, a DOMAIN ERROR will be reported unless function f is a primitive scalar dyadic function with an identity element shown in figure.

Examples:

      1 2 3+.×10 12 14
76

      1 2 3 PLUS.TIMES 10 12 14
76

      +/1 2 3×10 12 14
76

      NAMES
HENRY
WILLIAM
JAMES
SEBASTIAN

      NAMES∧.='WILLIAM  '
0 1 0 0


Spawn

{R}←{X}f&Y

& is a monadic operator with an ambivalent derived function. & spawns a new thread in which f is applied to its argument Y (monadic case) or between its arguments X and Y (dyadic case). The shy result of this application is the number of the newly created thread.

When function f terminates, its result (if any), the thread result, is returned. If the thread number is the subject of an active ⎕TSYNC, the thread result appears as the result of ⎕TSYNC. If no ⎕TSYNC is in effect, the thread result is displayed in the session in the normal fashion.

Note that & can be used in conjunction with the each operator ¨ to launch many threads in parallel.

Examples

      ÷&4         ⍝ Reciprocal in background
0.25

      ⎕←÷&4       ⍝ Show thread number
1
0.25

      FOO&88      ⍝ Spawn monadic function.

      2 FOO&3     ⍝ dyadic

      {NIL}&0     ⍝ niladic

      ⍎&'NIL'     ⍝ ..

      X.GOO&99    ⍝ thread in remote space.

      ⍎&'⎕dl 2'   ⍝ Execute async expression.

      'NS'⍎&'FOO' ⍝ .. remote .. .. ..

      PRT&¨↓⎕nl 9 ⍝ PRT spaces in parallel.


Indexing

R←X[Y]

X may be any array.  Y must be a valid index specification.  R is an array composed of elements indexed from X and the shape of X is determined by the index specification.

Indexing does not follow the normal syntax of a dyadic function.

⎕IO is an implicit argument of Indexing.

Three forms of indexing are permitted.  The form used is determined by context.

Simple Indexing

For vector X, Y is a simple integer array composed of items from the set ⍳⍴X.  R consists of elements selected according to index positions in Y.  R has the same shape as Y.

Examples:

      A←10 20 30 40 50

      A[2 3⍴1 1 1 2 2 2]
10 10 10
20 20 20

      A[3]
30

      'ONE' 'TWO' 'THREE'[2]
 TWO

For matrix X, Y is composed of two simple integer arrays separated by the semicolon character (;).  The arrays select indices from the rows and columns of X respectively.

Examples:

      +M←2 4⍴10×⍳8
10 20 30 40
50 60 70 80

      M[2;3]
70

For higher order array X, Y is composed of a simple integer array for each axis of X with adjacent arrays separated by a single semicolon character (;).  The arrays select indices from the respective axes of X, taken in row-major order.

Examples:

      +A←2 3 4⍴10×⍳24
 10  20  30  40
 50  60  70  80
 90 100 110 120

130 140 150 160
170 180 190 200
210 220 230 240

      A[1;1;1]
10

      A[2;3 2;4 1]
240 210
200 170

If an indexing array is omitted for the Kth axis, the index vector ⍳(⍴X)[K] is assumed for that axis.

Examples:

      A[;2;]
 50  60  70  80
170 180 190 200

      M
10 20 30 40
50 60 70 80

      M[;]
10 20 30 40
50 60 70 80

      M[1;]
10 20 30 40

      M[;1]
10 50

Choose Indexing

The index specification Y is a non-simple array.  Each item identifies a single element of X by a set of indices with one element per axis of X in row-major order.

Examples:

      M
10 20 30 40
50 60 70 80

      M[⊂1 2]
20

      M[2 2⍴⊂2 4]
80 80
80 80

      M[(2 1)(1 2)]
50 20

A scalar may be indexed by the enclosed empty vector:

      S←'Z'

      S[3⍴⊂⍳0]
ZZZ

Simple and Choose indexing are indistinguishable for vector X:

      V←10 20 30 40

      V[⊂2]
20
      ⊂2
2
      V[2]
20

Reach Indexing

The index specification Y is a non-simple integer array, each of whose items reach down to a nested element of X.  The items of an item of Y are simple vectors (or scalars) forming sets of indices that index arrays at successive levels of X starting at the top-most level.  A set of indices has one element per axis at the respective level of nesting of X in row-major order.

Examples:

      G←('ABC' 1)('DEF' 2)('GHI' 3)('JKL' 4)

      G←2 3⍴G,('MNO' 5)('PQR' 6)

      G
  ABC  1   DEF  2   GHI  3
  JKL  4   MNO  5   PQR  6

      G[((1 2)1)((2 3)2)]
 DEF  6

      G[2 2⍴⊂(2 2)2]
5 5
5 5

      G[⊂⊂1 1]
  ABC  1

      G[⊂1 1]
  ABC  1

      V←,G

      V[⊂⊂1]
  ABC  1

      V[⊂1]
  ABC  1

      V[1]
  ABC  1


Assignment

X←Y

Assignment allocates the result of the expression Y to the name or names in X.

If Y is an array expression, X must contain one or more names which are variables, system variables, or are undefined. Following assignment, the name(s) in X become variable(s) with value(s) taken from the result of the expression Y.

If X contains a single name, the variable assumes the value of Y.

Examples:

      A←2.3
      A
2.3

      A←⍳3
      A
1 2 3

More than one name may be specified in X by using vector notation. If so, Y must be a vector or a scalar. If Y is a scalar, its value is assigned to all names in X. If Y is a vector, each element of Y is assigned to the corresponding name in X.

Examples:

      A B←2
      A
2

      B
2

      P ⎕IO Q←'TEXT' 1 (1 2 3)
      P
TEXT
      ⎕IO
1
      Q
1 2 3

For compatibility with IBM's APL2, the list of names specified in X may be enclosed in parentheses.

Examples:

      (A B C)←1 2 3

(D E)←'Hello' 'World'

Multiple assignments are permitted. The value of Y is carried through each assignment:

      I←J←K←0

      I
0
      J
0
      K
0

Function Assignment

If Y is a function expression, X must be a single name which is either undefined, or is the name of an existing function or defined operator. X may not be the name of a system function, or a primitive symbol.

Examples

      PLUS←+
      PLUS
+

      SUM←+/
      SUM
+/

      MEAN←{(+/⍵)÷⍴⍵}

Namespace Reference Assignment

If an expression evaluates to a namespace reference, or ref, you may assign it to a name. A name assigned to a simple scalar ref, has name class 9, whereas one assigned to an array containing refs has name class 2.

      'f1'⎕WC'Form'
      'ns1' ⎕NS ''
      N←ns1
      ⎕NC'N'           ⍝ name class of a scalar ref
9
      F←f1
      ⎕NC'F'           ⍝ name class of a scalar ref
9
      refs←N F         ⍝ vector of refs.
      ⎕NC'refs'        ⍝ nameclass of vector.
2
      F2←2⊃refs
      ⎕NC 'F2'
9

Re-Assignment

A name that already exists may be assigned a new value if the assigment will not alter its name class, or will change it from 2 to 9 or vice versa. The table of permitted re-assignments is as follow.

 | Ref | Variable | Function | Operator
Ref | Yes | Yes |  |
Variable | Yes | Yes |  |
Function |  |  | Yes | Yes
Operator |  |  | Yes | Yes


Indexed Assignment

R←X[I]←Y

Indexed Assignment is the Assignment function modified by the Indexing function. The phrase [I]← is treated as the function for descriptive purposes.

Y may be any array. X may be the name of any array. I must be a valid index specification. The shape of Y must conform with the shape (implied) of the indexed structure defined by I. If Y is a scalar or a unit vector it will be extended to conform. A side effect of Indexed Assignment is to change the value of the indexed elements of X.

R is the value of Y. If the result is not explicitly assigned or used it is suppressed.

⎕IO is an implicit argument of Indexed Assignment.

Three forms of indexing are permitted.

Simple Indexed Assignment

For vector X, I is a simple integer array whose items are from the set ⍳⍴R. Elements of X identified by index positions I are replaced by corresponding elements of Y.

Examples:

      +A←⍳5
1 2 3 4 5

      A[2 3]←10 ⋄ A
1 10 10 4 5

The last-most element of Y is assigned when an index is repeated in I:

      A[2 2]←100 101 ⋄ A
1 101 10 4 5

For matrix X, I is composed of two simple integer arrays separated by the semicolon character (;). The arrays select indices from the rows and columns of X respectively.

Examples:

      +B←2 3⍴'REDSUN'
RED
SUN

      B[2;2]←'O' ⋄ B
RED
SON

For higher-order array X, I is a series of simple integer arrays with adjacent arrays separated by a single semicolon character (;). Each array selects indices from an axis of X taken in row-major order.

Examples:

      C
11 12 13
14 15 16

21 22 23
24 25 26

      C[1;1;3]←103 ⋄ C
11 12 103
14 15  16

21 22  23
24 25  26

An indexing array may be ELIDED. That is, if an indexing array is omitted from the Kth axis, the indexing vector ⍳(⍴X)[K] is implied:

      C[;1;2 3]←2 2⍴112 113 122 123 ⋄ C
11 112 113
14  15  16

21 122 123
24  25  26

      C[;;]←0 ⋄ C
0 0 0
0 0 0

0 0 0
0 0 0

Choose Indexed Assignment

The index specification I is a non-simple integer array. Each item identifies a single element of X by a set of indices with one element per axis of X in row-major order.

Examples:

      C
11 12 13 14
21 22 23 24

      C[⊂1 1]←101 ⋄ C
101 12 13 14
 21 22 23 24

      C[(1 2) (2 3)]←102 203 ⋄ C
101 102  13 14
 21  22 203 24

      C[2 2⍴(1 3)(2 4)(2 1)(1 4)]←2 2⍴103 204 201 104⋄C
101 102 103 104
201  22 203 204

A scalar may be indexed by the enclosed empty vector:

      S
10

      S[⊂⍳0]←⊂'VECTOR' ⋄ S
 VECTOR

      S[⊂⍳0]←5 ⋄ S
5

Choose Indexed Assignment may be used very effectively in conjunction with Index Generator (⍳) and Structural functions in order to assign into an array:

      C
11 12 13 14
21 22 23 24

      ⍳⍴C
1 1  1 2  1 3  1 4
2 1  2 2  2 3  2 4

      C[1 1⍉⍳⍴C]←1 2 ⋄ C
 1 12 13 14
21  2 23 24

      C[2 ¯1↑⍳⍴C]←99 ⋄ C
 1 12 13 99
21  2 23 99

Reach Indexed Assignment

The index specification I is a non-simple integer array, each of whose items reach down to a nested element of X. The items of an item of I are simple vectors (or scalars) forming sets of indices that index arrays at successive levels of X starting at the top-most level. A set of indices has one element per axis at the respective level of nesting of X in row-major order.

Examples:

      D←(2 3⍴⍳6)(2 2⍴'SMITH' 'JONES' 'SAM' 'BILL')

      D
 1 2 3   SMITH  JONES
 4 5 6   SAM    BILL

      ≡J←⊂2 (1 2)
¯3

      D[J]←⊂'WILLIAMS' ⋄ D
 1 2 3   SMITH  WILLIAMS
 4 5 6   SAM    BILL

      D[(1 (1 1))(2 (2 2) 1)]←10 'W' ⋄ D
 10 2 3   SMITH  WILLIAMS
  4 5 6   SAM    WILL

      E
 GREEN  YELLOW  RED

      E[⊂2 1]←'M' ⋄ E
 GREEN  MELLOW  RED

The context of indexing is important. In the last example, the indexing method is determined to be Reach rather than Choose since E is a vector, not a matrix as would be required for Choose. Observe that:

      ⊂2 1 ←→ ⊂(⊂2),(⊂1)


Selective Specification

Assignment (Selective)

(EXP X)←Y

X is the name of a variable in the workspace.   EXP is an expression that selects elements of X.  Y is an array expression. The result of the expression Y is allocated to the elements of X selected by EXP.

The following functions may appear in the selection expression.  Where appropriate these functions may be used with axis [].

↑ | Take
↓ | Drop
, | Ravel
⌽ | Reverse, Rotate
⍴ | Reshape
⊃ | Disclose, Pick
⍉ | Transpose (Monadic and Dyadic)
/ | Replicate
\ | Expand
⌷ | Index

Note that Mix and Split (monadic ↑ and ↓)
may not be used in the selection expression.

Examples :

      A←'HELLO'
      ((A∊'AEIOU')/A)←'*'

      A
H*LL*

      Z←3 4⍴⍳12
      (5↑,Z)←0

      Z
0  0  0  0
0  6  7  8
9 10 11 12

      MAT←3 3⍴⍳9
      (1 1⍉MAT)←0

      MAT
0 2 3
4 0 6
7 8 0


Modified Assignment

Assignment (Modified)

{R}←Xf←Y

f may be any dyadic function which returns an explicit result.  Y may be any array whose items are appropriate to function f.  X must be the name of an existing array whose items are appropriate to function f.

R is the 'pass-through' value, that is, the value of Y. If the result of the derived function is not assigned or used, there is no explicit result.

The effect of the derived function is to reset the value of the array named by X to the result of XfY.

Examples:

      A
1 2 3 4 5

      A+←10

      A
11 12 13 14 15

      ⎕←A×←2
2

      A
22 24 26 28 30

      vec←¯4+9?9 ⋄ vec
3 5 1 ¯1 ¯2 4 0 ¯3 2
      vec/⍨←vec>0 ⋄vec
3 5 1 4 2


Modified Indexed Assignment

Assignment (Mod.Ind.)

{R}←X[I]f←Y

f may be any dyadic function which returns an explicit result.  Y may be any array whose items are appropriate to function f.  X must be the name of an existing array.  I must be a valid index specification.  The items of the indexed portion of X must be appropriate to function f.

R is the 'pass-through' value, that is, the value of Y. If the result of the derived function is not assigned or used, there is no explicit result.

The effect of the derived function is to reset the indexed elements of X, that is X[I], to the result of X[I]fY.  This result must have the same shape as X[I].

Examples:

      A
1 2 3 4 5

      +A[2 4]+←1
1

      A
1 3 3 5 5

      A[3]÷←2

      A
1 3 1.5 5 5

If an index is repeated, function f will be applied to the successive values of the indexed elements of X, taking the index occurrences in left-to-right order.

Example:

      B←5⍴0

      B[2 4 1 2 1 4 2 4 1 3]+←1

      B
3 3 1 3 0


Modified Selective Specification

Assignment (Mod.Sel.)

{R}←(EXP X)f←Y

f may be any dyadic function which returns an explicit result.  Y may be any array whose items are appropriate to function f.  X must be the name of an existing array.  EXP is an expression that selects elements of X.  The selected elements of X must be appropriate to function f.

R is the 'pass-through' value, that is, the value of Y. If the result of the derived function is not assigned or used, there is no explicit result.

The effect of the derived function is to reset the selected elements of X to the result of X[I]fY where X[I] defines the elements of X selected by EXP.

Example:

      A
12 36 23 78 30

      ((A>30)/A) ×← 100
      A
12 3600 23 7800 30


Axis (monadic)

Axis Operator

R←f[B]Y

f must be a monadic primitive function from those shown in figure below, or a function derived from the operators Reduction (/) or Scan (\). B must be a numeric scalar or single-element vector. Y may be any array whose items are appropriate to function f. Axis does not follow the normal syntax of an operator.

In most cases, B is required to be an integer which identifies a specific axis of Y. An exception occurs when f is the Mix function (↑) in which case B is a fractional value whose lower and upper integer bounds select an adjacent pair of axes of Y or an extreme axis of Y.

⎕IO is an implicit argument of the derived function which determines the meaning of B.

Function | Name | Range of B
⌽ or ⊖ | Reverse | B∊⍳⍴⍴Y
↑ | Mix | (0≠1|B)∧(B>⎕IO-1)∧(B<⎕IO+⍴⍴Y)
↓ | Split | B∊⍳⍴⍴Y

Primitive monadic functions with an optional axis specification.

Examples:

      ⌽[1]2 3⍴⍳6
4 5 6
1 2 3

      ↑[.1]'ONE' 'TWO'
OT
NW
EO


Axis (dyadic)

Dyadic Axis Operator

R←X f[B]Y

f must be a dyadic primitive scalar function, or a dyadic primitive function included in figure below. B must be a numeric scalar or single element vector. X and Y may be any arrays whose items are appropriate to function f. Axis does not follow the normal syntax of an operator.

In most cases, B must be an integer value identifying the axis of X and Y along which function f is to be applied. Exceptionally, B must be a fractional value for the Laminate function (,) whose upper and lower integer bounds identify a pair of axes or an extreme axis of X and Y.

⎕IO is an implicit argument of the derived function which determines the meaning of B.

Function | Name | Range of B
/ or ⌿ | Replicate | B∊⍳⍴⍴Y
\ or ⍀ | Expand | B∊⍳⍴⍴Y
⊂ | Partitioned enclose | B∊⍳⍴⍴Y
⌽ or ⊖ | Rotate | B∊⍳⍴⍴Y
, or ⍪ | Catenate | B∊⍳⍴⍴Y
, | Laminate | (0≠1|B)∧(B>⎕IO-1)∧B<⎕IO+(⍴⍴X)⌈⍴⍴Y

Figure : Primitive dyadic functions with an optional axis specification.

Examples:

      2 ¯2 1/[2]2 3⍴'ABCDEF'
AA  C
DD  F

      'ABC',[1.1]'='
A=
B=
C=

      'ABC',[0.1]'='
ABC
===

      ⎕IO←O

      'ABC',[¯0.5]'='
ABC
===

Axis with Scalar Dyadic Functions

The axis operator [X] can take a scalar dyadic function as operand. This has the effect of stretching a lower rank array to fit a higher rank one. The arguments must be conformable along the specified axis (or axes) with elements of the lower rank array being replicated along the other axes.

For example, if H is the higher rank array, L the lower rank one, X is an axis specification, and f a scalar dyadic function, then the expressions Hf[X]L and Lf[X]H are conformable if (⍴L)←→(⍴H)[X]. Each element of L is replicated along the remaining (⍴H)~X axes of H.

In the special case where both arguments have the same rank, the right one will play the role of the higher rank array. if R is the right argument, L the left argument, X is an axis specification and f a scalar dyadic function, then the expression Lf[X]R is conformable if (⍴L)←→(⍴R)[X].


Namespaces

Namespace is a (class 9) object in Dyalog APL. Namespaces are analogous to nested workspaces.

'Flat' APL Workspace      Workspace with Namespaces

.OLD-------------------.   .NEW-------------------.
|                      |   | FOO MAT VEC          |
| DISPLAY              |   | .Util----------.     |
|                      |   | |DISPLAY       |     |
|   FOO MAT VEC        |   | |...           |     |
|                      |   | '--------------'     |
|   WsDoc_Init         |   | .WsDoc-------------. |
|   WsDoc_Xref         |   | |Init .prt-..fmt--.| |
|   WsDoc_Tree         |   | |     |Init||line || |
|   WsDoc_prt_init     |   | |Tree |    ||     || |
|   WsDoc_current_page |   | |Xref |page||     || |
|   ...                |   | |     '----''-----'| |
|                      |   | '------------------' |
'----------------------'   '----------------------'

They provide the same sort of facility for workspaces as directories do for filing systems. The analogy might prove helpful:

Operation | MS-DOS | Namespace
Create | MKDIR | )NSor ⎕NS
Change | CD | )CS or ⎕CS
Relative name | DIR1\DIR2\FILE | NS1.NS2.OBJ
Absolute name | \DIR\FILE | #.NS.OBJ
Name separator | \ | .
Top (root) object | \ | >#
Parent object | .. | ##

Namespaces bring a number of major benefits:

They provide static (as opposed to dynamic) local names. This means that a defined function can use local variables and functions which persist when it exits and which are available next time it is called.

Just as with the provision of directories in a filing system, namespaces allow us to organise the workspace in a tidy fashion. This helps to promote an object oriented programming style.

APL's traditional name-clash problem is ameliorated in several ways:

Workspaces can be arranged so that there are many fewer names at each namespace level. This means that when copying objects from saved workspaces there is a much reduced chance of a clash with existing names.

Utility functions in a saved workspace may be coded as a single namespace and therefore on being copied into the active workspace consume only a single name. This avoids the complexity and expense of a solution which is sometimes used in 'flat' workspaces, where such utilities dynamically fix local functions on each call.

In flat APL, workspace administration functions such as WSDOC must share names with their subject namespace. This leads to techniques for trying to avoid name clashes such as using obscure name prefixes like '⍙⍙L1'. This problem is now virtually eliminated because such a utility can operate exclusively in its own namespace.

The programming of GUI objects is considerably simplified:

An object's callback functions may be localised in the namespace of the object itself.

Static variables used by callback functions to maintain information between calls may be localised within the object.

This means that the object need use only a single name in its namespace.


Namespace Syntax

Names within namespaces may be referenced explicitly or implicitly. An explicit reference requires that you identify the object by its full or relative pathname using a '.' syntax; for example:

      X.NUMB ← 88

sets the variable NUMB in namespace X to 88.

      88 UTIL.FOO 99

calls dyadic function FOO in namespace UTIL with left and right arguments of 88 and 99 respectively. The interpreter can distinguish between this use of '.' and its use as the inner product operator, because the leftmost name: UTIL is a (class 9) namespace, rather than a (class 3) function.

The general namespace reference syntax is:

      SPACE . SPACE . (...) EXPR

Where SPACE is an expression which resolves to a namespace reference, and EXPR is any APL expression to be resolved in the resulting namespace.

There are three special space names:

  • # is the top level or 'root' namespace.
  • ## is the parent or space containing the current namespace.
  • ⎕SE is a system namespace which is preserved across workspace load and clear.

Examples

      WSDOC.PAGE.NO + 1           Increment WSDOC page count.
      #.⎕NL 2                      Variables in root space.
      UTIL.⎕FX ZDUP A ZA A   Fix remote function.
      ##.⎕EDFOO                  Edit function in parent space
      ⎕SE.RECORD  PERS.RECORD     Copy RECORD from PERS to ⎕SE.
      UTIL.(⎕EX ⎕NL 2)            ⍝ Expunge variables in UTIL.
      (⊃⎕SE #).(⍎⊃↓⎕NL 9).(⎕NL 2) ⍝ Vars in first ⎕SE namespace.
      UTIL.⍎STRING                ⍝ Execute STRING in UTIL space.

You may also reference a function or operator in a namespace implicitly using the mechanism provided by ⎕EXPORT and ⎕PATH. If you reference a name that is undefined in the current space, the system searches for it in the list of exported names defined for the namespaces specified by ⎕PATH.


Namespace Reference Evaluation

When the interpreter encounters a namespace reference, it :

  1. Switches to the namespace.
  2. Evaluates the name.
  3. Switches back to the original namespace.

If for example, in the following, the current namespace is #.W, the interpreter evaluates the line:

      A ← X.Y.DUP MAT

in the following way:

  1. Evaluate array MAT in current namespace W to produce argument for function.
  2. Switch to namespace X.Y within W,
  3. Evaluate function DUP in namespace W.X.Y with argument.
  4. Switch back to namespace W,
  5. Assign variable A in namespace W.


Namespaces and Localisation

The rules for name resolution have been generalised for namespaces.

In flat APL, the interpreter searches the state indicator to resolve names referenced by a defined function or operator. If the name does not appear in the state indicator, then the workspace-global name is assumed.

With namespaces, a defined function or operator is evaluated in its home namespace. When a name is referenced, the interpreter searches only those lines of the state indicator which belong to the home namespace. If the name does not appear in any of these lines, the home namespace-global value is assumed.

For example, if #.FN1 calls XX.FN2 calls #.FN3 calls XX.FN4, then:

FN1:
is evaluated in #
can see its own dynamic local names
can see global names in #
FN2:
is evaluated in XX
can see its own dynamic local names
can see global names in XX
FN3:
is evaluated in #
can see its own dynamic local names
can see dynamic local names in FN1
can see global names in #
FN4:
is evaluated in XX
can see its own dynamic local names
can see dynamic local names in FN2
can see global names in XX


Namespace References

A namespace reference, or ref for short, is a unique data type that is distinct from and in addition to number and character.

Any expression may result in a ref, but the simplest one is the namespace itself:

      )NS NS1          ⍝ Make a namespace called NS1
      NS1.A←1          ⍝ and populate it with variables A
      NS1.B←2 3⍴⍳6     ⍝ and B
      NS1              ⍝ expression results in a ref
#.NS1

You may assign a ref ; for example:

      X←NS1
      X
#.NS1

In this case, the display of X informs you that X refers to the named namespace #.NS1.

You may also supply a ref as an argument to a defined or dynamic function:

     ∇ FOO ARG
[1]    ARG
     ∇

      FOO NS1
#.NS1

The name class of a ref is 9.

      ⎕NC 'X'
9

You may use a ref to a namespace anywhere that you would use the namespace itself. For example:

      X.A
1
      X.B
1 2 3
4 5 6

Notice that refs are references to namespaces, so that if you make a copy, it is the reference that is copied, not the namespace itself. This is sometimes referred to as a shallow as opposed to a deep copy. It means that if you change a ref, you actually change the namespace that it refers to.

      X.A+←1
      X.A
2
      NS1.A
2

Similarly, a ref passed to a defined function is call-by-reference, so that modifications to the content or properties of the argument namespace using the passed reference, persist after the function exits. For example:

     ∇ FOO nsref
[1]    nsref.B+←nsref.A
     ∇

      FOO NS1
      NS1.B
3 4 5
6 7 8
      FOO X
      NS1.B
5 6  7
8 9 10

Notice that the expression to the right of a dot may be arbitrarily complex and will be executed within the namespace or ref to the left of the dot.

      X.(C←A×B)
      X.C
10 12 14
16 18 20
      NS1.C
10 12 14
16 18 20


Unnamed Namespaces

The monadic form of ⎕NS makes a new (and unique) unnamed namespace and returns a ref to it.

One use of unnamed namespaces is to represent hierarchical data structures; for example, a simple employee database:

The first record is represented by JOHN which is a ref to an unnamed namespace:

      JOHN←⎕NS ''
      JOHN
#.[Namespace]

      JOHN.FirstName←'John'
      JOHN.FirstName
John

      JOHN.LastName←'Smith'
      JOHN.Age←50

Data variables for the second record, PAUL, can be established using strand, or vector, assignment:

      PAUL←⎕NS ''
      PAUL.(FirstName LastName Age←'Paul' 'Brown' 44)

The function SHOW can be used to display the data in each record (the function is split into 2 lines only to fit on the printed page). Notice that its argument is a ref.

     ∇ R←SHOW PERSON
[1]    R←PERSON.FirstName,' ',PERSON.LastName
[2]    R, ←' is ',⍕PERSON.Age
     ∇
      SHOW JOHN
John Smith is 50
      SHOW PAUL
Paul Brown is 44

An alternative version of the function illustrates the use of the :With :EndWith control structure to execute an expression, or block of expressions, within a namespace:

     ∇ R←SHOW1 PERSON
[1]    :With PERSON
[2]        R←FirstName,' ',LastName,' is ',(⍕Age)
[3]    :EndWith
     ∇

      SHOW1 JOHN
John Smith is 50

In this case, as only a single expression is involved, it can be expressed more simply using parentheses.

     ∇ R←SHOW2 PERSON
[1]    R←PERSON.(FirstName,' ',LastName,' is ',(⍕Age))
     ∇

      SHOW2 PAUL
Paul Brown is 44

Dynamic functions also accept refs as arguments:

      SHOW3←{
        ⍵.(FirstName,' ',LastName,' is ',⍕Age)
      }

      SHOW3 JOHN
John Smith is 50


Arrays of Namespace References

You may construct arrays of refs using strand notation, catenate (,) and reshape (⍴).

      EMP←JOHN PAUL
      ⍴EMP
2

      EMP
 #.[Namespace]  #.[Namespace]

Like any other array, an array of refs has name class 2:

      ⎕NC 'EMP'
2

Expressions such as indexing and pick return refs that may in turn be used as follows:

      EMP[1].FirstName
John
      (2⊃EMP).Age
44

The each (¨) operator may be used to apply a function to an array of refs:

      SHOW¨EMP
 John Smith is 50  Paul Brown is 44

An array of namespace references (refs) to the left of a ‘.’ is expanded according to the following rule, where x and y are refs, and exp is an arbitrary expression:

      (x y).exp → (x.exp)(y.exp)

If exp evaluates to a function, the items of its argument array(s) are distributed to each referenced function. In the dyadic case, there is a 3-way distribution among: left argument, referenced functions and right argument.

Monadic function f:(x y).f d e → (x.f d)(y.f e)

Dyadic function c:a b (x y).g d e → (a x.g d)(b y.g e)

An array of refs to the left of an assignment arrow is expanded thus:

      (x y).a←c d   →  (x.a←c)(y.a←d)

Note that the array of refs can be of any rank. In the limiting case of a simple scalar array, the array construct: refs.exp is identical to the scalar construct: ref.exp.

Note that the expression to the right of the ‘.’ pervades a nested array of refs to its left:

      ((u v)(x y)).exp → ((u.exp)(v.exp))((x.exp)(y.exp))

Note also that with successive expansions (u v).(x y z). …, the final number of ‘leaf’ terms is the product of the number of refs at each level.

Examples:

      JOHN.Children←⎕NS¨'' ''
      ⍴JOHN.Children
2
      JOHN.Children[1].FirstName←'Andy'
      JOHN.Children[1].Age←23

      JOHN.Children[2].FirstName←'Katherine'
      JOHN.Children[2].Age←19

      PAUL.Children←⎕NS¨'' ''
      PAUL.Children[1].(FirstName Age←'Tom' 25)
      PAUL.Children[2].(FirstName Age←'Jamie' 22)

      ⍴EMP
2
      (⊃EMP).Children.(FirstName Age)
  Andy  23   Katherine  19

      DISPLAY (2⊃EMP).Children.(FirstName Age)
.→----------------------------.
| .→---------. .→-----------. |
| | .→--.    | | .→----.    | |
| | |Tom| 25 | | |Jamie| 22 | |
| | '---'    | | '-----'    | |
| '∊---------' '∊-----------' |
'∊----------------------------'

      EMP.Children ⍝ Is an array of refs
  #.[Namespace]  #.[Namespace]    #.[Namespace]  ...

      EMP.Children.(FirstName Age)
   Andy  23   Katherine  19     Tom  25   Jamie  22


Distributed Assignment

Assignment pervades nested strands of names to the left of the arrow. The conformability rules are the same as for scalar (pervasive) dyadic primitive functions such as ‘+’. The mechanism can be viewed as a way of naming the parts of a structure.

Examples:

     EMP.(FirstName Age)
  JOHN  43   PAUL  44

     EMP.(FirstName Age)←('Jonathan' 21)('Pauline' 22)

     EMP.(FirstName Age)
  Johnathan  21   Pauline  22

     ⍝ Distributed assignment is pervasive
     JOHN.Children.(FirstName Age)
  Andy  23   Katherine  19

     JOHN.Children.(FirstName Age)←('Andrew' 21)('Kate' 19)

     JOHN.Children.(FirstName Age)
  Andrew  21   Kate  19

More Examples:

      ((a b)(c d))←(1 2)(3 4)   ⍝ a←1 ⋄ b←2 ⋄ c←3 ⋄ d←4

      ((⎕io ⎕ml)vec)←0 ⎕av      ⍝ ⎕io←0 ⋄ ⎕ml←0 ⋄ vec←⎕av

      (i (j k))+←1 2            ⍝ i+←1 ⋄ j+←2 ⋄ k+←2

⍝ Naming of parts:

      ((first last) sex (street city state))←n⊃pvec

⍝ Distributed assignment in :For loop:

      :For (i j)(k l) :In array

⍝ Ref array expansion:

      (x y).(first last)←('John' 'Doe')('Joe' 'Blow')
(f1 f2).(b1 b2).Caption←⊂'OK' 'Cancel'


Namespaces and Operators

A function passed as operand to a primitive or defined operator, carries its namespace context with it. This means that if subsequently, the function operand is applied to an argument, it executes in its home namespace, irrespective of the namespace from which the operator was invoked or defined.

Examples:

      VAR←99                     ⍝ #.VAR

      )NS X
#.X
      X.VAR←77                   ⍝ X.VAR
      X.⎕FX'Z←FN R' 'Z←R,VAR'

      )NS Y
#.Y
      Y.VAR←88                   ⍝ Y.VAR
      Y.⎕FX'Z←(F OP)R' 'Z←F R'

      X.FN¨⍳3
 1 77  2 77  3 77>

      X.FN 'VAR:'
 VAR: 77

      X.FN Y.OP 'VAR:'
 VAR: 77
      ⍎ Y.OP'VAR'
99


Workspaces

APL expressions are evaluated within a workspace. The workspace may contain objects, namely operators, functions and variables defined by the user. APL expressions may include references to operators, functions and variables provided by APL. These objects do not reside in the workspace, but space is required for the actual process of evaluation to accommodate temporary data. During execution, APL records the state of execution through the STATE INDICATOR which is dynamically maintained until the process is complete. Space is also required to identify objects in the workspace in the SYMBOL TABLE. Maintenance of the symbol table is entirely dynamic. It grows and contracts according to the current workspace Contents.

Workspaces may be explicitly saved with an identifying name. The workspace may subsequently be loaded, or objects may be selectively copied from a saved workspace into the current workspace.

Under UNIX workspace names must be valid file names, but are otherwise unrestricted. See your UNIX documentation for details.

Under DOS, Dyalog APL workspaces are stored in files with the suffix ".DWS". However, they are referred to from within APL by only the first part of the file name which must conform to DOS file naming rules.


Expressions

An expression is a sequence of one or more syntactic tokens which may be symbols or constants or names representing arrays (variables) or functions. An expression which produces an array is called an ARRAY EXPRESSION. An expression which produces a function is called a FUNCTION EXPRESSION. Some expressions do not produce a result.

An expression may be enclosed within parentheses.

Evaluation of an expression proceeds from right to left, unless modified by parentheses. If an entire expression results in an array that is not assigned to a name, then that array value is displayed. (Some assigned to a name or if the result is the argument of a function or operator.)

Examples

      X←2×3-1

      2×3-1
4
      (2x3)-1
5

Either blanks or parentheses are required to separate constants, the names of variables, and the names of defined functions which are adjacent. Excessive blanks or sets of parentheses are redundant, but permitted. If F is a function, then:

    F 2←→ F(2) ←→ (F)2 ←→ (F) (2) ←→ F  (2) ←→ F ((2))

Blanks or parentheses are not needed to separate primitive functions from names or constants, but they are permitted:

      -2 ←→ (-)(2) ←→ (-) 2

Blanks or parentheses are not needed to separate operators from primitive functions, names or constants. They are permitted with the single exception that a dyadic operator must have its right argument available when encountered. The following syntactical forms are accepted:

      (+.×) ←→ (+).× ←→ +.(×)

The use of parentheses in the following examples is not accepted:

+(.)× or (+.)×


Statements

A statement is a line of characters understood by APL. It may be composed of:

  1. a LABEL (which must be followed by a colon)
  2. an EXPRESSION
  3. a SEPARATOR (consisting of the diamond character ⋄ which must separate adjacent expressions)
  4. a COMMENT (which must start with the character ⍝)

Each of the four parts is optional, but if present they must occur in the given order except that successive expressions must be separated by ⋄. Any characters occurring to the right of the first comment symbol (⍝) that is not within quotes is a comment.

Comments are not executed by APL. Expressions in a line separated by ⋄ are taken in left-to-right order as they occur in the line. For output display purposes, each separated expression is treated as a separate statement.

Examples

      5x10
50

      MULT: 5x10
50

      MULT: 5x10 ⋄ 2x4
50
8

      MULT: 5×10 ⋄ 2x4  ⍝ MULTIPLICATION
50
8


Defined Functions

Functions may be defined with the system function ⎕FX, or with the function editor. A function consists of a HEADER which identifies the syntax of the function, and a BODY in which one or more APL statements are specified.

The header syntax identifies the function name, its (optional) result and its (optional) arguments. If a function is ambivalent, it is defined with two arguments but with the left argument within braces ({}). If an ambivalent function is called monadically, the left argument has no value inside the function. If the explicit result is to be suppressed for display purposes, the result is shown within braces. A function need not produce an explicit result.

Example

     ∇ R←{A} FOO B
[1]    R←⊃'MONADIC' 'DYADIC'[⎕IO+0≠⎕NC'A']
[2]  ∇

      FOO 1
MONADIC

      'X' FOO 'Y'
DYADIC

Note that the right argument and result may be specified by a single name or by a Namelist.

Functions may also be created by using assignment (←).


Defined Operators

Operators may be defined with the system function ⎕FX, or with the function editor. A defined operator consists of a HEADER which identifies the syntax of the operator, and a BODY in which one or more APL statements are specified.

A defined operator may have one or two operands; and its derived function may have one or two arguments, and may or may not produce a result. The header syntax defines the operator name, its operand(s), the argument(s) to its derived function, and the result (if any) of its derived function. The names of the operator and its operand(s) are separated from the name(s) of the argument(s) to its derived function by parentheses.

Example

      ∇ R←A(F AND G)B
[1]     R←(A F B)(A G B)
      ∇

The above example shows a dyadic operator called AND with two operands (F and C). The operator produces a derived function which takes two arguments (A and B), and produces a result (R).

      12 +AND÷ 4
16 3

Operands passed to an operator may be either functions or arrays.

      12 (3 AND 5) 4
12 3 4  12 5 4

      12 (× AND 5) 4
48  12 5 4


Names & Local Names

Global and Local Names

The following names, if present, are local to the defined operation:

  1. the result
  2. the argument(s) and operand(s)
  3. additional names in the header line following the model, each name preceded by a semi-colon character
  4. labels
  5. the argument list of the system function ⎕SHADOW when executed,
  6. a name assigned within a Dynamic Function.

All names in a defined operation must be valid APL names. The same name may be repeated in the header line, including the operation name (whence the name is localised). Normally, the operation name is not a local name.

The same name may not be given to both arguments or operands of a dyadic operation. The name of a label may be the same as a name in the header line. More than one label may have the same name. When the operation is executed, local names in the header line after the model are initially undefined; labels are assigned the values of line numbers on which they occur, taken in order from the last line to the first; the result (if any) is initially undefined.

In the case of a defined function, the left argument (if any) takes the value of the array to the left of the function when called; and the right argument (if any) takes the value of the array to the right of the function when called. In the case of a defined operator, the left operand takes the value of the function or array to the left of the operator when called; and the right operand (if any) takes the value of the function or array to the right of the operator when called.

During execution, a local name temporarily excludes from use an object of the same name with an active definition. This is known as LOCALISATION or SHADOWING. A value or meaning given to a local name will persist only for the duration of execution of the defined operation (including any time whilst the operation is halted). A name which is not local to the operation is said to be GLOBAL. A global name could itself be local to a pendent operation. A global name can be made local to a defined operation during execution by use of the system function ⎕SHADOW. An object is said to be VISIBLE if there is a definition associated with its name in the active environment.

Examples:

      A←1

      ∇F
[1]  A←10
[2]  ∇

      F
      ⍝ <A> NOT LOCALISED IN <F>, GLOBAL VALUE REPLACED
      A
10

      A←1

      )ERASE F

      ∇F;A
[1]  A←10
[2]  ∇
      F
      ⍝ <A> LOCALISED IN <F>, GLOBAL VALUE RETAINED
      A
1

Any statement line in the body of a defined operation may begin with a LABEL. A label is followed by a colon (:). A label is a constant whose value is the number of the line in the operation defined by system function ⎕FX or on closing definition mode.

The value of a label is available on entering an operation when executed, and it may be used but not altered in any expression.

Example:

      ⎕VR'PLUS'
    ∇ R←{A} PLUS B
[1]   →DYADIC ⍴⍨2=⎕NC'A' ⋄ R←B ⋄ →END
[2]  DYADIC: R←A+B
[3]  END:
    ∇

      1 ⎕STOP'PLUS'

      2 PLUS 2

PLUS[1]
      DYADIC
2

      END
3


Namelists

The right argument and the result of a function may be specified in the function header by a single name or by a Namelist. In this context, a Namelist is a blank-delimited list of names surrounded by a single set of parentheses.

Names specified in a Namelist are automatically local to the function; there is no need to localise them explicitly using semi-colons.

If the right argument of a function is declared as a Namelist, the function will only accept a right argument that is a vector whose length is the same as the number of names in the Namelist. Calling the function with any other argument will result in a LENGTH ERROR in the calling statement. Otherwise, the elements of the argument are assigned to the names in the Namelist in the specified order.

Example:

     ∇ IDN←Date2IDN(Year Month Day)
[1]    'Year is ',⍕Year
[2]    'Month is ',⍕Month
[3]    'Day is ',⍕Day
[4] ...
     ∇
      Date2IDN 2004 4 30
Year is 2004
Month is 4
Day is 30
      Date2IDN 2004 4
LENGTH ERROR
      Date2IDN 2004 4
     ∧

Note that if you specify a single name in the Namelist, the function may be called only with a 1-element vector or a scalar right argument.

If the result of a function is declared as a Namelist, the values of the names will automatically be stranded together in the specified order and returned as the result of the function when the function terminates.

Example:

     ∇ (Year Month Day)←Birthday age
[1]    Year←1949+age
[2]    Month←4
[3]    Day←30
     ∇
      Birthday 50
1999 4 30


Locked Functions & Operators

Locked Functions and Operators

A defined operation may be locked by the system function ⎕LOCK. A locked operation may not be displayed or edited. The system function ⎕CR returns an empty matrix of shape 0 0 and the system functions ⎕NR and ⎕VR return an empty vector for a locked operation.

Stop, trace and monitor settings may be established by the system functions ⎕STOP, ⎕TRACE and ⎕MONITOR respectively. Existing stop, trace and monitor settings are cancelled when an operation is locked.

A locked operation may not be suspended, nor may a locked operation remain pendent when execution is suspended. The state indicator is cut back as described below.

Execution Characteristics

The state of execution is dynamically recorded in the STATE INDICATOR. The state indicator identifies the chain of execution for operators, functions and the evaluated or character input/output system variables (⎕ and ⍞). At the top of the state indicator is the most recently activated operation.

Execution may be suspended by an interrupt, induced by the user, the system, or by a signal induced by the system function ⎕SIGNAL or by a stop control set by the system function ⎕STOP. If the interrupt (or event which caused the interrupt) is not defined as a trappable event by the system variable ⎕TRAP, the state indicator is cut back to the first of either a defined operation or the evaluated input prompt (⎕) such that there is no locked defined operation in the state indicator. The topmost operation left in the state indicator is said to be SUSPENDED. Other operations in the chain of execution are said to be PENDENT.

The state indicator may be examined when execution is suspended by the system commands )SI and )SINL. The line numbers of defined operations in the state indicator are given also by the system variable ⎕LC.

Suspended execution may be resumed by use of the Branch function. Whilst execution is suspended, it is permitted to enter any APL expression for evaluation, thereby adding to the existing state indicator. Therefore, there may be more than one LEVEL OF SUSPENSION in the state indicator. If the state indicator is cut back when execution is suspended, it is cut back no further than the prior level of suspension (if any).

Examples:

     ∇ F
[1]    G
     ∇

     ∇ G
[1]    'FUNCTION G'+
     ∇

      ⍎'F'
SYNTAX ERROR
G[1] 'FUNCTION G'+
     ∧

      )SI
G[1]*
F[1]
⍎

      ⎕LOCK'G'

      ⍎'F'
SYNTAX ERROR
F[1] G
     ∧

      )SI
F[1]*
⍎
G[1]*
F[1]
⍎

A suspended or pendent operation may be edited by the system editor or redefined using ⎕FX provided that it is visible and unlocked. However, pendent operations retain their original definition until they complete, or are cleared from the State Indicator. When a new definition is applied, the state indicator is repaired if necessary to reflect changes to the operations, model syntax, local names, or labels.


Search Functions and Hash Tables

Primitive dyadic search functions, such as ⍳(index of) and ∊ (membership) have a principal argument in which items of the other subject argument are located.

In the case of ⍳, the principal argument is the one on the left and in the case of ∊, it is the one on the right. The following table shows the principal (P) and subject (s) arguments for each of the functions.

P ⍳ s | Index of
s ∊ P | Membership
s ∩ P | Intersection
P ∪ s | Union
s ~ P | Without
P {(↓⍺)⍳↓⍵} s | Matrix Iota (idiom)

The Dyalog APL implementation of these functions already uses a technique known as hashing to improve performance over a simple linear search.

(Note that although ⍷ (find) is a primitive dyadic search function, it does not employ the same hashing technique, and is excluded from this discussion.)

Building a hash table for the principal argument takes a significant time but is rewarded by a considerably quicker search for each item in the subject. Unfortunately, the hash table is discarded each time the function completes and must be reconstructed for a subsequent call (even if its principal argument is identical to that in the previous one).

For optimal performance of repeated search operations the hash table may be retained between calls, by binding the function with its principal argument using the primitive ∘ (compose) operator. The retained hash table is then used directly whenever this monadic derived function is applied to a subject argument.

Notice that retaining the hash table pays off only on a second or subsequent application of the derived function. This usually occurs in one of two ways: either the derived function is named for later (and repeated) use, as in the first example below or it is applied repeatedly as the operand of a primitive or defined operator, as in the second example.

Example: naming a derived function.

      words←'red' 'ylo' 'grn' 'brn' 'blu' 'pnk' 'blk'

      find←words∘⍳          ⍝ monadic find function
      find'blk' 'blu'       ⍝ fast find
7 5
      find'grn' 'brn' 'ylo' ⍝ hash table re-used.
3 4 2

Example: repeated application by (¨) each operator.

      ∊∘⎕A¨'This' 'And' 'That'
1 0 0 0  1 0 0  1 0 0 0


Idiom Recognition TOC

Idiom Recognition

Idioms are commonly used expressions that are recognised and evaluated internally, providing a significant performance improvement.

For example, in earlier Versions of Dyalog APL, the idiom BV/⍳⍴A (where BV is a Boolean vector and A is an array) would previously have been evaluated in 3 steps as follows:

  1. Evaluate ⍴A and store result in temporary variable temp1 (temp1 is just an arbitrary name for the purposes of this explanation)
  2. Evaluate ⍳temp1 and store result in temporary variable temp2.
  3. Evaluate BV/temp2
  4. Discard temporary variables

In the current Version of Dyalog APL, the idiom expression is recognised in its entirety and processed in a single step as if it were a single primitive function . In this case, the resultant improvement in performance is between 2 and 4.5.

Idiom recognition is precise; an expression that is almost identical but not exactly identical to an expression given in the Idiom List table will not be recognised.

For example, ⎕AV⍳ will be recognised as an idiom, but (⎕AV)⍳ will not. Similarly, (,)/ would not be recognized as the Join idiom.


Idiom List

In the following table, arguments to the idiom have types and ranks as follows:

Type | Description | Rank | Description
C | Character | S | Scalar or 1-item vector
B | Boolean | V | Vector
N | Numeric | M | Matrix
P | Nested (pointer) | A | Array (any rank)
A | Any type |  |

For example: NV: numeric vector, CM: character matrix, PV: nested vector.

Expression | Description
⍴⍴A | Rank
BV/⍳NS | Sequence selection
BV/⍳⍴A | Index selection
NA⊃¨⊂A | Array selection
A{}A | Sink
A{⍺}A | Left (Lev)
A{⍵}A | Right (Dex)
A{⍺ ⍵}A | Link
{0}A | Zero
{0}¨A | Zero Each
,/PV | Join
⊃⌽A | Upper right item (⎕ml<2)
↑⌽A | Upper right item (⎕ml≥2)
⊃⌽,A | Lower right item (⎕ml<2)
↑⌽,A | Lower right item (⎕ml≥2)
0=⍴V | Zero shape
0=⍴⍴A | Zero rank
0=≡A | Zero depth
⎕AV⍳CA | Atomic vector index. (Classic Edition only; use ⎕UCS)
M{(↓⍺)⍳↓⍵}M | Matrix Iota
↓⍉↑PV | Nested vector transpose (⎕ml<2)
↓⍉⊃PV | Nested vector transpose (⎕ml≥2)
∧\' '=CA | Mask of leading blanks.
+/∧\' '=CA | Number of leading blanks
+/∧\BA | Number of leading ones
{(∨\' '≠⍵)/⍵}CV | Trim leading blanks
{(+/∧\' '=⍵)↓⍵}CV> | Trim leading blanks
~∘' '¨↓CA | No-blank split
{(+/∨\' '≠⌽⍵)↑¨↓⍵}CA | No-trailing-blank split
⊃∘⍴¨A | Length of first axis of each sub-array (⎕ml<2)
↑∘⍴¨A | Length of first axis of each sub-array (⎕ml≥2)
V,←A | Catenate To


Version Issues

Idioms are recognised when a function is fixed by the function editor, or by ⎕FX. This means that as soon as you edit and save a function, any idioms the function uses will automatically be identified and optimised.

Functions in workspaces saved by a previous version of Dyalog APL are automatically re-fixed when the workspace is loaded. In a large workspace, this can take some time, so it makes sense to re-save your workspaces (using the latest Version) even if you are not otherwise changing them. However, please note that, as usual, saving a workspace with this Version renders the workspace unloadable by any previous version.


Control Structures Introduction

Control Structures

Control structures provide a means to control the flow of execution in your APL programs.

Traditionally, lines of APL code are executed one by one from top to bottom and the only way to alter the flow of execution is using the branch arrow. So how do you handle logical operations or the form “If this, do that; otherwise do the other”?.

In APL this is often not a problem because many logical operations are easily performed using the standard array handling facilities that are absent in other languages. For example, the expression:

      STATUS←(1+AGE<16)⊃'Adult' 'Minor'

sets STATUS to 'Adult' if AGE is 16 or more; otherwise sets STATUS to 'Minor'.

Things become trickier if, depending upon some condition, you wish to execute one set of code instead of another, especially when the code fragments cannot conveniently be packaged as functions. Nevertheless, careful use of array logic, defined operators, the execute primitive function and the branch arrow can produce high quality maintainable and comprehensible APL systems.

Control structures provide an additional mechanism for handling logical operations and decisions. Apart from providing greater affinity with more traditional languages, Control structures may enhance comprehension and reduce programming errors, especially when the logic is complex. Control structures are not, however, a replacement for the standard logical array operations that are so much a part of the APL language.


Control Structures Summary

Introduction

Control Structures are blocks of code in which the execution of APL statements follows certain rules and conditions. Control structures are implemented using a set of control words which all start with the colon symbol (:). Control Words are case-insensitive.

There are eight different types of control structures defined by the control words, :If, :While, :Repeat, :For, :Select, :With, :Hold, and :Trap respectively. Each one of these control words may occur only at the beginning of an APL statement and indicates the start of a particular type of control structure.

Within a control structure, certain other control words are used as qualifiers. These are :Else, :ElseIf, :AndIf, :OrIf, :Until, :Case and :CaseList.

A third set of control words is used to identify the end of a particular control structure. These are :EndIf, :EndWhile, :EndRepeat, :EndFor, and :EndSelect. Although formally distinct, these control words may all be abbreviated to :End.

Finally, the :GoTo, :Return, :Leave and :Continue control words may be used to conditionally alter the flow of execution within a control structure.

Control words, including qualifiers such as :Else and :ElseIf, may occur only at the beginning of a line or expression in a diamond-separated statement. The only exceptions are :In and :InEach which must appear on the same line within a :For expression.


:If Statement

Formal Definition

The simplest :If control structure is a single condition of the form:

[1]   :If AGE<21
[2]       expr 1
[3]       expr 2
[5]   :EndIf

If the test condition (in this case ACE<21) is true, the statements between the :If and the :EndIf will be executed. If the condition is false, none of these statements will be run and execution resumes after the :EndIf. Note that the test condition to the right of :If must return a single element Boolean value 1 (true) or 0 (false).

:If control structures may be considerably more complex. For example, the following code will execute the statements on lines [2–3] if ACE<21 is 1 (true), or alternatively, the statement on line [6] if ACE<21 is 0 (false).

[1]   :If AGE<21
[2]       expr 1
[3]       expr 2
[5]   :Else
[6]       expr 3
[7]   :EndIf

Instead of a single condition, it is possible to have multiple conditions using the :ElseIf control word. For example,

[1]   :If WINEAGE<5
[2]       'Too young to drink'
[5]   :ElseIf WINEAGE<10
[6]       'Just Right'
[7]   :ElseIf WINEAGE<15
[8]       'A bit past its prime'
[9]   :Else
[10]     'Definitely over the hill'
[11]  :EndIf

Notice that APL executes the expression(s) associated with the first condition that is true or those following the :Else if none of the conditions are true.

The :Andif and :Orif control words may be used to define a block of conditions and so refine the logic still further. You may qualify an :If or an :ElseIf with one or more :AndIf statements or with one or more :OrIf statements. You may not however mix :Andif and :Orif in the same conditional block. For example:

[1]   :If WINE.NAME'Chateau Lafitte'
[2]   :AndIf WINE.YEAR∊1962 1967 1970
[3]       'The greatest?'
[4]   :ElseIf WINE.NAME'Chateau Latour'
[5]   :Orif WINE.NAME'Chateau Margaux'
[6]   :Orif WINE.PRICE>100
[7]       'Almost as good'
[8]   :Else
[9]       'Everyday stuff'
[10]  :EndIf

Please note that in a :If control structure, the conditions associated with each of the condition blocks are executed in order until an entire condition block evaluates to true. At that point, the APL statements following this condition block are executed. None of the conditions associated with any other condition block are executed. Furthermore, if an :AndIf condition yields 0 (false), it means that the entire block must evaluate to false so the system moves immediately on to the next block without executing the other conditions following the failing :AndIf. Likewise, if an :OrIf condition yields 1 (true), the entire block is at that point deemed to yield true and none of the following :Orif conditions in the same block are executed.


:While Statement

Formal Definition

The simplest :While loop is :

[1]   I←0
[2]   :While I<100
[3]       expr1
[4]       expr2
[5]       I←I+1
[6]   :EndWhile

Unless expr1 or expr2 alter the value of I, the above code will execute lines [3–4] 100 times. This loop has a single condition; the value of I. The purpose of the :EndWhile statement is solely to mark the end of the iteration. Its acts the same as if it were a branch statement, branching back to the :While line.

An alternative way to terminate a :While structure is to use a :Until statement. This allows you to add a second condition. The following example reads a native file sequentially as 80-byte records until it finds one starting with the string 'Widget' or reaches the end of the file.

[1]   I←0
[2]   :While I<⎕NSIZE ¯1
[3]       REC←⎕NREAD ¯1 82 80
[4]       I←I+⍴REC
[5]   :Until 'Widget'≢6⍴REC

Instead of single conditions, the tests at the beginning and end of the loop may be defined by more complex ones using :AndIf and :OrIf. For example:

[1]   :While 100>i
[2]   :AndIf 100>j
[3]       i j←foo i j
[4]   :Until 100<i+j
[5]   :OrIf i<0
[6]   :OrIf j<0

In this example, there are complex conditions at both the start and the end of the iteration. Each time around the loop, the system tests that both i and j are less than or equal to 100. If either test fails, the iteration stops. Then, after i and j have been recalculated by foo, the iteration stops if i+j is equal to or greater than 100, or if either i or j is negative.


:Repeat Statement

Formal Definition

The simplest type of :Repeat loop is as follows. This example executes lines [3–5] 100 times. Notice that as there is no conditional test at the beginning of a :Repeat structure, its code statements are executed at least once.

[1]   I←0
[2]   :Repeat
[3]       expr1
[4]       expr2
[5]       I←I+1
[6]   :Until I=100

You can have multiple conditional tests at the end of the loop by adding :AndIf or :OrIf expressions. The following example will read data from a native file as 80-character records until it reaches one beginning with the text string 'Widget' or reaches the end of the file.

[1]   :Repeat
[2]       REC←⎕NREAD ¯1 82 80
[3]   :Until 'Widget'≢6⍴REC
[4]   :OrIf 0=⍴REC

A :Repeat structure may be terminated by an :EndRepeat (or :End) statement in place of a conditional expression,. If so, your code must explicitly jump out of the loop using a :Leave statement or by branching. For example:

[1]   :Repeat
[2]      REC←⎕NREAD ¯1 82 80
[3]      :If 0=⍴REC
[4]      :OrIf 'Widget'6⍴REC
[5]         :Leave
[6]      :EndIf
[7]   :EndRepeat


:Continue Statement

:Continue

A :Continue statement starts the next iteration of the immediately surrounding :For, :Repeat or :While control loop.

When executed within a :For loop, the effect is to start the body of the loop with the next value of the iteration variable.

When executed within a :Repeat or :While: loop, if there is a trailing test that test is executed and, if the result is true, the loop is terminated. Otherwise the leading test is executed in the normal fashion.


:Leave Statement

:Leave

A :Leave statement is used to explicitly terminate the execution of a block of statements within a :For, :Repeat or :While control structure. The :Leave control word takes no argument.


:For Statement

Formal Definition

Single Control Variable

The :For loop is used to execute a block of code for a series of values of a particular control variable. For example, the following would execute lines [2–3] successively for values of I from ⎕IO to (9+⎕IO)

[1]   :For I :In ...10
[2]       expr1 I
[3]       expr2 I
[4]   :EndFor

The way a :For loop operates is as follows. On encountering the :For, the expression to the right of :In is evaluated and the result stored. This is the control array. The control variable, named to the right of the :For, is then assigned the first value in the control array, and the code between :For and :EndFor is executed. On encountering the :EndFor, the control variable is assigned the next value of the control array and execution of the code is performed again, starting at the first line after the :For. This process is repeated for each value in the control array.

Note that if the control array is empty, the code in the :For structure is not executed. Note too that the control array may be any rank and shape, but that its elements are assigned to the control variable in ravel order.

The control array may contain any type of data. For example, the following code resizes (and compacts) all your component files

[1]   :For FILE :In (↓⎕FLIB '')~¨' '
[3]       FILE ⎕FTIE 1
[4]       ⎕FRESIZE 1
[5]       ⎕FUNTIE 1
[6]   :EndFor

You may also nest :For loops. For example, the following expression finds the timestamp of the most recently updated component in all your component files.

[1]   TS←0
[2]   :For FILE :In (↓⎕FLIB '')~¨' '
[3]       FILE ⎕FTIE 1
[4]       START END←2⍴⎕FSIZE 1
[5]       :For COMP :In (START-1)↓⍳END-1
[6]           TS⌈←¯1↑⎕FREAD FILE COMP
[7]       :EndFor
[8]       ⎕FUNTIE 1
[9]   :EndFor

Multiple Control Variable

The :For control structure can also take multiple variables. This has the effect of doing a strand assignment each time around the loop.

For example :For a b c :in (1 2 3)(4 5 6), sets a b c←1 2 3, first time around the loop and a b c←4 5 6, the second time.

Another example is :For i j :In ⍳⍴Matrix, which sets i and j to each row and column index of Matrix.

:InEach Control Word

      :For var ... :InEach value ...

In a :For control structure, the keyword :InEach is an alternative to :In.

For a single control variable, the effect of the keywords is identical but for multiple control variables the values vector is inverted.

The distinction is best illustrated by the following equivalent examples:

      :For a b c :In (1 2 3)(3 4 5)(5 6 7)(7 8 9)
           ⎕←a b c
      :EndFor

      :For a b c :InEach (1 3 5 7)(2 4 6 8)(3 5 7 9)
           ⎕←a b c
      :EndFor

In each case, the output from the loop is:

1 2 3
3 4 5
5 6 7
7 8 9

Notice that in the second case, the number of items in the values vector is the same as the number of control variables. A more typical example might be.

      :For a b c :InEach avec bvec cvec
          ...
      :EndFor

Here, each time around the loop, control variable a is set to the next item of avec, b to the next item of bvec and c to the next item of cvec.

COM Collections

The :For ⍎ :EndFor control structure provides a convenient way to enumerate through the members of a COM collection without using the Item method.

For example, the following code snippet accumulates the values in an Excel worksheet collection.

      DATA←0⍴⊂0 0⍴0
      :For S :In Sheets  ⍝ Enumerate SHEETS collection
          DATA,←⊂S.UsedRange.Value
      :EndFor


:Select Statement

Formal Definition

A :Select structure is used to execute alternative blocks of code depending upon the value of an array. For example, the following displays 'I is 1' if the variable I has the value 1, 'I is 2' if it is 2,or 'I is neither 1 nor 2' if it has some other value.

[1]   :Select I
[2]   :Case 1
[3]       'I is 1'
[4]   :Case 2
[5]       'I is 2'
[6]   :Else
[7]       'I is neither 1 nor 2'
[8]   :EndSelect

In this case, the system compares the value of the array expression to the right of the :Select statement with each of the expressions to the right of the :Case statements and executes the block of code following the one that matches. If none match, it executes the code following the :Else (which is optional). Note that comparisons are performed using the primitive function, so the arrays must match exactly. Note also that not all of the :Case expressions are necessarily evaluated because the process stops as soon as a matching expression is found.

Instead of a :Case statement, you may also use a :CaseList statement. If so, the enclose of the array expression to the right of :Select is tested for membership of the array expression to the right of the :CaseList using the ∊ primitive function. For example:

Example:

[1]   :Select ?6 6
[2]   :Case 6 6
[3]       'Box Cars'
[4]   :Case 1 1
[5]       'Snake Eyes'
[6]   :CaseList 2⍴¨⍳6
[7]       'Pair'
[8]   :CaseList (⍳6),¨⌽⍳6
[9]       'Seven'
[10]  :Else
[11]      'Unlucky'
[12]  :EndSelect


:With Statement

Formal Definition

:With is a control structure that may be used to simplify a series of references to an object or namespace. :With changes into the specified namespace for the duration of the control structure, and is terminated by :End[With]. For example, you could update several properties of a Grid object named 'F.G' as follows:

       :With 'F.G'
            ⎕WS 'Values' (4 3⍴0)
            ⎕WS 'RowTitles' ('North' 'South' 'East' 'West')
            ⎕WS 'ColTitles' ('Cakes' 'Buns' 'Biscuits')
       :EndWith

:With is analogous to ⎕CS in the following senses:

  • The namespace argument to :With is interpreted relative to the current space.
  • Local names in the containing defined function continue to be visible in the new space.
  • Global references from within the :With control structure are to names in the new space.
  • Exiting the defined function from within a :With control structure causes the space to revert to the one from which the function was called.
  • On leaving the :With control structure, execution reverts to the original namespace. Notice however that the interpreter does not detect branches (→) out of the control structure.

:With control structures can be nested in the normal fashion:

[1]   :With 'x'           ⍝ Change to #.x
[2]       :With 'y'       ⍝ Change to #.x.y
[3]           :With '⎕SE' ⍝ Change to ⎕SE
[4]               ...     ⍝ ... in ⎕SE
[5]           :EndWith    ⍝ Back to #.x.y
[6]       :EndWith        ⍝ Back to #.x
[7]   :EndWith            ⍝ Back to #


:Hold Statement

Formal Definition

Whenever more than one thread tries to access the same piece of data or shared resource at the same time, you need some type of synchronisation to control access to that data. This is provided by :Hold.

:Hold provides a mechanism to control thread entry into a critical section of code. tkns must be a simple character vector or scalar, or a vector of character vectors. tkns represents a set of ‘tokens’, all of which must be acquired before the thread can continue into the control structure. :Hold is analogous to the component file system ⎕FHOLD.

Within the whole active workspace, a token with a particular value may be held only once. If the hold succeeds, the current thread acquires the tokens and execution continues with the first phrase in the control structure. On exit from the structure, the tokens are released for use by other threads. If the hold fails, because one or more of the tokens is already in use:

If there is no :Else clause in the control structure, execution of the thread is blocked until the requested tokens become available.

Otherwise, acquisition of the tokens is abandoned and execution resumed immediately at the first phrase in the :Else clause.

tkns can be either a single token:

    'a'
    'Red'
    '#.Util'
    ''
    'Program Files'

… Or a number of tokens:

    'red' 'green' 'blue'
    'doe' 'a' 'deer'
    ,¨'abc'
    ↓⎕nl 9

Pre-processing removes trailing blanks from each token before comparison, so that, for example, the following two statements are equivalent:

      :Hold 'Red' 'Green'
    :Hold ↓2 5⍴'Red  Green'

Unlike ⎕FHOLD, a thread does not release all existing tokens before attempting to acquire new ones. This enables the nesting of holds, which can be useful when multiple threads are concurrently updating parts of a complex data structure.

In the following example, a thread updates a critical structure in a child namespace, and then updates a structure in its parent space. The holds will allow all ‘sibling’ namespaces to update concurrently, but will constrain updates to the parent structure to be executed one at a time.

    :Hold ⎕cs''          ⍝ Hold child space
        ...              ⍝ Update child space
        :Hold ##.⎕cs''   ⍝ Hold parent space
            ...          ⍝ Update Parent space
        :EndHold
        ...
    :EndHold

However, with the nesting of holds comes the possibility of a ‘deadlock’. For example, consider the two threads:

Thread 1                Thread 2
:Hold 'red'                :Hold 'green'
    ...                    ...
    :Hold 'green'                :Hold 'red'
        ...                        ...
    :EndHold                    :EndHold
:EndHold                :EndHold

In this case if both threads succeed in acquiring their first hold, they will both block waiting for the other to release its token. Fortunately, the interpreter detects such cases and issues an error (1008) DEADLOCK. You can avoid deadlock by ensuring that threads always attempt to acquire tokens in the same chronological order, and that threads never attempt to acquire tokens that they already own.

Note that token acquisition for any particular :Hold is atomic, that is, either all of the tokens or none of them are acquired. The following example cannot deadlock:

Thread 1               Thread 2
:Hold 'red'
    ...                :Hold 'green' 'red'
    :Hold 'green'                ...
        ...                :EndHold
    :EndHold
:EndHold

Examples

:Hold could be used for example, during the update of a complex data structure that might take several lines of code. In this case, an appropriate value for the token would be the name of the data structure variable itself, although this is just a programming convention: the interpreter does not associate the token value with the data variable.

    :Hold'Struct'
        ...              ⍝ Update Struct
        Struct ← ...
    :EndHold

The next example guarantees exclusive use of the current namespace:

    :Hold ⎕CS''          ⍝ Hold current space
        ...
    :EndHold

The following example shows code that holds two positions in a vector while the Contents are exchanged.

    :Hold ⍕¨to fm
        :If >/vec[fm to]
            vec[fm to]←vec[to fm]
        :End
    :End

Between obtaining the next available file tie number and using it:

    :Hold '⎕FNUMS'
        tie←1+⌈/0,⎕FNUMS
        fname ⎕FSTIE tie
    :End

The above hold is not necessary if the code is combined into a single line:

    fname ⎕FSTIE tie←1+⌈/0,⎕FNUMS

or,

    tie←fname ⎕FSTIE 0

Note that :Hold, like its component file system counterpart ⎕FHOLD, is a device to enable co-operating threads to synchronise their operation.

:Hold does not prevent threads from updating the same data structures concurrently, it prevents threads only from :Hold-ing the same tokens.


:Trap Statement

Formal Definition

:Trap is an error trapping mechanism which can be used in conjunction with, or as an alternative to, the ⎕TRAP system variable. It is equivalent to APL2’s ⎕EA, except that the code to be executed is not restricted to a single expression and is not contained within quotes (and so is slightly more efficient).

Operation

The segment of code immediately following the :Trap keyword is executed. On completion of this segment, if no error occurs, control passes to the code following :End[Trap]. If an error does occur, the event code (error number) is noted and:

If the error occurred within a sub-function, the system cuts the execution stack back to the function containing the :Trap keyword. In this respect, :Trap behaves like ⎕TRAP with a 'C' qualifier.

The system searches for a :Case[List] representing the event code.

If there is such a :Case[List], or failing that, an :Else keyword, execution continues from this point.

Otherwise, control passes to the code following :End[Trap] and no error processing occurs.

Note that the error trapping is in effect only during execution of the initial code segment. It is disabled (or surrendered to outer level :Traps or ⎕TRAPs) immediately a trapped error occurs. In particular, the error trap is no longer in effect during processing of :Case[List]’s argument or in the code following the :Case[List] or :Else statement. This avoids the situation sometimes encountered with ⎕TRAP where an infinite ‘trap loop’ occurs.

If an error which is not a member of <ecode> occurs, it is processed by outer :Traps, ⎕TRAPs, or default system processing in the normal fashion.

Examples

    ∇ lx
[1]   :Trap 1000        ⍝ Cutback and exit on interrupt
[2]       Main ...
[3]   :EndTrap
    ∇

    ∇ ftie←Fcreate file      ⍝ Create null component file
[1]   ftie←1+⌈/0,⎕fnums      ⍝ next tie number.
[2]   :Trap 22               ⍝ Trap FILE NAME ERROR
[3]       file ⎕fcreate ftie ⍝ Try to create file.
[4]   :Else
[5]       file ⎕ftie ftie    ⍝ Tie the file.
[6]       file ⎕ferase ftie  ⍝ Drop the file.
[7]       file ⎕fcreate ftie ⍝ Create new file.
[8]   :EndTrap
    ∇

    ∇ lx ⍝ Distinguish various cases
[1]   :Trap 0 1000
[2]       Main ...
[3]   :Case 1002
[4]       'Interrupted ...'
[5]   :CaseList 1 10 72 76
[6]       'Not enough resources'
[7]   :CaseList 17+⍳20
[8]       'File System Problem'
[9]   :Else
[10]      'Unexpected Error'
[11]  :EndTrap
    ∇

Note that :Traps can be nested:

    ∇ ntie←Ntie file                  ⍝ Tie native file
[1]   ntie←¯1+⌊/0,⎕nnums              ⍝ Next native tie number
[2]   :Trap 22                        ⍝ Trap FILE NAME ERROR
[3]       file ⎕ntie ntie             ⍝ Try to tie file
[4]   :Else
[5]       :Trap 22                    ⍝ Trap FILE NAME ERROR
[6]           (file,'.txt')⎕ntie ntie ⍝ Try with .txt extension
[7]       :Else
[8]           file ⎕ncreate ntie      ⍝ Create null file.
[9]       :EndTrap
[10]  :EndTrap
    ∇


:Return Statement

:Return

A :Return statement causes a function to terminate and has exactly the same effect as → 0. The :Return control word takes no argument. A :Return statement may occur anywhere in a function or operator.


:GoTo Statement

:Goto aexp

A :GoTo statement is a direct alternative to → (branch) and causes execution to jump to the line specified by the first element of aexp. The following are equivalent. See Branch for further details.

      →Exit
      :GoTo Exit

      →(N<I←I+1)/End
      :GoTo (N<I←I+1)/End

      →1+⎕LC
      :GoTo 1+⎕LC

      →10
      :GoTo 10


Introduction to Dynamic Functions

A Dynamic Function (operator) is an alternative function definition style suitable for defining small to medium sized functions. It bridges the gap between operator expressions: rank←⍴∘⍴ and full ‘header style’ definitions such as:

      ∇ rslt←larg func rarg;local...

In its simplest form, a dynamic function is an APL expression enclosed in curly braces {} possibly including the special characters ÷ and — to represent the left and right arguments of the function respectively. For example:

 {(+/⍵)÷⍴⍵} 1 2 3 4    ⍝ Arithmetic Mean (Average)
2.5

      3 {⍵*÷⍺} 64           ⍝ ⍺th root
4

Dynamic functions can be named in the normal fashion:

      mean←{(+/⍵)÷⍴⍵}
      mean¨(2 3)(4 5)
 2.5  4.5

Dynamic Functions can be defined and used in any context where an APL function may be found, in particular:

  • In immediate execution mode as in the examples above.
  • Within a defined function or operator.
  • As the operand of an operator such as each (¨).
  • Within another dynamic function.

The last point means that it is easy to define nested local functions.

The supplied workspace DFNS.DWS contains many useful examples of dynamic functions.


Multi-Line Dynamic Functions

The single expression which provides the result of the Dynamic Function may be preceded by any number of assignment statements. Each such statement introduces a name which is local to the function.

For example in the following, the expressions sum← and num← create local variables sum and num.

      mean←{          ⍝ Arithmetic mean
          sum←+/⍵     ⍝ Sum of elements
          num←⍴⍵      ⍝ Number of elements
          sum÷num     ⍝ Mean
      }

Note that Dynamic Functions may be commented in the usual way using ⍝.

When the interpreter encounters a local definition, a new local name is created. The name is shadowed dynamically exactly as if the assignment had been preceded by: ⎕shadow name ⋄.

It is important to note the distinction between the two types of statement above. There can be many assignment statements, each introducing a new local variable, but only a single expression where the result is not assigned. As soon as the interpreter encounters such an expression, it is evaluated and the result returned immediately as the result of the function.

For example, in the following,

      mean←{          ⍝ Arithmetic mean
          sum←+/⍵     ⍝ Sum of elements
          num←⍴⍵      ⍝ Number of elements
          sum,num     ⍝ Attempt to show sum,num (wrong)!
          sum÷num     ⍝ ... and return result.
      }

... as soon as the interpreter encounters the expression sum,num, the function terminates with the two element result (sum,num) and the following line is not evaluated.

To display arrays to the session from within a Dynamic function, you can use the explicit display forms ⎕← or ⍞← as in:

      mean←{          ⍝ Arithmetic mean
          sum←+/⍵     ⍝ Sum of elements
          num←⍴⍵      ⍝ Number of elements
          ⎕←sum,num   ⍝ show sum,num.
          sum÷num     ⍝ ... and return result.
      }

Note that local definitions can be used to specify local nested Dynamic Functions:

      rms←{                   ⍝ Root Mean Square
          root←{⍵*0.5}        ⍝ ∇ Square root
          mean←{(+/⍵)÷⍴⍵}     ⍝ ∇ Mean
          square←{⍵×⍵}        ⍝ ∇ Square
          root mean square ⍵
      }


Default Left Argument

The special syntax: ⍺←expr is used to give a default value to the left argument if a Dynamic Function is called monadically. For example:

      root←{    ⍝ ⍺th root
        ⍺←2     ⍝ default to sqrt
        ⍵*÷⍺
}

The expression to the right of ⍺← is evaluated only if its Dynamic Function is called with no left argument.


Guards

A Guard is a Boolean-single valued expression followed on the right by a ':'. For example:

      0⍵:         ⍝ Right arg simple scalar

      ⍺<0:          ⍝ Left arg negative

The guard is followed by a single APL expression: the result of the function.

      ⍵≥0: ⍵*0.5    ⍝ Square root if non-negative.

A Dynamic function may contain any number of guarded expressions each on a separate line (or collected on the same line separated by diamonds). Guards are evaluated in turn until one of them yields a 1. The corresponding expression to the right of the guard is then evaluated as the result of the function.

If an expression occurs without a guard, it is evaluated immediately as the default result of the function. For example:

      sign←{
          ⍵>0: '+ve'      ⍝ Positive
          ⍵=0: 'zero'     ⍝ zero
               '-ve'      ⍝ Negative (Default)
      }

Note that Dynamic Functions may be commented in the usual way using ⍝.

Note also that any code following the first unguarded expression can never be executed and is therefore redundant.


Shy Result

Dynamic Functions are usually 'pure' functions that take arguments and return explicit results. Occasionally, however, the main purpose of the function might be a side-effect such as the display of information in the session, or the updating of a file, and the value of a result, a secondary consideration. In such circumstances, you might want to make the result 'shy', so that it is discarded unless the calling context requires it. This can be achieved by assigning a dummy variable after a (true) guard:

      log←{                   ⍝ Append ⍵ to file ⍺.
          tie←⍺ ⎕fstie 0      ⍝ tie number for file,
          cno←⍵ ⎕fappend tie  ⍝ new component number,
          tie←⎕funtie tie     ⍝ untie file,
          1:rslt←cno          ⍝ comp number as shy result.
      }


Static Name Scope

When an inner (nested) Dynamic Function refers to a name, the interpreter searches for it by looking outwards through enclosing Dynamic Functions, rather than searching back along the execution stack. This regime, which is more appropriate for nested functions, is said to employ static scope instead of APL’s usual dynamic scope. This distinction becomes apparent only if a call is made to a function defined at an outer level. For the more usual inward calls, the two systems are indistinguishable.

For example, in the following function, variable type is defined both within which itself and within the inner function fn1. When fn1 calls outward to fn2 and fn2 refers to type, it finds the outer one (with value 'static') rather than the one defined in fn1:

      which←{
          type←'static'

          fn1←{
              type←'dynamic'
              fn2 ⍵
          }

          fn2←{
              type ⍵
          }

          fn1 ⍵
      }
      which'scope'
static  scope


Tail Calls

A novel feature of the implementation of Dynamic Functions is the way in which tail calls are optimised.

When a Dynamic Function calls a sub-function, the result of the call may or may not be modified by the calling function before being returned. A call where the result is passed back immediately without modification is termed a tail call.

For example in the following, the first call on function fact is a tail call because the result of fact is the result of the whole expression, whereas the second call isn’t because the result is subsequently multiplied by —.

      (⍺×⍵)fact ⍵-1       ⍝ Tail call on fact.
      ⍵×fact ⍵-1          ⍝ Embedded call on fact.

Tail calls occur frequently in Dynamic Functions, and the interpreter optimises them by re-using the current stack frame instead of creating a new one. This gives a significant saving in both time and workspace usage. it is easy to check whether or not a call is a tail call by tracing it. An embedded call will pop up a new trace window for the called function, whereas a tail call will re-use the current one.


Recursion

A Recursive Dynamic Function can refer to itself using its name explicitly, but because we allow unnamed functions, we also need a special symbol for implicit self-reference: '∇'. For example:

      fact←{          ⍝ Factorial ⍵.
          ⍵≤1: 1      ⍝ Small ⍵, finished,
          ⍵×∇ ⍵-1     ⍝ Otherwise recur.>
      }

Implicit self-reference using '∇' has the further advantage that it incurs less interpretative overhead and is therefore quicker. Tail calls using '∇' are particularly efficient.

Recursive Dynamic Operators refer to their derived functions, that is the operator bound with its operand(s) using ∇ or the operator itself using the compound symbol: ∇∇. The first form of self reference is by far the more frequently used.

      pow←{           ⍝ Function power.
          ⍺=0:⍵       ⍝ Apply function operand ⍺ times.
          (⍺-1)∇ ⍺⍺ ⍵ ⍝ ⍺⍺ ⍺⍺ ⍺⍺ ... ⍵
      }

The following example shows a rather contrived use of the second form of (operator) self reference. The exp operator composes its function operand with itself on each recursive call. This gives the effect of an exponential application of the original operand function:

      exp←{               ⍝ Exponential fn application.
          ⍺=0:⍺⍺ ⍵        ⍝ Apply operand 2*⍺ times.
          (⍺-1)⍺⍺∘⍺⍺ ∇∇ ⍵ ⍝ (⍺⍺∘⍺⍺)∘( ... ) ... ⍵
      }

      succ←{1+⍵}          ⍝ Successor (increment).
      10 succ exp 0
1024


Dynamic Operators

The operator equivalent of a dynamic function is distinguished by the presence of either of the compound symbols ⍺⍺ or ⍵⍵ anywhere in its definition. ⍺⍺ and ⍵⍵ represent the left and right operand of the operator respectively.

Example:

The following monadic each operator applies its function operand only to unique elements of its argument. It then distributes the result to match the original argument. This can deliver a performance improvement over the primitive each (¨) operator if the operand function is costly and the argument contains a significant number of duplicate elements. Note however, that if the operand function causes side effects, the operation of dynamic and primitive versions will be different.

      each←{              ⍝ Fast each:
          shp←⍴⍵          ⍝ Shape and ...
          vec←,⍵          ⍝ ... ravel of arg.
          nub←∪vec        ⍝ Vector of unique elements.
          res←⍺⍺¨nub      ⍝ Result for unique elts.
          idx←nub⍳vec     ⍝ Indices of arg in nub ...
          shp⍴idx⊃¨⊂res   ⍝ ... distribute result.
      }

The dyadic else operator applies its left (else right) operand to its right argument depending on its left argument.

      else←{
          ⍺: ⍺⍺ ⍵     ⍝ True: apply Left operand
             ⍵⍵ ⍵     ⍝ Else,  ..   Right   ..
      }
      0 1 ⌈else⌊¨ 2.5     ⍝ Try both false and true.
2 3


Error Guards

An error-guard is (an expression that evaluates to) a vector of error numbers, followed by the digraph: ::, followed by an expression, the body of the guard, to be evaluated as the result of the function. For example:

      11 5 :: ⍵×0      ⍝ Trap DOMAIN and LENGTH errors.

In common with :Trap and ⎕TRAP, error numbers 0 and 1000 are catchalls for synchronous errors and interrupts respectively.

When an error is generated, the system searches statically upwards and outwards for an error-guard that matches the error. If one is found, the execution environment is unwound to its state immediately prior to the error-guard’s execution and the body of the error-guard is evaluated as the result of the function. This means that, during evaluation of the body, the guard is no longer in effect and so the danger of a hang caused by an infinite ‘trap loop’, is avoided.

Notice that you can provide ‘cascading’ error trapping in the following way:

      0::try_2nd
      0::try_1st
         expr

In this case, if expr generates an error, its immediately preceding: 0:: catches it and evaluates try_1st leaving the remaining error-guard in scope. If try_1st fails, the environment is unwound once again and try_2nd is evaluated, this time with no error-guards in scope.

Examples:

Open returns a handle for a component file. If the exclusive tie fails, it attempts a share-tie and if this fails, it creates a new file. Finally, if all else fails, a handle of 0 is returned.

open←{                   ⍝ Handle for component file ⍵.
        0::0             ⍝ Fails:: return 0 handle.
       22::⍵ ⎕FCREATE 0  ⍝ FILE NAME:: create new one.
    24 25::⍵ ⎕FSTIE 0    ⍝ FILE TIED:: try share tie.
           ⍵ ⎕FTIE 0     ⍝ Attempt to open file.
}

An error in div causes it to be called recursively with ‘improved’ arguments.

div←{              ⍝ Tolerant division:: ⍺÷0 → ⍺.
    ⍺←1            ⍝ default numerator.
    5::↑∇/↓↑⍺ ⍵    ⍝ LENGTH:: stretch to fit.
    11::⍺ ∇ ⍵+⍵=0  ⍝ DOMAIN:: increase divisor.
    ⍺÷⍵            ⍝ attempt division.
}

Notice that some arguments may cause div to recur twice:

      6 4 2 div 3 2
→     6 4 2 div 3 2 0
→     6 4 2 div 3 2 1
→     2 2 2

The final example shows the unwinding of the local environment before the error-guard’s body is evaluated. Local name trap is set to describe the domain of its following error-guard. When an error occurs, the environment is unwound to expose trap’s statically correct value.

      add←{
          trap←'domain' ⋄ 11::trap
          trap←'length' ⋄  5::trap
          ⍺+⍵
      }
      2 add 3        ⍝ Addition succeeds
5

      2 add 'three'  ⍝ DOMAIN ERROR generated.
domain

      2 3 add 4 5 6  ⍝ LENGTH ERROR generated.
length


Restrictions

Currently multi-line Dynamic Functions can’t be defined directly in immediate execution mode in the session. The interpreter attempts to evaluate the first line with its opening brace and a SYNTAX ERROR results.

Dynamic Functions need not return a result. However even a non-result returning expression will terminate the function, so you can’t for example have a function which ties a component file (no result) and then on the next line reads the —th component.

You can trace a Dynamic Function only if it is defined on more than one line. Otherwise it is executed atomically in the same way as an execute (⍎) expression. This deliberate restriction is intended to avoid the confusion caused by tracing a line and seeing nothing change on the screen.

⎕cs is not currently supported in Dynamic Functions.


MultiThreading Overview

Overview of MultiThreading

Dyalog APL supports multithreading - the ability to run more than one APL expression at the same time.

This unique capability allows you to perform background processing, such as printing, database retrieval, database update, calculations, and so forth while at the same time perform other interactive tasks.

Multithreading may be used to improve throughput and system responsiveness.

A thread is a strand of execution in the APL workspace

A thread is created by calling a function asynchronously, using the new primitive operator ‘spawn’: & or by the asynchronous invocation of a callback function.

With a traditional APL synchronous function call, execution of the calling environment is paused, pendent on the return of the called function. With an asynchronous call, both calling environment and called function proceed to execute concurrently.

An asynchronous function call is said to start a new thread of execution. Each thread has a unique thread number, with which, for example, its presence can be monitored or its execution terminated.

Any thread can spawn any number of sub-threads, subject only to workspace availability. This implies a hierarchy in which a thread is said to be a child thread of its parent thread. The base thread at the root of this hierarchy has thread number 0.

With multithreading, APL’s stack or state indicator can be viewed as a branching tree in which the path from the base to each leaf is a thread.

When a parent thread terminates, any of its children which are still running, become the children of (are ‘adopted’ by) the parent’s parent.

Thread numbers are allocated sequentially from 0 to 2147483647. At this point, the sequence ‘wraps around’ and numbers are allocated from 0 again avoiding any still in use. The sequence is reinitialised when a )RESET command is issued, or the active workspace is cleared, or a new workspace is loaded. A workspace may not be saved with threads other than the base thread: 0, running.


New Language Elements

Multithreading Language Elements

Primitive operator, spawn: &.

System functions: ⎕TID, ⎕TNAME, ⎕TCNUMS, ⎕TNUMS, ⎕TKILL, ⎕TSYNC.

System functions: ⎕TGET, ⎕TPUT, ⎕TREQ, ⎕TPOOL.

Asynchronous callbacks for GUI Events.

A control structure: :Hold.

System commands: )HOLDS, )TID,

Extended )SI and )SINL display.

Running CallBack Functions as Threads

A callback function is associated with a particular event via the Event property of the object concerned. A callback function is executed by ⎕DQ when the event occurs, or by ⎕NQ.

If you append the character & to the name of the callback function in the Event specification, the callback function will be executed asynchronously as a thread when the event occurs. If not, it is executed synchronously as before.

For example, the event specification:

      ⎕WS'Event' 'Select' 'DoIt&'

tells ⎕DQ to execute the callback function DoIt asynchronously as a thread when a Select event occurs on the object.


Thread Switching

Programming with threads requires care.

The interpreter may switch between running threads at the following points:

  • Between any two lines of a defined (or dynamic) function or operator.

  • While waiting for a ⎕DL to complete.

  • While waiting for a ⎕FHOLD to complete.

  • While awaiting input from ⎕DQ, ⎕SR and ⎕ED

  • The session prompt or ⎕: or ⍞

  • While awaiting the completion of an external operation
    • A call on an external (AP) function.

    • A call on a ⎕NA (DLL) function.

    • A call on an OLE function.

At any of these points, the interpreter might execute code in other threads. If such threads change the global environment; for example by changing the value of, or expunging a name; then the changes will appear to have happened while the thread in question passes through the switch point. It is the task of the application programmer to organise and contain such behaviour!

You can prevent threads from interacting in critical sections of code by using the :Hold control structure.


Name Scope

APL’s name scope rules apply whether a function call is synchronous or asynchronous. For example when a defined function is called, names in the calling environment are visible, unless explicitly shadowed in the function header.

Just as with a synchronous call, a function called asynchronously has its own local environment, but can communicate with its parent and ‘sibling’ functions via local names in the parent.

This point is important. It means that siblings can run in parallel without danger of local name clashes. For example, a GUI application can accommodate multiple concurrent instances of its callback functions.

However, with an asynchronous call, as the calling function continues to execute, both child and parent functions may modify values in the calling environment. Both functions see such changes immediately they occur.

If a parent function terminates while any of its children are still running, those children will thenceforward ‘see’ local names in the environment that called the parent function. In cases where a child function relies on its parent’s environment (the setting of a local value of ⎕IO for example), this would be undesirable, and the parent function would normally execute a ⎕TSYNC in order to wait for its children to complete before itself exiting.

If, on the other hand, after launching an asynchronous child, the parent function calls a new function (either synchronously or asynchronously), names in the new function are beyond the purview of the original child. In other words, a function can only ever see its calling stack decrease in size – never increase. This is in order that the parent may call new defined functions without affecting the environment of its asynchronous children.


Debugging

If a thread sustains an untrapped error, its execution is suspended in the normal way. If the Pause on Error option (see User Guide) is set, all other threads are paused. If Pause on Error option (see User Guide) is not set, other threads will continue running and it is possible for another thread to encounter an error and suspend.

Using the facilities provided by the Tracer and the Threads Tool (see User Guide) it is possible to interrupt (suspend) and restart individual threads, and to pause and resume individual threads, so any thread may be in one of three states - running, suspended or paused.

The Tracer and the Session may be connected with any suspended thread and you can switch the attention of the Session and the Tracer between suspended threads using )TID or by clicking on the appropriate tab in the Tracer. At this point, you may:

  • Examine and modify local variables for the currently suspended thread.
  • Trace and edit functions in the current thread.
  • Cut back the stack in the currently suspended thread.
  • Restart execution.
  • Start new threads

The error message from a thread other than the base is prefixed with its thread number:

260:DOMAIN ERROR
Div[2] rslt←num÷div
      ∧

State indicator displays: )SI and )SINL have been extended to show threads’ tree-like calling structure.

      )SI
·   Calc[1]
&5
·   ·   DivSub[1]
·   &7
·   ·   DivSub[1]
·   &6
·   Div[2]*
&4
Sub[3]
Main[4]

Here, Main has called Sub, which has spawned threads 4 and 5 with functions: Div and Calc. Div, after spawning DivSub in each of threads 6 and 7, has been suspended at line [2].

Removing stack frames using ‘Quit’ from the tracer or ‘→’ from the session affects only the current thread. When the final stack frame in a thread (other than the base thread) is removed, the thread is expunged.

)RESET removes all but the base thread.

Note the distinction between a suspended thread and a paused thread.

A suspended thread is stopped at the beginning of a line in a defined function or operator. It may be connected to the Session so that expressions executed in the Session do so in the context of that thread. It may be restarted by executing →line (typically, →⎕LC).

A paused thread is an inactive thread that is currently being ignored by the thread scheduler. A paused thread may be paused within a call to ⎕DQ, a call on an external function, at the beginning of a line, or indeed at any of the thread-switching points described earlier in this chapter.

A paused thread may be resumed only by the action of a menu item or button. A paused thread resumes only in the sense that it ceases to be ignored by the thread scheduler and will therefore be switched back to at some point in the future. It does not actually continue executing until the switch occurs.


Using Threads

Put most simply, multithreading allows you to appear to run more than one APL function at the same time, just as Windows (or UNIX) appears to run more than one application at the same time. In both cases this is something of an illusion, although it does nothing to detract from its usefulness.

Dyalog APL implements an internal timesharing mechanism whereby it shares processing between threads. Although the mechanics are somewhat different, APL multithreading is rather similar to the multitasking provided by Windows 95/98 and NT. If you are running more than one application, Windows switches from one to another, allocating each one a certain time slice before switching. At any point in time, only one application is actually running; the others are paused, waiting.

If you execute more than one Dyalog APL thread, only one thread is actually running; the others are paused. Each APL thread has its own State Indicator, or SI stack. When APL switches from one thread to another, it saves the current stack (with all its local variables and function calls), restores the new one, and then continues processing.


Stack Considerations

When you start a thread, it begins with the SI stack of the calling function and sees all of the local variables defined in all the functions down the stack. However, unless the calling function specifically waits for the new thread to terminate (see ⎕TSYNC), the calling functions will (bit by bit, in their turn) continue to execute. The new thread’s view of its calling environment may then change. Consider the following example:

Suppose that you had the following functions: RUN[3] calls INIT which in turn calls GETDATA but as 3 separate threads with 3 different arguments:

     ∇ RUN;A;B
[1]    A←1
[2]    B←'Hello World'
[3]    INIT
[4]    CALC
[5]    REPORT
     ∇

     ∇ INIT;C;D
[1]    C←D←0
[2]    GETDATA&'Sales'
[3]    GETDATA&'Costs'
[4]    GETDATA&'Expenses'
     ∇

When each GETDATA thread starts, it immediately sees (via ⎕SI) that it was called by INIT which was in turn called by RUN, and it sees local variables A, B, C and D. However, once INIT[4] has been executed, INIT terminates, and execution of the root thread continues by calling CALC. From then on, each GETDATA thread no longer sees INIT (it thinks that it was called directly from RUN) nor can it see the local variables C and D that INIT had defined. However, it does continue to see the locals A and B defined by RUN, until RUN itself terminates.

Note that if CALC were also to define locals A and B, the GETDATA threads would still see the values defined by RUN and not those defined by CALC. However, if CALC were to modify A and B (as globals) without localising them, the GETDATA threads would see the modified values of these variables, whatever they happened to be at the time.


Globals and the Order of Execution

It is important to recognise that any reference or assignment to a global or semi-global object (including GUI objects) is inherently dangerous (i.e. a source of programming error) if more than one thread is running. Worse still, programming errors of this sort may not become apparent during testing because they are dependent upon random timing differences. Consider the following example:

     ∇ BUG;SEMI_GLOBAL
[1]    SEMI_GLOBAL←0
[2]    FOO& 1
[3]    GOO& 1
     ∇

     ∇ FOO
[1]    :If SEMI_GLOBAL=0
[2]        DO_SOMETHING SEMI_GLOBAL
[3]    :Else
[4]        DO_SOMETHING_ELSE SEMI_GLOBAL
[5]    :EndIf
     ∇

     ∇ GOO
[1]    SEMI_GLOBAL←1
     ∇

In this example, it is formally impossible to predict in which order APL will execute statements in BUG, FOO or GOO from BUG[2] onwards. For example, the actual sequence of execution may be:

      BUG[1] → BUG[2] → FOO[1] → FOO[2] →
               DO_SOMETHING[1]

or

      BUG[1] → BUG[2] → BUG[3] → GOO[1] →
               FOO[1] → FOO[2] → FOO[3] →
               FOO[4] → DO_SOMETHING_ELSE[1]

This is because APL may switch from one thread to another between any two lines in a defined function. In practice, because APL gives each thread a significant time-slice, it is likely to execute many lines, maybe even hundreds of lines, in one thread before switching to another. However, you must not rely on this; thread-switching may occur at any time between lines in a defined function.

Secondly, consider the possibility that APL switches from the FOO thread to the GOO thread after FOO[1]. If this happens, the value of SEMI_GLOBAL passed to DO_SOMETHING will be 1 and not 0. Here is another source of error.

In fact, in this case, there are two ways to resolve the problem. To ensure that the value of SEMI_GLOBAL remains the same from FOO[1] to FOO[2], you may use diamonds instead of separate statements, e.g.

      :If SEMI_GLOBAL=0 ⋄ DO_SOMETHING SEMI_GLOBAL

Even better, although less efficient, you may use :Hold to synchronise access to the variable, for example:

      ∇ FOO
[1]    :Hold 'SEMI_GLOBAL'
[2]        :If SEMI_GLOBAL=0
[3]            DO_SOMETHING SEMI_GLOBAL
[4]        :Else
[5]            DO_SOMETHING_ELSE SEMI_GLOBAL
[6]        :EndIf
[7]    :EndHold
     ∇

     ∇ GOO
[1]    :Hold 'SEMI_GLOBAL'
[2]        SEMI_GLOBAL←1
[3]    :EndHold
     ∇

Now, although you still cannot be sure which of FOO and GOO will run first, you can be sure that SEMI_GLOBAL will not change (because GOO cuts in) within FOO.

Note that the string used as the argument to :Hold is completely arbitrary, so long as threads competing for the same resource use the same string.

A Caution

These types of problems are inherent in all multithreading programming languages, and not just with Dyalog APL.

If you want to take advantage of the additional power provided by multithreading, it is advisable to think carefully about the potential interaction between different threads.


Threads and Niladic Functions

In common with other operators, the spawn operator & may accept monadic or dyadic functions as operands, but not niladic functions. This means that, using spawn, you cannot start a thread that consists only of a niladic function

If you wish to invoke a niladic function asynchronously, you have the following choices:

Turn your niladic function into a monadic function by giving it a dummy argument which it ignores.

Call your niladic function with a dynamic function to which you give an argument that is implicitly ignored. For example, if the function NIL is niladic, you can call it asynchronously using the expression:

      {NIL}& 0

Call your function via a dummy monadic function, e.g.

    ∇ NIL_M DUMMY
[1]    NIL
    ∇
      NIL_M& ''

Use execute, e.g.

      ⍎& 'NIL'

Note that niladic functions can be invoked asynchronously as callback functions. For example,

      ⎕WS'Event' 'Select' 'NIL&'

will execute correctly as a thread, even though NIL is niladic. This is because callback functions are invoked directly by ⎕DQ rather than as an operand to a the spawn operator.


Threads and External Functions

External functions in dynamic link libraries (DLLs) defined using the ⎕NA interface may be run in separate C threads. Such threads:

take advantage of multiple processors if the operating system permits.

allow APL to continue processing in parallel during the execution of a ⎕NA function.

When you define an external function using ⎕NA, you may specify that the function be run in a separate C thread by appending an ampersand (&) to the function name, for example:

      'beep'⎕NA'user32|MessageBeep& i' ⍝ MessageBeep will run in a separate C thread

When APL first comes to execute a multi-threaded ⎕NA function, it starts a new C-thread, executes the function within it, and waits for the result. Other APL threads may then run in parallel.

Note that when the ⎕NA call finishes and returns its result, its new C-thread is retained to be re-used by any subsequent multithreaded ⎕NA calls made within the same APL thread. Thus any APL thread that makes any multi-threaded ⎕NA calls maintains a separate C-thread for their execution. This C-thread is discarded when its APL thread finishes.

Note that there is no point in specifying a ⎕NA call to be multi-threaded, unless you wish to execute other APL threads at the same time.

In addition, if your ⎕NA call needs to access an APL GUI object (strictly, a window or other handle) it should normally run within the same C-thread as APL itself, and not in a separate C-thread. This is because Windows associates objects with the C-thread that created them. Although you can use a multi-threaded ⎕NA call to access (say) a Dyalog APL Form via its window handle, the effects may be different than if the ⎕NA call was not multi-threaded. In general, ⎕NA calls that access APL (GUI) objects should not be multi-threaded.

If you wish to run the same ⎕NA call in separate APL threads at the same time, you must ensure that the DLL is thread-safe. Functions in DLLs which are not thread-safe, must be prevented from running concurrently by using the :Hold control structure. Note that all the standard Windows API DLLs are thread safe.

Notice that you may define two separate functions (with different names), one single-threaded and one multi-threaded, associated with the same function in the DLL. This allows you to call it in either way.


Synchronising Threads

Threads may be synchronised using tokens and a token pool

An application can synchronise its threads by having one thread add tokens into the pool whilst other threads wait for tokens to become available and retrieve them from the pool.

Tokens possess two separate attributes, a type and a value.

The type of a token is a positive or negative integer scalar. The value of a token is any arbitrary array that you might wish to associate with it.

The token pool may contain up to 2*31 tokens; they do not have to be unique neither in terms of their types nor of their values.

The following system functions are used to manage the token pool:

⎕TPUT | Puts tokens into the pool.
⎕TGET | If necessary waits for, and then retrieves some tokens from the pool..
⎕TPOOL | Reports the types of tokens in the pool
⎕TREQ | Reports the token requests from specific threads

A simple example of a thread synchronisation requirement occurs when you want one thread to reach a certain point in processing before a second thread can continue. Perhaps the first thread performs a calculation, and the second thread must wait until the result is available before it can be used.

This can be achieved by having the first thread put a specific type of token into the pool using ⎕TPUT. The second thread waits (if necessary) for the new value to be available by calling ⎕TGET with the same token type.

Notice that when ⎕TGET returns, the specified tokens are removed from the pool. However, negative token types will satisfy an infinite number of requests for their positive equivalents.

The system is designed to cater for more complex forms of synchronisation. For example, a semaphore to control a number of resources can be implemented by keeping that number of tokens in the pool. Each thread will take a token while processing, and return it to the pool when it has finished.

A second complex example is that of a latch which holds back a number of threads until the coast is clear. At a signal from another thread, the latch is opened so that all of the threads are released. The latch may (or may not) then be closed again to hold up subsequently arriving threads. A practical example of a latch is a ferry terminal.


Semaphore Token Pool example

Semaphore Example

A semaphore to control a number of resources can be implemented by keeping that number of tokens in the pool. Each thread will take a token while processing, and return it to the pool when it has finished.

For example, if we want to restrict the number of threads that can have sockets open at any one time.

    sock←99                  ⍝ socket-token any +ive number will do).
    ⎕TPUT 5/sock             ⍝ add 5 socket-tokens to pool.
    ∇ sock_open ...
[1]   :If sock=⎕TGET sock    ⍝ grap a socket token
[.]       ...                ⍝ do stuff.
[.]       ⎕TPUT sock         ⍝ release socket token
[.]   :Else
[.]       error'sockets off' ⍝ sockets switched off by
                               retract (see below).
[.]   :EndIf
    ∇
    0 ⎕TPUT ⎕treq ⎕tnums     ⍝ retract socket "service" with 0 value.


Latch Token Pool example

Latch Example

A latch holds back a number of threads until the coast is clear. At a signal from another thread, the latch is opened so that all of the threads are released. The latch may (or may not) then be closed again to hold up subsequently arriving threads.

A visual example of a latch might be a ferry terminal, where cars accumulate in the queue until the ferry arrives. The barrier is then opened and all (up to a maximum number) of the cars are allowed through it and on to the ferry. When the last car is through, the barrier is re-closed.

    tkt←6                         ⍝ 6-token: ferry ticket.
    ∇ car ...
[1]   ⎕TGET tkt                   ⍝ await ferry.
[2]   ...

    ∇ ferry ...
[1]   arrives in port
[2]   ⎕TPUT(↑,/⎕treq ⎕tnums)∩tkt  ⍝ ferry tickets for all.
[3]   ...

Note that it is easy to modify this example to provide a maximum number of ferry places per trip by inserting max_places↑ between ⎕TPUT and its argument. If fewer cars than the ferry capacity are waiting, the ↑ will fill with trailing 0s. This will not cause problems because zero tokens are ignored.

Let us replace the car ferry with a new road bridge. Once the bridge is ready for traffic, the barrier could be opened permanently by putting a negative ticket in the pool.:

    ⎕TPUT -tkt      ⍝ open ferry barrier permananently.

Cars could choose to take the last ferry if there are places:

    ∇ car ...
[1]   :Select ⎕TGET tkt
[2]   :Case  tkt ⋄ take the last ferry.
[3]   :Case -tkt ⋄ ferry full: take the new bridge.
[4]   :End

The above :Select works because by default, ⎕TPUT -tkt puts a value of -tkt into the token.


Copy System Command

Copy Objects

)COPY {ws {nms}}

This command brings all or selected global objects nms from a stored workspace with the given name. A stored workspace is one which has previously been saved with the system command )SAVE or the system function ⎕SAVE.

If the list of names is excluded, all defined objects (including namespaces) are copied.

If the workspace name identifies a valid, readable workspace, the system reports the workspace name, saved and the date and time when the workspace was last saved.

Examples

      )COPY WS/UTILITY
WS/UTILITY saved Mon Nov  1 13:11:19 1992

      )COPY TEMP ⎕LX FOO X A.B.C
./TEMP saved Mon Nov  1 14:20:47 1992
not found X

Copied objects are defined at the global level in the active workspace. Existing global objects in the active workspace with the same name as a copied object are replaced. If the copied object replaces either a function in the state indicator, or an object that is an operand of an operator in the state indicator, or a function whose left argument is being executed, the original object remains defined until its execution is completed or it is no longer referenced by an operator in the state indicator. If the workspace name is not valid or does not exist or if access to the workspace is not authorised, the system reports ws not found.

You may copy an object from a namespace by specifying its full pathname. The object will be copied to the current namespace in the active workspace, losing its original parent and gaining a new one in the process. You may only copy a GUI object into a namespace that is a suitable parent for that object. For example, you could only copy a Group object from a saved workspace if the current namespace in the active workspace is itself a Form, SubForm or Group.

If the workspace name identifies a file that is not a workspace, the system reports bad ws.

If the source workspace is too large to be loaded into the second APL task, the system reports ws too large.

If ws is omitted, the file open dialog box is displayed and all objects copied from the selected workspace.

When copying data between Classic and Unicode Editions, )COPY will fail with TRANSLATION ERROR if any object in workspace Y fails conversion between Unicode and ⎕AV indices, whether or not that object is specified by nms. See ⎕AVU for further details.

If the list of names is included, the names of system variables may also be included and copied into the active workspace. The global referents will be copied.

If an object is not found in the stored workspace, the system reports not found followed by the name of the object.

If the list of names includes the name of:

  • an Instance of a Class but not the Class itself
  • a Class but not a Class upon which it depends
  • an array or a namespace that contains a ref to another namespace, but not the namespace to which it refers

the dependant object(s) will also be copied but will be unnamed and hidden. In such as case, the system will issue a warning message.

For example, if a saved workspace named CFWS contains a Class named #.CompFile and an Instance (of CompFile) named icf,

      )COPY CFWS icf
.\CFWS saved Fri Mar 03 10:21:36 2006
copied object created an unnamed copy of class #.CompFile

The existence of a hidden copy can be confusing, especially if it is a hidden copy of an object which had a name which is in use in the current workspace. In the above example, if there is a class called CompFile in the workspace into which icf is copied, the copied instance may appear to be an instance of the visible CompFile, but it will actually be an instance of the hidden CompFile - which may have very different (or perhaps worse: very slightly different) characteristics to the named version.

If you copy a Class without copying its Base Class, the Class can be used (it will use the invisible copy of the Base Class), but if you edit the Class, you will either be unable to save it because the editor cannot find the Base Class, or - if there is a visible Class of that name in the workspace - it will be used as the Base Class. In the latter case, the invisible copy which was brought in by )COPY will now disappear, since there are no longer any references to it - and if these two Base Classes were different, the behaviour of the derived Class will change (and any changes made to the invisible Base Class since it was copied will be lost).


Change Space System Command

Change Space

)CS {name}

)CS changes the current space to the global namespace name.

If no name is given, the system changes to the top level (root) namespace.

If name is not the name of a global namespace, the system reports the error message

Namespace does not exist.

name may be either a simple name or a compound name separated by '.', including one of the special names '#' or '##'.

Examples

      )CS
#
      )CS X
#.X
      )CS Y.Z
#.X.Y.Z
      )CS ##
#.X.Y
      )CS #.UTIL
#.UTIL

To change namespace under program control, see System Function ⎕CS


Edit System Command

Edit Objects

)ED nms

)ED invokes the Dyalog APL editor and opens an Edit window for each of the objects specified in nms.

If a name specifies a new symbol it is taken to be a function/operator. However, if a name is localised in a suspended function/operator but is otherwise undefined, it is assumed to be a vector of character vectors.

The type of a new object may be specified explicitly by preceding its name with an appropriate symbol as follows:

∇ | function/operator
→ | simple character vector
∊ | vector of character vectors
- | character matrix
⍟ | Namespace script
○ | Class script
∘ | Interface

The first object named becomes the top window on the stack.

)ED ignores names which specify GUI objects.

Examples:

      )ED MYFUNCTION

      )ED ∇FOO -MAT ∊VECVEC


Erase System Command

Erase Object

)ERASE nms

This command erases named global defined objects (functions, operators, variables, namespaces and GUI objects) from the active workspace or current namespace.

If a named object is a function or operator in the state indicator, or the object is an operand of an operator in the state indicator, or the object is a function whose left argument is being executed, the object remains defined until its execution is completed or it is no longer referenced by an operator in the state indicator. However, the name is available immediately for other uses.

If a named object is a GUI object, the object and all its children are deleted and removed from the screen.

If an object is not erased for any reason, the system reports not found followed by the name of the object.

Erasing objects such as external functions may have other implications: see the entry for expunge object (⎕EX) for details.

Example

      )ERASE FOO A ⎕IO
not found ⎕IO


Events System Command

List Events

)EVENTS

The )EVENTS system command lists the Events that may be generated by the object associated with the current space.

For example:

      ⎕CS 'BB'⎕WC'BrowseBox'
      )EVENTS
Close Create FileBoxCancel FileBoxOK PreCreate

)EVENTS produces no output when executed in a pure (non-GUI) namespace, for example:

      ⎕CS 'X' ⎕NS ''
      )EVENTS


Functions System Command

List Functions

)FNS {name}

This command displays the names of global defined functions in the active workspace. Names are displayed in ∩AV collation order. If a name is included after the command, only those names starting at or after the given name in collation order are displayed.

Examples:

      )FNS
ASK DISPLAY GET PUT ZILCH
      )FNS C
GET PUT ZILCH


Methods System Command

List Methods

)METHODS

The )METHODS system command lists the Methods that apply to the object associated with the current space.

For example:

      ⎕CS 'F'⎕WC'Form'
      )METHODS
Animate ChooseFont Detach GetFocus GetTextSize

)METHODS produces no output when executed in a pure (non-GUI) namespace, for example:

      ⎕CS 'X' ⎕NS ''
      )METHODS


Create Namespace System Command

Create Namespace

)NS {name}

)NS creates a global namespace and displays its full name.

name may be either a simple name or a compound name separated by '.', including one of the special names '#' or '##'.

If name does not start with the special root space identifier '#', the new namespace is created relative to the current one.

If name is already in use for a workspace object other than a namespace, the command fails and displays the error message Name already exists.

If name is an existing namespace, no change occurs.

)NS with no name specification displays the current namespace.

Examples

      )NS
#

      )NS W.X
#.W.X

      )CS W.X
#.W.X

      )NS Y.Z
#.W.X.Y.Z

      )NS
#.W.X


Objects System Command

List Global Namespaces

)OBS {nms}

This command displays the names of global namespaces in the active workspace. Names are displayed in the ⎕AV collating order. If a name is included after the command, only those names starting at or after the given name in collating order are displayed. Namespaces are objects created using ⎕NS, )NS or ⎕WC and have name class 9.

Note: )OBJECTS can be used as an alternative to )OBS

Examples

      )OBS
FORM1   UTIL    WSDOC   XREF

      )OBJECTS W
WSDOC   XREF


Operators System Command

List Operators

)OPS {name}

This command displays the names of global defined operators in the active workspace. Names are displayed in ⎕AV collation order. If a name is included after the command, only those names starting at or after the given name in collation order are displayed.

Examples:

      )OPS
AND DOIF DUAL ELSE POWER

      )OPS E
ELSE POWER


Protected Copy System Command

Protected Copy

)PCOPY {ws {nms}}

This command brings all or selected global objects from a stored workspace with the given name provided that there is no existing global usage of the name in the active workspace. A stored workspace is one which has previously been saved with the system command )SAVE or the system function ⎕SAVE.

If the workspace name is not valid or does not exist or if access to the workspace is not authorised, the system reports ws not found. If the workspace name identifies a file that is not a workspace, or is a workspace with an invalid version number (one that is greater than the version of the current APL) the system reports bad ws.

If the workspace name is the name of a valid, readable workspace, the system reports the workspace name, saved and the date and time that the workspace was last saved.

If the list of names is excluded, all global defined objects (functions and variables) are copied. If an object is not found in the stored workspace, the system reports not found followed by the name of the object. If an object cannot be copied into the active workspace because there is an existing referent, the system reports not copied followed by the name of the object.

For further information, see )COPY.

Examples:

      )PCOPY WS/UTILITY
WS/UTILITY saved Mon Nov  1 13:11:19 1992
not copied COPIED IF
not copied COPIED JOIN

      )PCOPY TEMP FOO X
./TEMP saved Mon Nov  1 14:20:47 1992
not found X


Properties System Command

List Properties

)PROPS

The )PROPS system command lists the Properties of the object associated with the current space.

For example:

      ⎕CS 'BB'⎕WC'BrowseBox'
      )PROPS
BrowseFor       Caption ChildList       Data    Event
HasEdit KeepOnClose     MethodList      PropList
StartIn Target  Translate       Type

)PROPS produces no output when executed in a pure (non GUI) namespace, for example:

      ⎕CS 'X' ⎕NS ''
      )PROPS


Variables System Command

List Variables

)VARS {name}

This command displays the names of global defined variables in the active workspace. Names are displayed in ⎕AV collation order. If a name is included after the command, only those names starting at or after the given name in collation order are displayed.

Example:

      )VARS
A  B  F  TEMP VAR

      )VARS F
F TEMP VAR


Reset System Command

Reset SI Stack

)RESET

This command cancels all suspensions recorded in the state indicator and discards any unprocessed events in the event queue.

)RESET also performs an internal re-organisation of the workspace and process memory. See ⎕WA (Workspace Availability) for details.

Example:

      )SI
FOO[1]*
⍎
FOO[1]*

      )RESET

      )SI


State Indicator System Command

State Indicator

)SI

This command displays the Contents of the state indicator in the active workspace. The state indicator identifies those operations which are suspended or pendent for each suspension.

The list consists of a line for each suspended or pendent operation beginning with the most recently suspended function or operator. Each line may be:

  • The name of a defined function or operator, followed by the line number at which the operation is halted, and followed by the * symbol if the operation is suspended. The name of a function or operator defined in a namespace other than the root is displayed relative to the root. For example, UTIL.PRINT. In addition, the display of a function or operator which has dynamically changed space away from its origin, is prefixed with its current space. For example, [⎕SE] TRAV.
  • A primitive operator symbol.
  • The Execute function symbol (⍎).
  • The Evaluated Input symbol (⎕).
  • The System Function ⎕DQ or ⎕SR (occurs when executing a callback function).

Examples

      )SI
PLUS[2]*
.
MATDIV[4]
FOO[1]*
⍎

This example indicates that at some point function FOO was executed and suspended on line 1. Subsequently, function MATDIV was invoked, with a function derived from the Inner Product or Outer Product operator (.) having defined function PLUS as an operand.

In the following, function foo in namespace x has called goo in namespace y. Function goo has then changed space (⎕CS) to namespace z where it has been suspended:

      )si
[z] y.goo[2]*
x.foo[1]

MultiThreading

In a multithreading application, where parent threads spawn child threads, the state indicator assumes the structure of a branching tree. Branches of the tree are represented by indenting lines belonging to child threads. For example:

)SI

·   Calc[1]
&5
·   ·   DivSub[1]
·   &7
·   ·   DivSub[1]
·   &6
·   Div[2]*
&4
Sub[3]
Main[4]

Here, Main has called Sub, which has spawned threads 4 and 5 with functions: Div and Calc. Function Div, after spawning DivSub in each of threads 6 and 7, has been suspended at line [2].


State Indicator and Name List System Command

SI & Name List

)SINL

This command displays the Contents of the state indicator in the active workspace. The state indicator identifies those operations which are suspended or pendent for each suspension. In addition, the names of all shadowed names are identified for each defined function or operator.

The list consists of a line for each suspended or pendent operation beginning with the most recently suspended function or operator. Each line may be:

  • the name of a defined function or operator, the line number at which the operation is halted, the * symbol if the operation is suspended, and a list of names localised by the operation, either its arguments, names in the header list of locals, labels, or names specified by the system function ⎕SHADOW.
  • an operator symbol.
  • the Execute function symbol (⍎).
  • the Evaluated Input symbol (⎕).
  • the System Function ⎕DQ or ⎕SR (occurs when executing a callback function)

Example:

      )SINL
PLUS[2]* B A R DYADIC END
.
MATDIV[4] R END I J ⎕TRAP
FOO[1]* R
⍎


Clear System Command

Clear Workspace

)CLEAR

This command clears the active workspace and gives the report "clear ws". The active workspace is lost. The name of a clear workspace is CLEAR WS. System variables are initialised with their default values.

In GUI implementations of Dyalog APL, )CLEAR expunges all GUI objects, discards any unprocessed events in the event queue and resets the properties of the ROOT object (".") to their default values.

Example:

      )CLEAR
clear ws


Drop System Command

Drop Workspace

)DROP {ws}

This command removes the specified workspace from disk storage. See the rules for specifying a workspace name.

If "ws" is omitted, a file open dialog box is displayed to elicit the workspace name.

Example:

      )DROP WS/TEMP


Lib System Command

List WS Library

)LIB {dir}

This command lists the names of Dyalog APL workspaces contained in the given directory.

Example:

      )LIB WS
MYWORK TEMP

If a directory is not given, the workspaces on the user's APL search path are listed. In this case, the listing is divided into sections identifying the directories concerned. The current directory is identified as ".".

Example:

      )LIB
.
        PDTEMP  WORK   GRAPHICS
C:\DYALOG\WS
        DISPLAY GROUPS


Load System Command

Load Workspace

)LOAD {ws}

This command causes the named stored workspace to be loaded. The current active workspace is lost.

If "ws" is a full or relative pathname, only the specified directory is examined. If not, the APL search path (as specified in APL.INI) is traversed in search of the named workspace. A stored workspace is one which has previously been saved with the system command )SAVE or the system function ⎕SAVE. If “ws” is omitted, the File Open dialog box is displayed.

If the workspace name is not valid or does not exist or if access to the workspace is not authorised, the system reports "ws not found". If the workspace name identifies a file or directory that is not a workspace, the system reports workspace name "is not a ws". If successfully loaded, the system reports workspace name "saved", followed by the date and time when the workspace was last saved. If the workspace is too large to be loaded into the APL session, the system reports "ws too large". After loading the workspace, the latent expression (⎕LX) is executed unless APL was invoked with the -x option.

If the workspace contains any GUI objects whose VISIBLE property is 1, these objects will be displayed. If the workspace contains a non-empty ⎕SM but does not contain an SM GUI object, the form defined by ⎕SM will be displayed in a window on the screen.

Example:

      )LOAD SMDEMO
/usr/dyalog/WS/SMDEMO saved Wed Sep 6 21:46:27 1994
Type HOWDEMO for help


Save System Command

Save Workspace

)SAVE {ws}

This command compacts (see ⎕WA - Workspace Available for details) and saves the active workspace..

The workspace is saved with its state of execution intact. A stored workspace may subsequently be loaded with the system command )LOAD or the system function ⎕LOAD, and objects may be copied from a stored workspace with the system commands )COPY or )PCOPY or the system function ⎕CY.

This command may fail with one of the following error messages:

  • Unacceptable char. The given workspace name was ill-formed.

  • Not saved this ws is WSID. An attempt was made to change the name of the workspace for the save, and that workspace already existed.

  • Not saved this ws is CLEAR WS. The active workspace was CLEAR WS and no attempt was made to change the name.

  • Cannot create. The user does not have access to create the file OR the workspace name conflicts with an existing non- workspace file.

  • Cannot save with windows open. A workspace may not be saved if trace or edit windows are open.

An existing stored workspace with the same name will be replaced. The active workspace may be renamed by the system command )WSID or the system function ⎕WSID. See the rules for specifying a workspace name.

After a successful save, the system reports the workspace name, "saved", followed by the and the time and date.

Example:

      )SAVE MYWORK
./MYWORK saved Thu Jul 20 15:32:28 1995


WSID System Command

WS Identification

)WSID {ws}

This command displays or sets the name of the active workspace.

If a workspace name is not specified, )WSID reports the name of the current active workspace. The name reported is the full path name, including directory references.

If a workspace name is given, the current active workspace is renamed accordingly. The previous name of the active workspace (excluding directory references) is reported.

Examples:

      )LOAD WS/TEMP
WS/TEMP saved Sun Nov  5 14:32:09 1995

      )WSID
is WS/TEMP

      )WSID WS/KEEP
was WS/TEMP

      )WSID
WS/KEEP


XLOAD System Command

Load Workspace (no latent expression)

)XLOAD {ws}

This command causes the named stored workspace to be loaded. The current active workspace is lost.

)XLOAD is identical in effect to )LOAD except that )XLOAD does not cause the expression defined by the latent expression ⎕LX in the saved workspace to be executed.


DOS System Command

Windows Command Processor

)CMD {cmd}

)CMD executes a Windows Command Processor or UNIX shell.

)CMD is a synonym of )SH. Either system function may be used in either environment (Windows or UNIX) with exactly the same effect. )CMD is probably more natural for the Windows user. This section describes the behaviour of )CMD and )SH under DOS. See )SH for a discussion of the behaviour of these system functions under UNIX.

The system functions ⎕CMD and ⎕SH provide similar facilities but may be executed from within APL code.

Note that under Windows, you may not execute )CMD without a command. If you wish to, you can easily open a new Command Processor window outside APL.

Example:

      )CMD DIR

 Volume in drive C has no label
 Directory of C:\PETE\WS

.            <DIR>     5-07-95  3.02p
..           <DIR>     5-07-95  3.02p
SALES    DWS    110092 5-07-95  3.29p
EXPENSES DWS    154207 5-07-95  3.29p

If the command cmd issues prompts and expects user input, it is ESSENTIAL to explicitly redirect input and output to the console. If this is done, APL detects the presence of a ">" in the command line, runs command processor in a visible window, and does not direct output to the pipe. If you fail to do this your system will appear to hang because there is no mechanism for you to receive or respond to the prompt.

Example :

      )CMD 'DATE <CON >CON'

(Command Prompt window appears)
Current date is Wed 19-07-1995
Enter new date (dd-mm-yy): 20-07-95
(DOS window disappears)

Implementation Notes

The argument of )CMD is simply passed to the appropriate command processor for execution and its output is received using an unnamed pipe.

By default, )CMD will execute the string 'cmd.exe /c',Y where Y is the argument given to )CMD. However, the implementation permits the use of alternative command processors as follows.

Before execution, the argument is prefixed and postfixed with strings defined by the APL parameters CMD_PREFIX and CMD_POSTFIX. The former specifies the name of your command processor and any parameters that it requires. The latter specifies a string which may be required. If CMD_PREFIX is not defined, it defaults to the name defined by the environment variable COMSPEC followed by "/c". If COMSPEC is not defined, it defaults to cmd.exe.. If CMD_POSTFIX is not defined, it defaults to an empty vector.


Continue System Command

Save Continue

)CONTINUE

This command saves the active workspace under the name CONTINUE and ends the Dyalog APL session.

When you subsequently start another Dyalog APL session, the CONTINUE workspace is loaded automatically. Unless you have started APL using the "-x" flag, the latent expression (if any) is executed.

Note that the values of all system variables (including ⎕SM) and GUI objects are also saved in CONTINUE.


Off System Command

Sign Off APL

)OFF

This command terminates the APL session, returning to the Operating System command processor or shell.


Unix Shell System Command

Unix Shell Command

)SH {cmd}

This command allows Windows or UNIX shell commands to be given from APL. )SH is a synonym of )CMD. Either command may be given in either environment (Windows or UNIX) with exactly the same effect. )SH is probably more natural for the UNIX user. This section describes the behaviour of )SH and )CMD under UNIX. See )CMD for a discussion of their behaviour under Windows.

The system commands ⎕SH and ⎕CMD provide similar facilities but may be executed from within APL code.

)SH allows UNIX shell commands to be given from APL. The argument must be entered in the appropriate case (usually lower-case). The result of the command, if any, is displayed.

)SH without an argument opens a new window. In Versions of Dyalog APL for asynchronous terminals, )SH without an argument causes APL to fork a (Bourne) shell and wait. When the shell is closed ("exit" or Ctrl-d), control returns to APL.

Example:

      )SH ls
EXT
FILES


Holds System Command

Display Held Tokens

)HOLDS

System command )HOLDS displays a list of tokens which have been acquired or requested by the :Hold control structure.

Each line of the display is of the form:

token:
acq

req

req
...

Where acq is the number of the thread that has acquired the token, and req is the number of a thread which is requesting it. For a token to appear in the display, a thread (and only one thread) must have acquired it, whereas any number of threads can be requesting it.

Example

Thread 300’s attempt to acquire token 'blue' results in a deadlock:

300:DEADLOCK
Sema4[1] :Hold 'blue'
        ∧

      )HOLDS
blue:   100
green:  200     100
red:    300     200     100

... which means that ...

  • Blue has been acquired by thread 100.

  • Green has been acquired by 200 and requested by 100.

  • Red has been acquired by 300 and requested by 200 and 100.

The following cycle of dependencies has caused the deadlock:

Thread 300 attempts to acquire blue 300    blue
which is owned by 100                ↑       ↓
which is waiting for red            red  ←  100
which is owned by 300.


Thread Identity System Command

Thread Identity

)TID {tid}

Only a single thread can be suspended at any one time. You can switch the suspension between threads by using )TID.

If no thread number is given, )TID reports the number of the current thread.

Only those threads which are paused between lines of code can be suspended. Attempting to switch to a thread that is, for example, pendent or waiting for a :Hold, will fail.

Examples

      ⍝State indicator
      )si
·   print[1]
&3
·   ·   sub_calc[2]*
·   &2
·   calc[1]
&1
      ⍝Current thread
      )tid
is 2
      ⍝Switch suspension to thread 3
      )tid 3
was 2
      ⍝State indicator
      )si
·   print[1]*
&3
·   ·   sub_calc[2]
·   &2
·   calc[1]
&1
      ⍝Attempt to switch to pendent thread 1
      )tid 1
Can't switch, this thread is 3


Fix Object

{R}←⎕FX Y

Y is the representation form of a function or operator that may be:

  1. its canonical representation form similar to that produced by ⎕CR except that redundant blanks are permitted other than within names and constants.
  2. its nested representation form similar to that produced by ⎕NR except that redundant blanks are permitted other than within names and constants.
  3. its object representation form produced by ⎕OR.
  4. its vector representation form similar to that produced by ⎕VR except that additional blanks are permitted other than within names and constants.

⎕FX attempts to create (fix) a function or operator in the workspace from the definition given by Y. ⎕IO is an implicit argument of ⎕FX.

If the function or operator is successfully fixed, R is a simple character vector containing its name and the result is shy. Otherwise R is an integer scalar containing the (⎕IO dependent) index of the row of the canonical representation form in which the first error preventing its definition is detected. In this case the result R is not shy.

Functions and operators which are pendent, that is, in the State Indicator without a suspension mark (*), retain their original definition until they complete, or are cleared from the State Indicator. All other occurrences of the function or operator assume the new definition. The function or operator will fail to fix if it has the same name as an existing variable, or a visible label.


Canonical Representation

R←⎕CR Y

Y must be a simple character scalar or vector which represents the name of a function or a defined operator.

If Y is a name of a defined function or defined operator, R is a simple character matrix.  The first row of R is the function or operator header. Subsequent rows are lines of the function or operator. R contains no unnecessary blanks, except for leading indentation of control structures, trailing blanks that pad each row, and the blanks in comments. If Y is the name of a variable, a locked function or operator, an external function, or is undefined, R is an empty matrix whose shape is 0 0.

Example:

      ∇R←MEAN X    ⍝ Arithmetic mean
[1]  R←(+/X)÷⍴X
[2]  ∇

      +F←⎕CR'MEAN'
R←MEAN X    ⍝ Arithmetic mean
R←(+/X)÷⍴X

      ⍴F
2 30

The definition of ⎕CR has been extended to names assigned to functions by specification (←), and to local names of functions used as operands to defined operators.

If Y is a name assigned to a primitive function, R is a one-element vector containing the corresponding function symbol.  If Y is a name assigned to a system function, R is a 1-element nested array containing the name of the system function.

Examples:

      PLUS←+
      +F←⎕CR'PLUS'
+
      ⍴F
1
      C←⎕CR
      C'C'
 ⎕CR
      ⍴C'C'
1

      ∇R←CONDITION (FN1 ELSE FN2) X
[1]   →CONDITION/L1
[2]   R←FN2 X ⋄ →0
[3]   L1:R←FN1 X
[4]   ∇

      2 ⎕STOP 'ELSE'
      (X≥0) ⌊ ELSE ⌈ X←¯2.5

ELSE[2]
       X
¯2.5
       ⎕CR'FN2'
⌈
       →⎕LC
¯2

If Y is a name assigned to a derived function, R is a vector whose elements represent the arrays, functions, and operators from which Y were constructed. Constituent functions are represented by their own ⎕CRs, so in this respect the definition of ⎕CR is recursive.  Primitive operators are treated like primitive functions, and are represented by their corresponding symbols.  Arrays are represented by themselves.

Example:

      BOX←2 2∘⍴
      +F←⎕CR'BOX'
 2 2 ∘⍴
      ⍴F
3
      DISPLAY F
.→----------.
| .→--.     |
| |2 2| ∘ ⍴ |
| '~--' - - |
'∊----------'

If Y is a name assigned to a defined function, R is the ⎕CR of the defined function.  In particular, the name that appears in the function header is the name of the original defined function, not the assigned name Y.

Example:

      AVERAGE←MEAN
      ⎕CR'AVERAGE'
R←MEAN X    ⍝ Arithmetic mean
R←(+/X)÷⍴X


Nested Representation

R←⎕NR Y

Y must be a simple character scalar or vector which represents the name of a function or a defined operator.

If Y is a name of a defined function or defined operator, R is a vector of text vectors.  The first element of R contains the text of the function or operator header.  Subsequent elements contain lines of the function or operator. Elements of R contain no unnecessary blanks, except for leading indentation of control structures and the blanks which precede comments.

If Y is the name of a variable, a locked function or operator, an external function, or is undefined, R is an empty vector.

Example:

      ∇R←MEAN X    ⍝ Average
[1]    R←(+/X)÷⍴X
      ∇

      +F←⎕NR'MEAN'
  R←MEAN X    ⍝Average   R←(+/X)÷⍴X

      ⍴F
2
      DISPLAY F
.→----------------------------------------.
| .→---------------------.  .→----------. |
| | R←MEAN X    ⍝ Average|  | R←(+/X)÷⍴X| |
| '----------------------'  '-----------' |
'∊----------------------------------------'

The definition of ⎕NR has been extended to names assigned to functions by specification (←), and to local names of functions used as operands to defined operators.  In these cases, the result of ⎕NR is identical to that of ⎕CR except that the representation of defined functions and operators is as described above.

Example:

      AVG←MEAN∘,

      +F←⎕NR'AVG'
   R←MEAN X    ⍝ Average   R←(+/X)÷⍴X  ∘,

      ⍴F
3

      DISPLAY F
.→------------------------------------------------.
| .→----------------------------------------.     |
| | .→---------------------.  .→----------. | ∘ , |
| | | R←MEAN X    ⍝ Average|  | R←(+/X)÷⍴X| | - - |
| | '----------------------'  '-----------' |     |
| '∊----------------------------------------'     |
'∊------------------------------------------------'


Vector Representation

R←⎕VR Y

Y must be a simple character scalar or vector which represents the name of a function or defined operator.

If Y is the name of a defined function or defined operator, R is a simple character vector containing a character representation of the function or operator with each line except the last terminated by the newline character (⎕TC[3]).  Its display form is as follows:

  1. the header line starts at column 8 with the ∇ symbol in column 6.

    2.

  2. the line number for each line of the function starts in column 1.

    3.

  3. the statement contained in each line starts at column 8 except for labelled lines or lines beginning with ⍝ which start at column 7.

    4.

  4. the header line and statements contain no redundant blanks beyond column 7 except that the û separator is surrounded by single blanks, control structure indentation is preserved and comments retain embedded blanks as originally defined.

    5.

  5. the last line shows only the ∇ character in column 6.
    6.

If Y is the name of a variable, a locked function or operator, an external function, or is undefined, R is an empty vector.

Example:

      ⍴V←⎕VR'PLUS'
128

      V
     ∇ R←{A}PLUS B
[1]   ⍝ MONADIC OR DYADIC +
[2]    →DYADIC⍴⍨2=⎕NC'A' ⋄ R←B ⋄ →END
[3]   DYADIC:R←A+B ⋄ →END
[4]   END:
     ∇

The definition of ⎕VR has been extended to names assigned to functions by specification (←), and to local names of functions used as operands to defined operators.  In these cases, the result of ⎕VR is identical to that of ⎕CR except that the representation of defined functions and operators is as described above.

Example:

      AVG←MEAN∘,

      +F←⎕VR'AVG'
      ∇ R←MEAN X    ⍝ Arithmetic mean
[1]    R←(+/X)÷⍴X
     ∇ ∘,

      ⍴F
3

      DISPLAY F
.→-------------------------------------------.
| .→-----------------------------------.     |
| |     ∇ R←MEAN X    ⍝ Arithmetic mean| ∘ , |
| |[1]    R←(+/X)÷⍴X                   | - - |
| |     ∇                              |     |
| '------------------------------------'     |
'∊-------------------------------------------'


Object Representation

R←⎕OR Y

⎕OR converts a function, operator or namespace to a special form, described as its object representation, that may be assigned to a variable and/or stored on a component file. Classes and Instances are however outside the domain of ⎕OR.

Taking the ⎕OR of a function or operator is an extremely fast operation as it simply changes the type information in the object’s header, leaving its internal structure unaltered. Converting the object representation back to an executable function or operator using ⎕FX is also very fast. ⎕OR is therefore the recommended form for storing functions and operators on component files and is significantly faster than using ⎕CR, ⎕VR or ⎕NR.

⎕OR may also be used to convert a namespace (either a plain namespace or a named GUI object created by ⎕WC ) into a form that can be stored in a variable or on a component file. The namespace may be reconstructed using ⎕NS or ⎕WC with its original name or with a new one. ⎕OR may therefore be used to clone a namespace or GUI object.

Y must be a simple character scalar or vector which contains the name of an APL object.

If Y is the name of a variable, the result R is its value. In this case, R←⎕OR Y is identical to R←Y.

Otherwise, R is a special form of the name Y, re-classified as a variable. The shape of R is <—> (R is scalar), and the depth of R is 1. These unique characteristics distinguish the result of ⎕OR from any other object. The type of R (∊R) is itself. Note that although R is scalar, it may not be index assigned to an element of an array unless it is enclosed.

If Y is the name of a function or operator, R is in the domain of the monadic functions Depth (≡), Disclose (⊃), Enclose (⊂), Format (⍕), Identity (+), Shape (⍴), Type (∊) and Unique (∪), of the dyadic functions Assignment (←), Excluding (~), Index Of (⍳), Intersection (∩), Match (≡), Membership (∊), Not Match (≢) and Union (∪), and of the monadic system functions Canonical Representation (⎕CR), Cross-Reference (⎕REFS), Fix (⎕FX), Format (⎕FMT), Nested Representation (⎕NR) and Vector Representation (⎕VR).

Nested arrays which include the object representations of functions and operators are in the domain of many mixed functions which do not use the values of items of the arrays.

The object representation forms of namespaces produced by ⎕OR may not be used as arguments to any primitive functions. The only operations permitted for such objects (or arrays containing such objects) are ⎕EX, ⎕FAPPEND, ⎕FREPLACE, ⎕NS, and ⎕WC.

Example:

      F←⎕OR ⎕FX'R←FOO' 'R←10'

      ⍴F

      ⍴⍴F
0
      ≡F
1
      F≡∊F
1

The display of the ⎕OR form of a function or operator is a listing of the function or operator. If the ⎕OR form of a function or operator has been enclosed, then the result will display as the operator name preceded by the symbol ∇. It is permitted to apply ⎕OR to a locked function or operator. In this instance the result will display as for the enclosed form.

Examples:

       F
      ∇ R←FOO
[1]     R←10
      ∇

      ⊂F
 ∇FOO

      ⎕LOCK'FOO'

      ⎕OR'FOO'
∇FOO
      A←⍳5

      A[3]←⊂F

      A
1 2  ∇FOO  4 5

For the ⎕OR forms of two functions or operators to be considered identical, their unlocked display forms must be the same, they must either both be locked or unlocked, and any monitors, trace and stop vectors must be the same.

Example:

      F←⎕OR ⎕FX 'R←A PLUS B' 'R←A+B'

      F≡⎕OR 'PLUS'
1

      1 ⎕STOP 'PLUS'

      F≡⎕OR 'PLUS'
0

Namespace Examples

The following example sets up a namespace called UTILS, copies into it the Contents of the UTIL workspace, then writes it to a component file:

      )CLEAR
clear ws
      )NS UTILS
#.UTILS
      )CS UTILS
#.UTILS
      )COPY UTIL
C:\WDYALOG\WS\UTIL saved Fri Mar 17 12:48:06 1995
      )CS
#
      'ORTEST' ⎕FCREATE 1
      (⎕OR'UTILS')⎕FAPPEND 1

The namespace can be restored with ⎕NS, using either the original name or a new one:

      )CLEAR
clear ws
      'UTILS' ⎕NS ⎕FREAD 1 1
#.UTILS
      )CLEAR
clear ws
      'NEWUTILS' ⎕NS ⎕FREAD 1 1
#.NEWUTILS

This example illustrates how ⎕OR can be used to clone a GUI object; in this case a Group containing some Button objects. Note that ⎕WC will accept only a ⎕OR object as its argument (or preceded by the “Type” keyword). You may not specify any other properties in the same ⎕WC statement, but you must instead use ⎕WS to reset them afterwards.

    'F'⎕WC'Form'
    'F.G1' ⎕WC 'Group' '&One' (10 10)(80 30)
    'F.G1.B2'⎕WC'Button' '&Blue' (40 10)('Style' 'Radio')
    'F.G1.B3'⎕WC'Button' '&Green' (60 10)('Style' 'Radio')
    'F.G1.B1'⎕WC'Button' '&Red' (20 10)('Style' 'Radio')
    'F.G2' ⎕WC ⎕OR 'F.G1'
    'F.G2' ⎕WS ('Caption' 'Two')('Posn' 10 60)

Note too that ⎕WC and ⎕NS may be used interchangeably to rebuild pure namespaces or GUI namespaces from a ⎕OR object. You may therefore use ⎕NS to rebuild a Form or use ⎕WC to rebuild a pure namespace that has no GUI components.


Attributes

R←{X}⎕AT Y

Y can be a simple character scalar, vector or matrix, or a vector of character vectors representing the names of 0 or more defined functions or operators. Used dyadically, this function closely emulates the APL2 implementation. Used monadically, it returns information that is more appropriate for Dyalog APL.

Monadic Use

If X is omitted, R is a 4 column matrix with the same number of rows as functions in Y containing the following attribute information:

R[;1]Each item is a 3-element integer vector representing the function header syntax:

1 | Function Result | 0 if the function has no result 1if the function has an explicit result ¯1 if the function has a shy result
2 | Function valence | 0 if the object is a niladic function or not a function 1 if the object is a monadic functio 2 if the object is a dyadic functionn ¯2 if the object is an ambivalent function
3 | Operator valence | 0 if the object is not an operator 1 if the object is a monadic operator 2 if the object is a dyadic operator

The following values correspond to the syntax shown alongside:

        0  0  0     ∇ FOO
        1  0  0     ∇ Z←FOO
       ¯1  0  0     ∇ {Z}←FOO
        0 ¯2  0     ∇ {A} FOO B
       ¯1  1  2     ∇ {Z}←(F OP G)B

R[;2]Each item is the (⎕TS form) timestamp of the time the function was last fixed.

R[;3]Each item is an integer reporting the current ⎕LOCK state of the function:

0 | Not locked
1 | Cannot display function
2
 Cannot suspend function
3 | Cannot display or suspend.

R[;4]Each item is a character vector - the network ID of the user who last fixed (edited) the function.

Example

     ∇{z}←{l}(fn myop)r
[1]   ...
     ∇

     ∇z←foo
[1]   ...
     ∇

      ∇z←{larg}util rarg
[1]   ...
     ∇
      DISPLAY ⎕AT 'myop' 'foo' 'util'
.→-------------------------------------------.
↓ .→------. .→-------------------.   .→---.  |
| |¯1 ¯2 1| |1997 2 13 12 30 53 0| 0 |john|  |
| '~------' '~-------------------'   '----'  |
| .→----.   .→-------------------.   .→----. |
| |1 0 0|   |1997 2 13 12 31 10 0| 0 |geoff| |
| '~----'   '~-------------------'   '-----' |
| .→-----.  .→-------------------.   .→---.  |
| |1 ¯2 0|  |1997 2 13 12 31 50 0| 0 |pete|  |
| '~-----'  '~-------------------'   '----'  |

'∊-------------------------------------------'

Dyadic Use

The dyadic form of ⎕AT emulates APL2. It returns the same rank and shape result containing information that matches the APL2 implementation as closely as possible.

If Y specifies a single name, the result R is a vector. If Y specifies more than one name, R is a matrix with one row per name in Y. The number of elements (columns) and their meaning depends upon the value of X which may be 1, 2, 3 or 4.

If X is 1, R specifies valences and contains 3 elements (or columns) whose meaning is as follows:

1 | Explicit result | 1 if the object has an explicit result or is a variable 0 otherwise
2 | Function valence | 0 if the object is a niladic function or not a function 1 if the object is a monadic function 2 if the object is an ambivalent function
3 | Operator valence | 0 if the object is not an operator 1 if the object is a monadic operator 2 if the object is a dyadic operator

If X is 2, R specifies fix times (the time the object was last updated) for functions and operators named in Y. The time is reported as 7 integer elements (or columns) whose meaning is as follows. The fix time reported for names in Y which are not defined functions or operators is 0.

1 | Year
2 | Month
3 | Day
4 | Hour
5 | Minute
6 | Second
7 | Milliseconds (this is always reported as 0)

If X is 3, R specifies execution properties and contains 4 elements (or columns) whose meaning is as follows:

1 | Displayable | 0 if the object is displayable 1 if the object is not displayable
2 | Suspendable | 0 if execution will suspend in the object 1 if execution will not suspend in the object
3 | Weak Interrupt behaviour | 0 if the object responds to interrupt 1 if the object ignores interrupt
4 |  | (always 0)

Note that the execution properties for primitive and system functions are 0 1 1 0.

If X is 4, R specifies object size and contains 2 elements (or columns) which both report the ⎕SIZE of the object.


Create Namespace

{R}←{X} ⎕NS Y

If specified, X must be a simple character scalar or vector identifying the name of a namespace.

Y is either a character array which represents a list of names of objects to be copied into the namespace, or is an array produced by the ⎕OR of an existing namespace. In the first case, Y must be a simple character scalar, vector, matrix or a nested vector of character vectors identifying zero or more workspace objects to be copied into the namespace X. The identifiers in X and Y may be simple names or compound names separated by '.' and including the names of the special namespaces '#', '##' and ''.

The namespace X is created if it doesn't already exist. If the name is already in use for an object other than a namespace, APL issues a DOMAIN ERROR.

If X is omitted, an unnamed namespace is created.

The objects identified in the list Y are copied into the namespace X.

If X is specified, the result R is the full name (starting #. or ⎕SE.) of the namespace X. If X is omitted, the result R is a namespace reference, or ref, to an unnamed namespace.

Examples:

      ⎕←'X' ⎕NS ''                 ⍝ Create namespace X.
#.X
      ⎕←'X' ⎕NS 'VEC' 'UTIL.DISP'  ⍝ Copy VEC & DISP into X.
#.X

      )CS X                        ⍝ Change to namespace X.
#.X
      ⎕←'Y' ⎕NS '#.MAT' '##.VEC'   ⍝ Create #.X.Y & copy into it
#.X.Y

      ⎕←'#.UTIL' ⎕NS 'Y.MAT'       ⍝ Copy MAT from Y to #.UTIL.
#.UTIL

      ⎕←'#' ⎕NS 'Y'                ⍝ Copy namespace Y to root.
#

      ⎕←'' ⎕NS '#.MAT'             ⍝ Copy MAT to current space.
#.X

      ⎕←'' ⎕NS ''                  ⍝ Display current namespace.
#.X

      'Z' ⎕NS ⎕OR 'Y'              ⍝ Create namespace from ⎕OR.
#.X.Z

      NONAME←⎕NS ''                ⍝ Create unnamed namespace
      NONAME
#.[Namespace]

      DATA←⎕NS¨4⍴⊂''               ⍝ Create 4-element vector of distinct unnamed namespaces

      DATA
 #.[Namespace]  #.[Namespace]  #.[Namespace]  #.[Namespace]

The second case is where Y is the ⎕OR of a namespace.

If Y is the ⎕OR of a GUI object, #.Z must be a valid parent for the GUI object represented by Y, or the operation will fail with a DOMAIN ERROR.

Otherwise, the result of the operation depends upon the existence of Z.

  • If Z does not currently exist (name class is 0), Z is created as a complete copy (clone) of the original namespace represented by Y. If Y is the ⎕OR of a GUI object or of a namespace containing GUI objects, the corresponding GUI components of Y will be instantiated in Z.
  • If Z is the name of an existing namespace (name class 9), the contents of Y, including any GUI components, are merged into Z. Any items in Z with corresponding names in Y (names with the same path in both Y and Z) will be replaced by the names in Y, unless they have a conflicting name class in which case the existing items in Z will remain unchanged. However, all GUI spaces in Z will be stripped of their GUI components prior to the merge operation.


Change Space

{R}←{X}⎕CS Y

Y must be a namespace reference (ref) or a simple character scalar or vector identifying the name of a namespace.

If specified, X is a simple character scalar, vector, matrix or a nested vector of character vectors identifying zero or more workspace objects to be exported into the namespace Y.

The identifiers in X and Y may be simple names or compound names separated by '.' and including the names of the special namespaces '⎕SE', '#',
and '##'.

The result R is the full name (starting
#.) of the space in which the function or operator was executing prior to the ⎕CS.

⎕CS changes the space in which the current function or operator is running to the namespace Y and returns the original space, in which the function was previously running, as a shy result.  After the ⎕CS, references to global names (with the exception of those specified in X) are taken to be references to global names in Y.  References to local names (i.e. those local to the current function or operator) are unaffected.

When the function or operator terminates, the calling function resumes execution in its original space.

The names listed in X are temporarily exported to the namespace Y.  If objects with the same name exist in Y , these objects are effectively shadowed and are inaccessible.

Note that calling ⎕CS with an empty argument Y obtains the namespace in which a function is currently executing.

Example:

This simple example illustrates how ⎕CS may be used to avoid typing long pathnames when building a tree of GUI objects.  Note that the objects NEW and OPEN are created as children of the FILE menu as a result of using ⎕CS to change into the F.MB.FILE namespace.

     ∇ MAKE_FORM;F;OLD
[1]    'F'⎕WC'Form'
[2]    'F.MB'⎕WC'MenuBar'
[3]    'F.MB.FILE'⎕WC'Menu' '&File'
[4]
[5]    OLD←⎕CS'F.MB.FILE'
[6]    'NEW'⎕WC'MenuItem' '&New'
[7]    'OPEN'⎕WC'MenuItem' '&Open'
[8]    ⎕CS OLD
[9]
[10]   'F.MB.EDIT'⎕WC'Menu' '&Edit'
[11]
[12]   OLD←⎕CS'F.MB.EDIT'
[13]   'UNDO'⎕WC'MenuItem' '&Undo'
[14]   'REDO'⎕WC'MenuItem' '&Redo'
[15]   ⎕CS OLD
[16]   ...
     ∇

Example:

This example illustrates how ⎕CS can be used to handle multiple instances of an object

Suppose a form F1 contains buttons B1 and B2. Each button maintains a count of the number of times it has been pressed, and the form maintains a count of the total number of button presses. The single callback function PRESS and its subfunction FMT can reside in the form itself

      )CS F1
#.F1
      ⍝ Note that both instances reference
      ⍝ the same callback function
      'B1'⎕WS'Event' 'Select' 'PRESS'
      'B2'⎕WS'Event' 'Select' 'PRESS'

      ⍝ Initialise total and instance counts.
      TOTAL ← B1.COUNT ← B2.COUNT ← 0

    ∇ PRESS MSG
[1]   'FMT' 'TOTAL'⎕CS⊃MSG          ⍝ Switch to instance space.
[2]   (TOTAL COUNT)+←1              ⍝ Incr total & instance count.
[3]   ⎕WS'Caption'(COUNT FMT TOTAL) ⍝ Set instance caption.
    ∇

    ∇ CAPT←INST FMT TOTL            ⍝ Format button caption.
[1]   CAPT←(⍕INST),'/',⍕TOTL        ⍝ E.g. 40/100.

Example:

This example uses ⎕CS to explore a namespace tree and display the structure.  Note that it must export its own name (tree) each time it changes space, because the name tree is global.

      ∇ tabs tree space;subs     ⍝ Display namespace tree
[1]    tabs,space
[2]    'tree'⎕CS space
[3]    →(⍴subs←↓⎕NL 9)↓0
[4]    (tabs,'.   ')∘tree¨subs
     ∇

      )ns x.y
#.x.y
      )ns z
#.z
      ''tree '#'
#
.   x
.   .   y
.   z


Copy Objects

{X}⎕CY Y

Y must be a simple character scalar or vector identifying a saved workspace. X is optional. If present, it must be a simple character scalar, vector or matrix. A scalar or vector is treated as a single row matrix. Each (implied) row of X is interpreted as an APL name.

Each (implied) row of X is taken to be the name of an active object in the workspace identified by Y. If X is omitted, the names of all defined active objects in that workspace are implied (defined functions and operators, variables and labels).

Each object named in X (or implied) is copied from the workspace identified by Y to become the active object referenced by that name in the active workspace if the object can be copied. A copied label is re-defined to be a variable of numeric type. If the name of the copied object has an active referent in the active workspace, the name is disassociated from its value and the copied object becomes the active referent to that name. In particular, a function in the state indicator which is disassociated may be executed whilst it remains in the state indicator, but it ceases to exist for other purposes, such as editing.

You may copy an object from a namespace by specifying its full pathname. The object will be copied to the current namespace in the active workspace, losing its original parent and gaining a new one in the process. You may only copy a GUI object into a namespace that is a suitable parent for that object. For example, you could only copy a Group object from a saved workspace if the current namespace in the active workspace is itself a Form, SubForm or Group.

A DOMAIN ERROR is reported if any of the following events pertain:

  • Y is ill-formed, or is not the name of a workspace with access authorised for the active user account.
  • Any name in X is ill-formed.
  • An object named in X does not exist as an active object in the workspace named in Y.

When copying data between Classic and Unicode Editions, ⎕CY will fail and a TRANSLATION ERROR will be reported if any object in workspace Y fails conversion between Unicode and ⎕AV indices, whether or not that object is specified by X. See ⎕AVU for further details.

A WS FULL is reported if the active workspace becomes full during the copying process.

Example:

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇
      'FOO' ⎕CY 'BACKUP'
      ⎕VR'FOO'
     ∇ R←FOO X
[1]    R←10×X
     ∇

System variables are copied if explicitly included in the left argument, but not if the left argument is omitted.

Example:

      ⎕LX
      (2 3⍴'⎕LX  X')⎕CY'WS/CRASH'
      ⎕LX
→RESTART

A copied object may have the same name as an object being executed. If so, the name is disassociated from the existing object, but the existing object remains defined in the workspace until its execution is completed.

Example:

      )SI
FOO[1]*

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇

      'FOO'⎕CY'WS/MYWORK'

      FOO
1 2 3
      )SI
FOO[1]*
      →⎕LC
10


Export Objects

{R}←{X}⎕EXPORT Y

⎕EXPORT is used to set or query the export type of a defined function (or operator) referenced by the ⎕PATH mechanism.

Y is a character matrix or vector-of-vectors representing the names of functions and operators whose export type is to be set or queried.

X is an integer scalar or vector (one per name in the namelist) indicating the export type. X can currently be one of the values:

0 - not exported.
1 - exported (default).

A scalar or 1-element-vector type is replicated to conform with a multi-name list.

The result R is a vector that reports the export type of the functions and operators named in Y. When used dyadically to set export type, the result is shy.

When the path mechanism locates a referenced function (or operator) in the list of namespaces in the ⎕PATH system variable, it examines the function’s export type:

0 | This instance of the function is ignored and the search is resumed at the next namespace in the ⎕PATH list. Type-0 is typically used for functions residing in a utility namespace which are not themselves utilities, for example the private sub-function of a utility function.
1 | This instance of the function is executed in the namespace in which it was found and the search terminated. The effect is exactly as if the function had been referenced by its full path name.

Warning: The left domain of ⎕EXPORT may be extended in future to include extra types 2, 3, ... (for example, to change the behaviour of the function). This means that, while ⎕EXPORT returns a Boolean result in the first version, this may not be the case in the future. If you need a Boolean result, use 0<— or an equivalent.

      (0≠⎕EXPORT ⎕nl 3 4)/⎕nl 3 4    ⍝ list of exported functions and operators.


Search Path

⎕PATH

⎕PATH is a simple character vector representing a blank-separated list of namespaces. It is approximately analogous to the PATH variable in MS-DOS or UNIX

The ⎕PATH variable can be used to identify a namespace in which commonly used utility functions reside. Functions (or operators) which are copied into this namespace can then be used directly from anywhere in the workspace without giving their full path names.

For example:

      ⎕PATH←'⎕se.util'⎕ns''      ⍝ Create and reference utility namespace.
      'DISPLAY'⎕se.util.⎕cy'UTIL'⍝ Copy DISPLAY function from UTIL into it.
                                 ⍝ (Remember to save the session to file).

the DISPLAY function is then available directly from within any namespace.

In detail, ⎕PATH works as follows:

When a reference to a name cannot be found in the current namespace, the system searches for it from left to right in the list of namespaces indicated by ⎕PATH. In each namespace, if the name references a defined function (or operator) and the export type of that function is non-zero (see ⎕EXPORT), then it is used to satisfy the reference. If the search exhausts all the namespaces in ⎕PATH without finding a qualifying reference, the system issues a VALUE ERROR in the normal manner.

The special character ↑ stands for the list of namespaces:

       ## ##.## ##.##.## ...

In other words, the search is conducted upwards through enclosing namespaces, emulating the static scope rule inherent in modern block-structured languages.

Note that the ⎕PATH mechanism is used ONLY if the function reference cannot be satisfied in the current namespace. This is analogous to the case when the MS_DOS or UNIX PATH variable begins with a '.'.

Examples:

    ⎕PATH              Search in ...
    -----              -------------
1. '⎕se.util'          Current space,   then
                       ⎕se.util,        then
                       VALUE ERROR

2. '↑'                 Current space
                       Parent space: ##
                       Parent's parent space:  ##.##
                       ...
                       Root: # (or ⎕se if current space was inside ⎕se)
                       VALUE ERROR

3. 'util ↑ ⎕se.util'   Current space
                       util (relative to current space)
                       Parent space: ##
                       ...
                       Root: # or ⎕se
                       ⎕se.util
                       VALUE_ERROR

Note that ⎕PATH is a session variable. This means that it is workspace-wide and survives )LOAD and )CLEAR. It can of course, be localised by a defined function or operator.


Lock Object

{X} ⎕LOCK Y

Y must be a simple character scalar, or vector which is taken to be the name of a defined function or operator in the active workspace.

The active referent to the name in the workspace is locked. Stop, trace and
monitor settings established by the ⎕STOP, ⎕TRACE
and ⎕MONITOR functions, are cancelled.

The optional left argument X specifies to what extent the function code is hidden. X may be 1, 2 or 3 (the default) with the following meaning:

  1. The object may not be displayed and you may not obtain its character form using ⎕CR, ⎕VR or ⎕NR.
    2.

  2. Execution cannot be suspended with the locked function or operator in the state indicator.  On suspension of execution the state indicator is cut back to the statement containing the call to the locked function or operator.
    3.

  3. Both 1 and 2 apply. You can neither display the locked object nor suspend execution within it.
    4.

Locks are additive, so that

      1 ⎕LOCK'FOO'
      2 ⎕LOCK'FOO'

is the same as:

      3 ⎕LOCK'FOO'

A DOMAIN ERROR is reported if:

  • Y is ill-formed.
    •

  • The name in Y is not the name of a visible defined function or operator which is not locked.
    •

Examples:

      ⎕VR'FOO'
     ∇ R←FOO
[1]    R←10
     ∇

      ⎕LOCK'FOO'
      ⎕VR'FOO'

      ⎕LOCK'FOO'
DOMAIN ERROR
      ⎕LOCK'FOO'
      ∧


Migration Level

⎕ML

⎕ML determines the degree of migration of the Dyalog APL language towards IBM's APL2. Setting this variable to other than its default value of 0 changes the interpretation of certain symbols and language constructs.

⎕ML←0 | Native Dyalog (Default).
⎕ML←1 | Z←∊R | Monadic '∊' is interpreted as 'enlist' rather than 'type'.
⎕ML←2 | Z←↑R | Monadic '↑' is interpreted as 'first' rather than 'mix'.
Z←⊃R
 Monadic '⊃' is interpreted as 'mix' rather than 'first'.
Z←≡R | Monadic '≡' returns a positive rather than a negative value if its argument has non-uniform depth.
⎕ML←3
R←X⊂[K]Y
 Dyadic '⊂' follows the APL2 (rather than the original Dyalog APL) convention.
⎕TC
 The order of the elements of ⎕TC is the same as in APL2.

Subsequent versions of Dyalog APL will provide further migration levels.

Examples

      X←2(3 4)

      ⎕ML←0
      ∊X
0  0 0
      ↑X
2 0
3 4
      ⊃X
2
      X
¯2

      ⎕ML←1
      ∊X
2 3 4
      ↑X
2 0
3 4
      ⊃X
2
      X
¯2

      ⎕ML←2
      ∊X
2 3 4
      ↑X
2
      ⊃X
2 0
3 4
      X
2


Using System Function

Using (.Net)

⎕USING

⎕USING specifies a list of Microsoft .Net Namespaces that are to be searched for a reference to a .Net class.

⎕USING is a vector of character vectors, each element of which specifies the name of a .Net Namespace followed optionally by a comma (,) and the Assembly in which it is to be found.

If the Assembly is defined in the global assembly cache, you need only specify its name. If not, you must specify a full or relative pathname.

If the Microsoft .Net Framework is installed, the System namespace in mscorlib.dll is automatically loaded when Dyalog APL starts. To access this namespace, it is not necessary to specify the name of the Assembly.

⎕USING has namespace scope. If the local value of ⎕USING is anything other than empty, and you reference a name that would otherwise generate a VALUE ERROR, APL searches the list of .Net Namespaces and Assemblies specified by ⎕USING for a class of that name. If it is found, an entry for the class is added to the symbol table in the current space and the class is used as specified. Note that subsequent references to that class in the current space will be identified immediately.

If ⎕USING is empty (its default value in a CLEAR WS) no such search is performed.

Note that when you assign a value to ⎕USING, you may specify a simple character vector or a vector of character vectors.

Examples:

      ⎕USING←'System'
      DISPLAY ⎕USING
.→---------.
| .→-----. |
| |System| |
| '------' |
'∊---------'

      ⎕USING,←⊂'System.Windows.Forms,System.Windows.Forms.dll'
      ⎕USING,←⊂'System.Drawing,System.Drawing.dll'

An Assembly may contain top-level classes which are not packaged into .Net Namespaces. In this case, you omit the Namespace name. For example:

      ⎕USING←,⊂',.\LoanService.dll'


Verify And Fix Input

Verify & Fix Input

R←{X}⎕VFI Y

Y must be a simple character scalar or vector.  X is optional.  If present, X must be a simple character scalar or vector.  R is a nested vector of length two whose first item is a simple logical vector and whose second item is a simple numeric vector of the same length as the first item of R.

Y is the character representation of a series of numeric constants.  If X is omitted, adjacent numeric strings are separated by one or more blanks.  Leading and trailing blanks and separating blanks in excess of one are redundant and ignored.  If X is present, X specifies one or more alternative separating characters.  Blanks in leading and trailing positions in Y and between numeric strings separated also by the character(s) in X are redundant and ignored.  Leading, trailing and adjacent occurrences of the character(s) in X are not redundant.  The character 0 is implied in Y before a leading character, after a trailing character, and between each adjacent pair of characters specified by X.

The length of the items of R is the same as the number of identifiable strings (or implied strings) in Y separated by blank or the value of X.  An element of the first item of R is 1 where the corresponding string in Y is a valid numeric representation, or 0 otherwise. An element of the second item of R is the numeric value of the corresponding string in Y if it is a valid numeric representation, or 0 otherwise.

Examples:

      ⎕VFI '12.1 1E1 1A1 ¯10'
 1 1 0 1  12.1 10 0 ¯10

      ⊃(//⎕VFI'12.1 1E1 1A1 ¯10')
12.1 10 ¯10

      ','⎕VFI'3.9,2.4,,76,'
 1 1 1 1 1  3.9 2.4 0 76 0

      '⋄'⎕VFI'1 ⋄ 2 3 ⋄ 4 '
 1 0 1  1 0 4


Character Input/Output

⍞

⍞ (quote=quad) is a variable which communicates between the user's terminal and APL.  Its behaviour depends on whether it is being assigned or referenced.

When ⍞ is assigned with a vector or a scalar, the array is displayed without the normal ending new-line character.  Successive assignments of vectors or scalars to ⍞ without any intervening input or output cause the arrays to be displayed on the same output line.

Example:

      ⍞←'2+2' ⋄ ⍞←'=' ⋄ ⍞←4
2+2=4

Output through ⍞ is independent of the print width in ⎕PW.  The way in which lines exceeding the print width of the terminal is treated is dependent on the characteristics of the terminal.  Numeric output is formatted in the same manner as direct output (see DISPLAY OF ARRAYS).

When ⍞ is assigned with a higher-order array, the output is displayed in the same manner as for direct output except that the print width ⎕PW is ignored.

When ⍞ is referenced, terminal input is expected without any specific prompt, and the response is returned as a character vector.

If the ⍞ request was preceded by one or more assignments to ⍞ without any intervening input or output, the last (or only) line of the output characters are returned as part of the response.

Examples:

      ⍞←'OPTION : ' ⋄ R←⍞
OPTION : INPUT

      R
OPTION : INPUT

      ⍴R
14

The output of simple arrays of rank greater than 1 through ⍞ includes a new-line character at the end of each line.  Input through ⍞ includes the preceding output through ⍞ since the last new-line character. The result from ⍞, including the prior output, is limited to 256 characters.

A soft interrupt causes an INPUT INTERRUPT error if entered while ⍞ is awaiting input, and execution is then suspended (unless the interrupt is trapped):

      R←⍞
(Interrupt)
INPUT INTERRUPT

A time limit is imposed on input through ⍞ if ⎕RTL is set to a non-zero value:

      ⎕RTL←5 ⋄ ⍞←'PASSWORD ? ' ⋄ R←⍞
PASSWORD ?
TIMEOUT
      ⎕RTL←5 ⋄ ⍞←'PASSWORD : ' ⋄ R←⍞
                                   ∧

The TIMEOUT interrupt is a trappable event.


Evaluated Input/Output

⎕

⎕ (quad) is a variable which communicates between the users terminal and APL.  Its behaviour depends on whether it is being assigned or referenced.

When ⎕ is assigned an array, the array is displayed at the terminal in exactly the same form as is direct output (see DISPLAY OF ARRAYS).

Example:

      ⎕←2+⍳5
3 4 5 6 7

      ⎕←2 4⍴'WINEMART'
WINE
MART

When ⎕ is referenced, a prompt (⎕:) is displayed at the terminal, and input is requested.  The response is evaluated and an array is returned if the result is valid.  If an error occurs in the evaluation, the error is reported as normal (unless trapped by a ⎕TRAP definition) and the prompt (⎕:) is again displayed for input.  An EOF interrupt reports INPUT INTERRUPT and the prompt (⎕:) is again displayed for input.  A soft interrupt is ignored and a hard interrupt reports INTERRUPT and the prompt (⎕:) is redisplayed for input.

Examples:

      10×⎕+2
⎕:
      ⍳3
30 40 50

      2+⎕
⎕:
      X
VALUE ERROR
      X
     ∧
⎕:
      2+⍳3
5 6 7

A system command may be entered.  The system command is effected and the prompt is displayed again (unless the system command changes the environment):

      ⍴3,⎕
⎕:
      )WSID
WS/MYWORK
⎕:
      )SI
⎕
⎕:
      )CLEAR
CLEAR WS

If the response to a ⎕: prompt is an abort statement (→), the execution will be aborted:

      1 2 3 = ⎕
⎕:
      →

A trap definition on interrupt events set for the system variable ⎕TRAP in the range 1000-1006 has no effect whilst awaiting input in response to a ⎕: prompt.

Example:

      ⎕TRAP←(11 'C' '''ERROR''')(1000 'C' '''STOP''')

      2+⎕
⎕:
      (Interrupt Signal)
INTERRUPT
⎕:
      'C'+2
ERROR

A time limit set in system variable ⎕RTL has no effect whilst awaiting input in response to a ⎕: prompt.


Digits

R←⎕D

This is a simple character vector of the digits from 0 to 9.

Example:

      ⎕D
0123456789


Alphabetic Characters

R←⎕A

This is a simple character vector, composed of the letters of the alphabet.

Example:

      ⎕A
ABCDEFGHIJKLMNOPQRSTUVWXYZ


Null Item

R←⎕NULL

This is a reference to a null item, such as may be returned across the COM interface to represent a null value. An example might be the value of an empty cell in a spreadsheet.

⎕NULL may be used in any context that accepts a namespace reference, in particular:

  • As the argument to a defined function

  • As an item of an array.

  • As the argument to those primitive functions that take character data arguments, for example: =, ≠, ≡,≢ , ⍴, ⊃, ⊂, ...

Example

      'EX'⎕WC'OLEClient' 'Excel.Application'
      WB←EX.Workbooks.Open 'simple.xls'

      (WB.Sheets.Item 1).UsedRange.Value
 [Null]  [Null]  [Null]  [Null]  [Null]
 [Null]    Year  [Null]  [Null]  [Null]
 [Null]    1999    2000    2001    2002
 [Null]  [Null]  [Null]  [Null]  [Null]
 Sales      100      76     120     150
 [Null]  [Null]  [Null]  [Null]  [Null]
 Costs       80      60     100     110
 [Null]  [Null]  [Null]  [Null]  [Null]
 Margin      20      16      20      40

To determine which of the cells are filled , you can compare the array with ⎕NULL.

      ⎕NULL≢¨(WB.Sheets.Item 1).UsedRange.Value
0 0 0 0 0
0 1 0 0 0
0 1 1 1 1
0 0 0 0 0
1 1 1 1 1
0 0 0 0 0
1 1 1 1 1
0 0 0 0 0
1 1 1 1 1


Delay

{R}←⎕DL Y

Y must be a simple non-negative integer scalar or one- element vector.  A pause of approximately Y seconds is caused.  The shy result R is a scalar value indicating the length of the pause in seconds.  The pause may be interrupted by a strong interrupt.


Response Time Limit

⎕RTL

A non-zero value in ⎕RTL places a time limit, in seconds, for input requested via ⍞ , ⎕ARBIN , and ⎕SR. ⎕RTL may be assigned any integer in the range 0 to 32767. The value is a clear workspace is 0.

Example:

      ⎕RTL←5 ⋄ ⍞←'FUEL QUANTITY?' ⋄ R←⍞
FUEL QUANTITY?
VALUE ERROR
      ⎕RTL←5 ⋄ ⍞←'FUEL QUANTITY?' ⋄ R←⍞
                                    ∧


Format

⎕FMT

Monadic ⎕FMT means

Format

      ⎕FMT 3 5⍴'abcd' 1.1 .333
 abcd  1.1   0.33  abcd  1.1
 0.33  abcd  1.1   0.33  abcd
 1.1   0.33  abcd  1.1   0.33

Dyadic ⎕FMT means

Format By Specification

      'X1,F4.2' ⎕FMT 2 3⍴1.1 99
 1.10 **** 1.10
 **** 1.10 ****

Language Elements


Dyadic Format

R←X ⎕FMT Y

Y must be a simple array of rank not exceeding two, or a non-simple scalar or vector whose items are simple arrays of rank not exceeding two. The simple arrays in Y must be homogeneous, either character or numeric. X must be a simple character vector. R is a simple character matrix.

X is a format specification that defines how columns of the simple arrays in Y are to appear. A simple scalar in Y is treated as a one-element matrix. A simple vector in Y is treated as a one-column matrix. Each column of the simple arrays in Y is formatted in left-to-right order according to the format specification in X taken in left-to-right order and used cyclically if necessary.

R has the same number of columns as the longest column (or implied column) in Y, and the number of rows is determined from the format specification.

The accuracy and performance of the algorithm used to format floating-point numbers is controlled by the APLFormatBias parameter.

The format specification consists of a series of control phrases, with adjacent phrases separated by a single comma, selected from the following:

rAw | Alphanumeric format
rEw.s | Scaled format
rqFw.d | Decimal format
rqG⍞pattern⍞ | Pattern
rqIw | Integer format
Tn | Absolute tabulation
Xn | Relative tabulation
⍞t⍞ | Text insertion.

(Alternative surrounding pairs for Pattern or Text insertion are

< >, ⊂ ⊃, ⎕ ⎕ or ¨ ¨.)

where:

r | is an optional repetition factor indicating that the format phrase is to be applied to r columns of Y.
q | is an optional usage of qualifiers or affixtures from those described below.
w | is an integer value specifying the total field width per column of Y, including any affixtures.
s | is an integer value specifying the number of significant digits in Scaled format; s must be less than w⍎1.
d | is an integer value specifying the number of places of decimal in Decimal format; d must be less than w.
n | is an integer value specifying a tab position relative to the notional left margin (for T-format) or relative to the last formatted position (for X-format) at which to begin the next format.
t | is any arbitrary text excluding the surrounding character pair. Double quotes imply a single quote in the result.
pattern | see following section G format

Qualifiers q are as follows:

B | leaves the field blank if the result would otherwise be zero.
C | inserts commas between triads of digits starting from the rightmost digit of the integer part of the result.
Km | scales numeric values by 1Em where m is an integer; negation may be indicated by ¯ or - preceding the number.
L | left justifies the result in the field width.
Ov⍞t⍞ | replaces specific numeric value v with the text t.
S⍞p⍞ substitutes standard characters. p is a string of pairs of symbols enclosed between any of the Text Insertion delimiters. The first of each pair is the standard symbol and the second is the symbol to be substituted. Standard symbols are as follows:
* | overflow fill character
. | decimal point
, | triad separator for C qualifier
0 | fill character for Z qualifier
_ | loss of precision character
Z | fills unused leading positions in the result with zeros (and commas if C is also specified).
9 | digit selector

Affixtures are as follows:

M⍞t⍞ | prefixes negative results with the text t instead of the negative sign.
N⍞t⍞ | post-fixes negative results with the text t.
P⍞t⍞ | prefixes positive or zero results with the text t.
Q⍞t⍞ | post-fixes positive or zero results with the text t.
R⍞t⍞ | presets the field with the text t which is repeated as necessary to fill the field. The text will be replaced in parts of the field filled by the result, including the effects of other qualifiers and affixtures except the B qualifier.

The surrounding affixture delimiters may be replaced by the alternative pairs described for Text Insertion.

Examples

A vector is treated as a column:

      'I5' ⎕FMT 10 20 30
   10
   20
   30

The format specification is used cyclically to format the columns of the right argument:

      'I3,F5.2' ⎕FMT 2 4⍴⍳8
  1 2.00  3 4.00
  5 6.00  7 8.00

The columns of the separate arrays in the items of a non-simple right argument are formatted in order.  Rows in a formatted column beyond the length of the column are left blank:

      '2I4,F7.1' ⎕FMT (⍳4)(2 2⍴ 0.1×⍳4)
   1   0    0.2
   1   0    0.4
   3
   4

Characters are right justified within the specified field width, unless the L qualifier is specified:

      'A2' ⎕FMT 1 6⍴'SPACED'
 S P A C E D

If the result is too wide to fit within the specified width, the field is filled with asterisks:

      'F5.2' ⎕FMT 0.1×5 1000 ¯100
 0.50
*****
*****

Relative tabulation (X-format) identifies the starting position for the next format phrase relative to the finishing position for the previous format, or the notional left margin if none.  Negative values are permitted providing that the starting position is not brought back beyond the left margin.  Blanks are inserted in the result, if necessary:

      'I2,X3,3A1' ⎕FMT (⍳3)(2 3⍴'TOPCAT')
 1   TOP
 2   CAT
 3

Absolute tabulation (T-format) specifies the starting position for the next format relative to the notional left margin.  If position 0 is specified, the next format starts at the next free position as viewed so far.  Blanks are inserted into the result as required.  Over-written columns in the result contain the most recently formatted array columns taken in left-to-right order:

      X←'6I1,T5,A1,T1,3A1,T7,F5.1'

      X ⎕FMT (1 6⍴⍳6)('*')(1 3⍴'ABC')(22.2)
ABC4*6 22.2

If the number of specified significant digits exceeds the internal precision, low order digits are replaced by the symbol _:

      'F20.1' ⎕FMT 1E18÷3
3333333333333333__._

The Text Insertion format phrase inserts the given text repeatedly in all rows of the result:

      MEN←3 5⍴'FRED BILL JAMES'

      WOMEN←2 5⍴'MARY JUNE '

      '5A1,<|>' ⎕FMT MEN WOMEN
FRED |MARY |
BILL |JUNE |
JAMES|     |

The last example also illustrates that a Text Insertion phrase is used even though the data is exhausted.  The following example illustrates some effects of the various qualifiers:

      X←'F5.1,BF6.1,X1,ZF5.1,X1,LF5.1,K3CS<.,,.>F10.1'

      X ⎕FMT ⍉5 3⍴¯1.5 0 25
 ¯1.5  ¯1.5 ¯01.5 ¯1.5   ¯1.500,0
  0.0       000.0  0.0        0,0
 25.0  25.0 025.0 25.0   25.000,0

Affixtures allow text to be included within a field.  The field width is not extended by the inclusion of affixtures.  N and Q affixtures shift the result to the left by the number of characters in the text specification.  Affixtures may be used to enclose negative results in parentheses in accordance with common accounting practice:

      'M<(>N<)>Q< >F9.2' ⎕FMT 150.3 ¯50.25 0 1114.9
  150.30
  (50.25)
    0.00
 1114.90

One or more format phrases may be surrounded by parentheses and preceded by an optional repetition factor.  The format phrases within parentheses will be re-used the given number of times before the next format phrase is used.  A Text Insertion phrase will not be re-used if the last data format phrase is preceded by a closing parenthesis:

      'I2,2(</>,ZI2)' ⎕FMT 1 3⍴⌽100|3↑⎕TS
20/07/89

G Format

Only the B, K, S and O qualifiers are valid with the C option

⍞pattern⍞ is an arbitrary string of characters, excluding the delimiter characters.  Characters '9' and 'Z' (unless altered with the S qualifier) are special and are known as digit selectors.

The result of a C format will have length equal to the length of the pattern.

The data is rounded to the nearest integer (after possible scaling).  Each digit of the rounded data replaces one digit selector in the result.  If there are fewer data digits than digit selectors, the data digits are padded with leading zeros.  If there are more data digits than digit selectors, the result will be filled with asterisks.

A '9' digit selector causes a data digit to be copied to the result.

A 'Z' digit selector causes a non-zero data digit to be copied to the result.  A zero data digit is copied if and only if digits appear on either side of it.  Otherwise a blank appears.  Similarly text between digit selectors appears only if digits appear on either side of the text.  Text appearing before the first digit selector or after the last will always appear in the result.

Examples

      'G⊂99/99/99⊃'⎕FMT 0 100 100 ⊥8 7 89
08/07/89

      'G⊂ZZ/ZZ/ZZ⊃'⎕FMT 80789 + 0 1
 8/07/89
 8/07/9

      'G⊂Andy ZZ Pauline ZZ⊃' ⎕FMT 2721.499 2699.5
Andy 27 Pauline 21
Andy 27

      ⍴⎕←'K2G⊂DM Z.ZZZ.ZZ9,99⊃' ⎕FMT 1234567.89 1234.56
DM 1.234.567,89
DM     1.234,56
2 15

An error will be reported if:

  •

    Numeric data is matched against an A control phrase.

  •

    Character data is matched against other than an A control phrase.

  •

    The format specification is ill-formed.

  •

    For an F control phrase, d>w⍎2

  •

    For an E control phrase, s>w⍎2

O Format Qualifier

The O format qualifier replaces a specific numeric value with a text string and may be used in conjunction with the E, F, I and G format phrases.

An O-qualifier consists of the letter "O" followed by the optional numeric value which is to be substituted (if omitted, the default is 0) and then the text string within pairs of  symbols such as "<>". For example:

O - qualifier | Description
O<nil> | Replaces the value 0 with the text "nil"
O42<N/A> | Replaces the value 42 with the text "N/A"
O0.001<1/1000> | Replaces the value 0.001 with the text "1/1000"

The replacement text is inserted into the field in place of the numeric value. The text is normally right-aligned in the field, but will be left-aligned if the L qualifier is also specified.

It is permitted to specify more than one O-qualifier within a single phrase.

The O-qualifier is ⎕CT sensitive.

Examples

      'O<NIL>F7.2'⎕FMT 12.3 0 42.5
  12.30
    NIL
  42.50

      'O<NIL>LF7.2'⎕FMT 12.3 0 42.5

12.30
NIL
42.50

      'O<NIL>O42<N/A>I6'⎕FMT 12 0 42 13
    12
   NIL
   N/A
    13

      'O99<replace>F20.2'⎕fmt 99 100 101
             replace
              100.00
              101.00


Screen Dimensions

R←⎕SD

⎕SD is a 2-element integer vector containing the number of rows and columns on the screen, or in the USER window.

Under DOS, ⎕SD always contains (25 80).  For asynchronous terminals under UNIX, the screen size is taken from the terminal database terminfo or termcap.

In window implementations of Dyalog APL, ⎕SD reports the current size (in characters) of the USER window or the current size of the SM object, whichever is appropriate.


Screen Map

⎕SM

⎕SM is a system variable that defines a character-based user interface (as opposed to a graphical user interface).  In versions of Dyalog APL for DOS/386 and in those that support asynchronous terminals, ⎕SM defines a form that is displayed on the USER SCREEN.  The implementation of ⎕SM in "window" environments is compatible with these versions.  In Dyalog APL/X, ⎕SM occupies its own separate window on the display, but is otherwise equivalent.  In versions of Dyalog APL with GUI support, ⎕SM either occupies its own separate window (as in Dyalog APL/X) or, if it exists, uses the window assigned to the SM object. This allows ⎕SM to be used in a GUI application in conjunction with other GUI components.

In general ⎕SM is a nested matrix containing between 3 and 13 columns.  Each row of ⎕SM represents a field; each column a field attribute.

The columns have the following meanings:

.----+------------------------------+-------.
|Col | Description                  |Default|
|----+------------------------------+-------|
|  1 |Field Contents                |  N/A  |
|  2 |Field position - Top Row      |  N/A  |
|  3 |Field position - Left Column  |  N/A  |
|  4 |Window Size - Rows            |   0   |
|  5 |Window Size - Columns         |   0   |
|  6 |Field Type                    |   0   |
|  7 |Behaviour                     |   0   |
|  8 |Video Attributes              |   0   |
|  9 |Active Video Attributes       |  ¯1   |
| 10 |Home Element - Row            |   1   |
| 11 |Home Element - Column         |   1   |
| 12 | Scrolling Group - Vertical   |   0   |
| 13 | Scrolling Group - Horizontal |   0   |
'----+------------------------------+-------'

With the exception of columns 1 and 8, all elements in ⎕SM are integer scalar values.

Elements in column 1 (Field Contents) may be :

  1. A numeric scalar

    2.

  2. A numeric vector

    3.

  3. A 1-column numeric vector

    4.

  4. A character scalar

    5.

  5. A character vector

    6.

  6. A character matrix (rank 2)

    7.

  7. A nested matrix defining a sub-form whose structure and Contents must conform to that defined for ⎕SM as a whole. This definition is recursive. Note however that a sub-form must be a matrix - a vector is not allowed.
    8.

Elements in column 8 (Video Attributes) may be :

  1. An integer scalar that specifies the appearance of the entire field.

    2.

  2. An integer array of the same rank as the field Contents. Each element specifies the appearance of the corresponding element in the field Contents.
    3.

Screen Management (DOS & Async Terminals)

Dyalog APL for DOS/386 and UNIX systems (Async terminals) manages two screens; the SESSION screen and the USER screen.  If the SESSION screen is current, an assignment to ⎕SM causes the display to switch to the USER screen and show the form defined by ⎕SM.

If the USER screen is current, any change in the value of ⎕SM is immediately reflected by a corresponding change in the appearance of the display.  However, an assignment to ⎕SM that leaves its value unchanged has no effect.

Dyalog APL automatically switches to the SESSION screen for default output, if it enters immediate input mode (6-space prompt), or through use of ⎕ or ⍞.  This means that typing

      ⎕SM ← expression

in the APL session will cause the screen to switch first to the USER screen, display the form defined by ⎕SM, and then switch back to the SESSION screen to issue the 6-space prompt.  This normally happens so quickly that all the user sees is a flash on the screen.

To retain the USER screen in view it is necessary to issue a call to ⎕SR or for APL to continue processing

eg.

      ⎕SM ← expression  ⋄  ⎕SR 1

or

      ⎕SM ← expression  ⋄  ⎕DL 5

Screen Management (Window Versions)

In Dyalog APL/X, and optionally in Dyalog APL/W, ⎕SM is displayed in a separate USER WINDOW on the screen. In an end-user application this may be the only Dyalog APL window.  However, during development, there will be a SESSION window, and perhaps EDIT and TRACE windows too.

The USER Window will only accept input during execution of ⎕SR.  It is otherwise "output-only".  Furthermore, during the execution of ⎕SR it is the only active window, and the SESSION, EDIT and TRACE Windows will not respond to user input.

Screen Management (GUI Versions)

In versions of Dyalog APL that provide GUI support, there is a special SM object that defines the position and size of the window to be associated with ⎕SM.  This allows character-mode applications developed for previous versions of Dyalog APL to be migrated to and integrated with GUI environments without the need for a total re-write.

The Effect of Localisation

Like all system variables (with the exception of ⎕TRAP) ⎕SM is subject to "pass-through localisation".  This means that a localised ⎕SM assumes the its value from the calling environment.  The localisation of ⎕SM does not, of itself therefore, affect the appearance of the display.  However, reassignment of a localised ⎕SM causes the new form to overlay rather than replace whatever forms are defined further down the stack.  The localisation of ⎕SM thus provides a simple method of defining pop-up forms, help messages, etc.

The user may edit the form defined by ⎕SM using the system function ⎕SR.  Under the control of ⎕SR the user may change the following elements in ⎕SM which may afterwards be referenced to obtain the new values.


Screen Read

R←{X}⎕SR Y

⎕SR is a system function that allows the user to edit or otherwise interact with the form defined by ⎕SM.

In Dyalog APL for DOS or in versions that support asynchronous terminals, if the current screen is the SESSION screen, ⎕SR immediately switches to the USER SCREEN and displays the form defined by ⎕SM.

In Dyalog APL/X, ⎕SR causes the input cursor to be positioned in the USER window.  During execution of ⎕SR, only the USER Window defined by ⎕SM will accept input and respond to the keyboard or mouse.  The SESSION and any EDIT and TRACE Windows that may appear on the display are dormant.

In versions of Dyalog APL with GUI support, a single SM object may be defined.  This object defines the size and position of the ⎕SM window, and allows ⎕SM to be used in conjunctions with other GUI components.  In these versions, ⎕SR acts as a superset of ⎕DQ (See ⎕DQ) but additionally controls the character-based user interface defined by ⎕SM.

Y is an integer vector that specifies the fields which the user may visit.  In versions with GUI support, Y may additionally contain the names of GUI objects with which the user may also interact.

If specified, X may be an enclosed vector of character vectors defining EXIT_KEYS or a 2-element nested vector defining EXIT_KEYS and the INITIAL_CONTEXT.

The result R is the EXIT_CONTEXT.

Thus the 3 uses of ⎕SR are :

EXIT_CONTEXT ← ⎕SR FIELDS

EXIT_CONTEXT ← (⊂EXIT_KEYS) ⎕SR FIELDS

EXIT_CONTEXT ← (EXIT_KEYS)(INITIAL_CONTEXT) ⎕SR FIELDS

FIELDS

If an element of Y is an integer scalar, it specifies a field as the index of a row in ⎕SM (if ⎕SM is a vector it is regarded as having 1 row).

If an element of Y is an integer vector, it specifies a sub-field.  The first element in Y specifies the top-level field as above.  The next element is used to index a row in the form defined by ⊃⎕SM[Y[1];1] and so forth.

If an element of Y is a character scalar or vector, it specifies the name of a top-level GUI object with which the user may also interact.  Such an object must be a "top-level" object, ie.  the ROOT object (.) or a FORM or pop-up MENU.  This feature is implemented ONLY in versions of Dyalog APL with GUI support.

EXIT_KEYS

Each element of EXIT_KEYS is a 2-character code from the Input Translate Table for the keyboard.  If the user presses one of these keys, ⎕SR will terminate and return a result.

If EXIT_KEYS is not specified, it defaults to :

      'ER' 'EP' 'QT'

which (normally) specifies <Enter>, <Esc> and ^D.

INITIAL_CONTEXT

This is a vector of between 3 and 6 elements with the following meanings and defaults:

.----+------------------------------+-------.
| El | Description                  |Default|
|----+------------------------------+-------|
|  1 |Initial Field                 |  N/A  |
|  2 |Initial Cursor Position - Row |  N/A  |
|  3 |Initial Cursor Position - Col |  N/A  |
|  4 |Initial Keystroke             |  ''   |
|  5 |(ignored)                     |  N/A  |
|  6 |Changed Field Flags           |   0   |
|----+------------------------------+-------|
|                                           |
|       Structure of INITIAL_CONTEXT        |
'-------------------------------------------'

INITIAL_CONTEXT[1] specifies the field in which the cursor is to be placed.  It is an integer scalar or vector, and must be a member of Y.  It must not specify a field which has BUTTON behaviour (64), as the cursor is not allowed to enter such a field.

INITIAL_CONTEXT[2 3] are integer scalars which specify the initial cursor position within the field in terms of row and column numbers.

INITIAL_CONTEXT[4] is either empty, or a 2-element character vector specifying the initial keystroke as a code from the Input Translate Table for the keyboard.

INITIAL_CONTEXT[5] is ignored.  It is included so that the EXIT_CONTEXT result of one call to ⎕SR can be used as the INITIAL_CONTEXT to a subsequent call.

INITIAL_CONTEXT[6] is a Boolean scalar or vector the same length as Y.  It specifies which of the fields in Y has been modified by the user.

EXIT_CONTEXT

The result EXIT_CONTEXT is a 6 or 9-element vector whose first 6 elements have the same structure as the INITIAL_CONTEXT.  Elements 7-9 only apply to those versions of Dyalog APL that provide mouse support.

.----+------------------------------.
| El | Description                  |
|----+------------------------------|
|  1 |Final Field                   |
|  2 |Final Cursor Position - Row   |
|  3 |Final Cursor Position - Col   |
|  4 |Terminating Keystroke         |
|  5 |Event Code                    |
|  6 |Changed Field Flags           |
|----+------------------------------|
|  7 |Pointer Field                 |
|  8 |Pointer Position - Row        |
|  9 |Pointer Position - Col        |
|----+------------------------------|
|                                   |
|  Structure of the Result of ⎕SR   |
'-----------------------------------'

EXIT_CONTEXT[1] contains the field in which the cursor was when ⎕SR terminated due to the user pressing an exit key or due to an event occurring.  It is an integer scalar or vector, and a member of Y.

EXIT_CONTEXT[2 3] are integer scalars which specify the row and column position of the cursor within the field EXIT_CONTEXT[1] when ⎕SR terminated.

EXIT_CONTEXT[4] is a 2-element character vector specifying the last keystroke pressed by the user before ⎕SR terminated.  Unless ⎕SR terminated due to an event, EXIT_CONTEXT[4] will contain one of the exit keys defined by X.  The keystroke is defined in terms of an Input Translate Table code.

EXIT_CONTEXT[5] contains the sum of the event codes that caused ⎕SR to terminate.  For example, if the user pressed a mouse button on a BUTTON field (event code 64) and the current field has MODIFIED behaviour (event code 2) EXIT_CONTEXT[5] will have the value 66.

EXIT_CONTEXT[6] is a Boolean scalar or vector the same length as Y.  It specifies which of the fields in Y has been modified by the user during this ⎕SR, ORed with INITIAL_CONTEXT[6].  Thus if the EXIT_CONTEXT of one call to ⎕SR is fed back as the INITIAL_CONTEXT of the next, EXIT_CONTEXT[6] records the fields changed since the start of the process.

EXIT_CONTEXT (Window Versions)

⎕SR returns a 9-element result ONLY if it is terminated by the user pressing a mouse button.  In this case :

EXIT_CONTEXT[7] contains the field over which the mouse pointer was positioned when the user pressed a button. It is an integer scalar or vector, and a member of Y.

EXIT_CONTEXT[8 9] are integer scalars which specify the row and column position of the mouse pointer within the field EXIT_CONTEXT[7] when ⎕SR terminated.


Arbitrary Input

R←{X}⎕ARBIN Y

This transmits the prompt Y to an output device specified by X prior to reading from an input device specified by X.

Under Windows, the use of ⎕ARBIN to the screen or in conjunction with RS232 ports is not supported.

Y may be a scalar, a simple vector, or a vector of simple scalars or vectors. The items of the simple arrays of Y must each be a character, or a number in the range 0 to 255. Numbers are sent to the output device without translation. Characters undergo the standard ⎕AV to ASCII translation. If Y is an empty vector, no codes are sent to the output device.

X may take several forms:

terminate (input output) | ⎕ARBIN prompt
terminate input | ⎕ARBIN prompt
terminate | ⎕ARBIN prompt
 | ⎕ARBIN prompt

Each of these elements is discussed separately.

<terminate>

This defines how the read should be terminated.

If it is omitted, the read terminates on receipt of a Newline character.

If supplied, it must be a simple numeric scalar or vector.

If it is a numeric scalar, it defines the number of characters to be read.

If it is a numeric vector, it defines a set of terminating characters.

If it is the null vector, the read terminates on Newline.

<input>

This defines the input device.

If this is omitted, input is taken from standard input (usually the keyboard).

If supplied, it must be a simple numeric scalar or a simple text vector.

If it is a numeric scalar, it must correspond to a DOS handle or Unix stream number.

If it is a text vector, it must correspond to a valid device or file name.

You must have permission to read from the chosen device.

<output>

This defines the output device.

If this is omitted, output is sent to standard output (usually the screen).

If supplied, it must be a simple numeric scalar or a simple text vector.

If it is a numeric scalar, it must correspond to a DOS handle or Unix stream number.

If it is a text vector, it must correspond to a valid device or file name.

You must have permission to write to the chosen device.

The result R is a simple numeric vector. Each item of R is the numeric representation of an 8-bit code in the range 0 to 255 received from the input device. The meaning of the code is dependent on the characteristics of the input device. If a set of delimiters was defined by <terminate>, the last code returned will belong to that set.

⎕RTL (Response Time Limit) is an implicit argument of ⎕ARBIN. This allows a time limit to be imposed on input. If the time limit is reached, ⎕ARBIN returns with the codes read up to that point.

Examples:

Write HELLO on the screen, and read a line of input from the keyboard:

      R ← ⎕ARBIN 'HELLO'

Beep three times, send ARE YOU AWAKE? to the screen and wait for a 1 character answer from the keyboard:

      R ← 1 ⎕ARBIN 7 7 7 'ARE YOU AWAKE (Y/N)'

Read a line from MYFILE:

      R ← '' 'MYFILE' ⎕ARBIN ''

Read MYFILE until a SPACE (code 32):

      R ← (,32) 'MYFILE' ⎕ARBIN ''

Read MYFILE until a SPACE (code 32) or a TAB (code 9):

      R ← (32 9) 'MYFILE' ⎕ARBIN ''

Write HELLO on /dev/tty1 (a UNIX terminal screen), then read a line from /dev/tty1 (a UNIX terminal keyboard):

      R ← '' ('/dev/tty1' '/dev/tty1') ⎕ARBIN 'HELLO'

Write TITLE to LPT1 (a DOS printer device), then read from COM1 (a DOS serial port) up to the first NEWLINE character:

      R ← (,13) ('COM1' 'LPT1') ⎕ARBIN 'TITLE'

Read 100 characters from COM1; timeout after 10 secs:

      ⎕RTL←10
      R←100 'COM1' ⎕ARBIN ''
      ⍎(100≠⍴R)/'''Read timed out'''

Read until DELIM from COM1; timeout after 10 secs:

      ⎕RTL←10
      R←(,DELIM) 'COM1' ⎕ARBIN ''
      ⍎(DELIM≠¯1↑R)/'''Read timed out'''


Arbitrary Output

{X}⎕ARBOUT Y

This transmits Y to an output device specified by X.

Under Windows, the use of ⎕ARBOUT to the screen or to RS232 ports is not supported.

Y may be a scalar, a simple vector, or a vector of simple scalars or vectors. The items of the simple arrays of Y must each be a character or a number in the range 0 to 255. Numbers are sent to the output device without translation. Characters undergo the standard ⎕AV to ASCII translation. If Y is an empty vector, no codes are sent to the output device.

X defines the output device. If X is omitted, output is sent to standard output (usually the screen). If X is supplied, it must be a simple numeric scalar or a simple text vector.

If it is a numeric scalar, it must correspond to a DOS handle or UNIX stream number.

If it is a text vector, it must correspond to a valid device or file name.

You must have permission to write to the chosen device.

Examples:

Write ASCII digits '123' to UNIX stream 9:

      9 ⎕ARBOUT 49 50 51

Write ASCII characters 'ABC' to MYFILE:

     'MYFILE' ⎕ARBOUT 'ABC'

Beep 3 times:

     ⎕ARBOUT 7 7 7


Files Available

R←⎕FAVAIL

Returns the Boolean value 1 unless the File System Control Block is unusable, either because it does not exist, or its associated permissions are not correct. In these cases it returns the Boolean value 0.


Append Component

Append Cpt

{R}←X ⎕FAPPEND Y

Access code 8

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. X may be any array. The shy result R is the number of the component to which X is written, and is 1 greater than the previously highest component number in the file, or 1 if the file is new.

Examples:

      (1000?1000) ⎕FAPPEND 1

      ⎕←(2 3⍴⍳6) 'ABCD' (⎕OR'FOO') ⎕FAPPEND 1
12

      ⎕←A B C ⎕FAPPEND¨1
13 14 15


Drop Component(s)

{R}←⎕FDROP Y

Access code 32

Y must be a simple integer vector of length 2 or 3 whose elements are:

[1] | a file tie number
[2] | a number specifying the position and number of components to be dropped. A positive value indicates that components are to be removed from the beginning of the file; a negative value indicates that components are to be removed from the end of the file
[3] | an optional passnumber which if omitted is assumed to be zero

The shy result of a ⎕FDROP is a vector of the numbers of the dropped components. This is analogous to ⎕FAPPEND in that the result is potentially useful for updating some sort of dictionary:

      cnos,←vec ⎕FAPPEND¨tie ⍝ Append index to dictionary

      cnos~←⎕FDROP tie,-⍴vec ⍝ Remove index from dictionary

Note that the result vector, though potentially large, is generated only on request.

Examples

      ⎕FSIZE 1
1 21 5436 4294967295

      ⎕FDROP 1 3 ⋄ ⎕FSIZE 1
4 21 5436 4294967295

      ⎕FDROP 1 ¯2 ⋄ ⎕FSIZE 1
4 19 5436 4294967295


Erase File

{R}←X ⎕FERASE Y

Access code 4

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. X must be a character scalar or vector containing the name of the file associated with the tie number Y. This name must be identical with the name used to tie the file, and the file must be exclusively tied. The file named in X is erased and untied. See User Guide for file naming conventions under UNIX and DOS.

The shy result of ⎕FERASE is the tie number of the erased file.

Examples

      'SALES'⎕FERASE 'SALES' ⎕FTIE 0

      './temp' ⎕FCREATE 1
      'temp' ⎕FERASE 1
FILE NAME ERROR
      'temp'⎕FERASE 1
      ∧


Hold File

{R}←⎕FHOLD Y

Access code 2048

This function holds component file(s) and/or external variable(s).

If applied to component files, then Y is an integer scalar, vector, or one-row matrix of file tie numbers, or a two-row matrix whose first row contains file tie numbers and whose second row contains passnumbers.

If applied to external variables, then Y is a non-simple scalar or vector of character vectors, each of which is the name of an external variable. (NOT the file names associated with those variables).

If applied to component files and external variables, Y is a vector whose elements are either integer scalars representing tie numbers, or character vectors containing names of external variables.

The effect is as follows:

  1. The user's preceding holds (if any) are released.

  2. Execution is suspended until the designated files are free of holds by any other task.

  3. When all the designated files are free, execution proceeds. Until the hold is released, other tasks using ⎕FHOLD on any of the designated files will wait.

If Y is empty, the user's preceding hold (if any) is released, and execution continues.

A hold is released by any of the following:

  1. Another ⎕FHOLD

  2. Untying or retying all the designated files. If some but not all are untied or retied, they become free for another task but the hold persists for those that remain tied.

  3. Termination of APL.

  4. Any untrapped error or interrupt.

  5. A return to immediate execution.

Note that a hold is not released by a request for input through ⎕ or ⍞.

Note also that point 5 above implies that ⎕FHOLD is generally useful only when called from a defined function, as holds set in immediate execution (desk calculator) mode are released immediately.

The shy result of ⎕FHOLD is a vector of tie numbers of the files held.

Examples :

      ⎕FHOLD 1

      ⎕FHOLD ⍬

      ⎕FHOLD ⊂'XTVAR'

      ⎕FHOLD 1 2,[0.5]0 16385

      ⎕FHOLD 1 'XTVAR'


File Library

R←⎕FLIB Y

Y must be a simple character scalar or vector which specifies the name of the directory whose APL component files are to be listed.  If Y is empty, the current working directory is assumed.  The result is a character matrix containing the names of the component files in the directory with one row per file.  The number of columns is given by the longest file name. Each file name is prefixed by Y followed by a directory delimiter character.  The ordering of the rows is not defined.  If there are no APL component files accessible to the user in the directory in question, the result is an empty character matrix with 0 rows and 0 columns.

Examples:

      ⎕FLIB ''
SALESFILE
COSTS

      ⎕FLIB '.'
./SALESFILE
./COSTS

      ⎕FLIB '../budget'
../budget/SALES.95
../budget/COSTS.95


Tied File Names

R←⎕FNAMES

The result is a character matrix containing the names of all tied files, with one file name per row. The number of columns is that required by the longest file name. A file name is returned precisely as it was specified when the file was tied. If no files are tied, the result is a character matrix with 0 rows and 0 columns. The rows of the result are in the order in which the files were tied.

Examples:

      '/usr/pete/SALESFILE' ⎕FSTIE 16

      '../budget/COSTFILE' ⎕FSTIE 2

      'PROFIT' ⎕FCREATE 5

       ⎕FNAMES
/usr/pete/SALESFILE
../budget/COSTFILE
PROFIT

      ⍴⎕FNAMES
3 19
      ⎕FNUMS,⎕FNAMES
16 /usr/pete/SALESFILE
 2 ../budget/COSTFILE
 5 PROFIT


Tied File Numbers

R←⎕FNUMS

The result is an integer vector of the tie numbers of all tied files. If no files are tied, the result is empty. The elements of the result are in the order in which the files were tied.

Examples:

      '/usr/pete/SALESFILE' ⎕FSTIE 16

      '../budget/COSTFILE' ⎕FSTIE 2

      'PROFIT' ⎕FCREATE 5

      ⎕FNUMS
16 2 5

      ⎕FNUMS,⎕FNAMES
16 /usr/pete/SALESFILE
 2 ../budget/COSTFILE
 5 PROFIT

      ⎕FUNTIE ⎕FNUMS
      ⍴⎕FNUMS
0


Read Access Matrix

R←⎕FRDAC Y

Access code 4096

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. The result is the access matrix for the designated file.

Examples:

      ⎕FRDAC 1
28 2105 16385
 0 2073 16385
31   ¯1     0


Read Component Information

Read Cpt Information

R←⎕FRDCI Y

Access code 512

Y must be a simple integer vector of length 2 or 3 containing the file tie number, component number and an optional passnumber. If the passnumber is omitted it is assumed to be zero.

The result is a 3 element numeric vector containing the following information:

  1. the size of the component in bytes (i.e. how much disk space it occupies)

  2. the user number of the user who last updated the component

  3. the time of the last update in 60ths of a second since 1st January 1970

Example:

      ⎕FRDCI 1 13
2200 207 3.702094494E10


Read Component

R←⎕FREAD Y

Access code 1

Y must be a simple 2 or 3 element integer vector containing the file tie number, the component number, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The result is the value of the array stored on the tied file at the given component number.

Example:

      ⍴SALES←⎕FREAD 1 241
3 2 12


Rename File

{R}←X ⎕FRENAME Y

Access code 128

Y must be a simple 1 or 2 element integer vector containing a file tie number and an optional passnumber. If the passnumber is omitted it is assumed to be zero.

X must be a simple character scalar or vector containing the new name of the file. This name must be in accordance with the operating system's conventions, and may be specified with a relative or absolute pathname.

The file being renamed must be tied exclusively.

The shy result of ⎕FRENAME is the tie number of the file.

Examples

      'SALES' ⎕FTIE 1
      'PROFIT' ⎕FTIE 2

      ⎕FNAMES
SALES
PROFIT

      'SALES.85' ⎕FRENAME 1
      '../profits/PROFIT.85' ⎕FRENAME 2
      ⎕FNAMES
SALES.85
../profits/PROFITS.85

Rename←{
    fm to←⍵
    ⎕FUNTIE to ⎕FRENAME fm ⎕FTIE 0
}


Replace Component

Replace Cpt

{R}←X ⎕FREPLACE Y

Access code 16

Y must be a simple 2 or 3 element integer vector containing the file tie number, the component number, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The component number specified must lie within the file's component number limits.

X is any array (including, for example, the ⎕OR of a namespace), and overwrites the value of the specified component. The component information (see ⎕FRDCI) is also updated.

The shy result of ⎕FREPLACE is the file index (component number of replaced record).

Example

      SALES←⎕FREAD 1 241

      (SALES×1.1) ⎕FREPLACE 1 241

Define a function to replace (index, value) pairs in a component file JMS.DCF:

Frep←{
    tie←⍺ ⎕FTIE 0
    _←{⍵ ⎕FREPLACE tie ⍺}/¨⍵
    ⎕FUNTIE tie
}

      'jms'Frep(0 'abc')(29 'xxx')(7 'yyy')


Resize File

{R}←{X}⎕FRESIZE Y

Access code 1024

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber.  If the passnumber is omitted it is assumed to be zero.

X is an integer that specifies the maximum permitted size of the file in bytes.

An attempt to update a component file that would cause it to exceed its maximum size will fail with a FILE FULL error (21).

A side effect of ⎕FRESIZE is to cause the file to be compacted.  Any interrupt entered at the keyboard during the compaction is ignored.

The shy result of ⎕FRESIZE is the tie number of the file.

Example

      'test'⎕FCREATE 1  ⋄ ⎕FSIZE 1
1 1 120 1.844674407E19
      (10 1000⍴1.1)⎕FAPPEND 1 ⋄ ⎕FSIZE 1
1 2 80288 1.844674407E19

      100000 ⎕FRESIZE 1 ⍝ Limit size to 100000 bytes

      (10 1000⍴1.1)⎕FAPPEND 1 ⋄ ⎕FSIZE 1
FILE FULL
      (10 1000⍴1.1)⎕FAPPEND 1 ⋄ ⎕FSIZE 1
     ∧

       ⎕FRESIZE 1      ⍝ Force file compaction.


File Size

R←⎕FSIZE Y

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero. The result is a 4 element numeric vector containing the following:

Element | Description
1 | The number of first component
2 | 1 + the number of the last component (i.e. the result of the next ⎕FAPPEND)
3 | The current size of the file in bytes.
4 | The file size limit in bytes.

Example:

      ⎕FSIZE 1
1 21 65271 4294967295


Set Access Matrix

{R}←X ⎕FSTAC Y

Access code 8192

Y must be a simple integer scalar or 1 or 2 element vector containing the file tie number followed by an optional passnumber. If the passnumber is omitted it is assumed to be zero.

X must be a valid access matrix, i.e. a 3 column integer matrix with any number of rows.

See "File Access Control" in User Guide for further details.

The shy result of ⎕FSTAC is the tie number of the file.

Examples

      SALES ⎕FCREATE 1
      (3 3⍴28 2105 16385 0 2073 16385 31 ¯1 0) ⎕FSTAC 1
      ((⎕FRDAC 1)⍪21 2105 16385) ⎕FSTAC 1

      (1 3⍴0 ¯1 0)⎕FSTAC 2


Share Tie File

{R}←X ⎕FSTIE Y

Y must be 0 or a simple 1 or 2 element integer vector containing an available file tie number to be associated with the file for further file operations, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The tie number must not already be associated with a tied file.

X must be a simple character scalar or vector which specifies the name of the file to be tied. The file must be named in accordance with the operating system's conventions, and may be specified with a relative or absolute pathname.

The file must exist and be accessible by the user. If it is already tied by another task, it must not be tied exclusively.

The shy result of ⎕FSTIE is the tie number of the file.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create, share tie or exclusive tie operation, allocates the first (closest to zero) available tie number and returns it as an explicit result. This allows you to simplify code. For example:

from:

      tie←1+⌈/0,⎕FNUMS  ⍝ With next available number,
      file ⎕FSTIE tie   ⍝ ... share tie file.

to:

      tie←file ⎕FSTIE 0 ⍝ Tie with first available number.

Example

      'SALES' ⎕FSTIE 1

      '../budget/COSTS' ⎕FSTIE 2


Tie File

{R}←X ⎕FTIE Y

Access code 2

Y must be 0 or a simple 1 or 2 element integer vector containing an available file tie number to be associated with the file for further file operations, and an optional passnumber. If the passnumber is omitted it is assumed to be zero. The tie number must not already be associated with a share tied or exclusively tied file.

X must be a simple character scalar or vector which specifies the name of the file to be exclusively tied. The file must be named in accordance with the operating system's conventions, and may be a relative or absolute pathname.

The file must exist and be accessible by the user. It may not already be tied by another user.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create, share tie or exclusive tie operation, allocates the first (closest to zero) available tie number, and returns it as an explicit result,. This allows you to simplify code. For example:

from:

      tie←1+⌈/0,⎕FNUMS ⍝ With next available number,
      file ⎕FTIE tie   ⍝ ... tie file.

to:

      tie←file ⎕FTIE 0 ⍝ Tie with first available number.

The shy result of ⎕FTIE is the tie number of the file.

Examples

      'SALES' ⎕FTIE 1

      '../budget/COSTS' ⎕FTIE  2

      '../budget/expenses' ⎕FTIE 0
3


Untie File(s)

{R}←⎕FUNTIE Y

Y must be a simple integer scalar or vector (including Zilde).  Files whose tie numbers occur in Y are untied.  Other elements of Y have no effect.

If Y is empty, no files are untied, but all internal file buffers are written to disk.  Under UNIX this is achieved with fsync; under DOS with the Commit File function (Int 21h Function 68h); on Win32 systems it is achieved with FlushFileBuffers().  This special facility allows the programmer to add extra security (at the expense of performance) for application data files.

The shy result of ⎕FUNTIE is a vector of tie numbers of the files actually untied.

Example

      ⎕FUNTIE ⎕FNUMS ⍝ Unties all tied files

      ⎕FUNTIE ⍬      ⍝ Flushes all buffers to disk


External Variable

⎕XT

Dyadic ⎕XT means

Set External Variable

      'FILE'⎕XT'VAR'

Monadic ⎕XT means

Query External Variable

      ⎕xt'VAR'
FILE.DXV

      VAR←5 5⍴1.234 5.6787
      ⎕ex'VAR'
      'FILE'⎕XT'VAR'
      VAR
1.2 5.7 1.2 5.7 1.2
5.7 1.2 5.7 1.2 5.7
1.2 5.7 1.2 5.7 1.2
5.7 1.2 5.7 1.2 5.7
1.2 5.7 1.2 5.7 1.2

Language Elements


Set External Variable

External Variable Set

X ⎕XT Y

Y must be a simple character scalar or vector which is taken to be a variable name.  X must be a simple character scalar or vector which is taken to be a file reference.  The name given by Y is identified as an EXTERNAL VARIABLE associated with an EXTERNAL ARRAY whose value may be stored in file identified by X.

If Y is the name of a function, defined operator or label in the active workspace, DOMAIN ERROR is reported.

Example:

      'EXT/ARRAY' ⎕XT'V'

If the file reference does not exist, the external variable has no value until a value is assigned:

      V
VALUE ERROR
      V
      ∧

A value assigned to an external variable is stored in file space, not within the workspace:

      ⎕WA
2261186

      V←⍳100000

      ⎕WA
2261186

There are no specific restrictions placed on the use of external variables.  They must conform to the normal requirements when used as arguments of functions or as operands of operators.  The essential difference between a variable and an external variable is that an external variable requires only temporary workspace for an operation to accommodate (usually) a part of its value.

Examples:

      +/V
15

      V[3]←⊂'ABC'

      V
1 2  ABC  4 5

      ⍴¨V
     3

Assignment allows the structure or the value of an external variable to be changed without fully defining the external array in the workspace.

Examples:

      V,←⊂2 4⍴⍳8

      ⍴V
6

      V[6]
1 2 3 4
5 6 7 8

      V[1 2 4 5 6]×←10

      V
10 20  ABC  40 50  10 20 30 40
                   50 60 70 80

An external array is (usually) preserved in file space when the name of the external variable is disassociated from the file.  It may be re-associated with any valid variable name.

Example:

      ⎕EX'V'

      'EXT/ARRAY'⎕XT'F'

      F
10 20  ABC  40 50  10 20 30 40
                   50 60 70 80

In Unix versions, if X is an empty vector, the external array is associated with a temporary file which is erased when the array is disassociated.

Example:

      ''⎕XT'TEMP'

      TEMP←⍳10

      +/TEMP×TEMP
385

      ⎕EX'TEMP'

An external array may only be erased using the native file function: ⎕NERASE.

In a multi-user environment (UNIX or a DOS LAN) a new file associated with an external array is created with access permission for owner read/write.  An existing file is opened for exclusive use (by the owner) if the permissions remain at this level.  If the access permissions allow any other users to read and write to the file, the file is opened for shared use. In Unix versions, access permissions may be modified using the appropriate Operating System command, or in Windows using the supplied function XVAR from the UTIL workspace.


Native File Create

{R}←X ⎕NCREATE Y

This function creates a new file. Under Windows the file is opened in compatibility mode. The name of the new file is specified by the left argument X which must be a simple character vector or scalar containing a valid pathname for the file. Y is 0 or a negative integer value that specifies an (unused) tie number by which the file may subsequently be referred.

The shy result of ⎕NCREATE is the tie number of the new file.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create or tie operation, allocates, and returns as an explicit result, the first (closest to zero) available tie number. This allows you to simplify code. For example:

from:

      tie←¯1+⌊/0,⎕NNUMS   ⍝ With next available number,
      file ⎕NCREATE tie   ⍝ ... create file.

to:

      tie←file ⎕NCREATE 0 ⍝ Create with first available no.


Native File Erase

{R}←X ⎕NERASE Y

Erases (deletes) a native file. Y is a negative integer tie number associate with a tied native file. X is a simple character vector or scalar containing the name of the same file and must be identical to the name used when it was opened by ⎕NCREATE or ⎕NTIE.

The shy result of ⎕NERASE is the tie number that the erased file had.


Native File Lock

{R}←X ⎕NLOCK Y

This function assists the controlled update of shared native files by locking a range of bytes.

Locking enables controlled update of native files by co-operating users. A process requesting a lock on a region of a file will be blocked until that region becomes available. A write-lock is exclusive, whereas a read-lock is shared. In other words, any byte in a file may be in one of only three states:

  • Unlocked

  • Write-locked by exactly one process.

  • Read-locked by any number of processes.

Y must be a simple integer scalar or vector containing 1, 2 or 3 items namely:

  1. Tie number

  2. Offset (from 0) of first byte of region. Defaults to 0

  3. Number of bytes to lock. Defaults to maximum possible file size

X must be a simple integer scalar or vector containing 1 or 2 items, namely:

  1. Type: 0: Unlock, 1:Read lock, 2:Write lock.

  2. Timeout: Number of seconds to wait for lock until TIMEOUT error. Defaults to indefinite wait.

The shy result R is Y. To unlock the file, this value should subsequently be supplied in the right argument to 0⎕NLOCK.

Examples:

    2 ⎕NLOCK ¯1        ⍝ write-lock whole file
    0 ⎕NLOCK ¯1        ⍝ unlock whole file.
    1 ⎕NLOCK ¯1        ⍝ read (share) lock whole file.
    2 ⎕NLOCK¨⎕NNUMS    ⍝ write-lock all files.
    0 ⎕NLOCK¨⎕NNUMS    ⍝ unlock all files.

    1 ⎕NLOCK ¯1 12 1   ⍝ read-lock byte 12.
    1 ⎕NLOCK ¯1 0 10   ⍝ read-lock first 10 bytes.
    2 ⎕NLOCK ¯1 20     ⍝ write-lock from byte 20 onwards.
    2 ⎕NLOCK ¯1 10 2   ⍝ write-lock 2 bytes from byte 10
    0 ⎕NLOCK ¯1 12 1   ⍝ remove lock from byte 12.

To lock the region immediately beyond the end of the file prior extending it:

    region←2 ⎕NLOCK ¯1, ⎕NSIZE ¯1  ⍝ write-lock from EOF.
    ... ⎕NAPPEND ¯1                ⍝ append bytes to file
    ... ⎕NAPPEND ¯1                ⍝ append bytes to file
    0 ⎕NLOCK ¯1,region             ⍝ release lock.

The left argument may have a second optional item that specifies a timeout value. If a lock has not been acquired within this number of seconds, the acquisition is abandoned and a TIMEOUT error reported.

    2 10 ⎕nlock ¯1      ⍝ wait up to 10 seconds for lock.

Notes:

There is no per-byte cost associated with region locking. It takes the same time to lock/unlock a region, irrespective of that region’s size.

Different file servers implement locks in slightly different ways. For example on some systems, locks are advisory. This means that a write lock on a region precludes other locks intersecting that region, but doesn't stop reads or writes across the region. On the other hand, mandatory locks block both other locks and read/write operations. ⎕NLOCK will just pass the server's functionality along to the APL programmer without trying to standardise it across different systems.

All locks on a file will be removed by ⎕NUNTIE.

Blocked locking requests can be freed by a strong interrupt. Iunder Windows, this operation is performed from the Dyalog APL pop-up menu in the system tray.

Errors

An attempt to unlock a region that contains bytes that have not been locked results in a DOMAIN error.

A LIMIT ERROR results if the operating system lock daemon has insufficient resources to honour the locking request.

Some systems support only write locks. In this case an attempt to set a read lock will generate a DOMAIN ERROR, and it may be appropriate for the APL programmer to trap the error and apply a write lock.

No attempt will be made to detect deadlock. Some servers do this and if such a condition is detected, a DEADLOCK error (1008) will be reported.


Native File Names

R←⎕NNAMES

Reports the names of all currently open native files. R is a character matrix. Each row contains the name of a tied native file padded if necessary with blanks. The names are identical to those that were used to open the files with ⎕NCREATE or ⎕NTIE.


Native File Numbers

R←⎕NNUMS

Reports the tie numbers associated with all currently open native files. R is an integer vector of negative tie numbers.


Native File Rename

{R}←X ⎕NRENAME Y

⎕NRENAME is used to rename a native file.

Y is a negative integer tie number associated with a tied native file. X is a simple character vector or scalar containing a valid (and unused) file name.

The shy result of ⎕NRENAME is the tie number of the renamed file.


Native File Resize

{R}←X ⎕NRESIZE Y

This function changes the size of a native file.

Y is a negative integer tie number associated with a tied native file.

X is a single integer value that specifies the new size of the file in bytes. If X is smaller than the current file size, the file is truncated. If X is larger than the current file size, the file is extended and the value of additional bytes is undefined.

The shy result of ⎕NRESIZE is the tie number of the resized file.


Native File Size

R←⎕NSIZE Y

Reports the size of a native file. Y is a negative integer tie number associated with a tied native file. The result R is the size of the file in bytes.


Native File Tie

{R}←X ⎕NTIE Y

⎕NTIE opens a native file.

X is a simple character vector or scalar containing a valid pathname for an existing native file.

Y is a 1- or 2-element vector. Y[1] is a negative integer value that specifies an (unused) tie number by which the file may subsequently be referred. Y[2] is optional and specifies the mode in which the file is to be opened. This is an integer value calculated as the sum of 2 codes. The first code refers to the type of access needed from users who have already tied the native file. The second code refers to the type of access you wish to grant to users who subsequently try to open the file while you have it open.

Needed from existing users |  | Granted to subsequent users
0 | read access | 0 | compatibility mode
1 | write access | 16 | no access (exclusive)
2 | read and write access | 32 | read access
 |  | 48 | write access
 |  | 64 | read and write access

On Unix systems, the first code (16|mode) is passed to the open(2) call as the access parameter. See include file fcntl.h for details.

Automatic Tie Number Allocation

A tie number of 0 as argument to a create or tie operation, allocates, and returns as an explicit result, the first (closest to zero) available tie number. This allows you to simplify code. For example:

from:

      tie←¯1+⌊/0,⎕NNUMS    ⍝ With next available number,
      file ⎕NTIE tie       ⍝ ... tie file.

to:

      tie←file ⎕NTIE 0     ⍝ Tie with first available no.

Example

ntie←{                  ⍝ tie file and return tie no.
    ⍺←2+64              ⍝ default all access.
    ⍵ ⎕ntie 0 ⍺         ⍝ return new tie no.
}


Native File Untie

{R}←⎕NUNTIE Y

This closes one or more native files. Y is a scalar or vector of negative integer tie numbers. The files associated with elements of Y are closed.

The shy result of ⎕NUNTIE is a vector of tie numbers of the files actually untied.


Dequeue

{R}←⎕DQ Y

⎕DQ awaits and processes events. Y specifies the GUI object(s) for which events are to be processed. Objects are identified by their names, as character scalars/vectors, or by namespace references. These may be objects of type Root, Form, Locator, Filebox, MsgBox, PropertySheet, TCPSocket, Timer, Clipboard and pop-up Menu. Sub-objects (children) of those named in Y are also included. However, any objects which exist, but are not named in Y, are effectively disabled (do not respond to the user).

If Y is '.', all objects currently owned and subsequently created by the current thread are included in the ⎕DQ. Note that because the Root object is owned by thread 0, events on Root are reported only to thread 0.

If Y is empty it specifies the object associated with the current namespace and is only valid if the current space is one of the objects listed above.

Otherwise, Y contains the name(s) of or reference(s) to the objects for which events are to be processed. Effectively, this is the list of objects with which the user may interact. A DOMAIN ERROR is reported if an element of Y refers to anything other than an existing "top-level" object.

Associated with every object is a set of events. For every event there is defined an "action" which specifies how that event is to be processed by ⎕DQ. The "action" may be a number with the value 0, 1 or ¯1, or a character vector containing the name of a "callback function", or a character vector containing the name of a callback function coupled with an arbitrary array. Actions can be defined in a number of ways, but the following examples will illustrate the different cases.

      OBJ ⎕WS 'Event' 'Select' 0

      OBJ ⎕WS 'Event' 'Select' 1

      OBJ ⎕WS 'Event' 'Select' 'FOO'

      OBJ ⎕WS 'Event' 'Select' 'FOO' 10

      OBJ ⎕WS 'Event' 'Select' 'FOO&'

These are treated as follows:

Action = 0 (the default)

⎕DQ performs "standard" processing appropriate to the object and type of event.  For example, the standard processing for a KeyPress event in an Edit object is to action the keypress, i.e. to echo the character on the screen.

Action = ¯1

This disables the event.  The "standard" processing appropriate to the object and type of event is not performed, or in some cases is reversed.  For example, if the "action code" for a KeyPress event (22) is set to ¯1,  ⎕DQ simply ignores all keystrokes for the object in question.

Action = 1

⎕DQ terminates and returns information pertaining to the event (the event message in R as a nested vector whose first two elements are the name of the object (that generated the event) and the event code.  R may contain additional elements depending upon the type of event that occurred.

Action = fn {larg}

fn is a character vector containing the name of a callback function.  This function is automatically invoked by ⎕DQ whenever the event occurs, and prior to the standard processing for the event.  The callback is supplied the event message (see above) as its right argument, and, if specified, the array larg as its left argument.  If the callback function fails to return a result, or returns the scalar value 1,  ⎕DQ then performs the standard processing appropriate to the object and type of event.  If the callback function returns a scalar 0, the standard processing is not performed or in some cases is reversed.

If the callback function returns its event message with some of the parameters changed, these changes are incorporated into the standard processing.  An example would be the processing of a keystroke message where the callback function substitutes upper case for lower case characters. The exact nature of this processing is described in the reference section on each event type.

Action = ⍎expr

If Action is set to a character vector whose first element is the execute symbol (⍎) the remaining string will be executed automatically whenever the event occurs.  The default processing for the event is performed first and may not be changed or inhibited in any way.

Action = fn& {larg}

fn is a character vector containing the name of a callback function.  The function is executed in a new thread. The default processing for the event is performed first and may not be changed or inhibited in any way.

⎕DQ terminates in one of four instances.  Note that its result is shy.

Firstly, ⎕DQ terminates when an event occurs whose "action code" is 1.  In this case, its result is a nested vector containing the event message associated with the event.  The structure of an event message varies according to the event type (see Object Reference).  However, an event message has at least two elements of which the first is a character vector containing the name of the object, and the second is a numeric code specifying the event type.

⎕DQ also terminates if all of the objects named in Y have been deleted.  In this case, the result is an empty character vector.  Objects are deleted either using ⎕EX, or on exit from a defined function or operator if the names are localised in the header, or on closing a form using the system menu.

Thirdly, ⎕DQ terminates if the object named in its right argument is a special modal object, such as a MsgBox, FileBox or Locator, and the user has finished interacting with the object (e.g. by pressing an "OK" button).  The return value of  ⎕DQ in this case depends on the action code of the event.

Finally, ⎕DQ terminates with a VALUE ERROR if it attempts to execute a callback function that is undefined.


Enqueue

{R}←{X}⎕NQ Y

This system function generates an event or invokes a method.

While APL is executing, events occur "naturally" as a result of user action or of communication with other applications. These events are added to the event queue as and when they occur, and are subsequently removed and processed one by one by ⎕DQ. ⎕NQ provides an "artificial" means to generate an event and is analogous to ⎕SIGNAL.

If the left argument X is omitted or is 0, ⎕NQ adds the event specified by Y to the bottom of the event queue. The event will subsequently be processed by ⎕DQ when it reaches the top of the queue.

If X is 1, the event is actioned immediately by ⎕NQ itself and is processed in exactly the same way as it would be processed by ⎕DQ. For example, if the event has a callback function attached, ⎕NQ will invoke it directly. See ⎕DQ for further details.

Note that it is not possible for one thread to use 1 ⎕NQ to send an event to another thread.

If X is 2 and the name supplied is the name of an event, ⎕NQ performs the default processing for the event immediately, but does not invoke a callback function if there is one attached.

If X is 2 and the name supplied is the name of a (Dyalog APL) method, ⎕NQ invokes the method. Its (shy) result is the result produced by the method.

If X is 3, ⎕NQ invokes a method in an OLE Control. The (shy) result of ⎕NQ is the result produced by the method.

If X is 4, ⎕NQ signals an event from an ActiveXControl object to its host application. The (shy) result of ⎕NQ is the result returned by the host application and depends upon the syntax of the event. This case is only applicable to ActiveXControl objects.

Y is a nested vector containing an event message. The first two elements of Y are :

Y[1] | Object name | a character vector
Y[2] | Event Type | a numeric scalar or character vector which specifies an event or method.

Y[1] must contain the name of an existing object. If not, ⎕NQ terminates with a VALUE ERROR. If Y[2] specifies a standard event type, subsequent elements must conform to the structure defined for that event type. If not, ⎕NQ terminates with a SYNTAX ERROR. If Y[2] specifies a non-standard event type, Y[3] onwards (if present) may contain arbitrary information. Although any event type not listed herein may be used, numbers in the range 0-1000 are reserved for future extensions.

If ⎕NQ is used monadically, or with a left argument of 0, its (shy) result is always an empty character vector. If a left argument of 1 is specified, ⎕NQ returns Y unchanged or a modified Y if the callback function returns its modified argument as a result. If the left argument is 2, ⎕NQ returns either the value 1 or a value that is appropriate.

Examples

      ⍝ Send a keystroke ("A") to an Edit Field
      ⎕NQ 'TEST.ED' 'KeyPress' 'A'

      ⍝ Iconify all top-level Forms
      {⎕NQ ⍵ 'StateChange' 1}¨'Form'⎕WN'.'

      ⍝ Set the focus to a particular field
      ⎕NQ 'TEST.ED3' 40

      ⍝ Throw a new page on a printer
      1 ⎕NQ 'PR1' 'NewPage'

      ⍝ Terminate ⎕DQ under program control

      'TEST'⎕WC 'Form' ... ('Event' 1001 1)
      ...
      ⎕DQ 'TEST'
      ...
      ⎕NQ 'TEST' 1001  ⍝ From a callback

      ⍝ Call GetItemState method for a TreeView 'F.TV'
      +2 ⎕NQ'F.TV' 'GetItemState' 6
96
      +2 ⎕NQ'.' 'GetEnvironment' 'Dyalog'
c:\Z\2\dyalog82


Session Namespace

⎕SE

Purpose | The Session object ⎕SE is a special system object that represents the session window and acts as a parent for the session menus, tool bar(s) and status bar.
Children | Form, MenuBar, Menu, MsgBox, Font, FileBox, Printer, Bitmap, Icon, Cursor, Clipboard, Locator, Timer, Metafile, ToolBar, StatusBar, TipField, TabBar, ImageList, PropertySheet, OLEClient, TCPSocket, CoolBar, ToolControl, BrowseBox
Properties | Caption, ChildList, Coord, CurObj, CurPos, CurSpace, Data, Event, EventList, File, FontObj, Handle, HintObj, Input, Log, MethodList, Popup, Posn, PropList, Size, State, TextSize, TipObj, Type, XRange, YRange
Events | Close, Create, FontOK, FontCancel, WorkspaceLoaded
Methods | ChooseFont, FileRead, FileWrite

Description

There is one (and only one) object of type Session and it is called ⎕SE. You may use ⎕WG, ⎕WS and ⎕WN to perform operations on ⎕SE, but you cannot expunge it with ⎕EX nor can you recreate it using ⎕WC. You may however expunge all its children. This will result in a bare session with no menu bar, tool bar or status bar.

⎕SE is loaded from a session file when APL starts. The name of the session file is specified by the session_file parameter (See User Guide). If no session file is defined, ⎕SE will have no children and the session will be devoid of menu bar, tool bar and status bar components.

You may use all of the standard GUI system functions to build or configure the components of the Session to your own requirements. You may also control the Session by changing certain of its properties.

Read-Only Properties

The following properties of ⎕SE are read-only and may not be set using ⎕WS:

Caption | A character vector containing 'Dyalog APL/W'
ChildList | A vector of character vectors containing the names of the GUI objects that can be created as top-level objects in ⎕SE.
CurObj | A character vector containing the name of the current object. This is the name under or immediately to the left of the input cursor.
CurPos | A 2-element integer vector containing the position of the input cursor (row and column number) in the session log. This is ⎕IO dependent. If ⎕IO is 1, and the cursor is positioned on the character at the beginning of the first (top) line in the log, CurPos is (1 1). If ⎕IO is 0, its value would be (0 0).
CurSpace | A character vector containing the name of the current namespace (i.e. the namespace in which code is executing).
EventList | A vector of character vectors containing the names of the events associated with ⎕SE.
Handle | Reports the window handle of the Session window (for use when invoking Winodws API functions to perform operations on or with the Session window).
Input | A vector of character vectors containing the most recent set of input statements (lines that you have executed) contained in the input history buffer.
Log | A vector of character vectors containing the most recent set of lines (input statements and results) that are recorded in the session log. The first element contains the top line in the log.
MethodList | A vector of character vectors containing the names of the methods that are supported by ⎕SE.
PropList | A vector of character vectors containing the names of the properties associated with ⎕SE.
TextSize | Reports the bounding rectangle for a text string. For a full description, see TextSize in Windows Interface.
Type | A character vector containing 'Session'

Read/Write Properties

The following properties of ⎕SE may be changed using ⎕WS:

Coord | Specifies the co-ordinate system for the session window. For a full description, see the section on Coord in the Windows Interface manual.
Data | May be used to associate arbitrary data with the session object ⎕SE. For further details, see the section on Data in the Windows Interface manual
Event | You may use this property to attach an expression or callback function to the FileRead and FileWrite events, or indeed to user-defined events. However, as these events may only be generated under program control, there is little need to do so.
File | The full pathname of the session file that is associated with the current session. This is the file name used when you save or load the session by generating a FileRead or FileWrite event.
FontObj | Specifies the APL font. In general, the FontObj property may specify a font in terms of its face name, size, and so forth or it may specify the name of a Font object. For applications, the latter method is recommended as it will result in better management of font resources. However, in the case of the Session object, it is recommended that the former method be used.
HintObj | Specifies the name of the object in which hints are displayed. Unless you specify HintObj individually for session components, this object will be used to display the hints associated with all of the menu items, buttons, and so forth in the session. The object named by this property is also used to display the message 'Ready...' when APL is waiting for input. For further details, see the section on HintObj in the Windows Interface manual.
Posn | A 2-element numeric vector containing the position of the top-left corner of the session window relative to the top-left corner of the screen. This is reported and set in units specified by the Coord property.
Popup | Specifies the name of the pop-up menu associated with the Session window.
Size | A 2-element numeric vector containing the height and width of the session window expressed in units specified by the Coord property.
State | An integer that specifies the window state (0=normal, 1=minimised, 2=maximised). You may wish to use this property to minimise and later restore the session under program control. If you save your session with State set to 2, your APL session will start off maximised.
YRange | See the section on YRange in the Windows Interface manual.
XRange | See the section on XRange in the Windows Interface manual.
TipObj | Specifies the name of the object in which tips are displayed. Unless you specify TipObj individually for session components, this object will be used to display the tips associated with all of the menu items, buttons, and so forth in the session. For further details, see the section on TipObj in the Windows Interface manual.


Create Windows Object

Create GUI Object

{R}←{X} ⎕WC Y

This system function creates a GUI object. Y is either a vector which specifies properties that determine the new object's appearance and behaviour, or the ⎕OR of a GUI object that exists or previously existed. X is a character vector which specifies the name of the new object, and its position in the object hierarchy.

If X is omitted, ⎕WC attaches a GUI component to the current namespace, retaining any functions, variables and other namespaces that it may contain. Monadic ⎕WC is discussed in detail at the end of this section.

If Y is a nested vector each element specifies a property. The Type property (which specifies the class of the object) must be specified. Most other properties take default values and need not be explicitly stated. Properties (including Type) may be declared either positionally or with a keyword followed by a value. Note that Type must always be the first property specified. Properties are specified positionally by placing their values in Y in the order prescribed for an object of that type.

If Y is a result of ⎕OR, the new object is a complete copy of the one from which the ⎕OR was made, including any child objects, namespaces, functions and variables that it contained at that time.

The shy result R is the full name (starting #. or ⎕SE.) of the namespace X.

An object's name is specified by giving its full pathname in the object hierarchy. At the top of the hierarchy is the Root object whose name is ".". Below "." there may be one or more "top-level" objects. The names of these objects follow the standard rules for other APL objects as described in Chapter 1.

Names for sub-objects follow the same rules except that the character "." is used as a delimiter to indicate parent/child relationships.

The following are examples of valid and illegal names :

    Legal             Illegal
    FORM1              FORM 1
    form_23            form#1
    Form1.Cp1          1_Form
    F1.c2.b34          Form+1

If X refers to the name of an APL variable, label, function, or operator, a DOMAIN ERROR is reported. If X refers to the name of an existing GUI object or namespace, the existing one is replaced by the new one. The effect is the same as if it were deleted first.

If Y refers to a non-existent property, or to a property that is not defined for the type of object X, a DOMAIN ERROR is reported. A DOMAIN ERROR is also reported if a value is given that is inconsistent with the corresponding property. This can occur for example, if Y specifies values positionally and in the wrong order.

A "top-level" object created by ⎕WC whose name is localised in a function/operator header, is deleted on exit from the function/operator. All objects, including sub-objects, can be deleted using ⎕EX.

GUI objects are named relative to the current namespace, so the following examples are equivalent:

      'F1.B1' ⎕WC 'Button'

is equivalent to :

      )CS F1
#.F1
      'B1' ⎕WC 'Button'
      )CS
#

is equivalent to :

      'B1' F1.⎕WC 'Button'

Examples:

⍝ Create a default Form called F1

      'F1' ⎕WC 'Form'

⍝ Create Form with specified properties (by position)
⍝   Caption = "My Application"  (Title)
⍝   Posn    = 10 30  (10% down, 30% across)
⍝   Size    = 80 60  (80% high, 60% wide)

      'F1' ⎕WC 'Form' 'My Application' (10 30)(80 60)

⍝ Create Form with specified properties (by keyword)
⍝   Caption = "My Application"  (Title)
⍝   Posn    = 10 30  (10% down, 30% across)
⍝   Size    = 80 60  (80% high, 60% wide)

      PROPS←⊂'Type' 'Form'
      PROPS,←⊂'Caption' 'My Application'
      PROPS,←⊂'Posn' 10 30
      PROPS,←⊂'Size' 80 60
      'F1' ⎕WC PROPS

⍝ Create a default Button (a pushbutton) in Form F1

      'F1.BTN' ⎕WC 'Button'

⍝ Create a pushbutton labelled "Ôk"
⍝ 10% down and 10% across from the start of the FORM
⍝ with callback function FOO associated with EVENT 30
⍝ (this event occurs when user presses the button)

      'F1.BTN'⎕WC'Button' '&Ok' (10 10)
                        ('Event' 30 'FOO')

⍝ Make F2, a copy (clone) of Form F1

      'F2' ⎕WC ⎕OR 'F1'

Monadic Use

Monadic ⎕WC is used to attach a GUI component to an existing object. The existing object must be a pure namespace or a GUI object. The operation may be performed by changing space to the object or by running ⎕WC inside the object using the dot syntax. For example, the following statements are equivalent.

      )CS F
#.F
      ⎕WC 'Form'  ⍝ Attach a Form to this namespace
      )CS

#

      F.⎕WC'Form' ⍝ Attach a Form to namespace F

Monadic ⎕WC is often used in conjunction with the KeepOnClose property.


Get Object Property

Get GUI Object Properties

R←X ⎕WG Y

This system function returns property values for a GUI object.

X is a namespace reference (ref) or a character vector containing the name of the object. Y is a character vector or a vector of character vectors containing the name(s) of the properties whose values are required. The result R contains the current values of the specified properties. If Y specifies a single property name, a single property value is returned. If Y specifies more than one property, R is a vector with one element per name in Y.

If X refers to a non-existent GUI name, a VALUE ERROR is reported. If Y refers to a non-existent property or to a property that is not defined for the type of object X a DOMAIN ERROR is reported.

GUI objects are named relative to the current namespace. A null value of X (referring to the namespace in which the function is being evaluated) may be omitted. The following examples are equivalent:

      'F1.B1' ⎕WG 'Caption'
      'B1' F1.⎕WG 'Caption'
      '' F1.B1.⎕WG 'Caption'
      F1.B1.⎕WG 'Caption'

Examples:

      'F1' ⎕WC 'Form' 'TEST'

      'F1' ⎕WG 'Caption'
TEST

      'F1' ⎕WG 'MaxButton'
1

      'F1' ⎕WG 'Size'
50 50

      DISPLAY 'F1' ⎕WG 'Caption' 'MaxButton' 'Size'
.→-----------------.
| .→---.   .→----. |
| |TEST| 1 |50 50| |
| '----'   '~----' |
'∊-----------------'


Windows Object Names

Query GUI Object Names

R←{X}⎕WN Y

This system function reports the names of the objects whose parent is Y. This is a character scalar or vector containing the name of an existing GUI object.

The optional left argument X is a character vector which specifies the Type of object to be reported.

The result R is a vector of character vectors containing the names of the direct children of Y which are of Type X, or all of them if X is not specified. The names of objects further down the tree are not returned, but can be obtained by recursive use of ⎕WN.

If Y refers to a non-existent GUI name, a VALUE ERROR is reported.

Note that ⎕WN reports only those child objects visible from the current thread.

GUI objects are named relative to the current namespace. The following examples are equivalent:

      ⎕WN 'F1.B1'
      F1.⎕WN 'B1'
      F1.B1.⎕WN ''

Examples:

      ⎕WN'.'
 FORM1  MENU1

      ⎕WN'FORM1'
 CANCEL  GROUP1  MENUBAR  OK

      'Button'⎕WN'FORM1'
 CANCEL  OK


Set Object Property

Set GUI Object Properties

X ⎕WS Y

This system function resets property values for a GUI object.

X is a namespace reference or a character vector containing the name of the object. Y defines the property or properties to be changed and the new value or values. If a single property is to be changed, Y is a vector whose first element Y[1] is a character vector containing the property name. If Y is of length 2, Y[2] contains the corresponding property value. However, if the property value is itself a numeric or nested vector, its elements may be may be specified in Y[2 3 4 ...] instead of as a single nested element in Y[2]. If Y specifies more than one property, they may be declared either positionally or with a keyword followed by a value. Properties are specified positionally by placing their values in Y in the order prescribed for an object of that type. Note that the first property in Y must always be specified with a keyword because the Type property (which is expected first) may not be changed using ⎕WS.

If X refers to a non-existent GUI name, a VALUE ERROR is reported. If Y refers to a non-existent property, or to a property that is not defined for the type of object X, or to a property whose value may not be changed by ⎕WS, a DOMAIN ERROR is reported.

GUI objects are named relative to the current namespace. A null value of X (referring to the namespace in which the function is being evaluated) may be omitted. The following examples are equivalent:

      'F1.B1' ⎕WS 'Caption' '&Ok'
      'B1' F1.⎕WS 'Caption' '&Ok'
      '' F1.B1.⎕WS 'Caption' '&Ok'
      F1.B1.⎕WS 'Caption' '&Ok'

Examples:

      'F1' ⎕WC 'Form'  ⍝ A default Form

      'F1' ⎕WS 'Active' 0

      'F1' ⎕WS 'Caption' 'My Application'

      'F1' ⎕WS 'Posn' 0 0

      'F1' ⎕WS ('Active' 1)('Event' 'Configure' 'FOO')

      'F1' ⎕WS 'Junk' 10
DOMAIN ERROR

      'F1' ⎕WS 'MaxButton' 0
DOMAIN ERROR


Diagnostic Message

R←⎕DM

Returns the last reported APL error as a three-element vector, giving error message, line in error and position of caret.

Example:

      2÷0
DOMAIN ERROR
      2÷0
     ∧

      ⎕DM
 DOMAIN ERROR        2÷0       ∧


Event Messages

R←⎕EM Y

Y must be a simple non-negative integer scalar or vector of event codes.  If Y is a scalar, R is a simple character vector containing the associated event message.  If Y is a vector, R is a vector of character vectors containing the corresponding event messages.

If Y refers to an undefined error code "n", the event message returned is "ERROR NUMBER n".

Example:

      ⎕EM 11
DOMAIN ERROR


Event Number

R←⎕EN

This simple integer scalar reports the identification number for the most recent event which occurred, caused by an APL action or by an interrupt or by the ⎕SIGNAL system function. Its value in a clear workspace is 0.


Exception

R←⎕EXCEPTION

This is a system object that identifies the most recent Exception thrown by a Microsoft .Net object.

⎕EXCEPTION derives from the Microsoft .Net class System.Exception. Among its properties are the following, all of which are strings:

Source | The name of the .Net namespace in which the exception was generated
StackTrace | The calling stack
Message | The error message
      ⎕USING←'System'
      DT←DateTime.New 100000 0 0
EXCEPTION
      DT←DateTime.New 100000 0 0

      ⎕EN
90

      ⎕EXCEPTION.Message
Specified argument was out of the range of valid values.

Parameter name: Year, Month, and Day parameters describe
an unrepresentable DateTime.

      ⎕EXCEPTION.Source
mscorlib

      ⎕EXCEPTION.StackTrace
   at System.DateTime.DateToTicks(Int32 year, Int32 month,
                                  Int32 day)

   at System.DateTime..ctor(Int32 year, Int32 month,
                            Int32 day)


Signal Event

{X}⎕SIGNAL Y

Y must be a single positive integer scalar or an empty vector. X is optional. If present, X must be a simple character scalar or vector. If Y is an empty vector nothing is signalled.

Y is taken to be an event number in the range of event numbers shown in a figure. X is an optional text message. If omitted, the standard event message shown for the corresponding event number in figure is assumed. If there is no standard message, a message of the form ERROR NUMBER n is composed, where n is the event number in Y.

The effect of the system function is to interrupt execution. The state indicator is cut back to exit from the function or operator containing the line that invoked ⎕SIGNAL or the Execute (⍎) expression that invoked ⎕SIGNAL, and an error interrupt is then caused.

An error interrupt may be trapped if the system variable ⎕TRAP is set to intercept the event. Otherwise, the standard system action is taken (which may involve cutting back the state indicator further if there are locked functions or operators in the state indicator). The standard event message is replaced by the text given in X, if present.

Example:

      ⎕VR'DIVIDE'
     ∇ R←A DIVIDE B;⎕TRAP
[1]    ⎕TRAP←11 'E' '→ERR'
[2]    R←A÷B ⋄ →0
[3]   ERR:'DIVISION ERROR' ⎕SIGNAL 11
     ∇

      2 4 6 DIVIDE 0
DIVISION ERROR
      2 4 6 DIVIDE 0
     ∧

If you are using the Microsoft .Net Framework, you may use ⎕SIGNAL to throw an exception by specifying a value of 90 in Y. In this case, if you specify the optional left argument X , it must be a reference to a .Net object that is or derives from the Microsoft .Net class System.Exception. The following example illustrates a constructor function CTOR that expects to be called with a value for ⎕IO (0 or 1)

     ∇ CTOR IO;EX
[1]    :If IO∊0 1
[2]        ⎕IO←IO
[3]    :Else
[4]        EX←ArgumentException.New'IO must be 0 or 1'
[5]        EX ⎕SIGNAL 90
[6]    :EndIf
     ∇


Trap System Function

Trap Events

⎕TRAP

This is a non-simple vector. An item of ⎕TRAP specifies an action to be taken when one of a set of events occurs. An item of ⎕TRAP is a 2 or 3 element vector whose items are simple scalars or vectors in the following order:

1 | an integer vector whose value is one or more event codes selected from the list in figure.
2 | a character scalar whose value is an action code selected from the letters C E N or S.
3 | if element 2 is the letter C or E, this item is a character vector forming a valid APL expression or series of expressions separated by ⋄. Otherwise, this element is omitted.

An EVENT may be an APL execution error, an interrupt by the user or the system, a control interrupt caused by the ⎕STOP system function, or an event generated by the ⎕SIGNAL system function.

When an event occurs, the system searches for a trap definition for that event. The most local ⎕TRAP value is searched first, followed by successive shadowed values of ⎕TRAP, and finally the global ⎕TRAP value. Separate actions defined in a single ⎕TRAP value are searched from left to right. If a trap definition for the event is found, the defined action is taken. Otherwise, the normal system action is followed.

The ACTION code identifies the nature of the action to be taken when an associated event occurs. Permitted codes are interpreted as follows:

C | Cutback | The state indicator is 'cut back' to the environment in which the ⎕TRAP is locally defined (or to immediate execution level). The APL expression in element 3 of the same ⎕TRAP item is then executed.
E | Execute | The APL expression in element 3 of the same ⎕TRAP item is executed in the environment in which the event occurred.
N | Next | The event is excluded from the current ⎕TRAP definition. The search will continue through further localised definitions of ⎕TRAP.
S | Stop | Stops the search and causes the normal APL action to be taken in the environment in which the event occurred.

⎕TRAP Event Codes
Code | Event
0 | Any event in range 1-999
1 | WS FULL
2 | SYNTAX ERROR
3 | INDEX ERROR
4 | RANK ERROR
5 | LENGTH ERROR
6 | VALUE ERROR
7 | FORMAT ERROR
10 | LIMIT ERROR
11 | DOMAIN ERROR
12 | HOLD ERROR
16 | NONCE ERROR
18 | FILE TIE ERROR
19 | FILE ACCESS ERROR
20 | FILE INDEX ERROR
21 | FILE FULL
22 | FILE NAME ERROR
23 | FILE DAMAGED
24 | FILE TIED
25 | FILE TIED REMOTELY
26 | FILE SYSTEM ERROR
28 | FILE SYSTEM NOT AVAILABLE
30 | FILE SYSTEM TIES USED UP
31 | FILE TIE QUOTA USED UP
32 | FILE NAME QUOTA USED UP
34 | FILE SYSTEM NO SPACE
35 | FILE ACCESS ERROR - CONVERTING FILE
38 | FILE COMPONENT DAMAGED
52 | FIELD CONTENTS RANK ERROR
53 | FIELD CONTENTS TOO MANY COLUMNS
54 | FIELD POSITION ERROR
55 | FIELD SIZE ERROR
56 | FIELD CONTENTS/TYPE MISMATCH
57 | FIELD TYPE/BEHAVIOUR UNRECOGNISED
58 | FIELD ATTRIBUTES RANK ERROR
59 | FIELD ATTRIBUTES LENGTH ERROR
60 | FULL⍎SCREEN ERROR
61 | KEY CODE UNRECOGNISED
62 | KEY CODE RANK ERROR
63 | KEY CODE TYPE ERROR
70 | FORMAT FILE ACCESS ERROR
71 | FORMAT FILE ERROR
72 | NO PIPES
76 | PROCESSOR TABLE FULL
84 | TRAP ERROR
90 | EXCEPTION
92 | TRANSLATION ERROR
200 – 499 | Reserved for distributed auxiliary processors
500 – 999 | User-defined events
1000 | Any event in range 1001-1006
1001 | Stop vector
1002 | Weak interrupt
1003 | INTERRUPT
1005 | EOF INTERRUPT
1006 | TIMEOUT
1007 | RESIZE (Dyalog APL/X, Dyalog APL/W)

Examples:

      ⎕TRAP←⊂(3 4 5) 'E' 'ERROR' ⋄ ⍴⎕TRAP
1

      ⎕TRAP
  3 4 5 E ERROR

Items may be specified as scalars. If there is only a single trap definition, it need not be enclosed. However, the value of ⎕TRAP will be rigorously correct:

      ⎕TRAP←11 'E' '→LAB'

      ⎕TRAP
  11 E →ERR

      ⍴⎕TRAP
1

The value of ⎕TRAP in a clear workspace is an empty vector whose prototype is

0⍴(⍬ '' ''). A convenient way of cancelling a ⎕TRAP definition is:

      ⎕TRAP←0⍴⎕TRAP

Event codes 0 and 1000 allow all events in the respective ranges 1-999 and 1000-1006 to be trapped. Specific event codes may be excluded by the N action (which must precede the general event action):

      ⎕TRAP←(1 'N')(0 'E' '→GENERR')

The 'stop' action is a useful mechanism for cancelling trap definitions during development of applications.

The 'cut-back' action is useful for returning control to a known point in the application system when errors occur. The following example shows a function that selects and executes an option with a general trap to return control to the function when an untrapped event occurs:

     ∇ SELECT;OPT;⎕TRAP
[1]   ⍝ Option selection and execution
[2]   ⍝ A general cut-back trap
[3]    ⎕TRAP←(0 1000)'C' '→ERR'
[4]   INP:⍞←'OPTION : ' ⋄ OPT←(OPT≠' ')/OPT←9↓⍞
[5]    →EX⍴⍨(⊂OPT)∊Options ⋄ 'INVALID OPTION' ⋄ →INP
[6]   EX:⍎OPT ⋄ →INP
[7]   ERR:ERROR∆ACTION ⋄ →INP
[8]   END:
     ∇

User-defined events may be signalled through the ∩SIGNAL system function. A user-defined event (in the range 500-999) may be trapped explicitly, or implicitly by the event code 0.

Example:

      ⎕TRAP←500 'E' '''USER EVENT 500 - TRAPPED'''

      ⎕SIGNAL 500
USER EVENT 500 - TRAPPED


Thread Child Numbers

R←⎕TCNUMS Y

Y must be a simple array of integers representing thread numbers.

The result R is a simple integer vector of the child threads of each thread of Y.

Examples:

      ⎕TCNUMS 0
2 3

      ⎕TCNUMS 2 3
4 5 6 7 8 9


Get Tokens

{R}←{X} ⎕TGET Y

Y must be a simple integer scalar or vector that specifies one or more tokens, each with a specific non-zero token type, that are to be retrieved from the pool.

X is an optional time-out value in seconds.

Shy result R is a scalar or vector containing the values of the tokens of type Y that have been retrieved from the token pool.

Note that types of the tokens in the pool may be positive or negative, and the elements of Y may also be positive or negative.

A request (⎕TGET) for a positive token will be satisfied by the presence of a token in the pool with the same positive or negative type. If the pool token has a positive type, it will be removed from the pool. If the pool token has a negative type, it will remain in the pool. Negatively typed tokens will therefore satisfy an infinite number of requests for their positive equivalents. Note that a request for a positive token will remove one if it is present, before resorting to its negative equivalent

A request for a negative token type will only be satisfied by the presence of a negative token type in the pool, and that token will be removed.

If, when a thread calls ⎕TGET, the token pool satisfies all of the tokens specified by Y, the function returns immediately with a (shy) result that contains the values associated with the pool tokens. Otherwise, the function will block (wait) until all of the requested tokens are present or until a timeout (as specified by X) occurs.

For example, if the pool contains only tokens of type 2:

    ⎕TGET 2 4        ⍝ blocks waiting for a 4-token ...

The ⎕TGET operation is atomic in the sense that no tokens are taken from the pool until all of the requested types are present. While this last example is waiting for a 4-token, other threads could take any of the remaining 2-tokens.

Note also, that repeated items in the right argument are distinct. The following will block until there are at least 3 × 2-tokens in the pool:

    ⎕TGET 3/2       ⍝ wait for 3 × 2-tokens ...

The pool is administered on a first-in-first-out basis. This is significant only if tokens of the same type are given distinct values. For example:

    ⎕TGET ⎕TPOOL             ⍝ empty pool.

    'ABCDE'⎕TPUT¨2 2 3 2 3  ⍝ pool some tokens.

    +⎕TGET 2 3
AC

    +⎕TGET 2 3
BE

Timeout is signalled by the return of a scalar 0 token. By default, the value of a token is the same as its type. This means that, unless you have explicitly set the value of a token to 0, a ⎕TGET result of 0 unambiguously identifies a timeout.

Beware - the following statement will wait forever and can only be terminated by a strong interrupt.

    ⎕TGET 0       ⍝ wait forever ...

Note too that if a thread waiting to ⎕TGET tokens is ⎕TKILLed, the thread disappears without removing any tokens from the pool. Conversely, if a thread that has removed tokens from the pools is ⎕TKILLed, the tokens are not returned to the pool.


Thread Identity

Current Thread Identity

R←⎕TID

R is a simple integer scalar whose value is the number of the current thread.

Examples:

      ⎕TID     ⍝ Base thread number
0

      ⍎&'⎕TID' ⍝ Thread number of async ⍎.
1


Kill Thread

{R}←{X}⎕TKILL Y

Y must be a simple array of integers representing thread numbers to be terminated. X is a Boolean single, defaulting to 1, which indicates that all descendant threads should also be terminated.

The shy result R is a vector of the numbers of all threads that have been terminated.

The base thread 0 is always excluded from the cull.

Examples:

      ⎕TKILL 0            ⍝ Kill background threads.

      ⎕TKILL ⎕TID         ⍝ Kill self and descendants.

      0 ⎕TKILL ⎕TID       ⍝ Kill self only.

      ⎕TKILL ⎕TCNUMS ⎕TID ⍝ Kill descendants.


Thread Name

Current Thread Name

⎕TNAME

The system variable ⎕TNAME reports and sets the name of the current APL thread. This name is used to identify the thread in the Tracer.

The default value of ⎕TNAME is an empty character vector.

You may set ⎕TNAME to any valid character vector, but it is recommended that control characters (such as ⎕AV[⎕IO] ) be avoided.

Example:

      ⎕TNAME←'Dylan'
      ⎕TNAME
Dylan


Thread Numbers

R←⎕TNUMS

⎕TNUMS reports the numbers of all current threads.

R is a simple integer vector of the base thread and all its living descendants.

Example:

      ⎕TNUMS
0 2 4 5 6 3 7 8 9


Token Pool

R←⎕TPOOL

R is a simple scalar or vector containing the token types for each of the tokens that are currently in the token pool.

The following (⎕ml=0) function returns a 2-column snapshot of the contents of the pool. It does this by removing and replacing all of the tokens, restoring the state of the pool exactly as before. Coding it as a single expression guarantees that snap is atomic and cannot disturb running threads.

      snap←{(⎕TGET ⍵){(⍉↑⍵ ⍺){⍺}⍺ ⎕TPUT¨⍵}⍵}

      snap ⎕TPOOL
1       hello world
2                 2
3                 2
2  three-type token
2                 2


Put Tokens

{R}←{X} ⎕TPUT Y

Y must be a simple integer scalar or vector of non-zero token types.

X is an optional array of values to be stored in each of the tokens specified by Y.

Shy result R is a vector of thread numbers (if any) unblocked by the ⎕TPUT.

Examples

    ⎕TPUT 2 3 2     ⍝ put a 2-token, a 3-token and another
                      2-token into the pool.

    88 ⎕TPUT 2      ⍝ put another 2-token into the pool
                      this token has the value 88.

    'Hello'⎕TPUT ¯4 ⍝ put a ¯4-token into the pool with
                      the value 'Hello'.

If X is omitted, the value associated with each of the tokens added to the pool is the same as its type.

Note that you cannot put a 0-token into the pool; 0-s are removed from Y.


Token Requests

R←⎕TREQ Y

Y is a simple scalar or vector of thread numbers.

R is a vector containing the concatenated token requests for all the threads specified in Y. This is effectively the result of catenating all of the right arguments together for all threads in Y that are currently executing ⎕TGET.

Example

    ⎕TREQ ⎕TNUMS    ⍝ tokens required by all threads.


Thread Synchronise

Wait for Threads to Terminate

R←⎕TSYNC Y

Y must be a simple array of thread numbers.

If Y is a simple scalar, R is an array, the result (if any) of the thread.

If Y is a simple non-scalar, R has the same shape as Y, and result is an array of enclosed thread results.

The interpreter detects a potential deadlock if a number of threads wait for each other in a cyclic dependency. In this case, the thread that attempts to cause the deadlock issues error number 1008: DEADLOCK.

Examples

      dup←{⍵ ⍵}        ⍝ Duplicate

      ⎕←dup&88         ⍝ Show thread number
11
88 88

      ⎕TSYNC dup&88    ⍝ Wait for result
88 88

      ⎕TSYNC,dup&88
 88 88

      ⎕TSYNC dup&1 2 3
 1 2 3  1 2 3

      ⎕TSYNC dup&¨1 2 3
 1 1  2 2  3 3

      ⎕TSYNC ⎕TID      ⍝ Wait for self
DEADLOCK
      ⎕TSYNC ⎕TID
      ∧

      ⎕EN
1008


Shared Variable Control

⎕SVC

Dyadic ⎕SVC means

Set Shared Variable Access Control

      0 0 1 1 ⎕SVC 'DATA'
0 0 1 1

Monadic ⎕SVC means

Query Shared Variable Access Control

      ⎕SVC 'DATA'
0 0 1 1

Language Elements


Set Access Control

R←X ⎕SVC Y

This system function sets access control on one or more shared variables.

Y is a character scalar, vector, or matrix containing names of shared variables. Each name may optionally be paired with its surrogate. If so, the surrogate must be separated from the name by at least one space.

X may be a 4-element Boolean vector which specifies the access control to be applied to all of the shared variables named in Y. Alternatively, X may be a 4-column Boolean matrix whose rows specify the access control for the corresponding name in Y. X may also be a scalar or a 1-element vector. If so, it treated as if it were a 4-element vector with the same value in each element.

Each shared variable has a current access control vector which is a 4-element Boolean vector. A 1 in each of the four positions has the following impact :

[1] | You cannot set a new value for the shared variable until after an intervening use or set by your partner.
[2] | Your partner cannot set a new value for the shared variable until after an intervening use or set by you.
[3] | You cannot use the value of the shared variable until after an intervening set by your partner.
[4] | Your partner cannot use the value of the shared variable until after an intervening set by you.

The effect of ⎕SVC is to reset the access control vectors for each of the shared variables named in Y by OR-ing the values most recently specified by your partner with the values in X. This means that you cannot reset elements of the control vector which your partner has set to 1.

Note that the initial value of your partner's access control vector is normally 0 0 0 0. However, if it is a non-APL client application that has established a hot DDE link, its access control vector is defined to be 1 0 0 1. This inhibits either partner from setting the value of the shared variable twice, without an intervening use (or set) by the other. This prevents loss of data which is deemed to be desirable from the nature of the link. (An application that requests a hot link is assumed to require every value of the shared variable, and not to miss any). Note that APL's way of inhibiting another application from setting the value twice (without an intervening use) is to delay the acknowledgement of the DDE message containing the second value until the variable has been used by the APL workspace. An application that waits for an acknowledgement will therefore hang until this happens. An application that does not wait will carry on obliviously.

The result R is a Boolean vector or matrix, corresponding to the structure of X, which contains the new access control settings. If Y refers to a name which is not a shared variable, or if the surrogate name is mis-spelt, the corresponding value in R is 4⍴0.

Examples:

      1 0 0 1 ⎕SVC 'X'
1 0 0 1

      1 ⎕SVC 'X EXTNAME'
1 1 1 1

      (2 4⍴1 0 0 1 0 1 1 0) ⎕SVC ↑'ONE' 'TWO'
1 1 1 1
0 1 1 0


Shared Variable Offer Symbol

Shared Variable Offer

⎕SVO

Dyadic ⎕SVO means

Shared Variable Offer

      DATA←⍳9
      'DDE:' ⎕SVO 'DATA'
1

Monadic ⎕SVO means

Query Degree of Coupling

      ⎕SVO 'DATA'
1

Language Elements


Shared Variable Offer

R←X ⎕SVO Y

This system function offers to share one or more variables with another APL workspace or with another application. Shared variables are implemented using Dynamic Data Exchange (DDE) and may be used to communicate with any other application that supports this protocol.

Y is a character scalar, vector or matrix. If it is a vector it contains a name and optionally an external name or surrogate. The first name is the name used internally in the current workspace. The external name is the name used to make the connection with the partner and, if specified, must be separated from the internal name by one or more blanks. If the partner is another application, the external name corresponds to the DDE item specified by that application. If the external name is omitted, the internal name is used instead. The internal name must be a valid APL name and be either undefined or be the name of a variable. There are no such restrictions on the content of the external name.

Instead of an external name, Y may contain the special symbol '⍎' separated from the (internal) name by a blank. This is used to implement a mechanism for sending DDE_EXECUTE messages, and is described at the end of this section.

If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

The left argument X is a character vector or matrix. If it is a vector, it contains a string that defines the protocol, the application to which the shared variable is to be connected, and the topic of the conversation. These three components are separated by the characters ':' and '|' respectively. The protocol is currently always 'DDE', but future implementations of Dyalog APL may support additional communications protocols if applicable. If Y specifies more than one name, X may be a matrix with one row per row in Y.

If the shared variable offer is a general one (server), X, or the corresponding row of X, should contain 'DDE:'.

The result R is a numeric scalar or vector with one element for each name in Y and indicates the "degree of coupling". A value of 2 indicates that the variable is fully coupled (via a warm or hot DDE link) with a shared variable in another APL workspace, or with a DDE item in another application. A value of 1 indicates that there is no connection, or that the second application rejected a warm link. In this case, a transfer of data may have taken place (via a cold link) but the connection is no longer open. Effectively, APL treats an application that insists on a cold link as if it immediately retracts the sharing after setting or using the value, whichever is appropriate.

Examples:

      'DDE:' ⎕SVO 'X'
1

      'DDE:' ⎕SVO 'X SALES_92'
1

      'DDE:' ⎕SVO ↑'X SALES_92' 'COSTS_92'
1 1

      'DDE:DYALOG|SERV_WS' ⎕SVO 'X'
2

      'DDE:EXCEL|SHEET1' ⎕SVO 'DATA R1C1:R10C12'
2

A special syntax is used to provide a mechanism for sending DDE EXECUTE messages to another application. This case is identified by specifying the '⍎' symbol in place of the external name. The subsequent assignment of a character vector to a variable shared with the external name of '⍎' causes the value of the variable to be transmitted in the form of a DDE_EXECUTE message. The value of the variable is then reset to 1 or 0 corresponding to a positive or negative acknowledgement from the partner. In most (if not all) applications, commands transmitted in DDE_EXECUTE messages must be enclosed in square brackets []. For details, see the relevant documentation for the external application.

Examples :

      'DDE:EXCEL|SYSTEM' ⎕SVO 'X ⍎'
2

      X←'[OPEN("c:\mydir\mysheet.xls")]'
      X
1

      X←'[SELECT("R1C1:R5C10")]'
      X
1


Query Shared Variable Offers

Query SV Offers

R←⎕SVQ Y

This system function is implemented for compatibility with other versions of APL but currently performs no useful function. Its purpose is to obtain a list of outstanding shared variable offers made to you, to which you have not yet responded.

Using DDE as the communication protocol, it is not possible to implement ⎕SVQ effectively.


Retract Shared Variables

Retract SVs

R←⎕SVR Y

This system function terminates communication via one or more shared variables, or aborts shared variable offers that have not yet been accepted

Y is a character scalar, vector or matrix. If it is a vector it contains a shared variable name and optionally its external name or surrogate separated from it by one of more blanks. If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

The result R is a 4-element vector whose length corresponds to the number of names specified by Y, indicating the level of sharing of each variable after retraction.

See ⎕SVS for further information on the possible states of a shared variable.


Shared Variable State

R←⎕SVS Y

This system function returns the current state of one or more shared variables.

Y is a character scalar, vector or matrix. If it is a vector it contains a shared variable name and optionally its external name or surrogate separated from it by one of more blanks. If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

If Y specifies a single name, the result R is a 4-element vector indicating its current state. If Y specifies more than one name, R is a matrix whose rows indicate the current state of the variable specified by the corresponding row in Y.

There are four possible shared variable states :

0 0 1 1 | means that you and your partner are both aware of the current value, and neither has since reset it. This is also the initial value of the state when the link is first established.
1 0 1 0 | means that you have reset the shared variable and your partner has not yet used it. This state can only occur if both partners are APL workspaces.
0 1 0 1
 means that your partner has reset the shared variable but that you have not yet used it.
0 0 0 0 | the name is not that of a shared variable.

Examples:

      ⎕SVS 'X'
0 1 0 1

      ⎕SVS ↑'X SALES' 'Y' 'JUNK'
0 0 1 1
1 0 1 0
0 0 0 0


Line Count

R←⎕LC

This is a simple vector of line numbers drawn from the state indicator. The most recently activated line is shown first. If a value corresponds to a defined function in the state indicator, it represents the current line number where the function is either suspended or pendent.

The value of ⎕LC changes immediately upon completion of the most recently activated line, or upon completion of execution within ¨ or ⎕.

If a ⎕STOP control is set, ⎕LC identifies the line on which the stop control is effected. In the case where a stop control is set on line 0 of a defined function, the first entry in ⎕LC is 0 when the control is effected.

The value of ⎕LC in a clear workspace is the null vector.

Examples:

      )SI
TASK1[5]*
⍎
BEGIN[3]

      ⎕LC
5 3

      →⎕LC

      ⎕LC

      ⍴⎕LC
0


Execution Monitor

⎕MONITOR

Dyadic ⎕MONITOR means

Set Monitor

      ∇ FOO
[1]    0⍴⌹10 10⍴⍳11
     ∇

      0 ⎕MONITOR'FOO'

Monadic ⎕MONITOR means

Query Monitor

      FOO

      ⎕MONITOR'FOO'
0 1 60 60 0

Language Elements


Set Monitor

Monitor Set

{R}←X ⎕MONITOR Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator.  X must be a simple non-negative integer scalar or vector.  R is a simple integer vector of non-negative elements.

X identifies the numbers of lines in the function or operator named by Y on which a monitor is to be placed. Numbers outside the range of line numbers in the function or operator (other than 0) are ignored.  The number 0 indicates that a monitor is to be placed on the function or operator as a whole.  The value of X is independent of ⎕IO.

R is a vector of numbers on which a monitor has been placed in ascending order.  The result is suppressed unless it is explicitly used or assigned.

The effect of ⎕MONITOR is to accumulate timing statistics for the lines for which the monitor has been set.  See Monitor Query for details.

Examples:

      +(0,⍳10) ⎕MONITOR 'FOO'
0 1 2 3 4 5

Existing monitors are cancelled before new ones are set:

      +1 ⎕MONITOR 'FOO'
1

All monitors may be cancelled by supplying an empty vector:

      ⍬ ⎕MONITOR 'FOO'

Monitors may be set on a locked function or operator, but no information will be reported.  Monitors are saved with the workspace.


Cross Reference

Cross References

R←⎕REFS Y

Y must be a simple character scalar or vector, identifying the name of a function or operator, or the object representation form of a function or operator (see ⎕OR).  R is a simple character matrix, with one name per row, of identified names in the function or operator in Y excluding distinguished names of system constants, variables or functions.

Example:

      ⎕VR'OPTIONS'
     ∇ OPTIONS;OPTS;INP
[1]  ⍝ REQUESTS AND EXECUTES AN OPTION
[2]   OPTS ←'INPUT' 'REPORT' 'END'
[3]  IN:INP←ASK'OPTION:'
[4]   →EX⍴⍨(⊂INP)∊OPTS
[5]   'INVALID OPTION. SELECT FROM',OPTS ⋄ →IN
[6]  EX:→EX+OPTS⍳⊂INP
[7]   INPUT ⋄ →IN
[8]   REPORT ⋄ →IN
[9]  END:
     ∇

    ⎕REFS'OPTIONS'
ASK
END
EX
IN
INP
INPUT
OPTIONS
OPTS
REPORT

If Y is locked or is an External Function, R contains its name only.  For example:

      ⎕LOCK 'OPTIONS' ⋄ ⎕REFS 'OPTIONS'
OPTIONS

If Y is the name of a primitive, external or derived function, R is an empty matrix with shape 0 0.


Shadow Names

⎕SHADOW Y

Y must be a simple character scalar, vector or matrix identifying one or more APL names.  For a vector Y, names are separated by one or more blanks.  For a matrix Y, each row is taken to be a single name.

Each valid name in Y is shadowed in the most recently invoked defined function or operator, as though it were included in the list of local names in the function or operator header.  The class of the name becomes 0 (undefined).  The name ceases to be shadowed when execution of the shadowing function or operator is completed.  Shadow has no effect when the state indicator is empty.

If a name is ill-formed, or if it is the name of a system constant or system function, DOMAIN ERROR is reported.

If the name of a top-level GUI object is shadowed, it is made inactive.

Example:

      ⎕VR'RUN'
     ∇ NAME RUN FN
[1]   ⍝ RUNS FUNCTION NAMED <NAME> DEFINED
[2]   ⍝ FROM REPRESENTATION FORM <FN>
[3]    ⎕SHADOW NAME
[4]    ⍎⎕FX FN
     ∇

      0 ⎕STOP 'RUN'

      'FOO' RUN 'R←FOO' 'R←10'
10

RUN[0]

      )SINL
RUN[0]*       FOO     FN      NAME

      →⎕LC

      FOO
VALUE ERROR
      FOO
      ∧


State Indicator

R←⎕SI

R is a nested vector of vectors giving the names of the functions or operators in the execution stack.

Example:

      )SI
PLUS[2]*
MATDIV[4]
FOO[1]*ß
⍎

      ⎕SI
 PLUS  MATDIV  FOO

      (⍴⎕LC) = ⍴⎕SI
1

If execution stops in a callback function, ⎕DQ will appear on the stack, and may occur more than once

      )SI
ERRFN[7]
* ⎕DQ
CALC
⎕DQ
MAIN

To edit the function on the top of the stack:

      ⎕ED ⊃⎕SI

The name of the function which called this one:

      ⊃1↓⎕SI

To check if the function ∆N is pendent:

     ((⊂∆N)∊1↓⎕SI)/'Warning : ',∆N,' is pendent'

See also ⎕XSI.


Extended State Indicator

R←⎕XSI

R is a nested vector of character vectors giving the full path names of the functions or operators in the execution stack. Note that if a function has changed space, its original (home) space is reported, rather than its current one.

Example

In the following, function foo in namespace x has called goo in namespace y. Function goo has then changed space (⎕CS) to namespace z where it has been suspended:

      )si
[z] y.goo[2]*
x.foo[1]

⎕XSI reports the full path name of each function:

      ⎕xsi
 #.y.goo  #.x.foo

This can be used for example, to edit all functions in the stack, irrespective of the current namespace by typing: ⎕ed ⎕xsi

See also ⎕SI.


Namespace Indicator

R←⎕NSI

R is a nested vector of character vectors containing the names of the spaces from which functions in the state indicator were called (⍴⎕NSI←→⍴⎕SI).

Note that ⎕NSI contains the names of spaces from which functions were called not those in which they are currently running.

Example:

      )OBJECTS
XX      YY

      ⎕VR 'YY.FOO'
     ∇ FOO
[1]    ⎕SE.GOO
     ∇
      ⎕VR'⎕SE.GOO'
     ∇ GOO
[1]    ⎕SI,[1.5]⎕NSI
     ∇

      )CS XX
#.XX
      #.YY.FOO
 GOO  #.YY
 FOO  #.XX


SI Stack

R←⎕STACK

R is a two-column matrix, with one row per entry in the State Indicator.

Column 1 | ⎕OR form of user defined functions or operators on the State Indicator. Null for entries that are not user defined functions or operators.
Column 2 | Indication of the type of the item on the stack as shown below.

Item | Meaning
space | user defined function or operator
⍎ | execute level
⎕ | evaluated input
* | desk calculator level
other | primitive operator

Example:

      )SI
PLUS[2]*
.
MATDIV[4]
FOO[1]*
⍎

      ⎕STACK
         *
∇PLUS
         .
∇MATDIV
         *
∇FOO
         ⍎
         *

      ⍴⎕STACK
8 2

      (⍴⎕LC) = ⍴⎕STACK
0

Pendent defined functions and operators may be edited in Dyalog APL with no resulting SI damage.  However, only the visible definition is changed; the pendent version on the stack is retained until its execution is complete.  When the function or operator is displayed, only the visible version is seen.  Hence ⎕STACK is a tool which allows the user to display the form of the actual function or operator being executed.

Example:

To display the version of MATDIV currently pendent on the stack:

      ⊃⎕STACK[4;1]
     ∇ R←A MATDIV B
[1]   ⍝ Divide matrix A by matrix B
[2]    C←A⌹B
[3]   ⍝ Check accuracy
[4]    D←⌊0.5+A PLUS.TIMES B
     ∇


Object State

State of Object

R←⎕STATE Y

Y must be a simple character scalar or vector which is taken to be the name of an APL object.  The result returned is a nested vector of 4 elements as described below.  ⎕STATE supplies information about shadowed or localised objects that is otherwise unobtainable.

1⊃R | Boolean vector, element set to 1 if and only if this level shadows Y. Note: (⍴1⊃R) = ⍴⎕LC
2⊃R | Numeric vector giving the stack state of this name as it entered this level: 0 not on stack 1 suspended 2 pendent (may also be suspended) 3 active (may also be pendent or suspended) Note: (⍴2⊃R) = ⍴⎕LC
3⊃R | Numeric vector giving the name classification of Y as it entered this level. Note: (⍴3⊃R) = +/1⊃R
4⊃R | Vector giving the Contents of Y before it was shadowed at this level. Note: (⍴4⊃R) = +/0≠3⊃R

Example:

      ⎕FMT∘⎕OR¨'FN1' 'FN2' 'FN3'
    ∇ FN1;A;B;C      ∇ FN2;A;C               ∇ FN3;A
[1]   A←1        [1]   A←'HELLO'         [1]   A←100
[2]   B←2        [2]   B←'EVERYONE'      [2]   ∘
[3]   C←3        [3]   C←'HOW ARE YOU?'      ∇
[4]   FN2        [4]   FN3
    ∇                ∇

      )SI
FN3[2]*
FN2[4]
FN1[4]

      ⎕STATE 'A'
 1 1 1  0 0 0  2 2 0   HELLO  1


Stop Control

⎕STOP

Dyadic ⎕STOP means

Set Stop Vector

      5 ⎕STOP 'MyFunction'
      MyFunction

MyFunction[5]

Monadic ⎕STOP means

Query Stop Vector

      ⎕STOP 'MyFunction'
5

Language Elements


Set Stop

Set Stop Vector

{R}←X ⎕STOP Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator.  X must be a simple non-negative integer scalar or vector.  R is a simple integer vector of non-negative elements.  X identifies the numbers of lines in the function or operator named by Y on which a stop control is to be placed.  Numbers outside the range of line numbers in the function or operator (other than 0) are ignored.  The number 0 indicates that a stop control is to be placed immediately prior to exit from the function or operator.  If X is empty, all existing stop controls are cancelled.  The value of X is independent of ⎕IO.

R is a vector of the line numbers on which a stop control has been placed in ascending order.  The result is suppressed unless it is explicitly used or assigned.

Examples:

      +(0,⍳10) ⎕STOP 'FOO'
0 1

Existing stop controls in the function or operator named by Y are cancelled before new stop controls are set:

      +1 ⎕STOP 'FOO'
1

All stop controls may be cancelled by giving X an empty vector:

      ⍴'' ⎕STOP 'FOO'
0

      ⍴⍬ ⎕STOP 'FOO'
0

Attempts to set stop controls in a locked function or operator are ignored.

      ⎕LOCK'FOO'

      +0 1 ⎕STOP'FOO'

The effect of ⎕STOP when a function or operator is invoked is to suspend execution at the beginning of any line in the function or operator on which a stop control is placed immediately before that line is executed, and immediately before exiting from the function or operator if a stop control of 0 is set. Execution may be resumed by a branch expression.  A stop control interrupt may also be trapped - see the ⎕TRAP system variable.

Example:

      ⎕FX'R←FOO' 'R←10'

      0 1 ⎕STOP'FOO'

      FOO
FOO[1]

      R
VALUE ERROR
      R
      ∧

      →1
FOO[0]

      R
10

      →⎕LC
10


Trace Control

⎕TRACE

Dyadic ⎕TRACE means

Set Trace Vector

      3 ⎕TRACE 'MyFunction'
      MyFunction
 MyFunction[3]  4

Monadic ⎕TRACE means

Query Trace Vector

      ⎕TRACE 'MyFunction'
3

Language Elements


Set Trace

Trace Set

{R}←X ⎕TRACE Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator.  X must be a simple non-negative integer scalar or vector.  R is a simple integer vector of non-negative elements.

X identifies the numbers of lines in the function or operator named by Y on which a trace control is to be placed.  Numbers outside the range of line numbers in the function or operator (other than 0) are ignored. The number 0 indicates that a trace control is to be placed immediately prior to exit from the function or operator.  The value of X is independent of ⎕IO.

Example:

      +(0,⍳10) ⎕TRACE'FOO'
0 1

Existing trace controls in the function or operator named by Y are cancelled before new trace controls are set:

      + 1 ⎕TRACE'FOO'
1

All trace controls may be cancelled by giving X an empty vector:

      ⍴⍬ ⎕TRACE 'FOO'
0

Attempts to set trace controls in a locked function or operator are ignored.

      ⎕LOCK 'FOO'

      +1 ⎕TRACE 'FOO'

The effect of trace controls when a function or operator is invoked is to display the result of each complete expression for lines with trace controls as they are executed, and the result of the function if trace control 0 is set.  If a line contains expressions separated by ⋄, the result of each complete expression is displayed for that line after execution.

The result of a complete expression is displayed even where the result would normally be suppressed. In particular:

  1. the result of a branch statement is displayed

  2. the result ('pass-through' value) of assignment is
  displayed

  3. the result of a function whose result would normally be suppressed is displayed;
    4.

For each traced line, the output from ⎕TRACE is displayed as a two element vector, the first element of which contains the function or operator name and line number, and the second element of which takes one of two forms.

  1. The result of the line, displayed as in standard
  output.

  2. followed by a line number.
    3.

Example:

      ⎕VR 'DSL'
     ∇ R←DSL SKIP;A;B;C;D
[1]    A←2×3+4
[2]    B←(2 3⍴'ABCDEF')A
[3]    →NEXT×⍳SKIP
[4]    'SKIPPED LINE'
[5]   NEXT:C←'one' ⋄ D←'two'
[6]   END:R←C D
     ∇

      (0,⍳6) ⎕TRACE 'DSL'

      DSL 1
 DSL[1]  14
 DSL[2]   ABC   14
          DEF
 DSL[3]  →5
 DSL[5]  one
 DSL[5]  two
 DSL[6]   one   two
 DSL[0]   one   two
 one  two


Account Information

R←⎕AI

This is a simple integer vector, whose four elements are:

⎕AI[1] | user identification
⎕AI[2] | compute time for the APL session in milliseconds
⎕AI[3] | connect time for the APL session in milliseconds
⎕AI[4] | keying time for the APL session in milliseconds

Elements beyond 4 are not defined but reserved.

Example:

      ⎕AI
52 7396 2924216 2814831


Account Name

R←⎕AN

This is a simple character vector containing the user (login) name.

Example:

      ⎕AN
Pete

      ⍴⎕AN
4


Clear Workspace System Function

Clear Workspace

⎕CLEAR

A clear workspace is activated, having the name CLEAR WS. The active workspace is lost. All system variables assume their default values. The maximum size of workspace is available.

Example:

      ⎕CLEAR
      ⎕WSID
CLEAR WS


Comparison Tolerance

⎕CT

The value of ⎕CT determines the precision with which two numbers are judged to be equal. Two numbers, X and Y, are judged to be equal if:

        (|X-Y)≤⎕CT×(|X)⌈|Y

where ≤ is applied without tolerance.

⎕CT may be assigned any value in the range from 0 to 16*¯8. A value of 0 ensures exact comparison. The value in a clear workspace is 1E¯14.

⎕CT is an implicit argument of the monadic primitive functions Ceiling (⌈), Floor (⌊) and Unique (∪), and of the dyadic functions Equal (=), Excluding (~), Greater (>), Greater or Equal (≥), Index of (⍳), Intersection (∩), Less (<), Less or Equal (≤), Match (), Membership (∊), Not Match (≢), Not Equal (≠), Residue (|) and Union (∪).

Examples:

        ⎕CT←1E¯10
        1.00000000001 1.0000001 = 1
1 0


Division Method

⎕DIV

The value of ⎕DIV determines how division by zero is to be treated. If ⎕DIV=0, division by 0 produces a DOMAIN ERROR except that the special case of 0÷0 returns 1. If ⎕DIV=1, division by 0 returns 0.

⎕DIV may be assigned the value 0 or 1. The value in a clear workspace is 0.

⎕DIV is an implicit argument of the monadic function Reciprocal (÷) and the dyadic function Divide (÷).

Examples:

      ⎕DIV←0

      1 0 2 ÷ 2 0 1
0.5 1 2

      ÷ 0 1
DOMAIN ERROR
      ÷0 1
      ∧

      ⎕DIV←1

      ÷0 2
0 0.5

      1 0 2 ÷ 0 0 4
0 0 0.5


Index Origin

⎕IO

⎕IO determines the index of the first element of a non-empty vector.

⎕IO may be assigned the value 0 or 1.  The value in a clear workspace is 1.

⎕IO is an implicit argument of any function derived from the Axis operator ([K]), of the monadic functions Fix (⎕FX), Grade Down (⍒), Grade up (⍋), Index Generator (>⍳), Roll (?), and of the dyadic functions Deal (?), Grade Down (⍒), Grade up (⍋), Index of (⍳), Indexed Assignment, Indexing, Pick (⊃) and Transpose (⍉).

Examples:

        ⎕IO←1
        ⍳5
1 2 3 4 5

        ⎕IO←0
        ⍳5
0 1 2 3 4

        +/[0]2 3⍴⍳6
3 5 7

        'ABC',[¯.5]'='
ABC
===


Key Labels

R←⎕KL Y

Classic Edition Only

Y is a simple character vector or a vector of character vectors containing Input Codes for Keyboard Shortcuts. In the Classic Edition, keystrokes are associated with Keyboard Shortcuts by the Input Translate Table.

R is a simple character vector or a vector of character vectors containing the labels associated with the codes. If Y specifies codes that are not defined, the corresponding elements of R are empty.

⎕KL provides the information required to build device-independent help messages into applications, particularly full-screen applications using ⎕SM and ⎕SR.

Examples :

      ⎕KL 'RC'
Right

      ⎕KL 'ER' 'EP' 'QT' 'F1' 'F13'
 Enter  Esc  Shift+Esc  F1  Shift+F1


Load Workspace

⎕LOAD Y

Y must be a simple character scalar or vector containing the identification of a saved workspace.

If Y is ill-formed or does not identify a saved workspace or the user account does not have access permission to the workspace, a DOMAIN ERROR is reported.

Otherwise, the active workspace is replaced by the workspace identified in Y.  The active workspace is lost.  If the loaded workspace was saved by the )SAVE system command, the latent expression (⎕LX) is immediately executed, unless apl was invoked with the -x option.  If the loaded workspace was saved by the ⎕SAVE system function, execution resumes from the point of exit from the ⎕SAVE function, with the result of the ⎕SAVE function being 0.

The workspace identification and time-stamp when saved is not displayed.

If the workspace contains any GUI objects whose VISIBLE property is 1, these objects will be displayed.  If the workspace contains a non-empty ⎕SM but does not contain an SM GUI object, the form defined by ⎕SM will be displayed in a window on the screen.


Latent Expression

⎕LX

This may be a character vector or scalar representing an APL expression. The expression is executed automatically when the workspace is loaded. If APL is invoked using the -x flag, this execution is suppressed.

The value of ⎕LX in a clear workspace is ''.

Example:

      ⎕LX←'''GOOD MORNING'''

      )SAVE GREETING
GREETING saved Tue Jul 18 10:49:29 1995

      )LOAD GREETING
./GREETING saved Tue Jul 18 10:49:29 1995
GOOD MORNING


Program Function Keys

Program Fn.Keys

R←{X}⎕PFKEY Y

⎕PFKEY is a system function that sets or queries the programmable function keys.  ⎕PFKEY associates a sequence of keystrokes with a function key.  When the user subsequently presses the key, it is as if he had typed the associated keystrokes one by one.

Y is an integer scalar in the range 0-255 specifying a programmable function key.  If X is omitted the result R is the current setting of the key.  If the key has not been defined previously, the result is an empty character vector.

If X is specified it is a simple or nested character vector defining the new setting of the key.  The value of X is returned in the result R.

The elements of X are either character scalars or 2- element character vectors which specify Input Translate Table codes.

Programmable function keys are recognised in any of the three types of window (SESSION, EDIT and TRACE) provided by the Dyalog APL development environment. ⎕SR operates with the 'raw' function keys and ignores programmed settings.

Note that key definitions can reference other function keys.

The size of the buffer associated with ⎕PFKEY is specified by the pfkey_size parameter.

Examples:

      (')FNS',⊂'ER') ⎕PFKEY 1
 )FNS  ER

      DISPLAY ⎕PFKEY 1
.→-------------.
|         .→-. |
| ) F N S |ER| |
| - - - - '--' |
'∊-------------'

      (')VARS',⊂'ER') ⎕PFKEY 2
 )VARS  ER

      'F1' 'F2' ⎕PFKEY 3   ⍝ Does )FNS and )VARS
 F1  F2


Print Width

⎕PW

⎕PW is the maximum number of output characters per line before folding the display.

⎕PW may be assigned any integer value in the range 30 to 32767. The value in a clear workspace is 79.

If an attempt is made to display a line wider than ⎕PW, then the display will be folded at or before the ⎕PW width and the folded portions indented 6 spaces. The display of a simple numeric array may be folded at a width less than ⎕PW so that individual numbers are not split.

⎕PW only affects output, either direct or through ⎕ output.  It does not affect the result of the function Format (⍕), of the system function ⎕FMT, or output through the system functions ⎕ARBOUT and ⎕ARBIN, or output through ⍞.

Note that if the auto_pw parameter is set to 1, ⎕PW is reset dynamically whenever the Session window is resized. In these circumstances, a value assigned to ⎕PW will only be effective until the Session Window is next resized.

Examples:

      ⎕PW←30

      ⎕←3⍴÷3
0.3333333333 0.3333333333
      0.3333333333


Random Link

⎕RL

⎕RL is used or set to establish a base for generating random numbers.

⎕RL may be assigned any integer value in the range 1 to 2147483646.  The value in a clear workspace is 16807.

Repeatable results can be obtained from Roll or Deal if ⎕RL is set to a particular value first.

⎕RL is used and set implicitly by the functions Roll and Deal (?).

Examples:

      ⎕RL
16807

      ?9 9 9
2 7 5

      ?9
7

      ⎕RL
984943658

      ⎕RL←16807
      ?9 9 9
2 7 5


Save Workspace

{R}←{X}⎕SAVE Y

Y must be a simple character scalar or vector, identifying a workspace name. R is a simple logical scalar. The active workspace is saved with the given name in Y. In the active workspace, the value 1 is returned. The result is suppressed if not used or assigned.

The optional left argument X is either 0 or 1. If X is omitted or 1, the saved version of the workspace has execution suspended at the point of exit from the ⎕SAVE function. If the saved workspace is subsequently loaded by ⎕LOAD, execution is resumed, and the value 0 is returned if the result is used or assigned, or otherwise the result is suppressed. In this case, the latent expression value (⎕LX) is ignored.

If X is 0, the workspace is saved without any State Indicator. The effect is the same as if you first executed )RESET and then )SAVE. In this case, when the workspace is subsequently loaded, the value of the latent expression (⎕LX) is honoured if applicable.

A DOMAIN ERROR is reported if the name in Y is not a valid workspace name, or the reference is to an unauthorised directory.

⎕SAVE will fail and issue DOMAIN ERROR if any threads (other than the root thread 0) are running.

Note that the values of all system variables (including ⎕SM) and all GUI objects are saved.

Example:

      (⊃'SAVED' 'ACTIVE' [⎕IO+⎕SAVE'TEMP']),' WS'
ACTIVE WS
      ⎕LOAD 'TEMP'
SAVED WS


Workspace Available

R←⎕WA

This is a simple integer scalar. It identifies the total available space in the virtual active workspace area given as the number of bytes it could hold. The virtual workspace includes the physical workspace.

A side effect of using ⎕WA is an internal reorganisation of the workspace and process memory, as follows.

  1. Any un-referenced memory is discarded. This process, known as garbage collection, is required because whole cycles of refs can become un-referenced.

  2. Numeric arrays are demoted to their tightest form. For example, a simple numeric array that happens to contain only values 0 or 1, is demoted or squeezed to have a ⎕DR type of 11 (Boolean).

  3. All remaining used memory blocks are copied to the low-address end of the workspace, leaving a single free block at the high-address end. This process is known as compaction.

  4. Workspace above a small amount (1/16 of the configured maximum workspace size) of working memory is returned to the Operating System. On a Windows system, you can see the process size changing by using Task Manager.

Example:

      ⎕WA
8261412


Workspace Identification

⎕WSID

This is a simple character vector. It contains the identification name of the active workspace. If a new name is assigned, that name becomes the identification name of the active workspace, provided that it is a correctly formed name.

See workspace naming conventions.

It is useful, though not essential, to associate workspaces with a specific directory in order to distinguish workspaces from other files.

The value of ⎕WSID in a clear workspace is 'CLEAR WS'. Normally an APL session is initialised with the active workspace as it was on the completion of the last session terminated by the )OFF system command.

Example:

      ⎕WSID
CLEAR WS

      ⎕WSID←'WS/MYWORK'     (UNIX)

      ⎕WSID←'B:\WS\MYWORK'   (DOS)


DOS Shell Command

Windows Command

R←⎕CMD Y

⎕CMD executes a Windows Command Processor or UNIX shell, or starts another Windows application program. ⎕CMD is a synonym of ⎕SH. Either system function may be used in either environment (Windows or UNIX) with exactly the same effect. ⎕CMD is probably more natural for the Windows user. This section describes the behaviour of ⎕CMD and ⎕SH under DOS. See ⎕SH for a discussion of the behaviour of these system functions under UNIX.

The system commands )CMD and )SH provide similar facilities but may only be executed from the APL Session.

Executing a Windows Command

If Y is a simple character vector, ⎕CMD invokes the Windows Command Processor (normally cmd.exe) and passes Y to it for execution. R is a vector of character vectors containing the result of the command. Each element in R corresponds to a line of output produced by the command.

Example:

      Z←⎕CMD'DIR'
      ⍴Z
8
      ↑Z
 Volume in drive C has no label  Directory of C:\DYALOG

.            <DIR>     5-07-95  3.02p
..           <DIR>     5-07-95  3.02p
SALES    DWS    110092 5-07-95  3.29p
EXPENSES DWS    154207 5-07-95  3.29p

If the command specified in Y already contains the redirection symbol (>) the capture of output through a pipe is avoided and the result R is empty. If the command specified by Y issues prompts and expects user input, it is ESSENTIAL to explicitly redirect input and output to the console. If this is done, APL detects the presence of a ">" in the command line, runs command processor in a visible window, and does not direct output to the pipe. If you fail to do this your system will appear to hang because there is no mechanism for you to receive or respond to the prompt.

Example :

      ⎕CMD 'DATE <CON >CON'

(Command Prompt window appears)
Current date is Wed 19-07-1995
Enter new date (dd-mm-yy): 20-07-95
(DOS window disappears)

Implementation Notes

The right argument of ⎕CMD is simply passed to the appropriate command processor for execution and its output is received using an unnamed pipe.

By default, ⎕CMD will execute the string 'cmd.exe /c',Y where Y is the argument given to ⎕CMD. However, the implementation permits the use of alternative command processors as follows.

Before execution, the argument is prefixed and postfixed with strings defined by the APL parameters CMD_PREFIX and CMD_POSTFIX. The former specifies the name of your command processor and any parameters that it requires. The latter specifies a string which may be required. If CMD_PREFIX is not defined, it defaults to the name defined by the environment variable COMSPEC followed by "/c". If COMSPEC is not defined, it defaults to cmd.exe.. If CMD_POSTFIX is not defined, it defaults to an empty vector.

⎕CMD treats certain characters as having special meaning as follows:

# marks the start of a trailing comment
; divides the command into sub-commands
> if found within the last sub-command, causes ⎕CMD to use a visible window

If you simply wish to open a Command Prompt window, you may execute the command as a Windows Program (see below). For example:

      ⎕CMD 'cmd.exe' ''

Executing a Windows Program

If Y is a 2-element vector of character vectors, ⎕CMD starts the executable program named by Y[1] with the initial window parameter specified by Y[2]. The shy result is an integer scalar containing the window handle allocated by the window manager.

Y[1] must specify the name or complete pathname of an executable program. If the name alone is specified, Windows will search the following directories:

  1. the current directory
  2. the Windows directory
  3. the Windows system directory
  4. the directories specified by the PATH variable
  5. the list of directories mapped in a network

Note that Y[1] may contain the complete command line, including any suitable parameters for starting the program. If Windows fails to find the executable program, ⎕CMD will fail and report FILE ERROR 2.

Y[2] specifies the window parameter and may be one of the following. If not, a DOMAIN ERROR is reported.

'Normal' | Application is started in a normal window, which is given the input focus.
'' | Same as Normal
'Unfocused' | Application is started in a normal window, which is NOT given the input focus.
'Hidden' | Application is run in an invisible window.
'Minimized' | Application is started as an icon which is NOT given the input focus.
'Minimised' | Same as Minimized.
'Maximized' | Application is started maximized (full screen) and is given the input focus.
'Maximised' | Same as Maximized

An application started by ⎕CMD may ONLY be terminated by itself or by the user. There is no way to close it from APL. Furthermore, if the window parameter is HIDDEN, the user is unaware of the application (unless it makes itself visible) and has no means to close it.

Examples:

      Path←'c:\Program Files\Microsoft Office\Office\'
      ⎕←⎕CMD (Path,'excel.exe') ''
33
      ⎕CMD (Path,'winword /mMyMacro') 'Minimized'


Start AuxiliaryProcessor

X ⎕CMD Y

Used dyadically, ⎕CMD starts an Auxiliary Processor. The effect, as far as the APL workspace is concerned, is identical under both DOS and UNIX, although the method of implementation differs. ⎕CMD is a synonym of ⎕SH. Either function may be used in either environment (DOS or UNIX) with exactly the same effect. ⎕CMD is probably more natural for the DOS user. This section describes the behaviour of ⎕CMD and ⎕SH under DOS. See ⎕SH for a discussion of the behaviour of these system functions under UNIX.

X must be a simple character vector containing the name (or pathname) of a Dyalog APL Auxiliary Processor (AP).

Y may be a simple character scalar or vector, or a vector of character vectors. Under DOS the Contents of Y are ignored.

⎕CMD loads the Auxiliary Processor into memory. If no other APs are currently running, ⎕CMD also allocates an area of memory for communication between APL and its APs.

The effect of starting an AP is that one or more external functions are defined in the workspace. These appear as locked functions and may be used in exactly the same way as regular defined functions.

When an external function is used in an expression, the argument(s) (if any) are passed to the AP for processing via the communications area described above. APL halts whilst the AP is processing, and waits for a result. Under DOS, unlike under UNIX, it is not possible for external functions to run in parallel with APL.


Unix Shell

Unix Shell Command

{R}←⎕SH Y

⎕SH executes a UNIX shell command or a Windows command. ⎕SH is a synonym of ⎕CMD. Either function may be used in either environment (UNIX or Windows) with exactly the same effect. ⎕SH is probably more natural for the UNIX user. This section describes the behaviour of ⎕SH and ⎕CMD under UNIX. See ⎕CMD for a discussion of the behaviour of these system functions under Windows.

Y must be a simple character scalar or vector representing a UNIX shell command. R is a nested vector of character vectors.

Y may be any acceptable UNIX command. It could cause another process to be entered, such as BASIC or VI. If the process returns a result, each line of the standard result when the same command is given at the shell prompt level is returned as an item of a vector. If the process does not return a result, R is ⊂'' but the result is suppressed if not explicitly used or assigned.

Examples:

      ⎕SH'ls'
FILES WS temp

      ⎕SH 'rm WS/TEST'


Start Unix AP

Start Auxiliary Processor

X ⎕SH Y

Used dyadically, ⎕SH starts an Auxiliary Processor. The effect, as far as the APL user is concerned, is identical under both DOS and UNIX although, there are differences in the method of implementation. ⎕SH is a synonym of ⎕SCMDS. Either function may be used in either environment (UNIX or DOS) with exactly the same effect. ⎕SH is probably more natural for the UNIX user. This section describes the behaviour of ⎕SH and ⎕CMD under UNIX. See ⎕CMD for a discussion of the behaviour of these system functions under DOS.

X must be a simple character vector. Y may be a simple character scalar or vector, or a nested character vector.

⎕SH loads the Auxiliary Processor from the file named by X using a search-path defined by the environment variable WSPATH.

The effect of starting an AP is that one or more external functions are defined in the workspace. These appear as locked functions and may be used in exactly the same way as regular defined functions.

When an external function is used in an expression, the argument(s) (if any) are piped to the AP for processing. If the function returns a result, APL halts while the AP is processing and waits for the result. If not it continues processing in parallel.

The syntax of dyadic ⎕SH is similar to the UNIX execl(2) system call, where 'taskname' is the name of the auxiliary processor to be executed and arg0 through argn are the parameters of the calling line to be passed to the task, viz.

       'taskname'  ⎕SH  'arg0' 'arg1' ... 'argn'

Examples:

        'xutils' ⎕SH 'xutils' 'ss' 'dbr'

        '/bin/sh' ⎕SH 'sh' '-c' 'adb test'


Time Stamp

R←⎕TS

This is a seven element vector which identifies the clock time set on the particular installation as follows:

⎕TS[1] | Year
⎕TS[2] | Month
⎕TS[3] | Day
⎕TS[4] | Hour
⎕TS[5] | Minute
⎕TS[6] | Second
⎕TS[7] | Millisecond

Example:

      ⎕TS
1995 7 11 10 42 59 123

Note that on some systems, where time is maintained only to the nearest second, a zero is returned for the seventh (millisecond) field.


Exit From APL

⎕OFF

This niladic system function terminates the APL session, returning to the shell command level . The active workspace does not replace the last continuation workspace.


Error Messages

Trappable APL Errors
1 | WS FULL | insufficient workspace
2 | SYNTAX ERROR | not a meaningful statement
3 | INDEX ERROR | invalid index/axis
4 | RANK ERROR | invalid argument rank
5 | LENGTH ERROR | non-conforming arg. shapes
6 | VALUE ERROR | no such object
7 | FORMAT ERROR | ill-formed format spec.
10 | LIMIT ERROR | system limit exceeded
11 | DOMAIN ERROR | outside permitted range/type
12 | HOLD ERROR | can't save as array/file held
16 | NONCE ERROR | reserved syntax
18-38 | APL File Errors | errors from the file system
52-63 | ⎕SM Errors | errors from screen manager
90 | EXCEPTION | Microsoft .Net exception
92 | TRANSLATION ERROR | error in translating between Unicode and ⎕AV indices
101-145 | DOS File Errors | errors from DOS
1001 | ⎕STOP | stop control set
1002 | WEAK INTERRUPT | stop execution by weak break
1003 | INTERRUPT | stop execution by hard break
1004 | INPUT INTERRUPT |
1005 | EOF INTERRUPT | end-of-file encountered
1006 | TIMEOUT | time limit exceeded
1007 | RESIZE | ⎕SM window resized
1008 | DEADLOCK | thread can't acquire hold

Non-Trappable System Errors
bad ws
cannot create name
copy incomplete
defn error
incorrect command
is not a ws
not copied name
not enough resources
not found name
sys error nn
too many names
trap error
warning duplicate label
warning duplicate name
warning pendent operation
warning label name present in line 0
warning unmatched brackets
warning unmatched parentheses
ws not found
ws too large


Contents

Graphical User Interface (GUI)

Objects | have properties, generate events and perform methods
Properties | determine an object’s appearance or behaviour
Events | generated by objects in response to user actions
Methods | functions performed by objects

Object Management Functions


Objects

Objects: Categorised

Objects: Alphabetical

System Objects |
Root | system-level object
Printer | for hard-copy output
Clipboard | provides access to Windows clipboard
Container Objects |
CoolBand | represents a band in a CoolBar
CoolBar | a container for CoolBand objects
Form | top-level Window
MDIClient | container for MDI windows
SubForm | acts as an MDI window or a constrained Form
Group | a frame for grouping Buttons and other objects
Static | a frame for drawing and clipping graphics
StatusBar | ribbon status bar
TabBar | contains TabBtns (tabs)
TabControl | contains TabButtons (tabs)
ToolBar | ribbon tool bar
ToolControl | Windows 95 tool bar
PropertySheet | contains PropertyPages
PropertyPage | tabbed or paged container for other controls
Splitter | divides a container into panes
Menu |
MenuBar | pull-down menu bar
Menu | pop-up menu
MenuItem | selects an option or action
Separator | separator between items
Action |
Button | selects an option
ToolButton | performs an action or selects an option
TabBtn | selects a tabbed SubForm
TabButton | selects a tabbed SubForm
Scroll | scroll bar
UpDown | spin buttons
Locator | graphical (positional) input device
Timer | generates events at regular intervals
Information |
Label | displays static text
StatusField | displays status information
MsgBox | displays a message box
TipField | displays pop-up context sensitive help
ProgressBar | displays the progress of a lengthy operation
Input & Selection |
Calendar | displays a month calendar control
Grid | displays a data matrix as a spreadsheet
Edit | text input field
RichEdit | text input with word-processing capabilities
Spinner | input field with spin buttons
List | for selecting an item
ListView | displays a collection of items for selection
Combo | edit field with selectabe list of choices
TreeView | displays a hierarchical collection of items
TrackBar | a slider control for analogue input/output
FileBox | prompts user to select a file
Resource |
Font | loads a font
Bitmap | defines a bitmap
Icon | defines an icon
ImageList | defines a collection of bitmaps or icons
Metafile | loads a Windows Metafile
Cursor | defines a cursor
Graphical Output |
Circle | draws a circle
Ellipse | draws an ellipse
Marker | draws a series of polymarkers
Poly | draws lines
Rect | draws rectangles
Image | displays Bitmaps, Icons and Metafiles
Text | draws graphical text
Miscellaneous |
ActiveXContainer | represents the application hosting a Dyalog APL ActiveXControl
ActiveXControl | represents an ActiveX control written in Dyalog APL
NetClient | provides access to .Net Classes
NetControl | instantiates a .Net Control.
NetType | exports an APL namespace as a Net Class
OCXClass | provides access to OLE Custom Controls
OLEClient | provides access to OLE Automation objects
OLEServer | enables APL to act as an OLE Automation server
SM | specifies a window for ⎕SM (character mode interface)
TCPSocket | provides an interface to TCP/IP sockets


ActiveXContainer Object

Properties Events Methods

Purpose | The ActiveXContainer object represents the application that is currently hosting an instance of an ActiveXControl object.
Parents | ActiveXControl
Children | (None)

Description

An ActiveXContainer is used to represent the host application that is hosting an ActiveXControl object, and provides access to its ambient properties such as font, and colour.

An ActiveXContainer object is created using the Container property of the ActiveXControl object. For example, the following expression , executed within an ActiveXControl instance creates an ActiveXContainer named 'CONT'

      'CONT' ⎕NS ⎕WG'Container'

The ambient properties of the host application are reported by the FontObj, Fcol and Bcol properties which are all read-only.

The ActiveXContainer object supports the AmbientChanged event which is reported when any of the ambient properties change. This event allows the ActiveXContainer to react to such changes.


ActiveXControl Object

Properties Events Methods

Purpose | The ActiveXControl object represents a Dyalog APL namespace as an ActiveX control.
Parents | Form
Children | ActiveXContainer, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, Metafile, MsgBox, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertySheet, Rect, RichEdit, Scroll, Spinner, Splitter, Static, StatusBar, SubForm, TabBar, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

The ActiveXControl object represents a Dyalog APL namespace as an ActiveX control.

During development, an ActiveXControl is a container object that is the child of a Form and acts as a wrapper for one or more other GUI objects.

To make an ActiveXControl available to another application, you must select Make OCX from the Session File menu. This creates an .OCX file that contains your entire workspace and all of the ActiveXControls within it.

Once an ActiveXControl has been saved in an .OCX file, any application that supports ActiveX may create and use instances of it.

When an ActiveX control is loaded by a host application, it and any code that it requires, is loaded into the host application’s address space; it does not run in a separate address space.

During development, an ActiveXControl is powered by the development version of Dyalog APL. However, an ActiveXControl object that is loaded by a host application, is powered by a DLL version of Dyalog APL. This automatically gets loaded when a host application creates the first instance of any Dyalog APL ActiveX control. However, within a single host application, other instances of the same or other Dyalog APL ActiveX controls share the same copy of DYALOG.DLL.

Like the development and run-time versions of Dyalog APL, DYALOG.DLL has an active workspace. When an application loads an ActiveXControl, DYALOG.DLL copies the top-level namespace that owns the ActiveXControl, together with everything it contains, into the active workspace. For example, if the ActiveXControl is named Controls.Form1.Ctrl1, the act of creating the first instance of Ctrl1 will cause the entire contents of the Controls namespace to be copied, from the corresponding .OCX file, into the active workspace. This affords the potential for controls from different OCX files to clash, but the name clash conflict is restricted to just one name.

Each instance of an ActiveXControl, is represented by a separate namespace which is automatically cloned from the original ActiveXControl namespace. Each instance namespace is entirely separate from any other instance namespace and there is no way for one instance to reference or see any other instance; nor can it reference the original class namespace from which it was cloned. In fact, each instance appears to itself to be the one and only original class namespace. Using the previous example, each instance of Ctrl1 believes that its full pathname is #.Controls.Form1.Ctrl1, although each instance is in fact a separate clone of that namespace.

When an application creates an instance of an ActiveXControl, it does so as the child of some object within its own GUI hierarchy. From the instance’s viewpoint, its parent Form is replaced by a different GUI object that imposes position, size, font, background colour, and other ambient properties.

The external name of an ActiveXControl is made up of the character vector defined by the ClassName property, prefixed by the string “Dyalog “, and followed by the string “ Control”. If ClassName is empty (which is the default), the name of the ActiveXControl namespace is inserted instead. Note that the name should not include APL symbols such as Á or ∆.ClassName may only be specified when you create the ActiveXControl with ⎕WC and may not be changed using ⎕WS.

The Coord property is read-only and its value is always 'Pixel'. If you wish to use a different co-ordinate system for the children of an ActiveXControl object, it is necessary to set Coord separately on each one of them.

Posn and Size are negotiable properties. When an instance of the ActiveXControl is created, the values of Posn and Size will be assigned by the host application. You may change these values using ⎕WS, but the host application has the right to refuse them and there is no guarantee that you will get what you set.

The Border and EdgeStyle properties may be used to control the outline appearance of the ActiveXControl object.

The Dragable and KeepOnClose properties apply only during development and are otherwise ignored.

The ToolBoxBitmap property specifies the name of a Bitmap object that may be used by a host application to represent the ActiveXControl when its complete visual appearance is not required.. For example, if you add an ActiveX control to the Microsoft Visual Basic development environment, its bitmap is added to the toolbox. The Bitmap should therefore be of an appropriate size, usually 24 x 24 pixels.

The Container property provides access to an ActiveXContainer object that represents the host application itself. This may be used to obtain the values of ambient properties, or to access methods exposed by the host application via OLE interfaces.

When an instance of an ActiveXControl is created, it generates first a PreCreate event, and then a Create event. The PreCreate event is generated at the point the instance is made.

The Create event is generated at the point when the host application requires the instance to appear visually. If, as is recommended, you create child controls of the instance when it is created, you must respond to the Create event, because at the time that PreCreate is generated, the object does not have a window.

Host applications which support two different modes of operation, namely design mode and run mode, differ in the way that they create instances of ActiveX controls. Microsoft Access does not require an ActiveX control to appear properly in design mode. Instead, it draws a simple box containing just the name of the object. If your ActiveXControl is hosted by Microsoft Access, it will get a PreCreate Event when an instance is created in design mode, and a Create event only when it enters run mode. Microsoft Visual Basic, however, requires the object to draw itself immediately, even in design mode, and so a Create event will be generated immediately after a PreCreate event in this case.


Animation Object

Properties Events Methods

Purpose | The Animation object displays simple animations from basic .AVI files or resources.
Parents | ActiveXControl, Form, Group, PropertyPage, SubForm
Children | Bitmap, Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The Animation object displays simple animations from basic .AVI files or resources.

The Animation object can only play AVI files or resources that have no sound and can only display uncompressed AVI files or .AVI files that have been compressed using Run-Length Encoding (RLE).

For more sophisticated animations, you may use the Windows Media Player (OCX).

To display an AVI file, you must first use the AnimOpen method to open it. If the AutoPlay property is set to 1, the animation will play immediately. Otherwise, only the first frame will be displayed.

The Align property may be 'None' or 'Centre' ('Center'). If Align is 'None', the Animation window is automatically resized to fit the AVI being played. If Align is 'Centre', the AVI is centred in the Animation window. If the window is too small, the AVI is clipped.

The AnimPlay method may be used to play the animation and allows you to specify the start, number of frames, and repeat count.

The AnimStop method causes the animation to stop.

The AnimClose method closes the current AVI file and resets the contents of the object's window to its background colour.

The AnimStarted and AnimStopped events are reported when the animation starts and stops respectively.


Bitmap Object

Properties Events Methods

Purpose | A graphical object used to represent a bitmap which may be used both to display a picture or as a pattern (brush) used to fill other objects.
Parents | ActiveXControl, Animation, Button, CoolBand, Form, Grid, Group, ImageList, ListView, Menu, MenuBar, MenuItem, NetType, OLEServer, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, StatusBar, SubForm, TCPSocket, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown
Children | Circle, Ellipse, Font, Image, Marker, Metafile, Poly, Rect, Text, Timer

Description

A Bitmap may be created either from a file (.BMP) or from APL arrays. To create a Bitmap object using ⎕WC, you can either specify the File property or the Cbits property, or the Bits and CMap properties.

If you specify File, it should contain the name of a bitmap file from which the bitmap is to be read. If omitted, a .BMP file extension is added. You may also load a Bitmap from a DLL or from the DYALOG.EXE executable. See File property for details.

If instead you want to create a Bitmap dynamically from APL variables, you may do so in one of two ways.

For a palette of up to 256 colours, you may specify the image using the Bits and CMap properties. The alternative is to use the Cbits property which works for any size of colour palette.

If MaskCol is non-zero, it specifies the transparent colour for the Bitmap. Any pixels specified with the same colour will instead be displayed in whatever colour is underneath the Bitmap. This achieves similar behaviour to that of an Icon.

The KeepBits property has the value 0 or 1, and controls how a Bitmap is saved in the workspace. A value of 0 (the default) means that the values of Cbits, Bits and CMap are not kept in the workspace. If you request the values of Cbits, Bits or CMap with ⎕WG, they are obtained directly from the corresponding Windows bitmap resource. When the workspace is )LOADed, the Bitmap is recreated from the associated file defined by the value of the File property. Note that if this file doesn't exist when the workspace is )LOADed, the Bitmap is not created, but no error is generated. However, when you reference the object you will get a VALUE ERROR.

If KeepBits is 1, the values of Cbits, Bits and CMap are stored permanently in the workspace, and are used to rebuild the Bitmap when the workspace is )LOADed. In this case, the file name (if any) is ignored. Setting KeepBits to 1 uses more workspace, but may be more convenient if you want to distribute applications.

The Size property allows you to query the size of a Bitmap without having to retrieve the Cbits or Bits property and then take its "shape". This will be noticeably faster for a large Bitmap. If you set the Size property using ⎕WS the Bitmap is scaled to the new size.

A useful feature of a Bitmap is that it can be the parent of any of the graphical objects. This allows you to create or edit a bitmap by drawing lines, circles, etc. in it.

The FileRead (90) and FileWrite (91) methods allow you to dynamically manage bitmap files (.BMP). The expression :

bmname.FileWrite

causes the Bitmap called bmname to be written to the file specified by the current value of the File property. The file is automatically written in standard bitmap format. Similarly, the expression :

bmname.FileRead

causes the Bitmap called bmname to be redefined from the bitmap file specified by the current value of the File property.

The MakeGIF and MakePNG methods may be used to convert the image represented by a Bitmap object into an uncompressed GIF or PNG data stream, suitable for display in a web browser. The TCPSendPicture method may be used to transfer a Bitmap on a TCP/IP socket.

Using a bitmap is always a 2-stage process. First you create a Bitmap object with ⎕WC. Then you use it by specifying its name as a property of another object.

The Picture property specifies the name of a Bitmap to be displayed in an ActiveXControl, Button, Form, Group, Image, MDIClient, Sm, Static, StatusBar, StatusField, SubForm, TabBar, or ToolBar.

The BtnPix property specifies three Bitmaps to be used to represent the 3 states of a Button, Menu or MenuItem.

The FStyle property specifies the name of a Bitmap to be used as a pattern to fill a Poly, Ellipse or Rect object.


BrowseBox Object

Properties Events Methods

Purpose | The BrowseBox object allows the user to browse for and select a folder or other resource.
Parents | ActiveXControl, CoolBand, Form, Grid, OLEServer, PropertyPage, PropertySheet, Root, StatusBar, SubForm, TCPSocket, ToolBar, ToolControl
Children | Timer

Description

For full functionality as described here, the BrowseBox object requires the Windows Shell Library SHELL32.DLL Version 4.71 or higher. The BrowseBox object also supports the enhanced functionality provided by SHELL32.DLL Version 5 (Windows 2000) if present.

The BrowseBox object is a dialog box that allows the user to browse for and select a folder (directory) or other resource.

The BrowseFor property specifies the type of resource and may be 'Directory' (the default), 'File', 'Computer' or 'Printer'.

The StartIn property specifies the path name where browsing should start.

The HasEdit property specifies whether or not the dialog box contains an edit field into which the user can type the name of the folder or other resource, rather than browsing for it. The default is 0.

A BrowseBox may only be used by the execution of a modal ⎕DQ. The action code for the FileBoxOK and FileBoxCancel events must be set to 1 so that the appropriate result is returned by the modal ⎕DQ.

After the user has pressed OK or Cancel, the Target property contains the name of the chosen folder or other resource

Example:

     ∇ DIR←{START_DIR}GetDir CAPTION;BB;MSG
[1]    ⍝ Ask user for a Directory name
[2]    ⍝ CAPTION specifies Caption for dialog box
[3]    ⍝ START_IN (optional) specifies starting directory
[4]    ⍝ DIR is empty if user cancels
[5]    :With 'BB'⎕WC'BrowseBox'
[6]        :If 2=⎕NC'START_DIR'
[7]            StartIn←START_DIR
[8]        :Else
[9]            StartIn←''
[10]       :EndIf
[11]       onFileBoxOK←onFileBoxCancel←1
[12]       Caption←CAPTION
[13]       HasEdit←1
[14]       MSG←⎕DQ''
[15]       :If 'FileBoxOK'≡2⊃MSG
[16]           DIR←Target ⍝ = 3⊃MSG
[17]       :Else
[18]           DIR←''
[19]       :EndIf
[20]   :EndWith
     ∇


Button Object

Properties Events Methods

Purpose | Allows the user to initiate an action or to select an option using a button.
Parents | ActiveXControl, CoolBand, Form, Grid, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The type of button displayed is determined by the Style property which may take the value 'Push', 'Radio', 'Check' or 'Toggle'. Under Windows, 'Toggle' and 'Check' are treated identically.

Push buttons are used to generate actions. When the user "presses" a pushbutton, it generates a Select event (30). To cause an action, you simply associate the name of a callback function with this event for the Button in question.

Radio buttons and Check boxes are used to select options. They each have two states between which the user can toggle by clicking the mouse. When the Button (option) is selected, its State property has the value 1; otherwise it is 0.

Only one of a group of Radio buttons which share the same parent can be set (State is 1) at any one time. Radio buttons are therefore used for a set of choices that are mutually exclusive. Check boxes however, may be set together to signify a combination of options. These are used for making choices which are not mutually exclusive.

Radio and Check buttons also generate Select events when their State changes, and you can attach callback functions to these events to keep track of their settings. However, as Radio and Check buttons are not normally used to generate actions, it is perhaps easier to wait until the user signifies completion of the dialog box in some way, and then query the State of the buttons using ⎕WG. For example, if you have a set of Radio or Check buttons in a Group called f1.options, the following statements retrieve their settings.

OPTIONS ← (⎕WN 'f1.options') ⎕WG¨⊂'State'

or

OPTIONS ← ⎕WG∘'State' ¨ ⎕WN 'f1.options'

The Caption property determines the text displayed in the Button. Its default value is an empty vector. If Style is 'Radio' or 'Check',the text may be aligned to the left or right of the button graphic using the Align property. Its default value is 'Right'.

If Posn is omitted, the button is placed in the centre of its parent. If either element of Posn is set to <—>, the button is centred along the corresponding axis.

If Size is not specified, the size of the button is determined by its Caption. If either element of Size is set to <—> the corresponding dimension is determined by the height or width of its Caption. If Caption is not specified, or is set to an empty vector, the value of Size is set to a default value.

Button colours can be specified using FCol and BCol. However, pushbuttons (Style 'Push') ignore BCol and instead use the standard Windows colour.

The Picture property is used to display a bitmap on a pushbutton. This property is a 2-element array containing the name of a Bitmap object and the "mode" in which it is to be displayed. The default mode (3) is the most useful, as it causes the Bitmap to be superimposed on the centre of the Button. The surrounding edges of the Button (which gives it its 3-dimensional appearance and pushbutton behaviour) are unaffected.

An alternative is to use the BtnPix property. This property specifies the names of up to 3 Bitmap objects. The first Bitmap is displayed when the State of the Button is 0. The second is displayed when its State is 1. The third is shown when the Button is inactive (Active 0). BtnPix is more flexible than Bitmap, but if you want your Button to exhibit pushbutton behaviour, you must design your bitmap accordingly.

The ReadOnly property is Boolean and specifies whether or not the user may change the state of the Button. It applies only to Style 'Radio' and Style 'Check'.


Calendar Object

Properties Events Methods

Purpose | The Calendar object provides an interface to the Month Calendar Control
Parents | ActiveXControl, Form, Group, PropertyPage, SubForm, ToolBar
Children | Cursor, Font, Menu, MsgBox, TCPSocket, Timer

Description

The Calendar object displays a calendar and allows the user to select a date or range of dates. The following illustration (Example 1) shows a default Calendar object.

The Calendar object will display as many full months as it can fit into the area specified by its Size property (Example 2).The minimum size required to encompass a single month may be obtained using the GetMinSize method.

The Today property is an IDN that specifies the current day. Its default value is today’s date, i.e. the local date set on your computer.

The CircleToday property is either 0 or 1 (the default) and specifies whether or not the Today date is circled when the Calendar object is showing the corresponding month.

The HasToday property is either 0 or 1 (the default) and specifies whether or not the Today date is displayed (using the Windows short date format) in the bottom left of the Calendar object.

The WeekNumbers property is either 0 (the default) or 1 and specifies whether or not the Calendar displays week numbers.

Example 3 shows a Calendar with both CircleToday and HasToday set to 0 and WeekNumbers set to 1.

The FirstDay property is an integer whose value is in the range 0-6. FirstDay specifies the day that is considered to be the first day of the week and which appears first in the Calendar. The default value for FirstDay depends upon your International Settings.

The MinDate and MaxDate properties are integers that specify the minimum and maximum IDN values that the user may display and select in the Calendar object. By default these properties specify the entire range of dates that the Windows Month Calendar control can provide.

The MonthDelta property specifies the number of months by which the Calendar object scrolls when the user clicks its scroll buttons. The default is empty (zilde) which implies the number of months currently shown.

The Style property may be either 'Single' (the default) or 'Multi'. If Style is 'Single', the user may select a single date. If Style is 'Multi', the user may select a contiguous range of dates. In this case, the maximum number of contiguous days that can be selected is defined by the MaxSelCount property which is an integer whose default value is 7.

The SelDate property is a 2-element integer vector of IDN values that identifies the first and last dates that are currently selected.

When the user selects one or more dates, the Calendar object generates a SelDateChange event. This event is also generated when the Calendar object is scrolled, and the selection changes automatically to another month.

The Calendar displays day numbers using either the normal or the bold font attribute and you may specify which attribute is to be used for each day shown. However, the Calendar object does not store this information beyond the month or months currently displayed.

When the Calendar control scrolls (and potentially at other times), it generates a GetDayStates event that, in effect, asks you (the APL program) to tell it which (if any) of the dates that are about to be shown should be displayed in bold.

If you wish any dates to be displayed using the bold font attribute, you must attach a callback function to the GetDayStates event which returns this information in its result. By default, all dates are displayed using the normal font attribute, so you only need a callback function if you want any dates to be displayed in bold.

You may also set the font attribute for particular days in the range currently displayed by calling GetDayStates as a method.

The CalendarCols property specifies the colours used for various elements in the Calendar object.

You may convert dates between IDN and ⎕TS representations using the IDNToDate and DateToIDN methods. Note that these methods apply to all objects and not just to the Calendar object itself.

The GetVisibleRange method reports the range of dates that is currently visible in the Calendar object.


Circle Object

Properties Events Methods

Purpose | A Graphical object to draw circles, arcs, and pie-slices.
Parents | ActiveXControl, Animation, Bitmap, Button, Combo, ComboEx, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TipField, ToolBar, TrackBar, TreeView, UpDown
Children | Timer

Description

The Points property contains the co-ordinates of the centre of the circle. The size of the circle is determined by the Radius property. This specifies the radius along the x-axis, the height is calculated so that the object is circular.

The RadiusMode property determines whether or not the circle is adjusted by a pixel, if required in order to appear perfectly round and perfectly centred. The default value is 0 (no adjustment is made).

The Start and/or End properties are used to draw partial circles. They specify start and end angles respectively, measuring from the x-axis in a counter-clockwise direction and are expressed in radians. The type of arc is controlled by ArcMode as follows :

ArcmodeEffect

0An arc is drawn from Start to End.

1An arc is drawn from Start to End. In addition, a single straight line is drawn from one end of the arc to the other, resulting in a segment.

2An arc is drawn from Start to End. In addition, two lines are drawn from each end of the arc to the centre, resulting in a pie-slice.

Points, Radius, Start and End can specify vectors so that several arcs, circles, pie slices, etc. can be drawn in one call (and with one name).

If Start is specified, but not End, end angles default to (¯1↓+\Start),○2. If End is specified, but not Start, start angles default to 0,¯1↓+\End

This means that you can draw a pie-chart using either Start or End angles; you do not have to specify both.

Examples:

A circle whose centre is (50,50) and radius 20

      'g.p1' ⎕WC 'Circle' (50 50) 20

An arc

      'g.arc' ⎕WC 'Circle' (50 50) 20 ('Start' (○0.75))('End' (○1.25))

Complete pie

      Data←12 27 21 40
      ANGLES←0,¯1↓((○2)÷+/Data)×+\Data
      COLS←(255 0 0)(0 255 0)(255 255 0)(0 0 255)
      PATS←1 2 3 4
      'g.pie' ⎕WC 'Circle' (50 50) 20 ('Start' ANGLES)('ArcMode' 2) ('FCol' (⊂0 0 0))('FStyle' PATS) ('FillCol' COLS)

Same pie as above, but 2nd slice is exploded by changing its centre and 4th slice is shrunk by reducing its radius :

      CY←50 52 50 50  ⍝ y-coord of centres
      R←20 20 20 17.5 ⍝ radii
      'g.pie' ⎕WC 'Circle' (50 CY) R ('Start' ANGLES)('ArcMode' 1) ('FCol' (⊂0 0 0))('FStyle' PATS) ('FillCol' COLS)


Clipboard Object

Properties Events Methods

Purpose | This object provides access to the Windows clipboard.
Parents | ActiveXControl, CoolBand, Form, OLEServer, PropertyPage, PropertySheet, Root, TCPSocket
Children | Timer

Description

When an application places data in the Windows clipboard, it may store it in one or more formats. An application wishing to retrieve data from the clipboard can then choose which format to read it in. Dyalog APL supports standard clipboard formats, including CF_TEXT, CF_BITMAP and CF_METAFILE. If there is any data in the clipboard, the Formats property lists the formats in which it may be retrieved.

In addition, the Array property may be used to set or retrieve clipboard contents in Dyalog APL array format.

Data is read from the clipboard using ⎕WG, specifying the name of the appropriate property for the data that you want.

If the data has been stored in CF_Text format, the value of Formats will include 'Text' and you may retrieve the data by querying the value of the Text property with ⎕WG.

If the data has been stored in device-independent bitmap format, the value of Formats will include 'CBits', 'Bits' and 'CMap'. To retrieve the bitmap pattern and colour map, you may query the values of the CBits, or Bits and CMap properties using ⎕WG.

If the data has been stored in device-dependent bitmap format, only the bitmap pattern is available and Formats will contain 'Bits' but not 'CMap'. In this case you can query the Bits property but not CMap without which you cannot realise the bitmap. However, if data was posted in this format, it is highly probable that the current Windows colour map applies to it. For a standard 16-colour device this is given under the description of the CMap property.

The following example retrieves text from the clipboard :

      'CL' ⎕WC 'Clipboard'
      Data ← 'CL' ⎕WG 'Text'

The next example retrieves a bitmap from the clipboard and defines it as a Bitmap object named 'BM' ready for use :

      'BM' ⎕WC 'Bitmap' '', 'CL' ⎕WG 'Bits' 'CMap'

Data may be placed in the clipboard using ⎕WC or ⎕WS. To store text, you simply set the Text property. You may use a simple character vector or matrix, or a vector of character vectors. For example :

      'CL' ⎕WS 'Text' 'Hello World'

To store a bitmap you can set either the Picture property to the name of a Bitmap object, or you can set the Bits and CMap properties explicitly. The former is more efficient, especially for large bitmaps, for example :

      'CL' ⎕WS 'Bitmap' 'BM'

or

      Bits CMap ← 'BM' ⎕WG 'Bits' 'CMap'
      'CL' ⎕WS ('Bits' Bits)('CMap' CMap)

Note that if you use the latter method, you must set both properties in one ⎕WS statement. This is also true if you wish to store data in both Text and Bitmap formats together.

The Metafile property allows graphical information to be restored in and retrieved from the clipboard in Windows Metafile format. See the description of the Metafile property for details.

A ClipChange (120) event is generated when another application places data in the clipboard.


ColorButton Object

Properties Events Methods

Purpose | The ColorButton object allows the user to select a colour.
Parents | ActiveXControl, Form, Grid, Group, PropertyPage, SubForm
Children | (None)

Description

The ColorButton object displays a coloured box, with an optional drop down button. When the user clicks the ColorButton with the left mouse button, a colour selection drop-down appears below it, allowing the user to select a new colour.

The CurrentColor property (default 0 0 0) is a 3-element integer vector that specifies and reports the RGB value of the currently selected colour.

The DefaultColors property is a nested matrix which specifies the RGB values of the colours shown in the colour selection box. The shape of DefaultColors determines the number of rows and columns in the colour selection drop-down. Each element of DefaultColors is a 3-element integer vector specifying an RGB colour value.

The OtherButton property is Boolean and specifies whether or not the user can select a colour using the Windows colour selection dialog box.

If OtherButton is 1 (the default), the final row of the colour selection drop-down contains a button labelled "Other…". If the user clicks this button, the standard Windows colour selection dialog box is displayed, allowing the user to select any colour that the computer can render.

If OtherButton is 0, the button labelled "Other…" is not present and the user is restricted to the choice of colours provided by the DefaultColors property.

The CustomColors property is a 1-row, 16-column nested matrix which specifies the RGB values of the Colours displayed in the Custom colors section of the Windows colour selection dialog box. Each element of CustomColors is a 3-element integer vector specifying an RGB colour value.

The ShowDropDown property is Boolean (default 1) and specifies whether or not a drop-down button is displayed in the ColorButton object.

When the user clicks a ColorButton with the left mouse button, the object generates a DropDown event just before it displays the colour selection drop-down. This event may be used to set the DefaultColors and/or CustomColors properties dynamically.

When the user selects a new colour, the ColorButton generates a ColorChange event.

Note that Pocket PC 2002 colour selection dialog box does not provide the facility to select custom colours, so this functionality is not available in PocketAPL.


Combo Object

Properties Events Methods

Purpose | This object combines an input area with a list box and allows the user to enter a selection by typing text or by choosing an item from the list.
Parents | ActiveXControl, CoolBand, Form, Grid, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

Three types of Combo box are provided by the Style property which may be 'Drop' (the default), 'Simple' or 'DropEdit'.

The Items property specifies the list of items which are displayed in the list box and from which the user can choose.

The SelItems property is a boolean vector which specifies which (if any) of the items is selected. When the user chooses an item from the list, it is copied to the edit field and a Select event is generated. At this point you may use SelItems to identify the chosen item. You can also use SelItems to pre-select the contents of the edit field.

If the Style is 'Simple' or 'DropEdit', the user may type text into the edit field. In these cases, the contents of the edit field may also be specified or queried using the Text property. Note that if the user first selects an item from the list box, then changes it in the edit field, the entry in the list box is automatically deselected. There is therefore no conflict between the value of Text and the value of SelItems.

For a Combo with Style 'Simple', the Index property specifies or reports the position of Items in the list box as a positive integer value. If Index has the value "n", it means that the "nth" item in Items is displayed on the top line in the list box. Note that Index can only be set using ⎕WS and not by ⎕WC and is ignored if all the Items fit in the list box. The default value for Index is ⎕IO.

The SelText property identifies the portion of the edit field that is highlighted. It is not applicable to a Combo with Style 'Drop' as the user cannot enter or change data in its edit field.

The height of a Combo object with Style 'Drop' or 'DropEdit' is defined in a manner that is different from other objects. The height of the edit field is fixed, and is dependent only upon the size of the font. The height of the associated drop-down list box is determined by the Rows property. The first element of the Size property (height) is ignored. For a Simple combo box (whose listbox is permanently displayed), the overall height is determined by the first element of Size. Rows is a "read-only" property.

If the Style is 'Simple' or 'DropEdit', the HScroll property determines whether or not the edit field may be scrolled. If HScroll is 0, the data is not scrollable, and the user cannot enter more characters once the field is full. If HScroll is ¯1 or ¯2 the field is scrollable, and there is no limit on the number of characters that can be entered. In neither case however is a horizontal scrollbar provided. If Style is 'Drop', the user is not allowed to enter data into the edit field anyway, and the value of HScroll is ignored.

Note that when you change the Items property using ⎕WS, the Text, SelItems and SelText properties are all reset to their default values.

The Combo object will report a Select event (if enabled) when the user chooses an item from the list box. It will generate a Change event (if enabled) when the user manually alters the contents of the edit field and then changes the focus to another object.


ComboEx Object

Properties Events Methods

Purpose | The ComboEx object is an extended version of the Combo object that provides additional features including item images
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The ComboEx object is a ComboBox that supports item images and indenting. It is a superset of the Combo object and supports all its functionality. For further details, see Combo Object.

For most purposes, you can use the ComboEx object in place of the Combo object whether or not you make use of the extended features of the ComboEx.

Like the basic Combo, the list of text items in the ComboEx is specified by the Items property. You may associate images with each of the text items using the ImageList, ImageIndex and SelImageIndex properties.

To do so, ImageList specifies the name of an ImageList object that contains a set of images. ImageIndex and SelImageIndex map individual images from the ImageList to each of the text items specified by Items. ImageIndex specifies the image to be displayed when the item is not selected; SelImageIndex specifies the image to be displayed when the item is selected.

The Indents property specifies the amount by which each of the items are indented in units of 10 pixels

The appearance of the items is additionally controlled by the EditImage and EditImageIndent properties. These are boolean and their effect is summarised in the table below. Notice that Images are displayed only if both these properties are set to 1 (which is the default).

There are certain restrictions that apply to a ComboEx object with Style 'Simple', namely:

  • images and indents do not apply to the edit control portion of the object.
  • the object may not redraw properly if EditImage and/or EditImageIndent are set to 0 or if CaseSensitive or PathWordBreak are set to 1.
  • PathWordBreak does not work.
 | EditImageIndent
EditImage | 0 | 1
0 | No images displayed, item text is indented as specified by Indents | No images displayed, item text is indented as specified by Indents plus the width of the images in ImageList
1 | No images displayed, item text is indented as specified by Indents | Images are displayed, items are indented as specified by Indents


CoolBand Object

Properties Events Methods

Purpose | The CoolBand object represents an area in a CoolBar that contains a child window.
Parents | CoolBar
Children | Bitmap, BrowseBox, Button, Clipboard, Combo, ComboEx, Cursor, Edit, FileBox, Font, Grid, Group, Icon, ImageList, Label, List, ListView, Menu, Metafile, MsgBox, OCXClass, OLEClient, Printer, ProgressBar, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabControl, TCPSocket, Timer, TipField, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

The CoolBand object is a container object that represents a band in a CoolBar.

A CoolBand can have any combination of a gripper bar, a bitmap, a text label, and a single child object.

A CoolBand may not contain more than one child object, but that child object may itself be a container such as a ToolControl or a SubForm.

The Caption property specifies a text string to be displayed to the left of the CoolBand. The colour of the text is specified by the Fcol property.

The ImageIndex property specifies an optional picture which is to be displayed alongside the Caption. If specified, ImageIndex is an index into an ImageList whose name is referenced via the ImageListObj property of the parent CoolBar.

The background in a CoolBand may be specified using its Bcol or Picture properties. Although typically, the visible background area is small, it is visible through a transparent ToolControl.

The ChildEdge property specifies whether or not the CoolBand leaves space above and below its child window.

The GripperMode property specifies whether or not the CoolBand has a gripper bar which is used to reposition and resize the CoolBand within its parent CoolBar. GripperMode may be 'Always' (the default), 'Never' or 'Auto'.

The position of a Cool Band within a CoolBar is determined by its Index and NewLine properties, and by the position and size of preceding CoolBand objects in the same CoolBar. For a CoolBand, Posn is a read-only property that reports its position but Posn may not be used to set it.

The Index property specifies the position of a CoolBand within its parent CoolBar, relative to other CoolBands and is ⎕IO dependant. Initially, the value of Index is determined by the order in which the CoolBands are created. You may re-order the CoolBands within a CoolBar, under program control, by changing Index with ⎕WS.

The NewLine property specifies whether or not the CoolBand occupies the same row as an existing CoolBand, or is displayed on a new line within its CoolBar parent. The value of NewLine in the first CoolBand in a CoolBar is always 1, even if you specify it to be 0. You may move a CoolBand to the previous or next row by changing its NewLine property (using ⎕WS )from 1 to 0, or from 0 to 1 respectively.

The 2nd element of the Size property determines the width of the CoolBand; the value of the 1st element is read-only.

Size may only be specified by ⎕WC. However, when you create a CoolBand, it will automatically occupy all the available space in the current row, to the right of any preceding CoolBands. Only when you create another CoolBand in the same row, will the Size of the first CoolBand be honoured. The rightmost CoolBand will always extend to the right edge of the CoolBar, whatever its Size.

If you create two or more CoolBands in the same row and you do not specify Size, the first CoolBand will be maximised, and the others minimised.

When the user drags a CoolBand to a different row its Index and NewLine properties may change, as may the Index and NewLine properties of any another CoolBand that is affected by the operation.

If you wish to remember the user’s chosen layout when your application terminates, you must store the values of Index x, Size and NewLine for each of the CoolBands. When your application is next started, you must re-create the CoolBands with the same values of these properties.


CoolBar Object

Properties Events Methods

Purpose | The CoolBar object acts as a container for CoolBand objects.
Parents | ActiveXControl, Form
Children | CoolBand, ImageList, Menu, Timer

Description

The CoolBar and CoolBand objects provide an interface to Windows Rebar Controls

A CoolBar contains one or more bands (CoolBand objects). Each band can have any combination of a gripper bar, a bitmap, a text label, and a single child object.

Using the gripper bars, the user may drag bands from one row to another, resize bands in the same row, and maximise or minimise bands in a row.

Example 1 illustrates a CoolBar containing 2 CoolBands each of which is displaying a ToolControl object.

Example 2 illustrates a CoolBar containing 3 CoolBands displaying an Edit, Combo and multi-line Edit respectively.

The VariableHeight property specifies whether or not the CoolBar displays bands in different rows at the minimum required height (the default), or all the same height.

The BandBorders property specifies whether or not narrow lines are drawn to separate adjacent bands. The default is 0 (no lines).

The DblClickToggle property specifies whether or not the user must single-click (the default) or double-click to toggle a child CoolBand between its maximised and minimised state.

The FixedOrder property specifies whether or not the CoolBar displays CoolBands in the same order. If FixedOrder is 1, the user may move bands to different rows, but the band order is static. The default is 0. Note that when the user moves a CoolBand within a CoolBar, its Index and (potentially) NewLine properties will change to reflect its new position.

If you wish to display pictures in one or more of the CoolBands owned by a CoolBar, you do so by setting the ImageListObj property to the name of an ImageList object which contains the pictures. Pictures are allocated to individual CoolBands via their ImageIndex properties.


Cursor Object

Properties Events Methods

Purpose | This object defines a cursor.
Parents | ActiveXControl, Animation, Button, Calendar, Combo, ComboEx, CoolBand, DateTimePicker, Edit, Form, Grid, Group, ImageList, Label, List, ListView, OLEServer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, SM, Static, StatusBar, SubForm, TCPSocket, ToolBar, ToolControl, TrackBar, TreeView, UpDown
Children | Timer

Description

The File property defines the name of a cursor file associated with the Cursor object, or it specifies the name of a DLL and the resource number or name of the cursor therein. If you omit the file extension, the system assumes .CUR. To use an animated cursor you must therefore specify the .AMI extension explicitly.

If the value of the File property is set by ⎕WS, no immediate action is taken, but the corresponding file may subsequently be read or written using the FileRead or FileWrite methods.

The Bits and Mask properties define the appearance of the cursor. Both are boolean matrices with a shape of 32 32. The colour of each pixel in the cursor is defined by the following table. Note that a 0 in Bits combined with a 1 in Mask causes the corresponding pixel to be the colour of the background. This is used to give the cursor a non-rectangular shape.

Bits | 0 | 1 | 0 | 1
Mask | 0 | 0 | 1 | 1
Pixel | Black | White | Background | Inverse

The HotSpot property determines the point within the cursor that registers its position over another object.

A Cursor is used by setting the CursorObj property of another object to its name or ref.


DateTimePicker Object

Properties Events Methods

Purpose | The DateTimePicker object is an editable date/time field with an optional drop-down Calendar.
Parents | ActiveXControl, Form, Grid, Group, PropertyPage, SubForm, ToolBar
Children | Cursor, Font, Menu, MsgBox, TCPSocket, Timer

Description

The DateTimePicker object represents the built-in Windows date and time picker control. For most purposes, the DateTimePicker supersedes the use of Label, Edit and Spinner objects for displaying and entering dates and times. Unlike the Edit and Spinner objects, it is not possible for the user to enter an invalid date or time into a DateTimePicker.

The Style property may be either 'Combo' (the default) or 'UpDown'. The former provides a drop-down calendar that behaves in the same way as the Calendar object and whose appearance and behaviour is controlled by a set of properties namely CalendarCols, CircleToday, HasToday, MaxDate, MinDate, MonthDelta, Today and WeekNumbers that are common to the Calendar. See the Calendar Object for further details.

If Style is 'Combo', the Align property specifies the horizontal alignment of the drop-down Calendar which may be 'Left' (the default) or 'Right'.

If Style is 'UpDown', the DateTimePicker includes instead a pair of spinner buttons that allow the user to increment and decrement values in the various sub-fields provided by the control.

Note that the Style property may only be set when the object is created.

The DateTime property represents the date and time value that is currently displayed in the object. This is a 4-element vector containing the IDN, hour, minutes and seconds respectively.

The FieldType property specifies one of a set of pre-defined date/time formats to be used by the control. This is a character vector that may be empty (the default), 'Date', 'DateCentury', 'LongDate', 'Time' or 'Custom'. Specifying an empty vector is the same as specifying 'Date'. Note that 'DateCentury' always displays a 4-digit year, regardless of the user's Windows settings.

If FieldType is set to 'Custom', the format is defined by the CustomFormat property. CustomFormat is a character vector that may contain a mixture of date/time format elements and body text.

The HasCheckBox property is a Boolean value (default 0) that specifies whether or not a checkbox is displayed in the object. This allows the user to specify whether or not the date/time displayed in the DateTimePicker is applicable.


Edit Object

Properties Events Methods

Purpose | Allows user to enter or edit data.
Parents | ActiveXControl, CoolBand, Form, Grid, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The value of the Style property, which may be 'Single' or 'Multi', determines whether the object presents a single-line data entry field or an area for viewing and editing a large block of text.

Single-Line Edit

The FieldType property (which applies only to a single-line Edit object) is either an empty vector (the default) or specifies the type of the field as reflected by its Value.property. If FieldType is empty, the Value of the field may be a number or a character vector, according to the contents defined by its Text property (this is always a character vector).

If FieldType is 'Char', the Value of the field is forced to be a character vector, even if the contents defined by its Text property is entirely numeric.

If FieldType is 'Numeric', 'LongNumeric', 'Currency', 'Date', 'LongDate', or 'Time' the Value contains a number. For fields of these types, basic validation is provided during user input. The field is revalidated when the user attempts to “leave” it and at this point the object will generate a BadValue event if its contents are inconsistent with its FieldType.

Note that when an Edit object is used as the Input property of a Grid, it is the Value of the Edit object (and not its Text property) that is used to update the Values property (i.e. the contents of) the Grid when the user moves away from the cell.

The MaxLength property defines the maximum number of characters that the user may enter into the object.

The ValidIfEmpty property may be 0 (the default) or 1 and specifies whether or not the Edit field is deemed to be valid if it is empty.

The Password property specifies the character that is displayed in response to the user typing a character. Normally, Password is empty (the default) and the object displays the character that was entered. However, if you set Password to (say) an asterisk (*) this symbol will be displayed instead of the characters the user has entered. Note however that the Text and Value properties will reflect what the user typed.

The HScroll property determines whether or not the data may be scrolled. If HScroll is 0, the data is not scrollable, and the user cannot enter more characters once the field is full. If HScroll is ¯1 or ¯2 the field is scrollable, and there is no limit on the number of characters that can be entered. In neither case however is a horizontal scrollbar provided.

Multi-Line Edit

If the Style is 'Multi', Text may be a simple character vector, a matrix, or a vector of vectors. If you specify Text as a matrix, "new-line" characters are automatically added at the end of each row. Similarly, if you specify Text as a vector of vectors, "new-line" characters are added after each vector. The user may insert a "new-line" character in the text by pressing Ctrl-Enter.

If you specify (assign) Text as a vector or vector of vectors, it will be returned as a vector of vectors when you query it. Otherwise, it will be returned as a matrix. "New-line" characters are not returned.

The Justify property determines whether the text in a multi-line Edit object is 'Left', 'Right', or 'Centre' justified. Setting Justify to 'Centre' or 'Right' also forces word-wrapping and disables horizontal scrolling, whatever the value of HScroll. Note that they keyword 'Centre' may also be spelled 'Center'. Justify may only be specified when the object is created using ⎕WC.

If Justify is 'Left', the HScroll property determines whether or not text may be scrolled horizontally. If HScroll is set to ¯2, each individual line may be any length, but the object does not have a horizontal scrollbar. Sideways scrolling is achieved using the cursor keys, or by typing. If HScroll is ¯1, each individual line may be of any length and the object will have a horizontal scrollbar. If HScroll is 0, lines are automatically "word-wrapped" at the right edge of the object. This means that the number of lines displayed may be greater than the number of lines implied by the rows of the matrix or the number of vectors supplied. In particular, if you specify a single long vector, it will be broken up into lines for you on the display, but still returned as a single vector by ⎕WG.

The VScroll property determines whether or not data may be scrolled vertically and whether or not the object has a vertical scrollbar. A value of 0 inhibits scrolling; ¯2 means scrollable, without a scrollbar; ¯1 means scrollable with a scrollbar.

The setting of Justify forces word-wrapping.

The SelText property identifies the portion of the text that is selected. It may be used to pre-select (and highlight) a part of the text, or to report the part of the text selected by the user. SelText is a 2-element integer vector which specifies the start and end of the selected area. Its structure depends upon the nature of the data specified by Text. See the description of SelText for details.

If the user changes any data in the field and attempts to change focus to another object, the Edit object will generate a Change event. You can use this to validate the new data in the field.


Ellipse Object

Properties Events Methods

Purpose | A Graphical object to draw ellipses, arcs, and pie-slices.
Parents | ActiveXControl, Animation, Bitmap, Button, Combo, ComboEx, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TipField, ToolBar, TrackBar, TreeView, UpDown
Children | Timer

Description

This object duplicates much of the functionality of the Circle object, but differs in two major respects. Firstly, ellipses, circles, and arcs are specified in terms of their bounding rectangles, rather than in terms of their centre(s) and radii. Secondly, the Ellipse object behaves like any other (rectangular) object when it is resized by its parent. The Circle object behaves differently in that when resized by its parent, it maintains a constant ratio between its physical height and width.

The Points property specifies one or more sets of co-ordinates which define the position(s) of one or more bounding rectangles. The position is defined to be the position of the corner that is nearest to the origin of its parent. The default is therefore its top-left corner.

The Size property specifies the height and width of each bounding rectangle, measuring away from the origin. To obtain a perfect circle, you must take the aspect ratio of the device into account. This is available from the DevCaps property of the Root and Printer objects. Alternatively you can use the Circle object.

The Start and/or End properties are used to draw partial ellipses and circles. They specify start and end angles respectively, measuring from the x-axis at the centre of the bounding rectangle in a counter-clockwise direction and are expressed in radians. The type of arc is controlled by ArcMode as follows.

ArcmodeEffect

0 | An arc is drawn from Start to End.
1 | An arc is drawn from Start to End. In addition, a single straight line is drawn from one end of the arc to the other, resulting in a segment.
2 | An arc is drawn from Start to End. In addition, two lines are drawn from each end of the arc to the centre, resulting in a pie-slice.

LStyle and LWidth define the style and width of the lines used to draw the boundaries of the ellipse(s), circle(s) or arc(s). FCol and BCol determine the colour of the lines.

FStyle specifies whether or not the ellipse(s), circle(s) or arc(s) are filled, and if so, how. For a solid fill (FStyle 0), FillCol defines the fill colour used. For a pattern fill (FStyle 1-6) FillCol defines the colour of the hatch lines and BCol the colour of the spaces between them.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Ellipse object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple ellipses, circles or arcs :

Single Ellipse, Circle or Arc

For a single ellipse, circle or arc, Points is a 2-element vector which specifies the y-coordinate and x-coordinate of the top-left corner of the bounding rectangle.

Size is also a simple 2-element vector whose elements specify the height and width of the bounding rectangle.

LStyle and LWidth are both simple scalar numbers.

FStyle is either a single number specifying a standard fill pattern, or the name of a Bitmap object which is to be used to fill the ellipse, circle or arc.

FCol, BCol and FillCol are each either single numbers representing standard colours, or 3-element vectors which specify colours explicitly in terms of their RGB values.

Examples:

First make a Form :

      'F' ⎕WC 'Form'

Draw a complete ellipse within the bounding rectangle located at (y=10, x=5) with (height=30, width=50) :

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)

Draw an elliptical arc within the same bounding rectangle as above, occupying the upper right quadrant (0 to 90 degrees):

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('End'(○0.5))

Ditto, but between 45 and 135 degrees :

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('Start'(○0.25))('End'(○0.75))

Ditto, but join the points of the arc to the centre of the ellipse, making a "pie-slice":

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('Start'(○0.25))('End'(○0.75))('ArcMode' 2)

Ditto, but use a green line and solid red fill :

      'F.E1' ⎕WC 'Ellipse' (10 5)(30 50)('Start'(○0.25))('End'(○0.75))('ArcMode' 2)('FCol' 0 0 255)('FStyle' 0)('FillCol' 255 0 0)

Multiple Ellipses, Circles or Arcs

To draw a set of ellipses, circles, or arcs with a single name, Points may be a simple 2-element vector (specifying the location of all the bounding rectangles), or a 2-column matrix whose first column specifies their y-coordinates and whose second column specifies their x-coordinates, or a 2-element nested vector whose first element specifies their y-coordinate(s) and whose second element specifies their x-coordinate(s).

Likewise, Size may be a simple 2-element vector (applying to all the bounding rectangles), or a 2-column matrix whose first column specifies their heights and whose second column specifies their widths, or a 2-element nested vector whose first element specifies their height(s) and whose second element specifies their width(s).

If specified, Start and/or End define arcs in terms of the angles made by drawing a line from the centre of the bounding box to the two ends of the arc. Both properties may be simple scalars, or vectors containing one element per arc drawn.

If Start is specified, but not End, end angles default to (¯1↓+\Start),○2. If End is specified, but not Start, start angles default to 0,¯1↓+\End

This means that you can draw a pie-chart using either Start or End angles; you do not have to specify both.

ArcMode, LStyle and LWidth may each be simple scalar values (applying to all the ellipses, circles or arcs) or simple vectors whose elements refer to each of the corresponding ellipses, circles or arcs in turn.

FStyle may be a simple scalar numeric or a simple character vector (Bitmap name) applying to all rectangles, or a vector whose elements refer to each of the corresponding ellipses, circles or arcs in turn.

Similarly, FCol, BCol and FillCol may each be single numbers or a single (enclosed) 3-element vector applying to all the rectangles. Alternatively, these properties may contain vectors whose elements refer to each of the rectangles in turn. If so, their elements may be single numbers or nested RGB triplets, or a combination of the two.

The Coord, Dragable and Data properties are specified for the object as a whole, and may not be allocated different values for each individual ellipse, circle or arc that is drawn.

Examples

First make a Form :

      'F' ⎕WC 'Form'

Draw two ellipses in bounding rectangles located at (y=5, x=10) and (y=5, x=60), each of (height=40, width=10)

      'F.E1' ⎕WC 'Ellipse' ((5 5)(10 60)) (40 10)

Ditto, using scalar extension for (y=5) :

      'F.E1' ⎕WC 'Ellipse' (5(10 60)) (40 10)

Ditto, but draw the first with (height=40, width=30) and the second with (height=20, width=10) :

      'F.E1' ⎕WC 'Ellipse' (5(10 60)) ((40 20)(30 10))

Draw an elliptical Pie-Chart in a bounding rectangle located at (y=5, x=10) with a height and width equal to 40% of the height and width of the parent Form. Each of the 4 pie-slices is bounded by a black line :

      Data ←12 27 21 40
      ANGLES←0,¯1↓((○2)÷+/Data)×+\Data
      COLS←(255 0 0)(0 255 0)(255 255 0)(0 0 255)
      PATS←1 2 3 4
      'F.PIE' ⎕WC 'Ellipse'(5 10)(40 40)('Start' ANGLES)('ArcMode' 2)('FCol' (⊂0 0 0))('FStyle' PATS)('FillCol' COLS)


FileBox Object

Properties Events Methods

Purpose | Prompts user to select a file.
Parents | ActiveXControl, CoolBand, Form, Grid, OLEServer, PropertyPage, PropertySheet, Root, StatusBar, SubForm, TCPSocket, ToolBar, ToolControl
Children | Timer

Description

The FileBox object implements the standard Windows FileSelection Dialog Box. This is a "modal" object. When you create a FileBox with ⎕WC, it is initially invisible and the user cannot interact with it. To use it, you must execute ⎕DQ with the name of the FileBox as its right argument. This causes the FileBox to be displayed. During the "local" ⎕DQ the user may interact only with the FileBox, or with other applications. When the user terminates the operation (by pressing the "OK" or "Cancel" Buttons, or by closing the window) the "local" ⎕DQ terminates, and the FileBox disappears.

When the "local" ⎕DQ is terminated, the FileBox generates either an FileBoxOk(71) or FileBoxCancel(72) event. The former is generated when the user presses the "OK" button or closes the FileBox; the latter when the user presses the "Cancel" button.

The Caption property determines the text that appears in the title bar of the FileBox window. If undefined, Caption defaults to "Save As" if FileMode is 'Write' or to "Open" if FileMode is 'Read'. The Directory property contains a simple character vector which specifies the initial directory from which a list of suitable files is displayed.

      'F' ⎕WC 'FileBox' 'The FileBox Object' 'C:\WDYALOG'
      ⎕DQ 'F'

The Style property specifies whether the user may choose a single file name ('Single' which is the default) or several file names ('Multi').

The Filters property is a nested scalar or vector containing a list of filters. Each filter is a 2-element vector of character vectors which contain a file type mask and a file type description respectively. The file type descriptions appear in a drop-down combo box labelled "List File of Type". When the user selects one of these, the currently selected directory is searched for files which match the corresponding mask. The default value of Filters is an empty vector. This gives a file type mask of "*.*" and a file type description of "All Files (*.*)". Hence an empty vector is equivalent to (⊂'*.*' 'All Files (*.*)').

The FileMode property is a character vector which indicates the mode in which the selected file is going to be opened. FileMode may be 'Read' (the default) or 'Write'. If FileMode is 'Write', files listed in the File Selection Box are "greyed", although they may still be selected.

The Index property determines which of the filters is initially selected. Its default value is ⎕IO.

Note that when ⎕DQ terminates with FileBoxOk, the File, Directory, and Index properties are updated to reflect the contents of the fields within the FileBox.


Font Object

Properties Events Methods

Purpose | Loads a font resource
Parents | ActiveXControl, Animation, Bitmap, Button, Calendar, Combo, ComboEx, CoolBand, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, OLEServer, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TCPSocket, TipField, ToolBar, ToolControl, TrackBar, TreeView, UpDown
Children | Timer

Description

This object loads a Windows font into memory ready for use by another object. The characteristics of the font are specified by its properties as follows :

PName | A character vector containing the name of the font face, e.g. 'COURIER'. The default is 'System'. Note that case is ignored when you specify the name, although it will be returned correctly by ⎕WG.
Size | An integer that specifies the character height of the font in pixels.
Fixed | A boolean value that specifies whether the font is fixed-width (1) or proportional (0).
Italic | A boolean value that specifies whether the font is italicised (1) or not (0).
Underline | A boolean value that specifies whether the font is underlined (1) or not (0).
Weight | An integer in the range 0-1000 that specifies how bold or heavy the font is (1000 = most bold).
Rotate | A numeric scalar that specifies the angle of rotation of the font in radians. The angle is measure from the x-axis in a counter-clockwise direction.
CharSet | An integer that specifes the character encoding.

When you ask Windows to allocate a font, you may specify as many or as few of these properties as you wish. Windows actually supplies the font that most closely matches the attributes you have specified. The matching rules it uses are complex, and may be found in the appropriate Windows documentation.

The values of the above properties after ⎕WC or ⎕WS reflect the attributes of the font which has been allocated by Windows, and not necessarily the values you have specified. Furthermore, it is possible that changing the value of one property will cause the values of others to be changed.


Form Object

Properties Events Methods

Purpose | This is a top-level window used to contain other objects (controls).
Parents | ActiveXControl, Form, OLEClient, OLEServer, Root, SubForm, TCPSocket
Children | ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, Metafile, MsgBox, NetControl, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertySheet, Rect, RichEdit, Scroll, SM, Spinner, Splitter, Static, StatusBar, SubForm, SysTrayItem, TabBar, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

The Posn property specifies the location of the internal top-left corner of the window relative to the top-left corner of the screen. If the window has a title bar and/or border, you must allow sufficient space for them. Similarly, the Size property specifies the internal size of the window excluding the title bar and border. The default for Size is 50% of the screen height and width. The default for Posn places the Form in the middle of the screen.

Normally, a Form has a title bar, a system menu box, a border and maximise and minimise buttons. To disable the System Menu box, set SysMenu to 0. To disable one or both of the maximise/minimise buttons, set MaxButton and/or MinButton to 0.

The HelpButton property specifies that a Question (?) button appears in the title bar of the Form. However, this does not apply if the Form has a maximise or minimise button which both take precedence. The user may obtain help by clicking on the Question (?) button and then on a control in the Form. It is up to you to provide the help by responding to the Help event on the control.

By default, a Form may be moved and resized using the mouse. These actions are achieved by dragging on the title bar and border respectively. It follows that a Form that is Moveable must have a title bar, and one that is Sizeable must have a border, regardless of the value of other properties. Also, if you specify any of SysMenu, MaxButton or MinButton, the window must have a title bar in which to place these controls. A title bar itself requires a border. To obtain a window without a title bar, you must therefore set Moveable, SysMenu, MaxButton and MinButton to 0. Note that setting Caption does not force a title bar on the window.

If Sizeable is 1, the window will have a double-line border, regardless of the values of other properties. If Sizeable is 0, and any one or more of Moveable, SysMenu, MaxButton, MinButton or Border is 1, the window will have a 1-pixel border. Only if all these properties are 0 will the window be borderless. To obtain a dialog box that may only be moved or closed, set Border to 2.

Note that the default value for Caption is an empty character vector which results in a blank title.

To obtain a standard dialog box with 3-dimensional appearance, create a Form with Border set to 2 and EdgeStyle set to 'Dialog', for example:

      'F' ⎕WC 'Form' 'Dialog Box' ('EdgeStyle' 'Dialog')('Border' 2)

The State property has the value 0 if the window is currently displayed in its "normal" state, 1 if it is currently displayed as an icon, and 2 if it is currently maximised and displayed full-screen. This property does not just report the current state, but can be used to set the state under program control.

The VScroll and HScroll properties determine whether or not a Form has a vertical and horizontal scrollbar respectively. These properties are set to ¯1 to obtain a scrollbar. Their default value is 0 (no scrollbar). The Range property is a 2-element vector that specifies the maximum value for the vertical and horizontal scrollbars respectively. The Step property is a 4-element vector that specifies the sizes of the small and large change. Its first two elements refer to the vertical scrollbar, elements 3 and 4 refer to the horizontal scrollbar. The Thumb property is a 2-element vector that both reports and sets the position of the thumb in the vertical and horizontal scrollbars respectively. When the user attempts to move the thumb in one of the scrollbars, the Form generates a VScroll or HScroll event.

VScroll and HScroll cannot be changed using ⎕WS. However, you can make a scrollbar disappear by setting the corresponding element of Range to 1, thus allowing you to dynamically switch the scrollbar off and on. Note however that doing so will change the size of the Form.

Setting the FontObj property on a Form does not affect the text in its title bar. However, the value of FontObj will (unless over-ridden) be inherited by all of the objects within the Form.

The background of the Form may be coloured using BCol. The default value for BCol is the Windows Button Face colour unless EdgeStyle is set to 'None' or 'Default' in which case it is the Windows background colour. Alternatively, the background of a Form can be defined using a Bitmap or Metafile object whose name is defined by the Picture property. A Metafile is automatically scaled to fit the Form. A Bitmap can be tiled or scaled. See Picture property for details.

The OnTop property is either 0 or 1. If it is 0, the Form assumes its normal position within the stack of windows on the screen and is only brought to the front when it receives the input focus. If OnTop is set to 1, the Form is always brought to the front even when it doesn't have the focus. If more than one Form has OnTop set to 1, the stacking order of this set of Forms is defined by the order in which they were created.

A Form can be created as a child of another Form. If so, it has the following characteristics :

  • A child Form always appears on top of its parent Form (although it is not constrained by it)
  • When you minimize a parent Form, its child Forms disappear.
  • Making the parent Form invisible or inactive has no effect on a Child Form.

Note that the Posn and Size properties of a child Form are expressed in screen coordinates and are not given relative to its parent.


Grid Object

Properties Events Methods

Purpose | This object displays data in a spreadsheet format and allows the user to change it.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm
Children | Bitmap, BrowseBox, Button, Circle, ColorButton, Combo, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Icon, Image, Label, Marker, Menu, MsgBox, NetControl, OCXClass, Poly, Rect, Spinner, Text, Timer, TrackBar

Description

The Values property is a matrix whose elements are displayed in the cells of the Grid. An element (and therefore a cell) may contain a single number, a single character, a character vector or a character matrix.

The CellHeights property specifies the height of each of the rows of the spreadsheet. It may be a single value which applies to all rows, or a vector with one element per row. The CellWidths property determine the width of each column of the spreadsheet. It too may be a single value or a vector with one element per column.

The RowTitles property is either an empty character vector (the default) or a vector of character vectors that specify row titles displayed to the left of the cells in the Grid. If RowTitles is not specified, the Grid labels each row with its row number. The ColTitles property is similar and is used to specify column headings. If ColTitles is not specified, the Grid displays “standard” spreadsheet column headings A-Z, then AA-AZ and so forth.

The TitleHeight property specifies height of the column headers. If this is set to 0, the column titles will not be displayed. Similarly, the TitleWidth property specifies the width of the row titles and again a value of zero disables the row titles.

The FontObj property may be used to specify the font to be used for the Grid as a whole, including the titles. The CellFonts property may be used to specify fonts for individual cells.

The FCol and BCol properties may each specify a single colour for the Grid as a whole, or may specify a vector of colours whose elements are mapped to individual cells through the CellTypes property.

The CellFonts property is either a character vector or a vector of character vectors that specifies the name of a single font object to be used for all cells in the Grid, or a vector of character vectors that specifies a set of font objects that are mapped to individual cells through the CellTypes property.

The Input property is a character vector that specifies the name of an object which is to be associated with every cell in the Grid, or a vector of names whose elements are mapped to individual cells through the CellTypes property. These objects may be of type Button, ColorButton, Combo, Edit, Label, Spinner or TrackBar. In addition, the Input property may specify instances of OCXClass objects (ActiveX controls) and NetType objects (.NET classes).

If the Input property is empty (the default) the user may browse the data in the spreadsheet but may not alter it. Furthermore, no feedback is provided as to which is the current cell. If the Input property specifies the name of an object that is the child of the Grid itself, this object floats from cell to cell as the user moves around the spreadsheet, and the current cell is identified by its presence. If the Input property specifies the name of an external object (that is, an object that is not a child of the Grid), the contents of the current cell are copied into that object as the user moves around the spreadsheet. In addition, the current cell is identified by a thick border. In either case, the associated object is used to impose formatting and validation.

If the Input property specifies the name of a Label object, that object is used to impose formatting, but the data is protected and may not be changed. If the Label is a child of the Grid, it moves from cell to cell, and its characteristics (Border, FCol, BCol and FontObj) can be used to identify the current cell. If the Label is an external one, no visual feedback is provided; even though the current cell (reflected by the CurCell property) changes as the user moves around the Grid.

If the Input property specifies one or more instances of OCXClass objects (ActiveX controls) and NetType objects (.NET classes), the InputProperties property is used to map the Values property of the Grid to specific properties of the external object.

The CellTypes property is either an empty numeric matrix (the default) or an integer matrix of the same shape as Values. If specified, each element of CellTypes determines the index into various properties, including the FCol, BCol, CellFonts and Input properties, to be used for the corresponding cell. For example, if an element in CellTypes is 3, the 3rd element of FCol is used for the foreground colour of the corresponding cell, the 3rd element of BCol specifies the background colour, and so forth.

The CurCell property may be used to set or query the current cell. The current cell is the cell which the user has picked by clicking the mouse over it or by using the cursor keys. CurCell is a 2-element vector containing the current cell’s row number and column number respectively and is ⎕IO dependent. The Index property specifies the row and column number of the cell in the top-left corner of the Grid. It too is ⎕IO dependent.

The AutoExpand property is a 2-element boolean vector which specifies whether (1) or not (0) new rows and columns are added when the user presses the corresponding cursor key when at the end of the block of cells. Its default value is (0 0).

The Grid object reports a CellDown event when the user depresses a mouse button over a cell. The event message contains the row and column address of the cell in question which is ⎕IO dependent. It also reports a similar CellUp event when the mouse button is released and a CellDblClick event when it is double-clicked. The number of the mouse button and the state of the shift keys are also reported.

When the user moves to another cell, the Grid object reports a CellMove event. This simply reports the address of the new cell and may be used to take some appropriate action when a particular cell is picked. If the user alters the data in a cell and then attempts to move to another, the Grid reports a CellChange event. This can be used to perform validation. Alternatively, the Grid may report a CellChanged event which occurs after the Values property has been updated with the new cell contents. This may be used to perform immediate recalculation.

The AddRow event is generated if the current cell is in the last row of the Grid and the user presses Cursor Down. By default, this operation adds a new row to the Grid, but you can attach a callback to the AddRow and selectively disable this default action if required. The AddCol event works in a similar manner for columns. Although the user has no direct means of inserting a row or column, your application can do this by calling AddRow or AddCol as a method on the Grid object. Typically this would be done in response to the user selecting a MenuItem or pressing a Button.

The ColChange, RowChange, DelRow, DelCol and Undo methods allow your application to perform these corresponding operations.

The Grid object maintains a buffer of the most recent 8 changes made by the user since the Values property was last set by ⎕WC or ⎕WS. Your application can restore these changes one by one by calling the Undo method. The Undo method restores the most recent change made by the user and removes that change from the undo stack. It is therefore not possible to “undo an undo”.

The Grid supports the selection of a block or blocks of cells using the mouse and/or the keyboard. The ability to select a range of cells is determined by the CellSelect property. When the user performs a selection , the Grid generates a GridSelect event. The range of cells currently selected is given by the SelItems property

If a block of cells has been selected, the user may delete the contents, and cut or copy the contents of the cells to the clipboard by pressing Delete, Shift+Delete or Ctrl+Insert respectively. These operations also generate GridDelete, GridCut and GridCopy events which you can selectively disable using a callback function. You can also perform these operations under program control by calling them as methods.

If more than one block of cells has been selected, these operations are honoured only if the blocks begin and end on the same rows or begin and end on the same columns. If so, the data placed in the clipboard is the result of joining the blocks horizontally or vertically as appropriate.

The user may paste data from the clipboard into a Grid by pressing Shift+Insert. Data is pasted into the currently selected block of cells, or, if there is no selection, data is pasted starting at the current cell (CurCell). The operation also generates a GridPaste event, and, if the operation cannot proceed, a GridPasteError event.

If you move the mouse pointer over any of the four edges of a selected block of cells, the cursor changes to an arrow. You may now click and drag the border of the selected cells with the mouse. If you press the Ctrl key at the same time, the contents of the selected cells are copied to the new location, replacing the values in the block of cells onto which they are dropped. Otherwise, the operation is treated as a move and the original block of cells is emptied. This operation also generates a GridDropSel event. You may only move or copy a single block of cells in this way.

The user may be permitted to resize the rows and/or columns of a Grid. This is controlled by the ResizeRows and ResizeCols properties whose default values are 0. To allow the user to resize, set either or both to 1. You can also specify a boolean vector to allow specific rows/columns to be resized while others are fixed. Two additional properties named ResizeRowTitles and ResizeColTitles determine whether or not the user may alter the width of the row titles and the height of the column titles.

If resizable, the cursor changes to a double-heads arrow when the user moves the mouse pointer over the lines between the row and/or column titles. The user may click and drag with the mouse to the desired size. The user may also double-click. This causes the row or column to be resized to fit the data. Both operations generate a SetColSize, or SetRowSize event.

When you edit data in a Grid, the editing behaviour and the action of the cursor movement keys is determined by the InputMode and InputModeKey properties.

The GridFCol property specifies the colour of all the grid lines. Alternatively, the GridLineFCol, GridLineWidth, RowLineTypes and ColLineTypes properties may specify the appearance for individual grid lines.

The GridBCol property specifies the colour used to fill the area between the end of the last column of data and the right edge of the Grid and between the bottom row of data and the bottom edge of the Grid.

The RowTitleFCol and ColTitleFCol properties specify the colours to be used for the row and column titles respectively.

The ClipCells property determines whether or not the Grid displays partial cells. The default is 1. If you set ClipCells to 0, the Grid displays only complete cells and automatically fills the space between the last visible cell and the edge of the Grid with the GridBCol colour.

The CellSet property is a boolean array that marks which cells are set (i.e. have values) and which are empty. This allows you to edit large numeric matrices which contain empty cells without a severe workspace penalty.

The Hscroll and Vscroll properties specify whether or not horizontal and vertical scrollbars are displayed. Either property may be given the value ¯3 which forces the corresponding scrollbar to appear always.

The Grid object supports comments in a manner that is consistent with the way that comments are handled by Microsoft Excel.. If a comment is associated with a cell, a small red triangle is displayed in its top right corner. When the user rests the mouse pointer over a commented cell, the comment is displayed as a pop-up with an arrow pointing back to the cell to which it refers. The comment disappears when the mouse pointer is moved away. This is referred to as tip behaviour. Comments may also be associated with row and column titles.

Grid comments are managed by a set of methods, namely AddComment, DelComment, GetComment, ShowComment, HideComment and ClickComment.

You may lock individual rows and columns using the LockRows and LockColumns methods. This facility is however not supported in combination with hierarchical rows and/or columns which are specified by RowTitleDepth and ColTitleDepth.

The Grid can display a TreeView like interface on the Row titles. In this mode, the Grid automatically shows and hides row of data as the end user expands and contracts nodes of the tree.

The RowTreeDepth property is used to specify the depth of rows in the Grid.

The appearance of the tree is determined by the RowTreeStyle property.

User defined bitmaps can be used instead of the default Images by setting the RowTreeImages property.

The Grid generates Expanding and Retracting events when the user interacts with the tree.

The RowSetVisibleDepth method can be used to set the visible depth of the tree.


Group Object

Properties Events Methods

Purpose | This object is used to group a related set of controls together visually, and to impose "radio-button" behaviour.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Animation, Bitmap, Button, Calendar, Circle, ColorButton, Combo, ComboEx, Cursor, DateTimePicker, Edit, Ellipse, Font, Grid, Group, Image, ImageList, Label, List, ListView, Locator, Marker, Metafile, NetControl, Poly, ProgressBar, Rect, RichEdit, Scroll, SM, Spinner, Splitter, Static, SubForm, Text, Timer, TipField, TrackBar, TreeView, UpDown

Description

A Group is displayed as an empty box with a border around it whose appearance is defined by the EdgeStyle property. The Caption property defines a string of text that is displayed in the top left border. The default value is an empty vector.

A Group will be resized if its parent Form or Group is resized. It can also be resized directly by the user if its Sizeable property is set to 1. By default, when a Group is resized, it automatically adjusts the size and position of its children to maintain the same proportions within it as before. The resizing of a Group and its children can be controlled using the AutoConf property or by enabling the Configure event (31).


Icon Object

Properties Events Methods

Purpose | This object defines an icon.
Parents | ActiveXControl, CoolBand, Form, Grid, ImageList, ListView, OLEServer, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, StatusBar, SubForm, SysTrayItem, TCPSocket, ToolBar, ToolControl, TrackBar, TreeView, UpDown
Children | Timer

Description

The File property specifies the name of an icon (.ICO) file, or the name of a DLL or EXE file and the identity of the icon within it.

The Style property identifies the size of the icon and must be 'Large' or 'Small'. The former specifies a 32x32 icon and is the default; the latter specifies a 16x16 icon. The size of the icon is not embedded within the icon data, so it is essential to specify Style correctly. Note that a single file may contain both sizes of an icon. Style is only relevant when loading an Icon from file.

If the value of the File property is set by ⎕WS, no immediate action is taken, but the corresponding file may subsequently be read or written using the FileRead or FileWrite methods.

The Bits, Mask and CMap properties define the appearance of the icon. Bits is an integer matrix whose elements define the colours of each pixel in the icon in terms of their (0-origin) indices into CMap. When the icon is displayed on the screen, the way in which these colours combine with those currently displayed on the screen (the background) is specified by Mask. This is a boolean matrix of the same size as Bits. The following table shows how the colour of each resulting pixel is determined.

Bits | Colour | 0 | Colour
Mask | 0 | 1 | 1
Pixel | Colour | Backgroun | New Colour

If an element of Mask is 0, the corresponding element of Bits defines the colour of the resulting pixel that is displayed on the screen. If an element of Mask is 1, the resulting pixel that is displayed on the screen is either the current background colour or is a new colour chosen by MS-Windows to be visible against the background. A non rectangular icon is obtained by setting those elements of Bits and Mask that you want to exclude from the shape to be 0 and 1 respectively.

The size of Bits is restricted by the capabilities of the current display driver. Under MS-Windows 3.1 it must be 32 x 32. Mask must have the same shape as Bits.

An Icon is used by setting the IconObj property of another object to its name or ref.


Image Object

Properties Events Methods

Purpose | Positions bitmaps and icons within an object.
Parents | ActiveXControl, Bitmap, Form, Grid, Group, Metafile, Printer, PropertyPage, Static, StatusBar, SubForm, ToolBar, ToolControl
Children | Timer

Description

The Points property specifies the co-ordinates of one or more points at which the specified graphical objects are to be drawn.

The Picture property specifies the name(s) of Bitmap, Icon or Metafile object(s) that are to be drawn. It may be a simple character vector or a vector of vectors.

To draw a single graphic picture, the Picture property is a simple character vector specifying the name of a Bitmap, Icon or Metafile object. Points is either a 2-element vector or a 1-row, 2-column matrix whose elements specify the y-coordinate and x-coordinate respectively at which the object is to be drawn.

To draw the same picture at several different positions, the Picture property is a simple character vector specifying the name of the Bitmap, Icon or Metafile object. Points is either a 2-column matrix of y-coordinates and x-coordinates, or a nested vector whose first element contains the y-coordinates and whose second element contains the x-coordinates.

To draw several different pictures, the Picture property is a vector of character vectors specifying the names of several Bitmap, Icon and/or Metafile objects. Points is a 2-column matrix or 2-element nested vector as described above.

Setting the EdgeStyle property causes the picture to be surrounded by the appropriate border. For example, setting EdgeStyle to 'Plinth' produces a button-like appearance.

Setting the Size property causes the picture to be scaled to fit within the specified rectangle. It is only necessary to specify Size when an Image is used to draw a Metafile object. For a Bitmap or Icon, Size defaults to the size of the object being drawn.

The Dragable property specifies whether or not the Image can be dragged and dropped using the mouse.

Examples:

First make a Form

      'F' ⎕WC 'Form'

Then make two Bitmaps :

      'YES' ⎕WC 'Bitmap' 'C:\WDYALOG\WS\YES'
      'NO'  ⎕WC 'Bitmap' 'C:\WDYALOG\WS\NO'

Display the "YES" Bitmap at (20,10)

      'F.I' ⎕WC 'Image' (20 10)('Picture' 'YES')

Display the "YES" Bitmap at (20,10) and (20,50)

      'F.I' ⎕WC 'Image' (20(10 50))('Picture' 'YES')

Display the "YES" Bitmap at (20,10) and the "NO" Bitmap at (20,50)

      'F.I' ⎕WC'Image'(20(10 50))('Picture' 'YES' 'NO')


ImageList Object

Properties Events Methods

Purpose | The ImageList object represents a set of bitmapped images.
Parents | ActiveXControl, CoolBand, CoolBar, Form, Group, ListView, OLEServer, PropertyPage, Root, SubForm, TabControl, TCPSocket, ToolBar, ToolControl, TreeView
Children | Bitmap, Cursor, Icon, Timer

Description

An ImageList object represents an array of bitmapped images which are used to depict items in a ListView or TreeView object, or the images in a CoolBar, Menu, TabControl or ToolControl.

Making an ImageList is a 2-step process. First, you create an (empty) ImageList specifying its Size and Masked properties. The former establishes the size of each of the bitmapped images in the array. The Masked property specifies whether the ImageList is to contain masked images (Icons and Cursors) or unmasked images (Bitmaps). The default is 1 (Icons). Note that these properties must be established when the ImageList is created by ⎕WC and may not subsequently be changed using ⎕WS.

Next, you create a series of Bitmap or Icon objects as children of the ImageList. As you make each one, APL adds the corresponding image (or images) to the ImageList object. If the size of each of the Bitmap or Icon objects is equal to the Size of the ImageList itself, each child object corresponds to an image in the ImageList. However, if you add an object whose width is an exact multiple of the width of the ImageList, a corresponding number of images will be added.

For example, if the Size of the ImageList is 16x16 (the default) and you create a child Bitmap of size 16x48, three images (each of size 16x16) will be added to the ImageList. This is more efficient than building the images one-by-one. In other circumstances (where the size of the Bitmap or Icon is not equal to Size of ImageList), the Bitmap or Icon will be scaled to fit.

Note that when making Bitmaps or Icons as children of an ImageList, it is not necessary to name them because they are subsequently referenced only via the ImageIndex and SelImageIndex properties and not by name. The number of images in an ImageList is given by the read-only property, ImageCount.

The MapCols property, which must be specified at the time you create the object, specifies whether or not bitmap colours are remapped to reflect the user’s colour preferences.

An ImageList is associated with a ListView or TreeView object by the ImageListObj property. Each item in the ListView or TreeView is then allocated a specific image in the ImageList by the ImageIndex and SelImageIndex properties.


Label Object

Properties Events Methods

Purpose | Displays static text.
Parents | ActiveXControl, CoolBand, Form, Grid, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

This object displays a text label, a number, a date or a time value.

If FieldType is empty, the Label displays the text defined by its Caption property. If FieldType is 'Numeric', 'LongNumeric', 'Currency', 'Date', 'LongDate', or 'Time' the Label converts and formats the number defined by its Value property and displays this instead. See FieldType property for details.

The Border property determines whether or not the label has a border. A value of 0 means no border (the default). A value of 1 means that a 1-pixel border is drawn around the label.

By default, the value of the EdgeStyle property for a Label is 'None' and the value of BCol is 0 which is normally white, or grey if the parent object has a 3-dimensional appearance. You can change its appearance by setting EdgeStyle and/or BCol to different values.


List Object

Properties Events Methods

Purpose | Allows the user to select one or more items from a list.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The Items property is either a vector of character vectors or a character matrix, and determines the items in the List.

The size and position of the area used to display the list is defined by Size and Posn. If Size is not chosen to represent an exact number of lines of text, the bottom line of text may be clipped.

The Index property specifies or reports the position of Items in the list box as a positive integer value. If Index has the value "n", it means that the "nth" item in Items is displayed on the top line in the list box. However, it is ignored if all the Items fit within the List object. Note that Index can only be set using ⎕WS and not by ⎕WC. The default value for Index is ⎕IO.

The Style property may be 'Single' (the default) or 'Multi'. 'Single' allows only a single item to be selected. 'Multi' allows several items to be chosen. In either case, if the Select event is enabled, it is generated whenever the selection changes. If Style is 'Multi' the List will generate a Select event every time an item is added to the selected list.

Under Windows, you may select or de-select multiple items in a List object by pressing the Ctrl key at the same time as pressing the left mouse button.

The SelItems property is a boolean vector with one element per element or row in Items and indicates which (if any) of the items is currently selected (and highlighted).

The VScroll property determines whether or not the list has a scrollbar. Its possible values are :

¯2 | scrollbar if required
¯1 | scrollbar if required
0 | no scrollbar

Note that data in a List is always scrollable if there are more items than will fit in the box. VScroll determines ONLY whether or not a scrollbar is provided.

The MultiColumn property is a boolean value that specifies whether or not the List object displays its items in columns. The default is 0 which produces a single-column display. If MultiColumn is 1, the List object displays its items in columns whose width is defined by the ColumnWidth property.


ListView Object

Properties Events Methods

Purpose | The ListView object displays a collection of items.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Icon, ImageList, Marker, Poly, Rect, Text, Timer

Description

The ListView object is a window that displays a collection of items, each item consisting of an icon and a label. The ListView provides several ways of arranging items and displaying individual items. For example, additional information about each item can be displayed in columns to the right of the icon and label. An example of the use of a ListView object is the “My Computer” Windows utility.

The Items property is a vector of character vectors that specifies the labels for the items displayed by the ListView. The ImageListObj property specifies the names of two ImageList objects that define two sets of icons; a large icon (32x32 pixel) set and a small icon (16x16 pixel) set. Alternatively, ImageList may be empty (no icons displayed) or contain just the name of a single large icon ImageList. Finally, the ReportInfo property may contain a matrix of information each row of which is associated with an item.

The View property contains a character vector that determines how the items are displayed. It may have one of the following values; 'Icon' (the default), 'SmallIcon', 'List' or 'Report'. When View is 'Icon' or 'SmallIcon', the items are arranged row-wise with large or small icons as appropriate. When View is set to 'List', the items are arranged column-wise using small icons. Examples of 'Icon' and 'List' views are illustrated below.

When View is set to 'Report', the items are displayed in a single column using small icons but with the matrix specified by ReportInfo displayed alongside. In this format, the boolean Header property determines whether or not the object also provides column headings. Its default value is 1. The column headings themselves are specified by the ColTitles property. Their alignment (and the alignment of the data in the columns beneath them) is defined by the ColTitleAlign property. The appearance of the column titles is further controlled by the ColTitle3D property. This is a boolean value (default 1) which specifies whether or not the column titles have a 3-dimensional (plinth) appearance. Header and ColTitle3D may only be set when the object is created using ⎕WC and may not subsequently be changed by ⎕WS.

In 'Report' View, columns may be resized by the user dragging the bars between the titles, or under program control using the SetColSize event. A 'Report' view example is illustrated below.

The DragItems property is boolean and specifies whether or not the user may drag an item from one position to another. Its default value is 1 (dragging is enabled).

The AutoArrange property is boolean and specifies whether or not the items are automatically re-arranged whenever an item is repositioned by the user or moved under program control. Its default value is 0.

The EditLabels is a boolean property (default 0) that determines whether or not the user may edit the labels which are specified by the Items property.

The Style property may be 'Single', which specifies that only one item may be selected at a time, or 'Multi' which permits multiple selections to be made. The default is 'Multi'.

The CheckBoxes property is Boolean and specifies whether or not check boxes are drawn to the left of items. Its default value is 0.

The GridLines property is Boolean and specifies whether or not grid lines are drawn between items. This applies only when View is 'Report'. Its default value is 0.

The FullRowSelect property is Boolean and specifies whether or not the entire row is highlighted to indicate selected items. This applies only when View is 'Report'. Its default value is 0.

The ItemGroups and ItemGroupMetrics properties allow you to display items in groups as illustrated below. However, this feature only applies if XP Look and Feel is enabled.


Locator Object

Properties Events Methods

Purpose | Allows the user to input a point, ellipse, line or rectangle.
Parents | ActiveXControl, Form, Group, PropertyPage, PropertySheet, Root, Static, SubForm, TCPSocket, ToolBar, ToolControl
Children | Timer

Description

This object is used to obtain graphical input from the user. Like a pop-up menu or a MsgBox, the Locator is a modal object whose interaction with the user is initiated by a "local" ⎕DQ. This is terminated when the user releases a mouse button or presses any key other than a cursor movement key, Shift, Ctrl or Alt. It is usual to initiate the ⎕DQ for the Locator from within a callback function attached to a MouseDown (1) Event.

When the "local" ⎕DQ is terminated, a Locator (80) Event is generated. The associated event message contains the new position and size of the Locator, together with how the event was generated (keystroke or mouse button). To obtain the Locator's new position or size, you must enable the event by setting its "action" code to 1, or to the name of a suitable callback function.

The value of the Style property determines the type of locator displayed. It may be 'Point', 'Line', 'Rect', or 'Ellipse'. The default value is 'Rect'. The value of the Sizeable property is 0 or 1 and determines whether or not "rubberbanding" is enabled. Its default value is 1 which turns "rubberbanding" on. The Size property determines the initial size of the Locator when displayed by ⎕DQ. Its default value is (0,0).

If Style is 'Rect' the Locator displays a rectangle. One corner of the rectangle is positioned at Posn. The diagonally opposite corner is positioned at (Posn+Size). If Sizeable is 0, the entire rectangle is dragged as the mouse is moved. If Sizeable is 1, the

corner initially defined by (Posn+Size) is dragged (rubberbanding the rectangle) as the mouse is moved. The rectangle disappears when the operation is terminated. The new position or size of the rectangle is reported in the Locator event message.

If Style is 'Ellipse' the Locator displays an ellipse. One corner of the bounding rectangle of the ellipse is positioned at Posn. The diagonally opposite corner is positioned at (Posn+Size). If Sizeable is 0, the entire ellipse is dragged as the mouse is moved. If Sizeable is 1, the corner of the bounding rectangle initially defined by (Posn+Size) is dragged (rubberbanding the ellipse) as the mouse is moved. The ellipse disappears when the operation is terminated. The new position or size of the bounding rectangle of the ellipse is reported in the Locator event message.

If Style is 'Line' the Locator displays a line drawn between the points defined by Posn and Posn+Size. If Sizeable is 0, the line is dragged with the cursor as the mouse is moved. If Sizeable is 1, the end of the line initially defined by Posn+Size is dragged (rubberbanding the line) as the mouse is moved. The line disappears when the operation is terminated. The new position or size of the line is reported in the Locator event message.

If 'Style' is 'Point', the values of Sizeable and Size are ignored. During the ⎕DQ no visible feedback (other than the cursor) is provided as the user moves the mouse. When the ⎕DQ terminates, the new position of the Locator is reported in the Locator event message.

The Step property is a 2-element integer vector (default value 1 1) that specifies the increments (in pixels) by which the size or position of the Locator changes in the Y and X directions respectively as the user moves the Locator.

The Locator is normally initiated from a MouseDown (1) event, and it is natural to place it at the current cursor position. However, if you are using rubberbanding, you will normally want to have the cursor appear at the end or corner of the Locator that moves. If you start with a non-zero sized Locator, you must set Posn (which defines the fixed end or corner) to the current cursor position minus Size to achieve this effect.


Marker Object

Properties Events Methods

Purpose | A graphical object used to draw polymarkers.
Parents | ActiveXControl, Animation, Bitmap, Button, Combo, ComboEx, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TipField, ToolBar, TrackBar, TreeView, UpDown
Children | Timer

Description

The Points property specifies one or more sets of points at which one or more sets of polymarkers are to be drawn.

The Style property determines the symbol that is drawn at each of a set of points. Marker styles are specified either by numbers which represent the following symbol shapes

0 | . (the default)
1 | +
2 | *
3 | ⎕
4 | ×
5 | ⋄
6 | ∘

or by character vectors containing the names of Bitmap or Icon objects.

The height of each symbol is specified by the value of the Size property. However this applies only to Styles 1-6 and is ignored if Style is 0 or the name of a Bitmap. The colour of each symbol is specified by the FCol property. The default is black.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Marker object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple sets of polymarkers.

Single Set of Polymarkers

For a single set of polymarkers, Points is either a 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y and x co-ordinates respectively.

Style and Size are both simple scalar numbers.

FCol is either a single number representing a standard colour, or a 3-element vector which specifies the marker colour explicitly in terms of RGB values.

First make a Form :

      'F' ⎕WC 'Form'

Draw a point at (y=20, x=10)

      'F.M1' ⎕WC 'Marker' (20 10)

Draw a row of points at (y=20, x=10, 20, ... 90) : (Note scalar extension of y-coordinate)

      'F.M1' ⎕WC 'Marker' (20(10×⍳9))

Draw "+" symbols at each corner of a box :

      Y ← 10 10 50 50
      X ← 10 50 50 10
      'F.M1' ⎕WC 'Marker' (Y X) 1

Ditto, but draw them 10% high :

      'F.M1' ⎕WC 'Marker' (Y X) 1 10

Ditto, but use "*" symbols in green :

      'F.M1' ⎕WC 'Marker' (Y X) 2 10 (0 255 0)

Multiple Sets of Polymarkers

To draw multiple sets of polymarkers with a single name, Points is a nested vector whose items are themselves 2-column matrices or 2-element nested vectors.

Style and Size may be simple scalars specifying a single type and/or size of symbol to be used for all the sets of polymarkers, or vectors specifying different symbols and/or sizes for each set.

FCol may be a single number or a single (enclosed) 3-element vector applying to all the sets of polymarkers. Alternatively, FCol may be a vector whose elements refer to each of the sets of polymarkers in turn. If so, the elements may be single numbers or nested RGB triplets, or a combination of the two.

First make a Form :

      'F' ⎕WC 'Form'

Draw a "⎕" at (10,20) and a "⋄" at (20,20) :

      'F.M1' ⎕WC 'Marker'((1 2⍴10 20)(1 2⍴20 20)) (3 5)

Draw "+" symbols at each corner of one box and "○" symbols at each corner of another

      Y1 X1 ← (10 10 50 50) (10 50 50 10)
      Y2 X2 ← (20 20 40 40) (20 40 40 20)
      'F.M1' ⎕WC 'Marker' ((Y1 X1)(Y2 X2)) (1 6)

Ditto, but draw the "+" symbols with height 2% and the "○" symbols 5% :

      'F.M1' ⎕WC 'Marker' ((Y1 X1)(Y2 X2)) (1 6) (2 5)

Ditto, but draw the "+" symbols in red and the "○" symbols in blue :

      'F.M1' ⎕WC 'Marker' ((Y1 X1)(Y2 X2)) (1 6) (2 5)('FCol' (255 0 0)(0 0 255))


MDIClient Object

Properties Events Methods

Purpose | Implements Multiple Document Interface (MDI) behaviour.
Parents | ActiveXControl, Form, SubForm
Children | Circle, Ellipse, Font, Marker, Poly, Rect, SubForm, Text, Timer

Description

The multiple-document interface (MDI) is a document-oriented interface that is commonly used by word-processors, spreadsheets and other applications that deal with documents. An MDI application allows the user to display multiple documents at the same time, with each document displayed in its own window.

The MDIClient object is a container object that effectively specifies the client area within the parent Form in which the SubForm are displayed. The MDIClient object also imposes special MDI behaviour which is quite different from that where a SubForm is simply the child of another Form.

By default, the MDIClient occupies the entire client area within its parent Form. This is the area within the Form that is not occupied by CoolBars, MenuBars, ToolBars, ToolControls, TabBars ,TabControls and StatusBars. In most applications it is therefore not necessary to specify the position and size of the MDIClient object, although you may do so if you want to reserve additional space in the parent Form for other objects.

Each of the four sides of an MDIClient object is automatically attached to the corresponding side of its parent Form and maintains its position when the parent Form is resized. This means that a default MDIClient always occupies the entire client area of its parent Form, regardless of how the parent is resized.

The appearance of the MDIClient may be changed using its Border, BCol and Picture properties. The EdgeStyle property has no direct effect and is provided only to pass on a value to its child Forms.

The MDIActive and MDIActiveObject properties contain the name of and a ref to the SubForm that currently has the focus. You may set these properties as well as query them.

You can call methods which cause the MDIClient to organise its child SubForms in some way. These methods are as follows:

MDICascade | Causes the MDIClient to organise its child Forms in an overlapping manner.
MDITile | Causes the MDIClient to arrange its child Forms as a row or column.
MDIArrange | Causes the MDIClient to arrange the icons associated with any minimised child Forms in an orderly fashion.


Menu Object

Properties Events Methods

Purpose | This is a pop-up object which allows the user to initiate an action or to select an option using a "menu".
Parents | ActiveXControl, Calendar, CoolBand, CoolBar, DateTimePicker, Form, Grid, Menu, MenuBar, OLEServer, Root, StatusField, SubForm, SysTrayItem, TCPSocket, ToolBar, ToolControl
Children | Bitmap, Menu, MenuItem, Separator, Timer

Description

For a Menu that is owned by a MenuBar or another Menu, the Caption property determines the text string that is displayed as the "choice". The Menu is then popped up by the user clicking on this text. It is automatically popped down when the user chooses an option (by selecting a MenuItem) or cancels the operation (by clicking elsewhere).

If a Menu belongs to a Form, SubForm or is a top-level object, it must be popped up by the application. This is commonly done in response to a MouseDown event. A Menu is popped-up by calling ⎕DQ with only the name of the Menu as its argument. The user may therefore not interact with any other object until a selection is made or until the operation is cancelled. When either occurs, the Menu is automatically popped down and de-activated, and its ⎕DQ terminates.

The Menu object does not have a Size property. Instead, its size is determined automatically by its contents.

If a Menu is owned by a MenuBar or by another Menu, its position within its parent is also calculated automatically, dependent on the order in which other related objects are established. The Posn property may however be used to insert a new Menu into an existing structure. For example, having defined three Menu objects as children of a MenuBar, you can insert a fourth one between the first and the second by specifying its Posn to be 2. Note that the value of Posn for the Menus that were previously second and third will then be reset to 3 and 4 respectively.

If a Menu is a child of a MenuBar which is itself a child of a Form or SubForm, the Align property can be set to 'Right'. This is used to position a single Menu (or MenuItem) at the rightmost end of a MenuBar. This does not apply if the MenuBar is owned by a ToolControl.

The BtnPix property is used to display a picture in a Menu. BtnPix specifies the names of, or refs to, three Bitmap objects. The first Bitmap is displayed when the Menu does not have the focus (normal), the second when it does have the focus (highlighted). The third Bitmap is displayed when the Menu is made inactive (Active property is 0). If Caption is also defined, it is displayed on top of the bitmaps.

If the Menu is a submenu (owned by a Menu), you may set its EdgeStyle property to 'Plinth'. This causes the Menu to take on an appearance that is similar to a pushbutton and be raised when not selected and recessed when selected. Note that to enable 3-dimensional appearance, you must set EdgeStyle to something other than 'None' for all the objects above the Menu in the tree.

EdgeStyle, BtnPix, Font, FCol and BCol do not affect the appearance of a Menu if it is the direct child of a MenuBar. However, the EdgeStyle property must be set to something other than 'None' if you want its children Menu and MenuItem objects to have a 3-dimensional appearance.


MenuBar Object

Properties Events Methods

Purpose | Specifies a horizontal menu bar displayed at the top of a Form.
Parents | ActiveXControl, Form, SubForm, ToolControl
Children | Bitmap, Menu, MenuItem, Separator, Timer

Description

Unless it is made invisible the MenuBar is always available to the user to initiate actions or to select options. A MenuBar has a fixed position and size.

It is possible to have more than one MenuBar associated with the same Form or SubForm, but only one of them should be Visible at any one time.

The following example illustrates how a menu structure can be built up from a MenuBar. For clarity, the example is indented, and the definition of the Event property is omitted.

      'F'           ⎕WC 'Form' 'Menu Example'
      'F.M         '⎕WC 'MenuBar'
      'F.M.FILE'    ⎕WC 'Menu' '&File'
      'F.M.MAT'     ⎕WC 'Menu' '&Materials'
      'F.M.MAT.B'   ⎕WC 'MenuItem' '&Brick'
      'F.M.MAT.C'   ⎕WC 'MenuItem' '&Concrete'
      'F.M.MAT.S'   ⎕WC 'MenuItem' '&Stone'
      'F.M.MAT.SEP' ⎕WC 'Separator'
      'F.M.MAT.W'   ⎕WC 'Menu'     '&Wood'
      'F.M.MAT.W.O' ⎕WC 'MenuItem' '&Oak'
      'F.M.MAT.W.T' ⎕WC 'MenuItem' '&Teak'
      'F.M.MAT.W.M' ⎕WC 'MenuItem' '&Mahogany'

Note that putting a Separator (either Style) in a MenuBar has the effect of breaking the bar vertically, i.e. the next Menu or MenuItem you add will appear on the left-hand side on the line below.

The EdgeStyle property has no effect on the appearance of a MenuBar or of a direct child of a MenuBar. However, if you want the sub-menus to have a 3-dimensional appearance, you must set the EdgeStyle property of the MenuBar to something other than 'None'.

If the MenuBar is owned by a Form that is the parent of an MDIClient, you can set the MDIMenu property to the name of the Menu you wish to nominate as the window menu. This menu will automatically be updated with the Captions of the child SubForm and may be used to select the currently active one.


MenuItem Object

Properties Events Methods

Purpose | This object allows the user to initiate an action or to select an option from a menu.
Parents | Menu, MenuBar
Children | Bitmap, Timer

Description

The Caption property determines the text string that is displayed in its parent as the menu option. The size of a MenuItem is determined by the size of its Caption, or by the size of the largest object (Menu, MenuItem or Separator) with the same parent. The position of the MenuItem is normally determined by the order in which it is created in relation to other objects with the same parent. However, you can use the Posn property to insert a new MenuItem into an existing structure. For example, having defined three MenuItem objects as children of a Menu, you can insert a fourth one between the first and the second by specifying its Posn to be 2. Note that the value of Posn for the MenuItems that were previously second and third will then be reset to 3 and 4 respectively.

The Style property may be 'Check' (the default) or 'Radio'. Style determines the type of graphic displayed alongside the Caption if the MenuItem is checked.

The Checked property is a single number with the value 0 or 1. 0 means not checked (the default), 1 means checked and a tick mark or radio dot is placed alongside its Caption. This property is frequently used to indicate which of a choice of options is currently set.

If a MenuItem is a child of a MenuBar which is itself a child of a Form or SubForm, the Align property can be set to 'Right'. This is used to position a single MenuItem (or Menu) at the rightmost end of a MenuBar. This does not apply if the MenuBar is owned by a ToolControl.

If you set the EdgeStyle property to 'Plinth', the MenuItem will take on an appearance that is similar to a pushbutton and be raised when not selected and recessed when selected. Note that to enable 3-dimensional appearance, you must set EdgeStyle to something other than 'None' for all the objects above the MenuItem in the tree.

The BtnPix property is used to display a picture in a MenuItem. BtnPix specifies the names of, or refs to, three Bitmap objects. The first Bitmap is displayed when the MenuItem does not have the focus (normal), the second when it does have the focus (highlighted). The third Bitmap is displayed when the MenuItem is made inactive (Active property is 0). If Caption is also defined, it is displayed on top of the bitmaps.

Alternatively, you may display an image alongside the Caption using the ImageIndex property. This selects a picture from the ImageList associated with the ImageListObj property of the parent Menu.

EdgeStyle, BtnPix, FontObj, FCol and BCol are not effective if the MenuItem is the direct child of a MenuBar.

A MenuItem generates a Select event (if enabled) when the user chooses it.


Metafile Object

Properties Events Methods

Purpose | This object represents a picture in Windows Metafile format.
Parents | ActiveXControl, Bitmap, CoolBand, Form, Group, OLEServer, Printer, PropertyPage, PropertySheet, Root, Static, SubForm, TCPSocket, ToolBar, ToolControl
Children | Circle, Ellipse, Font, Image, Marker, Poly, Rect, Text, Timer

Description

The Windows Metafile is a mechanism for representing a picture in terms of a collection of graphical components. Windows Metafiles are distributed in special files (.WMF) from which they are loaded into memory for use by an application. Once loaded a Metafile is a Windows “resource” that can be used in a variety of ways. The Metafile object represents this resource.

The File property specifies the name of a .WMF file from which the Metafile is to be loaded or to which it is to be saved. If you specify File with ⎕WC the Metafile object is loaded from it. If you specify File with ⎕WS no action takes place until you instruct the Metafile object to re-initialise itself from the file or to save itself to the file. These operations are performed using the FileRead and FileWrite methods. If you omit the File property in the argument to ⎕WC or if you specify a null vector, the Metafile object is initially empty. The following example loads the picture defined by the GOLF.WMF Metafile that is distributed with Microsoft Office.

      'GOLF' ⎕WC 'Metafile' 'C:\MSOFFICE\CLIPART\GOLF'

Whether or not the Metafile object is initialised from a file, you can add graphical components to it by creating child objects. However the Metafile behaves like a Bitmap object in that its children cannot be modified using ⎕WS nor can they be removed using ⎕EX. The components of a Metafile that has been initialised from a .WMF file also cannot be referenced in any way. It is therefore recommended that you use unnamed objects when you create the graphical components of a Metafile. The following statements create an empty Metafile called MF and then draw a line and circle in it.

      'MF' ⎕WC 'Metafile'
      'MF.' ⎕WC 'Poly' (50(10 90))
      'MF.' ⎕WC 'Circle' (50 50) 30

Like the Bitmap, Icon, Font and Cursor objects, the Metafile is a resource that is not visible until it is used. This is done by setting the Picture property of another object (Form, Image, Static or SubForm) to the name of, or ref to, the Metafile object. For example, to display the Metafile MF in a Form, you could type :

      'TEST' ⎕WC 'FORM' ('Picture' 'MF')

You can also copy a Metafile object to the Windows Clipboard from where it can be pasted into another application. This is done by creating a Clipboard object and then setting its MetafileObj property to the name of the Metafile object to be exported. For example :

      'CL' ⎕WC 'Clipboard'
      'CL' ⎕WS 'MetafileObj' 'MF'

The FileWrite method may be used to save a Metafile object on a file. The following statements save the Metafile MF in a file called TEST.WMF.

      MF.File←TEST'
      MF.FileWrite

The Size property determines the granularity of the Metafile. Its default value is the size of its parent. If you intend to replay the Metafile at higher resolution, you should set Size accordingly.

The RealSize property specifies the suggested size of a Metafile in units of 0.01mm. Setting RealSize has the effect of making the Metafile placeable. Certain programs (such as Word for Windows) only support placeable metafiles.


MsgBox Object

Properties Events Methods

Purpose | Provides a "modal" dialog box for displaying messages, errors, warnings and other information. The dialog box has a title, one or more lines of text, and up to three buttons.
Parents | ActiveXControl, Calendar, CoolBand, DateTimePicker, Form, Grid, OLEServer, PropertyPage, PropertySheet, Root, SubForm, TCPSocket, ToolBar, ToolControl
Children | Timer

Description

The Caption property determines the text displayed in the object's title bar.

The Text property determines the text to be displayed as the message.

The Style property determines the type of icon which is displayed. This is a character vector with one of the following values :

'Msg' | no icon (the default)
'Info' | information message icon
'Query' | query (question) icon
'Warn' | warning icon
'Error' | critical error icon

The Btns property determines the set of buttons to be displayed. It is a simple vector (one button) or a matrix with up to 3 rows, or a vector of up to 3 character vectors specifying the captions for up to 3 buttons. MS-Windows restricts you to a fixed set of button captions which are described below. However, the property has been designed more generally to be useful under different GUIs and perhaps later revisions of Windows. The buttons are arranged along the bottom of the dialog box in the order specified.

The Btns property may specify one of six sets of buttons as follows.

  • 'OK'
  • 'OK' 'CANCEL'
  • 'RETRY' 'CANCEL'
  • 'YES' 'NO'
  • 'YES' 'NO' 'CANCEL'
  • 'ABORT' 'RETRY' 'IGNORE'

If any other combination is specified, ⎕WC and ⎕WS will report a DOMAIN ERROR. The names of the buttons are however case-insensitive, so the system will accept 'ok', 'Ok', 'oK' or 'OK'. If Btns is not specified, it assumes a default according to Style as follows :

Style | Btns
'Msg' or 'Info' | 'OK'
'Warn' or 'Error' | 'OK' 'CANCEL'
'Query' | 'YES' 'NO'

The Default property may be used to determine which of the buttons is the "default" button, i.e. the one which initially has the focus and is "selected" when the user presses the Enter key. It has the value 1, 2 or 3. If Default is not specified, the first button is the "default" button. Note that if the user switches focus to another button and presses Enter, this action selects the button with the focus.

Like a pop-up (floating) Menu, the MsgBox object is unusual in that it is strictly modal. It is created by ⎕WC in the normal way, but at that stage is invisible and inactive. It is activated ONLY when ⎕DQ is called with the name of the MsgBox as the argument. When this is done, the MsgBox object pops up and is activated. Because there is no other object specified in the argument to ⎕DQ, all other objects are de-activated. The only thing that the user can do (within the APL application) is to press one of the buttons in the MsgBox. When this happens, the MsgBox automatically pops down, the callback function (if any) is fired, and then ⎕DQ terminates.

Notice that the position and size of the MsgBox are determined by Windows and are fixed, although the MsgBox may be moved by the user after it has been displayed.

The MsgBox object generates one of three events; MsgBtn1 (61), MsgBtn2 (62), or MsgBtn3 (63) depending upon which button is pressed.

      Caption←'Default MsgBox' ⋄ Text←'Hello World'
      'Msg' ⎕WC 'MsgBox' Caption Text ⋄ ⎕DQ 'Msg'

      Caption←'Information MsgBox' ⋄ Text←'Update Completed'
      'Msg' ⎕WC 'MsgBox' Caption Text 'Info' ⋄ ⎕DQ 'Msg'

      Caption←'Query MsgBox' ⋄ Text←'Save Changes'
      'Msg' ⎕WC 'MsgBox' Caption Text 'Query' ⋄ ⎕DQ 'Msg'

      Caption←'Warning MsgBox'
      Text←'Calculations will take 10 minutes'
      'Msg' ⎕WC 'MsgBox' Caption Text 'Warn' ⋄ ⎕DQ 'Msg'

      Caption←'Error MsgBox'
      Text←'Data out of range'
      'Msg' ⎕WC 'MsgBox' Caption Text 'Error' ⋄ ⎕DQ 'Msg'

      Caption←'Custom MsgBox'
      Text←⊂'You can have a multi-line'
      Text,←⊂'message if you want one'
      B←'ABORT' 'RETRY' 'IGNORE'
      'Msg' ⎕WC 'MsgBox' Caption Text 'Info' B ⋄ ⎕DQ 'Msg'


NETClient Object

Purpose | The NetClient object represents an instance of a Microsoft .Net class.
Parents | NetClient, NetType, Root
Children | NetClient, Timer

Description

The NetClient object represents an instance of a .Net class.

Normally, you create a NetClient object using the New method. For example:

      ⎕USING ←'System'
      DT1←DateTime.New 2002 4 30
      DT1.Type
NetClient

If, for any reason, you are unable to use the New method, you may create a NetClient object using ⎕WC. In this case, the ClassName property specifies the full name of the .Net class, and the ConstructorArgs property specifies the arguments for the constructor function if required.

      ⎕USING ←'System'
      'DT2'⎕WC'NETCLIENT' 'System.DateTime'(1949 4 30)
      DT2.(Type ClassName ConstructorArgs)
 NetClient  System.DateTime  1949 4 30


NetType Object

Properties Events Methods

Purpose | The NetType object is used to export a namespace as a Microsoft.Net class.
Parents | NetType, Root
Children | Bitmap, NetClient, NetType, TCPSocket, Timer

Description

The NetType object allows you to export an APL namespace as a .Net class that can be accessed by any conforming .Net client application.

The BaseClass property specifies the name of the .Net class from which the specified NetType object inherits. The default is System.Object.

When you create a NetType object, the name of its parent namespace specifies the name of the corresponding Microsoft .Net Namespace to which the NetType class belongs. If the NetType is created as a child of root, the corresponding Microsoft .Net Namespace is unnamed.


OCXClass Object

Properties Events Methods

Purpose | This object provides access to OLE (ActiveX) Controls.
Parents | ActiveXControl, CoolBand, Form, Grid, OLEServer, PropertyPage, Root, SubForm, TCPSocket, ToolBar, ToolControl
Children | (None)

Description

This object loads an OLE Control into memory and defines a new class of object associated with it. The name of the new class is the name specified by the left argument of ⎕WC You may create an instance of the newly defined class using the name you assigned to the OCXClass object as the Type property.

Once you have defined a new OCXClass, the properties, events and methods it supports may be obtained from its PropList, EventList and MethodList properties. These are the properties, events and methods defined for the OLE control by its author.

The QueueEvents property determines how events reported by the ActiveX control are handled.

To find out how to use the OLE control, you must consult the appropriate documentation. However, a great deal of information about it can be obtained using the GetPropertyInfo, GetEventInfo, and GetMethodInfo methods.


OLEClient Object

Properties Methods

Purpose | The OLEClient object provides access to an OLE Automation Server
Parents | ActiveXControl, CoolBand, Form, OLEClient, OLEServer, Root, TCPSocket
Children | Form, OLEClient, TCPSocket, Timer

Description

The OLEClient object allows you to control OLE Servers, which may be written in a variety of different programming languages, including Dyalog APL itself.

The ClassName property specifies the name of the OLE object to which the new object named by the left argument of ⎕WC is to be connected. A list of all the OLE Server objects installed on your system may be obtained from the OLEServers property of Root. ClassName may only be specified by ⎕WC.

Alternatively, the OLE object may be identified by the ClassID property.

The AutoBrowse property and Browse method are no longer relevant and are ignored. They are retained only for backwards compatibility with previous versions of Dyalog APL.

Note that the PropList and MethodList properties of an OLEClient instance contain the names of the properties and methods exposed by the corresponding OLE Object in addition to the generic properties and methods of the OLEClient class.

If you call an OLE method with an invalid parameter, set a read-only property, or assign it an invalid value, the LastError property of the OLEClient and Root objects will contain error information generated by OLE.


OLEServer Object

Properties Events Methods

Purpose | The OLEServer object is used to establish a namespace as an OLE Server object that can be used by an OLE Automation client.
Parents | ActiveXControl, Form, OLEServer, Root
Children | Bitmap, BrowseBox, Clipboard, Cursor, FileBox, Font, Form, Icon, ImageList, Menu, Metafile, MsgBox, OCXClass, OLEClient, OLEServer, Printer, PropertySheet, TCPSocket, Timer, TipField

Description

The OLEServer object allows you to export an APL namespace so that its functions and variables become directly accessible to an OLE Automation client application such as Microsoft Visual Basic or Microsoft Excel.

An OLEServer may be saved as an out-of-process OLE server (in a workspace) or as an in-process OLE server (in a DLL). See Interface Guide for details.

When you create an OLEServer object, APL allocates various OLE attributes to it. For example, the CLSID, which uniquely identifies the object, is assigned at this stage. However, the object is not actually registered until you execute )SAVE.

Registration involves updating the Windows registry with information about the object itself, such as its name, the command required to obtain it and so forth. Registration also records information about all of the functions and variables that your object exposes. Registration is therefore a non-trivial operation and should be delayed until the point when you are ready to test your OLEServer.

You may create an empty OLEServer object and then define functions and variables within it. Alternatively, you may convert an existing namespace which is already populated with functions and variables. The latter method is recommended as it implies less registry activity during the development of the object.

The ExportedFns and ExportedVars properties specify the names of the functions and variables that will be exposed by the object to OLE clients.

The RunMode property is a character vector that specifies how the object serves multiple clients. It may be 'MultiUse' (the default), 'SingleUse', or 'RunningObject'.

The ShowSession property is either 0 (the default) or 1 and specifies whether or not the APL Session window is displayed when the first instance of the OLEServer is created.

RunMode and ShowSession apply only to out-of-process OLEServers.


Poly Object

Properties Events Methods

Purpose | A graphical object used to draw lines, polygons, and filled areas.
Parents | ActiveXControl, Animation, Bitmap, Button, Combo, ComboEx, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TipField, ToolBar, TrackBar, TreeView, UpDown
Children | Timer

Description

The Points property specifies one or more sets of co-ordinates through which one or more lines are drawn. The resulting polygon(s) may also be filled.

LStyle and LWidth define the style and width of the lines. FCol and BCol determine the colour of the lines.

FStyle specifies whether or not the polygon(s) are filled, and if so, how. For a solid fill (FStyle 0), FillCol defines the fill colour used. For a pattern fill (FStyle 1-6) FillCol defines the colour of the hatch lines and BCol the colour of the areas between them.

Note that if you specify filling, you do not have to define a closed polygon. The first and last points will automatically be joined for you if necessary.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Poly object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple polylines or polygons.

Single Polyline or Polygon

For a single polyline or polygon, Points is either a 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y and x co-ordinates respectively.

LStyle and LWidth are both simple scalar numbers.

FStyle is either a single number specifying a standard fill pattern, or the name of a Bitmap object which is to be used as a "brush" to fill the polygon.

FCol, BCol and FillCol are each either single numbers representing standard colours, or 3-element vectors which specify colours explicitly in terms of their RGB values.

First make a Form :

      'F' ⎕WC 'Form'

Draw a single line from (y=20, x=10) to (y=30, x=50)

      'F.L1' ⎕WC 'Poly' ((20 30)(10 50))

or

      L ← 2 2⍴20 10 30 50
      'F.L1' ⎕WC 'Poly' L

Draw a horizontal line from (y=20, x=10) to (y=20, x=50). Note scalar extension of y-coordinate.

      'F.L1' ⎕WC 'Poly' (20(10 50))

Draw an empty box in green :

      Y ← 10 10 50 50 10
      X ← 10 50 50 10 10
      'F.L1' ⎕WC 'Poly' (Y X) (0 255 0)

Ditto, using a green/blue dashed line (LStyle 1) :

      'F.L1' ⎕WC 'Poly' (Y X) (0 255 0)(0 0 255) 1

Draw a red filled rectangle with a black border 5 pixels wide :

      'F.L1' ⎕WC 'Poly' (Y X) (0 0 0) ('LWidth' 5)('FStyle' 0)('FillCol' 255 0 0)

Multiple Polylines/Polygons

To draw a set of polylines or polygons with a single name, Points is a nested vector whose items are themselves 2-column matrices or 2-element nested vectors.

LStyle and LWidth may each be simple scalar values (applying to all the polylines) or simple vectors whose elements refer to each of the corresponding polylines in turn.

FStyle may be a simple scalar numeric or a simple character vector (Bitmap name) applying to all polylines, or a vector whose elements refer to each of the corresponding polylines in turn.

Similarly, FCol, BCol and FillCol may each be single numbers or a single (enclosed) 3-element vector applying to all the polylines. Alternatively, these properties may contain vectors whose elements refer to each of the polylines in turn. If so, their elements may be single numbers or nested RGB triplets, or a combination of the two.

First make a Form :

      'F' ⎕WC 'Form'

Draw two concentric triangles :

      BY ← 10 10 50 10
      BX ← 15 65 40 15
      RY ← 15 15 40 15
      RX ← 25 55 40 25
      'F.L1' ⎕WC 'Poly' ((BY BX)(RY RX))

Or, using matrices :

      BT ← BY,[1.5]BX
      RT ← RY,[1.5]RX
      'F.L1' ⎕WC 'Poly' (BT RT)

Ditto, but draw the first blue, the second red :

      'F.L1' ⎕WC 'Poly' (BT RT) ((0 0 255)(255 0 0))

Ditto, but make the lines 3 pixels wide :

      'F.L1' ⎕WC 'Poly' (BT RT) ((0 0 255)(255 0 0))('LWidth' 3)

Ditto, but make the line widths 3 and 6 pixels respectively :

      'F.L1' ⎕WC 'Poly' (BT RT) ((0 0 255)(255 0 0))('LWidth' 3 6)

Draw the first hollow, but fill the second in green :

      'F.L1' ⎕WC 'Poly' (BT RT) ('FStyle' ¯1 0)('FillCol' (⊂0 255 0))


Printer Object

Properties Events Methods

Purpose | To provide printer output.
Parents | ActiveXControl, CoolBand, Form, OLEServer, PropertyPage, PropertySheet, Root, TCPSocket
Children | Bitmap, Circle, Ellipse, Font, Icon, Image, Marker, Metafile, Poly, Rect, Text, Timer

Description

The PName property is a character vector which specifies the name of an installed printer and the device to which it is attached. The name and device are separated by a comma (,). All valid values of PName can be obtained from the PrintList property of the Root object.

If not specified, the default value of PName is (⊃'.' ⎕WG 'PrintList').

The DevCaps property reports the size of the printable area of the page in pixels (dots) and in millimetres. It also reports the number of colours available. This is 2 on a monochrome printer (black and white), although grey scales may be available.

The FontList property provides a list of fonts that are applicable and includes TrueType and printer fonts. This list is typically different from that obtained from the FontList property on the Root object which lists those fonts that apply to the screen.

The Orientation property specifies the orientation of the page and may be either 'Portrait' or 'Landscape'.

The graphics objects listed above may be printed in much the same way as they may be displayed on a Form or Static. The differences are :

Once an object has been created, it will be printed, even if its name is subsequently expunged.

An object does not replace an existing one which has the same name.

The act of changing one or more properties of a named object causes the object to be printed a second time. For example, changing the Posn of an object will print it again at a different place.

In general it is recommended that you use unnamed objects for printing.

The Printer object five methods :

Name | Event | Description
Print | 100 | Sends output to print spooler
Setup | 101 | Displays Printer Set-up dialog box
NewPage | 102 | Throws a new page
Abort | 103 | Aborts the print job
RTFPrintSetup | 460 | Displays Printer Set-up dialog box

Examples:

Start a print job on the default printer

      'PR1' ⎕WC 'Printer'

Write a centred heading at the top of the page using a proportional font

      'PR1.' ⎕WC 'Text' 'Report Title' (0 50)('HAlign' 1) ('FontObj' 'Roman' 64)

Draw a line across the page, 2 pixels wide

      'PR1.' ⎕WC 'Poly' (2(0 100)) ('LWidth' 2)

Print a character matrix. Note that a fixed width font is used.

      REPORT ← 'I6' ⎕FMT ?20 6⍴1000
      'PR1.' ⎕WC 'Text' REPORT (10 0)('FontObj' 'DyalogAPL')

Throw a new page

      PR1.NewPage

Spool output

      ⎕EX 'PR1'


ProgressBar Object

Properties Events Methods

Purpose | The ProgressBar object is used to indicate the progress of a lengthy operation.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, StatusBar, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Icon, Marker, Poly, Rect, Text, Timer

Description

The ProgressBar object is a window that an application can use to indicate the progress of a lengthy operation. It consists of a rectangle that is gradually filled, from left to right, with the system highlight colour as an operation progresses.

The range of a ProgressBar is specified by the Limits property. This is a 2-element integer vector defining its minimum and maximum values. The position of the filled rectangle is specified by the Thumb property. You can update the ProgressBar by using ⎕WS to set the value of the Thumb directly, or by generating a ProgressStep event. The latter causes the Thumb to be updated by the value of the Step property.

If you attempt to set the Thumb to a value greater than its maximum value (using either method) the behaviour depends upon the value of the Wrap property which is boolean and has a default value of 1. If Wrap is 1, the value obtained when you set the Thumb property is given by the expression:

      LIMITS[1]+(1+LIMITS[2]⍎LIMITS[1])|THUMB⍎LIMITS[1]

where THUMB is the value to which you set the Thumb property and LIMITS is the value of the Limits property. This causes the highlit rectangle to begin filling again from the left.

There are two basic ways that you can use a ProgressBar. One is to fill the bar just once, doing so as evenly as possible and ensuring that the completion of the process coincides with the complete filling of the bar. This gives the user useful (and hopefully accurate) information as to the progress of the operation. However, some processes have an indeterminate duration (for example, an iterative one) and you may choose to use the ProgressBar simply to indicate that the operation is continuing.

Here is a code fragment illustrating how you can update a ProgressBar evenly. (DO_SOMETHING represents some processing that is performed N times in a loop):

      'F.P'⎕WC'ProgressBar' ('Limits' 0 N)
      I←0
     Loop:→(N<I←I+1)/End
      DO_SOMETHING I
      'F.P' ⎕WS 'Thumb' I
      →Loop
     End:

and the same thing using the ProgressStep method:

      'F.P'⎕WC'ProgressBar' ('Limits' 0 N) ('Step' 1)
      I←0
     Loop:→(N<I←I+1)/End
      DO_SOMETHING I
      F.P.ProgressStep
      →Loop
     End:

Alternatively, you can update a ProgressBar via a Timer.


PropertyPage Object

Properties Events Methods

Purpose | The PropertyPage object represents a single page in a PropertySheet.
Parents | PropertySheet
Children | Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, Metafile, MsgBox, NetControl, OCXClass, Poly, Printer, ProgressBar, Rect, RichEdit, Scroll, SM, Spinner, Splitter, Static, SubForm, TCPSocket, Text, Timer, TipField, TrackBar, TreeView, UpDown

Description

The PropertyPage object represents a single page within a PropertySheet.

The Posn and Size properties are read-only properties determined by the parent PropertySheet and may not be changed using ⎕WC or ⎕WS.

The HasHelp property is either 1 (the default) or 0. If the parent PropertySheet has a “Help” button (determined by its own HasHelp property) this property determines whether or not the Help button is active when the PropertyPage is the current page. If the HasHelp property of a PropertyPage is 0, the Help button on the parent PropertySheet will be temporarily disabled when that PropertyPage is displayed.

The PropertyPage object generates a PageActivate event when it becomes the current page and a PageDeActivate event when another page is selected. These events may not be disabled by a callback function.

If the user presses the Cancel button, the current PropertyPage generates a PageCancel event. This is followed by a Close event which is reported by the parent PropertySheet.

Other properties and behaviour depend upon the Style of the parent PropertySheet which may be 'Standard' or 'Wizard'

Standard Behaviour

In a Standard PropertySheet, the Caption property of each PropertyPage specifies the text that is written in its tab.

PropertyPage objects owned by a Standard PropertySheet generate PageCancel, PageApply and PageHelp events. These events are all caused by the user pressing the corresponding button in the parent PropertySheet.

Conventionally, the Apply button is initially inactive. When the user changes an item on any of the PropertyPages, the Apply button immediately becomes active. When the user clicks the Apply button, the application responds (normally by changing the appropriate properties) and then the Apply button becomes inactive once again. This process is controlled as follows.

The Changed property is a boolean value that determines whether or not a PropertyPage is marked as having been in any way altered. The Apply button is active if the value of the Changed property for any of the PropertyPages is 1, and is inactive otherwise

Initially, the value of the Changed property for all of the PropertyPages is 0 and the Apply button is therefore inactive. If the user alters a control on a PropertyPage, by, for example typing into an Edit object or changing the State of a Radio Button, the PropertyPage immediately generates a PageChanged event with the parameter 1. The default processing for this event is to set the Changed property of the PropertySheet (to 1). This in turn activates the “Apply” button. If you return 0 from a callback on the PageChanged event, the Changed property remains 0 and the Apply button remains inactive.

When the user clicks the Apply button, each of the PropertyPages whose Changed flag is currently set to 1 generates a PageApply event. The default processing for this event is to generate a PageChanged event with the parameter 0. This is turn resets the Changed property of the PropertyPage to 0. Once all of the Changed flags have been reset, the Apply button becomes inactive. If you return 0 from a callback on any of the PageChanged events, the Changed property for the corresponding PropertyPage remains 1 and the Apply button remains active.

You may control the value of the Changed property using ⎕WS or by calling PageChanged as a method. In all cases, the Apply button is active if the value of Changed on any PropertyPage is 1, and inactive otherwise.

Wizard Behaviour

If the PropertyPage is owned by a Wizard PropertySheet, its Caption property specifies the text that appears in the title bar of the PropertySheet window when the PropertyPage is the current page. Note that a Wizard PropertySheet ignores its own Caption property.

There are effectively 3 page changing buttons on a Wizard PropertySheet, named Back, Next and Finish. The Next and Finish buttons actually occupy the same position and are mutually exclusive. The captions on the buttons are language-dependent.

Conventionally, the buttons change according to which of the PropertyPages is currently displayed. If the first one is displayed, the Next button is active but the Back button is inactive. When a middle page is displayed, both the Next and Back buttons are active. When the last page is displayed, the caption on the Next button changes to Finish. However, in some applications, the Back button may be disabled to prevent the user returning to a previous page.

When the user clicks the Back or Next button, the PropertyPage generates a PageBack or PageNext event followed by a PageDeactivate event. The new PropertyPage then generates a PageActivate event. These are followed by a SetWizard event which is generated by the parent PropertySheet and actually controls the state of the buttons. When the user clicks the Finish button, the PropertyPage generates a PageFinish event alone. All of these events reported by the PropertyPage are reported for information only. Returning 0 from a callback function has no effect. You may however control the buttons using the SetWizard event,


PropertySheet Object

Properties Events Methods

Purpose | The PropertySheet object represents a standard multi-page dialog box.
Parents | ActiveXControl, Form, OLEServer, Root, SubForm, TCPSocket
Children | Bitmap, BrowseBox, Circle, Clipboard, Cursor, Ellipse, FileBox, Font, Icon, Locator, Marker, Metafile, MsgBox, Poly, Printer, PropertyPage, Rect, Text, Timer, TipField

Description

There are two different kinds of PropertySheet which you select using the Style property. This may only be set when the PropertySheet is created using ⎕WC and Style may not subsequently be changed using ⎕WS.

If Style is Standard (the default), the PropertySheet displays a set of pages (each represented by a PropertyPage) as a set of tabbed forms as illustrated below. The user selects the current page by clicking on the appropriate tab. This Style allows the user to select any page at any time and does not oblige the user to visit any but the first page you choose to display. This Style is useful for displaying groups of options or settings that the user may change.

If Style is Wizard, the PropertySheet displays its pages in succession starting with the first. The user steps from one to another using the Next and Back buttons and may be forced to visit all the pages in a prescribed order. This Style is useful for data entry or for asking the user to make a series of choices.

The Caption property specifies the text written in the window title bar, but only applies if the Style is Standard. The title bar text of a Wizard PropertySheet is specified by the Caption of the current PropertyPage.

The HasApply and HasHelp properties are boolean and specify whether or not the PropertySheet has “Apply” and “Help” buttons respectively. These properties may only be set when the object is created using ⎕WC. They both have default values of 1.

The FontObj and EdgeStyle properties have no effect on the appearance of the PropertySheet itself, but may be used to define the default appearance of its children.


Rect Object

Properties Events Methods

Purpose | A graphical object used to draw boxes.
Parents | ActiveXControl, Animation, Bitmap, Button, Combo, ComboEx, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TipField, ToolBar, TrackBar, TreeView, UpDown
Children | Timer

Description

The Points property specifies one or more sets of co-ordinates which define the position(s) of one or more rectangles. The position of a rectangle is defined to be the position of the corner that is nearest to the origin of its parent. The default is therefore its top-left corner. The Size property specifies the height and width of each rectangle, measuring away from the origin.

The Radius property specifies the curvature of the corners of the rectangle.

LStyle and LWidth define the style and width of the lines used to draw the boundaries of the rectangle(s). FCol and BCol determine the colour of the lines.

FStyle specifies whether or not the rectangle(s) are filled, and if so, how. For a solid fill (FStyle 0), FillCol defines the fill colour used. For a pattern fill (FStyle 1-6) FillCol defines the colour of the hatch lines and BCol the colour of the spaces between them.

The EdgeStyle property may specify a 3-dimensional effect. If so, the boundary line around the rectangle is replaced by a border designed to achieve the desired effect.

The value of Dragable determines whether or not the object can be dragged. The value of AutoConf determines whether or not the Rect object is resized when its parent is resized.

The structure of the property values is best considered separately for single and multiple rectangles :

Single Rectangle

For a single rectangle, Points is either a 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y and x co-ordinates respectively.

Size is a simple 2-element vector whose elements specify the height and width of the rectangle respectively.

Radius is a 2-element vector which specifies the major (y-axis) and minor (x-axis) radii of an ellipse used to draw the corners of the rectangle. Its default value is (0 0) which yields right-angled corners.

LStyle and LWidth are both simple scalar numbers.

FStyle is either a single number specifying a standard fill pattern, or the name of a Bitmap object which is to be used as a "brush" to fill the rectangle.

FCol, BCol and FillCol are each either single numbers representing standard colours, or 3-element vectors which specify colours explicitly in terms of their RGB values.

First make a Form :

      'F' ⎕WC 'Form'

Draw a single rectangle at (y=10, x=5) with height=30, width=50 :

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)

Ditto with rounded corners (radii 10) :

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)(10 10)

Ditto, but use a red line :

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)(10 10)(255 0 0)

Ditto, but fill in green

      'F.R1' ⎕WC 'Rect' (10 5)(30 50)(10 10)(255 0 0) ('FStyle' 0)(0 255 0)

Multiple Rectangles

To draw a set of rectangles with a single name, Points may be a simple 2-element vector (specifying the location of all the rectangles), or a 2-column matrix whose first column specifies their y-coordinates and whose second column specifies their x-coordinates, or a 2-element nested vector whose first element specifies their y-coordinate(s) and whose second element specifies their x-coordinate(s).

Likewise, Size may be a simple 2-element vector (applying to all the rectangles), or a 2-column matrix whose first column specifies their heights and whose second column specifies their widths, or a 2-element nested vector whose first element specifies their height(s) and whose second element specifies their width(s).

Radius may be a simple 2-element vector (applying to all the rectangles), or a 2-column matrix whose first column specifies major radii and whose second column specifies minor radii, or a 2-element nested vector whose first element specifies major radii and whose second element specifies minor radii.

LStyle and LWidth may each be simple scalar values (applying to all the rectangles) or simple vectors whose elements refer to each of the corresponding rectangles in turn.

FStyle may be a simple scalar numeric or a simple character vector (Bitmap name) applying to all rectangles, or a vector whose elements refer to each of the corresponding rectangles in turn.

Similarly, FCol, BCol and FillCol may each be single numbers or a single (enclosed) 3-element vector applying to all the rectangles. Alternatively, these properties may contain vectors whose elements refer to each of the rectangles in turn. If so, their elements may be single numbers or nested RGB triplets, or a combination of the two.

First make a Form :

      'F' ⎕WC 'Form'

Draw two rectangles at (y=5, x=10) and (y=5, x=60) each of (height=40, width=10)

      'F.R1' ⎕WC 'Rect' ((5 5)(10 60)) (40 10)

Ditto, using scalar extension for (y=5) :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10)

Ditto, but draw the first with (height=40, width=30) and the second with (height=20, width=10) :

      'F.R1' ⎕WC 'Rect' (5(10 60)) ((40 20)(30 10))

Draw two rectangles at (y=5, x=10) and (y=5, x=60) each of (height=40, width=10) and with rounded corners of radii (10,10) :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10) (10 10)

Ditto, using a green line for both :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10) (10 10)(⊂0 255 0)

Ditto, but using red and blue lines respectively :

      'F.R1' ⎕WC 'Rect' (5(10 60)) (40 10) (10 10)((255 0 0)(0 0 255))


RichEdit Object

Properties Events Methods

Purpose | The RichEdit object is a multi-line text editor that provides a wide range of word-processing capabilities.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Icon, Marker, Poly, Rect, Text, Timer

Description

A RichEdit object is a window in which the user can enter and edit text. The text can be assigned character and paragraph formatting. Although the corresponding control can include embedded OLE objects, this is not yet supported by Dyalog APL.

The RichEdit object provides a programming interface for formatting text. However, your application must implement any user interface components necessary to make formatting operations available to the user. For example, your program can set the colour and font of a particular block of text, but the RichEdit itself provides no facilities for the user to do this directly. It is up to you to provide these.

The File property specifies the name of a file associated with the object. Data in the file is assumed to be in rich text format, and the default extension for the file is .RTF. You can read the file into the object by calling FileRead and you can write the contents to the file by calling FileWrite. You can also print the contents of the object by calling RTFPrint.

The Text property may be used to set or retrieve the text of the RichEdit, but ignores formatting information.

The RTFText property may be used to set or retrieve the contents of the RichEdit, including text and formatting.

The PageWidth property defines the width of the text within the object. Text entered into the object is automatically wrapped according to PageWidth. This property also defines the width when the text is printed.

You can set the default character format or the format of a particular block of text using the CharFormat property. If there is no selection, setting CharFormat defines the default character format that applies at the current insertion position and establishes the appearance of all of the text (font, colour, size etc.) that the user subsequently enters here. If there is a selection, setting CharFormat sets the character format for the selected block of text.

The WordFormat property is similar to CharFormat except that is sets the format for the selected word(s) or, if there is no selection, for the word containing the insertion point.

The Paraformat property defines the paragraph formatting which includes alignment, indentation and the location of tab stops. When you set Paraformat with ⎕WS, the formatting is applied to the current selection. If there is no selection, it defines the default paragraph formatting at the insertion point.

All of the dimensions used for text and paragraph formatting are specified in Twips. You can convert from pixels to Twips and vice versa using the DevCaps property of either Root or the Printer object as appropriate.

The behaviour of the Enter key is defined by the WantsReturn property. If WantsReturn is 1 (the default), the Enter key inputs a new line into the RichEdit object. If WantsReturn is 0 the Enter key is ignored by the RichEdit object and may instead generate a Select event on a Button. In this case the user must press Ctrl+Enter to input a new line.

The user may copy and paste information (in RTF format) between a RichEdit object and the Windows clipboard. The Clipboard object also has an RTFText property that supports RTF format

If the user attempts to alter text that is protected (see CharFormat) the RichEdit object reports a Protected event.

You may print the contents of a RichEdit object using the RTFPrint method. You may display a print set-up dialog box using the RTFPrintSetup method.


Root Object

Properties Events Methods

Purpose | This is an invisible "system" object that acts as the parent of all other objects.
Parents | (None)
Children | Bitmap, BrowseBox, Clipboard, Cursor, FileBox, Font, Form, Icon, ImageList, Locator, Menu, Metafile, MsgBox, NetClient, NetType, OCXClass, OLEClient, OLEServer, Printer, PropertySheet, SysTrayItem, TCPSocket, Timer, TipField

Description

There is a single Root object called '.' which is always present. It cannot be created using ⎕WC nor can it be destroyed.

The Caption and IconObj properties of '.' are used to identify a Dyalog APL/W application as distinct from the APL Session. The Caption property specifies the application name that is displayed when you cycle through running applications using Alt+Tab and by the Windows Task List. The IconObj property specifies the name of an Icon object that is displayed alongside the application name in the box displayed by Alt+Tab. For these to take effect, your application must have at least one visible and active Form.

For the Root object, the value of Posn is (0,0). The value of Size is either (100,100) if Coord is 'Prop', or the size of the screen in pixels if Coord is 'Pixel'. XRange and YRange both have the value (0,100). The DevCaps property reports the physical size of the screen in terms of both pixels and millimetres. It also reports the number of colours available. The FontList property provides a list of all the character fonts that are available. The PrintList property provides a list of all the installed printers. These properties are read-only and may not be changed using ⎕WS

As the default value of Coord is 'Inherit' for all other objects, the value of Coord for '.' defines the default co-ordinate system. It may be either 'Prop' (the default) or 'Pixel'. 'Inherit' and 'User' are not allowed.

The CursorObj property is used to define a cursor for the application as a whole. Its default value is an empty character vector. If it is set to any value other than '' or 0, the selected cursor overrides the CursorObj values for all other objects. If you want to indicate that the application is "busy", you can therefore set the CursorObj property on '.' to an hourglass for the duration of the operation, e.g.

      '.' ⎕WS 'CursorObj' 1  ⍝ Set cursor to an hourglass

[lengthy process...]

      '.' ⎕WS 'CursorObj' 0  ⍝ Reset cursor

The Yield property specifies how frequently APL yields to Windows during the execution of code. Its default value is 200 milliseconds.

The EdgeStyle property is used to determine whether or not objects may have 3-dimensional effects. Setting EdgeStyle to 'None' disables 3-dimensional effects on all Forms and controls. Setting EdgeStyle to any other value enables 3-dimensional effects for these objects.

The ExitApp and ExitWindows events can be used to prevent the user closing your application from the Windows Task List or by terminating Windows.

The expression ⎕EX '.' deletes all objects owned by the current thread except the Root object itself. In addition, if this expression is executed by thread 0, it resets all the properties of '.' to their default values.


Scroll Object

Properties Events Methods

Purpose | Provides a vertical or horizontal scrollbar.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The Scroll object provides a vertical or horizontal scrollbar that can be used as a "free-standing" object or can be "attached" to the side of its parent.

An "attached" scrollbar is one that extends along one edge of a Form, SubForm or Group and has a standard width or height. When the Form or Group is resized, a vertical attached scrollbar is resized vertically but remains the same width and stays fixed to the side of its parent. Similarly, a horizontal attached scrollbar is resized horizontally but remains the same height.

For most purposes, the use of the Scroll object to provide attached scrollbars in a Form has been superseded by the provision of scrollbars as a property of a Form. This facility was not available in the first release of Dyalog APL/W (Version 6.2).

A "free-standing" scrollbar is typically used as a "scale" for selecting a numeric value from a range and may appear and behave rather differently from a standard attached scrollbar. Firstly, a free-standing scrollbar will normally be positioned at an arbitrary position within its parent Form or Group and be associated with other objects such as Labels and Edit fields. Secondly, when its parent Form or Group is resized, it is probably desirable that the scrollbar reacts in the same way as the other child objects, so that the overall appearance of the layout is maintained.

The Align property determines whether or not a scrollbar is attached, and if so, to which side of the parent Group or Form it is fixed. The direction of the scrollbar is determined by the VScroll and HScroll properties, which are mutually exclusive. The position and size of the scrollbar are determined by Posn and Size.

To obtain an "attached" scrollbar, it is sufficient for most purposes to specify only the Align property. If so, the direction of the scrollbar and its position and size (which are otherwise defined by VScroll, HScroll, Posn and Size) are determined automatically for you.

To obtain a "free-standing" scrollbar, it is recommended for most purposes that you set Align to 'None' and define the orientation, position and size of the scrollbar explicitly using VScroll or HScroll, Posn and Size.

If you do attach a "free-standing" scrollbar to a particular side of its parent using Align, it will maintain its physical position (in pixels) relative to the side to which it is attached, and its dimension in that direction will remain fixed.

The Align property is a character vector containing 'Top', 'Bottom', 'Right', 'Left' or 'None'. If you specify Align 'Right' you get a vertical scrollbar attached to the right-hand edge of the parent Form or Group. Align 'Left' also produces a vertical scrollbar, but one that is attached to the left-hand edge. Align 'Top' and 'Bottom' each produce horizontal scrollbars, attached respectively to the top and bottom edges of the Form or Group.

Note that the default value of Align is 'Right' unless HScroll is set to ¯1 in which case it is 'Bottom'. It must therefore be explicitly set to 'None' if you want a non-attached "free-standing" scrollbar.

VScroll and HScroll are used to specify the orientation of the scrollbar explicitly, usually in conjunction with Align set to 'None'. VScroll or HScroll may be specified when the object is created by ⎕WC, but cannot be changed using ⎕WS. The two properties are mutually exclusive. Each of them may be set to 0 or ¯1, where ¯1 means "true" and 0 means "false". Thus (VScroll ¯1) defines a vertical scrollbar, while (HScroll ¯1) specifies a horizontal one. Setting either property to ¯1 automatically causes the other to be set to 0. If you try to set both to ¯1, VScroll takes precedence and HScroll is reset to 0.

[Note: the reason for using two properties where one would be sufficient is to allow for the possible future implementation of scrolling groups as provided by ⎕SM/⎕SR.]

Scrolling is controlled by the Thumb, Range and Step properties.

Thumb sets and reports the current position of the "thumb" as an integer in the range 1 to the value of the Range property.

Step determines the size of changes reported when the user clicks a scroll arrow (small change) or clicks on the body of the scrollbar (large change). Step is a 2-element numeric vector whose first element specifies the value of the "small change" and whose second element specifies the value of the "large change".

Examples of Attached Scrollbars:

      'F' ⎕WC 'Form' 'Default Scroll Bar'
      'F.SCR' ⎕WC 'Scroll'

      'F' ⎕WC 'Form' 'Default Horizontal Scroll Bar'
      'F.SCR' ⎕WC 'Scroll' ('HScroll' ¯1)

Examples of Free-Standing Scrollbars:

      'F' ⎕WC 'Form' 'Non-Default Scroll Bar'
      'F.SCR' ⎕WC 'Scroll' (5 45)(90 10)('Align' 'None')('VScroll' ¯1)

      'F' ⎕WC 'Form' 'Horizontal Scroll Bars'
      'F.SC1' ⎕WC 'Scroll' (15 15)(15 70)('Align' 'None')('HScroll' ¯1)
      'F.SC2' ⎕WC 'Scroll' (40 40)(20 20)('Align' 'None')('HScroll' ¯1)
      'F.SC3' ⎕WC 'Scroll' (85 5)(10 90)('Align' 'None')('HScroll' ¯1)


Seperator Object

Separator Object

Properties Events Methods

Purpose | A horizontal or vertical line used to separate items in a menu.
Parents | Menu, MenuBar
Children | Timer

Description

This object provides a vertical or horizontal line to separate items in a Menu. It may also be used to split a MenuBar over more than one line.

The orientation of the Separator is determined by its Style property, which may be 'Horz' (horizontal) or 'Vert' (vertical). The default is 'Horz'.

If you want to provide a menu with a 3-Dimensional (pushbutton) appearance, you should also set the EdgeStyle property on any Separator objects in it. Alternatively, you can achieve the same effect by setting the background colour (BCol) for the Separators to grey (192 192 192).

The Posn property is a single integer number which specifies the positional index of the Separator relative to the other objects in the Menu. A Separator does not generate any events.

Like other components of a menu, the position of a Separator is normally determined by the order in which it is created in relation to other objects with the same parent. However, you can use the Posn property to insert a Separator into an existing structure. For example, having defined three MenuItem objects as children of a Menu, you can insert a Separator between the first and the second by specifying its Posn to be 2. Note that the value of Posn for the MenuItems that were previously second and third will then be reset to 3 and 4 respectively.

If you put a Separator (either Style) into a MenuBar, it has the effect of adding another line to it. Any items added after the Separator will appear in the new line.


SM Object

Properties Events Methods

Purpose | Defines a window for ⎕SM/⎕SR.
Parents | Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Cursor, Timer

Description

This object defines a window for ⎕SM/⎕SR and allows you to combine the functionality of ⎕SM/⎕SR with the "windows" GUI. For example, you can define a Form with a MenuBar at the top and a ⎕SM window beneath it, with perhaps some Buttons alongside.

To allow the user to interact with both ⎕SM and other top-level objects, you must specify the names of these objects in the right argument of ⎕SR. Thus the statement :

      CTX ← KEYS CTX ⎕SR 1 2 3 'Form1'

allows the user to interact with fields (rows) 1-3 of ⎕SM and with the object 'Form1' and its children. Callback functions associated with events in 'Form1' will be executed automatically by ⎕SR. If an enabled event without a callback occurs, the event will be placed on ⎕DQ's internal queue and ⎕SR will terminate. The nature of the termination (i.e. that it was caused by an event in an object) is reported by the value 131072 (2*17) in the fourth element of ⎕SR's result. The specific event (Configure, MouseUp, etc.) is however not reported. It is therefore generally preferable to use callbacks.

The Posn, Size and Coord properties allow you to specify the position and size of the window occupied by ⎕SM within its parent Form. Note however that the ⎕SM window will automatically be sized to be an exact number of characters in height and width which will be reported in ⎕SD.

The Border property may be used to specify a border around the outside of the ⎕SM window. It is a number with the value 0 (no border) or 1 (1 pixel border). The default is 0. The EdgeStyle property may be used to give the object a 3-dimensional appearance. Its default value is 'Recess'. The area within the SM object that is defined by ⎕SM is necessarily a multiple of the character size. The region between this area and the outer edges of the object is coloured by the background colour specified by BCol, or may be filled with a bitmap specified by Picture.

If the user resizes the Form which contains the SM object, the SM object will generate a Configure event if enabled. If the Configure event is not enabled, ⎕SR will terminate with a RESIZE error which can be trapped using ⎕TRAP. Either method can be used to reformat ⎕SM as appropriate.

The MouseDown event can be used to bring up a pop-up menu. Note however that mouse events are not reported over ⎕SM fields because ⎕SR uses these to position the cursor.

The illustration shown below was produced as follows :

      'TEST'      ⎕WC 'Form' 'SM Object' (60 10)(40 50)
      'TEST.MB'   ⎕WC 'MenuBar'>
      'TEST.MB.F' ⎕WC 'Menu' '&File'
      'TEST.MB.O' ⎕WC 'Menu' '&Options'
      'TEST.B1'   ⎕WC 'Button' '&OK' (84 2)
      'TEST.B2'   ⎕WC 'Button' '&Cancel' (84 78)
      'TEST.S'    ⎕WC 'SM' (2 2)(80 96)('BCol' 192 192 192)
      ⎕SM←('The answer is' 5 10)(42 5 30)


Spinner Object

Properties Events Methods

Purpose | The Spinner object allows the user to enter a value, using an UpDown object to adjust it as required.
Parents | ActiveXControl, CoolBand, Form, Grid, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The Spinner object is a special Dyalog APL composite object that consists of an edit field and a pair of spin buttons. The user may enter a value by typing in the edit field and may adjust the value with the spin buttons. The Spinner may cycle through a pre-defined set of values specified by the Items property or through a range of values specified by the Limits property. The FieldType property supports all of the standard data types, i.e. Char, Numeric, LongNumeric, Currency, Date, LongDate and Time.

The Limits property is a 2-element numeric vector that specifies the minimum and maximum value of the object. The Step property specifies the amount by which the value is incremented or decremented by the spin buttons. The current value in the object is defined by the Thumb and Value properties, which are usually identical. If ReadOnly is 0, the user may type a value into the edit field which will be validated and converted according to the FieldType. In this case, the Value and the Thumb properties may be different.

An alternative way to use the Spinner object is to specify the Items property. This defines a discrete set of values through which the user may cycle, and the object behaves rather like a Combo without a drop-down list. In this case, the Limits property is automatically set to (1,⊃⍴Items), Thumb refers to the index into the list of Items, and Step specifies the amount by which this index is updated by the spin buttons. For example, if you set Step to 3, the spin buttons would display every third item. The Items property may be a character matrix, a vector of character vectors, or a numeric vector and will be formatted according to the FieldType. For example, if you wanted the user to select one of a set of specific dates, you would set the FieldType to Date or LongDate and the Items property to the day numbers (since 1 January 1900) corresponding to the dates you require. The ReadOnly property specifies whether or not the user may enter data into the edit field. A value typed in by the user will be converted and formatted according to the FieldType but need not correspond to a value in Items.

In operation, the value in the Spinner is adjusted by the Step each time one of the spin buttons is clicked. If the user holds a spin button down, the value is adjusted at the rate defined for the keyboard repeat rate. Furthermore, the size of each adjustment is increased according to the length of time the button stays depressed. After 1 second, the amount is increased to (2 × Step). after 2 seconds, to (4 × Step), after 3 seconds to (8 × Step) and so forth until the amount of adjustment exceeds one quarter of the range (Limits[2]⍎Limits[1]).

When the value in the spinner reaches its top or bottom limit, it will wrap around to the opposite limit if the value of the Wrap property is 1 (the default). Otherwise it will stick.

The MaxLength property defines the maximum number of characters that the user may type into the edit field. The Decimals property specifies the number of decimal places to which a numeric value is displayed and applies only if the FieldType is Numeric or LongNumeric.

The Spinner generates two special events, Spin and SetSpinnerText. The Spin event is generated each time the value of the Thumb is about to be updated and reports the new value and the difference between it and the current value. You may prevent the Thumb from being updated by returning 0 from a callback function, or you may alter the new value of the Thumb by returning a modified message. The SetSpinnerText event is generated after the Thumb has been reset but before the edit field has been updated. It reports the new value of the Thumb and the text that is about to be written into the edit field. By returning a modified event message from a callback, this event allows your application to respond dynamically to the spin buttons and to control the text in the edit field directly.

Like an Edit object, the Spinner has a Changed property and generates a Change event when loses the focus after the value of its Text and/or Thumb property has been altered.

If FieldType is Numeric, LongNumeric, Currency, Date, LongDate or Time, the Spinner will generate a BadValue event when it loses the focus if the text in the edit field (i.e. the Text property) is in conflict with the FieldType property and cannot be converted to an appropriate number. If the edit field is empty, a BadValue event will be generated if ValidIfEmpty is 0, but not if it is set to 1.


Splitter Object

Properties Events Methods

Purpose | The Splitter object divides a container into resizable panes.
Parents | ActiveXControl, Form, Group, PropertyPage, SubForm
Children | Timer

Description

The Splitter divides the client area of a Form or SubForm into resizable panes. Each pane created this way may be empty or be occupied by a single object. If the object in a pane is itself a container object, such as a SubForm, it may have a number of other controls within it.

A single Splitter may manage the geometry of 0, 1 or 2 other objects, which, together with the Splittter itself, share the same parent. The two objects are named by the SplitObj1 and SplitObj2 properties respectively.

A Splitter may manage objects of the following types:

Button | Calendar | Combo | Edit | Grid | Group
Label | List | ListView | MDIClient | ProgressBar | RichEdit
Scroll | Spinner | Static | StatusBar | SubForm | TabBar
TabControl | ToolBar | TrackBar | TreeView | UpDown |

If Style is 'Vert' (the default), the Splitter is drawn vertically in its parent with the first object (SplitObj1) positioned to its left, and the second object (SplitObj2) to its right as illustrated by Example 1.

If Style is 'Horz', the Splitter is drawn horizontally in its parent with the first object (SplitObj1) positioned above, and the second object (SplitObj2) below as illustrated by Example 2.

The Style property must be set when the object is created with ⎕WC and may not subsequently be changed using ⎕WS.

The Posn and Size properties are partially read-only, in that only one dimension of the value may be specified. If Style is 'Vert', you may specify the x-coordinate and the width of the Splitter, but you may not specify its y- coordinate nor its height. If Style is 'Horz', you may specify the y-coordinate and the width of the Splitter, but you may not specify its x-coordinate nor its length.

When the user positions the mouse pointer directly over the Splitter object, the cursor changes (by default) to a double-headed arrow (direction in accordance with Style). The user may now depress the left mouse button and drag the Splitter to a new position, resizing the objects named by SplitObj1 and SplitObj2 in the process.

You can select a different cursor using the CursorObj property. Note that setting the CursorObj property to 0 selects the default cursor, which is the appropriate double-headed arrow.

When the user depresses the mouse button, the Splitter generates a StartSplit event. When the user releases the mouse button, the Splitter generates an EndSplit event. If full-drag is in effect, the Splitter also reports Splitting events as it is dragged. All these events report the new or current position of the Splitter object and are provided for information only.

Note that the objects named by SplitObj1 and SplitObj2 and any sub-objects they contain will generate Configure events when they are resized by the Splitter.

Alignment

The Align property specifies how a Splitter behaves when its parent is resized and may be 'None', 'Left', 'Right', 'Top' or 'Bottom'.

If Align is 'None', the Splitter moves as its parent is resized, so that it divides its parent in the same proportions as before. This is the default.

Any other value of Align attaches the Splitter to the corresponding edge of its parent. For example, if Align is 'Left', the width of the object to the left of the Splitter remains fixed when its parent is resized horizontally by the user.

Like the Style property, Align may be set only when the object is created with ⎕WC and may not subsequently be changed using ⎕WS.

Using Multiple Splitters

If you want to divide a Form into more than 2 resizable panes, there are two possible approaches, each with its own different characteristics.

The first approach, illustrated by Example 3, is a hierarchical one using SubForms. This example shows how you can create a Form containing three resizable Edit objects.

First, you create an Edit, a SubForm, and a Splitter as children of the Form, using the Splitter to divide the Form into two panes, one for the Edit and the other for the SubForm. Next, you create two Edit objects and a Splitter as children of the SubForm, using the second Splitter to divide the SubForm into two. You can continue with this approach to any reasonable depth.

Notice that, by default, when the first Splitter is shifted to the left, both panes in the SubForm expand equally as shown in the example.

The second approach, illustrated by Example 4, is to create multiple Splitters at the same level, i.e. owned by the same parent. In this case, the third Edit object F.E3 is unaffected by movement of the leftmost Splitter F.S1. Note also, that the first Splitter F.S1 may not be dragged further right than the second Splitter F.S2.

Using the non-hierarchical approach, horizontal and vertical Splitters may be combined in interesting ways as illustrated in Example 5. This can also be achieved using nested SubForms, but at the expense of a complex object hierarchy.

Notice that in this example, with the exception of the last Splitter F.S4, it is necessary only to specify the SplitObj1 property for each of the Splitters. The reason is that the first four Splitters only manage one object directly. For example, the object to the right of F.S1 is in fact a horizontal Splitter F.S2. Dragging F.S1 changes the length of F.S2 which in turn changes the width of F.E2. and F.E3.

Colliding Splitters

If you have two or more vertical Splitters or two or more horizontal Splitters in the same parent object, it is possible for the user to make the Splitters collide. This can occur by dragging one of the Splitters into the other, or, unless both Splitters have Align set to 'None', by shrinking the parent.

When Splitters collide, the object being dragged by the user (a Splitter or a border of the parent) takes precedence over the setting of Align, and temporarily pushes other Splitters along in its direction of travel. If and when the operation is reversed, the other Splitters are pulled back to their original positions.


Static Object

Properties Events Methods

Purpose | This object is primarily used to display graphics in a sub-window.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Circle, Cursor, Ellipse, Font, Image, Locator, Marker, Metafile, Poly, Rect, Text, Timer

Description

The overall appearance of an empty Static object is controlled by the value of its Style property which may be one of the following character vectors :

'BlackFrame' 'BlackBox'

'GreyFrame' 'GreyBox'

'GrayFrame' 'GrayBox'

'WhiteFrame' 'WhiteBox'

Note that the colours implied by the Style are not "hard-coded" but are actually defined by the current Windows colour scheme as follows :

Black | Window Border Colour
Grey/Gray | Desktop Colour
White | Window Background Colour

If the background colour of the Form is also set to the Window Background Colour, it follows that the Styles 'WhiteFrame' and 'WhiteBox' make the Static itself invisible (against the background), although the contents of the Static will show. This makes the Static appear like an invisible clipping window.


StatusBar Object

Properties Events Methods

Purpose | This object is used to manage StatusField objects which display information for the user.
Parents | ActiveXControl, CoolBand, Form, SubForm
Children | Bitmap, BrowseBox, Circle, Cursor, Ellipse, FileBox, Font, Icon, Image, Marker, Poly, ProgressBar, Rect, StatusField, Text, Timer

Description

The StatusBar is a container object that manages StatusFields. StatusField objects display textual information and are typically used for help messages and for monitoring the status of an application. They can also be used to automatically report the status of the Caps Lock, Num Lock , Scroll Lock, and Insert keys.

The Align property determines to which side of the parent Form or SubForm the StatusBar is attached. By default, a StatusBar is positioned along the lower edge of the Form (Align 'Bottom') and is 24 pixels high. Using the Align, Posn and Size properties you may create StatusBars in different positions and with differing sizes if you wish. Notice that the Align property controls how the StatusBar reacts to its parent Form being resized. If Align is 'Top' or Bottom, the StatusBar remains fixed in height but stretches and shrinks sideways with the Form. If Align is 'Left' or 'Right', the StatusBar remains fixed in width and stretches and shrinks vertically with the Form.

By default a StatusBar has a Button Face colour background and the value of its EdgeStyle property is 'Default'. This gives it the appearance shown above.

Unless you specify the position and size of its children, a StatusBar automatically manages their geometry. The first StatusField is positioned just inside its top left corner. If Align is 'Top' or 'Bottom', the next StatusField is positioned alongside the first but with a small gap between them. Subsequent StatusFields are added in a similar fashion. If Align is 'Left' or 'Right', the second and subsequent StatusFields are added below the first with a similar gap between them. In either case you can position and size the StatusFields explicitly if you wish.

If you attempt to add a StatusField that would extend beyond the right edge (Align 'Top' or 'Bottom') or bottom edge (Align 'Left' or 'Right') the behaviour depends upon the value of HScroll or VScroll. If HScroll is 0 (the default) and Align is 'Top' or 'Bottom', the StatusField is added below the first one, thereby starting a new row. If VScroll is 0 (the default) and Align is 'Left' or 'Right', it is added to the right of the first one thereby starting a new column. If HScroll or VScroll is ¯1 or ¯2, the new StatusField is simply positioned in the same row or column and may be scrolled into view using a mini scrollbar. A value for HScroll or VScroll of ¯1 causes the mini scrollbar to be permanently present in the Scroll Bar. A value of ¯2 causes it to appear only when required.


StatusField Object

Properties Events Methods

Purpose | This object is used to display information for the user.
Parents | StatusBar
Children | Menu, Timer

Description

The StatusField object provides an area for displaying context sensitive help messages, keyboard status, and other application dependant information.

By default a StatusField is a recessed rectangle in which information is displayed. It has a Caption and a Text property, which by default are empty, but either or both of which can be used to present information. The Caption is left justified in the field and the Text is displayed immediately to its right. Typically, you would use the Caption property as a title to describe the information that the StatusField displays, and the Text property to show its current value. However, you are not obliged to use both of them and you can achieve most effects with just one.

Note that when the StatusField is used to display hints it is its Text property that is used.

A StatusField may be used to monitor the status of the keyboard and this is controlled by its Style property. The default value for Style is an empty vector. However, you can set it to monitor various keyboard states as follows :

CapsLock | Monitors state of Caps Lock key
ScrollLock | Monitors state of Scroll Lock key
NumLock | Monitors state of Num Lock key
KeyMode | Monitors the keyboard mode (APL/ASCII)
InsRep | Monitors the state of the Insert key

In each case, the Text property of the StatusField is used to display the keyboard status. If Style is CapsLock, ScrollLock or NumLock, the field displays “Caps”, “Num” or “Scroll” if the corresponding mode is selected and is blank if not.

If Style is InsRep, the StatusField displays either “Ins” or “Rep”. Initially it always displays “Ins” and then toggles between “Rep” and “Ins” each time the Insert key is pressed.

If Style is KeyMode, the StatusField displays the name for the current keyboard mode which is defined in the input table being used. For the 2-mode tables APL_US.DIN, APL_UK.DIN etc., the mode name displayed is either “Apl” or “Asc”. The unified tables have no modes so a StatusField with this Style does nothing.

If Style is set to one of the above, you may still use the Caption property to give the StatusField a title. You may even set the value of the Text property, but be aware that this value will be reset when the user next presses the key the StatusField is monitoring.


SubForm Object

Properties Events Methods

Purpose | This object represents a window that is owned by and constrained within another Form or an MDIClient.
Parents | ActiveXControl, CoolBand, Form, Group, MDIClient, PropertyPage, SubForm, TabControl, ToolBar, ToolControl
Children | Animation, Bitmap, BrowseBox, Button, Calendar, Circle, ColorButton, Combo, ComboEx, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, Metafile, MsgBox, NetControl, OCXClass, Poly, ProgressBar, PropertySheet, Rect, RichEdit, Scroll, SM, Spinner, Splitter, Static, StatusBar, SubForm, TabBar, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

If the SubForm is the child of a Form, it is by default a simple featureless window that occupies the entire client area (excluding standard ToolBars, StatusBars and TabBars) of its parent. The properties that control its appearance, including Sizeable, Moveable, SysMenu, Border, MaxButton and MinButton, all default to 0. The EdgeStyle property also defaults to 'None', so the background of the SubForm defaults to the Window Background colour.

If the SubForm is the child of an MDIClient, its default appearance is the same as for a top-level Form. By default its size is 25% of its parent client area and it is positioned in the centre of its parent object.

The Posn property specifies the location of the internal top-left corner of the SubForm relative to its parent. If the SubForm has a title bar, border, or a 3-dimensional shadow, you must allow sufficient space for these components. Similarly, the Size property specifies the internal size of the SubForm excluding the title bar and border.

A SubForm is constrained so that it cannot be moved outside its parent. In all other respects it behaves in a similar manner to a Form object. See Form object and the descriptions of its properties for further details.


SysTrayItem Object

Properties Events Methods

Purpose | The SysTrayItem object represents an item that you can create in the Windows System Tray.
Parents | Form, Root
Children | Icon, Menu, Timer

Description

The SysTrayItem object appears as an icon in the Windows System Tray and allows the user to interact with your application even if it is minimised or has no other visible presence.

Interaction is provided through a pop-up menu that is displayed when the user clicks on the SysTrayItem. The SysTrayItem does not support mouse or keyboard events directly.

The IconObj property specifies the name of an Icon object used to display the SysTrayItem. If not specified, the default is the standard Dyalog APL icon.

The Popup property specifies the name of a Menu object (which may be a child of the SysTrayItem). The Menu object is displayed automatically when the user clicks on the SysTrayItem icon. The Menu should contain one or more MenuItem objects with suitable callback functions attached.

Unlike other popup menus, the SysTrayItem menu is not activated by an explicit (modal) ⎕DQ but is posted automatically for you. The MenuItem callbacks will be executed by the current ⎕DQ, with the exception of modal ⎕DQs on MsgBox, FileBox, Locator and other popup Menu objects. For example, if your application is in a modal ⎕DQ on a Form, that ⎕DQ will react to and action events on the SysTrayItem menu, even though it is not explicitly included in the list of objects being ⎕DQ'ed.

The Tip property specifies a character string to be displayed when the user hovers the mouse over the SysTrayItem. This is displayed using the user's current setting for Tip text and it is not possible to change this appearance.


TabBar Object

Properties Events Methods

Purpose | To manage a set of TabBtn objects.
Parents | ActiveXControl, Form, SubForm
Children | Circle, Ellipse, Font, Marker, Poly, Rect, TabBtn, Text, Timer

Description

The TabBar object manages a group of TabBtn objects. These are associated with a set of SubForm objects which are positioned on top of one another. When the user clicks on a TabBtn, the corresponding SubForm is brought to the top and given the focus.

TabBar and TabBtn objects were implemented before Windows provided direct support for tabbed dialogs, and have been superceded by TabControl and TabButton objects. Please use these instead.

By default, a TabBar is a flat bar stretched across the bottom of its parent form. You can alter its appearance using its EdgeStyle property and you can control its alignment with its Align property. Align can be set to Top , Bottom (the default), Left or Right and causes the TabBar to be attached to the corresponding edge of the Form. A TabBar aligned Top or Bottom will automatically stretch or shrink horizontally when its parent Form is resized, but it will remain fixed vertically. A TabBar aligned Left or Right will stretch vertically but will remain fixed horizontally. By default a TabBar occupies the entire width or length of the side of the Form to which it is attached and (under Windows 3.1) is 17 pixels high or wide. You can change these defaults using the Posn and Size properties.

The alignment of a TabBar also determines the orientation of its TabBtns. TabBars aligned Top or Bottom cause their TabBtns to be drawn left to right with the free edge of the TabBtns facing downwards or upwards respectively. TabBar aligned Left or Right draw their TabBtns downwards with their free edges facing left or right respectively.

By default, TabBtn objects are positioned along the inner edge of the TabBar. This is the edge closest to the SubForm s they will tab. They are also positioned so that they overlap one another horizontally or vertically according to the Align property.

The HScroll and VScroll properties determine what happens when the end of the TabBar is reached. If HScroll or VScroll is 0 (the default) a TabBtn that would otherwise extend beyond the TabBar is instead positioned immediately above, below or alongside the first TabBtn in the TabBar, thereby starting a new row or column. Note however that the TabBar is not automatically resized vertically to accommodate a second row or column. If you want a multi-flight TabBar you have to set its height or width explicitly. If HScroll or VScroll is ¯1 or ¯2, TabBtns continue to be added along the TabBar even though they extend beyond its boundary and may be scrolled into view using a mini scrollbar. If HScroll is ¯1, the scrollbar is shown whether or not any controls extend beyond the TabBar. If HScroll is ¯2, the scrollbar appears only if required and may appear or disappear when the user resizes the parent Form.

If you specify a value for its Posn property, a TabBtn will be placed at the requested position regardless of the value of Style, HScroll or VScroll. However, the next control added will take its default position from the previous one according to the value of these properties. Thus if you wish to group your controls together with spaces between the groups, you need only specify the position of the first one in each group.

If you specify a value for its Posn property, a TabBtn will be placed at the requested position regardless of the value of Align. However, the next TabBtn added will take its default position from the previous one. Thus if you wish to group your TabBtns together with spaces between the groups, you need only specify the position of the first one in each group.


TabBtn Object

Properties Events Methods

Purpose | To tab a SubForm.
Parents | TabBar
Children | Timer

Description

TabBtn objects are associated with SubForms which are positioned on top of one another. When the user clicks on a TabBtn, the corresponding SubForm is brought to the top and given the focus.

TabBar and TabBtn objects were implemented before Windows provided direct support for tabbed dialogs, and have been superceded by TabControl and TabButton objects. Please use these instead.

The appearance of a TabBtn is determined by its EdgeStyle, Border and Caption properties. These take their defaults from the SubForm with which the TabBtn is associated. Thus there is generally no need to specify them. BCol also defaults to that of its associated SubForm.

The position of a TabBtn is normally determined by its parent TabBar and its default size is fixed (22 x 80 pixels), and not related to the size of its Caption. These defaults can be overridden using the Posn and Size properties.

A SubForm is associated with a TabBtn by setting the TabObj property of the SubForm to the name of, or ref to, the TabBtn. The TabObj property of the TabBtn is a read-only property that contains the name of, or ref to, the associated SubForm.


TabButton Object

Properties Events Methods

Purpose | The TabButton object represents an individual tab or button in a TabControl
Parents | TabControl
Children | Timer

Description

The TabButton object represents an individual tab or button in a TabControl

The position and size of a TabButton object are entirely determined by its parent TabControl and may not be altered. For this reason, the Posn and Size properties are read-only.

The Caption property specifies the text that appears on the button or tab.

A picture is specified by setting the ImageIndex property of the TabButton. This is a number that points to a particular icon or bitmap defined in an ImageList object whose name is specified by the ImageListObj property of the parent TabControl.

Note that all TabButton objects share the same font which is defined by the FontObj property of the TabControl.

The foreground and background colours of the TabButton object are fixed.

When used as a tab, a TabButton is normally attached to a SubForm by the TabObj property of the SubForm. The TabObj property of the TabButton itself, is a read-only property that specifies the name of, or ref to, the SubForm to which the TabButton is attached.

The State property reports the (selected) state of a TabButton and applies only when its parent TabControl has Style set to 'Buttons' or 'FlatButtons' and MultiSelect set to 1.


TabControl Object

Properties Events Methods

Purpose | The TabControl object provides access to the native Windows tab control.
Parents | ActiveXControl, CoolBand, Form, SubForm
Children | ImageList, SubForm, TabButton, Timer

Description

The standard tab control is analogous to a set of dividers in a notebook and allows you to define a set of pages that occupy the same area of a window or dialog box. Each page consists of a set of information or a group of controls that the application displays when the user selects the corresponding tab.

A special type of tab control displays tabs that look like buttons. For example, the Windows taskbar is such a tab control.

The overall appearance of the TabControl is determined by the Style property which may be 'Tabs' (the default), 'Buttons' or 'FlatButtons'.

Individual tabs or buttons are represented by TabButton objects which should be created as children of the TabControl object. Optional captions and pictures are specified by the Caption and ImageIndex properties of the individual TabButton objects themselves. Otherwise, the appearance of the tabs or buttons is determined by properties of the TabControl itself.

To implement a multiple page tabbed dialog, illustrated by Example 1, you should create a Form, then a TabControl with Style 'Tabs' as a child of the Form. Next, create one or more pairs of TabButton and SubForm objects as children of the TabControl. You associate each SubForm with a particular tab by setting its TabObj property to the name of, or ref to, the associated TabButton object. Making the SubForms children of the TabControl ensures that, by default, they will automatically be resized correctly. You may alternatively create your SubForms as children of the main Form and establish appropriate resize behaviour using their Attach property.

A TabControl object with Style 'Buttons' (Example 2) or 'FlatButtons' (Example 3) may be used in a similar way (i.e. to display a set of alternative pages), although buttons in this type of TabControl are more normally used to execute commands. For this reason, these styles of TabControl are without borders.

If Style is 'FlatButtons', the FlatSeparators property specifies whether or not separators are drawn between the buttons. The default value of FlatSeparators is 0 (no separators). Example 3a shows the effect of setting FlatSeparators to 1.

The Align property specifies along which of the 4 edges of the TabControl the tabs or buttons are arranged. Align also controls the relative positioning of the picture and Caption within each TabButton. Align may be Top (the default) , Bottom, Left or Right.

If Align is 'Top' or 'Bottom' (Example 4), the tabs or buttons are arranged along the top or bottom edge of the TabControl and picture is drawn to the left of the Caption.

If Align is 'Left' (Example 5), the tabs or buttons are arranged top-to-bottom along the left edge of the TabControl, and the pictures are drawn below the Captions.

If Align is 'Right' (Example 6) , the tabs are arranged top-to-bottom along the right edge of the TabControl, and the pictures are drawn above the Captions.

The Attach property specifies how the TabControl responds when its parent is resized. Its default value, which is independent of the Align property, is 'None' 'None' 'None' 'None'. This causes the TabControl to maintain its original proportions when its parent is resized.

The MultiLine property determines whether or not your tabs or buttons will be arranged in multiple flights or multiple rows/columns.

The default value of MultiLine is 0, in which case, if you have more tabs or buttons than will fit in the space provided, the TabControl displays an UpDown control to permit the user to scroll them. See Example 7.

If MultiLine is set to 1, the tabs are displayed in multiple flights (Example 8) or the buttons are displayed in multiple rows (Example 9).

The ScrollOpposite property specifies that unneeded tabs scroll to the opposite side of a TabControl, when a tab is selected. Setting ScrollOpposite to 1 forces MultiLine to 1 also.

Example 10 illustrates a TabControl with ScrollOpposite set to 1, after the user has clicked Third Tab. Notice that, in this example, the SubForms have been created as children of the TabControl. This is necessary to ensure that they are managed correctly in this case.

If MultiLine is 1, the way that multiple flights of tabs or rows/columns of buttons are displayed is further defined by the Justify property which may be 'Right' (the default) or None.

If Justify is 'Right' (which is the default), the TabControl increases the width of each tab, if necessary, so that each row of tabs fills the entire width of the tab control. Otherwise, if Justify is empty or 'None', the rows are ragged. See Example 11 (for tabs) and Example 12 (for buttons)

By default, the size of the tabs may vary from one to another. Fixed size tabs may be obtained by setting the TabSize property.

To obtain fixed sized tabs with MultiLine set to 1, you must however also set Justify to 'None'.

If fixed size tabs are in effect, the positions at which the picture and Caption are drawn within each TabButton is controlled by the TabJustify property which may be 'Centre', 'Edge', or 'IconEdge'. Example 13 illustrates these different settings.

The font used to draw the captions in the TabButton objects is determined by the FontObj property of the TabControl.

You cannot specify the foreground or background colours of the tabs/buttons, nor can you use different fonts in different tabs/buttons. The orientation of the Caption text is always determined by the value of the Align property of the TabControl.

The TabObj property is read-only and reports the name of, or ref to, the TabButton that is currently selected.

The MultiSelect property specifies whether or not the user can select more than one button in a TabControl at the same time, by holding down the Ctrl key when clicking. The default is 0 (only one button may be selected). MultiSelect is ignored if Style is 'Tabs'.

The TabFocus property specifies the focus behaviour for the TabControl object and may be 'Normal'(the default), 'Never' or 'ButtonDown'.

The HotTrack property specifies whether or not the tabs or buttons are automatically highlighted by the mouse pointer. The default is 0 (no highlighting).


TCPSocket Object

Properties Events Methods

Purpose | The TCPSocket object provides an interface to TCP/IP.
Parents | ActiveXControl, Calendar, CoolBand, DateTimePicker, Form, NetType, OLEClient, OLEServer, PropertyPage, Root, SubForm, TCPSocket
Children | Bitmap, BrowseBox, Clipboard, Cursor, FileBox, Font, Form, Icon, ImageList, Locator, Menu, Metafile, MsgBox, OCXClass, OLEClient, Printer, PropertySheet, TCPSocket, Timer, TipField

Description

The TCPSocket object provides an event-driven mechanism to communicate with other programs (including Dyalog APL) running on other computers and with the world-wide Web.

The SocketType property is a character vector that specifies the type of the TCP/IP socket. This is either 'Stream'(the default), or 'UDP'. SocketType must be defined when the object is created and may not be set or changed using ⎕WS.

The Style property is a character vector that specifies the type of data transmitted or received by the socket; it may be 'Char', 'Raw', or 'APL'. The value 'APL' is valid only if the SocketType is 'Stream'.

The Encoding property is a character vector that specifies how character data are encoded or translated. The possible values are 'None', 'UTF-8', 'Classic', or 'Unicode', depending upon the value of the Style property.

LocalAddr and LocalPort properties identify your end of the connection; RemoteAddr and RemotePort identify the other end of the connection. The values of the two sets of properties are clearly symmetrical; your LocalAddr is your partner’s RemoteAddr, and there are strict rules concerning which of them you and your partner may set. See the individual descriptions of these properties for details.

The SocketNumber property is the Window handle of the socket attached to the TCPSocket object and is generally a read-only property. The only time that SocketNumber may be specified is when a server replicates (clones) a listening socket to which a client has just connected.


Text Object

Properties Events Methods

Purpose | Writes text.
Parents | ActiveXControl, Animation, Bitmap, Button, Combo, ComboEx, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Metafile, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, TipField, ToolBar, TrackBar, TreeView, UpDown
Children | Timer

Description

The Text object is used to write arbitrary text. It can be used in a Form, SubForm or Group instead of a Label. The main difference is that a Label is implemented as a true window object (thus consuming Windows resources). A Text object is not a window and consumes no MS-Windows resources. However, a Label supports DragDrop events and has various useful properties that are not shared by the Text object.

The contents of the Text object are defined by its Text property. This is a character array containing one of the following :

  • a simple scalar
  • an enclosed vector or matrix (also a scalar)
  • a simple vector
  • a simple matrix
  • a vector of enclosed vectors or matrices

Points is either a simple 2-column matrix of (y,x) co-ordinates, or a 2-element vector of y-coordinates and x-coordinates respectively.

There are two distinct cases :

1) Points specifies a single point. In this case, Text may be a single scalar character, a simple vector, or a matrix containing a block of text. The result is that the character, string, or matrix is written at the specified point.

2) Points specifies more than one point. There are three possibilities :
a)If Text is a scalar, its contents are written at each of the points in Points. This means that by enclosing a vector or matrix, you can draw a string or block of text at several locations.
b)If Text is a vector, each element of Text is written at the corresponding position in Points.
c)If Text is a matrix, each row of Text is written at the corresponding position in Points.

FontObj specifies a single font to be used to write the Text. See a description of the FontObj property for details.

FCol specifies the colour of the Text. For a single text item, FCol may be a single number which specifies one of the standard MS-Windows colours, or a simple 3-element numeric vector of RGB colour intensities. If more than one text item is involved, FCol may be a vector which specifies the colour for each item separately. If so, its length must be the same as the number of points specified by Points.

BCol specifies the background colour of the text, i.e. the colour for the part of the character cell that is blank. It is defined in the same way as FCol.

HAlign and VAlign specify the horizontal and vertical alignment of the text respectively. They may each be numeric scalars or vectors with the same length as the number of points specified in Points. See HAlign and VAlign for details.

When one or more of FCol, BCol, HAlign and VAlign are vectors, the different components of Text are drawn using the corresponding colours and alignments.

The value of the Dragable property specifies whether or not the Text object can be dragged by the user. The value of the AutoConf property determines whether or not the Text object is repositioned when its parent is resized.

Examples:

Write 'A' at (10,20)

      'g.t1' ⎕WC 'Text' 'A' (10 20)

Write 'h' at (10,20) in red

      'g.t1' ⎕WC 'Text' 'h' (10 20) ('FCol' 255 0 0)

Write 'Hello' at (10,20)

      'g.t1' ⎕WC 'Text' 'Hello' (10 20)
Write 'THIS IS A
       BLOCK OF
       TEXT     '   at (20,30)
      BLK←3 9⍴'THIS IS A BLOCK OF TEXT     '
      'g.t1' ⎕WC 'Text' BLK (10 20)

Write 'A' at (10,20) and at (30,40)

      'g.t1' ⎕WC 'Text' 'A' ((10 30)(20 40))

Write a red '+' at (10,20) and a green '+' at (20 40)
      'g.t1' ⎕WC 'Text' '+' ((10 30)(20 40))('FCol' (255 0 0)(0 255 0))

Write 'Hello' at (10,20) and at (30,40)

      'g.t1' ⎕WC 'Text' (⊂'Hello') ((10 30)(20 40))

Write 'A' at (10,20) and 'B' at (30,40)

      'g.t1' ⎕WC 'Text' 'AB' ((10 30)(20 40))

Write 'Hello' at (10,20) and 'World' at (30,40)

      'g.t1' ⎕WC 'Text' ('Hello' 'World')((10 30)(20 40))


Timer Object

Properties Events Methods

Purpose | To generate an action at regular intervals.
Parents | ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetClient, NetType, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown
Children | Timer

Description

The Timer object is used to generate an event at regular intervals. It can be used to produce animation and to implement “repeaters” such as spin buttons.

The Interval property specifies how often the Timer generates events and is defined in milliseconds. Its default value is 1000.

The Active property determines whether or not the Timer generates events and can be used to switch the Timer off and on as required.

Note that if you create a Timer object whose Timer event generates an error (for example by attaching it to a non-existent callback) it may be very difficult or even impossible to type into the Session, because the error will be displayed over and over again. Care is therefore recommended.


TipField Object

Properties Events Methods

Purpose | To display pop-up help.
Parents | ActiveXControl, CoolBand, Form, Group, OLEServer, PropertyPage, PropertySheet, Root, SubForm, TCPSocket
Children | Circle, Ellipse, Font, Marker, Poly, Rect, Text, Timer

Description

The TipField is used to display pop-up help when the user moves the mouse pointer over an object.

Most of the GUI objects supported by Dyalog APL/W have Tip and a TipObj properties. TipObj specifies the name of, or ref to, a TipField object, and Tip specifies a “help” message. The TipField automatically pops-up to display the Tip when the user moves the mouse pointer over the object. It disappears when the user moves the mouse pointer away.

The TipField is a simple box with a 1-pixel black border in which the text specified by Tip is displayed. FCol, BCol and FontObj can be used to customise the appearance of the text within the box. FCol specifies the colour of the text; BCol specifies the background colour with which the box is filled. The default is black on yellow.

If you wish to display Tips for particular objects in different fonts and colours, you must create a separate TipField for each combination of colour and font you need.


ToolBar Object

Properties Events Methods

Purpose | To manage a group of controls such as Buttons.
Parents | ActiveXControl, CoolBand, Form, SubForm
Children | Bitmap, BrowseBox, Button, Calendar, Circle, Combo, ComboEx, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, Menu, Metafile, MsgBox, OCXClass, Poly, ProgressBar, Rect, RichEdit, Scroll, SM, Spinner, Static, SubForm, Text, Timer, TrackBar, TreeView, UpDown

Description

The ToolBar object is used to display and manage a set of controls. It is typically used to present a set of Buttons which the user can press to perform various actions. However, the ToolBar has the ability to manage other controls too.

By default, the ToolBar is a raised bar stretched across the top of its parent form. You can alter its appearance using its EdgeStyle property and you can control its alignment with its Align property. Align can be set to Top (the default), Bottom, Left or Right and causes the ToolBar to be attached to the corresponding edge of the Form. A ToolBar aligned Top or Bottom will automatically stretch or shrink horizontally when its parent Form is resized, but it will remain fixed vertically. A ToolBar aligned Left or Right will stretch vertically but will remain fixed horizontally. By default a ToolBar occupies the entire width or length of the side of the Form to which it is attached and is 30 pixels high or wide. You can change these defaults using the Posn and Size properties.

A ToolBar organises its child controls in the order they are created. The way this is done is governed by the value of the Align property. If Align is Top or Bottom, the ToolBar arranges its controls in rows across the screen. If Align is Left or Right, the ToolBar arranges controls in columns.

The first control added to a ToolBar is automatically positioned 2 pixels down and 2 pixels across from its top left corner. The rule for positioning subsequent controls depends upon the value of the Align property.

If Align is 'Top' or 'Bottom', controls are positioned so as to be horizontally adjacent to one another. Whenever a control is added it is positioned relative to the one that immediately preceded it so that its top left corner meets the top right corner of the previous one. The HScroll property determines what happens when the end of the ToolBar is reached. If HScroll is 0 (the default) a control that would otherwise extend beyond the width of the ToolBar is instead positioned immediately below the first control in the ToolBar, thereby starting a new row. Note however that the ToolBar is not automatically resized vertically to accommodate a second row. If you want a multi-row ToolBar you have to set its height explicitly. If HScroll is ¯1 or ¯2, controls continue to be added along the ToolBar even though they extend beyond its right edge and may be scrolled into view using a mini scrollbar. If HScroll is ¯1, the scrollbar is shown whether or not any controls extend beyond the width of the ToolBar. If HScroll is ¯2, the scrollbar appears only if required and may appear or disappear when the user resizes the parent Form.

If Align is 'Left' or 'Right', controls are positioned so as to be vertically adjacent to one another. Whenever a control is added, its top left corner is positioned against the bottom left corner of the previous control. The VScroll property determines what happens when the bottom of the ToolBar is reached. If VScroll is 0 (the default) a control that would otherwise extend beyond the bottom of the ToolBar is instead positioned immediately to the right of the first one; thereby starting a new column. Note however that the ToolBar is not automatically resized horizontally to accommodate a second column. You must set the width of the ToolBar explicitly. If VScroll is ¯1 or ¯2, controls continue to be added down the ToolBar even though they extend beyond its bottom edge and may be scrolled into view using a mini scrollbar. If VScroll is ¯1, the scrollbar is shown whether or not any controls extend beyond the bottom of the ToolBar. If VScroll is ¯2, the scrollbar appears only if required and may appear or disappear when the user resizes the parent Form.

If you specify a value for its Posn property, a control will be placed at the requested position regardless of the value of Style, VScroll or HScroll. However, the next control added will take its default position from the previous one according to the value of these properties. Thus if you wish to group your controls together with spaces between the groups, you need only specify the position of the first one in each group.


ToolButton Object

Properties Events Methods

Purpose | The ToolButton object represents a button in a ToolControl.
Parents | ToolControl
Children | Bitmap, Timer

Description

The ToolButton object represents a selectable button in a ToolControl object.

A ToolButton displays a text string, defined by its Caption property, and an image defined by its ImageIndex property. Apart from these characteristics, the appearance of a ToolButton is controlled by its parent ToolControl object.

ImageIndex is an index into an ImageList which contains a set of icons or bitmaps. The ImageList itself is named by the ImageListObj property of the parent ToolControl.

Typically, you will create up to three ImageLists as children of the ToolControl. These will be used to specify the pictures of the ToolButton objects in their normal, highlighted (sometimes termed hot) and inactive states respectively. The set of images in each ImageList is then defined by creating unnamed Bitmap or Icon objects as children. Finally, when you create each ToolButton you specify ImageIndex, selecting the three pictures which represent the three possible states of the button.

If you specify only a single ImageList, the picture on the ToolButton will be the same in all three states.

The behaviour and appearance of a ToolButton is further defined by its Style property, which may be 'Push', 'Check', 'Radio', 'Separator' or 'DropDown'.

Push buttons are used to generate actions and pop in and out when clicked.

Radio and Check buttons are used to select options and have two states, normal (out) and selected (in). Their State property is 0 when the button is in its normal (unselected state) or 1 when it is selected.

Separator buttons are a special case as they have no Caption or picture, but appear as vertical lines used to separate groups of buttons.

A group of adjacent ToolButtons with Style 'Radio' defines a set in which only one of the ToolButtons may be selected at any one time. The act of selecting one will automatically deselect any other. Note that a group of Radio buttons must be separated from Check buttons or other groups of Radio buttons by ToolButtons of another Style.

A ToolButton with Style 'DropDown' has an associated popup Menu object which is named by its Popup property. There are two cases to consider.

If the ShowDropDown property of the parent ToolControl is 0, clicking the ToolButton causes the popup menu to appear. In this case, the ToolButton itself does not itself generate a Select event; you must rely on the user selecting a MenuItem to specify a particular action.

If the ShowDropDown property of the parent ToolControl is 1, clicking the dropdown button causes the popup menu to appear; clicking the ToolButton itself generates a Select event, but does not display the popup menu.

Example 1 illustrates the use of DropDown buttons.


ToolControl Object

Properties Events Methods

Purpose | The ToolControl object provides a Windows 95/NT ToolBar.
Parents | ActiveXControl, CoolBand, Form, SubForm
Children | Bitmap, BrowseBox, Button, Combo, ComboEx, Cursor, Edit, FileBox, Font, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Menu, MenuBar, Metafile, MsgBox, OCXClass, ProgressBar, RichEdit, Scroll, SM, Spinner, Static, SubForm, Timer, ToolButton, TrackBar, TreeView, UpDown

Description

The ToolControl object provides an interface to the native Windows ToolBar control and supersedes the Dyalog APL ToolBar object.

The tools on a ToolControl are normally represented by ToolButton objects, but the ToolControl may also act as a parent for other objects, including a MenuBar (see below).

Unlike the ToolBar, the ToolControl fully determines the positioning of its children automatically and this is governed by their order of creation. The Posn property of any child of a ToolControl is therefore read-only. Furthermore, the height of objects in a ToolControl may be no greater than that of a ToolButton in the same ToolControl. This in turn is governed by the sizes of the FontObj and ImageList in use in that ToolControl.

If a ToolControl is the child of a Form, its position and orientation is defined by its Align property. This property is ignored if the ToolControl is the child of a CoolBand.

The overall appearance of the ToolButton objects displayed by the ToolControl is defined by the Style property of the ToolControl itself, rather than by individual ToolButtons. This may be 'Buttons', 'FlatButtons', 'List' or 'FlatList'. The appearance of these different styles is illustrated in Example 1.

The presence or absence of a recessed line drawn above, below, to the left of, or to the right of the ToolControl is controlled by the Divider property whose default is 1 (show divider).

The MultiLine property specifies whether or not ToolButtons (and other controls) are arranged in several rows (or columns) when there are more than will otherwise fit. If MultiLine is 0 (the default), the ToolControl object clips its childen and the user must resize it to bring more objects into view. Example 2 illustrates the effect of MultiLine on the ToolControl.

The Transparent property specifies whether or not the ToolControl is transparent. If so, the visual effect is as if the ToolButtons (and other controls) were drawn directly on the parent Form as illustrated by Example 3.

The ShowCaptions property specifies whether or not the captions of ToolButton objects are drawn. Its default value is 1 (draw captions). ToolButtons drawn without captions occupy much less space and ShowCaptions provides a quick way to turn captions on/off for user customisation.

The ShowDropDown property specifies whether or not a drop-down menu symbol is drawn alongside ToolButtons which have Style 'DropDown'. ShowDropDown also affects the behaviour of such ToolButton objects when clicked.

As a special case, the ToolControl may contain a MenuBar as its only child. In this case, Dyalog APL causes the menu items to be drawn as buttons as shown in Example 4. Although nothing is done to prevent it, the use of other objects in a ToolControl containing a MenuBar, is not supported.


TrackBar Object

Properties Events Methods

Purpose | The TrackBar object is a slider control that allows the user to enter a value by positioning a pointer (thumb) on a scale.
Parents | ActiveXControl, CoolBand, Form, Grid, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Icon, Marker, Poly, Rect, Text, Timer

Description

The TrackBar object consists of a window which contains a slider bar, a thumb, and a set of tick marks. The slider in a TrackBar moves in increments that you specify when you create it. For example, if you specify that the TrackBar should have a range of five, the slider can only occupy six positions: a position at the left side of the TrackBar and one position for each increment in the range. Typically, each of these positions is identified by a tick mark. TrackBars can have either a vertical or horizontal orientation. They can have tick marks on either side, both sides, or neither. A selection of different TrackBars is illustrated below.

The position and size of the container window are defined by the Posn and Size properties. Its appearance is defined by the EdgeStyle, Border and BCol properties. The defaults are ('EdgeStyle' 'None'), ('Border' 0) and ('BCol' 0). The default background colour ('BCol' 0) obtains either the standard Window Background colour, or grey to match the colour of the parent object if it has a 3-dimensional appearance.

The orientation of a TrackBar is determined by the HScroll and VScroll properties. A horizontal TrackBar is obtained by setting HScroll to ¯1 and VScroll to 0. This is the default. A vertical TrackBar is obtained by setting VScroll to ¯1 and HScroll to 0.

The ShowThumb property determines whether or not the thumb is visible. Its default value is 1. You may toggle this property dynamically using ⎕WS.

The TrackBar optionally displays tick marks at the two ends of the slider bar and spaced out along it. This behaviour is determined by the HasTicks property which may be 1 (the default) or 0 and may be set only when the object is created by ⎕WC.

If HasTicks is 1, the position and frequency of the tick marks is determined by the TickAlign and TickSpacing properties. Note that TickAlign may only be set when the TrackBar is created with ⎕WC and may not be altered using ⎕WS.

The slider and tick marks in a horizontal TrackBar are drawn along the top of the enclosing window. The slider and tick marks in a vertical TrackBar are drawn along the left edge of the window. The position and size of the slider and the thumb may be obtained from the TrackRect and ThumbRect properties which report these values in pixels. These are read-only properties and cannot not be set with ⎕WC or ⎕WS.

The value of the TrackBar is determined by its Thumb property which is an integer that may be set with ⎕WS or retrieved with ⎕WG. The Limits property specifies the minimum and maximum values of Thumb corresponding to its position at the two ends of the slider bar. The Step property is a 2-element integer vector defining the small and large increments by which the Thumb moves. A small step is obtained by pressing a cursor movement key; a large step is achieved by clicking the left mouse button either side of the thumb or by pressing Page Up and Page Down. The user may also drag the thumb to a new position or move it directly to either end of the slider by pressing Home or End.

An alternative form of the TrackBar is obtained by setting the Style property to 'Selection'. This may only be done when the object is created using ⎕WC. This style of TrackBar has a slider that is represented by a recessed thick white rectangle instead of a solid black line. Furthermore, you can select a range of values within the TrackBar by setting the SelRange property. This causes the TrackBar to display a solid blue bar within the white slider and to show the corresponding tick marks as small triangles. Note that there is no way for the user to change SelRange directly; you can only do this using ⎕WS.

In addition to the normal mouse events, the TrackBar generates a Scroll and ThumbDrag event. The Scroll event is the same event that is generated by a Scroll object and is reported when the user repositions the thumb. If enabled, the ThumbDrag event is reported continuously as the user drags the thumb with the mouse and may be used to synchronise the display of a corresponding value in another object.


TreeView Object

Properties Events Methods

Purpose | The TreeView object displays a hierarchical list of items.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Icon, ImageList, Marker, Poly, Rect, Text, Timer

Description

A TreeView object displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of sub-items associated with it. By clicking an item, the user can expand and collapse the associated list of sub-items.

The contents of a TreeView object are defined by the Items property; a vector of character vectors that specifies the item labels.

The ImageListObj, ImageIndex and SelImageIndex properties define bitmapped images corresponding to each item. The bitmapped images are drawn to the left of the item labels.

ImageListObj specifies the name of a single ImageList object that contains one or more bitmaps

ImageIndex and SelImageIndex are ⎕IO sensitive scalars, or vectors with the same length as the number of items in the object. The value in the ith element specifies the image for the ith item and is an index into the corresponding ImageList object. ImageIndex specifies the image displayed when an item is not selected, SelImageIndex specifies the image displayed when an item is selected.

If ImageListObj is specified, but ImageIndex is empty or not specified, the first bitmap in the ImageList is drawn alongside every item. If an element of ImageIndex or SelImageIndex specifies a value that does not correspond to a bitmap in the ImageList, no picture is drawn.

The structure of the items (i.e. the parent/child relationships of the items) is defined by the Depth property. This is either a scalar 0 (the default) which means that all items are root items, or it is a numeric vector of the same length as Items. Non-zero values in Depth indicate child items.

The HasLines property is 0, 1 or 2 and determines whether or not lines are drawn that link child items to their corresponding parent item. If HasLines is 0, no lines are drawn. If HasLines is 1, lines are drawn at all except the top level, i.e. the object does not link items at the root of the hierarchy. The default value for HasLines is 2 which provides lines at all levels including the root.

The HasButtons property determines whether or not the TreeView object has a button to the left side of each parent item. It is boolean with a default value of 1. The user can click the button to expand or collapse the child items as an alternative to double-clicking the parent item. Note that by itself, setting HasButtons to 1 does not add buttons to items at the root of the hierarchy. To achieve this you must also set HasLines to 2.

The CheckBoxes property specifies whether or not check boxes are displayed alongside items in a TreeView.

The FullRowSelect property specifies whether just the item itself, or the entire row of the TreeView, is highlighted when an item is selected. FullRowSelect should not be used if HasLines is 1 or 2

When the user presses the left mouse button over an item, the object generates an ItemDown event. This is followed by an ItemUp event when the mouse button is released. The object also generates an ItemDblClick event when the left mouse is double-clicked over an item. If all three events are enabled, they are reported in the order ItemDown, ItemDblClick, ItemUp.

When a parent item is in its retracted state (its children are not visible) it can be expanded to show its children by the user double-clicking its label or by clicking over its button or tree lines. An Expanding event is reported immediately before the children are shown. Similarly, when a parent item is in its expanded state, it can be retracted to hide its children when a Retracting event is reported. You can use the Expanding event to define new children for the object just before they are shown. You can also control the actions of these events using callback functions.

The EditLabels is a boolean property (default 0) that determines whether or not the user may edit the labels which are specified by the Items property.

The SelItems property is a boolean vector that indicates which of the items is currently selected and has the focus. If more items are visible than can fit within the object, a scrollbar is automatically provided. The Index property is a ⎕IO sensitive integer that reports the index number of the first item displayed in the object and changes as the items are scrolled.


UpDown Object

Properties Events Methods

Purpose | The UpDown object is a pair of arrow buttons used to increment or decrement a value.
Parents | ActiveXControl, CoolBand, Form, Group, PropertyPage, SubForm, ToolBar, ToolControl
Children | Bitmap, Circle, Cursor, Ellipse, Font, Icon, Marker, Poly, Rect, Text, Timer

Description

An UpDown object is a pair of arrow buttons that the user can click to increment or decrement a value, such as a scroll position or a number displayed in a companion control. The Spinner object is actually a composite object consisting of an UpDown and a companion Edit.


Accelerator Property

Applies to: ActiveXControl, Bitmap, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, Cursor, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Icon, Image, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuItem, Metafile, Poly, Printer, ProgressBar, Rect, RichEdit, Scroll, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, Text, ToolBar, ToolButton, TrackBar, TreeView, UpDown

Description

This property specifies a keystroke that, when pressed by the user, will generate a Select event on an object. It applies to all objects whether or not they posses a “natural” Select event. You can therefore associate a keystroke with an arbitrary action on any object you desire.

The Accelerator property is a 2-element integer vector. The first element is a key number which is the number by which Windows knows the key. The second element is the shift state which is the sum of 1 (Shift key), 2 (Control key) and 4 (Alt key).

For example, to attach the keystroke Ctrl+A to an object, you would set its Accelerator to (65 2). To attach the keystroke Shift+Ctrl+F1 (key number 112), you would set its Accelerator to (112 3). Key numbers may be obtained by displaying the messages generated by the KeyPress event.

Note that a keystroke used as an Accelerator will not generate a KeyPress event.


AcceptFiles Property

Applies to: ActiveXControl, Animation, Button, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Image, Label, List, ListView, ProgressBar, PropertyPage, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, TrackBar, TreeView, UpDown

The AcceptFiles property is Boolean and specifies whether or not an object will accept a file drag/drop operation. Its default value is 0. If set to 1, the object will report a DropFiles event when file icons are dropped on it.


Active Property

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, Menu, MenuItem, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, Spinner, Splitter, Static, StatusBar, SubForm, TabBar, TabBtn, Text, Timer, ToolBar, ToolButton, TrackBar, TreeView, UpDown

Description

This property specifies whether or not an object is currently responsive to user actions. It is a single number with the value 0 (object is inactive and does not generate events) or 1 (object is active and capable of generating events). The default is 1.

Setting Active to 0 disables the object (and all its children), even though the object may be referenced in the argument to ⎕DQ. It is therefore possible to deactivate an object from a callback function.

In general, the text associated with an object whose Active property is 0 is displayed in grey.


Align Property

Applies to: Animation, Button, CoolBar, DateTimePicker, ListView, Menu, MenuItem, Scroll, Spinner, Splitter, StatusBar, StatusField, TabBar, TabBtn, TabControl, ToolBar, ToolControl

Description

For an Animation, the Align property may be 'None' or 'Centre' ('Center'). If Align is 'None', the Animation window is automatically resized to fit the AVI being played. If Align is 'Centre', the AVI is centred in the Animation window. If the window is too small, the AVI is clipped.

For a Button, Menu, or MenuItem the Align property may be 'None', 'Left' or 'Right'. If the Button Style is 'Radio' or 'Check' this property specifies the position of the text relative to the button symbol. The default is 'Right'. For a Button with Style 'Push', the value of Align is 'None'.

For a Button with Style 'Radio' or 'Check' that is created as a child of a Grid the value of the Align property may also be 'Centre' or 'Center'. Either of these values causes the symbol part of the Button (the circle or checkbox) to be centred within the corresponding Grid cell(s).

For a DateTimePicker, the Align property specifies the horizontal alignment of the drop-down Calendar which may be 'Left' (the default) or 'Right'. This applies only if the Style of the DateTimePicker is 'Combo'.

For a Menu , MenuItem, or StatusField, Align 'Right' is used to position the object at the right end of its parent MenuBar or StatusBar. 'None' is equivalent to 'Left' which is the default.

For objects of type CoolBar, Splitter, Scroll, StatusBar, TabBar, ToolBar and ToolControl, Align may be 'None', 'Top', 'Bottom', 'Left' or 'Right'. It specifies to which (if any) of the four sides of the parent the object is anchored and also the default position and size of the object. Specifying Align typically causes the Attach property to be set to appropriate values as follows :

Align | Attach
'Top' | 'Top' 'Left' 'Top' 'Right'
'Bottom' | 'Bottom' 'Left' 'Bottom' 'Right'
'Left' | 'Top' 'Left' 'Bottom' 'Left'
'Right' | 'Top' 'Right' 'Bottom' 'Right'

These settings cause the object to remain at a fixed distance (in pixels) from the corresponding edge of the parent. Furthermore, the object will have a fixed height or width, but its length will stretch and shrink as the Form is resized.

Note that this does not apply to a TabControl for which the default value of Attach is 'None' 'None' 'None' 'None', regardless of the value of Align.

The default value of Align is 'Right' for a vertical Scroll, 'Bottom' for a horizontal Scroll, and 'Top' for a CoolBar, TabBar, TabControl, ToolBar and ToolControl. Furthermore, unless Posn and Size are specified explicitly, the object is placed along the corresponding edge of its parent.

For a Scroll object, Align also determines the direction of a Scroll object unless it is overridden by setting Hscroll or Vscroll directly. If neither Hscroll or VScroll is defined and Align is 'Top' or 'Bottom', a horizontal scrollbar is provided. If neither Hscroll or Vscroll is defined and Align is 'None', 'Left' or 'Right', a vertical scrollbar is provided.

Note
The value of the Align property may only be assigned by ⎕WC and may not be changed using ⎕WS.


AlignChar Property

Applies to: Grid

The AlignChar property specifies a character on which the data displayed in a column of a Grid is to be aligned vertically. It is useful to align columns of numbers that are formatted by the FormatString property. AlignChar may be a scalar or singleton that applies to all columns of the Grid, or a vector with one element per column.

If the data in the column is left-justified, it is aligned using the first occurrence of the alignment character in each cell counting from the left. If the data is right-justified, it is aligned using the first occurrence of the alignment character from the right-hand end of the text.

If the text in a cell does not contain an alignment character, it is aligned as if the alignment character were placed following the last digit.


AlphaBlend Property

Applies to: Form

The AlphaBlend property specifies a level of translucency which allows the area behind a Form to show through.

AlphaBlend is a scalar integer value in the range 0 to 255.

A value of 255 (the default) specifies no translucency, and the Form is entirely opaque obliterating anything behind it.

A value of 0 specifies total translucency and the Form itself is not visible. Furthermore, mouse events over the Form will not be reported by the Form itself but will be passed to any other windows underneath the Form.

Values in between specify varying levels of translucency.


AlwaysShowBorder Property

Applies to: Grid

The AlwaysShowBorder property specifies whether or not the border around the current cell in a Grid is displayed when the Grid loses the focus.

It is a Boolean value with a default value of 1.


AlwaysShowSelection Property

Applies to: Grid, ListView, TreeView

The AlwaysShowSelection property specifies whether or not the selection remains highlighted when the object loses the focus.

It is a Boolean value with a default value of 1.

If AlwaysShowSelection is 1, the highlight is dimmed. If AlwaysShowSelection is 0, the highlight disappears.


ArcMode Property

Applies to: Circle, Ellipse

Description

This property determines how arcs are drawn. Its value is 0, 1 or 2.

0 | only the arc is drawn
1 | arcs define "arc segments", with a single straight line joining the two ends of the arc together
2 | arcs define "pie segments", with lines drawn from the start and end points of the arc to the centre

Note that the segments defined by ArcMode 1 and 2 may be filled (by setting FStyle).


Array Property

Applies to: Clipboard

Description

This property may be used to set or retrieve the contents of the Windows clipboard as a Dyalog APL array.


Attach Property

Applies to: Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Grid, Group, Label, List, ListView, MDIClient, NetControl, ProgressBar, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, TabControl, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

This property specifies how an object responds to its parent being resized. It is a 4-element vector of character vectors which defines how each of the four edges of the object moves in response to a resize request made by the parent. Note that this property is only effective if the value of AutoConf on the parent is 2 or 3 and AutoConf for the object itself is 1 or 3.

The 4 elements of Attach refer to the Top, Left, Bottom and Right edges of the object respectively. Their values may be defined as follows :

Element | Value | Meaning
[1] | 'Top' | top edge of object attached to top edge of parent.
 | 'Bottom' | top edge of object attached to bottom edge of parent.
 | 'None' | top edge of object is not attached to its parent
[2] | 'Left' | left edge of object is attached to left edge of parent
 | 'Right' | left edge of object is attached to right edge of parent
 | 'None' | left edge of object is not attached to its parent
[3] | 'Top' | bottom edge of object is attached to top edge of parent.
 | 'Bottom' | bottom edge of object is attached to bottom edge of parent.
 | 'None' | bottom edge of object is not attached to its parent
[4] | 'Left' | right edge of object is attached to left edge of parent
 | 'Right' | right edge of object is attached to right edge of its parent
 | 'None' | right edge of object is not attached to its parent

If an edge of the object is attached to an edge of its parent, its position in absolute (pixel) terms remains fixed relative to that edge when its parent is resized. Thus if Coord is 'Pixel',the corresponding Posn or Size property of the object remains unaffected by the resize. If Coord has any other value, the value of Posn or Size will change.

If an edge of the object is not attached to its parent, its absolute position (in pixels) will change in proportion to the size change (in the corresponding direction) of its parent. Thus if Coord is 'Pixel',the corresponding Posn or Size property of the object will change as a result of the resize. If Coord has any other value, the value of Posn or Size will be unaffected.

The default value of Attach is ('None' 'None' 'None' 'None'). This causes the object to reposition and resize itself in proportion to its parent.

Some objects have an Align property which, among other things, provides a quick way to set their Attach property. Examining this mechanism may help to further explain how the Attach property works. Setting Align to 'Top' has the effect of setting Attach to ('Top' 'Left' 'Top' 'Right'). Attaching the top edge of the object to the top edge of its parent causes the object to remain at a fixed distance from the top edge of its parent. The additonal measure of attaching its bottom edge to the top edge of its parent causes the height of the object to remain fixed. Attaching the left and right edges of the object to the corresponding edges of its parent causes the object to shrink and expand as the parent is resized horizontally. If you position the object at (0 0) and set its width to be the same as the width of its parent, you have an object that always occupies the entire length of its parent, yet remains of fixed height. This is precisely the behaviour required for a ToolBar or a top Scroll Bar. For further details, see Align property.


AutoArrange Property

Applies to: ListView

The AutoArrange property is Boolean and specifies whether or not the items in a ListView object are automatically re-arranged when a single item is repositioned. Its default value is 0.


AutoBrowse Property

Applies to: OLEClient

This property is retained for backwards compatibility with previous versions of Dyalog APL, but is no longer relevant. Setting it has no effect.


AutoConf Property

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Image, Label, List, ListView, Marker, Poly, ProgressBar, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, Text, ToolBar, TrackBar, TreeView, UpDown

Description

This property determines what happens to an object when its parent is resized, and how resizing an object affects its children. It may take one of the following values; the default is 3.

0 | Ignore resize by parent.Do not propagate resize to children.
1 | Accept resize by parent.Do not propagate resize to children.
2 | Ignore resize by parent.Do propagate resize to children.
3 | Accept resize by parent.Do propagate resize to children.

If AutoConf is 0 or 2, the object's physical size (in pixels) and position (in pixels) relative to the top left corner of its parent remains unchanged when its parent is resized. If the object has 'Prop' or 'User' co-ordinates, the values of its Posn and Size properties will change as a result.

If AutoConf is 1 or 3, by default, the object is physically reconfigured when its parent is resized such that its relative size and position within its parent remain unchanged. If the object has 'Pixel' co-ordinates, the values of its Posn and Size properties will change as a result. Note that this default processing can be prevented by inhibiting the Configure (31) Event.

If AutoConf is 0 or 1 and the object is resized, either by its parent or directly by the user, it does not attempt to physically reconfigure its children. This means that if the children have 'Prop' or 'User' co-ordinates, the values of their Posn and Size co-ordinates will change as a result.

If AutoConf is 2 or 3 and the object is resized, either by its parent or directly by the user, it propagates a Configure (31) Event to each of its children. By default this means that the object's children will be physically reconfigured so that they maintain their relative positions and sizes within it. If their co-ordinate system is 'Pixel', the values of their Posn and Size properties will change as a result.

Note
Additional or alternative control may be imposed by inhibiting the Configure (31) Event. This can be done either by setting the event's "action" code to ¯1 or by returning a 0 from a callback function attached to it.


AutoExpand Property

Applies to: Grid

Description

This property is a 2-element boolean value that specifies whether or not rows and columns may be added to a Grid object by the user.

If the first element of AutoExpand is 1, a row is added when the current cell is within the last row of the Grid and the user presses Cursor Down

Similarly, if the second element is 1, a column is added when the current cell is within the last column of the Grid and the user presses Cursor Right.

Note that when a row or column is added, the appropriate properties (including Values and CellTypes)are expanded accordingly.

The default value for AutoExpand is (0 0).

If AutoExpand is enabled, the Grid generates AddRow and AddCol events. You can return a zero from a callback function to selectively prevent the addition of rows and columns if appropriate.


AutoPlay Property

Applies to: Animation

Specifies whether or not an AVI clip is played immediately when loaded in an Animation object.

AutoPlay is a single number with the value 0 (the default) or 1. If AutoPlay is 1, the AVI clip is automatically played through once from beginning to end when loaded from a file by the AnimOpen method.


APLVersion Property

Applies to: Root

Description

This is a read-only property that provides information about the Version of Dyalog APL that you are using. It is a.4-element vector of character vectors containing:

[1] | the target environment
[2] | the version
[3] | the version type ('W'=Windows, 'M'=Motif, 'P'=Pocket APL)
[4] | 'Development' or 'Runtime' or 'DLL'
      DISPLAY '.' ⎕WG'APLVersion'
.→-------------------------------------.
| .→------. .→-----. .→. .→----------. |
| |Windows| |10.0.1| |W| |Development| |
| '-------' '------' '-' '-----------' |
'∊-------------------------------------'


BandBorders Property

Applies to: CoolBar

The BandBorders property specifies whether or not narrow lines are drawn to separate adjacent bands in a CoolBar.

BandBorders is a single number with the value 0 (no lines) or 1 (lines are displayed); the default is 0.

The effect of BandBorders is illustrated below.


BaseClass Property

Applies to: NetType

This property specifies the name of the .Net class upon which the NetType is based. The newly created NetType inherits the properties, methods and events of this class.


BCol Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Button, Circle, Combo, ComboEx, CoolBand, CoolBar, Edit, Ellipse, Form, Grid, Group, Label, List, ListView, MDIClient, Menu, MenuItem, Poly, ProgressBar, Rect, RichEdit, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, Text, TipField, ToolBar, TrackBar, TreeView, UpDown

Description

This property defines the background colour(s) of an object. For objects with more than one constituent part, it may specify a set of background colours, one for each part. A single colour is represented by a single number which refers to a standard colour, or by a 3-element vector which defines a colour explicitly in terms of its red, green and blue intensities.

If BCol is 0 (which is the default) the background colour is defined by your current colour scheme for the object in question. For example, if you select yellow as your MS-Windows "Menu Bar" colour, you will by default get a yellow background in Menu and MenuItem objects, simply by not specifying BCol or by setting it to 0.

A negative value of BCol refers to a standard MS-Windows colour as described below. Positive values are reserved for a possible future extension.

BCol | Colour Element | BCol | Colour Element
0 | Default | ¯11 | Active Border
¯1 | Scroll Bars | ¯12 | Inactive Border
¯2 | Desktop | ¯13 | Application Workspace
¯3 | Active Title Bar | ¯14 | Highlight
¯4 | Inactive Title Bar | ¯15 | Highlighted Text
¯5 | Menu Bar | ¯16 | Button Face
¯6 | Window Background | ¯17 | Button Shadow
¯7 | Window Frame | ¯18 | Disabled Text
¯8 | Menu Text | ¯19 | Button Text
¯9 | Window Text | ¯20 | Inactive Title Bar Text
¯10 | Active Title Bar Text | ¯21 | Button Highlight

If BCol is set to ⍬ (zilde), the object is drawn with a transparent background.

If BCol contains a 3-element vector, it specifies the intensity of the red, green and blue components of the colour as values in the range 0-255. For example, (255 0 0) is red and (255 255 0) is yellow.

Note that the colour realised depends upon the capabilities of the display adapter and driver, and the current Windows colour map.

For a Button, BCol is only effective if the Style is 'Radio' or 'Check' and is ignored if the Style is 'Push'.

It is recommended that you only use pure background colours in Combo and Edit objects. This is because the text written in these objects cannot itself have a dithered background.

For the Ellipse, Poly and Rect objects, BCol specifies the background colour of the line drawn around the perimeter of the object and is effective only when a non-solid line (LStyle 1-4) is used. It also specifies the colour used to fill the spaces between hatch lines if a hatch fill (FStyle 1-6) is used.


Bits Property

Applies to: Bitmap, Clipboard, Cursor, Icon

Description

This property defines the pattern in a Bitmap, Cursor, or Icon object, or the pattern of a bitmap stored in the Windows clipboard.

For a Bitmap, Clipboard or Icon, Bits is an integer matrix each of whose elements represents the colour of the corresponding pixel in the bitmap. The colours are specified as 0-origin indices into the CMap property, which itself defines the complete set of different colours (the colour map) used by the object.

Please note that Bits and CMap may only be used to represent an image with a colour palette of 256 colours or less. If the colour palette is larger, the values of Bits and CMap reported by ⎕WG will be (0 0). For a high-colour image, use Cbits instead.

For a Cursor, Bits is a boolean matrix which specifies the shape of the cursor. For a Cursor and Icon, Bits is used in conjunction with the Mask property.

See CMap for further details.


Border Property

Applies to: ActiveXControl, Animation, Button, Calendar, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, TabBtn, ToolBar, TrackBar, TreeView, UpDown

Description

This property specifies whether or not an object is displayed with a border around it. It is a single number with the value 0 (no border)1 (Border), or 2. The value 2 applies only to a Form and is used in combination with ('EdgeStyle' 'Dialog') to obtain standard dialog box appearance

For a Form or SubForm, the value of the Border property is only relevant if Sizeable, Moveable, SysMenu, MaxButton and MinButton are all 0.

Note
The value of the Border property may only be assigned by ⎕WC and may not be changed using ⎕WS.


BrowseFor Property

Applies to: BrowseBox

The BrowseFor property is a character vector that specifies the type of resource to be the target of a object.

BrowseFor may be 'Directory' (the default), 'File', 'Computer' or 'Printer'.


Btns Property

Applies to: MsgBox

Description

The Btns property determines the set of buttons to be displayed in a MsgBox. It is a simple vector (one button) or a matrix with up to 3 rows, or a vector of up to 3 character vectors specifying the captions for up to 3 buttons. The buttons are arranged along the bottom of the dialog box in the order specified.

Under Windows, there are restrictions on these buttons. However the property has been designed more generally to be useful under different GUIs and perhaps later revisions of Windows.

Under Windows, the Btns property may specify one of six sets of buttons as follows.

  1. 'OK'
  2. 'OK' 'CANCEL'
  3. 'RETRY' 'CANCEL'
  4. 'YES' 'NO'
  5. 'YES' 'NO' 'CANCEL'
  6. 'ABORT 'RETRY' 'IGNORE'

If any other combination is specified, ⎕WC and ⎕WS will report a DOMAIN ERROR. The names of the buttons are however case-insensitive, so the system will accept 'ok', 'Ok', 'oK' or 'OK'.

If the Btns property is not specified, it assumes a default according to Style as follows :

Style | Btns
'Msg' or 'Info' | 'OK'
'Warn' or 'Error' | 'OK' 'CANCEL'
'Query' | 'YES' 'NO'

If Style is not specified, Btns defaults to 'OK'.


BtnPix Property

Applies to: Button, Menu, MenuItem

Description

This property is used to customise the appearance of a Button, Menu or MenuItem. It specifies the names of or refs to up to 3 Bitmap objects to be used to display the object under different circumstances. In general, BtnPix is a 3-element vector of character vectors or refs. However, if it defines a single Bitmap, it may be a single ref, a simple character scalar or vector, or an enclosed character vector.

The first Bitmap is displayed when the object is shown in its normal state. For a Button, this is when its State is 0. The second Bitmap is used for a Menu or MenuItem, when the object is selected (highlighted), or for a Button when its State is 1. The third Bitmap is used when the object is disabled by having its Active property set to 0.

For a Button with Style 'Push', this means that when the user clicks the Button, its appearance switches from the first to the second Bitmap, and then back again. To maintain the standard 3-D appearance, the Bitmaps should contain the correct shadow lines around their edges. For Buttons with Style 'Radio' or 'Check', the Button will display one or other of the two Bitmaps according to its current State.

For example, to have a Button that displays a "Tick" or a "Cross" according to its State :

      'YES' ⎕WC 'Bitmap' 'C:\WDYALOG\YES.BMP'
      'NO'  ⎕WC 'Bitmap' 'C:\WDYALOG\NO.BMP'
      'f1.r1' ⎕WC 'Button'('Style' 'Check')('BtnPix' 'YES' 'NO')


CalendarCols Property

Applies to: Calendar, DateTimePicker

The CalendarCols property specifies the colours used for various elements in the Calendar object.

CalendarCols is a 6-element integer vector whose elements specify the colours as follows:

[1] | Background colour displayed between months
[2] | Background colour displayed within the month.
[3]
 Text colour within a month
[4]
 Background colour displayed in the calendar's title
[5]
 Colour used to display text within the calendar's title
[6] | Colour used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Each element of CalendarCols may be 0 (which means default colour), a negative singleton that specifies a particular Windows colour, or a 3-element integer vector of RGB values.

Note: At the time of writing, setting the first element of CalendarCols has no effect. Dyalog believes this to be a Windows problem that may be corrected in due course.


Cancel Property

Applies to: Button

Description

This property determines which (if any) Push button in a Form or SubForm is to be associated with the Escape key. It has the value 1 or 0.

Pressing the Escape key will generate a Select event on the Button whose Cancel property is 1, regardless of which object has the keyboard focus.

As only one button in a Form or SubForm can be the Cancel button, setting Cancel to 1 for a particular button automatically sets Cancel to 0 for all others in the same Form.


Caption Property

Applies to: BrowseBox, Button, ColorButton, CoolBand, FileBox, Form, Group, Label, Menu, MenuItem, MsgBox, PropertyPage, PropertySheet, Root, StatusField, SubForm, TabBtn, TabButton, ToolButton

Description

The Caption property is a character vector specifying fixed text associated with the object. For example, Caption defines the label on a Button, the title of a Form, SubForm or MsgBox, the heading in a Group, and the text of a Menu or a MenuItem.

For the Root object, Caption specifies the text displayed when Alt+Tab is used to switch to the Dyalog APL/W application. It may be used in conjunction with the IconObj property which specifies the name of an Icon object to be displayed alongside this text.

Its default value is an empty vector.


CaseSensitive Property

Applies to: ComboEx

Specifies whether or not string searches in the items displayed by a ComboEx object will be case sensitive. Searching occurs when text is being typed into the edit box portion of the ComboEx


CBits Property

Applies to: Bitmap, Clipboard

The CBits property represents the picture in a Bitmap object.

CBits provides an alternative representation to that provided by the Bits and Cmap properties which apply only to bitmaps with 256 colours or under. CBits may be used to represent both low-colour and high-colour bitmaps.

CBits is a rank-2 numeric array whose dimensions represent the rows and columns of pixels in the Bitmap. The values in CBits represent the colour of each pixel.

The colour value of each pixel is obtained by encoding the red, green and blue components, i.e.

      PIXEL←256⊥RED GREEN BLUE

where RED, GREEN and BLUE are numbers in the range 0-255.


CellFonts Property

Applies to: Grid

Description

This property specifies the font objects to be used to display the Values in a Grid object.

CellFonts is either a single ref or a simple character vector, or a vector of refs or character vectors. If it specifies a single font object this will be used to draw the text in all of the cells in the Grid. If it specifies more than one font object, these are mapped to individual cells through the CellTypes property.


CellHeights Property

Applies to: Grid

Description

This property specifies the height of each row in a Grid object in the units specified by its Coord property. It may be a scalar or a vector whose length is the same as the number of rows implied by the Values property. If it is a scalar, it specifies a constant row height. If it is a vector it specifies the height of each row individually.


CellSelect Property

Applies to: Grid

Description

The Grid supports the selection of a contiguous block of cells by the user, using the mouse and/or the keyboard. The ability to select a range of cells is determined by the CellSelect property. This may be a character vector or a vector of character vectors comprising the following :

'Rows' | User may select an entire row by clicking on a row title and may select multiple rows by dragging the mouse over contiguous row titles.
'MultiRows' | Same as 'Rows', but user may additionally select several non-contiguous rows and blocks of rows using the Ctrl key.
'Columns' | User may select an entire column by clicking on a column title and may select multiple columns by dragging the mouse over contiguous column titles.
'MultiColumns' | Same as 'Columns', but user may additionally select several non-contiguous columns and blocks of columns using the Ctrl key.
'Partial' | User may select any rectangular block of cells by either dragging the mouse or using Shift+cursor keys.
'MultiPartial' | Same as 'Partial', but user may additonally select multiple rectangular blocks of cells using the Ctrl key.
'Whole' | User may select the entire Grid by clicking in the space to the left of the column titles and above the row titles.
'Any' | Same as ('Rows' 'Columns' 'Partial' 'Whole'). This is the default.
'Multi' | Same as ('MultiRows' 'MultiColumns' 'MultiPartial' 'Whole').
'None' | User may not select any cells in the Grid.

For example, the following expression would allow the user to select only whole rows and columns:

      gridname ⎕WS 'CellSelect' ('Rows' 'Columns')

Setting CellSelect to ('Rows' 'Columns' 'Whole' 'Partial') is equivalent to setting it to 'Any'.

When the user performs a selection , the Grid generates a GridSelect event.

The range of cells currently selected is given by the SelItems property. You can obtain the current selection by querying this property with ⎕WG and you can set it with ⎕WS.

Note that the user may delete the contents of the selected range, or cut and copy them to the clipboard by pressing Delete, Shift+Delete or Ctrl+Insert respectively. The user may also replace the current selection with the contents of the clipboard by pressing Shift+Insert. These operations generate GridDelete, GridCut, GridCopy and GridPaste events which you may disable (by setting the event action code to ¯1 or to which you may attach a callback function.

If more than one block of cells has been selected, these operations are honoured only if the blocks begin and end on the same rows or begin and end on the same columns. If so, the data placed in the clipboard is the result of joining the blocks horizontally or vertically as appropriate.

You can also invoke these events as methods. This allows you to attach these actions to MenuItems and Buttons. For example, the following expression could be used to implement Cut as a MenuItem:

      name ⎕WC 'MenuItem' 'Cu&t'('Event' 'Select' '⍎gridname.GridCut')

In addition to the ability to copy blocks of cells through the clipboard, the user may also drag a block of cells from one part of the Grid to another.

When the user places the mouse pointer over any of the four edges of a selected block of cells, the cursor changes from a cross to a n arrow pointer. The user may now drag the border of the selected block to a new location. If the Ctrl key is pressed at the same time, the contents of the selected cells are copied to the new location. If not, the operation is a move and the original block of cells is cleared (emptied). In either case, the contents of the original block replace the contents of the target block (marked by the dragging rectangle) and the target block become selected. You may only move or copy a single block of cells in this way.

These operations generate a GridDropSel event. You may prevent the user from moving and copying blocks of cells by disabling this event (by setting its event action code to ¯1) or you may control these operations selectively with a callback function. Note that although the operation of inserting cells (using Ctrl+Shift) has not been implemented, you may provide this facility yourself with the information provided by the event message.

You may also move or copy a block of cells (which need not necessarily be selected) under program control by calling GridDropSel event as a method.


CellSet Property

Applies to: Grid

Description

This property identifies which cells in a Grid are set (i.e. have values) and which are empty. Its purpose is to allow large numeric matrices containing blank cells to be displayed and edited efficiently.

The CellSet property is a boolean matrix with the same shape as the Values property. If an element of CellSet is 0, the cell is defined to be empty. Empty cells are displayed as blank and the cell contents by the Values property are ignored.

A more direct way to handle empty cells is to set the corresponding elements of Values to empty vectors. However, if Values is otherwise entirely numeric, this makes the array nested when it would otherwise be simple. For large numeric matrices, this penalty can be severe. For example, a 100x100 array of 2-byte integer values occupies about 20Kb of workspace. Setting one or more elements of the array to an empty vector increases its size to 200Kb. However, because it is boolean, the size of the CellSet property for a 100x100 array is only 1.27Kb and represents a significant saving of space.

Note that if the Values property contains text and is therefore nested anyway, the CellSet property is not helpful in conserving workspace, although it may still be useful to separate empty cells from real data.

You can dynamically change a single element of CellSet using the SetCellSet method.


CellTypes Property

Applies to: Grid

Description

This property specifies the type of each cell in a Grid object. It is a matrix whose elements are indices into other property arrays (FCol, BCol, CellFonts and Input).

For example, if CellTypes[1;1] is 3, the first cell in the Grid is displayed using the foreground colour specified by the 3rd element of FCol, the background colour specified by the 3rd element of BCol, and so forth. Note however that scalar property arrays are extended if necessary. Therefore if you require 5 different foreground colours but only one background colour, BCol need specify only a single colour.

You can dynamically change a single element of CellTypes using the SetCellType method.


CellWidths Property

Applies to: Grid

Description

This property specifies the width of each column in a Grid object in the units specified by its Coord property. It may be a scalar or a vector whose length is the same as the number of columns implied by the Values property. If it is a scalar, it specifies a constant column width. If it is a vector it specifies the width of each column individually.


Changed Property

Applies to: Edit, PropertyPage, RichEdit, Spinner

The Changed property, in conjunction with the Change event, provides the means to control the validation of an object after the user has finished interacting with it.

Initially, the value of the Changed property of an object is set to 0. When the user gives the focus to the object and causes either the Text or (in the case of a Spinner) the Thumb property to be altered, the Changed property is immediately set to 1. When the object loses the input focus and the value of the Changed property is 1, the object generates a Change event. The value of the Changed property is then determined as follows:

If there is no callback function attached to the Change event, or if the Change event is disabled, the Changed property is reset to 0.

If an attached callback returns no result or returns 1, the Change property is reset to 0.

If an attached callback function returns 0, the Changed property is not altered and remains set to 1. The object will therefore generate another Change event when the user next tries to leave it, even if the text and/or Thumb are not altered this time.

Note that the object generates a Change event when it loses the focus only if the value of the Changed property is 1 at the time.


CharFormat Property

Applies to: RichEdit

The CharFormat property describes or applies formatting to the currently selected text in a RichEdit object. If the selection is empty, it reports or specifies the default character formatting for the object. It is a 5-element nested array structured as follows:

[1]

A vector of character vectors which describes the text attributes and is comprised of the following keywords:

'Autocolour' | default colour (Windows text colour)
'Bold' | bold text
'Italic' | bold text
'Underline' | underlined
'StrikeOut' | line through text
'Protected' | protected (read-only) text

[2]

A character vector that specifies the face name of the font used to draw the text

[3]

Character height in Twips.

[4]

Text colour. A single integer or an enclosed vector of 3 RGB values. The default is 0 which implies the standard Windows text colour.

[5]

Integer specifying the vertical offset of the character from the base line in Twips. This is used to specify superscript (positive offset) and subscript (negative offset) symbols. The default value is 0.

When you set the character format using ⎕WC or ⎕WS the following rules apply.

If you just want to set a single text attribute (element 1) you may specify a simple vector, for example (⎕WS 'CharFormat' 'Protected') is valid and will add the protected text attribute to the current set of text attributes.

To unset a text attribute (element 1) you must insert the tilde (~) character before the name of the attribute. For example, the expression (⎕WS 'CharFormat' '~Bold') will turn the bold text attribute off.

You need only specify the number of elements required, but you must insert proper values for the elements you wish to remain unaltered. However, you may use '' in the first element to leave the text attributes unchanged.

If there is no text selected, CharFormat specifies the default character format, i.e. the format that will be used to draw the next (and subsequent) characters that the user enters. If there is text selected it specifies the format of the selected block of text. If the format is not strictly homogeneous, ⎕WG may report the format of the first character in the selected block, or, if the block contains characters which use completely different fonts, the result of (⎕WG 'CharFormat') will be empty.

(⎕WS 'CharFormat' ...) will set the format of the currently selected block of text. To set the format of an arbitrary block of text you must select it first using (⎕WS 'SelText' ...).


CharSet Property

Applies to: Font

This property applies to the Classic Edition only. In the Unicode Edition, its value is ignored.

CharSet is an integer that specifies the character encoding of the Font object.

The following table illustrates some of the character set encodings supported by Windows. Note that this set may vary according to the edition of Windows that is installed.

Language | CharSet
Western (Ansi) | 0
Hebrew | 177
Arabic | 178
Greek | 161
Turkish | 162
Baltic | 186
Central European | 238
Cyrillic | 204
Vietnamese | 163

Windows fonts typically contain glyphs for the ASCII character set in their first 128 positions, and glyphs for the Western European character set in positions 129-256. Additional sets of character glyphs are stored in positions 257 onwards in what are sometimes referred to as codepages.

When you change the character set encoding, to (say) Greek (161), the set of Greek characters are mapped into the top 128 positions of the font.

For example, if the CharSet is 0 (ANSI), the character code Hex EC is displayed as ì (i-grave). However, if you change CharSet to 161 (Greek), the same character code is displayed as the Greek µ.

The following example illustrates how the character string 'ôï üíïìá ìïõ Ýéíáé Ðåôå' appears differently according to the value of CharSet.

      'F'⎕WC'FORM' 'CharSet Property'('Size' 300 400)('Coord' 'Pixel')
      F.Coord←'Prop'

      'F.F1'⎕WC'Font' ('Size' 32) ('CharSet' 0)
      'F.F2'⎕WC'Font' ('Size' 32) ('CharSet' 161)
      'F.F3'⎕WC'Font' ('Size' 32) ('CharSet' 178)

      STRING←'ôï üíïìá ìïõ Ýéíáé Ðåôå'

      'F.E1'⎕WC'Edit'STRING(10 10)(⍬ 80)('Font' 'F.F1')
      'F.E2'⎕WC'Edit'STRING(40 10)(⍬ 80)('Font' 'F.F2')('Translate' 'ANSI')
      'F.E3'⎕WC'Edit'STRING(70 10)(⍬ 80)('Font' 'F.F3')('Translate' 'ANSI')

Note that setting Translate to 'ANSI' means that characters entered into the Edit fields using a corresponding National Language keyboard (Greek and Arabic) will appear in that language as intended


Checked Property

Applies to: MenuItem

Description

This property determines whether or not a check mark is displayed alongside the text in a MenuItem. It is a single number with the value 0 (not checked) or 1 (checked). The default is 0.


CheckBoxes Property

Applies to: ListView, TreeView

The CheckBoxes property specifies whether or not check boxes are displayed alongside items in a ListView or TreeView object.

CheckBoxes is a single number with the value 0 (check boxes are not displayed) or 1 (check boxes are displayed); the default is 0.

For a TreeView, CheckBoxes will only be honoured if the items have pictures associated with them (via the ImageListObj and ImageIndex properties).

For a ListView, CheckBoxes applies to all settings of the View property.

The GetItemState method can be used to determine if a specific item in a ListView or TreeView is checked. The result of the method will have the 13th bit set if the item is checked.

      STATE←Form.ListView.GetItemState 11
      13⊃⌽(32⍴2)⊤STATE
1

The picture below illustrates the effect on the appearance of a ListView object, of setting CheckBoxes to 1.


ChildEdge Property

Applies to: CoolBand

The ChildEdge property specifies whether or not the CoolBand leaves space above and below its child window.

ChildEdge is a single number with the value 0 (no space) or 1 (space is provided); the default is 0.

The following pictures illustrate the effect of the ChildEdge property.


ChildList Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetControl, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

This is a read-only property that reports the names of those objects that may be created as children of the object in question. It is a vector of character vectors in which the order of the items is not significant.


CircleToday Property

Applies to: Calendar, DateTimePicker

The CircleToday property specifies whether or not a circle is drawn around the Today date in a Calendar object or in the drop down calendar in a DateTimePicker, when the month containing that date is visible.

CircleToday is a single number with the value 0 (a circle is not drawn) or 1 (a circle is drawn); the default is 1.

See also HasToday property.


ClassID Property

Applies to: ActiveXControl, OCXClass, OLEClient, OLEServer

The ClassID property specifies the class identifier (usually abbreviated to CLSID) of an APL object that is used to represent a COM object. The CLSID is a globally unique identifier (GUID) that uniquely identifies the object.

When you create or recreate an ActiveXControl or OLEServer using ⎕WC, you may specify ClassID. This allows you to re-use a value that was previously allocated to that control by the system. However, you should not specify any other value because that value could be allocated now or in the future to another object on any other computer in the world. Otherwise, a new ClassID is automatically allocated by the system.

Note that the CLSID is not actually recorded on your computer (in the registry) until you register it using )SAVE or Make OCX, or by executing the OLERegister method.


ClassName Property

Applies to: ActiveXControl, NetControl, OCXClass, OLEClient, OLEServer

For an OLEClient, the ClassName property specifies the name of the OLE object to which an OLEClient object named by the left argument of ⎕WC is to be connected. Similarly, for a NetControl the ClassName property specifies the name of the .Net class to be instantiated. Note that ClassName is mandatory for ⎕WC and may not subsequently be changed using ⎕WS.

For an ActiveXControl or OLEServer, ClassName specifies the external name with which the object is registered, and by which it is referenced by other applications.

For an ActiveXControl, the external name is “Dyalog xxx Control, where xxx is the value of the ClassName property, or, if ClassName is not specified, the name of the ActiveXControl namespace.

For an OLEServer, the external name is “Dyalog.xxx” where xxx is derived in the same way.

For a NetControl, the external name is the name of the .Net class which must be expressed relative to a corresponding element of ⎕USING. For example, to load one of the standard .Net controls:

      ⎕USING,←⊂'System.Windows.Forms,system.windows.forms.dll'


ClipCells Property

Applies to: Grid

Description

This property determines whether or not the Grid displays partial cells. The default is 1. If you set ClipCells to 0, the Grid displays only complete cells and automatically fills the space between the last visible cell and the edge of the Grid with the GridBCol colour.

The first picture below shows a default Grid (ClipCells is 1) in which the third column of data is in fact incomplete (clipped), although this is by no means apparent to the user. The second picture shows the effect on the Grid of setting ClipCells to 0 which prevents such potential confusion.


Collate Property

Applies to: Printer

Specifies whether or not multiple copies of printer output are collated.

Collate is a single number with the value 0 or 1. If Collate is 1, multiple copies of output are collated separately. If Collate is 0, copies are uncollated on output.

Collate is ignored unless Copies is >1.

The default value for Collate is derived from the current printer setting and Collate is only effective if the printer supports this capability.


ColLineTypes Property

Applies to: Grid

This property specifies the appearance of the vertical grid lines in a Grid object.

ColLineTypes is an integer vector, whose length is normally equal to the number of columns in the Grid. Each element in ColLineTypes specifies an index into the GridLineFCol and GridLineWidth properties, thus selecting the colour and width of the vertical grid lines.

For example, if ColLineTypes[1] is 3, the first vertical grid line in the Grid is displayed using the colour specified by the 3rd element of GridLineFCol, and the width specified by the 3rd element of GridLineWidth.

Note that ColLineTypes is not ⎕IO dependant, and the value 0 is treated the same as the value 1; both selecting the first colour and line width specified by GridLineFCol and GridLineWidth respectively

The default value of ColLineTypes is an empty numeric vector (<—>). If so, all vertical grid lines are drawn using the first element of GridLineFCol and GridLineWidth.

A vertical grid line is drawn down the right edge of its associated column. One pixel is drawn inside the column of cells; additional pixels (if any) are drawn between that column of cells and the next one to its right.


ColorMode Property

Applies to: Printer

Specifies whether or not printing is done in colour.

ColorMode is a single number with the value 0 or 1. If ColorMode is 1, printing is done in colour. If ColorMode is 0, printing is done using black ink only.

This property only applies to colour printers.


ColSortImages Property

Applies to: Grid

The ColSortImages property identifies the names of, or refs to, up to three Bitmap objects that are used to specify the sort images for a Grid object.

If ColSortImages is not specified, default images are used.

The Bitmap specified by the 1st element of ColSortImages is used to display columns that are sorted down.

The Bitmap specified by the 2nd element of ColSortImages is used to display columns that are unsorted.

The Bitmap specified by the 3rd element of ColSortImages is used to display columns that are sorted up.

      'F'⎕WC'Form' 'Grid: ColSortImages Property'
      'F.G'⎕WC'Grid'('Posn' 0 0)(100 100)
      F.G.Values←(COUNTRIES,POPULATION,[1.5]AREA)
      F.G.ColTitles←'Country' 'Population' 'Area'
      F.G.TitleWidth←0

      'GD'⎕WC'BITMAP' 'gd.bmp'('MaskCol'(255 255 255))
      'GU'⎕WC'BITMAP' 'gu.bmp'('MaskCol'(255 255 255))
      F.G.ColSortImages←'GD' '' 'GU'
      F.G.(Values←Values[⍋Values[;3];])

      F.C.ColSorted 3 1


ColumnWidth Property

Applies to: List

This property specifies the column width in pixels of a multi-column List object. See MultiColumn property for details.


ColTitles Property

Applies to: Grid, ListView

Description

This property specifies the headings that are displayed above the columns in a Grid object. If specified, it must be a vector of character vectors or matrices whose length is the same as the number of columns implied by the Values property. The default value of ColTitles is an empty character vector. In this case, the system displays “standard” spreadsheet column titles A-Z, AA-AZ, BA-BZ and so forth.

To disable the display of column titles in a Grid, you should set the TitleHeight property to 0.


ColTitle3D Property

Applies to: Grid, ListView

The ColTitle3D property is a boolean value that specifies whether or not the column titles in a ListView object are displayed with a 3-dimensional effect. Its default value is 1. A column heading with a 3-dimensional button appearance may be used to imply that the user may click on it to sort by the values in that column.

ColTitle3D is only relevant if View is 'Report' and Header is 1. Note that this property may only be set by ⎕WC and may not subsequently be changed using ⎕WS.


ColTitleAlign Property

Applies to: Grid, ListView

The ColTitleAlign property specifies the alignment of column titles. For a ListView object this is only relevant only when the View property is set to 'Report'. ColTitleAlign is either a simple character vector, or a vector of character vectors with one element per column.

For a Grid, ColTitleAlign may be:'Top','Bottom', 'Left', 'Right', 'Centre', 'TopLeft', 'TopRight', 'BottomLeft', or 'BottomRight'.

For a ListView object, ColTitleAlign may be 'Left', 'Right' or 'Centre'. Also, for a ListView the column data itself is aligned likewise. Note that the first column in a ListView is always left-aligned regardless of the setting of ColTitleAlign. This is a Windows restriction.

Note that both spellings 'Centre' and 'Center' are accepted.


ColTitleBCol Property

Applies to: Grid

The ColTitleBCol property specifies the background colour of the column titles in a Grid object

ColTitleBCol may be a scalar that specifies a single background colour to be used for all of the column titles, or a vector that specifies the background colour of each of the column titles individually. An element of ColTitleBCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see Bcol for details). Its default value is 0 which obtains the colour defined for Button Face.


ColTitleDepth Property

Applies to: Grid

ColTitleDepth specifies the structure of a set of hierarchical column titles. It is an integer vector with the same length as the ColTitles property. A value of 0 indicates that the corresponding element of ColTitles is a top-level title. A value of 1 indicates that the corresponding title is a sub-title of the most recent title whose ColTitleDepth is 0; a value of 2 indicates that the corresponding title is a sub-title of the most recent title whose ColTitleDepth is 1, and so forth. For example:

      'F'⎕WC'Form'('Coord' 'Pixel')('Size' 200 498)
      'F'⎕WS'Caption' 'Hierarchical Column Titles'
      'F.G'⎕WC'Grid'(?10 12⍴100)(0 0)(200 498)
      'F.G'⎕WS('TitleWidth' 0)('TitleHeight' 60)
      'F.G'⎕WS'CellWidths' 40

      Q1←'First Quarter' 'Jan' 'Feb' 'Mar'
      Q2←'Second Quarter' 'Apr' 'May' 'Jun'
      Q3←'Third Quarter' 'Jul' 'Aug' 'Sep'
      Q4←'Fourth Quarter' 'Oct' 'Nov' 'Dec'

      CT←(⊂'1995'),Q1,Q2,Q3,Q4
      CD←0,16⍴1 2 2 2

      'F.G'⎕WS('ColTitles'CT)('ColTitleDepth'CD)

Note that the LockColumns method is not supported in combination with hierarchical column titles.


ColTitleFCol Property

Applies to: Grid

Description

The ColTitleFCol property specifies the colour of the column titles in a Grid object

ColTitleFCol may be a scalar that specifies a single colour to be used for all of the column titles, or a vector that specifies the colour of each of the column titles individually. An element of ColTitleFCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). . Its default value is 0 which obtains the colour defined for Button text.


Container Property

Applies to: ActiveXControl

The Container property is a read-only property whose value is the ⎕OR of an ActiveXContainer object that represents the ActiveX Site object of the application that is hosting the ActiveXControl.

The value of Container may be converted to a namespace using ⎕NS or ⎕WC.

The resulting object may then be used to obtain the values of ambient properties, or to access methods exposed by the host application via OLE interfaces. See OLEQueryInterface.


Copies Property

Applies to: Printer

Specifies the number of copies to be printed.

Copies is a non-zero scalar integer value whose default is defined by the current printer settings.


Coord Property

Applies to: ActiveXControl, Animation, Bitmap, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Image, Label, List, ListView, Locator, Marker, MDIClient, Menu, Metafile, NetControl, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, TabBar, Text, ToolBar, TrackBar, TreeView, UpDown

Description

This property defines an object's co-ordinate system. It is a character string with one of the following values; 'Inherit', 'Prop', 'Pixel', 'User' or 'Cell' (graphics children of a Grid only).

If Coord is 'Inherit', the co-ordinate system for the object is inherited from its parent. Note that the default value of Coord for the system object '.' is 'Prop', so by default all objects created by ⎕WC inherit 'Prop'.

If Coord is 'Prop', the origin of the object's parent is deemed to be at its top left interior corner, and the scale along its x- and y-axes is 100. The object's position and size (Posn and Size properties) are therefore specified and reported as a percentage of the dimensions of the parent object, or, for a Form, of the screen.

If Coord is 'Pixel', the origin of the object's parent is deemed to be at its top left interior corner, and the scale along its x- and y-axes is measured in physical pixel units. The object's size and position (Posn and Size properties) are therefore reported and set in physical pixel units. If you set Coord on the system object to 'Pixel', the value of its Size property gives you the resolution of your screen, e.g. (480,640). Note that pixels are numbered from 0 to (Size -1).

If Coord is 'User', the origin and scale of the co-ordinate system are defined by the values of the YRange and XRange properties of the parent object. Each of these is a 2-element numeric vector whose elements define the co-ordinates of top left and bottom right interior corners of the (parent) object respectively.

Note that if Coord is 'User' and you change the values of YRange and/or XRange of the parent, the object (and all its siblings with Coord 'User') are redrawn (and clipped) according to the new origin and scale defined for the parent. The values of their Posn, Size and Points properties are unaffected. Changing YRange and/or XRange therefore provides a convenient and efficient means to "pan and zoom".

The Coord property for graphic objects created as a children of a Grid may also be set to Cell. Apart from being easier to compute, a graphic drawn using cell coordinates will expand and contract when the grid rows and columns are resized.

Example:

This statement creates a button 10 pixels high, 20 pixels wide, and 5 pixels down and along from the top-left corner of the parent Form.

      'TEST.B1'⎕WC'Button' 'OK'(5 5)(10 20)('Coord' 'Pixel')

If you set Coord to 'Pixel' in the Root object '.', then query its Size, you get the dimensions of the screen in pixels, i.e.

      '.' ⎕WS 'Coord' 'Pixel'
      '.' ⎕WG 'Size'
480 640


CurrentColor Property

Applies to: ColorButton

The CurrentColor property is a 3-element integer vector that specifies and reports the RGB value of the currently selected colour in a ColorButton object. Its default value is (0 0 0) which is black.


CurrentState Property

Applies to: TCPSocket

The CurrentState property is a read-only property that reports the current state of a TCPSocket object. Its possible values and their means are as follows:

CurrentState | Description
'Open' | a client socket that is not yet connected or a UDP socket
'Bound' | a server socket that has been bound
'Listening' | a server socket to which a client has not yet connected
'Connected' | a client or server socket that is connected
'IhaveClosed' | a temporary state on the way to Closed
'PartnerHasClosed' | a temporary state on the way to Closed
'Closed' | a socket that has been closed by both client and server


CursorObj Property

Applies to: ActiveXControl, Button, Calendar, Circle, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Label, List, ListView, Locator, MDIClient, Poly, ProgressBar, Rect, RichEdit, Root, Scroll, SM, Spinner, Splitter, Static, StatusBar, SubForm, TabBar, Text, ToolBar, TrackBar, TreeView, UpDown

Description

This property is used to associate a particular cursor with an object. Its value is either a simple scalar number which specifies a standard Windows cursor, or the name of, or ref to, a Cursor object. The standard Windows cursors are :

0 | arrow (Windows default)
1 | hourglass
2 | crosshair
3 | I-Beam
4 | crossing vertical/horizontal double-headed arrows
5 | diagonal double-headed arrows (left-to-right)
6 | vertical double-headed arrows
7 | diagonal double-headed arrows (right-to-left)
8 | horizontal double-headed arrows
9 | upward pointing arrow
10 | box
11 | crossing vertical/horizontal double-headed arrows
12 | no-entry sign
13 | arrow with hourglass

If CursorObj is set to anything other than an empty vector (which is the default) it defines the appearance of the cursor when the mouse pointer is moved into the object. If CursorObj is an empty vector, the shape of the cursor remains unchanged when the mouse pointer enters the object. In effect, the cursor is "inherited" from its parent. Exceptions to this rule are certain objects which have special cursors by default.

If the value of CursorObj for the Root object is set to anything other than an empty vector, it applies to all Forms and their children, irrespective of their own CursorObj values. Therefore, if you want to indicate that your application is "working" and is not responsive to input, you can simply do :

      '.' ⎕WS 'CursorObj' 1 ⍝ Hourglass cursor

Then to reset the application you do :

      '.' ⎕WS 'CursorObj' ''


CurCell Property

Applies to: Grid

Description

This property specifies or reports the current cell in a Grid object. The current cell is the one that is currently addressed by the user. The current cell is identified visibly if it has an associated object, other than an external. Label object


CustomColors Property

Applies to: ColorButton

The CustomColors property is a 1-row, 16-column nested matrix which specifies the RGB values of the colours displayed in the Custom colors section of the Windows colour selection dialog box when displayed by a ColorButton object.

Each element of CustomColors is a 3-element integer vector specifying an RGB colour value.

By default, each element of CustomColors is (0 0 0). If the user selects a new custom colour from the Windows colour selection dialog box, its value will be reported by CustomColors. CustomColors must always have shape (1 16).

Note that CustomColors is maintained separately for each separate ColorButton, and CustomColors defaults to (1 16⍴⊂0 0 0) for each new ColorButton that you create. If you want to maintain a global custom colour table for your application, you must do this yourself.

Note that the Pocket PC 2002 colour selection dialog box does not provide the facility to select custom colours, so this functionality is not available in PocketAPL.


CustomFormat Property

Applies to: DateTimePicker

Specifies a custom format for the date/time display in a DateTimePicker.

CustomFormat is a character vector that may contain a mixture of date/time format elements and body text. The date/time elements are replaced by the actual date/time values when the object is displayed. The body text is displayed as-is. Note that CustomFormat may only be specified when the DateTimePicker object is created.

The date/time elements are defined by the following groups of characters, notice that they are case-sensitive:

Element

Description

d | The one- or two-digit day.
dd | The two-digit day. Single-digit day values are preceded by a zero.
ddd | The three-character weekday abbreviation.
dddd | The full weekday name.
h | The one- or two-digit hour in 12-hour format.
hh | The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
H | The one- or two-digit hour in 24-hour format.
HH | The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
m | The one- or two-digit minute.
mm | The two-digit minute. Single-digit values are preceded by a zero.
M | The one- or two-digit month number.
MM | The two-digit month number. Single-digit values are preceded by a zero.
MMM | The three-character month abbreviation.
MMMM | The full month name.
t | The one-letter AM/PM abbreviation (that is, AM is displayed as "A").
tt | The two-letter AM/PM abbreviation (that is, AM is displayed as "AM").
yy | The last two digits of the year (that is, 1996 would be displayed as "96").
yyyy | The full year (that is, 1996 would be displayed as "1996").

The body text is defined by sub-strings contained within single quotes. For example, to display the current date with the format "Today is: 04:22:31 Tuesday Mar 23, 1996", the format string is defined as follows:
      CustomFormat
'Today is: 'hh':'m':'s dddd MMM dd', 'yyyy

To include a single quote in your body text, use two consecutive single quotes. For example, to produce output that looks like: "Don't forget Mar 23, 1996", CustomFormat should be specified as follows:

        CustomFormat
'Don''t forget' MMM dd',' yyyy
Note:
Non format characters that are not delimited by single quotes will result in unpredictable display by the DateTimePicker object.


CMap Property

Applies to: Bitmap, Clipboard, Cursor, Icon

Description

This property defines the table of colours (the colour map) used by a Bitmap or Icon object or by a bitmap stored in the Windows clipboard. Its value is a 3-column integer matrix of numbers in the range 0-255. Each row represents a separate colour which is indexed (0-origin) by values in the Bits property. The 3 columns refer to the intensities of the red, green and blue components of colour respectively.

Please note that Bits and CMap may only be used to represent an image with a colour palette of 256 colours or less. If the colour palette is larger, the values of Bits and CMap reported by ⎕WG will be (0 0). For a high-colour image, use Cbits instead.

When you create a Bitmap or Icon by specifying Bits and CMap, the actual colours you obtain are not necessarily those that you specified. This is partly due to hardware restrictions and partly due to the way in which Windows manages colours. Firstly, your display adapter and driver limit the number of pure colours that can be displayed at any one time and therefore define a maximum size for the colour map. For example, on a standard VGA you are limited to 16 different pure colours (additional ones are provided by dithering).

Secondly, Windows reserves a certain number of colours in the colour map for its own use. When an application requests a new colour (i.e. one that is not already installed in the colour map), MS-Windows either assigns it to a spare entry, or allocates the closest match if the colour map is full. The value of Bits and CMap after ⎕WC reflect the actual colours allocated and may bear little resemblance to the values you assigned to these properties initially.

Note that if you are running 16 colours, MS-Windows reserves all 16 entries in the colour map for its own use. This means that on a 16-colour system, you cannot use any colours other than the default ones reserved by MS-Windows. In practice, the "standard" 16-colour CMap is shown in the following table.

Bits[] | CMap |  |  | Colour
1 | 0 | 0 | 0 | Black
2 | 128 | 0 | 0 | Dark red
3 | 0 | 128 | 0 | Dark Green
4 | 128 | 128 | 0 | Olive Green
5 | 0 | 0 | 128 | Dark Blue
6 | 128 | 0 | 128 | Dark Magenta
7 | 0 | 128 | 128 | Dark Cyan
8 | 128 | 128 | 128 | Dark Grey
9 | 192 | 192 | 192 | Light Grey
10 | 255 | 0 | 0 | Red
11 | 0 | 255 | 0 | Green
12 | 255 | 255 | 0 | Yellow
13 | 0 | 0 | 255 | Blue
14 | 255 | 0 | 255 | Magenta
15 | 0 | 255 | 255 | Cyan
16 | 255 | 255 | 255 | White

The default 16-colour CMap

If you are using a 256-colour set-up, the first 9 and the last 7 entries of the 256-colour CMap are the same as the first 9 and last 7 entries of the 16-colour CMap shown above. The intervening entries represent additional colours or are initially unused (0 0 0). New colours that you specify will be allocated to unused entries until the table is full.


Data Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This property allows you to associate arbitrary data with an object. The value of the Data property may be any APL array.


DateTime Property

Applies to: DateTimePicker

Specifies the value of date/time in a DateTimePicker.

The DateTime property represents the date and time value that is currently displayed in a DateTimePicker object.

It is normally a 4-element integer vector containing the date (as an IDN), hour, minutes and seconds respectively.

However, if the checkbox shown in the object is unset (see HasCheckBox), the value of DateTime will be ⍬ (zilde).


DblClickToggle Property

Applies to: CoolBar

The DblClickToggle property specifies whether or not the user must single-click or double-click to toggle a child CoolBand between its maximised or minimised state.

DblClickToggle is a single number with the value 0 (single-click toggles state) or 1 (double-click toggles state); the default is 0.


Decimals Property

Applies to: Edit, Label, Spinner

Description

This property specifies the number of decimal places to which a number is to be displayed in an Edit or Label object with FieldType 'Numeric'. For an Edit object, Decimals also specifies the maximum number of digits that the user may enter after a decimal point.

The default value of decimals is ¯1 which allows any number of decimal places to be entered.


Default Property

Applies to: Button, MsgBox

Description

This property determines which of a set of push buttons in a Form, SubForm or MsgBox is the default button.

In a Form or SubForm, the Default Button will generate a Select event (30) when the user presses the Enter key, even though the Default Button may not have the focus at the time.

If however, the user explicitly shifts the focus to another Push Button, the automatic selection of the Default Button is disabled and the Enter key applies to the Button with the focus.

For a Button, the Default property has the value 1 or 0. As only one Button can be the Default Button, setting Default to 1 for a particular Button automatically sets Default to 0 for all others with the same parent.

In a MsgBox, Default specifies which button initially has the focus. It has the value 1, 2 or 3 corresponding to the three buttons that can be defined. See Btns property for further details.


DefaultColors Property

Applies to: ColorButton

The DefaultColors property is a nested matrix which specifies the RGB values of the colours shown in the colour selection drop-down displayed by a ColorButton object.

The shape of DefaultColors determines the number of rows and columns in the colour selection drop-down.

Each element of DefaultColors is a 3-element integer vector specifying an RGB colour value.


Depth Property

Applies to: TreeView

The Depth property specifies the structure of the items in a TreeView object. It is either a scalar 0 or an integer vector of the same length as the Items property.

A value of 0 indicates that the corresponding item is a top-level item. A value of 1 indicates that the corresponding item is a child of the most recent item whose Depth is 0; a value of 2 indicates that the corresponding item is a child of the most recent item whose Depth is 1, and so forth. For example:

AIRPORTS | DEPTH | Description
Europe | 0 | Top-level (root) item
UK | 1 | 1st sub-item of Europe
London Heathrow | 2 | 1st sub-item of UK
London Gatwick | 2 | 2nd sub-item of UK
Manchester | 2 | 3rd sub-item of UK
France | 1 | 2nd sub-item of Europe
Paris CDG | 2 | 1st sub-item of France
Americas | 0 | Top-level (root) item
USA | 1 | 1st sub-item of N.America
California | 2 | 1st sub-item of USA
Los Angeles | 3 | 1st sub-item of California
San Francisco | 3 | 2nd sub-item of California
East Coast | 2 | 2nd sub-item of USA
New York | 3 | 1st sub-item of East Coast
Kennedy | 4 | 1st sub-item of NY
La Guardia | 4 | 2nd sub-item of NY
      'F'⎕WC'FORM' 'International Airports'
      'F.TV'⎕WC'TreeView'AIRPORTS(0 0)(100 100)('Depth'DEPTH)


DevCaps Property

Applies to: Printer, Root

Description

This property reports the device capabilities of the screen or printer. It is a 3-element nested vector as follows :

[1] | Height and Width:2-element numeric vector of device in pixels
[2] | Height and Width:2-element numeric vector of device in mm
[3] | Number of colours:integer scalar

This property is useful if you want to make objects of a specific physical size. For example, to draw a 10mm square in a Form 'F' at (5,5):

      Size ← 10 × ⊃÷/2'.' ⎕WG 'DevCaps'
      'F.R' ⎕WC 'Rect' (5 5) Size ('Coord' 'Pixel')

Note that new elements may be added to DevCaps in a future release.

Please note that the physical size reported for the screen is typically only a nominal size, because, if you use a generic video driver, Windows has no way to tell that you have a 14”, 15” or 17” screen attached to your computer.


Directory Property

Applies to: FileBox

Description

The Directory property contains a simple character vector which specifies the initial directory from which a list of suitable files is displayed.

If, whilst interacting with the FileBox, the user changes directory and exits by pressing "OK" or by closing the FileBox, the value of the Directory property is updated accordingly.


Divider Property

Applies to: ToolControl

The Divider property controls the presence or absence of a recessed line drawn above, below, to the left of, or to the right of a ToolControl object.

Divider is a single number with the value 0 (dividing line is not drawn) or 1 (a dividing line is drawn); the default is 1.

The pictures below illustrates a ToolControl drawn with and without a divider.


DockableProperty

Applies to: CoolBand, Form, SubForm, ToolControl

The Dockable property specifies whether or not an object may be docked or undocked.

Dockable is a character vector containing 'Never' (the default), 'Always' or 'Disabled'.

If Dockable is 'Never', the object may not be docked or undocked by the user, and the docking menu items are not present in the object's context menu. This is the default.

If Dockable is 'Always', the object may be docked or undocked by the user, and the docking menu items are present in the object's context menu.

If Dockable is 'Disabled', the object may not currently be docked or undocked by the user, but the docking menu items are present in the object's context menu.

Note that by default, the user may switch between Dockable 'Always'and 'Disabled' by toggling the Dockable menu item. If you want to exercise full control over this property, you may implement your own context menu (see ContextMenu Event)


DockChildrenProperty

Applies to: CoolBar, Form, SubForm

The DockChildren property specifies the names of client objects that may be docked in a host object.

DockChildren may be a single ref or simple character scalar or vector, or a vector of refs or character vectors. Each item represents an object that may be docked. Notice that if you use a name, you must specify the simple name of the object, excluding any part of its full pathname that refers to a parent; i.e. the specified names must not contain any leading pathname information.

If the name of, or ref to, a dockable object occurs in the DockChildren property, the host object will generate DockMove events when the client is dragged over it, and will generate a DockAccept event when a docking operation takes place.

If the name of , or ref to, the client object is not present in its DockChildren property, the object will not respond in any way as the client is dragged over it.

The following example shows the creation of 3 forms, all of which are dockable in a host form called H1.

The first, C1, is a totally independent Form. When docked in H1, it will become a SubForm H1.C1. When undocked, it will revert to an independent Form C1.

The second, C2, is created initially as a child of H1 and will therefore be displayed above it in the window stacking order. When docked it will become a SubForm H1.C2. When undocked, it will revert back to a dependant Form H1.C2. In all cases, it appears on top of H1.

The third, C3, is created initially as a child of another Form, H2. When docked (in H1) it will become a SubForm H1.C3. When undocked, it will become a dependant Form H1.C3, and will therefore appear above H1 in the stacking order.

      'H1'⎕WC'Form' 'Host'

      'C1' ⎕WC 'Form' 'Client 1' ('Dockable' 'Always')
      'H1.C2' ⎕WC 'Form' 'Client 2' ('Dockable' 'Always')
      'H2.C3' ⎕WC 'Form' 'Client 3' ('Dockable' 'Always')
      Host.DockChildren←'C1' 'C2 'C3'


DockedProperty

Applies to: Form, SubForm

The Docked property is a read-only property that indicates whether or not an object is currently docked.

Docked is a single number with the value 0 (is not docked) or 1 (is docked).


DockShowCaptionProperty

Applies to: Form, SubForm

The DockShowCaption property specifies whether or not a Form displays a title bar when it is docked as a SubForm.

DockShowCaption is a single number with the value 0 or 1 (the default).

The DockShowCaption property may be toggled on and off by the user from the object's context menu.

The first picture below illustrates a Form, docked as a SubForm, whose DockShowCaption property is 1, but is about to be set to 0.

The next picture shows the same docked Form with DockShowCaption set to 0.


Dragable Property

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Grid, Group, Image, Label, List, ListView, Marker, Poly, ProgressBar, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusField, Text, TrackBar, TreeView, UpDown

Description

This property determines whether or not an object may be the subject of a "drag and drop" operation. It is a single number with the value 0, 1 or 2. A value of 0 (which is the default) means that the object may not be drag/dropped. A value of 1 means that the object may be drag/dropped and that during the "drag" operation, a box representing the bounding rectangle around the object is displayed on the screen. A value of 2 means that the outline of the object is displayed as the object is dragged, or, if the object is an Image with a Picture property containing the name of an Icon object, the icon itself is displayed as it is dragged. For rectangular non-graphical objects, values of 1 and 2 are equivalent.

If an object is Dragable, the user may drag it by positioning the mouse pointer within the object, depressing the left mouse button, then moving the mouse with the button held down. During the drag operation, the mouse pointer is automatically changed to a "drag" symbol. The object is "dropped" by releasing the left mouse button. The effect depends upon where it is dropped, and on the action associated with the DragDrop event for the object under the mouse pointer (if any).

If there is no object under the mouse pointer, the "drag and drop" operation is ignored. Otherwise, the object under the mouse pointer generates a DragDrop event.

If the object under the mouse pointer is the parent of the object that has been "dragged and dropped", the default action is for the system to move that object to the new location within its parent. If you wish to allow your user to freely move an object within its parent Form or Group, simply set its Dragable property to 1; the system will take care of the rest. If you want to allow the user to move an object, but you want to know about it when it happens, you can associate a callback function to the DragDrop event that queries the new position. To permit the operation to complete, the callback function should either not return a result or it should return something other than a scalar 0. To selectively disable movement, your callback function should return a scalar 0 in circumstances when the "drop" is not to be permitted.

If the object under the mouse pointer is not the parent of the object being dragged, the default action is for the system to ignore the operation. However, by enabling the DragDrop event, your application can of course take whatever action is appropriate, including perhaps moving the dragged object to a new parent.

Note that a Dragable object does not generate a Configure (31) event when it is dragged and dropped.


DragItems Property

Applies to: ListView

The DragItems property is boolean and specifies whether or not the items in a ListView object may be drag/dropped by the user. Its default value is 1.


DrawMode Property

Applies to: Circle, Ellipse, Marker, Poly, Rect, Text

The DrawMode property provides direct control over the low-level drawing operation performed by graphical objects.

The DrawMode property specifies the current foreground mix mode. The Windows GDI uses the foreground mix mode to combine pens and interiors of filled objects with the colours already on the screen. The foreground mix mode defines how colours from the brush or pen and the colours in the existing image are to be combined.

DrawMode affects every drawing operation performed by Dyalog APL and not just the initial drawing operation when the object is created. Many of the drawing modes are additive (the result depends not just on what is being drawn, but on what is already there) and the effects may therefore vary. For this reason, DrawMode should normally be used only with un-named graphical objects.

You could use DrawMode to move or animate graphical objects in circumstances where the standard Dyalog APL behaviour was not ideal.

DrawMode is an integer with one of the following values:

Value | Name | Resulting Pixel Colour
1 | R2_BLACK | Pixel is always 0.
2 | R2_NOTMERGEPEN | Pixel is the inverse of the R2_MERGEPEN colour.
3 | R2_MASKNOTPEN | Pixel is a combination of the colours common to both the screen and the inverse of the pen.
4 | R2_NOTCOPYPEN | Pixel is the inverse of the pen colour.
5 | R2_MASKPENNOT | Pixel is a combination of the colours common to both the pen and the inverse of the screen.
6 | R2_NOT | Pixel is the inverse of the screen colour.
7 | R2_XORPEN | Pixel is a combination of the colours in the pen and in the screen, but not in both.
8 | R2_NOTMASKPEN | Pixel is the inverse of the R2_MASKPEN colour.
9 | R2_MASKPEN | Pixel is a combination of the colours common to both the pen and the screen.
10 | R2_NOTXORPEN | Pixel is the inverse of the R2_XORPEN colour.
11 | R2_NOP | Pixel remains unchanged.
12 | R2_MERGENOTPEN | Pixel is a combination of the screen colour and the inverse of the pen colour.
13 | R2_COPYPEN | Pixel is the pen colour.
14 | R2_MERGEPENNOT | Pixel is a combination of the pen colour and the inverse of the screen colour.
15 | R2_MERGEPEN | Pixel is a combination of the pen colour and the screen colour.
16 | R2_WHITE | Pixel is always 1.


Duplex Property

Applies to: Printer

Specifies whether pages are printed on separate sheets or back-to-back.

Duplex is a character vector which is either empty or contains 'Simplex', 'Vertical', or 'Horizontal'.

The default value for Duplex is derived from the current printer setting and 'Vertical' and 'Horizontal' are only effective if the printer supports a duplex capability.


EdgeStyle Property

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, FileBox, Form, Grid, Group, Image, Label, List, ListView, MDIClient, Menu, MenuBar, MenuItem, MsgBox, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Static, StatusBar, StatusField, SubForm, TabBtn, ToolBar, TrackBar, TreeView, UpDown

Description

Note that EdgeStyle is not honoured for objects which have a natural built-in 3-dimensional appearance.

This property is used to give a 3-dimensional appearance to screen objects. This is achieved by drawing the object with a grey or white background colour and by drawing a border around it using various combinations of black, white and dark grey lines. Note that this border is drawn outside a control but inside a Form or SubForm. The value of the EdgeStyle property is a character vector chosen from the following :

'None' | Object is drawn with no 3-dimensional effects and the EdgeStyle properties of its children are ignored (treated as None).
'Plinth' | Object is drawn with a light shadow along its top and left edges and a dark shadow along its bottom and right edges. This gives the illusion of a raised effect.
'Recess'
 Object is drawn with a dark shadow along its top and left edges and a light shadow along its bottom and right edges. This gives the illusion of a sunken effect.
'Groove'
 Object is drawn with a border that has the appearance of a groove.
'Ridge'
 Object is drawn with a border that has the appearance of a ridge.
'Shadow'
 Object is drawn with a dark border line along its top and left edges.
'Default' | Object itself is drawn with no 3-dimensional border, but the values of the EdgeStyle properties of its children are observed.
'Dialog' | Used in conjunction with ('Border' 2), this gives a Form the appearance of a standard 3-dimensional dialog box. This setting applies only to a Form or a SubForm

For the Root object, the EdgeStyle property may be 'None' or 'Default'. If EdgeStyle is 'None', screen objects are drawn without 3-dimensional effects of any kind and the value of their EdgeStyle property is ignored. If EdgeStyle is 'Default', all controls are drawn using their default EdgeStyle properties.

Note that MsgBox, FileBox and the set-up dialog box associated with the Printer object are all drawn with 3-dimensional effects regardless of the value of EdgeStyle on Root. These objects do not have their own EdgeStyle properties.

If you set EdgeStyle to 'None' on the Root object, all your objects will (by default) be drawn without 3-dimensional effects.


EditImage Property

Applies to: ComboEx

Specifies whether or not the edit control portion of the ComboEx displays an image for selected items.

EditImage is a single number with the value 0 or 1 (the default). If EditImage is 1, the image associated with the selected item is displayed in the edit control, portion of the ComboEx object, to the left of the text. If EditImage is 0, only the item text is displayed in the edit control.


EditImageIndent Property

Applies to: ComboEx

Specifies whether or not the indents associated with items in a ComboEx object are honoured in the edit control portion of the ComboEx.

EditImageIndent is a single number with the value 0 or 1 (the default).

If EditImageIndent is 1, the selected item which is displayed in the edit control portion of the ComboEx object is indented in the same way as when it is displayed in the dropdown portion of the object. The amount of indentation is specified by the Indents property.

If EditImageIndent is 0, the item displayed in the edit control portion of the ComboEx is not indented.


EditLabels Property

Applies to: ListView, TreeView

The EditLabels property is boolean and specifies whether or not the labels (specified by the Items property) in a ListView or TreeView object may be edited by the user. Its default value is 0 (editing is not allowed).

If EditLabels is 1, the user begins editing by clicking the label of the item that has the focus. This causes a pop-up edit box to appear around the item and allows the use to change it. A BeginEditLabel event is reported at the start of the edit operation and an EndLabelEdit event is reported on its completion. You may control the edit of a particular label using callback functions attached to these events.


End Property

Applies to: Circle, Ellipse

Description

This property specifies one or more end-angles for an arc, pie-slice, or chord of a circle or ellipse. It may be used in conjunction with Start which specifies start angles. Angles are measured counter-clockwise from the x-axis at the centre of the object.

If a single arc is being drawn, End is a single number that specifies the end angle of the arc in radians (0 ⍎> ○2). If multiple arcs are being drawn, End is either a single number as before (the end angle for several concentric arcs) or a numeric vector with one element per arc.

If Start is not specified, the default value of End is ○2. Otherwise, the default value of End is ((¯1↓+\Start),○2).


EnterReadOnlyCells Property

Applies to: Grid

Description

This is a Boolean property that specifies whether or not the user may visit read-only cells in a Grid object. Its default value is 1.

In this context, a read-only cell is one that satisfies one or more of the following conditions:

  • it has no associated Input object
  • its associated Input object is a Label
  • its associated Input object is an Edit object with ReadOnly set to 1.
  • its associated Input object is inactive (Active0)

If EnterReadOnlyCells is set to 0 and the user clicks the mouse on a read-only cell, the current cell does not change although CellDown, CellUp and CellDblClick events are reported if enabled. If the user presses a cursor movement key that would otherwise cause the cursor to move into a read-only cell, the cursor moves instead to the nearest editable cell in the appropriate direction.


EvaluationDays Property

Applies to: Root

Description

This is a read-only property that reports the number of days remaining before an evaluation version of a Dyalog APL run-time application expires.

It is provided so that you can display an appropriate message box to notify your end-user when your application is started.

PocketAPL only


Event Property

Applies to: ActiveXContainer ActiveXControl Bitmap Button Calendar Circle Clipboard Combo CoolBand CoolBar Cursor Edit Ellipse FileBox Form Grid Group Icon Image ImageList Label List ListView Locator Marker MDIClient MenuItem Metafile MsgBox OLEClient OLEServer Poly Printer ProgressBar PropertyPage PropertySheet Rect RichEdit Root Scroll SM Spinner Splitter Static StatusBar StatusField SubForm TabBar TabBtn TabButton TabControl TCPSocket Text Timer ToolBar ToolButton ToolControl TrackBar TreeView UpDown

Description

This property defines how an object responds to user actions. Unlike other properties which only have a single value, this property has a value corresponding to each of the events that may be generated by a particular object. Each event setting is specified by a 2 or 3-element vector containing :

[1]

event name(s) (optionally prefixed by the string 'on') or event number(s) (numeric scalar or vector).
[2]

action code (numeric scalar or character vector)

¯1 | inhibit (ignore) event
0 | handle event, do not report to APL
1 | handle event, then report to APL
fn | name of callback function
fn& | name of callback function to be executedasynchronously
⍎expr | expression to be executed
[3] any array (optional)

The event number 0 and the event name 'All', apply to all events supported by that object.

Like any other property, the Event property can be set using assignment. However, certain special considerations apply which are discussed later.

If action is set to ¯1, the event is ignored by APL. If, for example, you set the action on a KeyPress event to ¯1, all keystrokes for the object in question will be ignored. Similarly, if you set the action on a Close event for a Form to ¯1, the user will be unable to close the Form. This is possible because APL intercepts most events before Windows itself takes any action. However, certain events (e.g. focus change events) are not notified to APL until after the event has occurred and after Windows has itself responded in some way. In these circumstances it is not always practical for APL to undo what Windows has already done, and an action code of ¯1 is treated as if it were 0. For further details, see the individual entries for each event type in this Chapter.

If action code is set to 0 (the default), the event is processed by APL and Windows in the normal way (this is referred to herein as "default processing") but your program is not notified in any way that the event has occurred. For example, the default processing for a keystroke is to action it (via the translate table) and either echo a character in the object or perform some other appropriate function.

If action code is set to 1, the event is first processed by APL (and Windows) in the normal way, then ⎕DQ terminates, returning an event message as its result. The format of the event message is given under the description of each event type.

If action code is set to a character vector that specifies the name of a function, this function (termed a "callback") will be executed automatically by ⎕DQ whenever the event occurs. Default processing of the event is deferred until after the callback has been run, and may be inhibited or modified by its result. If the callback function returns no result, or returns a scalar 1, normal processing of the event is allowed to continue as soon as the callback completes. If the callback returns a scalar 0, normal processing of the event is inhibited and the effect is identical to setting the action code to ¯1. A callback function may also return an event message as its result. If so, ⎕DQ will action this event rather than the original one that fired the callback.

Note that that if a callback function does not exist at the instant it is invoked, ⎕DQ terminates with a VALUE ERROR. However, the name of the missing function is reported in the Status Window.

If, in setting the Event property, the event name is prefixed by the string 'on', for example, 'onSelect', the right argument to the callback function will contain one or more object references. If not, it will contain the corresponding object names or, if the object has no name, its display form.

If the character & is appended to the name of a callback function, the callback is executed asynchronously in a new thread. In this case, default processing of the event is performed immediately. Such a callback should not return a result; if it does so, it will be treated as normal output and will therefore be displayed in the Session window.

When a callback function is invoked by ⎕DQ, the corresponding event message is supplied as its right argument. The format of the event message is given under the description of each event type in this chapter. Note that the first element of the event message is always a reference to or the name of the object that generated the event. It is a reference if the event name was prefixed by the string 'on'; otherwise it is a character vector containing the object's name.

If an array was specified as the 4th element of the value of the Event property, the value of this array is supplied as its left argument.

Notice that ⎕DQ takes account of the syntax defined for the callback, and supplies these arguments only if it is appropriate to do so. It is possible therefore to use a niladic callback function. This is appropriate if the callback can perform its task without needing to interrogate the event message.

If action code is set to a character vector whose first element is the execute symbol (⍎) the remaining string will be executed automatically whenever the event occurs. The default processing for the event is performed first and may not be changed or inhibited in any way.

Notice that when you specify the action to be taken on the occurrence an event there is a great difference between 'FOO' and '⍎FOO'. The former causes APL to invoke the function FOO as a callback function. If the function takes an argument, APL will supply it with the event message. Secondly, the result (if any) of the function FOO will be used by APL and may cause the event to be disabled or changed in some way. In the second case, APL will perform the default processing for the event and then execute FOO without supplying an argument. If the function returns a result, it will be displayed in the Session.

When using ⎕WC and ⎕WS to assign different events to different callbacks, it is not necessary to repeat the 'Event' keyword. Instead, several event settings can be specified at once. In any given occurrence of the Event property you may use event number(s) or event name(s); however you may not mix numbers and names together.

If you use event names, your callback functions will receive event names in their right argument when invoked. That is to say that the second element of the event message will be a character vector. If you use event numbers, the second element of the event message will be numeric. If you want to specify several event names at once, you must enclose them. If you use numbers, ⎕WC and ⎕WS are more tolerant about the structure of their arguments, and will accept many different expressions.

If no events are set, the result obtained by ⎕WG and the result obtained by referencing Event directly are different:

      'F'⎕WC'Form'
      DISPLAY 'F'⎕WG'Event'
.→--.
|0 0|
'~--'
      DISPLAY F.Event
.⊖------------.
| .→--------. |
| | .⊖. .⊖. | |
| | | | | | | |
| | '-' '-' | |
| '∊--------' |
'∊------------'

Asynchronous Callback Functions

If you append the character & to the name of the callback function in the Event specification, the callback function will be executed asynchronously in a new thread when the event occurs. If not, it is execute synchronously.

For example, the event specification:

      onSelect←'DoIt&'

tells ⎕DQ to execute the callback function DoIt asynchronously as a thread when a Select event occurs on the object. Note that a callback function executed in this way should not return a result (because ⎕DQ does not wait for it) and any result will be displayed in the Session window.

Specifying the Event property using Assignment

There are two ways to specify the Event property using assignment; you can specify the entire set of events, or you can set individual events one by one.

To specify the entire set of events, the array assigned to Event must contain one or more nested vectors, each containing 2 or 3 elements as described above. For example, if F1 is a Form:

Invoke callback function FOO on MouseDown, the first element of the right argument to FOO will contain a namespace reference to F1. All other events perform their default actions.

      F1.Event ← 'onMouseDown' 'FOO'

Invoke callback function FOO on MouseDown, the first element of the right argument to FOO will contain the character vector 'F1'. All other events perform their default actions.

      F1.Event ← 'MouseDown' 'FOO'

Invoke callback function FOO on MouseDown and MouseUp. All other events perform their default actions.

      F1.Event ← ('onMouseDown' 'FOO')( 'onMouseUp' 'FOO')

Add callback function FOO with ('THIS' 1) as its left-argument on the MouseMove event. All other events perform their default actions.

      F1.Event, ← ⊂ 'onMouseMove' 'FOO' ('THIS' 1)

To set individual events one by one, you make the assignment to the event name prefixed by the string 'on'. In all cases, the first element of the right argument to FOO will contain a namespace reference to F1. You must use the 'on' prefix; you cannot assign to the Event name itself.

Invoke callback function FOO on MouseDown.

      F1.onMouseDown ← 'FOO'

Add the same callback for MouseUp.

      F1.onMouseUp ← 'FOO'

Add callback function FOO with ('THIS' 1) as its left-argument on the MouseMove event.

      F1.onMouseMove ← 'FOO' ('THIS' 1)

Specifying the Event property using ⎕WC and ⎕WS

Examples using Event Names (⎕WS)

Ignore MouseDown (1) event (APL will perform the default processing for you)

      'F1' ⎕WS 'Event' 'MouseDown' 0

Terminate ⎕DQ on MouseDown

      'F1' ⎕WS 'Event' 'MouseDown' 1

Invoke callback function FOO on MouseDown, the first element of the right argument to FOO will contain a namespace reference to F1.

      'F1' ⎕WS 'Event' 'onMouseDown' 'FOO'

Invoke callback function FOO on MouseDown, the first element of the right argument to FOO will contain the character vector 'F1'.

      'F1' ⎕WS 'Event' 'MouseDown' 'FOO'

Invoke callback function FOO on MouseDown and MouseUp

      'F1' ⎕WS 'Event' ('onMouseDown' 'onMouseUp') 'FOO'

Invoke callback function FOO with ('THIS' 1) as its left-argument on MouseDown

      'F1' ⎕WS 'Event' 'onMouseDown' 'FOO' ('THIS' 1)

Invoke callback function FOO with ('THIS' 1) as its left-argument on MouseDown, MouseUp and MouseMove

      EV ← 'onMouseDown' 'onMouseUp' 'onMouseMove'
      'F1' ⎕WS 'Event' EV 'FOO' ('THIS' 1)

Execute the expression COUNT +←1 on MouseDown

      'F1' ⎕WS 'Event' 'MouseDown' '⍎COUNT+←1'

Execute the expression COUNT +←1 on MouseDown, MouseUp and MouseMove

      EV ← 'MouseDown' 'MouseUp' 'MouseMove'
      'F1' ⎕WS 'Event' EV '⍎COUNT+←1'

Examples using Event Numbers (⎕WS)

Ignore MouseDown (1) event (APL will perform the default processing for you)

      'F1' ⎕WS 'Event' (1 0)
      'F1' ⎕WS 'Event' 1 0     ⍝  Ditto

Terminate ⎕DQ on MouseDown

      'F1' ⎕WS 'Event' (1 1)
      'F1' ⎕WS 'Event' 1 1     ⍝ Ditto

Call function FOO on MouseDown

      'F1' ⎕WS 'Event' (1 'FOO')
      'F1' ⎕WS 'Event' 1 'FOO'    ⍝ Ditto

Call function FOO on MouseDown and MouseUp

      'F1' ⎕WS 'Event' ((1 2) 'FOO')
      'F1' ⎕WS 'Event' (1 2) 'FOO'              ⍝ Ditto
      'F1' ⎕WS 'Event' 1 2 'FOO'                ⍝ Ditto
      'F1' ⎕WS 'Event' (1 'FOO')(2 'FOO')       ⍝ Ditto

Call function FOO with ('THIS' 1) as its left-argument on MouseDown

      'F1' ⎕WS 'Event' (1 'FOO' ('THIS' 1))
      'F1' ⎕WS 'Event' 1 'FOO' ('THIS' 1)       ⍝ Ditto

Call function FOO with ('THIS' 1) as its left-argument on MouseDown and MouseUp

      'F1' ⎕WS 'Event' ((1 2) 'FOO' ('THIS' 1))
      'F1' ⎕WS 'Event' (1 2) 'FOO' ('THIS' 1)   ⍝ Ditto
      'F1' ⎕WS 'Event' 1 2 'FOO' ('THIS' 1)     ⍝ Ditto
      'F1' ⎕WS 'Event' 1 2 'FOO' ('THIS' 1)     ⍝ Ditto

Execute the expression COUNT +←1 on MouseDown

      'F1' ⎕WS 'Event' 1 '⍎COUNT+←1'

Execute the expression COUNT +←1 on MouseDown, MouseUp and MouseMove

      'F1' ⎕WS 'Event' (1 2 3) '⍎COUNT+←1'
      'F1' ⎕WS 'Event' 1 2 3 '⍎COUNT+←1'     ⍝ Ditto

User defined Events

In addition to the standard events supported directly by Dyalog APL, you may specify your own events. For these, you must use event numbers; user-defined event names are not allowed.

You may use any numbers not already defined, but it is strongly recommended that you choose numbers greater than 1000 to avoid potential conflict with a future release of Dyalog APL.

You can only generate user-defined events under program control with ⎕NQ.


EventList Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetControl, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This is a read-only property that reports the names of all the events supported by an object.


ExportedFns Property

Applies to: OLEServer

This property specifies the functions to be exposed as methods by an OLEServer object.

ExportedFns may be set to 0 (none), 1 (all), or a vector of character vectors containing the names of the functions to be exported.

There are certain important restrictions concerning the type of function that you can export as a method.

Firstly, only top-level defined functions within the OLEServer may be exported; you cannot export functions in other namespaces including sub-namespaces.

Furthermore, you may not export defined operators, dynamic functions, external functions, or functions created by function assignment.

Finally, OLE does not support the concept of a dyadic function, so your exported functions must be niladic, monadic, or take an optional left argument; they may not be explicitly dyadic.

If you wish to export a new function from your OLEServer, and ExportedFns is not 1, you must explicitly reset the value of the ExportedFns property before you re-save the workspace.


ExportedVars Property

Applies to: OLEServer

This property specifies the variables to be exposed as properties by an OLEServer object.

ExportedVars may be set to 0 (none), 1 (all), or a vector of character vectors containing the names of the variables to be exported.

Note that you may not export external variables or shared variables, or variables in other namespaces.

If you wish to export a new variable from your OLEServer, and ExportedVars is not 1, you must explicitly reset the value of the ExportedVars property before you re-save the workspace.


FCol Property

Applies to: ActiveXContainer, ActiveXControl, Button, Circle, Combo, ComboEx, CoolBand, CoolBar, Edit, Ellipse, Grid, Group, Label, List, ListView, Marker, Menu, MenuItem, Poly, Rect, RichEdit, Separator, Spinner, Static, StatusBar, StatusField, TabBtn, Text, TipField, ToolBar, TreeView, UpDown

Description

This property defines the foreground colour(s) of an object. For non-graphical objects, FCol specifies a single colour. For graphical objects with more than one constituent part, it may specify a set of background colours, one for each part. A single colour is represented by a single number which refers to a standard colour, or by a 3-element vector which defines a colour explicitly in terms of its red, green and blue intensities.

If FCol is 0 (which is the default) the foreground colour is defined by your current colour scheme for the object in question. For example, if you select red as your MS-Windows "Button Text" colour, you will by default get red writing on all your Button objects, simply by not specifying FCol or by setting it to 0.

A negative value of FCol refers to a standard MS-Windows colour as described below. Positive values are reserved for a possible future extension.

FCol | Colour Element | FCol | Colour Element
0 | Default | ¯11 | Active Border
¯1 | Scroll Bars | ¯12 | Inactive Border
¯2 | Desktop | ¯13 | Application Workspace
¯3 | Active Title Bar | ¯14 | Highlight
¯4 | Inactive Title Bar | ¯15 | Highlighted Text
¯5 | Menu Bar | ¯16 | Button Face
¯6 | Window Background | ¯17 | Button Shadow
¯7 | Window Frame | ¯18 | Disabled Text
¯8 | Menu Text | ¯19 | Button Text
¯9 | Window Text | ¯20 | Inactive Title Bar Text
¯10 | Active Title Bar Text | ¯21 | Button Highlight

If instead, FCol contains a 3-element vector, it specifies the intensity of the red, green and blue components of the colour as values in the range 0-255. For example, (255 0 0) is red and (255 255 0) is yellow.

Note that if the colour specified by FCol would normally be rendered as a dithered colour, it is instead converted to the nearest pure colour available on the device. The actual colour realised also depends upon the capabilities of the display adapter and driver, and the current Windows colour map.

For a Button, Combo, Edit, Label, List, Menu and MenuItem, FCol refers to the colour of the text in the object. Borders around these objects (where applicable) are drawn using the standard Windows colour. For a Static object however, FCol specifies the colour of its border.

For the Ellipse, Poly and Rect objects, FCol specifies the colour of the line drawn around the perimeter of the object. If a dashed or dotted line is used (LStyle 1-4) the "gaps" in the line are drawn using the colour specified by BCol, or are left undrawn if BCol is not specified. For the Marker object, FCol specifies the colour in which the markers are drawn. For the graphics objects Ellipse, Poly, Rect and Text, FCol may be a vector of 3-element vectors specifying a set of colours for the constituent parts of the object. For example, a Poly object consisting of four polygons, may have a FCol property of four 3-element vectors. In addition, for graphics objects, FCol is used in place of FillCol if the latter is not specified.


FieldType Property

Applies to: DateTimePicker, Edit, Label, Spinner

Description

The FieldType property controls data conversion, formatting and validation. For Edit, Label and Spinner objects, FieldType controls how the Value property of these objects is interpreted.

FieldType is a character vector. If it is empty (the default), the Text or Label object is a standard text object with no special formatting or, in the case of an Edit, no input validation. For a DateTimePicker, an empty FieldType implies the default which is 'Date'.

For a DateTimePicker, FieldType may be one of the following:

Date | Uses Windows “short date” format
DateCentury | Uses Windows “short date” format but with a 4-digit year regardless of user preference
LongDate | Uses Windows “long date” format
Time | Uses Windows time format
Custom | Uses a special format defined by the CustomFormat property

The value of the date or time is represented by the DateTime property. Note that all validation is performed by the object itself, and it is impossible to enter an invalid value.

For an Edit, Label and Spinner, if FieldType is defined, the contents of the object are defined by its Value property, which is a number, rather than by its Text property, and special formatting and validation rules are applied. FieldType may be one of the following :

Numeric | Simple numeric formatting and validation
LongNumeric | Uses Windows number format
Date
 Uses Windows “short date” format
LongDate
 Uses Windows “long date” format
Currency
 Uses Windows currency format
Time
 Uses Windows time format
Char | No validation, forces Value to be a character vector

FieldType 'Char' only affects an Edit object. When the user enters data into a standard single-line Edit object , the Value property is set to a number if the contents are numeric, or to a character vector if the contents do not represent a valid number. If FieldType is 'Char', the Value property is always set to a character vector, regardless of the type of the field contents.

If FieldType is 'Numeric', the object displays the number defined by its Value property rounded to the number of decimal places specified by its Decimals property. The decimal separator character used will be as specified by the Number format in the user’s International Control Panel settings. If the object is an Edit object, the user is prevented from entering anything but a valid number. The number of decimal digits is also restricted to Decimals. When the user “leaves” the object, the number is re-formatted.

If FieldType is 'LongNumeric', the object displays the number specified by its Value property according to the Number format in the user’s International Control Panel settings. This format specifies the 1000 separator, decimal separator, decimal digits and whether or not a leading zero is inserted. If the object is an Edit object, the user is prevented from entering anything but a valid number. However, the character specified for the 1000 separator is ignored and may be entered anywhere in the number. When the user “leaves” the object, the number is re-formatted correctly.

If the FieldType is 'Currency', the object displays the number specified by its Value property according to the Currency format in the user’s International Control Panel settings. This specifies the currency symbol and placement, the way in which a negative value is displayed, and the number of decimal places. If the object is an Edit object, the user is restricted to entering a “reasonable” value. When the user leaves the object, the number is reformatted correctly.

If the FieldType is 'Date', the Value property represents the number of days since January 1st 1900 and is displayed using the “short date” format specified by the user’s International Control Panel settings. If the object is an Edit object, the user is restricted to entering a “reasonable” date. The object will accept any numeric triplet separated by slash(/), colon (:) or space characters but checks that the day number and month number lie in the range 1-31 and 1-12 respectively and will not allow the user to enter a digit that would invalidate this. (Note that the position within the triplet of the day, month and year are as specified by the Windows short date format). However, the user is not prevented from entering an invalid date such as 31st September.

If the FieldType is 'LongDate', the Value property represents the number of days since January 1st 1900 and is displayed using the “long date” format specified by the user’s International Control Panel settings. If the object is an Edit object, its appearance and behaviour automatically switches to FieldType 'Date' when it has the input focus and back again when it loses the focus. This allows the user to edit or input a date in a more convenient form.

If the FieldType is 'Time', the Value property represents the number of seconds since midnight and is displayed using the time format specified by the user’s International Control Panel settings.

When the user attempts to move the input focus away from the object, the contents are validated. If they cannot be converted to a valid number, date, or time, the object generates a BadValue event, or, if the object is associated with a Grid, the Grid (and not the Edit object) generates a CellError event. See the descriptions of these events for further details.

Note that for Edit, Label and Spinner objects, FieldType may only be specified when you create an object using ⎕WC.


File Property

Applies to: Animation, Bitmap, Cursor, FileBox, Icon, Metafile, RichEdit

Description

For an Animation, Bitmap, Cursor or Icon object, this property is either a simple character vector or a 2-element nested vector.

If it is simple, File specifies the name of the associated bitmap (.BMP), icon (.ICO) or cursor (.CUR) file.

If it is nested, the first element specifies the name of a DLL or (Icon only) EXE and the second element identifies the particular bitmap, icon or cursor in that file. The identifier may be its name (a character string), its resource id (a non-zero positive integer) or (Icon only), its index (0 or negative integer) within the file. As a special case, if the name of the file is an empty vector, the object is loaded from DYALOG.EXE or DYARESxx.DLL. In this case, the identifier must be a name or resource id; indexes are not supported.

For a Metafile object, File must be simple and specifies the name of a metafile (.WMF) file. For a RichEdit object, File must be simple and specifies the name of a Rich text Format (.RTF) file.

When applied to a FileBox object, File contains the name (or names) of the selected file (or files) depending upon the value of its Style ('Single' or 'Multi').


FileMode Property

Applies to: FileBox

Description

The FileMode property applies only to a FileBox object. It indicates the mode in which the selected file is going to be opened. It is a character vector containing 'Read' (the default) or 'Write'. If FileMode is 'Write', files listed in the File Selection Box are greyed, although they may still be selected.


FillCol Property

Applies to: Circle, Ellipse, Poly, Rect

Description

This property defines the fill colour in a graphics object.

If FStyle is 0 (solid fill) FillCol defines the colour with which the object is filled. If FStyle is in the range 1-6 (pattern fill) it defines the colour of the lines that make up the pattern. The areas between the lines are filled using the colour specified by BCol, or are left undrawn (transparent) if BCol is not specified. If FStyle contains the name of a Bitmap object, the value of FillCol is ignored.

A single colour is represented by a single number which refers to a standard colour, or by a 3-element vector which defines a colour explicitly in terms of its red, green and blue intensities. A negative value of FillCol refers to a standard MS-Windows colour as described below. Positive values are reserved for a possible future extension.

FCol | Colour Element | FCol | Colour Element
0 | Default | ¯11 | Active Border
¯1 | Scroll Bars | ¯12 | Inactive Border
¯2 | Desktop | ¯13 | Application Workspace
¯3 | Active Title Bar | ¯14 | Highlight
¯4 | Inactive Title Bar | ¯15 | Highlighted Text
¯5 | Menu Bar | ¯16 | Button Face
¯6 | Window Background | ¯17 | Button Shadow
¯7 | Window Frame | ¯18 | Disabled Text
¯8 | Menu Text | ¯19 | Button Text
¯9 | Window Text | ¯20 | Inactive Title Bar Text
¯10 | Active Title Bar Text | ¯21 | Button Highlight

If instead, FillCol contains a 3-element vector, it specifies the intensity of the red, green and blue components of the colour as values in the range 0-255. For example, (255 0 0) is red and (255 255 0) is yellow. Note that the colour realised depends upon the capabilities of the display adapter and driver, and the current Windows colour map.

FillCol may also be a vector of 3-element vectors specifying a set of colours for the constituent parts of the object. For example, a Poly object consisting of four polygons, may have a FillCol property of four 3-element vectors.


Filters Property

Applies to: FileBox

Description

The Filters property is a nested scalar or vector containing a list of filters. Each filter is a 2-element vector of character vectors which contain a file type mask and a file type description respectively. The file type descriptions appear in a drop-down combo box labelled "List Files of Type". When the user selects one of these, the currently selected directory is searched for files which match the corresponding mask. The default value of Filters is an empty vector. This gives a file type mask of "*.*" and a file type description of "All Files (*.*)". Hence an empty vector is equivalent to (⊂'*.*' 'All Files (*.*)').


FirstDay Property

Applies to: Calendar

The FirstDay property specifies the day that is considered to be the first day of the week and which appears first in the Calendar.

FirstDay is an integer whose value is in the range 0-6. The default value for FirstDay depends upon your International Settings, but in most countries is 0 meaning Monday.


Fixed Property

Applies to: Font

Description

This property specifies whether or not a font represented by a Font object is fixed-width or proportional. It is either 0 (fixed-width) or 1 (proportional). There is no default; the value of this property reflects the characteristic of the selected font.


FixedOrder Property

Applies to: CoolBar

The FixedOrder property specifies whether or not the CoolBar displays CoolBands in the same order.

FixedOrder is a single number with the value 0 (user may re-order bands) or 1 (user may not re-order bands); the default is 0.

If FixedOrder is 1, the user may move bands to different rows, but the band order is static.


FlatSeparators Property

Applies to: TabControl

The FlatSeparators property specifies whether or not separators are drawn between buttons in a TabControl object. FlatSeparators only affects a TabControl if Style is 'FlatButtons' and is otherwise ignored.

FlatSeparators is a single number with the value 0 (no separators) or 1 (separators); the default is 0.

The pictures below illustrate the effect of FlatSeparators on the appearance of a TabControl object.


FontList Property

Applies to: Printer, Root

Description

The FontList property is a read-only property (you cannot set its value) that provides a list of available fonts.

Its value is a vector (1 per font) of 8-element character vectors, each of which is as follows :

[1] | Face name (character vector)
[2] | Character height in "points" (integer)
[3] | Fixed width or not (boolean)
[4] | Italic or not (boolean)
[5] | Underline or not (boolean)
[6] | Weight (integer)
[7] | Angle of rotation (integer)
[8] | Character set (see CharSet)

Example:

       ↑'.'⎕WG'FontList'
 System                         16 0 0 0 700 0   0
 Terminal                       12 1 0 0 400 0 255
 Fixedsys                       15 1 0 0 400 0   0
 Roman                          37 0 0 0 400 0 255
 Script                         36 0 0 0 400 0 255
 Modern                         37 0 0 0 400 0 255
 Small Fonts                     3 0 0 0 400 0   0
 MS Serif                       10 0 0 0 400 0   0
 WST_Czec                       12 1 0 0 700 0   2
 WST_Engl                       12 1 0 0 700 0   2
 WST_Fren                       12 1 0 0 700 0   2
 WST_Germ                       12 1 0 0 700 0   2
 WST_Ital                       12 1 0 0 700 0   2
 WST_Span                       12 1 0 0 700 0   2
 WST_Swed                       12 1 0 0 700 0   2
 Courier                        13 1 0 0 400 0   0
 Serif                          13 0 0 0 400 0   0
 Causeway                       16 1 0 0 700 0   0
 Dyalog Alt                     16 1 0 0 400 0   0
 Dyalog Std                     16 1 0 0 400 0   0

Note that the list of fonts obtained from FontList for a Printer object will include TrueType fonts and printer fonts but will exclude screen fonts. FontList for Root will include TrueType fonts and screen fonts, but exclude printer-only fonts. The two lists will therefore (typically) be different.


FontObj Property

Applies to: ActiveXContainer, ActiveXControl, Bitmap, Button, Calendar, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, Menu, MenuBar, MenuItem, Printer, PropertyPage, PropertySheet, RichEdit, Root, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, TabControl, Text, TipField, ToolBar, ToolControl, TrackBar, TreeView

Description

The FontObj property associates a font with an object. It specifies either the name of, or a ref to, a Font object, or it specifies the attributes of the font directly. The use of the FontObj property to specify a font directly is supported only for compatibility with previous releases of Dyalog APL/W and may be removed in the future. The Font object provides a more efficient mechanism for managing fonts and allows greater flexibility for drawing and printing graphical text. It is recommended that all fonts be specified using Font objects and not loaded directly using the FontObj property.

If unspecified, the default value for FontObj is an empty character vector. For most objects, this setting implies that the font used in the object is inherited from its parent object. However, CoolBar, Menu, MenuBar, StatusBar, TipField, ToolBar, and ToolControl objects do not inherit their font.

Note that the default value of FontObj for Root is also an empty character vector and that this implies the Windows default GUI font, which is a Windows user preference setting.

Note however that it is not currently possible to specify the font for Menu and MenuItem objects which are the direct descendants of a MenuBar. Nor is it possible to specify the font used for the Caption in a Form.

If FontObj specifies a Font object, it is a ref or a simple character vector.

If FontObj specifies a font directly, it may be either an empty character vector (this is its default value) or as an array containing up to 8 elements as follows :

[1] | Face name of requested font (character vector)
[2] | Character height in pixels (integer)
[3] | Fixed width or not (boolean)
[4] | Italic or not (boolean)
[5] | Underline or not (boolean)
[6] | Weight (integer)
[7] | Angle of rotation (integer)
[8] | Character set (see CharSet)

When you assign a value to the FontObj property of an object, Windows actually supplies the font that most closely matches the attributes you have specified. The matching rules it uses are complex, and may be found in the appropriate Windows documentation. The value of the FontObj property reflects the attributes of the font which has been allocated by Windows, not the value you originally specified.

A list of available fonts and their attributes may be obtained from the FontList property of the Root object ".".

The "Face name" is the name assigned to the font by Windows. The default is 'System'. The face name of the Dyalog APL font is 'APL'. Note that case is ignored when you specify the name, although it will be returned correctly by ⎕WG.

The size of the font is specified in terms of its height in pixels. If Windows cannot supply exactly the size you request, it will supply the nearest below that.

A value of 1 in the third element requests a fixed-width font, as opposed to a proportional one. This attribute is given the maximum weighting by Windows in choosing a matching font.

A value of 1 in the fourth and fifth elements requests the font attributes italic and underlined respectively. Windows will add these attributes to an existing font if they don't physically exist. For example, you can obtain italic and underlined APL characters from the standard APL font.

The weight is a number in the range 0 to 1000 which specifies how faint or bold the characters appear. The larger the number, the bolder the font.

The angle of rotation is measured in 1/10ths of a degree from the x-axis in a counter-clockwise direction. Its default value is 0.


Formats Property

Applies to: Clipboard

Description

This is a "read-only" property that identifies the formats in which data is currently available in the clipboard. It is a vector of character vectors containing the names of the corresponding Clipboard properties for which data may be obtained using ⎕WG. In the following example data was copied to the Windows clipboard from Microsoft Excel. This product stores data in CF_Text and the older device-dependent CF_Bitmap formats. The latter excludes colour map information, so CMap is not available.

      'CL' ⎕WC 'Clipboard'
      'CL' ⎕WG 'Formats'
 Bits  CMap  Text


FormatString Property

Applies to: Edit, Grid, Label, Spinner

The FormatString property specifies one or more ⎕FMT format specifications to be used to format data in an Grid or single-line Edit. When applied to a Grid, it is either a simple character vector that specifies the format specification for the entire Grid, or a vector of character vectors. If it is a vector, its elements are mapped to individual cells via the CellTypes property. When applied to an Edit object, FormatString must be a simple character vector.

APL derives the text to be displayed in a cell by calling ⎕FMT with a left argument of the corresponding element of FormatString and a right argument of the cell value. If the format specification is invalid, the text displayed is blank.

When a formatted Edit object receives the focus, it redisplays the contents in its raw (unformatted) form. When the Edit loses the focus, its contents are reformatted. When the user moves to a formatted Grid cell, the text remains formatted until the user presses a non-movement key or enters in-cell mode. The data is then redisplayed in its raw form for editing. Data in the cell is reformatted when the user moves away.

In a Grid, formatted data may be aligned vertically using the AlignChar property as illustrated in the following example.

      'F'⎕WC'Form'
      'F.G'⎕WC'Grid'(¯50+?10 10⍴100)(0 0)(100 100)
      'F.G'⎕WS'FormatString' 'M<(>N<)>F12.3'
      'F.G'⎕WS'AlignChar' '.'


FullRowSelect Property

Applies to: ListView, TreeView

The FullRowSelect property specifies whether or not the entire row is highlighted when an item in a ListView or a TreeView is selected.

FullRowSelect is a single number with the value 0 (only the item name is highlighted) or 1 (the whole row is highlighted); the default is 0.

For a ListView, FullRowSelect only applies if its View property is set to 'Report'.

The picture below illustrates the effect on the appearance of a ListView object, of setting FullRowSelect to 1.


FStyle Property

Applies to: Circle, Ellipse, Poly, Rect

Description

This property determines how a graphics object is filled. It takes one of the following values, or, if the object has more than one component, a vector of such values.

FStyle | Effect
¯1 | hollow (no fill). This is the default.
0 | solid fill
1 | hatch fill with horizontal lines
2 | hatch fill with vertical lines
3 | hatch fill with diagonal lines at 135 degrees
4 | hatch fill with diagonal lines at 45 degrees
5 | hatch fill with horizontal and vertical lines
6 | hatch fill with criss-crossing diagonal lines
str | the name of. or a ref to, a Bitmap object which is used to fill the object.

For example, to fill an object with criss-crossing diagonal lines you would specify ('FStyle' 6). If the object contained two components, you could fill the first one with criss-crossing diagonal lines, and the second one with a Bitmap called 'YES', with the specification ('FStyle' 6 'YES')

If the size of the Bitmap is 88 APL uses a Windows "brush" to fill the object. If not, it uses "tiling". Filling with a brush is faster.


GridBCol Property

Applies to: Grid

Description

This property specifies the colour used to fill the area between the end of the last column of data and the right edge of the Grid and between the bottom row of data and the bottom edge of the Grid.

GridBCol may be a 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). Its default value is 0 which obtains the colour defined for Window Background.


GridFCol Property

Applies to: Grid

Description

The GridFCol property specifies the colour of the grid lines in a Grid object

GridFCol may be a 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). . Its default value is 0 which obtains the colour defined for Window text.

The grid lines may be removed by setting GridFCol to the same colour as the background colour of the cells, which is defined by Bcol.


GridLineFCol Property

Applies to: Grid

The GridLineFCol property specifies the colours of the grid lines in a Grid object. GridLineFCol should be used if different coloured grid lines are required. If all the grid lines are the same colour, use GridFCol.

GridLineFCol may be a scalar or a vector. Each item may be a 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or a scalar that defines a standard Windows colour element (see Bcol for details). Note that a single RGB triplet must be enclosed.

The default value of GridLineFCol is an empty numeric vector (<—>). If so, all the grid lines are drawn using the single colour specified by GridFCol.

Elements of GridLineFCol are allocated to individual grid lines via the RowLineTypes and ColLineTypes properties.

See also: GridLineWidth.


GridLineWidth Property

Applies to: Grid

The GridLineWidth property specifies the widths in pixels of the grid lines in a Grid object.

GridLineWidth may be an integer scalar or a vector. Its default value is an empty numeric vector (<—>). If so, grid lines are drawn 1-pixel wide.

Grid lines are always displayed so that 1 pixel is drawn within the cell. If the width is greater than 1 pixel, the additional pixels are drawn between the cells.

If an element of GridLineWidth is 0, the corresponding grid lines are not drawn.

Elements of GridLineWidth are allocated to individual grid lines via the RowLineTypes and ColLineTypes properties.

See also: GridLineFCol.


GridLines Property

Applies to: ListView

The GridLines property specifies whether or not lines are displayed between items in a ListView object. GridLines applies only if the value of the View property is 'Report'.

GridLines is a single number with the value 0 (no lines are displayed) or 1 (lines are displayed); the default is 0.

The picture below illustrate the effect on the appearance of a ListView object, of setting GridLines to 1.


GripperMode Property

Applies to: CoolBand

The GripperMode property specifies whether or not the CoolBand has a gripper bar which is used to reposition and resize the CoolBand within its parent CoolBar.

GripperMode is a character vector with the value 'Always' (the default), 'Never' or 'Auto'.

If GripperMode is 'Always' , the CoolBand displays a gripper bar even if it is the only CoolBand in the CoolBar.

If GripperMode is 'Never' , the CoolBand does not have a gripper bar and may not be directly repositioned or resized by the user.

If GripperMode is 'Auto' , the CoolBand displays a gripper bar only if there are other CoolBands in the same CoolBar.


Handle Property

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, Cursor, DateTimePicker, Edit, Font, Form, Grid, Group, Icon, ImageList, Label, List, ListView, MDIClient, Menu, MenuBar, Metafile, OLEClient, OLEServer, Printer, ProgressBar, PropertySheet, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

This is a read-only property that reports the handle associated with an object. For a visual object, such as a Form or a Button, this is the window handle. For a Printer, it is the printer device context.

This handle allows you to access the corresponding object directly with Windows API functions via ⎕NA. This facility must be used with care and the responsibility for its behaviour is entirely yours. Do NOT use it to delete an object. This will cause APL to crash.

An example of the use of the Handle property is to set tab stops in a List object. This is illustrated by the following function:

     ∇ OBJ TABSTOPS STOPS;I; LB_SETTABSTOPS;SetTabStops;SINK
[1]   ⍝ Sets the tabstops in the List Box OBJ to be at
[2]   ⍝ STOPS Horizontal Dialog units.
[3]
[4]   ⍝ Sends LB_SETTABSTOPS to the List Box
[5]   ⍝ LB_SETTABSTOPS is 1043 for Windows 3.x
[6]   ⍝                but 402 for Windows 95 and NT
[7]   ⍝ See Windows SDK for Details.
[8]
[9]    I←OBJ ⎕WG'ITEMS'
[10]
[11]   :If '3.x'≢¯3↑⊃'.'⎕WG'APLVersion'
[12]      LB_SETTABSTOPS←402
[13]      'SetTabStops'⎕NA'U4 USER32.C32|SendMessageA U4 U4 U4 <U4[]'
[14]   :Else
[15]      LB_SETTABSTOPS←1043
[16]      'SetTabStops'⎕NA'U4 USER.P16|SendMessage U2 U2 U2 <U2[]'
[17]   :EndIf
[18]
[19]   SINK←SetTabStops(OBJ ⎕WG'Handle') LB_SETTABSTOPS (⍴,STOPS)(,STOPS)
[20]
[21]   OBJ ⎕WS'Items'I
     ∇


HasApply Property

Applies to: PropertySheet

The HasApply property is a boolean value that specifies whether or not a PropertySheet has an Apply button. Its default value is 1. Note that an Apply button is only actually used if Style is 'Standard'.


HasButtons Property

Applies to: TreeView

The HasButtons property is a boolean value and specifies whether or not buttons are shown in a TreeView object. If HasButtons is 1 (the default) a square button is displayed to the left of each parent item label. If the item is expanded (i.e. is children are visible) the button contains a minus sign. If the item is not expanded, (i.e. its children are hidden) the button contains a plus sign. The user can cause a parent item to expand or collapse by clicking this button.


HasCheckBox Property

Applies to: DateTimePicker

Specifies whether or not a checkbox is displayed alongside the value in a DateTimePicker.

HasCheckBox is a single number with the value 0 (the default) or 1. If HasCheckBox is 1, the user may set or clear the checkbox to indicate whether or not the date/time displayed in the object is to apply.

If the checkbox is not set, the DateTimePicker is considered to be empty (the contents will be grayed out) and the value returned by the DateTime property is zilde. Note that HasCheckBox may only be set when the object is created.


HasEdit Property

Applies to: BrowseBox

Specifies whether or not a BrowseBox has an edit field.

HasEdit is a single number with the value 0 (the default) or 1. If HasEdit is 1, the user may type in the name of a folder or other resource that is the target of the BrowseBox. If HasEdit is 0, the user must browse to it.


HasHelp Property

Applies to: PropertyPage, PropertySheet

The HasHelp property is a boolean value For a PropertySheet, it determines whether or not the PropertySheet has a Help button. for a PropertyPage, HasHelp determines whether or not the Help button is active when the PropertyPage is the current page. If the HasHelp property of a PropertyPage is 0, the Help button on the parent PropertySheet will be temporarily disabled when that PropertyPage is displayed.


HasLines Property

Applies to: TreeView

The HasLines property specifies whether or not tree lines are drawnin a TreeView object. It is a single integer with the value 0, 1 or 2:

0 | No tree lines
1 | Tree lines are drawn at all levels except the top level
2 | Tree lines are drawn at all levels

The user can cause a parent item to expand or collapse by clicking on its corresponding tree line.


HasTicks Property

Applies to: TrackBar

The HasTicks property specifies whether or not tick marks are drawn in a TrackBar object. It is boolean value with a default value of 0.

The position of the tick marks in the TrackBar is determined by the TickAlign property.


HasToday Property

Applies to: Calendar, DateTimePicker

The HasToday property specifies whether or not the Today date is displayed in the bottom left corner of a Calendar object or in the dop-down calendar of a DateTimePicker.

HasToday is a single number with the value 0 (the date is not shown) or 1 (the date is shown); the default is 1.

See also CircleToday property.


Header Property

Applies to: ListView

The Header property is boolean and specifies whether or not a ListView object displays column titles. Its default value is 1. Header applies only if the View property is 'Report'. The column titles are defined by the ColTitles property and their alignment by the ColTitleAlign property.

Note that Header may only be set by ⎕WC and may not subsequently be changed.


HelpButton Property

Applies to: Form, SubForm

This is a Boolean property that specifies whether or not a Question (?) button appears in the title bar of a Form or SubForm. However, this does not apply if the Form has a maximise or minimise button which both take precedence. The user may obtain help by clicking on the Question (?) button and then on a control in the Form. It is up to you to provide the help by responding to the Help event on the control. The default value of HelpButton is 0.

HelpButton is ignored in Version 7 because Windows 3.x does not support this feature.


HelpFile Property

Applies to: ActiveXControl, OCXClass, OLEClient

The Helpfile property is a read-only property that reports the pathname of a Windows help file associated with a particular COM object.

For an OCXClass or OLEClient object, the HelpFile property is read-only.


Hint Property

Applies to: Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, MenuItem, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolButton, TrackBar, TreeView, UpDown

Description

The Hint property is a character vector that specifies a help message that is to be displayed when the user positions the mouse pointer over the object. The Hint is displayed in the object specified by its HintObj property. A StatusField is often used for this purpose.


HintObj Property

Applies to: Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, MenuItem, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolButton, TrackBar, TreeView, UpDown

Description

The HintObj property is a character vector or ref that specifies the name of , or a ref to, an object in which the “help” message defined by the Hint property is to be displayed. This message is displayed when the user positions the mouse pointer over the object. The Hint is displayed by automatically setting the Caption or Text property of the object named by HintObj. The following types of object can therefore be used to display Hints: Button, Edit, Combo, Group, Form, Label, Menu, MenuItem, StatusField, SubForm and Text. For a StatusField that has both Caption and Text properties, the text property is used for displaying hints.

When the user moves the mouse pointer away from the object, the Caption or Text property of the object specified by HintObj is reset to an empty vector.

Note that if HintObj is empty, its value is inherited from its parent. Thus setting HintObj on a Form defines the default location for displaying Hints for all the controls in that Form. Setting HintObj on Root defines the default location for hints for the entire application.


HotSpot Property

Applies to: Cursor

Description

This property specifies the point within a Cursor object that registers the cursor's position over another object. The mouse position, which is reported by various events, is actually the position of the cursor's HotSpot over the object in question.

HotSpot is a 2-element numeric vector that specifies the y-position and x-position of the hotspot within the cursor. A value of (0 0) specifies the top-left corner of the cursor; (31 31) specifies the bottom right corner of the cursor. The default value of HotSpot is (15 15).


HotTrack Property

Applies to: TabControl

The HotTrack property specifies whether or not the tabs or buttons in a TabControl object ( which are represented by TabButton objects), are automatically highlighted by the mouse pointer.

HotTrack is a single number with the value 0 (no highlighting) or 1. The default is 0.

If HotTrack is 1 and the Style property of the TabControl is 'Tabs' or 'Buttons', the text defined by the Caption property of the TabButton is highlighted when the mouse pointer is placed over the tab or button. If Style is 'FlatButtons', the button is highlighted by being raised.

The value of HotTrack is effective only when the object is created with ⎕WC.


HAlign Property

Applies to: Text

Description

This property determines the horizontal alignment of text in a Text object. It is either a single integer value, or, if the Text object contains several components, a corresponding vector of such values. These may be:

0left aligned (the left edge of the bounding box of the text is aligned on the x-co-ordinate specified by the Points property).

1centre aligned (the centre of the bounding box of the text is aligned on the x-co-ordinate specified by the Points property).

2right aligned (the right edge of the bounding box of the text is aligned on the x-coordinate specified by the Points property).


HScroll Property

Applies to: Combo, ComboEx, Edit, Form, Grid, ListView, RichEdit, Scroll, StatusBar, SubForm, TabBar, ToolBar, TrackBar, UpDown

Description

For most objects to which it applies, this property determines whether or not a horizontal scrollbar is provided.

When applied to a Combo, or to an Edit object with Style 'Single' (i.e. a single-line edit field), the value 0 inhibits scrolling, and prevents the user from entering more data when the field is full. If instead it has the value ¯2, the field is scrollable, and the length of data that may be entered is not limited by the length of the field.

When applied to an Edit object with Style 'Multi' (i.e. a multi-line text box), the value 0 inhibits scrolling, and causes individual lines to be "word-wrapped". The values ¯2 and ¯1 enable sideways scrolling, and permit individual lines to exceed the width of the object. The value ¯1 means that a horizontal scrollbar is provided.

For a Scroll object, the scrollbar is horizontal if HScroll is ¯1 and vertical if HScroll is 0. For a Form, a horizontal scrollbar is provided if HScroll is set to ¯1. The default value is 0 (no scrollbar).

For a StatusBar, TabBar or ToolBar with Align set to Top or Bottom, HScroll determines whether or not a horizontal scrollbar is provided and how the object positions its children. If HScroll is 0 (the default) the object organises its children in multiple rows and does not provide a scrollbar. If HScroll is ¯1 or ¯2, the object organises its children in a single row and provides a mini scrollbar to allow those positioned beyond the right edge of the object to be scrolled into view. If HScroll is ¯1, the scrollbar is always shown. If HScroll is ¯2, it is only shown when needed.

For a Grid, HScroll may be 0 (no horizontal scrollbar), ¯1 (scrollbar is displayed when required), ¯2 (same as ¯1) or ¯3 (scrollbar is always displayed).


IconObj Property

Applies to: Form, MDIClient, Root, SubForm, SysTrayItem, TabBar, ToolBar

Description

This property is used to specify a large and small icon for a Form or SubForm, or for the Root object which represents your application as a whole. Its value is either a single ref or character scalar or vector containing the name of, or ref to, an Icon object, or a 2-element vector of character vectors or refs that specifies 2 Icon objects.

If empty (the default value), the standard "Dyalog APL GUI" icon is used.

The large and small icons are supplied to the Operating System which uses them as and when is appropriate. Normally, the large icon is of size 32x32 and the small icon is 16x16. If you specify an icon of a different size, the Operating System will scale it as appropriate.

The icon associated with a Form is displayed when the Form is minimised. The icon associated with '.' is displayed when the user presses Alt+Tab to toggle between applications. In both cases, the text shown underneath or alongside the icon is defined by the Caption property.

For an MDIClient, the IconObj property has no direct use, but is inherited by all its child SubForms. Thus if you want all your child SubForms to use the same icon, you need only define it once for the MDIClient.


ImageCount Property

Applies to: ImageList

The ImageCount property is a read-only property that reports the number of images in an ImageList object. It is an integer scalar.


ImageIndex Property

Applies to: ComboEx, CoolBand, ListView, Menu, MenuItem, TabButton, ToolButton, TreeView

For a ComboEx, ListView or TreeView, the ImageIndex property maps bitmapped images in an ImageList to items. ImageIndex is an integer vector whose length is the same as the number of items in the object. See also SelImageIndex

For a CoolBand, MenuItem, TabButton or ToolButton, ImageIndex specifies the picture to be displayed in the object. In these cases, ImageIndex is a single integer value.

ImageIndex is ⎕IO dependent.


ImageListObj Property

Applies to: ComboEx, CoolBar, ListView, Menu, TabControl, ToolControl, TreeView

The ImageListObj property is a simple character vector or a ref, or a vector of character vectors or refs that specifies ImageList objects that are associated with an object.

For aComboEx or TreeView object, the ImageListObj property specifies the name of, or ref to, a single ImageList object that contains a set of images to be displayed alongside its Items. The image(s) displayed by a particular item in its normal (unselected) and selected states are specified by the corresponding element of the ImageIndex and SelImageIndex properties respectively.

For CoolBar, Menu, and TabControl objects, the ImageListObj property specifies the name of, or ref to, a single ImageList object that contains a set of images for its CoolBand, MenuItem, and TabButton children respectively.

For a ToolControl, ImageListObj may specifiy up to three ImageList objects that correspond to the three different states, normal, highlighted (hot) and inactive, of its ToolButton children.

In all these cases, individual images are mapped to the child objects by their ImageIndex property.

For a ListView either one or two ImageList objects may be specified. The first ImageList contains the large icon set of images. the second contains the small icon set. The set that is used is determined by the value of the View property. The mapping between the set of images in the ImageList and items in the object is determined by the ImageIndex property.


Indents Property

Applies to: ComboEx

Specifies the amount by which items in a ComboEx object are indented.

Indents may be an integer scalar or a vector with the same number of elements as there are items in the ComboEx. Its default value is 0.

The unit of indenting is 10 pixels. For example, if there are 3 items and Indents is (0 1 2), the items will be indented by 0, 10 and 20 pixels respectively.


Index Property

Applies to: Combo, ComboEx, CoolBand, FileBox, Grid, List, TreeView

Description

For a List and a Combo with Style 'Simple', this property specifies the position of the data in the list box as a positive integer value. If Index has the value "n", it means that the "nth" item in Items is displayed on the top line in the list box. The value of Index is dependent upon the value of ⎕IO. Note that Index for a Combo or List cannot be set using ⎕WC. The value of Index in a Combo with a drop-down list box (Style 'Drop' or 'DropEdit') is always equal to ⎕IO.

For a Grid, Index is a 2-element vector that specifies the row and column number of the cell that is currently in the top left corner of the Grid.

For a TreeView, Index is a positive integer value that specifies which item appears at the top of the TreeView window.

For a FileBox, the Index property determines which of the Filters is initially selected.

For a CoolBand, the Index property specifies the position of the CoolBand within its parent CoolBar, relative to the other CoolBands in the CoolBar.

The value of Index is dependent on ⎕IO, and its default value is equal to ⎕IO.


Input Property

Applies to: Grid

Description

This property specifies objects to be associated with cells in a Grid. These objects may be of type Button, ColorButton, Combo, Edit, Label, Spinner or TrackBar. In addition, the Input property may specify instances of OCXClass objects (ActiveX controls) and NetType objects (.NET classes).

The Input property is either a single ref or a simple character scalar or vector, or a vector of character vectors or refs. If it specifies a single object, this will be associated with all of the cells in the Grid. If it specifies a set of objects, these are mapped to individual cells through the CellTypes property.

When a cell becomes the current cell, its value (defined by the appropriate element of the Values property) defines the value of a corresponding property of the associated object The property that corresponds to the value in the cell, depends upon the Type of the associated object as shown in the following table:

Associate Object Type | Corresponding Property
Label | Text
Edit | Value
Combo | Text
Button (Style Push) | Caption
Button (Style Radio or Check) | State
ColorButton | CurrentColor
Spinner | Value
TrackBar | Thumb
OCXClass | Specified by InputProperties
NetType | Specified by InputProperties

In effect, the user inputs a new value into the current cell by changing the corresponding property of its associated object. An associated object may be a fixed object that is external to the Grid or a floating object that moves automatically from cell to cell. The latter is achieved by creating the associated object as a child of the Grid.

If the associated object is an Edit or Combo, the user may change the Text property of the object by typing, or, in the case of a Combo, by selecting an item from a list. The new value of the Text property is then used to update the value in the cell (defined by the Values property of the Grid) when the user moves on. If the associated object is a radio button, the value in the cell (0 or 1) is reflected by the State property of the Button. The user may click the Button on and off, changing its State and thereby the corresponding value in the cell.

If the associated object is a ColorButton, the corresponding elements of the Values property contain 3-element integer vectors which specify the RGB colour values.

If the associated object is an instance of an OCXClass object (ActiveX control) or a NetType object (.NET class), the Grid uses the default property of the external object if it has one. Alternatively, the InputProperties property is used to specify which property (or properties) of the external object are to be mapped to elements of Values. If more than one property is specified, elements of Values are vectors.

If there is no object associated with a cell, or if its associated object is a Label or a Button with Style Push, the cell is protected and may not be changed by the user. When the current cell is thus protected, the corresponding row and column titles are not indented as they are when the cell may be edited.

If the associated object is a numeric Edit or Label (FieldType Numeric, LongNumeric, Currency, Date, LongDate or Time) the contents of the cell are formatted accordingly, even when it is not the current cell. Thus a cell associated with a Label with FieldType Date, always displays as a date.

If the associated object is a Combo or Button, the appearance of a non-current cell is defined by the corresponding element of the ShowInput property.

The following example illustrates the use of different types of object specified by the Input and ShowInput properties.


InputMode Property

Applies to: Grid

Description

This property determines editing behaviour and the action of the cursor movement keys when the user changes the contents of a Grid using a floating Edit or DropEdit Combo control.

InputMode is a character vector with one of the following values:

'Scroll' | The cursor keys move around the Grid; the user may switch to InCell mode.
'InCell' | The cursor keys move within the Input object; the mode reverts to Scroll when the user selects a new cell.
'AlwaysScroll' | The cursor keys move around the Grid; the user may not switch to InCell mode.
'AlwaysInCell' | The cursor keys move within the Input object, even when the user moves to a new cell
'AutoEdit' | See below

By default, the input mode is Scroll. In this mode, cursor movement keys are actioned by the Grid itself and used to move from cell to cell. The user may switch to InCell mode by double-clicking or by pressing the key defined by InputModeKey (the default is "F2").

In InCell mode, all cursor movement keys are actioned by the Input object and typically move the cursor around within the Input object and do not switch between cells. When the user switches to a different cell, InputMode reverts to Scroll mode

If InputMode is AlwaysScroll or AlwaysInCell, the user remains permanently in either Scroll or InCell mode respectively.

If InputMode is 'AutoEdit', the behaviour of a cell that contains a floating Input field is as follows:

When the user enters the cell, the contents are selected (and highlighted).At this stage, the cursor movement keys move to an adjacent cell. If the user presses a (valid) data key, that character replaces the current contents of the cell.

If the user presses F2 (or the key defined by the InputModeKey property), the data is de-selected and unhighlighted and the cursor is placed at the rightmost end of the data.

In either case, the left and right cursor keys now move the cursor within the current data string, but skip to the adjacent cell from the beginning or end of the data. This behaviour differs from InCell mode in which the cursor movement keys stick at the end of the data.


InputModeKey Property

Applies to: Grid

Description

This property defines the keystroke used to switch from Scroll mode to Incell mode in a Grid. It applies only where the Grid has a floating Edit control. See the description of the InputMode property for further details.

The InputModeKey property is specified (in the same way as the Accelerator property) as a 2-element vector of integer values containing the key number and shift state respectively. Its default is (113 0) which is “F2”.

As an example, if you wanted to use Ctrl+Shift+a to switch modes, you would set InputModeKey to (65 3). 65 is the keynumber for “a” and 3 means Shift (1) + Ctrl (2).


InputProperties Property

Applies to: Grid

The InputProperties property is a vector of character vectors that specifies the names of properties of an OCXClass (ActiveX Control) or .NET Class that are to be mapped to the Values property in a Grid.

When an ActiveX Control or .NET Class is used as a child of the Grid, InputProperties is used to specify how the value in each Grid cell corresponds to the value of one or more properties of the child object.

For example, suppose there is a third-party ActiveX Control that displays a playing card. The control has two properties named Suit and Value that specify the suit (1=clubs, 2=diamonds, 3=hearts, 4=spades) and card value (1="Ace", 2="2", …11="Jack",…) respectively. To display these cards in a Grid, the InputProperties property may be set to ('Suit' 'Value') and each element of the Values property must be a 2-element integer vector specifying the suit and value of the corresponding card.

     'CARDS'⎕WC'OCXClass' '...'
     'F'⎕WC'Form'
     'F.G'⎕WC'Grid'
     'F.G.card'⎕WC'CARDS'
     F.G.Input←'F.G.card'
     F.G.InputProperties←'Suit' 'Value'
     F.G.Values←⍳4 13

If InputProperties is not specified, the default property of the ActiveX Control or .NET Class is used.


Interval Property

Applies to: ProgressBar, Timer

Description

The Interval property specifies the frequency with which a Timer object generates Timer events. It is an integer value specified in milliseconds and has a default of 1000.

Setting Interval to 0 effectively de-activates the Timer.


Italic Property

Applies to: Font

Description

This property specifies whether or not a font represented by a Font object is italicised or not. It is either 0 (normal) or 1 (italic). There is no default; the value of this property reflects the characteristic of the selected font.


ItemGroupMetrics Property

Applies to: ListView

Applies to ListViewThis property is used to specify colours and spacing elements for a ListView that is displaying its Items in groupings (see ItemGroups).

Note that setting this property will only have an effect if XP Look and Feel is enabled.

ItemGroupMetrics is a 3-item nested vector as follows:

[1] | Text Colours | 2-element vector of 3 element RGB values that specifies the colour of the group caption and group footer respectively.
[2] | Spacing | 4-element integer vector that specifies the top, left, bottom and right spacing around each grouping in pixels
[3] | Border | Colours4-element vector of 3 element RGB values that specifies the colours for the top, left, bottom and right borders (not yet implemented).

The following expression, coupled with the code shown in the SetGroups example, causes the items to be displayed as shown below.

      F.L.ItemGroupMetrics[1 2]←(2⍴⊂255 0 0)(10 100 0 10)


ItemGroups Property

Applies to: ListView

Applies to ListViewThis property specifies item groupings for a ListView object.

Note that setting this property will only have an effect if XP Look and Feel is enabled.

ItemGroups is a nested scalar or nested vector each of whose elements specifies a grouping. Each grouping is a 5-element vector as follows:

[1] | Group caption | character vector
[2] | Item index | Vector of indices to the Items property that specifies which Items are in this grouping.
[3] | Caption alignment | an integer: 1 = left aligned caption (the default) 2 = centre aligned caption 4 = right-aligned caption
[4] | State | Integer (not yet implemented)
[5] | Footer text | character vector (not yet implemented)

Note that State and Footer text are not yet implemented by Windows.

For example, the following expressions executed in the WTUTOR95 workspace will result in the display shown below.

      'F'⎕WC'Form' 'ListView Object'
      II←⍳⍴COUNTRIES
      'F.L'⎕WC'ListView'COUNTRIES(0 0)(100 100)('ImageList' 'F.I1')('ImageIndex' (⍳⍴COUNTRIES))
      'F.I1'⎕WC'ImageList'('Size' 32 32)
      (⊂'F.I1.')⎕WC¨(⊂'Icon' ''),¨↓⍉↑FLAGBITS FLAGCMAP FLAGMASK
      GROUPS←⊂'Europe'(11 4 5 6 7 8 9)
      GROUPS,←⊂'Americas'(12 3 2)
      GROUPS,←⊂'Rest of the World'(1 10)
      F.L.ItemGroups←GROUPS

You can control the appearance of the groupings using the ItemGroupMetrics property.


Items Property

Applies to: Combo, ComboEx, List, ListView, Spinner, TreeView

Description

This property specifies the list of items from which the user may choose.

The value of Items is a text array. It is normally specified as a vector of character vectors each of which represents an item. For a Combo, ComboEx, or List or Spinner, Items may also be a matrix whose rows specify items. If a character scalar or simple vector is specified, it is treated as a single item.

An empty character vector is treated the same as a vector of blanks, and represents one item.

A zero-length vector of vectors or an empty matrix represents 0 items. The default value for Items is an empty matrix.

⎕WG 'Items' returns an array of the same structure as was assigned by ⎕WC or ⎕WS.


Justify Property

Applies to: Button, Edit, Label, Spinner, TabControl

Description

This property determines the manner in which text is justified within the object. It is a character vector that may take the value 'Left' (the default), 'Centre' or 'Right'. The keyword 'Centre' may also be spelled 'Center'.

When applied to an Edit object with Style 'Multi', a value of 'Centre' or 'Right' forces word-wrapping and disables horizontal scrolling. Note that Justify only applies to a multi-line edit field. If you specify a value for Justify in a 1-line edit field (Style 'Single'), it will be ignored.

For a TabControl, Justify may be 'Right' (which is the default) or 'None' or empty.

If Justify is 'Right', the TabControl increases the width of each tab, if necessary, so that each row of tabs fills the entire width of the tab control. Otherwise, if Justify is empty or 'None', the rows are ragged.

With the exception of Label and TabControl objects, Justify may only be specified when the object is created using ⎕WC.


KeepBits Property

Applies to: Bitmap, Cursor, Icon

Description

This property is be used to control the way that Bitmap, Cursor and Icon objects are stored in the workspace.

When you create a Bitmap, Icon or Cursor using ⎕WC, APL asks Windows to allocate a corresponding bitmap, icon or cursor resource. This resource is allocated in Windows memory. If APL were to hold the values of the image properties (CBits, Bits and CMap for a Bitmap; Bits, CMap and Mask for Cursor and Icon objects) internally in the workspace, this data would be duplicated. For large bitmaps this would have a serious impact on memory utilisation and may affect performance. The KeepBits property is provided to allow you to control whether or not APL retains the values of the image properties in the workspace, so that you can choose a strategy to suit your configuration and requirements. KeepBits may take the value 0 or 1.

If KeepBits is 0 the values of the image properties are not stored internally in your workspace. If you save a workspace containing a Bitmap, Cursor or Icon object, the corresponding Windows resource is automatically re-allocated when the workspace is loaded by referring to the associated file. This is the file whose full pathname is defined by the value of the object's File property. It follows that if you adopt this strategy, you must ensure that the File property is set correctly. If APL cannot find the file when the workspace is )LOADed, it cannot re-create the object, and you will get a VALUE ERROR when you subsequently refer to it. A further consideration is the effect on ⎕WG. If KeepBits is 0, and you execute ⎕WG 'CBits' or 'Bits' or 'CMap' or 'Mask', APL obtains these values by requesting the data from Windows.

If KeepBits is set to 1, the contents of the image properties are stored in the workspace, thus duplicating the information which is held by Windows itself. If you save a workspace containing a Bitmap, Cursor or Icon the corresponding Windows resource is automatically re-allocated from the image properties when the workspace is loaded. The value of the File property is ignored. When you execute ⎕WG 'CBits' or 'Bits' or 'CMap' or 'Mask', APL generates the result directly from the stored values held (internally) in the workspace.


KeepOnClose Property

Applies to: (all objects)

This property is either 0 or 1 and determines how the object is treated when its parent Form (or, in the case of a Form, the Form itself) is closed by the user, receives a Close event from ⎕NQ, or when Close is called as a method.

If KeepOnClose is 1 (for the object itself and for all its parents) when its parent Form is closed, the object changes from being a GUI object to a pure namespace. For example, the Type of a Button will change from 'Button' to 'Namespace'. Effectively, the GUI component of the object is discarded but its Namespace component (and any variables, functions, operators and other namespaces that it contains) remains intact. Monadic ⎕WC may subsequently be used to re-attach the GUI component to the object.

Note that the default value of KeepOnClose depends upon the way in which a GUI object was created with ⎕WC. If a GUI object is created by dyadic ⎕WC, KeepOnClose defaults to 0. If a GUI object is attached by monadic ⎕WC, its KeepOnClose property defaults to 1.


LastError Property

Applies to: ActiveXControl, OLEClient, OLEServer, Root

The LastError property provides information about the most recent error reported by OLE. You may use this property to report an error from an OLEServer or ActiveXControl to a host application.


LicenseKey Property

Applies to: OCXClass

The LicenseKey property is a character string that contains the license key for an ActiveX control.

If an ActiveX control requires a license key, it must be specified by an application when it creates an instance of the control. Typically, the license key is required only by the run-time version of an ActiveX control, and is made available to an application by the development version of the control.


Limits Property

Applies to: ProgressBar, Scroll, Spinner, TrackBar, UpDown

This property is a 2-element vector that specifies the minimum and maximum values of an object.


Locale Property

Applies to: OLEClient

The Locale property specifies the language in which the OLE server, attached to an OLEClient, exposes its methods (functions) and properties (variables).

When you create an OLEClient object, Dyalog APL/W requests the default Type Library associated with the OLE server that you specify. Many OLE servers, such as Excel.Application, provide different names for the methods and properties they expose for different languages. Without Locale, it would be difficult to write an OLE client application that could run in different countries, as the names of the functions and variables may be unpredictable.

Locale is an integer; for example, the value 9 specifies English and the value 12 specifies French.

Locale may only be specified by the ⎕WC statement that is used to create the OLEClient; it may not subsequently be changed using ⎕WS. A table of commonly used Locale values is given below.

Note that Dyalog cannot guarantee that you will actually be given the Locale you specify. This is a function of your specific installation and the OLE server in question. However, Dyalog believes that for Microsoft products, it is a fairly safe bet that the US/English interface will be available in most countries.

Language | Locale
Neutral | 0
Danish | 6
Dutch | 19
English | 9
Finnish | 11
French | 12
German | 7
Italian | 16
Norwegian | 20
Portuguese | 22
Russian | 25
Spanish | 10
Swedish | 29


LocalAddr Property

Applies to: TCPSocket

The LocalAddr property is a character vector that specifies the IP address of your computer. Its default value is '0:0:0:0' which refers to your default IP address.

Unless your computer has more than one network adapter each identified by a different IP address, you do not need to specify LocalAddr. However, in this case you may use either LocalAddr or LocalAddrName to identify the adapter. If you specify both properties, the value of LocalAddrName will be ignored.

Note that you may also set the value of LocalAddr to an empty character vector. In this case, the value returned by ⎕WG will be '0:0:0:0'.

LocalAddr may only be specified in the ⎕WC statement that creates the TCPSocket and may not subsequently be changed using ⎕WS.


LocalAddrName Property

Applies to: TCPSocket

The LocalAddrName property is a character vector that specifies the host name of your computer. It may be useful when you have more than one network adapter (perhaps an Ethernet adapter and a token ring adapter) and you wish to avoid hard-coding the IP address.

Note that you may use either LocalAddr or LocalAddrName to identify the local computer. If you specify both properties, the value of LocalAddrName will be ignored.

LocalAddrName may only be specified by a server TCPSocket. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

When the specified host name has been resolved to an IP address, the TCPSocket will generate a TCPGotAddr event and update the value of LocalAddr accordingly.

For a client TCPSocket, you may not specify LocalAddrName and ⎕WG returns an empty character vector.


LocalPort Property

Applies to: TCPSocket

The LocalPort property is a scalar integer in the range 1-65536 that identifies the port number associated with a TCPSocket object.

Note that you may use either LocalPort or LocalPortName to identify the service. The use of LocalPortName is slightly slower but it avoids hard-coding the port number in your program and is generally more flexible. If you specify both properties, the value of LocalPortName will be ignored.

LocalPort may be specified only by the process that is initiating the connection (the server) and must be set by the ⎕WC statement that creates the TCPSocket. LocalPort may not subsequently be changed using ⎕WS

If you specify a value of 0, the system will assign an available port number. For example:

      'S1' ⎕wc'TCPSocket' ('LocalPort' 0)
      S1.LocalPort
4047

For a process that is completing a connection, LocalPort is allocated by the system and is effectively read-only.


LocalPortName Property

Applies to: TCPSocket

The LocalPortName property is a character vector that specifies the port name of the local service that you wish to offer as a server.

Note that you may use either LocalPort or LocalPortName to identify the service. The use of LocalPortName is slightly slower but it avoids hard-coding the port number in your program and is generally more flexible. If you specify both properties, the value of LocalPortName will be ignored.

LocalPortName may be specified only by the process that is initiating the connection (the server) and must be set by the ⎕WC statement that creates the TCPSocket. LocalPortName may not subsequently be changed using ⎕WS.

When the specified port name has been resolved to a port number, the TCPSocket will generate a TCPGotPort event and update the value of LocalPort accordingly.

For a client TCPSocket, you may not specify LocalPortName and ⎕WG returns an empty character vector.


LStyle Property

Applies to: Circle, Ellipse, Locator, Poly, Rect

Description

This property determines the type of line used to draw a graphics object. It takes one of the following integer values, or, if the object contains more than one component, a vector of such values.

0 | solid line
1 | dashed line
2 | dotted line
3 | dash dotted line
4 | dash dot dotted line
5 | null line (invisible)

If LStyle is in the range 1-4, the gaps between the dashes and dots are drawn using the colour specified by BCol, or are left undrawn (i.e. transparent) if BCol is not defined.

If LWidth specifies a line width greater than 1 pixel, the value of LStyle is ignored and a solid (thick) line is drawn regardless.


LWidth Property

Applies to: Circle, Ellipse, Poly, Rect

Description

This property determines the width of line used to draw a graphics object. A positive value specifies the line width in pixels. A negative value specifies line width in units of the co-ordinate system defined for the object in the x direction. If the object contains more than one component, LWidth may be a vector.

If LWidth specifies a line width greater than 1 pixel, a solid (thick) line is drawn regardless of the value of LStyle.


MapCols Property

Applies to: ImageList

The MapCols property specifies whether or not the button colours in bitmaps and icons in an ImageList are re-mapped to reflect the users colour preferences. If your bitmaps and icons represent buttons using the standard windows button colours, this property causes those colours to be changed to suit the user’s own colour scheme.

MapCols is a single number with the value 0 (no colour mapping) or 1 (colours are automatically re-mapped. The default is 0.

If MapCols is 1, the following colour mappings are performed:

Colour | Description | Mapped to
0 0 0 | Black | Button Text
128 128 128
 Dark grey Button Shadow
191 191 191
 Light grey Button Face
192 192 192
 Light grey Button Face
255 255 255 | White | Button Highlight


Mask Property

Applies to: Cursor, Icon

Description

This property is used to specify how the bitmap for a Cursor or Icon interacts with the pixels of the screen when it is displayed.

When a Cursor or Icon is displayed, the colour of each pixel occupied by the object on the screen is determined by :

  • The colour specified by Bits via CMap
  • The value of Mask
  • The existing colour of the screen pixel

Mask is a boolean matrix with the same shape as the Bits property. See Cursor and Icon objects for further details.


MaskCol Property

Applies to: Bitmap, Form

Specifies the transparent colour for a Bitmap or Form.

MaskCol may be an integer scalar or a 3-element integer vector.

If MaskCol is 0 (the default), no transparent colour is defined.

If MaskCol is a negative scalar, it specifies a standard Windows colour. See Bcol for details.

Otherwise, MaskCol is a 3-element vector of intergers in the range 0-255 that specifies the transparent colour in terms of RGB values (the intensity of the red, green and blue components of colour).

For a Bitmap, if MaskCol is non-zero, any pixels specified with the same colour will instead be displayed in whatever colour is underneath the Bitmap. This achieves similar behaviour to that of an Icon.

For a Form, if MaskCol is non-zero, any of the contents of the Form that are specified to be the same colour as MaskCol will be transparent. For example, if MaskCol is 255 0 0 (red), any red items contained in the Form will instead be transparent areas, displaying whatever is behind them on the screen. Mouse events generated over such transparent areas will be passed to any other windows behind them, and will not be reported on the Form itself.


Masked Property

Applies to: ImageList

The Masked property specifies whether or not the ImageList will contain masked images, i.e. icons. Its default value is 1 which means that the ImageList expects Icons. If you want to use BitMap objects in an ImageList, you must set Masked to 0. An inappropriate value of Masked will cause the images to be drawn incorrectly.

Masked must be established when the ImageList is created by ⎕WC and may not subsequently be altered.


MaxButton Property

Applies to: Form, SubForm

Description

This property determines whether or not a Form or a SubForm has a "maximise" button. Pressing this button will cause a Form to be resized to occupy the entire screen, or a SubForm to occupy the entire area of its parent. Pressing it again will restore the Form or SubForm to its original size. MaxButton is a single number with the value 0 (no maximise button) or 1 (maximise button is provided). The default is 1.

Note that MaxButton is independent of Sizeable, i.e. you can define a Form that can be maximised but not resized. If any of the properties MaxButton, MinButton, SysMenu and Sizeable are set to 1, the Form or SubForm will have a title bar.


MaxDate Property

Applies to: Calendar, DateTimePicker

The MaxDate property specifies the largest date that the user may select in a Calendar object or in the calendar drop-down of a DateTimePicker.

MaxDate is an IDN value. Its default value is 11249470 which is the maximum date that the Calendar can display.


MaxLength Property

Applies to: Edit, Spinner

Description

This property specifies the maximum number of characters that the user may enter in a single-line Edit object ( Style 'Single') or in the edit field associated with a Spinner. It does not apply to a multi-line Edit object (Style 'Multi'). MaxLength does not limit the length of the vector that you may assign to the Text property using ⎕WC or ⎕WS. However, if you overfill the field in this way, the user must delete excess characters before the object will accept further input.


MaxSelCount Property

Applies to: Calendar

The MaxSelCount property specifies the maximum number of contiguous days that the user may select in a Calendar object.

MaxSelCount is an integer whose default value is 7.

MaxSelCount is ignored unless the Style property of the Calendar object is set to 'Multi'.


MDIActive Property

Applies to: MDIClient

Description

This property contains the name of the SubForm owned by the MDIClient that is currently active. Only one SubForm may be active at a time. You can switch between SubForms in an MDI application under program control by setting this property with ⎕WS. You can also do this by generating an MDIActivate event.

See also MDIActiveObject property.


MDIActiveObject Property

Applies to: MDIClient

Description

This property contains a ref to the SubForm owned by the MDIClient that is currently active.

See also MDIActive property.


MDIMenu Property

Applies to: MenuBar

Description

This property specifies the name of, or ref to, the Menu object that is nominated as the “Window” menu in an MDI application. If such a menu is defined, the Captions of all the child Forms are automatically added to it below any other Menu or MenuItem objects that the application has created directly. This list is separated from the preceding items by a separator. The entry for the currently active SubForm is checked and the user may switch between SubForms by selecting from this list.

Note that the additional separator and the items representing the list of child forms are not Dyalog APL/W objects and may not be accessed by the application. If you prefer to maintain your own “window list” you should not use this property.


MetafileObj Property

Applies to: Clipboard

Description

This property is used to copy graphical data to and from the Windows clipboard using the Windows Metafile format.

When you set the MetafileObj property of a Clipboard object to the name of the Metafile object using ⎕WS its contents are copied to the Windows clipboard in Windows Metafile format.

To import a picture that has been stored in the Windows clipboard in Metafile format you use ⎕WG. This returns a nested array whose elements correspond to the graphical components of the picture. Each of the elements of the array may be used as the arguments of ⎕WC to draw the corresponding component of the picture. For example, if the picture stored in C:\MSOFFICE\CLIPART\BIRD.WMF is copied to the Windows clipboard, it may be imported into Dyalog APL/W as follows :

      BIRD ← 'CL' ⎕WG 'MetafileObj'
      ⍴BIRD
4

Each of the items in BIRD is a 2-element vector. The first element is a “dummy” object name which you may use or ignore as you wish. The second element is an array that defines a graphical object and is suitable as the right argument of ⎕WC. For example :

      2⊃4⊃BIRD
POLY  191 397   FSTYLE  0   FILLCOL  0 0 0    ...

190 402
187 406
182 409
176 410
172 409
168 406
165 402
164 397
165 391
168 387
172 384
176 383
182 384
187 387
190 391
191 397
189 395
191 397

From this array, you can rebuild the imported picture component by component, either as a Metafile object or directly onto a Form, Static or another object. The following example draws the picture in a Form using the dummy names supplied.

      'TEST' ⎕WC 'FORM' ('Coord' 'User')
      'TEST' ⎕WS ('YRange' 0 1024)('XRange' 0 2048)
      TEST.⎕WC/¨BIRD

Notice that the co-ordinates of each of the graphical components are typically integers in a co-ordinate system that extends from 0 to 1024 in the y-direction and 0 to 2048 in the x-direction. The simplest way to draw the picture is therefore to set up the same co-ordinate system on a Form as in the example above.


MethodList Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetControl, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This property reports the names of all the methods supported by a particular COM object or instance of an OLE control. It is a vector of character vectors returned by ⎕WG. It may not be set using ⎕WC or ⎕WS.


MinButton Property

Applies to: Form, SubForm

Description

This property determines whether or not a Form or SubForm has a "minimise" button. Pressing this button will cause the Form or SubForm to be iconified. Pressing it again will restore the Form to its original size. MinButton is a single number with the value 0 (no minimise button) or 1 (minimise button is provided). The default is 1.

Note that MinButton is independent of Sizeable, i.e. you can define a Form that can be minimised but not resized.

If any of the properties MinButton, MaxButton, SysMenu, and Moveable are set to 1, the Form or SubForm will have a title bar.


MinDate Property

Applies to: Calendar, DateTimePicker

The MinDate property specifies the smallest date that the user may select in a Calendar or DateTimePicker object.

MinDate is an IDN value. Its default value is -109206 which is the minimum date that the Calendar can display.


MonthDelta Property

Applies to: Calendar, DateTimePicker

The MonthDelta property specifies the number of months by which a Calendar object scrolls when the user clicks its scroll buttons.

MonthDelta is an integer or an empty vector (zilde). The latter means that the Calendar object scrolls by the number of months that are currently displayed in its window. This is the default.


Moveable Property

Applies to: Form, SubForm

Description

This property determines whether or not a Form or SubForm can be moved by the user. It is a single number with the value 0 (Form cannot be moved) or 1 (Form is moveable). If any of the properties MinButton, MaxButton, SysMenu, and Moveable are set to 1, the Form or SubForm will have a title bar. However, a Form or SubForm with a title bar is not necessarily moveable.


MultiColumn Property

Applies to: List

MultiColumn is boolean and specifies whether or not a List object displays its items in a single column (0, the default) or in multiple columns (1). MultiColumn may only be set by ⎕WC and cannot be changed using ⎕WS after the object has been created. Note that a MultiColumn List will use the minimum number of columns that are required to make the items fit within it and will reconfigure itself automatically when resized. The following example illustrates its use.

      'F'⎕WC'Form' 'MultiColumn List'('Size' 23 32)
      'F.L'⎕WC'LIST' AIRPORTS (0 0)(100 100)('MultiColumn' 1)


MultiLine Property

Applies to: TabControl, ToolControl

The MultiLine property determines whether or not the tabs or buttons will be arranged in multiple flights or multiple rows/columns in a TabControl or ToolControl object.

MultiLine is a single number with the value 0 (single flight of tabs, or single row/column of buttons) or 1 (multiple flights of tabs or multiple rows/columns of buttons); the default is 0.

If MultiLine is 0 and there are more tabs or buttons than will fit in the space provided, the TabControl displays an UpDown which allows the user to scroll.

However, If MultiLine is 0 in a ToolControl, the buttons are clipped, and the user may have to resize the object to see them all.

See also: Justify, TabSize.


MultiSelect Property

Applies to: TabControl

The TabControl property specifies whether or not the user can select more than one button in a TabControl at the same time, by holding down the Ctrl key when clicking.

MultiSelect is a single number with the value 0 (only 1 button may be selected) or 1 (more than one button may be selected); the default is 0.

MultiSelect apples only if the Style of the TabControl is 'Buttons' or 'FlatButtons', and is ignored if Style is 'Tabs'.

Note that the State property of the associated TabButton object reports whether or not the button is selected.


NewLine Property

Applies to: CoolBand

The NewLine property specifies whether or not a CoolBand occupies the same row as an existing CoolBand, or is displayed on a new line within its CoolBar parent.

NewLine is a single number with the value 0 (same row) or 1 (new row); the default is 1.

The value of NewLine in the first CoolBand in a CoolBar is always 1, even if you specify it to be 0.

When the user drags a CoolBand to another row, the value of its NewLine property, and that of any other CoolBand affected by the move, will change.

You may move a CoolBand to the previous or next row by changing its NewLine property (using ⎕WS )from 1 to 0, or from 0 to 1 respectively.


OKButton Property

Applies to: Form

OKButton applies only to PocketAPL. In versions of Dyalog APL for other platforms, it has no effect.

This is a Boolean property that specifies whether or not an [OK] button appears in the title bar of a Form. Its default value is 0.

OKButton may only be specified when the Form is created using ⎕WC; you cannot subsequently change its value.

If OKButton is 1, the Form displays an [OK] button in its title bar in place of the standard [X] button.

When the user clicks the [OK] button, the system will press the default button, which is specified by the Default property of a Button on the Form.

If there is no default button, the Form will generate a Close event.


OLEControls Property

Applies to: Root

The OLEControls property reports a list of the OLE Controls installed on your computer. This information is obtained from the Windows registry. Its value is a nested vector with one element per OLE Control. Each element is a vector of 2-element character vectors. The first is the name of the OLE Control; the second is its class identifier.


OLEServers Property

Applies to: Root

The OLEServers property is a read-only property that reports the names and CLSIDs of all the OLE Automation servers installed on your computer. This information comes from the Windows registry.

Its value is a nested vector with one element per OLE Server.

Each element is a vector of 2-element character vectors. The first is the name of the OLE Server; the second is its class identifier or CLSID which is a type of GUID.


OnTop Property

Applies to: Circle, Ellipse, Form, Image, Marker, Poly, PropertySheet, Rect, SubForm, TabBar, Text, ToolBar

Description

This property may be used to cause a Form or SubForm to be displayed on top of all other windows, even those owned by other applications.

Normally, Forms are brought to the front when they receive the input focus. Forms that do not have the input focus may be partially obscured by the one that does. If OnTop is set to 1, the Form or SubForm remains at the front even if it doesn't have the input focus. Indeed, it may partially obscure the Form that does have the focus. The default value is 0 (normal).

More than one Form may have OnTop set to 1. If so, these Forms appear on top of all others, but may overlap one another. Other applications may also have windows with this property.

For a graphical object, the OnTop property controls how it is drawn in a Grid relative to the grid lines and cell text. OnTop is applicable only if the graphic is the child of a Grid and is otherwise ignored.

0 | Graphical object is drawn behind grid lines and cell text
1 | Graphical object is drawn on top of grid lines but behind cell text
2 | Graphical object is drawn on top of grid lines and cell text


Orientation Property

Applies to: Printer

The Orientation property specifies the orientation of the paper on a Printer object. It is a simple character vector which is either 'Portrait' or 'Landscape'. When you create a Printer object, the default value of the Orientation property is determined by the current setting for the corresponding printer device.

The effect of changing Orientation using ⎕WS is to spool the current page (effectively the same as sending a NewPage event) and then to change the orientation of the paper. Note that the values of the first 2 elements of the DevCaps property change accordingly.

You may also set Orientation when you create the Printer object with ⎕WC.

In neither case does the global setting for the printer device change.


OtherButton Property

Applies to: ColorButton

The OtherButton property is Boolean and specifies whether or not the user can select a colour from a ColorButton object using the Windows colour selection dialog box.

If OtherButton is 1 (the default), the final row of the colour selection drop-down contains a button labelled "Other…". If the user clicks this button, the standard Windows colour selection dialog box is displayed, allowing the user to select any colour that the computer can render.

Note that the Pocket PC 2002 colour selection dialog box does not provide the facility to select custom colours, so this functionality is not available in PocketAPL.

If OtherButton is 0, the button labelled "Other…" is not present and the user is restricted to the choice of colours provided by the DefaultColors property.


OverflowChar Property

Applies to: Grid

The OverflowChar property specifies the character to be displayed in place of the digits when a numeric value cannot be displayed in its entirety in a Grid cell. If the value of OverflowChar is an empty vector (the default) the data in a numeric cell is simply clipped if it is too wide to fit in the cell. For example:

   'F'⎕WC'Form'('Coord' 'Pixel')('Size' 101 296)
   'F'⎕WS'Caption' 'OverflowChar Property'
   DATA←3 3⍴12 123456789 13 9876543 99 456 10 99 1236.893
   'F.G'⎕WC'Grid'DATA(0 0)(101 296)
   'F.G'⎕WS'CellWidths' 65
   'F.G'⎕WS'OverflowChar' '#'

The same Grid without OverflowChar being defined appears as follows. Notice how the numbers have been truncated


PageActive Property

Applies to: PropertySheet

The PageActive property specifies the name of the current PropertyPage in a PropertySheet. You may select a particular page by setting this property or by generating a PageActivate event.

See also or PageActiveObject.


PageActiveObject Property

Applies to: PropertySheet

The PageActiveObject property specifies a ref to the current PropertyPage in a PropertySheet. You may select a particular page by setting this property or by generating a PageActivate event.

See also or PageActive.


PageWidth Property

Applies to: RichEdit

The PageWidth property specifies the width of the page in a RichEdit object and is the dimension that is used to apply text wrapping and paragraph formatting to the text in the object. PageWidth is a single integer value specified in Twips. The default value of PageWidth is 0 which disables text wrapping. You may find it convenient to set PageWidth to the width of the RichEdit window or to a value that is appropriate for your printer.


PaperSize Property

Applies to: Printer

The PaperSize property specifies the size of paper to be used for printing

PaperSize may be a character vector containing the name of the paper size (eg. 'Legal 8 1/2 x 14 in' or 'A4 210 x 297 mm') or a 2-element integer vector that specifies the desired height and width of the paper in tenths of a millimetre (e.g. 3556 2159 or 2970 2099).

The default value of PaperSize is the name of the paper size associated with the current printer settings.

You can obtain a list of supported paper sizes from the PaperSizes property.


PaperSizes Property

Applies to: Printer

The PaperSizes property is a read-only property that provides the names and dimensions of the various different paper sizes supported by the printer associated with the Printer object.

PaperSizes is a nested vector of 2-element vectors which contain the name, and height and width of each paper size respectively. Dimensions are reported in tenths of a millimetre.

You may set or query the current paper size using the PaperSize property.


PaperSource Property

Applies to: Printer

The PaperSource property is a character vector that specifies the name of the paper bin to be used as the paper source for printing.

An empty character vector (the default) means the default bin, Otherwise, PaperSource must be a member of the PaperSources property.


PaperSources Property

Applies to: Printer

The PaperSources property is a read-only property that provides the names of the paper bins installed on the printer associated with the Printer object. It is a vector of character vectors.

You may select which of the bins is to be used by specifying the PaperSource property.


ParaFormat Property

Applies to: RichEdit

The ParaFormat property describes the current paragraph format or the paragraph format of the currently selected text in a RichEdit object. It is a 6-element nested array structured as follows:

[1] | A character vector that specifies the text alignment. This may be 'Left' (the default), 'Right' or 'Centre'
[2] | The size of the indentation of the first line in the paragraph measured from the left margin in Twips.
[3] | The size of the horizontal offset of the start of the second and subsequent lines. This is measured in Twips relative to the first line indentation specified in element [2].
[4] | The size of the right indentation measured in Twips from the right margin.
[5] | An integer value specifying the bullet/numbering option. 0 mean no numbering, 1 means bullets.
[6] | An integer vector specifying the size of any tab stops measured in Twips from the left margin and specified in ascending order.

If there is no text selected, ParaFormat specifies the current paragraph formatting format, i.e. that which will be used to format the current (and subsequent) lines of characters that the user enters. If there is text selected ParaFormat specifies the paragraph formatting of the selected block of text. If the format is not strictly homogeneous, ⎕WG will report the format of the first paragraph in the selected block

(⎕WS 'ParaFormat' ...) will set the format of the currently selected block of text. To set the format of an arbitrary block of text you must select it first using (⎕WS 'SelText' ...).


Password Property

Applies to: Edit, Spinner

Description

This property specifies the character that is echoed when a user enters data into a single-line Edit object ( Style 'Single'). It does not apply to a multi-line object (Style 'Multi'). If Password is empty (the default) the character echoed is the same as the character the user entered. If Password is set to (say) the asterisk character (*), the object will display asterisks as the user types into it.


PathWordBreak Property

Applies to: ComboEx

If set, the edit control portion of the ComboEx will use the forward slash (/), back slash (\), and period (.) characters as word delimiters. This makes keyboard shortcuts for word-by-word cursor movement (Ctrl + arrow keys) effective inn path names and URLs.

This property is ignored under Windows 95/98.


Picture Property

Applies to: ActiveXControl, Button, Clipboard, CoolBand, Form, Group, Image, MDIClient, SM, Static, StatusBar, StatusField, SubForm, TabBar, ToolBar

Description

The Picture property specifies a bitmap, icon, or other image for an object.

For Button, Form, Group, MDIClient, Static, StatusBar, StatusField, SubForm, SM, TabBar or ToolBar, this property specifies the name of, or ref to, a Bitmap, Icon, or Metafile which is drawn as a background on the object. Other controls and graphical objects are drawn on top of this background.

When it refers to a Metafile, the Picture property specifies the name of, or ref to, the Metafile to be drawn in the object. When it refers to a Bitmap or Icon, the value of the Picture property is a 2-element vector whose elements specify the name of, or ref to, the Bitmap, or Icon, and the manner in which it is displayed. This is specified as an integer as follows:

0 | The Bitmap or Icon is drawn in the top left corner of the object.
1 | The Bitmap or Icon is tiled (replicated) to fill the object.
2 | The Bitmap is scaled (up or down) to fit exactly in the object. This setting does not apply to an Icon whose size is fixed.
3 | The Bitmap or Icon is drawn in the centre of the object. This is the default. Note that the centre of the Bitmap is positioned over the centre of the object, so that you see the middle portion of a Bitmap that is larger than the object in which it is displayed.

For example, the following statements produce a Form filled with the CARS bitmap.

      'CARS' ⎕WC 'Bitmap' 'C:\WINDOWS\CARS'
      'f1' ⎕WC 'Form' ('Picture' 'CARS' 1)

An easy way to provide a customised pushbutton is to create a Button whose Picture property specifies the name of, or ref to, a Bitmap or Icon, using drawmode 3 (the default). This causes the corresponding bitmap or icon to be drawn in the centre of the Button. So long as the Button is larger than the bitmap or icon, its borders (which give it its 3-dimensional appearance and “pushbutton” behaviour) will be unaffected. Note that if Picture is set on a Button whose Style is 'Radio' or 'Check', the Button assumes pushbutton appearance, although its radio/check behaviour is preserved.

For an Image object, the Picture property specifies the name of, or ref to, a Bitmap, Icon or Metafile object to be drawn, or a vector of names or refs. The Image is a graphical object and is drawn on top of the background. It does not support the drawmode options provided by the objects in which Picture specifies the background.

For the Clipboard object, Picture is a "set-only" property that allows you to place a specified Bitmap object into the Windows clipboard. To place a Metafile object into the clipboard, use its Metafile property.


PName Property

Applies to: Font, Printer

Description

This property is a character vector that specifies the face name for a Font object, or the printing device associated with a Printer. It is case-independent.

For a Printer, PName contains the description of the printer followed by a comma (,) and then the device to which it is attached. The device ends with a colon (:).

Example:

      'PR1' ⎕WC 'Printer'
      'PR1' ⎕WG 'PName'
IBM 4039 LaserPrinter PS,LPT2:


Points Property

Applies to: Circle, Ellipse, Image, Marker, Poly, Rect, Text

Description

This property specifies the co-ordinates for a graphics object. It may define a single set of co-ordinates, or be a nested vector containing several sets of co-ordinates.

Each set of co-ordinates may be:

a) a 2-column numeric matrix containing y-values in column 1 and x-values in column 2.

or

b) a 2-element numeric vector whose first element specifies y-values and whose second element specifies x-values. The two elements must be of equal length unless one or both is a scalar in which case scalar extension applies.

For further details, see the specifications for the relevant objects.


Popup Property

Applies to: SysTrayItem, ToolButton

The Popup property specifies the name of, or ref to, a (popup) Menu object that is associated with a SysTrayItem or ToolButton.

Note that Popup is ignored unless Style is set to 'DropDown'.


Posn Property

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBand, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, Locator, MDIClient, Menu, MenuItem, NetControl, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, TabButton, TabControl, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

With the exception of Menu, MenuItem and Separator objects, Posn is a 2-element numeric vector specifying the y-position and x-position respectively of the top-left corner of the object relative to its parent. For a Form, Posn specifies its position on the screen. The units are defined by the Coord property.

When specifying Posn for ⎕WC, you can allow the y-position or x-position to assume a default value by giving the corresponding element a value of <—>.

Using ⎕WS, if you want to set the y-position, but not the x-position, or vice-versa, you should specify <—> for the item you don't want to change.

For Menu, MenuItem and Separator objects, Posn is a single integer that specifies the position at which the object is to be inserted in its parent. For example, to add a new MenuItem between the third and fourth items in an existing Menu, you would specify its Posn as 4. For these objects, the value of Posn returned by ⎕WG is the current index of the object within its parent.


PrintList Property

Applies to: Root

Description

This property provides a list of the printers that are installed on your computer system, i.e. those listed when you select "printers" from the MS-Windows Control Panel. It is a "read-only" property of the Root object '.'.

PrintList is a vector of character vectors. Each item in PrintList contains the name of an installed printer followed by a comma (,) and then the name of the device to which it is attached. The first item in PrintList is the default system printer.

Example:

      DISPLAY '.' ⎕WG 'PrintList'
.→------------------------------.
| .→--------------------------. |
| |HP Laserjet Series II,LPT1:| |
| '---------------------------' |
'∊------------------------------'


PrintRange Property

Applies to: Printer

The PrintRange property specifies the range of pages to be printed.

PrintRange may be an empty character vector (the default), or 'All', either of which will cause all pages to be printed.

Alternatively, PrintRange may be a 3 or 4-element nested array whose items are:

[1] | 'Pages'
[2] | Start page (integer)
[3] | End page (integer)
[4] | Maximum number of pages (integer)

In this case, printing starts at the page specified to be the Start page, and ends at the page specified by End page or after the Maximum number of pages has been reached, whichever is sooner.


ProgressStyle Property

Applies to: ProgressBar

The ProgressStyle property specifies the appearance of a ProgressBar control.

ProgressStyle is a character vector that may be 'Normal' or 'Smooth'. Its value is effective only when the object is created with ⎕WC. Changing ProgressStyle with ⎕WS has no effect on the appearance or behaviour of the ProgressBar.

If ProgressStyle is 'Normal', the highlight in the centre of the ProgressBar is displayed as a broken bar. This is the default.

If ProgressStyle is 'Smooth', the highlight in the centre of the ProgressBar is displayed as a solid block of colour.

If ProgressStyle is 'Marquee', the the highlight in the centre of the ProgressBar is displayed as a broken bar that moves continuously from left to right. The speed is controlled by the Interval Property which deternines the frequency in milliseconds with which the highlight is redrawn, each time further along the ProgressBar. The special value of ¯1 causes the animation to stop.

Note that 'Marquee' will only be honoured if XP Look and Feel is enabled.

The picture below illustrates the appearance of the different values of ProgressStyle.


PropList Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetControl, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This is a "read-only" property that supplies a list of all other properties which are applicable to the object in question. The list is returned as a vector of character vectors in the order in which the corresponding properties are expected by ⎕WC and ⎕WS.

Example:

      'F'    ⎕WC 'Form'
      'F.MB' ⎕WC 'MenuBar'
      'F.MB' ⎕WG 'PropList'
 Type  Visible  FontObj  Data  EdgeStyle  MDIMenu  PropList


QueueEvents Property

Applies to: OCXClass, OLEClient

The QueueEvents property specifies whether or not incoming events generated by an COM object are queued.

QueueEvents is a single number with the value 1 (queue events) or 0 (process events immediately). The default value is 1.

If QueueEvents is 1, the result (if any) of your callback function is not passed back to the COM object but is discarded. Thus you cannot, for example, inhibit or modify the default processing of the event by the COM object.

If QueueEvents is 0, the following applies.

The callback function attached to the event is executed immediately, even if there are other APL events before it in the internal event queue. This immediate execution means that your callback can fire during the execution of any other function, including a callback function on an APL event. You must therefore take care that the callback makes no references to objects that may be shadowed.

The result of your callback function is then passed back to the COM object. In this situation, it is essential that the callback is not interrupted by other events from the same, or another instance, of an COM object.

To prevent APL itself from yielding to Windows, the Yield property is temporarily and automatically set to 0 while the callback is run. For the same reason, the tracing of a callback function, that is run immediately in this way, is disabled.

However, you must yourself also ensure that your own code does not yield. This means that you may not perform any operation in your callback that would yield to Windows; these include:

  • ⎕DL
  • certain uses of ⎕NA
  • external function calls to Auxiliary Processors

If your callback does yield to Windows, thereby allowing another COM object event to arrive, this second event and any subsequent events that arrive during the execution of the callback are queued and will be processed later. These events may therefore not be modified by their callback functions.


Radius Property

Applies to: Circle, Rect

Description

For a Circle object, this property is a single number that specifies the radius of the circle/arc or a numeric vector that specifies the radii of a set of circles/arcs.

For a Rect object, Radius is a 2-element vector that specifies the curvature of the corners of the rectangle or set of rectangles to be drawn. The curvature is defined in terms of the vertical and horizontal radii of an ellipse. The first element of Radius defines the radius vertically, the second horizontally. If more than one rectangle is involved, either or both of the elements of Radius may be vectors. The default value is (0,0) which gives square corners.


Range Property

Applies to: Form, Scroll, SubForm

Description

This property determines the maximum value of the thumb in a scrollbar (the minimum value is always 1). This may be any positive integer value that is greater than 1.

For a Scroll object Range is a single number. For a Form or SubForm object, Range is a 2-element vector which specifies the maxima for the Form's vertical and horizontal scrollbars respectively.


ReadOnly Property

Applies to: Button, Edit, Spinner

Description

This property specifies whether or not the user may alter the text in an object. The default value of ReadOnly is 0 which allows the user to alter text.

If you set ReadOnly to 1, a cursor is displayed in the object, the user may navigate around the text in the usual manner with the mouse and/or the keyboard and select text and copy it to the clipboard. However, all input that would otherwise change the data is ignored.

For a Button object with Style 'Radio' or 'Check', setting ReadOnly to 1 prevents the user from changing the state of the Button, although mouse and other events will still be reported.


RealSize Property

Applies to: Metafile

There are several distinct types of Windows metafiles. A placeable metafile is one that carries with it its suggested size. Certain programs (such as Word for Windows) only support placeable metafiles.

The RealSize property specifies the suggested size of a Metafile in units of 0.01mm. Thus to make a placeable Metafile with a suggested size of 20 x 10 cm, you would set RealSize to (20000 10000).

The RealSize property is not used or required by Dyalog APL/W and is provided only to enable you to make and save a new metafile that is placeable. If you create a Metafile object from a file, the value of RealSize will be obtained from the value recorded in the file (if it is placeable). Otherwise, RealSize will be (0 0). If so, you must set RealSize to make it placeable. Each element of RealSize must be an integer in the range 0-144745.


Redraw Property

Applies to: ActiveXControl, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TrackBar, TreeView, UpDown

The Redraw property specifies whether or not APL automatically redraws an object when it is exposed or when any of its properties change in a way that would affect its appearance.

The value reported by the Redraw property is a Boolean value; 1 means that APL automatically redraws the object when necessary (the default); 0 means that APL does not redraw the object.

Setting Redraw to 0 or 1 affects only whether or not APL will redraw the object from then on.

In addition to the values 0 and 1, you may set Redraw to 2. This has the same effect as setting it to 1, but object is also redrawn immediately.


RemoteAddr Property

Applies to: TCPSocket

The RemoteAddr property is a character vector that specifies the IP address of the remote computer.

RemoteAddr may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

You may use either RemoteAddr or RemoteAddrName to identify the remote computer. If you know its IP address, it is normally quicker to specify RemoteAddr. If you specify both properties, the value of RemoteAddrName will be ignored.

For a server TCPSocket, RemoteAddr is determined by the IP address of the connecting process and is a read-only property.


RemoteAddrName Property

Applies to: TCPSocket

The RemoteAddrName property is a character vector that specifies the host name of the remote computer to which you wish to make a connection.

RemoteAddrName may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

When the specified host name has been resolved to an IP address, the TCPSocket will generate a TCPGotAddr event and update the value of RemoteAddr accordingly.

Note that you may use either RemoteAddr or RemoteAddrName to identify the remote computer. If you know its IP address, it is normally quicker to specify RemoteAddr. If you specify both properties, the value of RemoteAddrName will be ignored.

For a server TCPSocket, you may not specify RemoteAddrName and ⎕WG returns an empty character vector.


RemotePort Property

Applies to: TCPSocket

The RemotePort property is a scalar integer in the range 1-65536 that identifies the port number associated with a service on a remote computer.

RemotePort may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

Note that you may use either RemotePort or RemotePortName to identify the remote service. If you know the port number, it is normally quicker to specify RemotePort. However unless it is a well known port number, the use of a port name is generally more flexible. If you specify both properties, the value of RemotePortName will be ignored.

For a server TCPSocket, RemotePort is determined by the port number of the connecting process and is a read-only property.


RemotePortName Property

Applies to: TCPSocket

The RemotePortName property is a character vector that specifies the port name of the remote service to which you wish to make a connection.

RemotePortName may only be specified by a client TCPSocket that is intended to make a connection with a server. Furthermore, it must be specified in the ⎕WC statement that creates the TCPSocket object and it may not subsequently be changed using ⎕WS.

When the specified port name has been resolved to a port number, the TCPSocket will generate a TCPGotPort event and update the value of RemotePort accordingly.

Note that you may use either RemotePort or RemotePortName to identify the remote service. If you know the port number, it is normally quicker to specify RemotePort. However unless it is a well known port number, the use of a port name is generally more flexible. If you specify both properties, the value of RemotePortName will be ignored.

For a server TCPSocket, you may not specify RemotePortName and ⎕WG returns an empty character vector.


ReportInfo Property

Applies to: ListView

The ReportInfo property is a matrix that is displayed alongside each item in a ListView object when its View property is 'Report'. Each element of the matrix may be a character vector or a number.

The information is displayed in a grid format, the first column of which contains the item labels and their icons. Subsequent columns of the grid are defined by the corresponding columns of ReportInfo. The alignment of the columns is specified by the ColTitleAlign property.


ResizeCols Property

Applies to: Grid

Description

This property determines whether or not the user may resize columns in the Grid. It is a boolean scalar or vector with one element per column. A value of 1 indicates that the corresponding column is resizable by the user. A value of 0 means that the corresponding column may not be resized by the user.

If a column is resizable, the cursor changes to a double headed arrow when the mouse pointer is placed over the right-hand border of the column title. The user may resize the column by dragging this border. The user may also resize a column by double-clicking over its right-hand border. This causes the column to be resized to fit the data and the width of the column is automatically adjusted to display the widest value in any of its cells. Either operation generates a SetColSize event.

Note that the user may cause the column to disappear altogether by dragging it to a zero width. Once this has been done, this column may only be restored if the column to its left is itself not resizable.


ResizeColTitles Property

Applies to: Grid

Description

This property determines whether or not the user may alter the height of the column titles in the Grid. It is either 1, which indicates that the height of the column titles is adjustable by the user, or 0 which means that it is not.

If the height of the column titles is adjustable, the cursor changes to a double headed arrow when the mouse pointer is placed over the top border of the first row title The user may resize the column titles by dragging this border. The user may also resize the column titles by double-clicking over this border. This causes the column titles to be resized to fit the data and the height of the column titles is automatically adjusted to display the tallest heading in any of its columns. Either operation generates a SetRowSize event. The value of the row number reported by the event is ¯1.

Note that the user may cause the column titles to disappear altogether by dragging them to a zero height. Once this has been done, the row titles cannot be restored.


ResizeRows Property

Applies to: Grid

Description

This property determines whether or not the user may resize rows in the Grid. It is a boolean scalar or vector with one element per column. A value of 1 indicates that the corresponding row is resizable by the user. A value of 0 means that the corresponding row may not be resized by the user.

If a row is resizable, the cursor changes to a double headed arrow when the mouse pointer is placed over the lower border of the row title. The user may change the height of the row by dragging this border up and down. The user may also resize a row by double-clicking over its bottom border. This causes the row to be resized to fit the data and the height of the row is automatically adjusted to display the tallest value in any of its cells. Either operation generates a SetRowSize event.

Note that the user may cause the row to disappear altogether by dragging it to a zero height. Once this has been done, this row may only be restored if the row above it is itself not resizable.


ResizeRowTitles Property

Applies to: Grid

Description

This property determines whether or not the user may alter the width of the row titles in the Grid. It is either 1, which indicates that the width of the row titles is adjustable by the user, or 0 which means that it is not.

If the width of the row titles is adjustable, the cursor changes to a double headed arrow when the mouse pointer is placed over the left-hand border of the first column title. The user may resize the row titles by dragging this border. The user may also resize the row titles by double-clicking over this border. This causes the row titles to be resized to fit the data and the width of the row titles is automatically adjusted to display the longest string in any of its rows. Either operation generates a SetColSize event. The value of the column number reported by the event is ¯1.

Note that the user may cause the row titles to disappear altogether by dragging them to a zero width. Once this has been done, the row titles cannot be restored.


Resolution Property

Applies to: Printer

The Resolution property determines the print resolution.

You may set Resolution to 'Draft', 'Low', 'Medium' or 'High'.

Alternatively, you can set Resolution to a 2-element integer vector that specifies the desired number of dots per inch in the x (horizontal) and y (vertical) direction respectively.

The initial value reported by Resolution may be reported in either form (character vector or 2-element numeric vector) according to the current printer settings.


Resolutions Property

Applies to: Printer

The Resolutions property is a read-only property that reports the available printer resolutions.

Resolutions is a vector of 2-element integer vectors each of which specifies the number of dots per inch in the x (horizontal) and y (vertical) directions respectively.


Rotate Property

Applies to: Font

Description

This property specifies the angle of rotation of the font measured in radians (0 → ○2) from the x-axis in a counter-clockwise direction. Note that only TrueType fonts can be rotated. Rotated fonts are supported only for use with the Text object.


Rows Property

Applies to: Combo, ComboEx

Description

For Combo objects with Style 'Drop' or 'DropEdit' this property determines the number of rows displayed in the drop-down listbox when it is displayed. Note that the height of the edit field of a Combo of this type is dependent only upon the size of the font in use, and cannot otherwise be changed.

Rows is a "read-only" property for a Combo with Style 'Simple' and an attempt to set it in a Combo of this type with ⎕WC or ⎕WS will generate a NONCE ERROR. Instead, the overall height of a Simple Combo is determined by the first element of the Size property.


RowLineTypes Property

Applies to: Grid

This property specifies the appearance of the horizontal grid lines in a Grid object.

RowLineTypes is an integer vector, whose length is normally equal to the number of rows in the Grid. Each element in RowLineTypes specifies an index into the GridLineFCol and GridLineWidth properties, thus selecting the colour and width of the horizontal grid lines.

For example, if RowLineTypes[1] is 3, the first horizontal grid line in the Grid is displayed using the colour specified by the 3rd element of GridLineFCol, and the width specified by the 3rd element of GridLineWidth.

Note that RowLineTypes is not ⎕IO dependant, and the value 0 is treated the same as the value 1; both selecting the first colour and line width specified by GridLineFCol and GridLineWidth respectively

The default value of RowLineTypes is an empty numeric vector (<—>). If so, all horizontal grid lines are drawn using the first element of GridLineFCol and GridLineWidth.

A horizontal grid line is drawn along the bottom edge of its associated row. One pixel is drawn inside the row of cells; additional pixels (if any) are drawn between that row of cells and the next one below.


RowTitles Property

Applies to: Grid

Description

This property specifies the headings that are displayed to the left of the rows in a Grid object. If specified, it must be a vector of character vectors or matrices whose length is the same as the number of rows implied by the Values property. The default value of RowTitles is an empty character vector. In this case, the system displays the row numbers.

To disable the display of row titles in a Grid, you should set the TitleWidth property to 0.


RowTitleAlign Property

Applies to: Grid

The RowTitleAlign property specifies the alignment of row titles in a Grid. It is either a simple character vector, or a vector of character vectors with one element per row.

An element of RowTitleAlign may be:'Top','Bottom', 'Left', 'Right', 'Centre', 'TopLeft', 'TopRight', 'BottomLeft', or 'BottomRight'.

Note that both spellings 'Centre' and 'Center' are accepted.


RowTitleBCol Property

Applies to: Grid

The RowTitleBCol property specifies the background colour of the row titles in a Grid object

RowTitleBCol may be a scalar that specifies a single background colour to be used for all of the row titles, or a vector that specifies the background colour of each of the row titles individually. An element of RowTitleBCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see Bcol for details). Its default value is 0 which obtains the colour defined for Button Face.


RowlTitleDepth Property

RowTitleDepth Property

Applies to: Grid

RolTitleDepth specifies the structure of a set of hierarchical row titles. It is an integer vector with the same length as the RowTitles property. A value of 0 indicates that the corresponding element of RowTitles is a top-level title. A value of 1 indicates that the corresponding title is a sub-title of the most recent title whose RowTitleDepth is 0; a value of 2 indicates that the corresponding title is a sub-title of the most recent title whose RowTitleDepth is 1, and so forth. For example:

      'F'⎕WC'Form'('Coord' 'Pixel')('Size' 318 310)
      'F'⎕WS'Caption' 'Hierarchical Column Titles'
      'F.G'⎕WC'Grid'(?12 4⍴100)(0 0)(318 310)
      'F.G'⎕WS('TitleWidth' 150)('TitleHeight' 0)
      'F.G'⎕WS'CellWidths' 40

      Q1←'Q1' 'Jan' 'Feb' 'Mar'
      Q2←'Q2' 'Apr' 'May' 'Jun'
      Q3←'Q3' 'Jul' 'Aug' 'Sep'
      Q4←'Q4' 'Oct' 'Nov' 'Dec'
      RT←(⊂'1995'),Q1,Q2,Q3,Q4
      RD←0,16⍴1 2 2 2

      'F.G'⎕WS('RowTitles'RT)('RowTitleDepth'RD)

      'F.G'⎕WS'RowTitleAlign' 'Centre'

Note that the LockRows method is not supported in combination with hierarchical row titles.


RowTitleFCol Property

Applies to: Grid

Description

The RowTitleFCol property specifies the colour of the row titles in a Grid object

RowTitleFCol may be a scalar that specifies a single colour to be used for all of the row titles, or a vector that specifies the colour of each of the row titles individually. An element of RowTitleFCol may be an enclosed 3-element vector of integer values in the range 0-255 which refer to the red, green and blue components of the colour respectively, or it may be a scalar that defines a standard Windows colour element (see BCol for details). . Its default value is 0 which obtains the colour defined for Button text.


RowTreeDepth Property

Applies to: Grid

The RowTreeDepth property specifies the structure of the rows in a Grid object. It is either a scalar 0 or an integer vector of the same length as the number of rows in the Grid. RowTreeDepth is similar to the Depth property of the TreeView object.

A value of 0 indicates that the corresponding row is a top-level row. A value of 1 indicates that the corresponding row is a child of the most recent row whose RowTreeDepth is 0; a value of 2 indicates that the corresponding row is a child of the most recent row whose RowTreeDepth is 1, and so forth.

When you set RowTreeDepth, the Grid is redrawn so that only rows with a RowTreeDepth of 0 are visible.

The RowSetVisibleDepth method can be used to make data visible to a specific depth.

For example:

      'F'⎕WC'Form' 'Grid: TreeView Feature'
      'F.G'⎕WC'Grid'(30 2⍴2/⍳30)
      F.G.RowTreeDepth←30⍴0 1 2 2

The user can interact with the tree images to expand and contract rows of the Grid.


RowTreeImages Property

Applies to: Grid

The RowTreeImages property is a simple character vector or ref, or a vector of character vectors or refs, that specifies the names(s) of, or ref(s) to, Bitmap objects that are used to display the tree nodes for a Grid object.

Note that images in tree nodes are only displayed if RowTreeStyle is set to 'ImagesOnly', 'ImagesAndLines', or 'AllImagesAndLines'∇.

If RowTreeImages is not specified default images are used.

The Bitmap specified by the 1st element of RowTreeImages is used to display unopened nodes.

The Bitmap specified by the 2nd element of RowTreeImages is used to display opened nodes.

The Bitmap specified by the 3rd element of RowTreeImages is used to display nodes without children.

For example:

      'Closed'⎕WC'Bitmap' 'Folder.bmp'
      'Open'⎕WC'Bitmap' 'FolderOpen.bmp'
      'Item'⎕WC'Bitmap' 'Ideas'
      F.G.RowTreeStyle←'AllImagesAndLines'
      F.G.RowTreeImages←'Closed' 'Open' 'Item'


RowTreeStyle Property

Applies to: Grid

RowTreeStyle specifies the visible attributes of the tree displayed in the Row titles of a Grid.

The value of the RowTreeStyle property is a character vector chosen from the following :

'LinesOnly' | Only the lines of the tree structure are drawn.
'ImagesOnly' | Only the images of nodes with children are drawn.
'ImagesAndLines' | Both lines and images for nodes with children are drawn.
'AllImagesOnly' | Images for all nodes are drawn.
'AllImagesAndLines' | Both lines and images for all nodes are drawn.

The default value, 'ImagesAndLines', is illustrated in the first picture below. Other values are displayed in subsequent pictures.

      F.G.RowTreeStyle←'LinesOnly'

      f.g.RowTreeStyle←'ImagesOnly'

      f.g.RowTreeStyle←'AllImagesOnly'

      f.g.RowTreeStyle←'AllImagesAndLines'


RTFText Property

Applies to: Clipboard, RichEdit

The RTFText property is used to set or retrieve the contents of a Clipboard or a RichEdit object in rich text format (RTF). It is always a character vector.


RunMode Property

Applies to: OLEServer

This property specifies the way in which an OLEServer object serves multiple clients.

RunMode is a character vector and may be 'MultiUse' (the default), 'SingleUse' or 'RunningObject'.

If RunMode is 'MultiUse', OLE will load a single copy of Dyalog APL and the appropriate workspace into memory. All OLE client processes will communicate with the same Dyalog APL session.

Note that in this case, each OLE client is actually connected to a separate instance of the corresponding APL namespace. That is to say, each client will appear to have its own private copy of the namespace. However, the individual functions and variables in the namespace are not physically copied until they are changed. This means that, in general, OLE clients will share APL functions but have private copies of the namespace variables. However, please remember that global objects in the workspace or in other namespaces are not instanced and will effectively be shared by all clients although they are not directly accessible to them.

If RunMode is 'SingleUse', OLE will load a separate copy of Dyalog APL and a separate copy of the appropriate workspace into memory for each OLE client. Each OLE client operates directly on the namespace associated with the object and not an instance of it.

If RunMode is 'RunningObject', OLE will load a single copy of Dyalog APL and the appropriate workspace into memory. All OLE client processes will communicate with the same Dyalog APL session and indeed with the same namespace. The namespace is not instanced and all objects, including exported variables, are shared by all clients.


ScrollOpposite Property

Applies to: TabControl

The ScrollOpposite property specifies that unneeded tabs scroll to the opposite side of a TabControl, when a tab is selected.

ScrollOpposite is a single number with the value 0 (normal scrolling) or 1 (scrolling to the opposite side); the default is 0.

The picture below illustrates a TabControl with ScrollOpposite set to 1, after the user has clicked Third Tab.

Setting ScrollOpposite to 1 implies that MultiLine is also 1. If you set ScrollOpposite to 1 in a ⎕WC statement, the MultiLine property will automatically be set to 1, even if you try to set MultiLine to 0 in the same statement. If you subsequently change MultiLine back to 0 using ⎕WS , this will work, but the effect is not useful and it is not supported.


SelDate Property

Applies to: Calendar

The SelDate property identifies the range of dates that is currently selected in a Calendar object.

SelDate is a 2-element integer vector of IDN values that identifies the first and last dates that are currently selected.


SelImageIndex Property

Applies to: ComboEx, TreeView

The SelImageIndex property determines which bitmapped images in an ImageList correspond to items in a TreeView object when the item is selected. It is an integer vector whose length is the same as the number of items in the object and is ⎕IO dependent.

See also ImageIndex


SelItems Property

Applies to: Combo, ComboEx, Grid, List, ListView, TreeView

Description

This property determines which (if any) of the items in an object are currently selected and highlighted. Except in a Grid, it is a Boolean vector with one element per item in the list. A value of 1 means "selected"; 0 means "not selected".

This property is used after a Select event to identify which item has been chosen. In a Combo or a List with Style 'Single' it will contain only a single 1.

SelItems should also be used to pre-set the contents of the edit field in a Combo box with Style 'Drop'. In Combo boxes with Style 'Simple' or 'DropEdit', the contents of the edit field may also be specified by the Text property. If you specify both, the value of Text takes precedence.

In a Grid SelItems is a 2-element vector of 2-element integer vectors that identifies the row and column coordinates of the first and last cells in the currently selected block of cells. If multiple selection is enabled, SelItems may be a vector of such arrays, specifying the coordinates of a number of non-contiguous blocks of selected cells.


SelRange Property

Applies to: TrackBar

The SelRange property specifies the selected range in a TrackBar which has Style 'Selection'. It is a 2-element numeric vector.


SelText Property

Applies to: Combo, ComboEx, Edit, RichEdit

Description

This property determines or identifies the portion of text in an object that is currently selected and highlighted. It can be used to pre-select all or part of the text to be replaced or deleted when the user starts typing. It can also be used to query the area of text that the user has highlighted. This can be useful if you want to implement your own cut/paste/replace features.

SelText is always a 2-element integer vector. If the field contents (defined by the Text property) is a vector, SelText is simple. Its first element is the index of the first selected character and its second element is 1 + the index of the last selected character. The length of the selected string is therefore obtained by subtracting the first element from the second.

If there are no characters selected, the two elements are equal and specify the current position of the input cursor.

If the contents is a vector of vectors or a matrix, each element of SelText is a 2-element vector. The first item in each of the elements indexes the vector (in a vector of vectors) or row (in a matrix). The second item in each element indexes the position of the character in the vector or along the row. Again, the value reported for the last character in the selected string is 1 + its index.


ServerVersion Property

Applies to: OLEServer

This property specifies the version number of an OLEServer object.

It is a 2-element integer vector that specifies the major and minor version numbers respectively.

The default value of ServerVersion is (1 0).


ShowCaptions Property

Applies to: ToolControl

The ShowCaptions property specifies whether or not the captions of individual ToolButton objects are drawn. ShowCaptions is a property of the parent ToolControl object.

ShowCaptions is a single number with the value 0 (ToolButton captions are not shown) or 1 (ToolButton captions are shown); the default is 1

ShowCaptions allows you to toggle end-user preferences for the display of ToolButton captions, without having to set/clear individual captions one by one.


ShowDropDown Property

Applies to: ColorButton, ToolControl

The ShowDropDown property specifies whether or not a drop-down menu symbol is drawn in a ColorButton or alongside ToolButton objects which have Style 'DropDown'.

ShowDropDown is a single number with the value 0 (drop-downs captions are not shown) or 1 (drop-downs are shown); the default is 1.

ShowDropDown also affects the behaviour of ToolButton objects which have Style 'DropDown'.

If the ShowDropDown property of the parent ToolControl is 0, clicking the ToolButton causes the popup menu to appear. In this case, the ToolButton itself does not itself generate a Select event; you must rely on the user selecting a MenuItem to specify a particular action.

If the ShowDropDown property of the parent ToolControl is 1, clicking the dropdown button causes the popup menu to appear; clicking the ToolButton itself generates a Select event, but does not display the popup menu.

The following picture illustrates a ToolControl with ShowDropDown set to 1.


ShowInput Property

Applies to: Grid

Description

This property specifies whether or not the cells in a Grid are displayed using their associated input objects.

The ShowInput property is either a single boolean value that applies to all the cells in a Grid, or it is a vector whose elements are mapped to individual cells via the CellTypes property. A value of 0 means that the corresponding cell is displayed normally. A value of 1 indicates that the cell is displayed using its associated input object, as it is when it is the current cell. ShowInput is relevant to cells displayed using Combo and Button objects.

The example below illustrates the appearance of a Grid in which ShowInput is set to 0 for the Job Title column and 1 for the Region and Permanent columns.

The appearance of the same Grid but with ShowInput set to 0 throughout is illustrated below:


ShowSession Property

Applies to: OLEServer

This property specifies whether or not the APL Session window is displayed when an OLEServer object is started by an OLE client.

Its default value is 0 (hide Session).

Note that if RunMode is 'MultiUse', you may not in any way access the instances of the object that are being controlled by the client applications, even if only a single client is connected.


ShowThumb Property

Applies to: TrackBar

The ShowThumb property specifies whether or not the thumb in a TrackBar object is visible. It is boolean with a default value of 1 and it may be toggled on and off using ⎕WS.


SingleClickExpand Property

Applies to: TreeView

The SingleClickExpand property specifies whether or not an item in a TreeView control is expanded when the user selects the item.

SingleClickExpand is a single number with the value 0 (the user must select the expand icon to cause the item to expand) or 1 (the item is expanded when the text of the item is selected); the default is 0.


SIPMode Property

Applies to: Form

SIPMode applies only to PocketAPL. In versions of Dyalog APL for other platforms, it has no effect.

This is a Boolean property that specifies the behaviour of the Input Panel with respect to the Pocket APL GUI.

If SIPMode is 1, the Input Panel is automatically displayed when a GUI control that may receive character input (e.g. an Edit object) receives the input focus. The Input Panel is automatically hidden when the input focus moves to a control that does not receive character input.

If SIPMode is 0 (the default), the display of the Input Panel is not handled automatically, but may be controlled using the ShowSIP method.

Note that the user may display and hide the Input Panel manually, regardless of the value of SIPMode.


SIPResize Property

Applies to: Form

SIPResize applies only to PocketAPL. In versions of Dyalog APL for other platforms, it has no effect.

This is a Boolean property that specifies the behaviour of a Form when the Input Panel is raised or lowered.

If SIPResize is 1 (the default), the Form generates a Configure event when the Input Panel is raised or lowered. Unless disabled or modified by a callback function, the Form is automatically resized to occupy the entire space above the Input Panel.

If SIPResize is 0, the Form does not generate a Configure event when the Input Panel is raised or lowered. This means that, at times, the lower part of the Form may be obscured by the Input Panel.


Size Property

Applies to: ActiveXControl, Animation, Bitmap, Button, Calendar, ColorButton, Combo, ComboEx, CoolBand, CoolBar, DateTimePicker, Edit, Ellipse, Font, Form, Grid, Group, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Metafile, NetControl, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, TabButton, TabControl, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This is a 2-element numeric vector specifying the height and width of the object.

For the Bitmap object, Size is set and reported in pixels. Setting the Size of a Bitmap causes it to be scaled (up or down).

For all other objects, Size is reported and set in units defined by the Coord property and, if Coord is 'User', the XRange and YRange properties of the object's parent.

For the Root object, if Coord is 'Prop' the value of Size is (100,100). If Coord is 'Pixel' the value of Size reports the number of pixels on the screen.

For a Form or SubForm, the Size property defines the area within the object, and excludes its title bar, menu bar and border if these are present.

For a Combo object with a "drop-down" list, the first element of Size (height) is ignored. The height of the edit field is determined by the height of the font, while the size of the list box is determined by the Rows property.

When specifying Size, you can set the height or width to a default value (⎕WC) or leave it unchanged (⎕WS) by giving the corresponding element a value of <—>.


Sizeable Property

Applies to: Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, Locator, ProgressBar, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, ToolBar, TrackBar, TreeView, UpDown

Description

This property determines whether or not an object can be directly resized by the user once it has been created by ⎕WC.

It is a single number with the value 0 (the object cannot be resized by the user) or 1 (the object may be resized by the user). The default is 1.

For a Form or SubForm, the Sizeable property may only be set by ⎕WC and cannot subsequently be altered using ⎕WS. An attempt to do so generates a NONCE ERROR. For a Form, the default value is 1 and the Form occupies a standard resizeable window with a border. Note that the value of Sizeable is independent of the values of the MaxButton and MinButton properties, so that a Form with MaxButton 1 can be maximised even though its Sizeable property is 0.

For other objects, the default value of the Sizeable property is 0. However, setting it to 1 (which may be done dynamically using ⎕WS) allows the user to resize it with the mouse.

In all these cases, when the user resizes an object, the object will generate a Configure (31) event.

Sizeable also applies to the Locator object. In this case, a value of 1 implies "rubberbanding" and a value of 0 means "no rubberbanding". See Locator object for further details.


SocketNumber Property

Applies to: TCPSocket

The SocketNumber property is an integer whose value is the Window handle of the socket attached to the TCPSocket object and is generally a read-only property.

The only time that SocketNumber may be specified is when a server replicates (clones) a listening socket to which a client has just connected.


SocketType Property

Applies to: TCPSocket

The SocketType property is a character vector that specifies the type of the TCP/IP socket. This is either Stream (which is the default), or UDP.

SocketType must be defined when the object is created and may not be set or changed using ⎕WS.

For two Dyalog APL applications to communicate, their TCPSocket objects must have the same SocketType.


SortItems Property

Applies to: List

The SortItems property specifies whether or not the items in a List object are sorted.

It is Boolean with a default value of 0. If SortItems is 1, the items are automatically sorted in alphabetical order and the object provides word recognition capabilities for selecting an item from the keyboard.

Note that the value of the Items property reflects the order of the items displayed in the List object rather than the order in the array that was used to assign it.

This property may only be initialised when the object is created and cannot subsequently be changed.


SplitObj1 Property

Applies to: Splitter

The SplitObj1 property specifies the name of, or ref to, one ot up to two objects managed by a Splitter object. The object must be one of the following types:

Button | Calendar | Combo | Edit | Grid | Group
Label | List | ListView | MDIClient | ProgressBar | RichEdit
Scroll | Spinner | Static | StatusBar | SubForm | TabBar
TabControl | ToolBar | TrackBar | TreeView | UpDown |

If the Style property of the Splitter is 'Vert', the object specified by SplitObj1 is positioned at (0 0) and sized to occupy the space in its parent to the left of the Splitter, with the Splitter itself attached to its right edge.

If the Style property of the Splitter is 'Horz', the object specified by SplitObj1 is positioned at (0 0) and sized to occupy the space in its parent above the Splitter, with the Splitter itself attached to its bottom edge.

If SplitObj1 is empty, the Splitter manages the single object specified by SplitObj2 and the space to the left or above the Splitter is empty or controlled by another Splitter.


SplitObj2 Property

Applies to: Splitter

The SplitObj2 property specifies the name of, or ref to, one of up to two objects managed by a Splitter object. The object must be one of the following types:

Button | Calendar | Combo | Edit | Grid | Group
Label | List | ListView | MDIClient | ProgressBar | RichEdit
Scroll | Spinner | Static | StatusBar | SubForm | TabBar
TabControl | ToolBar | TrackBar | TreeView | UpDown |

If the Style property of the Splitter is 'Vert', the object specified by SplitObj2 is initially positioned at (0 x), where x is half the width of the parent plus the Size of the Splitter, and sized to occupy the space in its parent to the right of the Splitter, with the Splitter itself attached to its left edge.

If the Style property of the Splitter is 'Horz', the object specified by SplitObj2 is initially positioned at (y 0), where y is half the height of the parent plus the Size of the Splitter, and sized to occupy the space in its parent below the Splitter, with the Splitter itself attached to its top edge.

If SplitObj2 is empty, the Splitter manages the single object specified by SplitObj1 and the space to the right or below the Splitter is empty or controlled by a second Splitter.


Start Property

Applies to: Circle, Ellipse

Description

This property specifies one or more start-angles for an arc, pie-slice, or chord of a circle or ellipse. It may be used in conjunction with End which specifies end angles. Angles are measured counter-clockwise from the x-axis at the centre of the object.

If a single arc is being drawn, Start is a single number that specifies the start angle of the arc in radians (0 ⍎> ○2). If multiple arcs are being drawn, Start is either a single number as before (the start angle for several concentric arcs) or a numeric vector with one element per arc.

If End is not specified, the default value of Start is 0. Otherwise, the default value of Start is (0,¯1↓+\End).


StartIn Property

Applies to: BrowseBox

The StartIn property is a character string that specifies the start point and root for a BrowseBox object.

Only the specified folder and its subfolders appear in the dialog box. The user cannot browse higher in the folder architecture than this folder.

The default value for StartIn is an empty vector which means that the root of the browse dialog is the desktop.


State Property

Applies to: Button, Form, SubForm, TabButton, ToolButton

Description

This property determines the state of a Button, TabButton, ToolButton, Form, or SubForm. It is a single number with the value 0 (the default), 1, or 2 (Form and SubForm).

If the Style property is 'Push', a State of 0 means that the pushbutton is displayed normally (out). If its State is 1, the pushbutton is displayed depressed (in).

If the Style property is 'Radio' or 'Check', 0 means "not selected" and 1 means "selected". Note that only one of a group of buttons with Style 'Radio' that share the same parent may have State 1. Setting State to 1 automatically deselects all the others in the group.

For a Form or SubForm, a value of State of 0 means that the Form is currently displayed in its "normal" state. 1 means that the Form is currently minimised (displayed as an icon). The value 2 indicates that the Form is maximised and displayed full-screen. The State of a Form can be changed using ⎕WS.


Step Property

Applies to: Form, Locator, ProgressBar, Scroll, Spinner, SubForm, TrackBar, UpDown

Description

This property determines the size of changes reported when the user clicks a scroll arrow (small change) or clicks on the body of the scrollbar (large change). The object's Thumb property increases or decreases by this amount.

For a Scroll object, Step is a 2-element numeric vector whose first element specifies the value of the "small change" and whose second element specifies the value of the "large change".

For a Form or SubForm, Step is a 4-element numeric vector. The first two elements refer to the Form's vertical scrollbar and the second two elements refer to the Form's horizontal scrollbar.

For the above objects, values of Step must be between 1 and the value of the Range property.

For a Locator object, Step is a 2-element integer vector (default value 1 1) that specifies the increments (in pixels) by which the size or position of the Locator changes in the Y and X directions respectively as the user moves the Locator.


Style Property

Applies to: Button, Calendar, Combo, ComboEx, DateTimePicker, Edit, FileBox, Icon, List, ListView, Locator, Marker, MenuItem, MsgBox, ProgressBar, PropertySheet, Separator, Splitter, Static, StatusField, TabControl, TCPSocket, ToolButton, ToolControl, TrackBar

Description

This property determines a particular style of object within the general category of Type. It is a character vector whose value depends upon the type of object.

For a Button, Style may be 'Push', 'Radio' or 'Check'.

'Push' specifies that the button appears and behaves like a pushbutton (sometimes also called a command button).

'Radio' means that the button is displayed as a small circle accompanied by a description. When the button is selected, the circle is filled in. In a group of buttons with Style 'Radio' that share the same parent, only one of them may be selected. This style of button is generally known as a "radio-button" or an "option button".

'Check' means that the button is displayed as a small box accompanied by a description. When the button is selected a cross appears in the box. This style of button is known as a "check-box".

For a Calendar object, The Style property may be either 'Single' (the default) or 'Multi'. If Style is 'Single', the user may select a single date. If Style is 'Multi', the user may select a contiguous range of dates.

For a Combo or ComboEx object, Style may be 'Simple' 'DropEdit' or 'Drop' (the default). 'Simple' specifies a simple combo box in which the associated list box is displayed at all times. The other two styles provide list boxes which "drop down" when the user clicks on a symbol displayed to the right of the Combo's edit field. A 'DropEdit' Style allows the user to type (anything) in the edit field. A 'Drop' Style does not and forces the contents of the edit field to be either empty or one of the choices specified by Items.

For a DateTimePicker, Style may be either 'Combo' (the default) or 'UpDown'.

For an Edit object, Style may be 'Single' or 'Multi'. If Style is 'Single' the object displays only a single line of text and the user may not enter any more lines. If the Style is 'Multi' the number of lines displayed is governed by the Rows or Size property and the user may insert, add or delete lines as desired.

For FileBox, List, and ListView objects, Style may be 'Single' or 'Multi'. If the Style is 'Single' only one file or item can be selected. If Style is 'Multi', several files or items can be selected.

For an Icon, Style may be 'Large' (the default) or 'Small' and specifies the size of the icon (32x32 or 16x16) to be loaded from a file.

For a Locator, Style may be 'Point', 'Rect' (the default), 'Line' or 'Ellipse'. It specifies the shape that is drawn as the user moves the mouse.

For a MenuItem, Style may be 'Check' (the default) or 'Radio'. The latter specifies that within a contiguous block of such MenuItems, only one may have Checked set to 1. Setting Checked to 1 on any item in that group automatically sets Checked to 0 on the others. A radio style MenuItem that is checked has a small radio dot drawn to the left of its Caption.

For a MsgBox, the Style property determines the type of icon which is displayed in it. This is a character vector with one of the following values :

'Msg' | :no icon (the default)
'Info' | information message icon
'Query' | query (question) icon
'Warn' | warning icon
'Error' | critical error icon

For a Static object, Style defines its appearance, and may be one of :

'BlackFrame' | 'BlackBox'
'GreyFrame' | 'GreyBox'
'GrayFrame' | 'GrayBox'
'WhiteFrame' | 'WhiteBox'

A StatusField may be used to monitor the state of a key on the keyboard. If so, its Style property determines the key it monitors and may be one of the following:

'CapsLock' | Monitors state of Caps Lock key
'ScrollLock' | Monitors state of Scroll Lock key
'NumLock' | Monitors state of Num Lock key
'KeyMode' | Monitors the keyboard mode (APL/ASCII)
'InsRep' | Monitors the state of the Insert key

For a Splitter, the Style property specifies the orientation of the Splitter and may be 'Vert' (the default) or 'Horz' .

For a TabControl, the Style property determines the appearance of its TabButton children, and may be 'Tabs' (the default), 'Buttons' or 'FlatButtons'.

For aTCPSocket,Style is a character vector that specifies the type of data transmitted or received by the socket; it may be 'Char', 'Raw', or 'APL'. The value APL is valid only if the SocketType is 'Stream'.

For a ToolButton, the Style property specifies the behaviour of the button and may be 'Push' (the default), 'Check', 'Radio', 'DropDown', or 'Separator'.

For a ToolControl, the Style property determines the appearance of its ToolButton children and may be 'Buttons', 'FlatButtons' (the default), 'List' or 'FlatList'.

For a TrackBar, the Style property determines the appearance and behaviour of the TrackBar and may be 'Standard' (the default) or 'Selection'.


SysMenu Property

Applies to: Form, SubForm

Description

This property determines whether or not a Form or SubForm has a "System Menu " box in the top-left corner of its border. Pressing the left mouse button in this box brings up the standard window control menu for the Form. Double clicking the box closes the Form.

SysMenu is a single number with the value 0 (no System menu box) or 1 (System Menu box is provided). The default is 1.

If any of the SysMenu, MaxButton, MinButton and Moveable properties are set to 1, the Form or SubForm has a title bar.


TabFocus Property

Applies to: TabControl

The TabFocus property specifies the focus behaviour for the TabControl object and may

TabFocus is a character vector that may be 'Normal' (the default), 'Never' or 'ButtonDown'.

If TabFocus is 'Normal', the tabs or buttons in a TabControl do not immediately receive the input focus when clicked, but only when clicked a second time. This means that, normally, when the user circulates through the tabs, the input focus will be given to the appropriate control in the associated SubForm. However, if the user clicks twice in succession on the same tab or button, the TabControl itself will receive the input focus.

If TabFocus is 'ButtonDown', the tabs or buttons in a TabControl receive the input focus when clicked.

If TabFocus is 'Never', the tabs or buttons in a TabControl never receive the input focus. This allows the user to circulate through a set of tabbed SubForms without ever losing the input focus to the TabControl itself.


TabIndex Property

Applies to: ActiveXControl, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, TrackBar, TreeView, UpDown

The TabIndex property reports the ⎕IO-dependant relative position of a child object within the list of child objects owned by its parent. If N is the number of children owned by an object, TabIndex is an integer between ⎕IO and (N-~⎕IO). The sequence of objects in this list is also used as the tabbing sequence, i.e. if the input focus is on the first child in the list, pressing Tab moves the input focus to the next child in the list.

When you create a child object, it is inserted in the list at the position specified by its TabIndex property. If TabIndex is omitted, it is appended to the end of the list.

If you subsequently change TabIndex, the object is moved to the corresponding position in the list.

Naturally, if you specify a value of TabIndex that is greater than the number of existing children, the object is inserted at or moved to the end of the list.


TabJustify Property

Applies to: TabControl

The TabJustify property specifies, the positions at which the picture and caption are drawn within each tab or button implemented by a TabButton in a TabControl object.

TabJustify is a character vector that may be 'Centre', 'Edge', or 'IconEdge'. Its default value is 'Centre'.

If TabJustify is 'Centre', the picture and caption are arranged in the centre of the TabButton.

If TabJustify is 'Edge', the picture and caption are together aligned to the appropriate edge of the TabButton according to the value of Align.

If TabJustify is set to 'IconEdge', the caption is drawn centrally and only picture is aligned to the edge.

TabJustify is only honoured if fixed size tabs are in effect.


TabObj Property

Applies to: SubForm, TabBar, TabBtn, TabButton, TabControl

Description

TabObj is a character vector.

For a SubForm, it specifies the name of , or ref to,a TabBtn or TabButton object that is associated with the SubForm. Selecting the TabBtn or TabButton causes the SubForm to be given the input focus.

For TabBtn and TabButton objects, TabObj is a read-only property that contains the name of, or ref to, the associated SubForm.

For a TabBar or TabControl, TabObj is a read-only property that contains the name of, or ref to, the currently selected TabBtn or TabButton.


TabSize Property

Applies to: TabControl

The TabSize property specifies the size of fixed size tabs or buttons in a TabControl object.

By default, the size of the tabs may vary from one to another. Fixed size tabs may be obtained by setting the TabSize property.

TabSize is a 2-element numeric vector that specifies the height and width of the tab. Either or both elements of TabSize may be set to <—> which means “default”.

To obtain fixed sized tabs with MultiLine set to 1, you must however also set the Justify property to 'None'.

If MultiLine is 1 and Justify is 'Right', TabSize is ignored.


Target Property

Applies to: BrowseBox

The Target property is a read-only character string that specifies the chosen folder or other resource selected by the user in a BrowseBox object.

If the BrowseFor is 'Directory', Target will contain a directory name followed by the character "\". Otherwise, Target just contains the name.


TargetState Property

Applies to: TCPSocket

The TargetState property reflects the intended final state of a TCPSocket object. Its possible values are as follows:

Stream | UDP
Client | Open
Server | Bound
Closed | Closed

Setting TargetState to Closed is the recommended way to close a socket. It informs APL that you want the socket to be closed, but only when it is safe to do so. When all the data has been sent, the TCPSocket will generate a TCPClose event which, unless a callback function decides otherwise, will cause the TCPSocket object to disappear.

To control socket closure, you may execute the following steps:

1. Set TargetState to Closed

2. either:

a) continue processing

or

b) wait (using ⎕DQ) for the TCPSocket to disappear

or

c) wait (using ⎕DQ) for the TCPClose event


Text Property

Applies to: Clipboard, Combo, ComboEx, Edit, MsgBox, RichEdit, Spinner, StatusField, Text

Description

This property is associated with the text contents of an object and is a character array.

In a Combo, StatusField, Spinner, or a single-line Edit object, Text may be a simple scalar or a simple vector.

In a RichEdit , a multi-line Edit field or in a MsgBox, the value of Text may also be a simple matrix, or a vector of vectors. If so, "new-line" characters are appended to each row of the matrix, or to each vector in a vector of vectors, before being displayed. The user may insert or add a "new-line" character in a multi-line Edit by pressing Ctrl-Enter (Enter itself is used to press Buttons).

Note that if word-wrapping is in effect in a multi-line Edit object, the structure of Text does not correspond to the lines displayed.

In a Text object, the value of the Text property may be a simple scalar, an enclosed vector or matrix, a simple vector, a simple matrix, or a vector of enclosed vectors or matrices.

In general, the value of Text returned by ⎕WG has the same structure that was assigned to it by ⎕WC or by the most recent call to ⎕WS. New-Line characters are removed.

You can copy text into the Windows Clipboard by using ⎕WS to set Text for a Clipboard object. In this case you may specify a simple character scalar, vector or matrix, or a vector of character vectors. If you are retrieving data from the clipboard that has been stored by another application, Text will be either a character vector or a vector of character vectors.

The Text property of a StatusField is updated automatically if its Style property is set to monitor the status of a key.


TextSize Property

Applies to: ActiveXControl, Bitmap, Edit, Form, Grid, Printer, Root, Static, StatusBar, SubForm, TabBar, ToolBar

Description

This property has been replaced by the GetTextSize method, which should be used instead. TextSize is retained only for compatibility with previous versions of Dyalog APL.

TextSize is a "read-only" property that reports the size of the bounding rectangle of a text item in a given font. The result is given in the co-ordinate system of the object in question. This property is useful for positioning Text objects.

When you query TextSize you give the text item in whose size you are interested and, optionally, the name of a Font object. The text item may be a simple scalar, a vector or a matrix. If the Font is omitted, the result is given using the current font for the object in question. When you query TextSize on its own, you must enclose the argument to ⎕WG. This is because APL would otherwise not be able to distinguish between the text string and font name associated with 'TextSize' and other properties with the same name as these items.

Examples:

      '.' ⎕WG ⊂'TextSize' 'Hello World'
2.666666746 9.625

      'FNT1' ⎕WC 'FontObj' 'Arial' 72
      '.' ⎕WG ⊂'TextSize' 'Hello World' 'FNT1'
12 41.875

      '.' ⎕WS 'Coord' 'Pixel'
      '.' ⎕WG ('TextSize' (3 11⍴'Hello World')) 'Coord'
39 55  Pixel


Thumb Property

Applies to: Form, ProgressBar, Scroll, Spinner, SubForm, TrackBar, UpDown

Description

This property determines and reports the position of the thumb in an object.

For a Scroll object, the value of Thumb is a single integer whose minimum value is 1 and whose maximum value is defined by the Range property.

For ProgressBar, Spinner,UpDown and TrackBar objects, Thumb is a single numeric value in the range specified by the Limits property.

For a Form or SubForm object, Thumb is a 2-element vector whose elements refer to the position of the thumb in the object’s own built-in vertical and horizontal scrollbars respectively.

For other objects, Thumb is a single numeric value in the range defined by the Limits property.


ThumbRect Property

Applies to: TrackBar

ThumbRect is a read-only property that reports the position and size of the bounding rectangle of the thumb in a TrackBar object. It is a 4-element integer vector containing:

[1] | Vertical position of the top-left corner of the bounding rectangle
[2] | Horizontal position of the top-left corner of the bounding rectangle
[3] | Height of the bounding rectangle
[4] | Width of the bounding rectangle


TickAlign Property

Applies to: TrackBar

TickAlign determines the position of the tick marks in a TrackBar object. For a horizontal TrackBar, TickAlign may be either 'Bottom' (the default), 'Top' or 'Both'. If TickAlign is 'Bottom', the ticks are drawn below the slider. If TickAlign is 'Top', the ticks are drawn above it. If TickAlign is 'Both', the ticks are drawn above and below.

For a vertical TrackBar, TickAlign may be either 'Right' (the default), 'Left', or 'Both' and similarly specifies to which side of the slider bar the ticks are drawn. Note that TickAlign may only be set when the TrackBar is created with ⎕WC and may not subsequently be altered using ⎕WS.

Note that ticks are not drawn if the value of HasTicks is 0


TickSpacing Property

Applies to: TrackBar

The TickSpacing property specifies the spacing between each tick mark in a TrackBar object. It is an integer between 1 and the maximum value of the TrackBar which is defined by the 2nd element of the Limits property.

For example, if you set ('Limits' 10 50) and you specify ('TickSpacing' 10) you will obtain 5 ticks corresponding to the values 10, 20, 30, 40 and 50 along the slider bar.


Tip Property

Applies to: Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, MenuItem, ProgressBar, PropertyPage, PropertySheet, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, SysTrayItem, TabBar, TabButton, ToolBar, ToolButton, TrackBar, TreeView, UpDown

Description

The Tip property is a character vector or character matrix that specifies a “help” message which is to be displayed when the user positions the mouse pointer over the object. The Tip is displayed in a pop-up TipField object specified by the TipObj property.


TipObj Property

Applies to: Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, MenuItem, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, TrackBar, TreeView, UpDown

Description

The TipObj property is a character vector or ref that specifies the name of, or ref to, a TipField object in which the “help” message defined by the Tip property is to be displayed. This message is displayed when the user positions the mouse pointer over the object.

Note that if TipObj is empty, its value is inherited from its parent. Thus setting TipObj on a Form defines the default TipField (and thus the default appearance of all Tips) for all the controls in that Form. Setting TipObj on Root defines the default TipField for the entire application.


TitleHeight Property

Applies to: Grid

Description

This property is a single number that specifies the height of the column titles displayed in a Grid object. It is expressed in the units specified by the Coord property of the Grid.


TitleWidth Property

Applies to: Grid

Description

This property is a single number that specifies the width of the row titles displayed in a Grid object. It is expressed in the units specified by the Coord property of the Grid.


Today Property

Applies to: Calendar, DateTimePicker, NetClient, NetType

The Today property is an IDN that specifies today’s date in a Calendar or DateTimePicker object. Its default value is the current date that is set on your computer.

See also CircleToday and HasToday properties.


ToolboxBitmap Property

Applies to: ActiveXControl, OCXClass

For an ActiveXControl, the ToolboxBitmap property is a character vector or ref that specifies the name of, or ref to, a Bitmap object that may be used by a host application to represent the ActiveXControl when its complete visual appearance is not required. For example, if you add an ActiveX control to the Microsoft Visual Basic development environment, its bitmap is added to the toolbox. The Bitmap should therefore be of an appropriate size, usually 24 x 24 pixels.

For an OCXClass, The ToolboxBitmap is a read-only property that reports a bitmap image associated with an OLE Control. This is intended for use by a GUI design tool. Its value is a 2-element vector. The first element is an integer matrix of pixel colours corresponding to the Bits property of a Bitmap object. The second element is a 3-column integer matrix specifying the colour map and corresponds to the CMap property of a Bitmap object.

Thus you can construct a Bitmap object directly from this property with an expression such as:

      'BM'⎕WC'Bitmap' '','GAUGE' ⎕WG'ToolboxBitmap'

where GAUGE is the name of an OCXClass.


TrackRect Property

Applies to: TrackBar

TrackRect is a read-only property that reports the position and size of the bounding rectangle of the slider in a TrackBar object. It is a 4-element integer vector containing:

[1] | Vertical position of the top-left corner of the bounding rectangle
[2] | Horizontal position of the top-left corner of the bounding rectangle
[3] | Height of the bounding rectangle
[4] | Width of the bounding rectangle


Translate Property

Applies to: ActiveXControl, Animation, Bitmap, BrowseBox, Button, Clipboard, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, ImageList, Label, List, ListView, MDIClient, Menu, MenuBar, MenuItem, Metafile, OCXClass, Printer, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, Separator, Spinner, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, Text, TipField, ToolBar, TrackBar, TreeView, UpDown

Description

This property applies to the Classic Edition only. In the Unicode Edition, its value is ignored.

This property specifies whether or not character data is to be translated. Translate is a character vector whose values may be 'Inherit', 'Translate', 'ANSI' or 'None'.

A value of 'Translate' means that all character property values and event parameters are translated to and from ⎕AV using the current output translation table (WIN.DOT).

'None' means that character data is passed between APL and the object with no translation.

If you set the value of the Translate property to 'ANSI', APL does not attempt to resolve characters as they are typed by the user via the Input Translate Table. Using Translate 'ANSI' in combination with the appropriate value of CharSet and the corresponding National Language keyboard, will permit users to enter strings in non-western languages.

'Inherit' means that the object inherits its translation from its parent.

The default value for the Root and Printer objects is 'Translate', and for most other objects it is 'Inherit'.


Transparent Property

Applies to: Animation, ToolControl

The Transparent property specifies whether or not a ToolControl is transparent.

Transparent is a single number with the value 0 (the default) or 1.

If Transparent is 1, the visual effect is as if the ToolButtons (and other controls owned by the ToolControl) were drawn directly on the parent Form as illustrated below.


Type Property

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetControl, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Root, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This property determines the type of an object. Its value is a character vector containing a valid object type. The Type property is set by ⎕WC and reported by ⎕WG, but may not be altered using ⎕WS.


TypeLibFile Property

Applies to: ActiveXControl, OLEServer

The TypeLibFile property is a read-only property that reports the name of the file in which the Type Library associated with a COM object is stored.


TypeLibID Property

Applies to: ActiveXControl, OLEServer

The TypeLibID property is a read-only property that reports the value of the globally unique identifier (GUID) of the Type Library associated with a COM object.


TypeList Property

Applies to: OCXClass, OLEClient

Description

This property reports the names of all the special data types defined for a particular COM object. It is a vector of character vectors returned by ⎕WG. It may not be set using ⎕WC or ⎕WS. Further information about each data type may be obtained using GetTYpeInfo.

Note that TypeList reports all of the data type names recorded in the .OCX file associated with the COM object. If several COM objects are provided within a single .OCX file, the entire set of data types reported may not necessarily be applicable to the Control in question.


Underline Property

Applies to: Font

Description

This property specifies whether or not the characters in the font associated with a Font object are underlined or not. It is either 0 (normal) or 1 (underlined). There is no default; the value of this property reflects the underline characteristic of the font allocated by Windows.


UndocksToRoot Property

Applies to: CoolBand, Form, SubForm, ToolControl

Specifies the parent adopted by an object when its Type changes to a Form as a result of an undocking operation.

UndocksToRoot is a single number with the value 0 or 1.

If UndocksToRoot is 1, the object becomes a Form that is a child of Root and therefore becomes completely independent of the Form in which it was previously docked.

If UndocksToRoot is 0, the object becomes a Form that is a child of the Form in which it was previously docked and is therefore always displayed on top of it. This setting is appropriate for a dockable toolbar.

The default value of UndocksToRoot is 1 if the object was originally created as a child of Root; otherwise it is 0.


UpperCase Property

Applies to: Root

Description

This property specifies whether or not property names returned by ⎕WG and event names supplied by ⎕DQ and ⎕NQ are converted to uppercase or not. It is a boolean property where 1 means convert to upper case and 0 means not. The default is 0. For example :

      '.' ⎕WG 'Type'

Root

      '.' ⎕WS 'UpperCase' 1
      '.' ⎕WG 'Type'
ROOT

In Dyalog APL Version 6, property names were always reported in upper case. This was changed in Version 7. The UpperCase property is provided to enable applications developed prior to Dyalog APL/W Version 7 to function with minimal alteration.


ValidIfEmpty Property

Applies to: Edit, Spinner

Description

This property applies to an Edit object with Style Single and specifies whether or not an empty field is considered to be valid. It also applies to a Spinner. Its value is either 0 (an empty field is not valid) or 1 (an empty field is valid. If the FieldType is Numeric, LongNumeric, Currency, Date or Time, the default value for ValidIfEmpty is 0. Otherwise, its default value is 1.

If ValidIfEmpty is 0 and the user attempts to leave the Edit object by shifting the input focus to another control, or by selecting a Button or MenuItem, the Edit object will generate a BadValue event. The Text property will reflect the appearance of the field and be empty, but the Value property will not be changed.

If ValidIfEmpty is 1 and the FieldType is Numeric, LongNumeric, Currency, date or Time, the Value property will be set to <—> when the user clears the field and leaves it.


Value Property

Applies to: Edit, Label, Spinner

Description

This property specifies or reports the numeric value associated with an Edit or Label object whose FieldType property is set to Numeric, LongNumeric, Date, LongDate or Time.

If the FieldType is Numeric or LongNumeric, the Value property contains a scalar number. If the FieldType is Date or LongDate, the Value property is an integer representing the date as the number of days since 1st January 1900. If the FieldType is Time, the Value property is an integer that contains the number of seconds since midnight.


Values Property

Applies to: Grid

Description

This property specifies the data values for the cells in a Grid object. Values must be a matrix whose elements are either single numbers, character scalars, character vectors or character matrices. This property is updated as the user moves around the Grid changing data.


VariableHeight Property

Applies to: CoolBar

The VariableHeight property specifies whether or not a CoolBar displays bands at the minimum required height, or all the same height (that of the largest).

VariableHeight is a single number with the value 0 (same height) or 1 (variable height). The default is 1.


View Property

Applies to: ListView

The View property specifies how the items in a ListView object are displayed. It is a character vector which may have one of the following values; 'Icon' (the default), 'SmallIcon', 'List' or 'Report'.

When View is 'Icon' or 'SmallIcon', the items are arranged row-wise with large or small icons as appropriate. When View is set to 'List', the items are arranged column-wise using small icons. When View is set to 'Report', the items are displayed in a single column using small icons but with the matrix specified by ReportInfo displayed alongside. In this format, the ListView also provides column headings which are specified by the ColTitles property. The alignment of these titles (and of the data in the columns beneath them) is defined by the ColTitleAlign property. Examples of different views are illustrated below.


Visible Property

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, CoolBand, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Image, Label, List, ListView, Marker, MenuBar, Poly, ProgressBar, PropertySheet, Rect, RichEdit, Scroll, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, Text, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

This property specifies whether or not an object is currently visible. It is a single number with the value 0 (object is invisible) or 1 (object is visible). The default is 1. Setting Visible on and off is a way to pop a dialog box up and down as required.

Note that an invisible object is not necessarily inactive, and is capable of generating events. For example, a Button with a Cancel property of 1 will generate a Select (30) event (if enabled) whether or not it is visible. An invisible object will also respond to methods and events sent to it by ⎕NQ.


VAlign Property

Applies to: Text

Description

This property determines the vertical alignment of text in the Text object. It is either a single integer value, or, if the Text object has several components, a corresponding vector of such values. These may be :

0 | base aligned | the base line of the character is aligned on the y-coordinate specified by the Points property.
1 | half aligned | the centre of the character is aligned on the y-coordinate specified by the Points property.
2 | cap aligned | the top of the character is aligned on the y-coordinate specified by the Points property.
3 | bottom aligned | the bottom of the character cell is aligned on the y-coordinate specified by the Points property.
4 | top aligned | the top of the character cell is aligned on the y-coordinate specified by the Points property. This is the default.


VScroll Property

Applies to: Combo, ComboEx, Edit, Form, Grid, List, ListView, RichEdit, Scroll, StatusBar, SubForm, TabBar, ToolBar, TrackBar, UpDown

Description

This property determines whether or not an object has a vertical scrollbar. It is a single integer with the value ¯2, ¯1, or 0.

For a Form object, the value ¯1 specifies that the Form has a vertical scrollbar. A value of 0 (which is the default) means that it does not.

When applied to an Edit object, the value ¯2 specifies that the data is scrollable vertically, but only by using the cursor keys; a scrollbar is not provided. A value of ¯1 causes a scrollbar to be displayed (whether or not one is needed).

When applied to a List object, the value ¯2 specifies that the data is scrollable vertically, but only by using the cursor keys; a scrollbar is not provided. A value of ¯1 causes a scrollbar to be displayed if required (when the list of items exceeds the height of the object).

When applied to a Combo or ComboEx object, a value of ¯1 or ¯2 causes a scrollbar to be displayed, whether or not one is required..

For all these objects, a value of 0 inhibits scrolling altogether.

For a Scroll object, VScrollmay be ¯1 or 0. If it is ¯1 the direction of the scrollbar is vertical. If both HScroll and VScroll are set to ¯1, HScroll takes precedence and forces VScroll back to 0.

For a StatusBar, TabBar or ToolBar with Align set to Left or Right, VScroll determines whether or not a vertical scrollbar is provided and how the object positions its children. If VScroll is 0 (the default) the object organises its children in multiple columns and does not provide a scrollbar. If VScroll is ¯1 or ¯2, the object organises its children in a single column and provides a mini scrollbar to allow those positioned beyond the bottom edge of the object to be scrolled into view. If VScroll is ¯1, the scrollbar is always shown. If VScroll is ¯2, it is only shown when needed.

For a Grid, VScroll may be 0 (no vertical scrollbar), ¯1 (scrollbar is displayed when required), ¯2 (same as ¯1) or ¯3 (scrollbar is always displayed).


WanstReturn Property

WantsReturn Property

Applies to: Edit, RichEdit

This boolean property specifies the behaviour of the Enter key for a multi-line Edit (Style 'Multi') and a RichEdit object.

A value of 0 means that the Enter key is ignored by the Edit or RichEdit. Instead, the Enter key will (if appropriate) cause a Select event on a Button in the same Form. The user must press Ctrl+Enter to input a new line.

A value of 1 means that pressing the Enter key will introduce a new line into the object.

WantsReturn must be established when the object is created by ⎕WC and may not subsequently be altered using ⎕WS. Its default value is 0 in an Edit and 1 in a RichEdit.


WeekNumbers Property

Applies to: Calendar, DateTimePicker

The WeekNumbers property specifies whether or not a Calendar object displays week numbers.

WeekNumbers is a single number with the value 0 (week numbers are not shown) or 1 (week numbers are shown); the default is 0.


Weight Property

Applies to: Font

Description

This property specifies the degree of boldness of a font associated with a Font object. It is a number in the range 0 to 1000, where 0 represents very faint and 1000 represents very bold. There is no default; the value of this property reflects the degree of boldness of the font allocated by Windows.

In general, 400 means normal and 700 means bold.


WordFormat Property

Applies to: RichEdit

The WordFormat property is identical to the CharFormat property except that it is used to apply formatting to the selected word or words in a RichEdit object. If the selection is empty but the insertion point is inside a word, the formatting is applied to the word. See CharFormat for further details.


Wrap Property

Applies to: ListView, ProgressBar, Spinner, UpDown

The Wrap property is boolean and has a default value of 1.

For a ListView it specifies whether or not long labels (specified by the Items property) may be wrapped or not.

For a ProgressBar object it determines whether or not the object starts over again when it reaches its upper limit. In particular, if Wrap is 1, the value obtained when you set the Thumb property is given by the expression: LIMITS[1]+THUMB|LIMITS[2] where THUMB is the value to which you set the Thumb property and LIMITS is the value of the Limits property.

For a Spinner , Wrap determines what happens when the value in the Spinner reaches its upper or lower limit. If Wrap is 1 the Spinner will wrap around to its opposite limit. Otherwise it will stick.


XRange Property

Applies to: ActiveXControl, Bitmap, Form, Grid, Group, MDIClient, Metafile, Printer, Root, Static, StatusBar, SubForm, TabBar, ToolBar

Description

XRange and YRange together determine a user-defined co-ordinate system. These properties are effective on the object's children which have Coord set to 'User'.

XRange is a 2-element numeric vector containing the x-coordinate of the top left and bottom right interior corners of the object respectively. See Coord for further details.


Yield Property

Applies to: Root

Description

This property specifies the frequency with which APL yields to Windows and applies mainly to Version 7. Multi-tasking in Windows 3.x is implemented by task switching between applications whenever any application requests a message from the queue. An application that is purely performing computational or file-handling tasks will therefore prevent all other applications from running. Well-behaved Windows applications should yield control by requesting a message periodically even though no user interaction is currently taking place. However, this operation takes a perceptible length of time, even if no other applications are running.

By default, Dyalog APL/W yields control to Windows approximately every 1/5th of a second. This is implemented by checking the time at the beginning of each line of executable APL code and yielding if 1/5th of a second or more has elapsed since the last yield. This mechanism also allows APL to detect user interrupts (which are simply Windows messages) during the execution of code.

In most circumstances yielding every 1/5th of a second produces "good" Windows behaviour with little impact on APL throughput. However, in some cases it may be beneficial to use the Yield property to explicitly control the yield frequency. An example is in an application that takes an appreciable time to redraw an existing graphical picture. If APL yields before the entire picture has been redrawn, some objects will be erased before others are redrawn, causing a flickering effect.

The value of Yield is an integer expressed in 1/1000's of a second. Its default value is 200. Yield defines the period of time allowed to elapse between the execution of successive lines of APL code before APL yields to Windows by requesting a message from the Windows queue. If Yield is set to zero APL does not explicitly yield.

Note that the value of this property only controls the yield frequency when APL is executing user-defined code. APL may also yield implicitly during ⎕DQ, ⎕NQ, ⎕WC, ⎕SR, ⎕WS and ⎕WG and in communicating with Auxiliary processors. Note that setting Yield to 0 (or to a very high value) during the execution of code that does not implicitly yield will effectively de-activate all other applications (including Program manager) and disable APL interrupts (Ctrl+Break). It should therefore be used with extreme caution.


YRange Property

Applies to: ActiveXControl, Bitmap, Form, Grid, Group, MDIClient, Metafile, Printer, Root, Static, StatusBar, SubForm, TabBar, ToolBar

Description

XRange and YRange together determine a user-defined co-ordinate system. These properties are effective on the object's children which have Coord set to 'User'.

YRange is a 2-element numeric vector containing the y-coordinate of the top left and bottom right interior corners of the object respectively. See Coord for further details.


Events

Event | Num | Description
ActivateApp | 137 | User has switched to/from the APL application.
AddCol | 153 | appended a column to a Grid object.
AddRow | 152 | appended a row to a Grid object
AmbientChanged | 533 | reported when any of the ambient properties change in an application hosting an ActiveXControl object.
BadValue | 180 | attempted to leave Edit object with invalid text
BeginEditLabel | 300 | signals the start of an edit operation in a ListView or TreeView object
CalendarDblClick | 273 | reported when the user double-clicks the left mouse button over a Calendar object
CalendarDown | 271 | reported when the user depresses the left mouse button over a Calendar object
CalendarMove | 274 | reported when the user moves the left mouse button over a Calendar object
CalendarUp | 272 | reported when the user releases the left mouse button over a Calendar object
CellChanged | 164 | modified and updated the contents of a cell in a Grid object
CellChange | 150 | modified the contents of a cell in a Grid object
CellDblClick | 163 | double-clicked the mouse on a cell in a Grid
CellDown | 161 | depressed a mouse button over a cell in a Grid
CellError | 157 | input invalid data into a cell in a Grid
CellMove | 151 | moved to a new cell in a Grid object
CellOver | 160 | mouse moved over a cell in a Grid object
CellUp | 162 | released a mouse button over a cell in a Grid
Change | 36 | altered the text in an Edit or Combo
ClipChange | 120 | data in the clipboard has changed
Close | 33 | Form is about to be closed
ColorChange | 430 | user has selected a colour in a ColorButton
ColumnClick | 320 | user has clicked on a heading in a ListView.
Configure | 31 | position and/or size of an object is about to change
Create | 34 | reported after an object has been created
DDE | 50 | DDE message has been received or sent
DisplayChange | 137 | user has changed screen resolution or number of colours
DragDrop | 11 | moved an object using drag & drop operation
DropFiles | 450 | user has drag/dropped a file icon onto an object
DropObjects | 455 | user has drag/dropped an object icon from the Workspace Explorer or Find Objects tool onto an object
DyalogCustomMessage1 | 95 | allows external applications and dynamic link libraries to insert events into the Dyalog APL/W message queue
EndEditLabel | 301 | signals completion of an edit operation in a ListView or TreeView object
EndSplit | 282 | reported when user releases the left mouse button to signify the end of a drag operation on a Splitter object
ExitApp | 132 | selected End Task from the Windows Task List
ExitWindows | 131 | requested Windows to terminate
Expanding | 302 | reported by a TreeView object as it is about to expand
Expose | 32 | exposed part or all of a Form or a Static
FileBoxCancel | 72 | selected the Cancel button in a FileBox
FileBoxOk | 71 | selected the Ok button in a FileBox
GetDayStates | 266 | reported when a Calendar object requires the APL program to provide state information
GotFocus | 40 | object has received the input focus
GridCopy | 191 | copies selected cells of a Grid to the clipboard
GridCut | 190 | copies selected cells of a Grid to the clipboard and clears them
GridDelete | 193 | clears selected cells of a Grid
GridDropSel | 195 | user has drag/dropped a block of cells in a Grid
GridPaste | 192 | pastes data from the clipboard into a Grid
GridPasteError | 194 | generated by an invalid paste operation in a Grid
GridSelect | 165 | user has changed the selection in a Grid
Help | 400 | user has clicked the Question (?) button and then clicked on an object
HScroll | 39 | requested movement in horiz. scrollbar of Form
Idle | 130 | generated when system is idle
IndexChanged | 210 | user has scrolled the data in a Grid so that the value of its Index property has changed.
ItemDblClick | 342 | user has double-clicked on an item in a ListView or TreeView object
ItemDown | 340 | user has depressed the left mouse button over an item in a ListView or TreeView object
ItemUp | 341 | user has released the left mouse button over an item in a ListView or TreeView object
KeyError | 23 | pressed an invalid key on the keyboard
KeyPress | 22 | pressed a key on the keyboard
Locator | 80 | terminated interaction with a Locator object
LostFocus | 41 | object has lost the input focus
MDIActivate | 42 | MDI SubForm becomes the active one
MDIDeactivate | 43 | MDI SubForm is deactivated
MouseDblClick | 5 | double-clicked a mouse button
MouseDown | 1 | pressed mouse button down
MouseEnter | 6 | moved the mouse into the object
MouseLeave | 7 | moved the mouse out of the object
MouseMove | 3 | user has moved the mouse
MouseUp | 2 | user released a mouse button
MsgBtn1 | 61 | user selected first button in a MsgBox
MsgBtn2 | 62 | user selected second button in a MsgBox
MsgBtn3 | 63 | user selected third button in a MsgBox
PageActivate | 360 | user has switched to a new PropertyPage
PageApply | 350 | user has clicked Apply in a PropertySheet
PageBack | 353 | user has clicked Back in a PropertySheet
PageCancel | 351 | user has clicked Cancel in a PropertySheet
PageChanged | 356 | user has altered Changed property of a PropertyPage
PageDeActivate | 361 | user has switched to a new PropertyPage
PageFinish | 355 | user has clicked Finish in a PropertySheet
PageHelp | 352 | user has clicked Help in a PropertySheet
PageNext | 354 | user has clicked Next in a PropertySheet
PreCreate | 534 | Reported when an instance of an ActiveXControl is created
Protected | 470 | user has attempted to alter protected text in a RichEdit object.
Retracting | 304 | reported by a TreeView object as it is about to retract
Scroll | 37 | requested a movement of the thumb in scrollbar
SelDateChange | 265 | reported when the user changes the date that is selected in a Calendar object
Select | 30 | user has selected the object
SetColSize | 176 | generated when column width changes in a Grid
SetItemPosition | 322 | generated when the user drag-drops an item in a ListView
SetRowSize | 175 | generated when row height changes in a Grid
SetSpinnerText | 421 | user has clicked a spin button in a Spinner object
SetWizard | 365 | user has clicked Next or Back in a PropertySheet
Spin | 420 | user has clicked a spin button in a Spinner object
Splitting | 281 | reported while a Splitter object is being dragged, between a StartSplit and an EndSplit
StartSplit | 280 | reported when the user depresses the left mouse button over a Splitter object
StateChange | 35 | Form is about to change state
SysColorChange | 134 | system colour scheme has changed
TCPAccept | 371 | reported when a client connects to a server TCPSocket object
TCPClose | 374 | reported when the remote end of a TCP/IP connection breaks the connection.
TCPConnect | 372 | reported when a server accepts the connection of a client TCPSocket object and is reported by the client
TCPError | 370 | generated when a fatal TCP/IP error occurs and is reported by a TCPSocket object
TCPGotAddr | 377 | reported when a host name (specified by the RemoteAddrName or LocalAddrName property) is resolved to an IP address
TCPGotPort | 378 | reported when a port name (specified by the RemotePortName or LocalPortName property) is resolved to a port number
TCPReady | 379 | reported when the TCP/IP buffers are free and there is no data waiting to be sent in the internal APL queue
TCPRecv | 373 | reported when data is received by a TCPSocket object
ThumbDrag | 440 | user is dragging the thumb in a TrackBar
Timer | 140 | event generated by a Timer object
VScroll | 38 | requested movement in vert. scrollbar of Form
WinIniChange | 133 | WIN.INI has changed
WorkspaceLoaded | 525 | Reported when a workspace is loaded


ActivateApp Event

ActivateApp Event 137

Applies to: Root

Description

If enabled, this event is reported when the user switches to or from a Dyalog APL/W application.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'ActivateApp' or 137
[3] | Activation flag | 0 or 1

The Activation flag is 0 when the user switches from Dyalog APL to another application

The Activation flag is 1 when the user switches to Dyalog APL from another application.


AddCol Event

AddCol Event 153

Applies to: Grid

Description

If enabled, this event is reported by the Grid object if the user presses the Cursor Right key, and the current cell (CurCell) is within the last column on the Grid. The default action is to append a new column to the contents of the Grid. If you attach a callback function to this event and have it return a value of 0, a new column will not be appended to the Grid. Note that the event will not be generated unless the second element of the AutoExpand property is set to 1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'AddCol' or 153
[3] | Column number | number of the new column (integer). An application may insert a new column into a Grid by calling AddCol as a method. The argument is a 1 to 7-element array as follows: [1] Column number:number of the new column (integer) [2] Column title:character vector or matrix [3] Column width:integer
[4] | Undo flag | 0 or 1
[5] | Resize flag | 0 or 1
[6] | Title colour | negative integer or 3-element RGB vector
[7] | Line type | integer

If you are using default column headings, Column title will be ignored and the columns will be re-labelled with the default titles. If you have set ColTitles, the title you specify will be inserted. If you omit Column title, a blank title will be inserted.

Similarly, if you have not previously set CellWidths, ResizeCols, ColTitleFCol or ColLineTypes, or if you have given them a scalar value, the corresponding parameter will be ignored. However, if you have specified CellWidths, ResizeCols, ColTitleFCol or ColLineTypes to be a vector, the number you specify in the corresponding parameter will be inserted into the appropriate property vector. If you omit to specify Column width for the new column, it will be assigned a default value; new values for the other properties default to 0.

Undo flag (default 1) specifies whether or not the addition of the new column may subsequently be undone by an Undo event.

To insert a new column before the first one, you must specify the Column number as 1 (or 0 if ⎕IO is 0). To add a new column after the last one, you may specify any number greater than the current number of columns. The data in the new column will be set to 0 if the Values property is numeric, or to an empty character vector otherwise.


AddRow Event

AddRow Event 152

Applies to: Grid

Description

If enabled, this event is reported by the Grid object if the user presses the Cursor Down key, and the current cell (CurCell) is within the last row on the Grid. The default action is to append a new row to the contents of the Grid. If you attach a callback function to this event and have it return a value of 0, a new row will not be appended to the Grid.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3 element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'AddRow' or 152
[3] | Row number | integer. An application may insert a new row into a Grid by calling AddRow as a method. The argument is a 1 to 7-element array as follows: [1] Row number:integer [2] Row title:character vector or matrix [3] Row height:integer
[4] | Undo flag | 0 or 1
[5] | Resize flag | 0 or 1
[6] | Title colour | negative integer or 3-element RGB vector
[7] | Line type | integer

If you are using default row titles, Row title will be ignored and the rows will be re-labelled with default titles. If you have set RowTitles, the title you specify will be inserted. If you omit Row title, a blank title will be inserted.

Similarly, if you have not previously set CellHeights, ResizeRows, RowTitleFCol or RowLineTypes, or if you have given them a scalar value, the corresponding parameter will be ignored. However, if you have specified CellHeights, ResizeRows, RowTitleFCol or RowLineTypes to be a vector, the number you specify in the corresponding parameter will be inserted into the appropriate property vector. If you omit Row height, it will be assigned a default value; new values for the other properties default to 0.

Undo flag (default 1) specifies whether or not the addition of the new row may subsequently be undone by an Undo event.

To insert a new row before the first one, you must specify the Row number as 1 (or 0 if ⎕IO is 0). To add a new row after the last one, you may specify any number greater than the current number of rows. The data in the new row will be set to 0 if the Values property is numeric, or to an empty character vector otherwise.


AmbientChanged Event

AmbientChangedEvent 533

Applies to: ActiveXContainer, ActiveXControl

If enabled, this event is reported when any of the ambient properties change in an application hosting an ActiveXControl object. The new values of the ambient properties are available from the FontObj, Fcol and Bcol properties of the ActiveXContainer.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'AmbientChanged' or 533
[3] | Property code | integer
[4] | Description | character vector

For properties supported by Dyalog APL, Property code and Description may be one of the following:

Property code | Description | Meaning
¯701 | DISPID_AMBIENT_BACKCOLOR | BCol has changed
¯703 | DISPID_AMBIENT_FORECOLOR | FCol has changed
¯705 | DISPID_AMBIENT_FONT | Font has changed
¯1 | DISPID_AMBIENT_UNKNOWN | Unknown

Note that other ambient properties may be reported, although these have no corresponding Dyalog APL property.


AnimStarted Event

AnimStartedEvent 294

Applies to: Animation

If enabled, this event is reported by an Animation object just before an AVI clip starts playing

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'AnimStarted' or 294

This event is reported for information only and cannot be disabled or modified in any way.


AnimStopped Event

AnimStoppedEvent 295

Applies to: Animation

If enabled, this event is reported by an Animation object just after an AVI clip has stopped playing

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'AnimStopped' or 295

This event is reported for information only and cannot be disabled or modified in any way.


BadValue Event

BadValue Event 180

Applies to: Edit, Spinner

Description

If enabled, this event is reported by an Edit or Spinner object whose FieldType property is set when the user enters invalid data into the object and then switches focus to another control or to another application. The default action of the event is to sound the bell (beep). You can disable this action by returning 0 from a callback function or by setting its action code to ¯1. Note that in neither case is the Value property of the object updated. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'BadValue' or 180
[3] | Object name | character vector

The third element of the event message is either the name of the control to which the user has switched the focus, or is an empty vector if the focus has gone to another application.


BeginEditLabel Event

BeginEditLabel Event 300

Applies to: ListView, TreeView

If enabled, this event is reported when the user clicks on an item in a ListView or TreeView object that has the focus, and signals the start of an edit operation. The default processing for the event is to display a pop-up edit box around the item and to permit the user to change its text.

You may disable the operation by setting the action code for the event to ¯1. You may prevent a particular item from being edited by returning 0 from a callback function. You may also initiate the edit operation by calling BeginEditLabel as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'BeginEditLabel' or 300
[3] | Item number | Integer. The index of the item.


CalendarDblClick Event

CalendarDblClickEvent 273

Applies to: Calendar

If enabled, this event is reported when the user double-clicks the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'CalendarDblClick' or 273
[3] | Item Number | integer
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer

For the meaning of elements 3 and 6, see CalendarDown.


CalendarDown Event

CalendarDownEvent 271

Applies to: Calendar

If enabled, this event is reported when the user depresses the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'CalendarDown' or 271
[3] | Item Number | integer (see below)
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer (see below)

The 6th element of the event message is one of the following values:
Value |  | Description
0 | NOWHERE | The mouse pointer was not on the month calendar control, or it was in an inactive portion of the control.
1 | CALENDARBK | The mouse pointer was in the calendar's background.
2 | CALENDARDATE | The mouse pointer was on a particular date within the calendar
3 | CALENDARDATENEXT | The mouse pointer was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
4 | CALENDARDATEPREV | The mouse pointer was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
5 | CALENDARDAY | The mouse pointer was over a day abbreviation ("Fri", for example).
6 | CALENDARWEEKNUM | The mouse pointer was over a week number
7 | TITLEBK | The mouse pointer was over the background of a month's title.
8 | TITLEBTNNEXT | The mouse pointer was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
9 | TITLEBTNPREV | The mouse pointer was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
10 | TITLEMONTH | The mouse pointer was in a month's title bar, over a month name.
11 | TITLEYEAR | The mouse pointer was in a month's title bar, over the year value.

If the value of the 6th element of the event message is 2 (CALENDARDATE), the 3rd element is the corresponding date reported as an IDN.

If the value of the 6th element of the event message is 5 (CALENDARDAY), the 3rd element is the index of the corresponding weekday (0-6).

If the value of the 6th element of the event message is 6 (CALENDARWEEKNUM), the 3rd element is the date of the first (leftmost) day in the corresponding week, reported as an IDN.

Otherwise, the 3rd element of the event message is 0.


CalendarMove Event

CalendarMoveEvent 274

Applies to: Calendar

If enabled, this event is reported when the user moves the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'CalendarMove' or 274
[3] | Item Number | integer
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer

For the meaning of elements 3 and 6, see CalendarDown.


CalendarUp Event

CalendarUpEvent 272

Applies to: Calendar

If enabled, this event is reported when the user releases the left mouse button over a Calendar object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'CalendarUp' or 272
[3] | Item Number | integer
[4] | Mouse Button | integer
[5] | Shift State | integer. Sum of 1=shift key, 2=ctrl key, 4=Alt key
[6] | Element Type | integer

For the meaning of elements 3 and 6, see CalendarDown.


CellChange Event

CellChange Event 150

Applies to: Grid

Description

If enabled, this event is reported when the user changes the contents of a cell in a Grid object and then attempts to move to another cell or to another control outside the Grid.

The purpose of this event is to give the application the opportunity to perform additional validation before the update occurs (and to prevent it if necessary) or to update other cells in the Grid as a result of the change.

The default action for the CellChange event is to update the appropriate element of the Values property with the new data. This action can be disabled by returning 0 from the attached callback function. Notice however, that the user is not prevented from moving away from the cell. If you are using this event to perform additional validation and you require the user to correct the data before moving away, you must force the user back to the cell in question by generating a CellMove event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 8-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'CellChange' or 150
[3] | Cell row | integer
[4] | Cell column | integer
[5] | New data | number or character array
[6] | Object name | character vector (name of object to which the user has transferred focus)
[7] | New cell (row) | integer
[8] | New cell (column) | integer

If the user moves to another cell in the Grid, the 6th element of the event message is the name of the Grid object and elements 7 and 8 specify the new cell address (⎕IO dependent).

If the user switches the input focus to another control or selects a MenuItem, the 6th element of the event message contains the name of that control or MenuItem. If the user switches to another application, the 6th element of the event message is an empty character vector. In all these cases, the 7th and 8th elements are 0.

The 5th element of the event message contains the data value that will be used to update the Values property. This will be numeric if the FieldType of the associated Edit object is Numeric, LongNumeric, Date, LongDate or Time. Otherwise, it will be a character array.

An application can update an individual cell in the Grid under program control by calling CellChange as a method. If so, the New object, New cell row and New cell column parameters may be omitted.


CellChanged Event

CellChanged Event 164

Applies to: Grid

Description

If enabled, this event is reported after the user has changed the contents of a cell in a Grid object and then moved to another cell or to another control outside the Grid. The purpose of this event is to give the application the opportunity to perform calculations, and perhaps to update other cells in the Grid as a result of the change.

Note that this event is reported after the change has taken place, and after the Values property has been updated. Furthermore, neither setting the event action code to ¯1 nor returning 0 from a callback function has any effect. If you wish to validate the new data you should use the CellChange (150) event instead.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 5-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'CellChanged' or 164
[3] | Cell row | integer
[4] | Cell column | integer
[5] | New data | number or character array

The 5th element of the event message contains the data value that has been used to update the Values property. This will be numeric if the FieldType of the associated Edit object is Numeric, LongNumeric, Date, LongDate or Time. Otherwise, it will be a character array.

If you want to update an individual cell under program control, you may call CellChange , but not CellChanged, as a method.


CellDblClick Event

CellDblClick Event 163

Applies to: Grid

Description

If enabled, this event is reported when the user double-clicks a mouse button whilst over a cell in a Grid. The purpose of this event is to allow an application to enable some special action on double-click. This event may not be disabled.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9 element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'CellDblClick' or 163
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user clicks over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.


CellDown Event

CellDown Event 161

Applies to: Grid

Description

If enabled, this event is reported when the user presses a mouse button down whilst over a cell in a Grid. The purpose of this event is to allow an application to display a pop-up Menu or a Locator over a cell in a Grid or to take some other special action.

The default action is to generate a CellMove event which will then position the user on the new cell. This action can be prevented by returning 0 from the callback function, in which case the normally ensuing CellMove event will not occur.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 9 element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'CellDown' or 161
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user clicks over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.

An application can position the user on a particular cell in a Grid by calling CellDown as a method, but it is recommended that a CellMove event is used instead.


CellError Event

CellError Event 157

Applies to: Grid

Description

If enabled, this event is reported when the user inserts invalid data into the Edit object associated with a cell in a Grid object and then attempts to move to another cell or to another control outside the Grid. It is also reported if the user selects a MenuItem.

The default action for the CellError event is to sound the bell (beep). This action can be disabled by returning 0 from the attached callback funtion. Whatever the result of the callback, the user will be prevented from moving to another cell in the Grid and the CurCell and Values properties will remain unchanged. The user is not prevented from switching to any other control or to another application. However, if and when the user returns to the Grid, the current cell (CurCell) remains the invalid one and the user may not select a different one until the invalid data in the cell has been corrected. If you wish to allow the user to move to another cell without correcting the data, you may do so by generating a CellMove event explicitly. However, the Values property will remain unchanged and the invalid contents of the Edit object will simply be discarded.

The event message reported as the result of ⎕DQ or supplied as the right argument to your callback function, is an 8-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'CellError' or 157
[3] | Cell row | integer
[4] | Cell column | integer
[5] | Invalid data | character vector
[6] | Object name | character vector (name of object to which the user has transferred focus)
[7] | New cell (row) | integer
[8] | New cell (column) | integer

If the user moves to another cell in the Grid, the 6th element of the event message is the name of the Grid object and elements 7 and 8 specify the cell address (⎕IO dependent).

If the user switches the input focus to another control or selects a MenuItem, the 6th element of the event message contains the name of that control or MenuItem. If the user switches to another application, the 6th element of the event message is an empty character vector. In all these cases, the 7th and 8th elements are 0.

The 5th element of the event message contains the character vector in the Text property of the associated Edit object which is inconsistent with its FieldType.


CellOver Event

CellOver Event 160

Applies to: Grid

Description

If enabled, this event is reported when the user moves the mouse poimter whilst over a cell in a Grid.

There is no default action for this event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is an 9 element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'CellOver' or 160
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user moves the mouse pointer over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.


CellMove Event

CellMove Event 151

Applies to: Grid

Description

If enabled, this event is reported when the user attempts to position the cursor over a cell in a Grid by clicking the left mouse button or by pressing a cursor movement key. The purpose of this event is to allow an application to perform some action prior to the user entering a cell, or to inhibit entry to a cell.

The default action is to position the user on the new cell. This action can be prevented by returning a 0 from the callback function attached to the event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7 element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'CellMove' or 151
[3] | New cell (row) | integer
[4] | New cell (column) | integer
[5] | Scroll flag | 0 or 1
[6] | Selection flag | 0, 1 or 2
[7] | Mouse flag | 0 or 1

The 5th element of the event message is 1 if switching to the new cell would cause the Grid to scroll.

The 6th element of the event message is 1 if the user is moving to the new cell by extending the selection. It is 2 if the user selects an entire row or column (by clicking on a title), which moves the current cell to the first one in the selection.

The 7th element of the event message is 1 if the mouse is used to switch to a new cell.

An application can position the user on a particular cell in a Grid by calling CellMove as a method. If so, the argument need contain only the New cell row and New cell column parameters.


CellUp Event

CellUp Event 162

Applies to: Grid

Description

If enabled, this event is reported when the user releases a mouse button down whilst over a cell in a Grid. This event is a companion to the CellDown event and could be used to hide a pop-up which was displayed in response to the CellDown. The CellUp event performs no default action and may not be disabled.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9 element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'CellUp' or 162
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button released (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down
[7] | Cell row | integer
[8] | Cell column | integer
[9] | Title index | integer

The y and x position of the mouse are reported relative to the top-left corner of the Grid.

The cell row and column are ⎕IO dependent

If the user clicks over a row title, the value reported for the column is ¯1, and the value reported for Title index is the index of that row title in RowTitles, or, if RowTitles is not defined, the row number. Column titles are handled in a similar fashion.

An application can position the user on a particular cell in a Grid by calling CellDown event as a method, but it is recommended that a CellMove event is used instead.


Change Event

Change Event 36

Applies to: Combo, Edit, RichEdit, Spinner

Description

If enabled, this event is reported when the user alters the text in a Combo or Edit object (by typing). The event is not applicable for a Combo with Style 'Drop' because this Style does not allow the user to alter data. The Change event is not reported repeatedly as the user edits the data. Instead, it is reported when the user indicates that he has finished with the field by :

a) clicking on another object

or

b) causing an event on another object (without altering the input focus) which will fire a callback function or cause ⎕DQ to terminate. This can occur if the user chooses a MenuItem, or fires a Button with the Default or Cancel property by pressing Enter or Esc, or selects an object using an accelerator key.

The purpose of the Change event is to allow the application to validate data which has been newly entered to the field, before proceeding with another action. It is for this reason that the event is fired not just when the input focus changes, but also when the user takes some action that could cause the application to do something else.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Change' or 36
[3] | Object name | character vector (name of object that is to receive the focus or generate an event)

If the focus is transferred to an external application, the third element is an empty vector.

The default processing for this event is to allow the focus to change (if applicable) and to reset the internal flag that indicates that the data in the field has changed.

If you disable the event by setting the "action" code to ¯1, or inhibit it by returning 0 from a callback, the focus change (if applicable) is allowed to proceed, but the internal flag is not reset. If you wish to prevent the focus change you must explicitly reset the focus back onto the object that generated the event.

If the event was generated because the user switched to another application, and you return a 0 from your callback (because the data was not valid), the flag marking the Combo or Edit as having been changed remains set. If the user returns to your application by re-focusing on the same Combo or Edit, nothing happens immediately, but because the field is marked as changed (the flag was not reset) you will get another Change event when he leaves it. However, if the user returns to your application in some other way, e.g. by focusing on another object or by selecting a MenuItem, a second Change event will be generated immediately.

The following function illustrates how Change events can be processed. The Check function referred to in line[4] is assumed to return 1 if the data is valid and 0 if not.

[0]   R←VALIDATE Msg
[1]  ⍝ Validates field contents after Change event
[2]
[3]  ⍝ Normal exit (R←1) if data is valid
[4]    →(R←Check⊃Msg)/Exit
[5]
[6]  ⍝ R now 0, so field remains marked as "changed"
[7]
[8]  ⍝ If user has switched to another application,
[9]  ⍝ we need take no further action because we will
[10] ⍝ get a second Change event when he returns.
[11]  →(''3⊃Msg)/Exit
[12]
[13] ⍝ Display error box (prepared earlier)
[14]   'ERR' ⎕WS 'Text' 'Data is invalid'
[15]   ⎕DQ'ERR'
[16]
[17] ⍝ Restore focus to bad field
[18]   ⎕NQ(⊃Msg)40
[19]
[20] Exit:


ClickComment Event

ClickComment Method 225

Applies to: Grid

If enabled, a ClickComment event is generated when the user clicks the mouse in a comment window of a Grid.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'ClickComment' or 225
[3] | Row | integer
[4] | Column | integer

The event message reports the co-ordinates of the cell. The default action is to raise the comment window so that it appears above all other, potentially overlapping, comment windows.

Note that if the comment window relates to a row or column title, the value reported in element [3] or [4] of the event message is ¯1.


ClipChange Event

ClipChange Event 120

Applies to: Clipboard

Description

If enabled, this event is reported when another application changes the contents of the Windows clipboard.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'ClipChange' or 120


Close Event

Close Event 33

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetType, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

A Close event is generated when an object is destroyed. For a Form or SubForm, the event may be generated by the user selecting "Close" from its System Menu. In this case, the event is reported before the window is destroyed, and you may prevent it from going ahead by associating a callback function which returns a result of 0.

By trapping this event you can control termination of your application in many different ways. For example, you can :

automatically close all Forms in your application when the master Form is closed.

prevent the user from terminating the application if it is inappropriate at that time.

display an "Are you sure ?" MsgBox.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Close' or 33


ColorChange Event

ColorChangeEvent 430

Applies to: ColorButton

If enabled, this event is reported by a ColorButton object when the user chooses a colour from the colour selection drop-down.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'ColorChange' or 430
[3] | New Colour | 3-element integer vector

The 3rd element of the event message contains the RGB value for the selected colour.

Note that the event is reported when the user chooses a colour, whether or not the newly selected colour differs from the one that was previously selected.

This event is reported for information only and cannot be disabled or modified in any way.


ColumnClick Event

ColumnClick Event 320

Applies to: ListView

If enabled, this event is reported when the user clicks on the column heading in a ListView object. This event may not be disabled or affected by a callback function in any way.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'ColumnClick' or 320
[3] | Column number | Integer
[4] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[5] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down


Configure Event

Configure Event 31

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

If enabled, this event is generated when the configuration of an object (position and/or size) is about to change.

For a Form, the event is generated when the Form is resized or moved by the user.

For any object other than a Form, it can occur in one of two ways. Firstly, whenever a Form is resized, the system (by default) re-arranges its children so as to maintain their relative position and size. This generates a Configure event (if enabled) for each one of them.

Secondly, it can occur as a result of the user resizing the object directly. This facility is enabled by setting the object's Sizeable property to 1.

Note that a Configure event is not reported when an object is moved using "drag & drop". See Dragable (property) and DragDrop (event) for details of this operation.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Configure' or 31
[3] | Y | y-position of top left corner
[4] | X | x-position of top left corner
[5] | H | height of object
[6] | W | width of object

For any object, the operation can be prevented by returning a scalar 0 from the callback function associated with the Configure event.

Full-Drag Considerations

The user may choose a system option, described here as full-drag, whereby the contents of the window are re-arranged during a resize operation.

If you manage the geometry of your controls using the Attach property, APL honours full drag during resize, changing the size and position of your controls dynamically for you.

However, if you manage the geometry of controls using Configure event callbacks, you should consider the following.

  1. If full drag is in enabled, APL generates Configure events during the resize operation, allowing you to dynamically alter the geometry of controls as you wish. However, the following restrictions apply:

  2. Configure callbacks will only be executed when the interpreter is idle. For example during a ⎕DQ or during Session input (6-space prompt). If the user attempts to move/resize a window that has Configure callbacks attached when the interpreter is busy, the move/resize is not started. This is similar to the operation in non full drag mode, where the move/resize is allowed but the callback does not execute until the interpreter again becomes idle.

  3. The callback cannot be traced. It is necessary to debug the callback code with full drag disabled.

  4. Any untrapped errors in the Configure callback will not halt execution in the normal way, but will instead be reported in the Status Window. Note that it is also not possible to trap such errors higher up the SI stack than the Configure Callback.

  5. There are some programming styles to be avoided if full drag Configure callbacks are to be processed correctly. For example events generated by monadic ⎕NQ within a Configure callback will not be processed until the entire resize operation has been completed.

  6. It is not possible to save a workspace from within a Configure Callback in full drag mode.

The above restrictions apply to Configure events when full drag is enabled, but only when full drag is enabled. The behaviour of Configure callbacks with full drag disabled is the same as for other events.


ContextMenu Event

ContextMenu Event 410

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TrackBar, TreeView, UpDown

If enabled, this event is reported when the user performs the standard Windows action to display a ContextMenu. These include clicking/releasing the right mouse button and pressing F10.

If the object has its own standard context menu, for example an Edit object, the default action is to display this menu. If the object is dockable (see Docking Property), the default action is to display the standard (English) Dyalog APL docking menu.

You may use this event to display your own pop-up context menu, by ⎕DQ'ing it within a callback function. In this case, your callback function should return 0 to disable the standard context menu.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'ContextMenu' or 410
[3] | (reserved) | Empty character vector
[4] | Y | y-position of the mouse (number)
[5] | X | x-position of the mouse (number)


Create Event

Create Event 34

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, NetType, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

If enabled, this event is reported after an object has been created. You may not nullify or modify the event with a 0-returning callback, nor may you generate the event using ⎕NQ, or call it as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Create' or 34
[3] | Flag | 1 = object was created by ⎕WC 0 = object was created by )LOAD, )COPY or ⎕OR

This event also applies to the Session object ⎕SE and may be used to fire a start-up function (in the ⎕SE namespace) when APL initialises.


DateTimeChange Event

DateTimeChangeEvent 267

Applies to: DateTimePicker

If enabled, this event is reported by a DateTimePicker object when the user changes the DateTime value. This occurs when the user selects a new date from the drop-down calendar, or increments or decrements a date time element using the spinner buttons, or edits a datetime element using the keyboard. In the latter case, the event may not be generated until the input focus leaves the corresponding date time element.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'DateTimeChange' or 267
[3] | IDN | integer
[4] | Hour | integer
[5] | Minute | integer
[6] | Second | integer

This event is reported for information only and cannot be disabled or modified in any way.


DDE Event

DDE Event 50

Applies to: Root

Description

If enabled, a DDE event is generated whenever a DDE message is received by Dyalog APL. This will occur whenever a server notifies APL that the value of a shared variable has changed, and whenever a client application requests data from APL. If you have several shared variables, you can determine which of them has changed or whose value has been requested using ⎕SVS.

This event only applies to the Root object ".", so to enable it you must execute one of the following statements :

      '.' ⎕WS 'Event' 50 1

or

      '.' ⎕WS 'Event' 50 fn

or

      '.' ⎕WS 'Event' 50 fn larg

The first statement would cause ⎕DQ to terminate on receipt of a DDE event. The second would cause it to call "fn" each time. The third would do likewise but the value in "larg" would be supplied as its left argument.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function is a 2-element vector as follows :

[1] | Object name | '.' (1-element character vector)
[2] | Event code | 'DDE' or 50

Note:

Due to the nature of DDE "conversations" messages may be received when in fact no change in the value of any shared variables has occurred. Your application code must therefore be prepared to cater for this situation.


DisplayChange Event

DisplayChange Event 137

Applies to: Root

If enabled, this event is reported when the user changes the screen resolution or number of colours. The event is reported for information only; you cannot prevent the change from occurring.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'DisplayChange' or 137
[3] | Height | Integer. Number of pixels in the y-direction
[4] | Width | Integer. Number of pixels in the x-direction
[5] | Number of colours | Integer.


DockAccept Event

DockAcceptEvent 483

Applies to: CoolBand, CoolBar, Form, SubForm, ToolControl

If enabled, this event is reported by a host object just before it accepts a client object docking operation. This event is reported (by the host) immediately after the DockRequest is reported (by the client).

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Host Object | ref or character vector
[2] | Event name or code | 'DockAccept' or 483
[3] | Client Object | ref or character vector
[4] | Edge | character vector
[5] | y-position | number
[6] | x-position | number
[7] | Outline rectangle | 4-element nested

Elements 4-7 of this event message are the same as those reported by DockMove, and the effect of a callback function is identical. See DockMove for further information.


DockCancel Event

DockCancelEvent 485

Applies to: CoolBand, CoolBar, Form, SubForm, ToolControl

If enabled, this event is reported by a client object when the user aborts a docking operation by pressing Escape.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Client Object | ref or character vector
[2] | Event name or code | 'DockCancel' or 485

This event is reported for information only and cannot be cancelled or inhibited in any way.


DockEnd Event

DockEndEvent 484

Applies to: CoolBand, CoolBar, Form, SubForm, ToolControl

If enabled, this event is reported by a client object after it has been successfully docked in a host object.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Client Object | ref or character vector
[2] | Event name or code | 'DockEnd' or 484

This event is reported for information only and cannot be cancelled or inhibited in any way.


DockMove Event

DockMoveEvent 481

Applies to: CoolBand, CoolBar, Form, SubForm, ToolControl

If enabled, this event is reported by a host object when a dockable object (the client) is dragged over it. The event will only be reported if the name of the client object is included in the list of objects that the host object will accept, which is defined by its DockChildren property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Host Object | ref or character vector
[2] | Event name or code | 'DockMove' or 481
[3] | Client Object | ref or character vector
[4] | Edge | character vector
[5] | y-position | number
[6] | x-position | number
[7] | Outline rectangle | (see below)

The 4th element of the event message Edge is a character vector that indicates along which edge of the host object the client object will be docked if the mouse button is released. It is either 'Top', 'Bottom', 'Left', 'Right' or 'None'. The latter indicates that the object will not be docked. An object will dock only if the mouse pointer is inside, and sufficiently near to an edge of, the host.

The 5th and 6th elements of the event message report the position of the mouse pointer in the host object.

The 7th element of the event message is a 4-element nested vector containing the y-position, x-position, height and width of a rectangle. If Edge is 'None', this is the bounding rectangle of the client object. Otherwise, the rectangle describes a docking zone in the host that the client object will occupy when the mouse button is released.

If a callback function returns 0, the system displays the bounding rectangle and not a docking zone, and the docking operation is inhibited. You could use this mechanism to prohibit docking along one or more edges, whilst allowing it along others.

A callback function may modify the event message to cause a different sized docking zone to be displayed, or to force docking along a particular edge.

The DockMove event is generated repeatedly as the docking object is dragged.


DockRequest Event

DockRequestEvent 482

Applies to: CoolBand, CoolBar, Form, SubForm, ToolControl

If enabled, this event is reported by a client object just before it is docked in a host object, when the user releases the mouse button.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Client Object | ref or character vector
[2] | Event name or code | 'DockRequest' or 482
[3] | Host Object | ref or character vector
[4] | Edge | character vector
[5] | y-position | number
[6] | x-position | number
[7] | Outline rectangle | 4-element nested

Elements 4-7 of this event message are the same as those reported by DockMove, and the effect of a callback function is identical. See DockMove for further information.


DockStart Event

DockStartEvent 480

Applies to: CoolBand, CoolBar, Form, SubForm, ToolControl

If enabled, this event is reported by a dockable object (one whose Dockable property is set to 1) when the user starts to drag it using the mouse.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'DockStart' or 480

A callback function may prevent the docking operation from starting by returning 0.


DragDrop Event

DragDrop Event 11

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Image, Label, List, ListView, Marker, MDIClient, Poly, ProgressBar, PropertyPage, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, Text, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

If enabled, this event is reported when the user drops one object over another. It is generated by the object which is being dropped on.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object name | character vector (name of target object)
[2] | Event code | 'DragDrop' or 11
[3] | Object name | character vector (name of dragged object)
[4] | Y | y-position of mouse pointer
[5] | X | x-position of mouse pointer
[6] | H | height of dragged object
[7] | W | width of dragged object
[8] | Shift State | numeric scalar containing the sum of the values associated with the Shift(1), Ctrl(2) and Alt(4) keys when the object was dropped.

Y, H, X and W are reported relative to the object being dropped on.


DropDown Event

DropDownEvent 45

Applies to: ColorButton, Combo, ComboEx, DateTimePicker, Menu

If enabled, this event is reported when the user clicks the drop-down button in a Combo, ComboEx, ColorButton, DateTimePicker or Menu object, just before the drop-down list, colour selection, calendar or -menu is displayed.

For a DateTimePicker this event only applies if the Style of the DateTimePicker is 'Combo'.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'DropDown' or 45

This event is reported for information only and cannot be disabled or modified in any way.


DropFiles Event

DropFiles Event 450

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TrackBar, TreeView, UpDown

If enabled, this event is reported when the user drags a file icon or a set of file icons and drops them onto the object. The system takes no action other than to report the event.

Note that the event is only reported if AcceptFiles is set to 1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'DropFiles' or 450
[3] | Files | Vector of character vectors containing the file names.
[4] | Item number | Integer. The index of the item within the object onto which the file(s) was dropped. Applies only to objects that have an Items property such as List, ListView and TreeView.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key


DropObjects Event

DropObjects Event 455

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, ToolBar, ToolControl, TrackBar, TreeView, UpDown

If enabled, this event is reported when the user drags an object icon or a set of object icons from the Explorer Tool or Find Objects Tool (which are part of the Dyalog APL Session) and drops them onto the object. The system takes no action other than to report the event. You can use this event to extend drag-drop functionality in your Session. For example, you could perform an operation by drag-dropping an APL object icon onto a Button in the Session toolbar.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'DropObjects' or 455
[3] | Objects | Vector of character vectors containing the object names.
[4] | Item number | Integer. The index of the item within the object onto which the file(s) was dropped. Applies only to objects that have an Items property such as List, ListView and TreeView. Otherwise this value is -1.
[5] | Shift state | Integer. Sum of 1=Shift key, 2=Ctrl key, 4=Alt key


DyalogCustomMessage1 Event

DyalogCustomMessage1 Event 95

Applies to: Form

This event allows external applications and dynamic link libraries to insert events into the Dyalog APL/W message queue.

DyalogCustomMessage1 may be invoked from a C program as follows:

msg=RegisterWindowMessage("DyalogCustomMessage1");
SendMessage(hWnd,msg,wParam,lParam);

where hWnd is the window handle of the object in the Dyalog APL Workspace. If the object is a Form, this may be obtained using FindWindow(). If not, hwnd may be passed to the external process as an argument to a function.

The parameters wParam and lParam are reported as numeric arguments to the APL callback function.

NOTE: It is not possible to pass pointers to data in wParam or lParam. When the APL callback executes the pointers may not be valid.

If a callback function is attached to the event, the callback function will be run when the event reaches the top of the queue.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The result of a callback function is not returned to the external application.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'DyalogCustomMessage1' or 95
[3] | wparam | integer
[4] | lparam | integer


EndEditLabel Event

EndEditLabel Event 301

Applies to: ListView, TreeView

If enabled, this event is reported when the user signals completion of an edit operation in a ListView or TreeView object. This occurs when the item being edited loses the focus or when the user presses the Enter key. The default processing for the event is to update the item label (string) with the edited text in the pop-up edit box.

You may disable the update operation by setting the action code for the event to ¯1. You may also prevent the update from occurring by returning 0 from a callback function. You may specify the text used to update the item by returning the event message (containing the desired text) from a callback function. Finally, you may change the text of any item dynamically by calling EndEditLabel as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'EndEditLabel' or 301
[3] | Item number | Integer. The index of the item.
[4] | Text | character vector containing the text that will be used to update the item’s label.


EndSplit Event

EndSplitEvent 282

Applies to: Splitter

If enabled, this event is reported when the user releases the left mouse button to signify the end of a drag operation on a Splitter object.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'EndSplit' or 282
[3] | Y | y-position of top left corner
[4] | X | x-position of top left corner
[5] | H | height of the Splitter
[6] | W | width of the Splitter

See also StartSplit, Splitting.


ExitApp Event

ExitApp Event 132

Applies to: Root

Description

If enabled, this event is reported when the user attempts to terminate a Dyalog APL/W application from the Windows Task List.

The Windows Task list displays the names of all running applications. The name displayed for a Dyalog APL/W application is defined by the Caption property of the system object Root. If you fail to define this property, there will be no entry for the application in the Task List.

If you wish to prevent the user from terminating your application from the Windows Task List, you may disable this event by setting its action code to ¯1. However, if you do this, your user may be puzzled as to why the operation does not work as expected. An alternative is to attach a callback function to the event which displays a message box. Not only does this allow you to provide user feedback, but you can provide confirm/cancel options. If your callback function returns a zero, your application will not be terminated.

Note that this event only provides for termination via the Windows Task List. See also the ExitWindows event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'ExitApp' or 132


ExitWindows Event

ExitWindows Event 131

Applies to: Root

Description

If enabled, this event is reported when the user attempts to terminate the Windows Operating System. When this is done, Windows gives all running applications the opportunity to prevent it. Typically, an application that has unsaved changes will display a dialog box warning the user of this situation and offering the opportunity to cancel the termination. The default action for this event is to allow Windows to close. You can prevent this by returning a zero from a callback function. You can also prevent the user from closing Windows down by disabling the event altogether. This is achieved by setting its action code to ¯1. In most cases this is less preferable than the callback method as it does not allow you to inform the user as to why Windows won’t terminate.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'ExitWindows' or 131
[3] | Flag | 0 or 1


Expanding Event

Expanding Event 302

Applies to: Grid, TreeView

If enabled, this event is reported by a Grid or a TreeView object just before it is about to expand to show additional rows or children of the current item.

In a Grid, this occurs when the user clicks the picture or tree line in the row title.

In a Treeview, this occurs when the user double-clicks the item label or clicks in the button or on the tree line to the left of the item label.

The default processing for the event is to expand the tree at the corresponding point.

You may disable the expand operation by setting the action code for the event to ¯1. You may also prevent the expand from occurring by returning 0 from a callback function. You may expand an object dynamically under program control by calling Expanding as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Expanding' or 302
[3] | Item number | Integer. The index of the row or item.


Expose Event

Expose Event 32

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Description

If enabled, this event is reported when part or all of the object's window is exposed to view. Under normal circumstances, APL repaints the exposed region automatically. However, if you have drawn unnamed graphical objects (which are not managed by APL) you should use this event to redraw them when required. Note that APL will itself repaint any named objects in the region before reporting the event.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Expose' or 32
[3] | Y | y-position of top-left corner of exposed region
[4] | X | x-position of top-left corner of exposed region
[5] | H | height of exposed region
[6] | W | width of exposed region

This event cannot be disabled by setting its action code to ¯1. Similarly, setting the result of a callback function to 0 has no effect on it.


FileBoxCancel Event

FileBoxCancel Event 72

Applies to: BrowseBox, FileBox

Description

If enabled, this event is reported when a FileBox is closed because the user has pressed the "Cancel" button or closed it.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'FileBoxCancel' or 72
[3] | File name | character vector containing the name of the currently selected file (empty if none)


FileBoxOk Event

FileBoxOk Event 71

Applies to: FileBox

Description

If enabled, this event is reported when a FileBox is closed because the user has pressed the "OK" button.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'FileBoxOk' or 71
[3] | File name | character vector containing the name of the currently selected file (empty if none)


FrameContextMenu Event

FrameContextMenuEvent 411

Applies to: Form, SubForm

If enabled, this event is reported when the user clicks and releases the right mouse button over the non-client area of an object, e.g. the title bar in a Form.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'FrameContextMenu' or 411
[3] | Y | y-position of the mouse (number)
[4] | Y | x-position of the mouse (number)

For further details, see ContextMenu Event.


GetDayStates Event

GetDayStatesEvent 266

Applies to: Calendar

If enabled, this event is reported when a Calendar object requires the APL program to provide day state information for the range of dates it is about to display.

The Calendar object displays day numbers using either the normal or the bold font attribute. However, it does not store this information beyond the month or months currently displayed.

When the Calendar control scrolls (and potentially at other times), it generates a GetDayStates event to ask you (the APL program) to tell it which of the dates that are about to be shown, should be displayed using the bold font attribute.

If you wish any dates to be displayed using the bold font attribute, you must attach a callback function to this event which returns day state information in its result.

By default, all dates are displayed using the normal font attribute, so you need only do this if you want any dates highlighted in bold.

You may not disable or nullify the operation that caused GetDayStates to fire by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'GetDayStates' or 266
[3] | First Date | an integer (IDN)
[4] | Last Date | an integer (IDN)
[5] | Bold Dates | an integer vector of IDNs.

When the callback function is invoked, the 3rd and 4th elements of the event message contain IDNs for the first and last date in the range of dates that the Calendar object is about to display. The 5th element of the event message contains those IDNs within this range of dates that the Calendar control already knows are to be displayed using the bold font attribute. This will typically be empty.

The result of your callback function should be the same event message with only the 5th element modified in any way. This should contain the IDNs of the dates (within the range specified by the 3rd and 4th elements) that are to be displayed using the bold font attribute.

Example:

Suppose that you keep a variable BOLD_DATES in the Calendar object. This variable is a vector of IDN values that defines those dates that the user has somehow identified as special and that you wish to display in bold, The following callback function could be applied:

∇ MSG←DAYSTATES MSG;MASK;⎕IO
[1]   ⍝ Callback function for the GetDayStates event
[2]   ⍝ Object (⊃MSG) contains a variable BOLD_DATES
[3]   ⍝ that defines ALL the IDNs that are to be displayed in bold
[4]   ⍝ We need to return only those that fall within the range
[5]   ⍝ of dates that are about to be displayed by the Calendar
[6]    ⎕CS⊃MSG
[7]    ⎕IO←1
[8]    MASK←BOLD_DATES≥3⊃MSG
[9]    MASK←MASK∧BOLD_DATES≤4⊃MSG
[10]   MSG[5]←⊂MASK/BOLD_DATES
     ∇

You may also set the font attribute for particular days by calling GetDayStates as a method.

For example, to set the bold attribute for IDN 36048 (11 September 1998) in a Calendar object called 'F.CAL1', you could execute the expression:

F.CAL1.CetDayStates 36048 36048 36048

To clear the bold attribute for the same day:

F.CAL1.CetDayStates 36048 36048 <⌈>

Note that the Calendar object will ignore any IDNs you specify that are outside the range of dates that it is currently displaying.


GetTipText

GetTipText Event 325

Applies to: ListView , TreeView

If enabled, this event is reported by a TreeView or ListView object just before it displays a tip for a specific row.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'GetTipText' or 325
[3] | Item index | Integer (⎕IO dependant)
[4] | SubItem index | Integer (⎕IO dependant, currently always equal to ⎕IO)
[5] | TipText | The text to be displayed.

Modifying and returning the 5th element of the argument to the callback function allows the application to change the displayed tip.

The text can be set to a character array of rank 2 or less.

The default processing for the event is to display the default tip (if there is one).


GotFocus Event

GotFocus Event 40

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, SubForm, TrackBar, TreeView

Description

If enabled, this event is generated when the user has moved the keyboard focus to a new object by clicking the left mouse button, pressing TAB, or using a cursor key.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector (name of object that has received the focus)
[2] | Event code | 'GotFocus' or 40
[3] | Object name | character vector (name of object which previously had the focus)

The third element (object name) is empty if the focus was obtained from another application window.

The GotFocus event is generated after the focus has changed. The default processing is therefore to take no action. However, if you disable the event by setting its action code to ¯1, or inhibit it by returning a 0 from your callback function, the focus is automatically restored to the object (or external application) that had lost it.


GridCopy Event

GridCopy Event 191

Applies to: Grid

Description

If enabled, this event is reported when the user presses Ctrl+Insert and there are selected cells in the Grid. The default action of the event is to copy the contents of the selected block of cells to the clipboard. You may disable this effect entirely by setting the action code of the event to ¯1. You may also disable the copy operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows:

[1] | Object name | character vector
[2] | Event name or code | 'GridCopy' or 191
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell(s) in the selected block
[5] | Values | 2-element nested vector. The first element is a matrix containing the values of the selected block(s) of cells. This is the data that will be copied to the clipboard. The second element is a Boolean matrix containing the values of the CellSet property for the selected block(s) of cells.

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If more than one block of cells is selected, Start and End are matrices whose rows identify the start and end cells of each of the selected blocks, and Data is the contents of the selected blocks catenated along the appropriate dimension according to their relative positions in the Grid.

You may copy cells under program control by calling GridCopy as a method.

To copy a specific block of cells to the clipboard whether or not they are selected, you must specify the Start and End parameters. For example, the following expression will copy the 3x3 block of cells in the top-left of the Grid (⎕IO is 1) to the clipboard:

     Gridname.GridCopy (1 1) (3 3)

If you omit these parameters, the currently selected block of cells will be copied to the clipboard. If no cells are selected, the entire contents of the Grid will be copied. i.e.

gridname.GridCopy <⌈>

The data copied to the clipboard is registered in Dyalog (APL internal),Wk3 (Lotus), XlTable (Excel) and tab/new-line delimited text formats.


GridCut Event

GridCut Event 190

Applies to: Grid

Description

If enabled, this event is reported when the user presses Shift+Delete and there are selected cells in the Grid. The default action of the event is to copy the contents of the selected block(s) of cells to the clipboard and then to empty the selected cells. You may disable this effect entirely by setting the action code of the event to ¯1. You may also disable the cut operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows:

[1] | Object name | character vector
[2] | Event name or code | 'GridCut' or 190
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell in the selected block
[5] | Data | 2-element nested vector. The first element is a matrix containing the values of the selected block(s) of cells. This is the data that will be copied to the clipboard. The second element is a Boolean matrix containing the values of the CellSet property for the selected block(s) of cells.

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If more than one block of cells is selected, Start and End are matrices whose rows identify the start and end cells of each of the selected blocks, and Data is the contents of the selected blocks catenated along the appropriate dimension according to their relative positions in the Grid.

The data copied to the clipboard is registered in Dyalog (APL internal),Wk3 (Lotus), XlTable (Excel) and tab/new-line delimited text formats.


GridDelete Event

GridDelete Event 193

Applies to: Grid

Description

If enabled, this event is reported when the user presses Delete and there are selected cells in the Grid. The default action of the event is to empty the selected cells. You may disable this effect entirely by setting the action code of the event to ¯1. You may also disable the delete operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows:

[1] | Object name | character vector
[2] | Event name or code | 'GridDelete' or 193
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell(s) in the selected block(s)

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If more than one block of cells is selected, Start and End are matrices whose rows identify the start and end cells of each of the selected blocks.


GridDropSel Event

GridDropSel Event 195

Applies to: Grid

Description

If enabled, this event is reported when the user drag/drops a selected block of cells in the Grid. The default action is that the contents of the selected cells replace the values in the block of cells onto which they are dropped and this block now becomes selected.

You may disable the drag/drop facility entirely by setting the action code of the event to ¯1. You may also disable an individual drag/drop operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'GridDropSel' or 195
[3] | Start | 2-element integer vector containing the row, column address of the top left cell in the selected block
[4] | Size | 2-element integer vector containing the number of rows and columns in the selected block
[5] | Target | 2-element integer vector containing the row/column address of the top left cell onto which the selected block is being dropped
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down
[7] | Undo flag | 0 or 1
[8] | Values | Matrix containing the values of the selected block of cells. This is the data that will replace the values in the target cells.
[9] | CellSet flags | Boolean Matrix containing the values of the CellSet property for the selected block of cells. This will replace the values of the CellSet property of the target cells.

The shift state in element 6 is intended to allow the APL programmer to implement an insert operation instead of a copy or move operation if required.

You may copy the contents of one block of cells to another by calling GridDropSel as a method. If so, you need only specify the Start, Size and Target parameters. Note that the result block becomes selected.

The Undo flag is always 1 if the event was generated by the user.


GridKeyPress Event

GridKeyPress Event 24

Applies to: Grid

If enabled, this event is generated when the user presses and releases a key in a Grid cell.

The GridKeyPress is reported on the Grid, after the KeyPress event, which is reported on the Input object associated with the current cell.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'GridKeyPress' or 24
[3] | Input Code | character scalar or vector
[4] | ASCII code | integer scalar
[5] | Key Number | integer scalar
[6] | Shift State | integer scalar
[7] | Input Object | character vector

For a full description of elements [3-6], see KeyPress event.

The 7th element of the event message contains the name of the Input object associated with the current cell and on which the corresponding KeyPress event has been reported.

If a callback function on the KeyPress event returns 0, the GridKeyPress event is not fired. If a callback function on the KeyPress event returns a modified KeyPress message, the GridKeyPress event is fired with the modified message and not the original one.

The default action of the GridKeyPress event is to pass its message back to the appropriate Input object to be actioned. If a callback on GridKeyPress returns 0, the keystroke will be ignored.


GridPaste Event

GridPaste Event 192

Applies to: Grid

Description

If enabled, this event is reported when the user presses Shift+Insert and there is data in the clipboard that is in a suitable format for the Grid. The default action of the event is to copy the contents of the clipboard into the currently selected block of cells, or, if no cells are selected, into the block of cells starting at the current cell (CurCell). Note that if there is a selected range of cells and the shape of the data being pasted does not exactly match the size of the selected range, the system generates a GridPasteError event in addition to the GridPaste event.

You may disable the paste facility entirely by setting the action code of the event to ¯1. You may also disable an individual paste operation by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'GridPaste' or 192
[3] | Values | New values (taken from the clipboard) which are to replace the existing values of the block of cells defined by Start and End.
[4] | CellSet flags | Boolean Matrix containing the new values of the CellSet property for the block of cells defined by Start and End.
[5] | Start | 2-element integer vector containing the row, column address of the top left cell the selected block. If there is no selection, this is the address of the current cell(CurCell).
[6] | End | 2-element integer vector containing the row, column address of the bottom right cell in the selected block. If there is no selection, this is the address of the bottom right cell of the block starting at the current cell that will be overwritten

You can replace the contents of a contiguous block of cells with the data in the clipboard, or with an arbitrary matrix of values, by calling GridPaste as a method.

If you call GridPaste with an argument of <—>, the data is taken from the clipboard; otherwise the data to be pasted is specified by the Values and CellSet flags parameters.. If you omit Start, data is pasted into the currently selected range of cells. If there are no cells selected, data is pasted starting at the current cell (CurCell). In either case, the block of replaced cells becomes selected.


GridPasteError Event

GridPasteError Event 194

Applies to: Grid

Description

If enabled, this event is reported when the user presses Shift+Insert and there is data in the clipboard, but the system is unable to paste the data into the Grid. This occurs if there is a currently selected block of cells whose shape does not match the shape of the data in the clipboard. It also occurs if there is no selected block of cells, and pasting the data in starting at the current cell (CurCell) would overflow the Grid. Setting the action code of this event to ¯1, or returning a 0 from a callback function attached to it, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'GridPasteError' or 194
[3] | Values | Contents of the clipboard.
[4] | CellSet flags | Boolean array indicating which elements of the clipboard data are empty.
[5] | Start | 2-element integer vector containing the row, column address of the top left cell in the selected block. If there is no selection, this is the address of the current cell (CurCell).
[6] | End | 2-element integer vector containing the row, column address of the bottom right cell in the selected block. If there is no selection, this is the address of the bottom right cell of the block starting at the current cell that will be overwritten
[7] | Error Number | 4 (RANK ERROR) or 5 (LENGTH ERROR)


GridSelect Event

GridSelect Event 165

Applies to: Grid

Description

If enabled, this event is reported when the user performs or cancels the selection of a block of cells in a Grid object. This event is reported after the selection has changed. Setting its action code to ¯1 has no effect and the result of a callback function cannot be used to alter the selection that has been made. You may however control the user’s ability to make selections using the CellSelect property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'GridSelect' or 165
[3] | Start | 2-element integer vector or matrix containing the row, column address(es) of the top left cell(s) in the selected block(s)
[4] | End | 2-element integer vector or matrix containing the row, column address(es) of the bottom right cell(s) in the selected block

Note that the values of Start and End are sensitive to the index origin, ⎕IO.

If the selection is made with the mouse, the GridSelect event is reported when the left mouse button is released. If the selection is made using the cursor keys, the GridSelect event is reported when the Shift key is released.

The GridSelect event is also generated when the current selection is cancelled by clicking on a cell with the mouse or by pressing a cursor key.


Help Event

Help Event 400

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Ellipse, Form, Grid, Group, Image, Label, List, ListView, Marker, MDIClient, Poly, ProgressBar, PropertyPage, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, Text, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

If enabled, this event is reported when the user clicks on the Question (?) button in the title bar of a Form and then clicks again over the object. The presence of the Question (?) button is determined by the value of the HelpButton property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Help or 400
[3] | Y-coordinate | Number
[4] | X-coordinate | Number

The y and x-coordinates refer to the position of the mouse pointer in the object and are reported in the coordinate system of that object.


HideComment Event

HideComment Event 220

Applies to: Grid

If enabled, a HideComment event is generated just before a comment window is hidden as a result of the user moving the mouse-pointer away from a commented cell.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'HideComment' or 224
[3] | Row | integer
[4] | Column | integer

You may prevent the comment from being hidden by returning 0 as the result of a callback function.

Note that if the comment window relates to a row or column title, the value reported in element [3] or [4] of the event message is ¯1.

Invoked as a method, HideComment is used to hide a comment that has previously been displayed by ShowComment. For example, the following expression hides the comment associated with the cell at row 2, column 1.

      F.G.HideComment 2 1

If HideComment is called with an argument of <—>, all comments are hidden.


HScroll Event

HScroll Event 39

Applies to: Form, SubForm

Description

If enabled, this event is generated when the user attempts to move the thumb in a horizontal scrollbar in a Form or SubForm. This event occurs only in a Form whose HScroll property is set to ¯1 and is distinct from the Scroll event that is generated by a Scroll object. The event may be generated in one of three ways:

  • dragging the thumb.
  • clicking in one of the "arrow" buttons situated at the ends of the scrollbar. This is termed a small change, the size of which is defined by Step[3].
  • clicking in the body of the scrollbar. This is termed a large change, the size of which is defined by Step[4].

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'HScroll' or 39
[3] | Scroll Type | numeric
[4] | Position | numeric

The value of Scroll Type is 0 (drag), 1 or ¯1 (small change) or 2 or ¯2 (large change). The sign indicates the direction.

The value of Position is the new (requested) position of the thumb. Notice however, that the event is generated before the thumb is actually moved. If your callback function returns a scalar 0, the position of the thumb will remain unaltered.


Idle Event

Idle Event 130

Applies to: Root

Description

If enabled, this event is generated whenever APL looks to see if there is an event on the queue and finds it empty. Its purpose is to allow an application to perform some background processing when the user is not doing anything. It is unwise to use this event directly from the Session as it will occur repeatedly and may lock you out.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function is a 2-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'Idle' or 130


IndexChanged Event

IndexChanged Event 210

Applies to: Grid

If enabled, this event is reported when the value of the Index property of a Grid has changed as a result of user interaction. The event is reported after the Grid has been scrolled. You may not modify or nullify the operation with a 0-return callback and you may not call IndexChanged as a method or generate this event using ⎕NQ. To cause a Grid to scroll, use ⎕WS to set its Index property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'IndexChanged or 210
[3] | Row | Integer.
[4] | Column | Integer.


ItemDblClick Event

ItemDblClick Event 342

Applies to: ListView, TreeView

If enabled, this event is reported when the user double-clicks a mouse button when the mouse pointer is over an item in a ListView or TreeView object. This event is reported for information only and may not be controlled in any way using a callback function. Generating the event with ⎕NQ, or calling it as a method, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'ItemDblClick' or 342
[3] | Item number | Integer. The index of the item.
[4] | Mouse button | Integer.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key
[6] | Position | Integer. Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon), 4 (over the label), 8 (over the line), or 16 (over the symbol).


ItemDown Event

ItemDown Event 340

Applies to: ListView, TreeView

If enabled, this event is reported when the user depresses a mouse button when the mouse pointer is over an item in a ListView or TreeView object. This event is reported for information only and may not be controlled in any way using a callback function. Generating the event with ⎕NQ, or calling it as a method, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'ItemDown' or 340
[3] | Item number | Integer. The index of the item.
[4] | Mouse button | Integer.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key
[6] | Position | Integer. Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon), 4 (over the label), 8 (over the line), or 16 (over the symbol).


ItemUp Event

ItemUp Event 341

Applies to: ListView, TreeView

If enabled, this event is reported when the user releases a mouse button when the mouse pointer is over an item in a ListView or TreeView object. This event is reported for information only and may not be controlled in any way using a callback function. Generating the event with ⎕NQ, or calling it as a method, has no effect.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'ItemUp' or 341
[3] | Item number | Integer. The index of the item.
[4] | Mouse button | Integer.
[5] | Shift state | Integer. Sum of 1=shift key, 2=Ctrl key, 4=Alt key
[6] | Position | Integer. Indicates the position of the mouse-pointer within the item. It is either 2 (over the icon), 4 (over the label), 8 (over the line), or 16 (over the symbol).


Locator Event

Locator Event 80

Applies to: Locator

Description

If enabled, this event is generated when the user releases a mouse button, or presses any key (other than a cursor movement key) during a ⎕DQ on a Locator object.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Locator' or 80
[3] | Y | y-position of Locator after ⎕DQ
[4] | X | x-position of Locator after ⎕DQ
[5] | H | height of Locator after ⎕DQ
[6] | W | width of Locator after ⎕DQ
[7] | Mouse Button | number of the button which was released (0 if keystroke)
[8] | Keystroke | character scalar or vector containing the "Input Code" for the key that terminated the operation
[9] | Shift state | integer scalar


LostFocus Event

LostFocus Event 41

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, SubForm, TrackBar, TreeView

Description

If enabled, this event is generated when the user transfers the keyboard focus away from the object in question.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector (name of object that has lost the focus)
[2] | Event code | 'LostFocus' or 41
[3] | Object name | character vector (name of object that has received the focus)

If the focus is transferred to a window that is not part of the Dyalog APL GUI Interface, the third element is an empty vector.

The LostFocus event is generated after the focus has changed. The default processing is therefore to take no action. However, if you inhibit the event by returning a 0 from your callback function, the focus is automatically restored to the object that had lost it.


MouseDblClick Event

MouseDblClick Event 5

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Form, Group, Image, Label, List, ListView, Marker, MDIClient, Poly, ProgressBar, PropertyPage, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, Text, ToolBar, ToolButton, ToolControl, TreeView

Description

If enabled, this event is reported when the user presses and then releases a mouse button twice within a short space of time. The duration of this time is set through the Windows Control Panel.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MouseDblClick' or 5
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button double clicked (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.

If you enable MouseDown and MouseUp events in addition to MouseDblClick events, double-clicking a mouse button will generate the following sequence of events :

  1. MouseDown
  2. MouseUp
  3. MouseDblClick
  4. MouseUp


MouseDown Event

MouseDown Event 1

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Form, Group, Image, Label, List, ListView, Marker, MDIClient, Poly, ProgressBar, PropertyPage, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, Text, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

If enabled, this event is reported when the user presses one of the mouse buttons. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MouseDown' or 1
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

If you enable this event it is advisable that you ALSO enable MouseUp events. Otherwise, the slight delay in running your callback function will cause the down and up sequence to be reversed.

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.


MouseEnter Event

MouseEnter Event 6

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TreeView, UpDown

Description

If enabled, this event is reported when the user moves the mouse pointer into (over) an object. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MouseEnter' or 6
[3] | Object name | character vector (name of previous object)

This event is generated when the user moves the mouse pointer across the boundary and into an object. The first element of the event message is the name of the object over which the mouse pointer now resides. The 3rd element of the event message contains the name of the object that was previously under the mouse pointer, or is an empty vector if the mouse pointer was not previously over a Dyalog APL/W object.


MouseLeave Event

MouseLeave Event 7

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TreeView, UpDown

Description

If enabled, this event is reported when the user moves the mouse pointer out of an object. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MouseLeave' or 7
[3] | Object name | character vector (name of new object)

This event is generated when the user moves the mouse pointer across the boundary and away from an object. The first element of the event message contains the name of the object that previously contained the mouse pointer and which generated the event when it crossed its boundary. The third element contains the name of the object which now contains the mouse pointer or is an empty vector if the mouse pointer is not now over a Dyalog APL/W object.


MouseMove Event

MouseMove Event 3

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Form, Group, Image, Label, List, ListView, Marker, MDIClient, Poly, ProgressBar, PropertyPage, Rect, RichEdit, Scroll, Spinner, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, Text, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

If enabled, this event is reported when the user moves the mouse. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MouseMove' or 3
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button released (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.

Note that rapid movement of the mouse will not necessarily cause an overwhelming number of MouseMove events to be reported, as several small movements are automatically combined into one large one.


MouseUp Event

MouseUp Event 2

Applies to: ActiveXControl, Animation, Button, Calendar, Circle, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Ellipse, Form, Group, Image, Label, List, ListView, Marker, MDIClient, Poly, ProgressBar, PropertyPage, Rect, RichEdit, Scroll, SM, Spinner, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, Text, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

Description

If enabled, this event is reported when the user releases one of the mouse buttons. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MouseUp' or 3
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button released (number) 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down

In a graphical object (Circle, Ellipse, Image, Marker, Poly and Rect), the position of the mouse is reported relative to the top-left corner of its bounding rectangle.


MouseWheel Event

MouseWheelEvent 8

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, Spinner, Static, StatusBar, SubForm, TabBar, ToolBar, ToolControl, TreeView

If enabled, this event is reported when the user rotates the mouse wheel.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 9-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'MouseWheel' or 8
[3] | Y | y-position of mouse (number)
[4] | X | x-position of mouse (number)
[5] | Button | button pressed 1 = left button 2 = right button 4 = middle button
[6] | Shift State | sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down
[7] | Delta | integer
[8] | Lines | integer
[9] | Wheel Delta | integer

The value of Delta indicates the distance that the wheel is rotated, expressed in multiples or divisions of Wheel Delta. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user.

Lines specifies the number of lines to scroll when the wheel is rotated by I Mouse Delta unit. A value of ¯1 indicates that that a whole screen is to be scrolled. These values are defined by the user's preferences (Control Panel/Mouse)


MsgBtn1 Event

MsgBtn1 Event 61

Applies to: MsgBox

Description

If enabled, this event is reported when the user responds to a MsgBox object by clicking its first (leftmost) button. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'MsgBtn1' or 61


MsgBtn2 Event

MsgBtn2 Event 62

Applies to: MsgBox

Description

If enabled, this event is reported when the user responds to a MsgBox object by clicking its second (from the left) button. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'MsgBtn2' or 62


MsgBtn3 Event

MsgBtn3 Event 63

Applies to: MsgBox

Description

If enabled, this event is reported when the user responds to a MsgBox object by clicking its third (from the left) button. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows:

[1] | Object name | character vector
[2] | Event code | 'MsgBtn3' or 63


MDIActivate Event

MDIActivate Event 42

Applies to: SubForm

Description

This event is generated when the user activates a particular SubForm that is the child of an MDIClient. This occurs when the user clicks the left mouse button in the SubForm or selects it from the menu nominated for this purpose (see MDIMenu property). You may also call MDIActivate as a method.

Note that this event is reported after the action has taken place and cannot be disabled by returning 0 from a callback function or by setting its action code to ¯1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MDIActivate' or 42
[3] | Object name | character vector

Note that the 3rd element of the event message is either an empty vector or contains the name of the SubForm that was previously the active one in the same MDIClient.


MDIDeactivate Event

MDIDeactivate Event 43

Applies to: SubForm

Description

This event is generated when the user activates a different SubForm that is the child of an MDIClient, thereby de-activating the current one which causes this event. This occurs when the user clicks the left mouse button in another SubForm or selects it from the menu nominated for this purpose (see MDIMenu property). You may also call MDIDeactivate as a method.

Note that this event is reported after the action has taken place and cannot be disabled by returning 0 from a callback function or by setting its action code to ¯1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'MDIDeactivate' or 43
[3] | Object name | character vector

Note that the 3rd element of the event message contains the name of the SubForm that has now been made the active one in the same MDIClient.


PageActivate Event

PageActivate Event 360

Applies to: PropertyPage

If enabled, this event is reported when the user switches from one PropertyPage to another in a PropertySheet object. This event is reported by the new page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageActivate' or 360

You may select a particular page by calling PageActivate as a method, or by setting the PageActive or PageActiveObject property of the PropertySheet.


PageApply Event

PageApply Event 350

Applies to: PropertyPage

If enabled, this event is reported when the user clicks the Apply button in a PropertySheet. Note however, that the event is actually reported by each of its PropertyPage objects whose Changed property is currently 1, i.e. the event is reported by each of the pages that the user has changed.

The default processing for this event is to set the Changed property of the PropertyPage to 0. If you disable the event or return a 0 from a callback function, the Changed property is not reset. Note that the Apply button in a PropertySheet is active if the value of the Changed property of any of the PropertyPage objects is 1.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageApply' or 350


PageBack Event

PageBack Event 353

Applies to: PropertyPage

If enabled, this event is reported when the user switches from one PropertyPage to another in a Wizard PropertySheet object by clicking its Back button. This event is reported by the old page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageBack' or 353


PageCancel Event

PageCancel Event 351

Applies to: PropertyPage

If enabled, this event is reported when the user presses the Cancel button in a PropertySheet object and is reported by the current PropertyPage. This event is reported for information only and may not be disabled by a callback function. However, the operation will also generate a Close event reported by the PropertySheet itself that may be disabled by a callback.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageCancel' or 351


PageChanged Event

PageChanged Event 356

Applies to: PropertyPage

If enabled, this event is reported when the Changed property of a PropertyPage is altered by user action. It is not reported if you reset the Changed property using ⎕WS.

The Changed property is reset by two separate user actions. It is set to 1 when the user alters any of the controls on the PropertyPage. It is reset to 0 when the user clicks the Apply button, although this action may be disabled by a callback function on the PageApply event.

The PageChanged event is reported for information only and may not itself be disabled or affected by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageChanged' or 356
[3] | Changed value | New value for the Changed property (0 or 1).


PageDeactivate Event

PageDeactivate Event 361

Applies to: PropertyPage

If enabled, this event is reported when the user switches from one PropertyPage to another in a PropertySheet object. This event is reported by the old page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageDeactivate' or 361


PageFinish Event

PageFinish Event 355

Applies to: PropertyPage

If enabled, this event is reported when the user clicks the Finish button in a Wizard PropertySheet. This event is reported by current (last) PropertyPage. The event is reported for information only and cannot be affected by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageFinish' or 355


PageHelp Event

PageHelp Event 352

Applies to: PropertyPage

If enabled, this event is reported when the user clicks the Help button in a Wizard PropertySheet. This event is reported by current PropertyPage. The event is reported for information only and cannot be affected by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageHelp' or 352


PageNext Event

PageNext Event 354

Applies to: PropertyPage

If enabled, this event is reported when the user switches from one PropertyPage to another in a Wizard PropertySheet object by clicking its Next button. This event is reported by the old page after the page change has occurred and the page change may not be disabled by a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'PageNext' or 354


PreCreate Event

PreCreateEvent 534

Applies to: ActiveXControl

If enabled, this event is reported when an instance of an ActiveXControl is created. The PreCreate event is generated at the point the instance is made.

An ActiveXControl also generates a Create event, which occurs after the PreCreate event at the point when the host application requires the instance to appear visually.

Note that at the time that PreCreate is generated, the ActiveXControl does not have a window.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object namecharacter vector
[2] | Event name or code'PreCreate' or 534


Protected Event

Protected Event 470

Applies to: RichEdit

If enabled, this event is reported when the user attempts to alter protected text in a RichEdit. See CharFormat property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Protected' or 470


Retracting Event

Retracting Event 304

Applies to: Grid, TreeView

If enabled, this event is reported by a Grid or a TreeView object just before it is about to retract to hide the children of the current item.

In a Grid, this occurs when the user clicks the picture or tree line in the row title.

In a TreeView, this occurs when the user double-clicks the item label or clicks in the button or on the tree line to the left of the item label, when the item is in its expanded state.

The default processing for the event is to retract the tree at the corresponding point.

You may disable the retract operation by setting the action code for the event to ¯1. You may also prevent the retraction from occurring by returning 0 from a callback function. You may retract Grid a or a TreeView dynamically under program control by calling Retracting as a method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Retracting' or 304
[3] | Item number | Integer. The index of the item.


Scroll Event

Scroll Event 37

Applies to: Scroll, TrackBar

Description

If enabled, this event is generated when the user attempts to move the thumb in a scrollbar. This can be done in one of three ways :

  1. dragging the thumb.
  2. clicking in one of the "arrow" buttons situated at the ends of the scrollbar. This is termed a small change, the size of which is defined by Step[1].
  3. clicking in the body of the scrollbar. This is termed a large change, the size of which is defined by Step[2].

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Scroll' or 37
[3] | Scroll Type | numeric
[4] | Position | numeric

The value of Scroll Type is 0 (drag), 1 or ¯1 (small change) or 2 or ¯2 (large change). The sign indicates the direction.

The value of Position is the new (requested) position of the thumb. Notice however, that the event is generated before the thumb is actually moved. If your callback function returns a scalar 0, the position of the thumb will remain unaltered.


Select Event

Select Event 30

Applies to: ActiveXControl, Bitmap, Button, Calendar, Circle, Clipboard, Combo, ComboEx, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuItem, Metafile, Poly, Printer, ProgressBar, Rect, RichEdit, Scroll, Spinner, Static, StatusBar, StatusField, SubForm, TabBar, TabBtn, TabButton, Text, ToolBar, ToolButton, TrackBar, TreeView, UpDown

Description

For a Button with Style 'Push' this event is generated when the user "pushes" the button. This can be done by clicking the left mouse button, or by pressing the Enter key or the space bar when the Button has the focus. The Select event can also be generated when the Button does not have the focus, by pressing the Enter key when its Default property is 1 or by pressing the ESC key when its Cancel property is 1.

For a Button with Style 'Radio' or 'Check' this event is generated when the user toggles the button from one state to another. This can be achieved by clicking the left mouse button or by pressing the space bar when the Button has the focus.

For a Combo or List object, a Select event is generated when the user selects an item from the list, whether by pressing the arrow keys or by clicking the left mouse button.

For a MenuItem, a Select event is generated when the user chooses the item.

For all other objects, this event is generated when the user presses the keys associated with the object’s Accelerator property.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Select' or 30


SelDateChange Event

SelDateChangeEvent 265

Applies to: Calendar

If enabled, this event is reported when the user changes the date, or range of dates, that is selected in a Calendar object. This event is also reported when the Calendar object is scrolled and the selection changes automatically to another month.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'SelDateChange' or 265
[3] | First Date | an integer (IDN)
[4] | Last Date | an integer (IDN)


SetColSize Event

SetColSize Event 176

Applies to: Grid, ListView

Description

If enabled, this event is reported when the user changes the width of a column in a Grid or ListView object, or changes the width of the row titles in a Grid. This may be done by dragging a border with the mouse or by double-clicking over a border. In the former case, the default action is to adjust the width of the appropriate column or the width of the row title area to the size selected by the user. In the latter case, the default action is to adjust the width to the maximum required to display all the data.

In either case, you can disable the default action by setting the event action code to ¯1 or you can selectively prevent a particular resize operation from taking place by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'SetColSize' or 176
[3] | Column number | Integer. This is sensitive to the index origin, ⎕IO, but is ¯1 if the user has resized the row titles in a Grid.
[4] | Width | Integer containing the value of the (new)column width. This is ¯3 if the user has double-clicked to request automatic width adjustment.
[5] | Undo flag | 0 or 1

You can resize a column or resize the row titles under program control by calling SetColSize as a method. If you specify ¯1 as the Width parameter, the column will be resized to its default width .. If you specify a value of ¯2 the column will be resized to fit the data. The following expression will size the first NCOLS columns of a Grid called F.G to fit the data and the column titles:

      {F.G.SetColSize⍵ ¯3}¨⍳NCOLS

The Undo flag is applicable only to a Grid object and is always 1 if the event was generated by the user.


SetItemPosition Event

SetItemPosition Event 322

Applies to: ListView

If enabled, this event is reported when the user drag-drops an item within a ListView object. This operation may be disabled by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 7-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'SetItemPosition' or 322
[3] | Item number | Integer. The index of the item.
[4] | Y-position | Integer. New y-position of the item.
[5] | X-position | Integer. New x-position of the item.
[6] | Button number | Integer. The mouse button used to perform the drag.
[7] | Shift State | Integer: Sum of shift key codes (number) 1 = Shift key is down 2 = Ctrl key is down 4 = Alt key is down


SetRowSize Event

SetRowSize Event 175

Applies to: Grid

Description

If enabled, this event is reported when the user changes the height of a row or changes the height of the column titles. This may be done by dragging a border with the mouse or by double-clicking over a border. In the former case, the default action is to adjust the height of the appropriate row or the height of the column title area to the size selected by the user. In the latter case, the default action is to adjust the height to the maximum required to display all the data.

In either case, you can disable the default action by setting the event action code to ¯1 or you can selectively prevent a particular resize operation from taking place by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'SelRowSize' or 175
[3] | Row number | Integer. This is sensitive to the index origin, ⎕IO, but is ¯1 if the user has resized the column titles.
[4] | Height | Integer containing the value of the (new) row height. This is ¯3 if the user has double-clicked to request automatic height adjustment.
[5] | Undo flag | 0 or 1

You can resize a row or resize the column titles under program control by calling SetRowSize as a method. If you specify ¯1 as the Height parameter, the row will be resized to its default height .. If you specify a value of ¯2 the row will be resized to fit the data. The following expression will set the heights of first NROWS rows of a Grid called F.G to fit the data and the row titles.

      {F.G.SetRowSize⍵ ¯3}¨⍳NROWS

The Undo flag is always 1 if the event was generated by the user.


SetSpinnerText Event

SetSpinnerText Event 421

Applies to: Spinner

If enabled, this event is generated when the user clicks one of the spin buttons in a Spinner object. The event is reported after the value of the Thumb property has been updated but before the Text property has been changed. You may use this event to set the text in the Spinner dynamically instead of relying on it being updated automatically.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'SetSpinnerText' or 421
[3] | Thumb value | Integer. The new value of the Thumb property resulting from the user pressing one of the spin buttons.
[4] | Text | The text that is about to be put into the edit field.

The SetSpinnerText event is designed to allow you to dynamically set the text in the Spinner in response to a spin button. It might be used in circumstances where the set of items you wish to present to your user is not predictable in advance.


SetWizard Event

SetWizard Event 365

Applies to: PropertyPage

If enabled, this event is reported when the user has clicked the Next or Back button in a PropertySheet with Style 'Wizard'. This action also generates PageNext (or PageBack) and PageDeactivate and PageActivate events. The SetWizard event is the final event to be reported as a result of this action, and is the only one that is affected by the result of a callback function. The event message reports the active/inactive state of the 3 page changing buttons (Back, Next and Finish) that should result from the action. Note that the Next and Finish buttons occupy the same position and are mutually exclusive.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'SetWizard' or 365
[3] | Active state Back | 0 or 1
[4] | Active state Next | 0 or 1
[5] | Active state Finish | 0 or 1
[6] | Finish caption | character vector

You may alter the state of the buttons by changing elements [3-5] of the event message and returning it as a result of your callback. You may also set the state of the buttons at any time by calling SetWizard as a method.

When the event is reported by ⎕DQ, element 6 is an empty vector. If you modify it and return it in the result of a callback, the caption of the Finish button changes accordingly and the Back and Next buttons disappear. This happens regardless of the states you specified in elements [3-5].


ShowComment Event

ShowComment Event 223

Applies to: Grid

If enabled, a Grid will generate a ShowComment event when the user rests the mouse pointer over a commented cell. You may use this event to modify the appearance of the comment dynamically.

The event message reported as the result of ⎕DQ or supplied as the right argument to your callback function is an 8-element vector containing the following:

[1] | Object name | character vector
[2] | Event name or code | 'ShowComment' or 223
[3] | Cell row | integer
[4] | Cell column | integer
[5] | Comment text | character vector
[6] | Window height | integer, pixels
[7] | Window width | integer, pixels
[8] | Tip behaviour flag | (1 = yes; 0 = no)

A callback function may modify the standard behaviour. You may prevent the comment from being displayed by returning 0 as the result of the callback. Alternatively, you may modify the comment text, its window size, or its pop-up behaviour by changing the appropriate element(s) of the event message and returning the new event message as the result.

Note that if the comment window relates to a row or column title, the value reported in element [3] or [4] of the event message is ¯1.

You may display the comment associated with a particular cell under program control by calling ShowComment as a method. In this case, only the Cell row and Cell column parameters need be specified. If however, you wish to override the comment text and/or its window size, you may do so (temporarily) by specifying the corresponding parameters. By default, a comment displayed under program control does not exhibit tip behaviour but remains visible until it is explicitly removed using the HideComment method.

Note that a comment will only be displayed if the specified cell is marked as a commented cell.


Spin Event

Spin Event 420

Applies to: Spinner, UpDown

If enabled, this event is generated when the user clicks one of the spin buttons in a Spinner object. The event is reported before the value of the Thumb property has been updated. You may disable the operation of the spin buttons by disabling this event. You may selectively prevent the user selecting a particular value by returning 0 from a callback function. You may also return a modified event message as a result in order to set the Thumb property to a different value.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Spin' or 420
[3] | Thumb value | Integer. The new value of the Thumb property resulting from the user pressing one of the spin buttons.
[4] | Adjustment | Integer. The amount by which the new value of the Thumb differs from its previous value.


Splitting Event

splittingEvent 281

Applies to: Splitter

If enabled, this event is reported while a Splitter object is being dragged, between a StartSplit and an EndSplit. This event is only reported if full-drag is enabled.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 6-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'Splitting' or 281
[3] | Y | y-position of top left corner
[4] | X | x-position of top left corner
[5] | H | height of the Splitter
[6] | W | width of the Splitter

See also StartSplit, EndSplit.


StartSplit Event

StartSplitEvent 280

Applies to: Splitter

If enabled, this event is reported when the user depresses the left mouse button over a Splitter object to signify the beginning of a drag operation.

This event is reported for information alone. You may not disable or nullify the event by setting the action code for the event to ¯1 or by returning 0 from a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'StartSplit' or 280

See also EndSplit, Splitting.


StateChange Event

StateChange Event 35

Applies to: Form, SubForm

Description

This event is generated by a Form or SubForm when the user attempts to change the State of a Form, by minimising it, maximising it, or restoring it from a minimised or maximised state. The event is reported before the window changes state. You may prevent the state change by disabling the event (action code ¯1) or by returning a 0 result from an attached callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'StateChange' or 35
[3] | Window state | 0 (about to be restored) 1 (about to be minimised) 2 (about to be maximised)


SysColorChange Event

SysColorChange Event 134

Applies to: Root

Description

If enabled, this event is reported when the user or another application updates the system colour palette. The event is reported after the change has taken place and cannot be disabled or inhibited in any way. If you want your application to respond to colour palette changes, this event gives you the opportunity of doing so.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'SysColorChange' or 134


TCPAccept Event

TCPAccept Event 371

Applies to: TCPSocket

If enabled, this event is reported when a client connects to a server TCPSocket object.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPAccept as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPAccept' or 371
[3] | Socket handle | an integer

The socket handle reported by this event is the socket handle for the original listening socket that was associated with the TCPSocket before the client connected.

If you want your server to remain available for other clients, you must create a new TCPSocket object in a callback function attached to this event. The new TCPSocket object must be created by cloning the original listening socket. This is done by specifying the socket handle as the value of its SocketNumber property. You may not specify any other properties (except Event and Data) in the ⎕WC statement that creates the new clone object.

The default processing for this event is to close the socket handle reported by the 3rd element of the event message unless it has been associated with a new TCPSocket object by the callback function as described above. You may prevent this from occurring by returning 0 from a callback function. This may be necessary in a multithreaded application.

You may not call TCPClose as a method or generate this event artificially using ⎕NQ.


TCPClose Event

TCPClose Event 374

Applies to: TCPSocket

If enabled, this event is reported when the remote end of a TCP/IP connection breaks the connection.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPClose as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPClose' or 374


TCPConnect Event

TCPConnect Event 372

Applies to: TCPSocket

If enabled, this event is reported when a server accepts the connection of a client TCPSocket object and is reported by the client.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPConnect as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPConnect' or 372


TCPError Event

TCPError Event 370

Applies to: TCPSocket

This event is generated when a fatal TCP/IP error occurs and is reported by a TCPSocket object.

The default processing for this event is to display a message box containing details of the TCP/IP error. You may disable the display of this message box by setting the action code for the event to ¯1 or by returning 0 from a callback function attached to it.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPError' or 370
[3] | Error code | a number
[4] | Error text | a character vector


TCPGotAddr Event

TCPGotAddr Event 377

Applies to: TCPSocket

If enabled, this event is reported when a host name (specified by the RemoteAddrName or LocalAddrName property) is resolved to an IP address.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPGotAddr as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPGotAddr' or 377

Note that the IP address is not reported in the event message but may be obtained from RemoteAddr or LocalAddr as appropriate.


TCPGotPort Event

TCPGotPort Event 378

Applies to: TCPSocket

If enabled, this event is reported when a port name (specified by the RemotePortName or LocalPortName property) is resolved to a port number.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPGotPort as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPGotPort' or 378

Note that the port number is not reported in the event message but may be obtained from RemotePort or LocalPort as appropriate.


TCPReady Event

TCPReady Event 379

Applies to: TCPSocket

If enabled, this event is reported when the TCP/IP buffers are free and there is no data waiting to be sent in the internal APL queue.

This event is provided to enable you to control the transmission of a large amount of data that cannot be handled in a single call to TCPSend.

The amount of data that the system can handle in one go is limited by TCP/IP buffers, the speed of the network, and the amount of Windows memory and disk space available for buffering.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. However, you may call TCPReady as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPReady' or 379


TCPRecv Event

TCPRecv Event 373

Applies to: TCPSocket

If enabled, this event is reported when data is received by a TCPSocket object.

You may not disable or nullify the operation by setting the action code for the event to ¯1 or by returning 0 from a callback function. You may also not call TCPRecv as a method or generate this event artificially using ⎕NQ.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 5-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'TCPRecv' or 373
[3] | Data | the data received
[4] | IP address | character vector
[5] | Port number | integer

Elements [4-5] refer to the IP address and port number of the remote process that sent the data.

If the SocketType is 'Stream', this information will be identical to the values of the RemoteAddr and RemotePort respectively.

If the SocketType is 'UDP' and there is potentially more than one partner sending you data, the IP address and port number information provided by the TCPRecv event is more reliable than the current values of RemoteAddr and RemotePort as these may already have changed.


ThumbDrag Event

ThumbDrag Event 440

Applies to: TrackBar

If enabled, this event is generated when the user drags the thumb in a TrackBar object. The event is reported after the value of the Thumb property has been updated and is reported continuously as the thumb is dragged. You may not disable this event or alter its effect with a callback function.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 3-element vector as follows :

[1] | Object name | character vector
[2] | Event name or code | 'ThumbDrag' or 440
[3] | Thumb value | Integer. The new value of the Thumb property resulting from the user dragging the thumb.


Timer Event

Timer Event 140

Applies to: Timer

Description

This event is generated at regular intervals by a Timer object and is typically used to fire a callback function to perform a task repeatedly. Returning a 0 from a callback function attached to a Timer event has no effect. The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2 element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'Timer' or 140


VScroll Event

VScroll Event 38

Applies to: Form, SubForm

Description

If enabled, this event is generated when the user attempts to move the thumb in a vertical scrollbar in a Form or SubForm. This event occurs only in a Form whose VScroll property is set to ¯1 and is distinct from the Scroll event which is generated by a Scroll object. The event may be generated in one of three ways :

  1. dragging the thumb
  2. clicking in one of the "arrow" buttons situated at the ends of the scrollbar. This is termed a small change, the size of which is defined by Step[1].
  3. clicking in the body of the scrollbar. This is termed a large change, the size of which is defined by Step[2].

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'VScroll' or 38
[3] | Scroll Type | numeric
[4] | Position | numeric

The value of Scroll Type is 0 (drag), 1 or ¯1 (small change) or 2 or ¯2 (large change). The sign indicates the direction.

The value of Position is the new (requested) position of the thumb. Notice however that the event is generated before the thumb is actually moved. If your callback function returns a scalar 0, the position of the thumb will remain unaltered.


WinIniChange Event

WinIniChange Event 133

Applies to: Root

Description

If enabled, this event is reported when another application changes relevant registry settings using the standard API calls. The event is reported after the change has taken place and cannot be disabled or inhibited in any way. If your application depends upon registry settings, this event gives you the opportunity of refreshing these parameters if they are changed.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'WinIniChange' or 133


Abort Event

Abort Method 103

Applies to: Printer

Description

This method causes the print job to be aborted and all pending output to be discarded.

The Abort method is niladic.

If you attach a callback function to this method and have it return a value of 0, the print job will continue.


AddChildren Event

AddChildren Method 310

Applies to: TreeView

This method is used to add child items to an item in a TreeView object

The argument to AddChildren is a 3, 4 or 5 element array as follows:

[1] | Item number | Integer.
[2] | New items | Vector of character vectors.
[3] | Depth vector | Integer vector.
[4] | Picture vector | Integer vector.
[5] | Selected picture vector | Integer vector.

Item number specifies the index of the item to which the child items are to be added.

New items is a vector of character vectors containing the labels for the new child items.

Depth vector is an integer vector specifying the depth of each of the new items relative to the parent item to which they are being added. The first element of this array must be 0.

Picture vector and Selected picture vector are optional and specify values of ImageIndex and SelImageIndex respectively for each of the new items.

The result is the index at which the first new item has been inserted.


AddComment Event

AddComment Method 220

Applies to: Grid

This method is used to add a new comment to a Grid.

The argument to AddComment is a 3, 4 or 5 element array as follows:

[1] | Row | integer
[2] | Column | integer
[3] | Comment text | character array
[4] | Height in pixels | integer
[5] | Width in pixels | integer

For example, the following statement associates a comment with the cell at row 2, column 1; the text of the comment is “Hello”, and the size of the comment window is 50 pixels (high) by 60 pixels (wide).

      F.G.AddComment 2 1 'Hello' 50 60

Note that if you specify a row number of ¯1, the comment is added to the corresponding column title. Similarly, if you specify a column number of ¯1, the comment is added to the corresponding row title.

The height and width of the comment window, specified by the last 2 elements of the argument are both optional. If the cell already has an associated comment, the new comment replaces it.

You can use a Dynamic Function to add several comments in one statement; for example:

      (1 2)(2 3){F.G.AddComment ⍺,⊂⍵}¨'Hello' 'Goodbye'

Note that just before the comment is displayed, the Grid generates a ShowComment event which gives you the opportunity to (temporarily) change the text and/or window size of a comment dynamically.

The comment text specified by the 5th element of the argument to ⎕NQ must be a simple character scalar, vector, matrix or vector of vectors. Text specified by a simple character vector will be wrapped automatically if necessary. A matrix or vector of vectors may be used to explicitly specify multi-line text. If the array is a vector whose first element is an opening brace ({), the text is assumed to be in rich-text format (RTF) and is displayed accordingly. Note that there is no way for the user to scroll the text in the comment window and it is entirely your responsibility to ensure that the size of the window is appropriate for its contents.


AddItems Event

AddItems Method 308

Applies to: TreeView

This method is used to add items to a TreeView object

This method is used to add items to a TreeView object

The argument to AddItems is a 3,4 or 5-element array as follows:

[1] | Item number | Integer.
[2] | New items | Vector of character vectors.
[3] | Depth vector | Integer vector.
[4] | Picture vector | Integer vector.
[5] | Selected picture vector | Integer vector.

Item number specifies the index of the item to which the child items are to be added.

New items is a vector of character vectors containing the labels for the new child items.

Depth vector is an integer vector specifying the depth of each of the new items relative to the parent item to which they are being added. The first element of this array must be 0. This element may be omitted. If so, it is assumed to be all 0s.

Picture vector and Selected picture vector are optional and specify values of ImageIndex and SelImageIndex respectively for each of the new items.

The new items are inserted with the first one being placed at the same level in the hierarchy as the item specified in element [1].

The result is an integer that reports the index position at which the first of the new items has been inserted.


Animate Method

AnimateMethod 29

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, TabControl, ToolBar, ToolControl, TrackBar, TreeView, UpDown

Windows 2000 only

The Animate method enables you to produce special effects when showing or hiding objects. There are three types of animation: roll, slide, and alpha-blended fade.

The argument to Animate is a 1 or 2-element array as follows:

[1] | Effects | integer
[2] | Play time | integer

The value of the Effects parameter is the sum of the following flags:

Flag | Value | Description
AW_HOR_POSITIVE | 1 | Animates the window from left to right. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_HOR_NEGATIVE | 2 | Animates the window from right to left. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_VER_POSITIVE | 4 | Animates the window from top to bottom. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_VER_NEGATIVE | 8 | Animates the window from bottom to top. This flag can be used with roll or slide animation. It is ignored when used with the AW_CENTER flag.
AW_CENTER | 16 | Makes the window appear to collapse inward if being hidden or expand outward if being displayed
AW_SLIDE | 262144 | Uses slide animation. By default, roll animation is used. This flag is meaningless on its own but is ignored when used with the AW_CENTER flag.
AW_BLEND | 524288 | Uses a fade effect. This flag can be used only for a Form.

The Playtime parameter is optional and specifies the length of time over which the animation is played in milliseconds. The default value depends upon the animation but is typically 200 milliseconds.


AnimClose Method

AnimCloseMethod 291

Applies to: Animation

The AnimClose method closes the AVI file that is currently loaded in an Animation object. The display is reset to the object's background colour.

The AnimClose method is niladic.


AnimOpen Method

AnimOpenMethod 290

Applies to: Animation

The AnimOpen method opens an AVI file in an Animation object.

The argument to AnimOpen is a 1 or 2-element array as follows:

[1] | File | character vector
[2] | Resource id | integer

If a single element is specified, it represents the name of a .AVI file.

If 2 elements are specified, the first element specifies the name of a DLL or EXE and the second element identifies the particular AVI resource stored in that file. The identifier may be its name (a character string) or its resource id (a non-zero positive integer).

If the AutoPlay property is set to 1, the animation will play immediately. Otherwise, only the first frame will be displayed.

Note that the Animation object can only play AVI files or resources that have no sound and can only display uncompressed AVI files or .AVI files that have been compressed using Run-Length Encoding (RLE). If you attempt to open an inappropriate AVI file, the operation will fail with a DOMAIN ERROR and the following message will be displayed in the Status Window:

AVI file includes sound data or is in a format not supported by the Animation object


AnimPlay Method

AnimPlayMethod 292

Applies to: Animation

The AnimPlay method plays an AVI clip in an Animation object.

The argument to AnimPlay is a 3-element array as follows:

[1] | Repeat | integer
[2] | From | integer
[3] | To | integer

Repeat specifies the number of times the clip is repeated. A value of -1 causes the clip to be repeated indefinitely.

From is a 0-based index of the frame where playing begins and must be less than 65536. A value of zero means begin with the first frame in the AVI clip

To is a 0-based index of the frame where playing ends and must be less than 65536. A value of -1 means end with the last frame in the AVI clip

The last frame remains displayed until the clip is unloaded using AnimClose or until another clip is loaded.


AnimStop Method

AnimStopMethod 293

Applies to: Animation

The AnimStop method stops playing an AVI clip in an Animation object.

AnimStop is niladic.

The last frame remains displayed until the clip is unloaded using AnimClose or until another clip is loaded.


Browse Method

BrowseMethod 585

Applies to: OCXClass, OLEClient

The Browse method is retained for compatibility with previous versions of Dyalog APL, but is no longer relevant and has no effect.


CancelToClose Event

CancelToClose Method 367

Applies to: PropertySheet

This method is used to change the buttons in a PropertySheet object. Its effect is to disable the Cancel button and, if the Style of the PropertySheet is 'Standard', it changes the text of the OK button to “Close”. There is no result.

The CancelToClose method is niladic.


CellFromPoint

CellFromPoint Method 200

Applies to: Grid

This method converts from Grid co-ordinates to cell co-ordinates.

The argument to CellFromPoint is a 2-element array as follows:

[1] | y-coordinate | number in Grid co-ordinates
[2] | x-coordinate | number in Grid co-ordinates

The result is a 2-element vector containing the following.,

[1] | y-coordinate | number in cell co-ordinates
[2] | x-coordinate | number in cell co-ordinates


ChooseFont Event

ChooseFont Method 240

Applies to: ActiveXControl, Button, Calendar, Combo, ComboEx, DateTimePicker, Edit, Font, Form, Grid, Group, Label, List, ListView, PropertyPage, PropertySheet, RichEdit, Root, Spinner, Static, StatusBar, SubForm, TabBtn, Text, TipField, TreeView

This method is used to display the standard Windows font selection dialog box.

The argument to ChooseFont is ⍬ or a 1 or 2-element array as follows:

[1] | Printer name | character scalar or vector.
[2] | Modify flag | 0 or 1.

If the argument is <—> or the first element of the argument is '', the user is offered a list of fonts suitable for use on the screen. If not, the user is offered a choice of fonts suitable for the specified Printer object. If you omit the 2nd element, the modify flag defaults to 0.

The dialog box is initialised with the properties of the Font object specified in the first element of the event message.

When the user presses the “OK” button, the “Cancel” button or closes the dialog box, ChooseFont terminates. Its result is either 0 (user pressed “Cancel”) or a 2-element vector. In the latter case, the first element is an 8-element array that describes the selected font as described below, and the second element is a 3-element RGB colour vector.

[1] | Face name of selected font (character vector)
[2] | Character height in pixels (integer)
[3] | Fixed width or not (boolean)
[4] | Italic or not (boolean)
[5] | Underline or not (boolean)
[6] | Weight (integer)
[7] | Angle of rotation (integer)
[8] | Character set (see CharSet)

If the modify flag was 1, the Font object is redefined to match the user’s selections and all the objects that reference the Font are redrawn.


CloseUp Event

CloseUpEvent 46

Applies to: DateTimePicker

If enabled, this event is reported by a DateTimePicker object just before the drop-down calendar is hidden. It applies only if the Style of the DateTimePicker is 'Combo'.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object | ref or character vector
[2] | Event name or code | 'CloseUp' or 46

This event is reported for information only and cannot be disabled or modified in any way.


ColChange Event

ColChange Method 159

Applies to: Grid

Description

This method is used to change the data in a column of a Grid.

The argument to ColChange is a 2-element array as follows:

[1] | Column number | integer
[2] | Column data | array

Note that the Column data must be a scalar or a vector whose length is equal to the number of rows in the Grid. Its elements may be scalar numbers, character vectors or matrices.


ColSorted Method

ColSortedMethod 174

Applies to: Grid

This method is used to specify that an image is to be displayed in a Grid column title to indicate the column has been sorted.

The argument to ColSorted is a 2-element array as follows:

[1] | Column number | Integer.
[2] | Sorted state | Integer. -1 = Sorted Down 0 = Unsorted 1 = Sorted Up

The column title for the appropriate column is redrawn to include the appropriate image.

If you wish to use your own images, you may specify them using the ColSortImages property.

      'F'⎕WC'Form' 'Grid: ColSorted Method'
      'F.G'⎕WC'Grid'('Posn' 0 0)(100 100)
      F.G.Values←(COUNTRIES,POPULATION,[1.5]AREA)
      F.G.ColTitles←'Country' 'Population' 'Area'
      F.G.TitleWidth←0

      F.G.Values←Values[⍋Values[;2];])
      F.G.ColSorted 2 1

      F.G.(Values←Values[⍒↑Values[;1];])
      F.G.ColSorted 2 0
      F.G.ColSorted 1 ¯1


DateToIDN Method

DateToIDNMethod 264

Applies to: Calendar, DateTimePicker, Root

This method is used to convert a date from ⎕TS format into an IDN suitable for use in a Calendar object.

The argument to DateToIDN is a 3-element array as follows:

[1] | Year | Integer
[2] | Month | Integer
[3] | Day | Integer

DateToIDN will also accept a single enclosed argument containing these values. In either case, if you specify more than 3 numbers, excess elements they will be ignored.

Examples

      F.C.DateToIDN 1998 9 11
36048
      F.C.DateToIDN ⊂1998 9 11
36048
      F.C.DateToIDN ⎕TS
36048
      F.C.DateToIDN,⎕TS
36048


DeleteChildren Event

DeleteChildren Method 311

Applies to: TreeView

This method is used to delete child items from a parent item in a TreeView object.

The argument to DeleteChildren is a scalar or 1 element array as follows:

[1] Item number Integer.

Item number specifies the index of the parent item from which the child items are to be removed.

The result is an integer that indicates the number of children that have been removed from the parent item.


DeleteItems Event

DeleteItems Method 309

Applies to: TreeView

This method is used to delete items from a TreeView object.

The argument to DeleteItems is a 2-element array as follows:

[1] | Item number | Integer.
[2] | Number of Items | Integer.

Item number specifies the index of the first item to be removed.

Number of items specifies the number of items to be removed and refers to those items at the same level in the TreeView hierarchy as the Item number. Number of items is optional and defaults to 1.

Note that any children of these items will also be removed.

The result is an integer that indicates the total number of items, including children, that have been removed from the TreeView.


DelCol Event

DelCol Method 155

Applies to: Grid

Description

This method is used to delete a specified column from a Grid object.

The argument to DelCol is a 1 or 2-element vector as follows:

[1] | Column number | number of the column (integer) to delete
[2] | Undo flag | 0 or 1 (optional; default 0)

If the Undo flag 1, the column may subsequently be restored by invoking the Undo method. If the Undo flag is omitted or is 0, the operation may not be undone.


DelComment Event

DelComment Method 221

Applies to: Grid

This method is used to delete a comment from a Grid.

The argument to DelComment is a 2 array as follows or ⍬:

[1] | Row | integer
[2] | Column | integer

For example, the following expression removes the comment associated with the cell at row 2, column 1.

      F.C.DelComment 2 1

Note that to delete a comment associated with a row or column title, the appropriate element in the argument should be ¯1.

If the argument is ⍬, all comments are deleted.


DelRow Event

DelRow Method 154

Applies to: Grid

Description

This method is used to delete a specified row from a Grid object.

The argument to DelRow is a 1 or 2-element array as follows:

[1] | Row number | number of the row (integer) to delete
[2] | Undo flag | 0 or 1 (optional; default 0)

If the Undo flag is 1, the column may subsequently be restored by invoking the Undo method. If the Undo flag is omitted or is 0, the operation may not be undone.


Detach Method

Detach Method 270

Applies to: ActiveXContainer, ActiveXControl, Animation, Bitmap, BrowseBox, Button, Calendar, Circle, Clipboard, ColorButton, Combo, ComboEx, CoolBand, CoolBar, Cursor, DateTimePicker, Edit, Ellipse, FileBox, Font, Form, Grid, Group, Icon, Image, ImageList, Label, List, ListView, Locator, Marker, MDIClient, Menu, MenuBar, MenuItem, Metafile, MsgBox, OCXClass, OLEClient, OLEServer, Poly, Printer, ProgressBar, PropertyPage, PropertySheet, Rect, RichEdit, Scroll, Separator, SM, Spinner, Splitter, Static, StatusBar, StatusField, SubForm, SysTrayItem, TabBar, TabBtn, TabButton, TabControl, TCPSocket, Text, Timer, TipField, ToolBar, ToolButton, ToolControl, TrackBar, TreeView, UpDown

This method is used to detach the GUI component from an object without losing the functions, variables and sub-namespaces that it may contain.

The Detach method is niladic.

The effect of this method is to remove the GUI component associated with the named object, leaving behind a plain namespace of the same name. All non-GUI child objects are retained. GUI child objects are either destroyed, or similarly converted to plain namespaces depending upon the values of their KeepOnClose properties.


DuplicateColumn Method

DuplicateColumn Method 178

Applies to: Grid

Description

This method is used to duplicate a column in a Grid object.

The argument to DuplicateColumn is a 2, 3, 4 or 5-element vector as follows:

[1] | Source Column number | number of the column (integer) to be duplicated
[2] | Target Column number | new column number (integer)
[3] | Comment flag | 0 or 1 (optional, default 1)
[4] | Lock flag | 0 or 1 (optional, default 1)
[5] | Undo flag | 0 or 1 (optional; default 0)

If the Comment flag is 1 (the default), any Comments associated with cells in the source column are duplicated in the target column.

If the Lock flag is 1 (the default), the lock state of the column is duplicated; otherwise, the new column is not locked.

If the Undo flag is 1, the column may subsequently be restored by invoking the Undo method. If this element is omitted or is 0, the operation may not be undone.


DuplicateRow Method

DuplicateRow Method 177

Applies to: Grid

Description

This method is used to duplicate a row in a Grid object.

The argument to DuplicateRow is a 2, 3, 4 or 5-element vector as follows:

[1] | Source Row number | number of the row (integer) to be duplicated
[2] | Target Row number | new row number (integer)
[3] | Comment flag | 0 or 1 (optional, default 1)
[4] | Lock flag | 0 or 1 (optional, default 1)
[5] | Undo flag | 0 or 1 (optional; default 0)

If the Comment flag is 1 (the default), any Comments associated with cells in the source row are duplicated in the target row.

If the Lock flag is 1 (the default), the lock state of the row is duplicated; otherwise, the new row is not locked.

If the Undo flag is 1, the row may subsequently be restored by invoking the Undo method. If this element is omitted or is 0, the operation may not be undone.


FileRead Event

FileRead Method 90

Applies to: Bitmap, Cursor, Icon, Metafile, RichEdit

Description

This method causes the object to be recreated from the file named in its File property.

The FileRead method is niladic.

[1] | Object name | character vector
[2] | Event code | 'FileRead' or 90

If you attach a callback function to this event and have it return a value of 0, the object will not be recreated from file.


FileWrite Event

FileWrite Method 91

Applies to: Bitmap, Cursor, Icon, Metafile, RichEdit

Description

This method causes the object to be written to the file named in its File property.

The FileRead method is niladic.

If you attach a callback function to this event and have it return a value of 0, the object will not be written to file. You could use this to avoid overwriting an existing file.


Flush Event

Flush Method 135

Applies to: Root

Description

This method forces any objects that have been created but not yet shown to be displayed. Normally, Dyalog APL/W buffers the display of new objects unless they are being created by a callback function. This event can be used to override the bufferring.

The Flush method is niladic.


GetBuildID Method

GetBuildIDMethod 192

Applies to: Root

This method is used to obtain the Build ID of a Dyalog APL executable.

The argument to GetBuildID is ⍬ or a single item as follows:

[1] File name character vector

The (shy) result is an 8-element character vector of hexadecimal digits that represents the Build ID.

If the argument is ⍬, the build id is that of the current version of Dyalog APL that is running the expression.

Note that although this method is designed to uniquely identify different versions of Dyalog APL by its check-sum, it may be used to obtain a check-sum for any arbitrary file.

Examples:

      GetBuildID ⍬
38091b76
      GetBuildID 'E:\DYALOG81\DYALOG.EXE'
cbf0d376
      GetBuildID 'C:\AUTOEXEC.BAT'
4a29334d

Note that if the file does not exist, the result is 00000000.


GetCellRect

GetCellRect Method 201

Applies to: Grid

This method returns the rectangle associated with a particular cell in a Grid.

The argument to GetCellRect is a 2-element vector as follows:

[1] | Row | integer
[2] | Column | integer

The result is a 2-element nested vector. The first element contains the y and x-coordinate of the top-left corner of the cell. The second element contains the height and width of the cell.

The result is reported in terms of the coordinate system of the Grid object.


GetCommandLine Method

GetCommandLineMethod 145

Applies to: Root

The GetCommandLine method returns the command line that was used to start the current Dyalog APL session or application.

The GetCommandLine method is niladic.

The result is a character vector. For example:

      GetCommandLine
"C:\Dyalog82\dyalog.exe" -Dw YY_WINDOW=-30
      ⎕←2 ⎕NQ '.' 'GetCommandLine'
"C:\Dyalog82\dyalog.exe" -Dw YY_WINDOW=-30


GetCommandLineArgs Method

GetCommandLineArgsMethod 148

Applies to: Root

The GetCommandLineArgs method returns the command and the arguments to the command that was used to start the current Dyalog APL session or application.

The GetCommandLineArgs method is niladic.

The result is a vector of character vectors. For example:

      GetCommandLineArgs
 C:\Dyalog82\dyalog.exe  -Dw  YY_WINDOW=-30
      DISPLAY 2 ⎕NQ '.' 'GetCommandLineArgs'
.→-----------------------------------------------.
| .→---------------------. .→--. .→------------. |
| |C:\Dyalog10\dyalog.exe| |-Dw| |YY_WINDOW=-30| |
| '----------------------' '---' '-------------' |
'∊-----------------------------------------------'


GetComment Event

GetComment Method 222

Applies to: Grid

This method is used to retrieve the comment associated with a cell in a Grid.

The argument to GetComment is a 2-element array as follows:

[1] | Row | integer
[2] | Column | integer

For example, the following expression retrieves the comment associated with the cell at row 3, column 1.

      F.C.GetComment 3 1
 1 3  Hello  175 100

Note that to retrieve a comment associated with a row or column title, the appropriate element in the argument should be ¯1.

If there is no comment associated with the specified cell, the result is a scalar 1.


GetEnvironment

GetEnvironment Method 510

Applies to: Root

This method is used to obtain information about one or more parameters that were specified in the APL command line, your Windows registry, or defined as environment variables. If a value is defined in several places (for example, MAXWS in the command line overriding MAXWS in the registry), GetEnvironment follows exactly the same logic as is used by Dyalog APL itself and so obtains the same value.

The argument to GetEnvironment is a single item as follows:

[1] Parameter name(s) see below

Parameter names is simple character vector or vector of character vectors specifying one or more parameters.

The result is a simple character vector or a vector of character vectors.

Examples:

      GetEnvironment 'DYALOG'
C:\Dyalog82
     GetEnvironment ⊂'DYALOG' 'APLNID'
 C:\Dyalog82  0

Note that you may use GetEnvironment to obtain the values of your own arbitrary parameters given on the APL command line, defined in APL.INI, or specified as DOS environment variables.

GetEnvironment is not supported by DYALOG.DLL because it does not use parameters.


GetEventInfo

GetEventInfo Method 551

Applies to: OCXClass, OLEClient

This method is used to obtain information about a particular event or set of events supported by a COM object.

For each event supported by a COM object, the author will have registered the data type of its result (if it has a result), a help message or description of the event (optional) and the name and data type of each of its parameters. These event parameters make up the array returned by ⎕DQ or supplied as an argument to your callback function. The GetEventInfo method returns this information.

The argument to GetEventInfo is a single item as follows:

[1] Event name(s) see below

Event name(s) is a simple character vector or a vector of character vectors specifying one or more names of events supported by the object.

The result is a nested vector with one element per event name. Each element of this vector is itself a vector of 2-element character vectors. For each event, the first item describes the help message or description (if any) registered for the event and the data type of its result. Each of the remaining elements contains a parameter name and its corresponding data type.

For example,

      CLNAME←'Microsoft Multimedia Control, Version 6.0'
      'MM' ⎕WC 'OCXClass' CLNAME
      MM.EventList
 Done  BackClick  PrevClick  NextClick  PlayClick  ...
      DISPLAY ↑MM.GetEventInfo 'Done'
.→---------------------------------------------------.
↓ .→-----------------------------. .→------.         |
| |Occurs when an MCI command ...| |VT_VOID|         |
| '------------------------------' '-------'         |
| .→---------.                     .→--------------. |
| |NotifyCode|                     |VT_PTR to VT_I2| |
| '----------'                     '---------------' |
'∊---------------------------------------------------'

Note that if the event does not produce a result, the data type of the result is reported as 'VT_VOID'.


GetFocus

GetFocus Method 511

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, PropertySheet, RichEdit, Root, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, TabControl, ToolBar, ToolControl, TrackBar, TreeView, UpDown

This method is used to obtain the name of the object that currently has the input focus.

The GetFocus method is niladic.

The result is a simple character vector. An empty result indicates that no Dyalog APL GUI object has the input focus.


GetItemHandle Event

GetItemHandle Method 313

Applies to: TreeView

This method is used to obtain the window handle of a particular item in a TreeView object.

The argument for GetItemHandle is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result is an integer containing the window handle of the item.


GetItemPosition Event

GetItemPosition Method 323

Applies to: ListView

This method is used to obtain the position of a particular item in a ListView object.

The argument for GetItemPosition is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result is a 2-element vector containing the position of the item.


GetItemState Event

GetItemState Method 306

Applies to: ListView, TreeView

This method is used to obtain the status of a particular item in a ListView or TreeView object.

The argument for GetItemPosition is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result indicates the state of the item as the sum of one or more of the following codes:

2 | Item is selected
8 | Item is highlighted for dropping
16 | Item is displayed in bold text
32 | Item is expanded
64 | Item is or has been expanded
4096 | tem is checked (see CheckBoxes)


GetMethodInfo

GetMethodInfo Method 552

Applies to: OCXClass, OLEClient

This method is used to obtain information about a particular method or set of methods supported by a COM object.

For each method supported by a COM object the author will have registered a help message or description of the method (this is in fact optional), the data type of its result (if it has a result), and the name and data type of each of the parameters that must be supplied when you invoke it. The GetMethodInfo method returns this information.

The argument to GetMethodInfo is a single item as follows:

[1] Method name(s) see below

Method name(s) is a simple character vector or a vector of character vectors specifying one or more names of methods supported by the object.

The result is a nested vector with one element per method name. Each element of this vector is itself a vector of 2-element character vectors. For each method, the first item describes the help message or description (if any) registered for the method and the data type of its result. Note that if the event does not produce a result, the data type of the result is reported as 'VT_VOID'. Each of the remaining elements contains a parameter name and its corresponding data type.

For example,

      CLNAME←'Microsoft Multimedia      Control, Version 6.0'
      'MM' ⎕WC 'OCXClass' CLNAME
      MM.MethodList
 AboutBox  Refresh  OLEDrag

      DISPLAY ↑ MM.GetMethodInfo 'AboutBox'
.→--------------.
↓ .⊖. .→------. |
| | | |VT_VOID| |
| '-' '-------' |
'∊--------------'


GetMinSize Method

GetMinSizeMethod 275

Applies to: Calendar

This method is used to obtain the minimum size that you must specify for a Calendar object for it to display a complete month.

The GetMinSize method is niladic.

The (shy) result of the method is a 2-element numeric vector containing the minimum height and width required for the object to display a complete month.


GetParentItem Event

GetParentItem Method 312

Applies to: TreeView

This method is used to obtain the index of the parent of a particular item in a TreeView object.

The argument for GetParentItem is a single item as follows:

[1] Item number Integer.

Item number is the index of the item concerned.

The result is an integer containing the index of the parent item.


GetPropertyInfo

GetPropertyInfo Method 550

Applies to: OCXClass, OLEClient

This method is used to obtain information about a particular property or set of properties supported by aCOM object.

For each property supported by a COM object, the author will have registered the property name, its data type, and an optional help message or description of the property. GetPropertyInfo returns this information.

The argument to GetPropertyInfo is a single item as follows:

[1] Property name(s) see below

Property name(s) is a simple character vector or a vector of character vectors specifying one or more names of properties supported by the object.

The result is a nested vector with one element per property name. Each element of this vector is itself a 2-element vector of character vectors containing the data type and help message for the corresponding property.

For example,

      CLNAME←'Microsoft Multimedia Control, Version 6.0'
      'MM' ⎕WC 'OCXClass' CLNAME
      MM.PropList
 Type  DeviceType  AutoEnable  PrevVisible ...

      DISPLAY ↑MM.GetPropertyInfo 'PrevVisible'
.→------------------------------------------------------.
↓ .→----------------------------------------. .→------. |
| |Determines if the Prev button is visible.| |VT_VOID| |
| '-----------------------------------------' '-------' |
| .→-.                                        .→------. |
| |⌈P|                                        |VT_BOOL| |
| '--'                                        '-------' |
'∊------------------------------------------------------'

If the data type of a property is VT_USERDEFINED, it means that the property may assume one of a set of values defined by a type list. In this case, the name of the type list is returned in place of the string “VT_USERDEFINED”. Further information can be obtained using GetTypeInfo with this name as a parameter.


GetTextSize Method

GetTextSizeMethod 92

Applies to: ActiveXControl, Animation, Bitmap, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, Printer, ProgressBar, PropertyPage, RichEdit, Root, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, TabControl, ToolBar, ToolControl, TrackBar, TreeView, UpDown

The GetTextSize method obtains the size of the bounding rectangle of a text item in a given font. The result is given in the co-ordinate system of the object in question. This method is useful for positioning Text objects.

GetTextSize duplicates the functionality of the TextSize property. It is recommended that you use GetTextSize instead of TextSize which may be removed in a future release of Dyalog APL.

The argument to GetTextSize is a 1 or 2-element array as follows:

[1] | Text item | character array
[2] | Font name | character vector

When you invoke GetTextSize you give the text item in whose size you are interested and, optionally, the name of a Font object. The text item may be a simple scalar, a vector or a matrix. If the Font is omitted, the result is given using the current font for the object in question.

Examples

      'F'⎕WC'Form'
      F.GetTextSize'Hello World'
3.385416667 10.7421875
      'FNT1' ⎕WC 'Font' 'Arial' 72
      F.GetTextSize'Hello World'  '#.FNT1'
18.75 65.4296875
      F.Coord←'Pixel'
      F.FontObj←'FNT1'
      F.GetTextSize'Hello World'
16 77


GetTypeInfo

GetTypeInfo Method 553

Applies to: OCXClass, OLEClient

This method is used to obtain information about a type list supported by a COM object.

The argument to GetTypeInfo is a single item as follows:

[1] | Type List name(s) | see below
[2] | Value | (usually) numeric
[3] | Description | character vector

Type List name(s) is a simple character vector or a vector of character vectors specifying one or more names of type lists supported by the object.

The result is a nested vector with one element per Type List. Each element of this vector is itself a 3-element vector of character vectors made up as follows:

[1] | Name of Constant | character vector
[2] | Value | (usually) numeric
[3] | Description | character vector


GetVisibleRange Method

GetVisibleRangeMethod 262

Applies to: Calendar

This method is used to obtain the range of dates that is currently visible in a Calendar object.

The GetVisibleRange method is niladic.

The result is a 2-element integer vector containing the first and last dates currently displayed by the object, reported as IDNs.


GreetBitmap Method

GreetBitmapMethod 138

Applies to: Root

This method is used to display or remove a bitmap, typically during initialisation of a Dyalog APL runtime application.

The argument to GreetBitMap is ⍬ or a 2 element vector as follows:

[1] | Display | 0 = off, 1 = on.
[2] | Bitmap file name | Character vector.

If the argument is ⍬, the bitmap is removed.

The image may also be displayed initially by setting parameter: greet_bitmap on the command line, e.g.:

c:\myapp\dyalogrt greet_bitmap=mylogo myws

The image is displayed until either an untrapped error occurs, causing the interpreter to (attempt to) display the session window, or the GreetBitmap method is called.


IDNToDate Method

IDNToDateMethod 263

Applies to: Calendar, DateTimePicker, Root

This method is used to convert a date from an IDN into ⎕TS format (year, month, day). The corresponding day of the week is also obtained.

The argument to IDNToDate is a single item as follows:

[1] IDN Integer

The result is a 4-element integer vector containing the year, month, day, and weekday corresponding to the IDN that was specified.

The value of the 4th element, weekday, is an integer in the range 0-6 that specifies on which day of the week the specified date falls (0=Monday).

Example:

      F.C.IDNToDate 36048
1998 9 11 4


LockColumns Method

LockColumns Method 227

Applies to: Grid

This method is used to lock one or more columns of a Grid object. However, LockColumns is not supported in combination with hierarchical column titles as specified by the ColTitleDepth property.

The argument to LockColumns is a 1 or 2-element vector as follows.

[1] | Column(s) | integer scalar, vector or matrix
[2] | Lock flag | 0 or 1

Column(s) may be a scalar or a vector specifying the column or columns to be locked or unlocked. Alternatively, it may be a matrix whose first row specifies the columns to be locked and whose second row specifies where they are to be locked.

If the Lock flag is 1, the corresponding columns are locked. This is the default and may be omitted. If the Lock flag is 0, the corresponding columns are unlocked

Examples:

      F.G.LockColumns 3         ⍝Lock 3rd column
      F.G.LockColumns 3 0       ⍝Unlock 3rd column
      F.G.LockColumns (4 5)     ⍝Lock 4th & 5th cols
      F.G.LockColumns (2 1⍴8 4) ⍝Lock 8 at 4
      F.G.LockColumns 3         ⍝Lock 3rd column
      F.G.LockColumns 3 0       ⍝Unlock 3rd column
      F.G.LockColumns (4 5)     ⍝Lock 4th & 5th cols
      F.G.LockColumns (2 1⍴8 4) ⍝Lock 8 at 4

The result is an integer matrix containing the indices of all locked columns and the positions at which they are currently locked.

The expression:

      F.G.LockColumns ⊂⍬

may therefore be used to obtain the indices of the locked columns, and:

      F.G.LockColumns(F.G.LockColumns ⊂⍬) 0

unlocks all currently locked columns.

Locks are additive. If column 4 is locked, locking column 5 results in both columns 4 and 5 being locked.

A locked column remains fixed in position and does not scroll sideways. The user may enter and edit cells in a locked column in the normal way, but the behaviour of the various cell movement keys (Tab, left and right cursor, and so forth) differs when a locked column is encountered. As a general rule, if a keystroke attempts to move the cursor into a locked column from an adjacent column, and the adjacent column has been scrolled, it is unscrolled and the cursor remains in the (new) column adjacent to the fixed column. If not, the cursor moves into the locked column.

When you lock a column, the position you specify for it to be locked at is a position in the data and not the physical position of the column as displayed in the Grid . The physical column in the Grid depends upon the value of the Index property at the time it was locked.

If C is the value specified for where a given column is to be locked, the value of the physical column P at which it will be displayed in the Grid named GRID is:

      P←C-(2⊃GRID ⎕WG 'Index')-⎕IO

Furthermore, the position of a locked column given by the result of the LockColumns method changes (with the Index property) as the Grid is scrolled.


LockRows Method

LockRows Method 226

Applies to: Grid

This method is used to lock one or more Rows of a Grid. However, LockRows is not supported in combination with hierarchical row titles as specified by the RowTitleDepth property.

The argument to LockRows is a 1 or 2-element vector as follows.

[1] | Row(s) | integer scalar, vector or matrix
[2] | Lock flag | 0 or 1

Row(s) may be a scalar or a vector specifying the row or rows to be locked or unlocked. Alternatively, it may be a matrix whose first row specifies the data rows to be locked and whose second row specifies where in the Grid they are to be locked

If the Lock flag is 1, the corresponding rows are locked. This is the default and may be omitted. If the Lock flag is 0, the corresponding rows are unlocked

Examples:

      F.G.LockRows 3         ⍝Lock 3rd row
      F.G.LockRows 3 0       ⍝Unlock 3rd row
      F.G.LockRows (4 5)     ⍝Lock 4th and 5th rows
      F.G.LockRows (2 1⍴8 4) ⍝Lock row 8 at 4
      F.G.LockRows 3         ⍝Lock 3rd row
      F.G.LockRows 3 0       ⍝Unlock 3rd row
      F.G.LockRows (4 5)     ⍝Lock 4th and 5th rows
      F.G.LockRows (2 1⍴8 4) ⍝Lock row 8 at 4

The result is an integer matrix containing the indices of all locked rows and the positions at which they are currently locked.

The expression:

      F.G.LockRows ⊂⍬

may therefore be used to obtain the indices of the locked rows, and

      F.G.LockRows(F.G.LockRows ⊂⍬) 0

unlocks all currently locked rows.

Locks are additive. If row 4 is locked, locking row 5 results in both rows 4 and 5 being locked.

A locked row remains fixed in position and does not scroll vertically. The user may enter and edit cells in a locked row in the normal way, but the behaviour of the various cell movement keys (Tab, up and down cursor, and so forth) differs when a locked row is encountered. As a general rule, if a keystroke attempts to move the cursor into a locked row from an adjacent row, and the adjacent row has been scrolled, it is unscrolled and the cursor remains in the (new) row adjacent to the fixed row. If not, the cursor moves into the locked row.

When you lock a row, the position you specify for it to be locked at is a position in the data and not the physical position of the column as displayed in the Grid. The physical column in the Grid depends upon the value of the Index property at the time it was locked.

If R is the value specified for where a given row is to be locked, the value of the physical row P at which it will be displayed in the Grid named GRID is given by the expression:

P←R-(⊃GRID ⎕WG 'Index')-⎕IO

Furthermore, the position of a locked row given by the result of the LockRows method changes (with the Index property) as the Grid is scrolled.


MakeGIF Method

MakeGIFMethod 261

Applies to: Bitmap

This method is used to generate an uncompressed GIF representation of a picture from a Bitmap object suitable for display by a Web browser.

The MakeGIF method is niladic.

The result is an integer vector containing the encoded GIF image.

Example:

      ⍴GIF←BM.MakeGIF
19620
Note:
Dyalog has chosen to support uncompressed GIF to avoid the legal complexity of dealing with the licensing issues surrounding the compression algorithm which is patented. If the target Web browser supports PNG (Portable Network Graphics) format, use that instead.


MakePNG Method

MakePNGMethod 260

Applies to: Bitmap

This method is used to generate a PNG (Portable Network Graphics) representation of a picture from a Bitmap object suitable for display by a Web browser.

The MakePNG method is niladic.

The result is an integer vector containing the encoded PNG image.

Example:

      ⍴PNG←BM.MakePNG
4930
Note:
Although PNG is recognised as the latest graphics standard for displaying pictures, not all Web browsers support it.


MDIArrange Event

MDIArrange Method 112

Applies to: MDIClient

Description

This method causes the MDIClient object to organise the icons associated with any minimised child Forms into regimented rows and columns. To permit the user to carry out this action, it is recommended that a suitable callback function or expression is attached to a MenuItem or Button. The callback function or expression should then call MDIArrange.

The MDIArrange method is niladic.


MDICascade Event

MDICascade Method 110

Applies to: MDIClient

Description

This method causes the MDIClient object to organise its child Forms in an overlapping fashion. To permit the user to carry out this action, it is recommended that a suitable callback function or expression is attached to a MenuItem or Button. The callback function or expression should then call MDICascade.

The MDICascade method is niladic.


MDITile Event

MDITile Method 111

Applies to: MDIClient

Description

This method causes the MDIClient object to organise its child Forms as a row or column. To permit the user to carry out this action, it is recommended that a suitable callback function or expression is attached to a MenuItem or Button. The callback function or expression should then call the MDITile method.

Note that because there are restrictions concerning the minimum height and width of a window, MS-Windows does not necessarily respond as requested. If the MDIClient is itself of insufficient size, or if it contains a large number of child Forms, Windows may choose to tile the Forms in a row when a column was specified or vice versa. It may also choose to ignore the event entirely.

The argument to MDITile is ⍬,or a single item as follows:

[1] Tile Mode 0 (vertical)
1 (horizontal)

If the argument is ⍬, the Tile Mode defaults to 0.


NameFromHandle Event

NameFromHandle Method 136

Applies to: Root

This method is used to obtain the name of a particular object from the value of its Handle property.

The argument to NameFromHandle is a single item as follows:

[1] Handle The value of the Handle property from an existing object.

The result is a character vector containing the name of the object.


NewPage Event

NewPage Method 102

Applies to: Printer

Description

This method causes a Printer to start a new page

The NewPage method is niladic.

If you attach a callback function to this event and have it return a value of 0, the page throw will not occur.


OLEAddEventSink Method

OLEAddEventSinkMethod 540

Applies to: OCXClass, OLEClient

This method connects a named event sink to a COM object and adds the events defined by that event sink to the EventList property of the associated namespace.

The argument to OLEAddEventSink is a single item as follows:

[1] Event sink name character vector

The result is a number that represents the handle of the event sink. This may be subsequently required.


OLEDeleteEventSink Method

OLEDeleteEventSinkMethod 541

Applies to: OCXClass, OLEClient

This method disconnects a named event sink from a COM object and removes the events defined by that event sink from the EventList property of the associated namespace.

This method may be used to remove an event sink that was established automatically when the OLE object was created.

The argument to OLEDeleteEventSink is a single item as follows:

[1] Event sink name character vector


OLEListEventSinks Method

OLEListEventSinksMethod 542

Applies to: OCXClass, OLEClient

This method returns the names of event sinks that are currently connected to a COM object.

The list contains the names of all the event sinks that were connected automatically when the object was created, together with any that you have added subsequently using OLEAddEventSink.

The OLEListEventSinks method is niladic.

The result is a vector of character vectors containing the names of the event sinks connected to the object.


OLEQueryInterface Method

OLEQueryInterfaceMethod 543

Applies to: ActiveXContainer, OLEClient

This method is used to obtain the methods and properties associated with a particular interface that is provided by a COM object. An interface is simply a pointer to a table of methods (not properties) that are exported by an object.

Note that methods and properties exported using the standard IDispatch interface are established automatically when the object is created. OLEQueryInterface is required only to support alternative or additional interfaces that the object may implement.

The argument to OLEQueryInterface is a single item as follows:

[1] Interface name character vector

The result is a namespace.

It is normal, although not strictly required, that the new namespace be a child of the one for which the method is run.

Note that if the object does not support a type library, the new namespace will be empty and you will have to establish functions corresponding to the methods exported by the interface using SetMethodInfo.


OLERegister Method

OLERegisterMethod 530

Applies to: OLEServer

This method is used to register an OLEServer object and may be used to install Dyalog APL OLE Servers as part of a run-time installation.

The OLERegister method is niladic.


OLEUnregister Method

OLEUnregister Method 531

Applies to: OLEServer

This method is used to unregister an OLEServer object that has previously been saved by Dyalog APL.

The OLEUnregister method is niladic.

This method removes all traces of the object from the Windows registry and erases its Type Library file.

Note that the name of the object removed from the registry is the name of the OLEServer object prefixed by the string “dyalog.”


Print Event

Print Method 100

Applies to: Printer

Description

This method causes any spooled output to be printed.

The Print method is niladic.

If you attach a callback function to this event and have it return a value of 0, the printout will not be spooled.


ProgressStep Event

ProgressStep Method 250

Applies to: ProgressBar

This method is used to increment the thumb in a ProgressBar object.

The ProgressStep method is niladic.

The ProgressStep method causes the ProgressBar to attempt to increment its thumb by the value of its Step property, taking into account the setting of its Wrap property. If the values of the Thumb, Step and Limits properties are THUMB, STEP and LIMITS respectively, the new value of Thumb (and the corresponding position of the highlit bar) is:

if Wrap is 0:

    LIMITS[2]⌊THUMB+STEP

if Wrap is 1:

    LIMITS[1]+(1+LIMITS[2]⍎LIMITS[1])|THUMB+STEP⍎LIMITS[1]


RowChange Event

RowChange Method 158

Applies to: Grid

Description

This method is used to change the data in a row of a Grid object.

The argument to RowChange is a 2-element array as follows.

[1] | Row number | integer
[2] | Row data | array

Row data must be a scalar or a vector whose length is equal to the number of columns in the Grid. Its elements may be scalar numbers, character vectors or matrices.


RowSetVisibleDepth Method

RowSetVisibleDepth Method 173

Applies to: Grid

This method is used to set the maximum visible depth of data in rows of a Grid.

The argument to RowSetVisibleDepth is a numeric scalar as follows

[1] Depth integer

All rows in the grid that have a value of RowTreeDepth less that or equal to Depth are expanded. Rows with a value of RowTreeDepth greater than Depth are collapsed.

Note:Expanding and Retracting events are not generated when this method is called.

      'F'⎕WC'Form' 'Grid: TreeView Feature'
      'F.G'⎕WC'Grid'(30 2⍴2/⍳30)
      F.G.RowTreeDepth←30⍴0 1 2 2

      F.G.RowSetVisibleDepth 1

      F.G.RowSetVisibleDepth 99


RTFPrint Event

RTFPrint Method 461

Applies to: RichEdit

This method is used to print the contents (RTFText) of a RichEdit object.

The argument to RTFPrint is <—>, or a 1 to 4-element array as follows:

[1] | Printer name | Optional - character vector (see below)
[2] | Print range | Optional - (see below)
[3] | Number of copies | Optional - Integer.
[4] | Collate | Optional - 0 or 1

Printer name may be the name of an existing Printer object, or the (Windows) name of an installed printer. If you use the latter, the document will be spooled immediately. An empty vector implies the default printer.

Print range may be a simple character vector containing 'All', 'Pages', or 'Selection'. Alternatively, it may be a 3 or 4-element nested vector containing:

[1] | 'All', 'Pages', or 'Selection'
[2] | Start page (integer)
[3] | End page (integer)
[4] | Maximum pages (ignored)


RTFPrintSetup Event

RTFPrintSetup Method 460

Applies to: Printer, RichEdit

This method is used to display a print set-up dialog box. The dialog box allows the user to select a particular printer, the pages to be printed and other information. The user’s choices are returned in the result.

The argument to RTFPrintSetup is <—>, or a 1 to 3-element array as follows:

[1] | Print range | Optional - (see below)
[2] | Number of copies | Optional - Integer.
[3] | Collate | Optional - 0 or 1

Print range may be a simple character vector containing 'All', 'Pages', or 'Selection'. Alternatively, it may be a 3 or 4-element nested vector containing:

[1] | 'All', 'Pages', or 'Selection'
[2] | Start page (integer)
[3] | End page (integer)
[4] | Maximum pages

Maximum pages (4th element of Print range) may be an integer number, or the name of a reference object. The latter allows the system to calculate the total number of pages required. If the object to which the RTFPrintSetup event is sent is a RichEdit, this is the name of a printer object. If the object to which the RTFPrintSetup event is sent is a Printer, this is the name of a RichEdit object. Both are required because the number of pages of a printed document is dependent upon both the content of the document and the characteristics of the device upon which it will be printed.

If the user presses OK, the result is a 4-element vector containing the user’s choices as follows:

[1] | Printer name | character vector
[2] | Print range | (see above)
[3] | Number of copies | Integer
[4] | Collate | 0 or 1

Example:

      F.T.RTFPrintSetup ('All' 1 1 'PR')
 IBM 4039 LaserPrinter PS   Pages  2 3 3  1 0


Setup Event

Setup Method 101

Applies to: Printer

Description

This method causes the system to display a standard Printer Setup dialog box and thereby allows the user to alter the printer settings. This is a "modal" dialog box that must be closed before the APL application can continue.

The Setup method is niladic.

If you attach a callback function to this event and have it return a value of 0, the dialog box will not appear.


SetCellSet Method

SetCellSetMethod 171

Applies to: Grid

The SetCellSet method sets the value of the CellSet property of a Grid for a particular cell.

The argument to SetCellSet is a 3-element array as follows:

[1] | Row | integer
[2] | Column | integer
[3] | Value | 0 or 1


SetCellType Method

SetCellType Method 156

Applies to: Grid

Description

This method is used to change the type of a particular cell in a Grid.

The argument to SetCellType is a 3-element vector as follows :

[1] | Cell row | integer
[2] | Cell column | integer
[3] | Cell type | integer


SetEventInfo Method

SetEventInfoMethod 547

Applies to: ActiveXControl, OLEServer

This method is used to register an event that may be generated by an ActiveXControl or OLEServer object.

A host application that wishes to attach a callback function to an event in a Dyalog APL ActiveXControl or OLEServer, needs to know the name of the event and the number and data types of any parameters that the event may supply. It also needs to know the data type (if any) of the result that the callback function may be expected to pass back to the control.

An ActiveXControl or OLEServer generates an event in the host application using 4 ⎕NQ. The right argument is a vector whose first 2 elements are character vectors containing the names of the ActiveXControl or OLEServer and the event respectively. The parameters for the event are passed as additional elements in the argument.

Another way to think about it is that when you generate an event using 4 ⎕NQ, you are effectively calling a function, of your specification, in the host application. To enable the host application to accept the function call, it needs to know the number of parameters that you will supply and their data types.

A further consideration is that if you specify that the data type of a parameter is a pointer (e.g. 'VT_PTR TO I4') this will allow a callback function to modify the parameter in-situ. If so, the result returned by 4 ⎕NQ will be the modified values of any such parameters; this is a similar mechanism to ⎕NA.

The argument to SetEventInfo is a 1, 2 or 3-element array as follows:

[1] | Event name | character vector
[2] | Event info | nested array (see below)
[3] | Help ID | integer

Event info

Event info, specifies an optional help string which describes what the event does, the data type of the result (if any) and the names and data types of its arguments.

If the event is fully described, each element of Event Info is a 2-element vector of character vectors. The first element contains the help string and the COM data type of the result that the callback function in the host application is expected to supply. Subsequent elements contain the name and COM data type of each of the parameters supplied by the event.

However, both the help string and the names of the parameters are optional and may be omitted. If so, one or more elements of Event Info may be a simple character vector.

Help ID

This is an integer value that identifies the help context id for the event within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.

Example

The example Dual ActiveXControl, that is fully described elsewhere, generates a ChangeValue1 event. This event occurs when the user moves the thumb in a TrackBar that is internal to an instance of the ActiveXControl.

The external ChangeValue1 event is fired by an internal APL callback function (called ChangeValue) that is attached to ThumbDrag and Scroll events on the TrackBar object. The internal callback function is :

[0]   ChangeValue MSG
[1]   ⍝ Callback for ThumbDrag and Scroll
[2]   Value1←4 ⎕NQ'' 'ChangeValue1'(⊃¯1↑MSG)
[3]   CalcValue2
[4]   'V1'⎕WS'Text'(⍕Value1)
[5]   'V2'⎕WS'Text'(⍕Value2)

Note that ChangeValue[2] generates the external ChangeValue1 event by invoking 4 ⎕NQ, passing it the new value provided by the TrackBar. However, the host application is permitted to modify that value, returning it in the result of 4 ⎕NQ. This result, rather than the TrackBar value itself, is then used to update other (Label) controls in the object.

The following statements were used to declare the ChangeValue1 event The event provides a single parameter named Value1 that may be modified in-situ by a callback function in the host application. The callback is not, otherwise, expected to return a result.

      INFO←⊂'Occurs when the value of the control is changed' 'VT_VOID'
      INFO,←⊂'Value1' 'VT_PTR TO VT_I4'
      F.Dual.SetEventInfo 'ChangeValue1' INFO

If the host application was Visual Basic, a suitable callback function might be:

Private Sub Dual1_ChangeValue1(Value1 As Long)
Value1=2*(Value1\2)
End Sub

This callback function receives the proposed new value of the control as the parameter Value1, and modifies it, forcing it to be an even number.


SetFinishText Method

SetFinishTextMethod 366

Applies to: PropertySheet

The SetFinishText method sets the caption of the Finish button in a Wizard-style PropertySheet.

The argument to SetFinishText is a single item as follows:

[1] Finish button text character vector


SetFnInfo Method

SetFnInfoMethod 545

Applies to: ActiveXControl, OLEServer

This method is used to describe an APL function that is to be exported as a method, or as a property get or property put function, of an ActiveXControl or OLEServer object.

An exported function must be a niladic or monadic defined function (dynamic functions and derived functions are not allowed) and may optionally return a result. Ambivalent functions (functions with optional left argument) are allowed, but will be called monadically by the host application.

COM syntax differs from APL syntax in many ways and the SetFnInfo method is required to declare an APL function to COM in terms that COM understands. In particular, although monadic APL functions take just one argument, COM functions may take several parameters, and some may be optional.

A function exported by SetFnInfo will be called by a host application with the number of parameters that SetFnInfo has described. The argument received when the function is called by a host application, will be a nested vector of this length.

The argument to SetFnInfo is a 2, 3 or 4-element array as follows:

[1] | Function name | character vector
[2] | Function info | nested array (see below)
[3] | Help ID | integer
[4] | Function type | integer
[5] | Property name | character vector

Function info

Function info, specifies an optional help string which describes what the function does, the data type of the result (if any) and the names and data types of its arguments.

If the function syntax is fully described, each element of Function Info is a 2-element vector of character vectors. The first element contains the help string and the COM data type of the function’s result. Subsequent elements contain the name and COM data type of each parameter.

However, both the help string and the names of the parameters are optional and may be omitted. If so, one or more elements of Function Info may be a simple character vector.

Consider a very basic function ADD in an ActiveXControl called F.dbase, that is designed to add a record to a personnel database. The database consists only of a list of names, ages and addresses.

Function ADD expects to be called with a name (character string), age (number) and address (character string), and returns a result 0 or 1 (Boolean) according to whether the record was successfully added. This function could be declared as follows:

      HELP←'Adds a new record to the personnel database'
      SPEC←⊂(HELP 'VT_BOOL')      ⍝ Result is boolean
      SPEC,←⊂('Name' 'VT_BSTR')   ⍝ 1st param called 'Name' is a string
      SPEC,←⊂('Age' 'VT_I4')      ⍝ 2nd param called 'Age' is an integer
      SPEC,←⊂('Address' 'VT_BSTR')⍝ 3rd param called 'Address' is a string

      F.dbase.SetFnInfo 'ADD' SPEC

Alternatively, but much less helpfully, the function could be declared to take a single unnamed nested argument, leaving it to the host application programmer to guess at its structure :

      SPEC←⊂('' 'VT_BOOL')              ⍝ No help string, result is boolean
      SPEC,←⊂('' 'VT_ARRAY OF VT_VARIANT') ⍝ Param is a nested array
      F.dbase.SetFnInfo 'ADD'SPEC

Help ID

This is an integer value that identifies the help context id within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.

Function type

This specifies the type of function being exported. This is an integer with one of the following values:

1 | Function is a method
2 | Function is a property get function
4 | Function is a property put function

In both these last two cases, the name of the property, which is totally independent of the name of the APL function, is given as Property name.

If omitted, the function type is method.


SetItemImage Event

SetItemImage Method 315

Applies to: TreeView

This method is used to allocate a picture icon to a particular item in a TreeView object.

The argument to SetItemImage is a 2-element array as follows:

[1] | Item number | Integer.
[2] | Picture index | Integer.

Item number is the index of the item concerned.

Picture index is an index into the array of bitmapped images in the corresponding ImageList object which is referenced via the ImageListObj property.


SetItemState Event

SetItemState Method 307

Applies to: ListView, TreeView

This method is used to set the status of a particular item in a ListView or TreeView object.

The argument to SetItemState is a 2-element array as follows:

[1] | Item number | Integer. The index of the item concerned.
[2] | Status | Integer

The status of an item is calculated as the sum of one or more of the following state codes:

1 | Item has the focus
2 | Item is selected
8 | Item is highlighted for dropping
16 | Item is displayed in bold text
32 | Item is expanded
64 | Item is or has been expanded
4096 | Item is checked (see CheckBoxes)


SetMethodInfo Method

SetMethodInfoMethod 556

Applies to: OCXClass, OLEClient

This method is used to redefine the arguments or data types associated with a method that is exported by a COM object. SetMethodInfo is used to override the information provided by the object's Type Library.

The argument to SetMethodInfo is a 2 or 3-element array as follows:

[1] | Method name | character vector
[2] | Method info | nested vector (see below)
[3] | Method index | integer

If you wish to describe the method completely, the structure of Method info should be identical to the structure returned by GetMethodInfo, although abbreviated formats are also allowed.

If the object exports the method directly, and not through the standard IDispatch interface, you must also specify Method Index, which is the index of the method in the object's virtual table (vtable). This information may be available in printed documentation or in a C-language header file.

For example, the InchesToPoint method exported by Excel.Application takes a single argument whose name is Arg1 and whose data type is VT_R8. The function returns a result of the same data type. The details provided in the Excel.Application Type Library are in fact correct, but if you wanted to redefine them, the following statements could be used to describe the InchesToPoints method.

      'EX' ⎕WC 'OLEClient' 'Excel.Application' ('AutoBrowse' 0)

      methodinfo← ('' 'VT_R8')('Arg1' 'VT_R8')
      EX.SetMethodInfo 'InchesToPoints' methodinfo

Note that the structure of variable methodinfo is identical to the result of the GetMethodInfo method.

      DISPLAY methodinfo
.→-----------------------------------.
| .→------------. .→---------------. |
| | .⊖. .→----. | | .→---. .→----. | |
| | | | |VT_R8| | | |Arg1| |VT_R8| | |
| | '-' '-----' | | '----' '-----' | |
| '∊------------' '∊---------------' |
'∊-----------------------------------'

      DISPLAY EX.GetMethodInfo 'InchesToPoints'
.→-----------------------------------.
| .→------------. .→---------------. |
| | .⊖. .→----. | | .→---. .→----. | |
| | | | |VT_R8| | | |Arg1| |VT_R8| | |
| | '-' '-----' | | '----' '-----' | |
| '∊------------' '∊---------------' |
'∊-----------------------------------'

Unless you are going to call the method using the names of its arguments, these names are clearly superfluous and may be omitted, for example:

      methodinfo← 'VT_R8' 'VT_R8'
      EX.SetMethodInfo 'InchesToPoints' methodinfo


SetPropertyInfo Method

SetPropertyInfoMethod 554

Applies to: OCXClass, OLEClient

This method is used to redefine a property that is exported by a COM object. SetPropertyInfo is used to override the information provided by the object's Type Library.

The argument to SetPropertyInfo is a 2 or 3-element array as follows:

[1] | Property name | character vector
[2] | Property info | nested vector
[3] | Property function | integer

For example, the Visible property exported by Excel.Application has the data type VT_BOOL and may be declared as follows:

      'EX' ⎕WC 'OLEClient' 'Excel.Application'
      EX.SetPropertyInfo 'Visible' 'VT_BOOL'

Property function may be required if the property value is retrieved or set via a function. This typically applies if the property takes parameters and will result in the property being fixed as a function rather than as a variable. Such properties may have a PropertyGet function, a PropertyPut function and/or a PropertyPutByReference function. If so, it is necessary to say to which of these three functions the details apply. The value of Property function is an integer 2 (PropertyGet), 4 (PropertyPut), or 8 (PropertyPutByReference).

For example, the following statement declares the PropertyGet function for the Item property of the Fields collection of the OLE object DAO.DBEngine. This property takes an index (into the collection) and returns an object.

      Fields.SetPropertyInfo 'Item'('VT_DISPATCH' 'VT_I4')2


SetVarInfo Method

SetVarInfoMethod 546

Applies to: ActiveXControl, OLEServer

This method is used to describe an APL variable that is to be exported as a property of an ActiveXControl or OLEServer object.

The argument to SetVarInfo is a 2 or 3-element array as follows:

[1] | Variable name | character vector
[2] | Variable info | see below
[3] | Help ID | integer

Variable info is either a simple character vector that specifies the COM data type of the variable, or a 2-element vector of character vectors whose first element specifies a help string and whose second element specifies the COM data type.

Help ID is an optional integer value that identifies the help context id within the help file associated with the HelpFile property of the ActiveXControl object. The value ¯1 means that no help is provided. APL stores this information in the registry from where it may be retrieved by the host application.


ShowHelp

ShowHelp Method 580

Applies to: OCXClass, OLEClient

This method is used to display the Windows help file for aCOM object or the help topic associated with one of its properties, events or methods.

The argument to ShowHelp is <—>, or a single item as follows :

[1] Topic character vector.

Topic specifies the name of a property, event or method.

In the case of an OLE Control, the Obect name may be the name of the OCXClass or an instance of the OCXClass.


ShowItem Event

ShowItem Method 316

Applies to: TreeView

This method is used to display a particular item in a TreeView object.

The argument to ShowItem is a single item as follows:

[1] Item number Integer.

Item number specifies the index of the item concerned.

In order to display the requested item, the parent item (if any) will be opened and the object will be scrolled if necessary.


ShowProperties

ShowProperties Method 560

Applies to: OCXClass

This method is used to display the PropertySheet for an instance of an OLE Control. The user may then modify some or all of the properties of the control by changing values in the property sheet. This facility is intended to be used in the context of a GUI design tool but may also be useful in certain end-user applications.

The ShowProperties method is niladic.


ShowSIP Method

ShowSIPMethod 25

Applies to: ActiveXControl, Animation, Button, Calendar, ColorButton, Combo, ComboEx, CoolBar, DateTimePicker, Edit, Form, Grid, Group, Label, List, ListView, MDIClient, ProgressBar, PropertyPage, RichEdit, Root, Scroll, SM, Spinner, Static, StatusBar, SubForm, TabBar, TabControl, ToolBar, ToolControl, TrackBar, TreeView, UpDown

ShowSIP applies only to PocketAPL.. In versions of Dyalog APL for other platforms, it has no effect.

This method displays and hides the Input Panel.

The argument to ShowSIP is 1 (display the Input Panel) or 0 (hide the Input Panel).

The argument to ShowSIP is 0 or 1 as follows :

[1] Mode Boolean
0 = hide the Input Panel.
1 = display the Input Panel

The result of ShowSIP is 1 if the Input Panel was previously displayed, or 0 if it was previously hidden.


TCPGetHostID Method

TCPGetHostID Method 376

Applies to: Root, TCPSocket

This method is used to obtain the IP Address of your PC.

The TCPGetHostID method is niladic.

The (shy) result is a character string containing your IP address. If you have more than one, it will return the first.

For example:

      TCPCetHostID
193.32.236.43


TCPSend Method

TCPSend Method 375

Applies to: TCPSocket

This method is used to send data to a remote process connected to a TCPSocket object

The argument to TCPSend is a 1 or 3-element array as follows:

[1] | Data | the data to be sent
[2] | IP address | character vector
[3] | Port number | integer

If Style is 'Char', the data to be sent must be a character vector. If Style is 'Raw', the data to be sent must be an integer vector whose elements are in the range -128 to 255. If Style is 'APL', any array may be transmitted.

The optional IP address and Port number parameters specify the intended recipient of the message and apply only if the SocketType is 'UDP', in which case they are mandatory. If the SocketType is 'Stream', these parameters will be ignored and should be omitted.


TCPSendPicture Method

TCPSendPictureMethod 380

Applies to: TCPSocket

This method is used to transmit a picture represented by a Bitmap object to a TCP/IP socket. The picture may be transmitted in uncompressed GIF or in PNG format.

The argument to TCPSendPicture is a 1 or 2-element array as follows:

[1] | Bitmap name | character vector
[2] | Picture format | character vector, 'GIF' or 'PNG'

If Picture format is omitted, the default is GIF format.

Note that the Style of the TCPSocket object must be set to 'Raw' before you execute the TCPSendPicture method.

The (shy) result of the method is an integer that reports the number of bytes that were transmitted.

Example:

      S1.TCPSendPicture 'BM' 'PNG'
4930
Note:
Although PNG is recognised as the latest graphics standard for displaying pictures, not all Web browsers support it.

See also: MakeGIF, MakePNG


Undo Event

Undo Method 170

Applies to: Grid

Description

This method is used to undo the previous change in a Grid object.

The Grid object maintains a buffer of the most recent 8 changes made by the user since the Values property was last set by ⎕WC or ⎕WS.

Your application can restore these changes one by one by calling the Undo method on the Grid. The Undo method restores the most recent change made by the user and removes that change from the undo stack.

It is therefore not possible to “undo an undo”.

The argument to Undo is <—>,or a single item as follows :

[1] Number of changes integer

If called with an argument of <—>, the default value for the Number of changes is 1. This restores the most recent change.


ActiveXContainer Events

AmbientChanged Close Create


ActiveXContainer Methods

Detach OLEQueryInterface


ActiveXContainer Properties

Type | Event | FontObj
FCol | BCol | Data
KeepOnClose | MethodList | ChildList
EventList | PropList |


ActiveXControl Events

AmbientChanged | Close | Configure
ContextMenu | Create | DragDrop
DropFiles | DropObjects | Expose
FontCancel | FontOK | GotFocus
Help | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | PreCreate | Select


ActiveXControl Method

A method is function that may be called directly by a host application.


ActiveXControl Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | SetEventInfo
SetFnInfo | SetVarInfo | ShowSIP


ActiveXControl Properties

Type | ClassName | Posn
Size | Coord | Border
Active | Visible | Event
Dragable | FontObj | FCol
BCol | Picture | CursorObj
AutoConf | YRange | XRange
Data | TextSize | EdgeStyle
Handle | Translate | Accelerator
AcceptFiles | ClassID | Container
KeepOnClose | HelpFile | ToolboxBitmap
TypeLibID | TypeLibFile | LastError
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


ActiveXControl Property Get Function

A property get function is a function that is invoked by OLE when a host application references a specific property.

Property get and property put functions provide an alternative to representing a property as a variable.

A property get function allows your ActiveXControl to derive the current value of a property dynamically, rather than having to continually keep it updated in a variable. For example, a property such as the current contents of an Edit box within an ActiveXControl is better represented by a property get function than by a variable.


ActiveXControl Property put Function

A property put function is a function that is invoked by OLE when a host application assigns a value to a specific property.

Property get and property put functions provide an alternative to representing a property as a variable.

A property put function allows your ActiveXControl to validate before accepting a new value assigned by the host application It also allows it to action side effects, such as updating the user interface, to reflect the new value.


aexp

Expression returning an array


Ampersand

&

Ampersand is a Monadic operator with an ambivalent operand

Operator Ampersand means

Spawn

      ⍎& '⌹4 4⍴1 2 3 4 5'
¯0.17   0.21   0.014  0.014
 0.029 ¯0.19   0.21   0.014
 0.029  0.014 ¯0.19   0.21
 0.26   0.029  0.029 ¯0.17

      3 2 1 4 ⌹& 4 4⍴1 2 3 4 5
¯0.014 ¯0.014 0.79 0.17

Language Elements


andor

Either:

1 or more :AndIf statements

or:

1 or more :OrIf statements

       |
       .-----------------------.
       |                       |
       |<--------------.       |<--------------.
       |               |       |               |
       :AndIf bexp-----'       :OrIf -----'       :OrIf bexp------'
       |                       |
       |<----------------------'
       |


Animation Events

AnimStarted | AnimStopped | Close
Configure | ContextMenu | Create
DragDrop | DropFiles | DropObjects
Expose | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel


Animation Methods

Animate | AnimClose | AnimOpen
AnimPlay | AnimStop | Detach
GetFocus | GetTextSize | ShowSIP


Animation Properties

Type | Posn | Size
File | Coord | Border
Active | Visible | Event
Sizeable | Dragable | BCol
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | AcceptFiles | KeepOnClose
AutoPlay | Transparent | Align
MethodList | ChildList | EventList
PropList |  |


APL Programs

Defined Functions & Operators

Workspaces

Expressions

Statements

Defined Functions

Defined Operators

Global & Local Names

Idiom Recognition

Search Functions and Hash Tables

Control Structures

Locked Functions & Operators


APLFormatBias Parameter

There is a choice between two algorithms used to format floating-point numbers. The algorithm used depends upon the value of the APLFormatBias Parameter (see User Guide).

If APLFormatBias is 0 (the default if it is not specified), floating point numbers are formatted as accurately as possible using high-precision mathematical routines.

If you set APLFormatBias to 1, there is a significant performance optimisation whereby numbers which would display in fewer than 10 digits are scaled and then treated as integers. This optimisation results in significantly better performance, although the increase in speed may only be noticeable in an application that does a lot of formatting.

A consequence of the optimisation is that numbers smaller than but indistinguishable (in terms of the accuracy of internal representation) from a number whose last decimal digit is 5, are rounded up. For example, any number whose decimal part (the part of the number after the decimal point) is in the range (0.49999999999999987 to 0.49999999999999999 will be rounded as if it were 0.5 (i.e., rounded up). This effect, although potentially desirable, may be regarded as being not strictly correct.

For example, consider the number 0.015 which is internally represented as the value 1.4999999...

      2 ⍕0.015 ⍝ APLFormatBias = 0
0.01
      2 ⍕0.015 ⍝ APLFormatBias = 1
0.02


Array Selection

Array Selection NV⊃¨⊂A

is implemented as A[NV], which is significantly faster.

The two are equivalent but the former may now be used as a matter of taste with no performance penalty.


bexp

Expression returning a single Boolean value (0 or 1)


Bitmap Events

Close Create Select


Bitmap Methods

Detach | FileRead | FileWrite
GetTextSize | MakeGIF | MakePNG


Bitmap Properties

Type | File | Bits
CMap | KeepBits | Size
Coord | Event | FontObj
YRange | XRange | Data
TextSize | Translate | Accelerator
KeepOnClose | CBits | MaskCol
MethodList | ChildList | EventList
PropList |  |


Booking Class

    :Class Booking
        :Field Public OK
        :Field Public Course
        :Field Public TeeTime
        :Field Public Message

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          OK Course TeeTime Message←args
        ∇
        ∇ format
          :Implements Trigger OK,Message
          ⎕DF⍕Course TeeTime(⊃OK⌽Message'OK')
        ∇
    :EndClass


Brackets

() [] {}

Round brackets are used in APL expressions to control the order of execution. A right parenthesis is also used to introduce a System Command.

Parentheses ()

Square brackets are have two distinct meanings in APL. They are used to select sub-arrays from an n-dimensional array and to indicate an axis along which a function (operand) is to apply.

Bracket Indexing []

and

Bracket Axis Operator []

Curly brackets have two distinct meanings in Dyalog APL. They are used to indicate shy results and optional left arguments in defined functions. They are also used to enclose the definition of a dynamic function.

Braces in Defined Functions {}

and

Braces round Dynamic Functions {}

Language Elements


BrowseBox Events

Close | Create | FileBoxCancel
FileBoxOK |  |


BrowseBox Methods

Detach Wait


BrowseBox Properties

Type | Caption | BrowseFor
Target | StartIn | HasEdit
Event | Data | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


Button Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


Button Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Button Properties

Type | Caption | Posn
Size | Style | Coord
Align | State | Default
Cancel | Border | Justify
Active | Visible | Event
Sizeable | Dragable | FontObj
FCol | BCol | Picture
BtnPix | CursorObj | AutoConf
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | ReadOnly
Translate | Accelerator | AcceptFiles
KeepOnClose | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


Calendar Events

CalendarDblClick | CalendarDown | CalendarMove
CalendarUp | Close | Configure
ContextMenu | Create | DragDrop
DropFiles | DropObjects | Expose
FontCancel | FontOK | GetDayStates
GotFocus | Help | KeyPress
LostFocus | MouseDblClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | Select
SelDateChange |  |


Calendar: Example 1

'F'⎕WC'Form' 'Example 1' ('Size' 30 30)
'F.C'⎕WC'Calendar'


Calendar: Example 2

'F'⎕WC'Form' 'Example 2'('Size' 50 50)
'F.C'⎕WC'Calendar'('Size' 100 100)


Calendar: Example 3

'F'⎕WC'Form' 'Example 3'('Size' 30 30)
'F.C'⎕WC'Calendar'('CircleToday' 0)('HasToday' 0)('WeekNumbers' 1)


Calendar Methods

Animate | ChooseFont | DateToIDN
Detach | GetFocus | GetMinSize
GetTextSize | GetVisibleRange | IDNToDate
ShowSIP |  |


Calendar Properties

Type | Posn | Size
Style | Coord | Border
Active | Visible | Event
FirstDay | MaxSelCount | SelDate
MinDate | MaxDate | CalendarCols
Today | HasToday | CircleToday
WeekNumbers | MonthDelta | Sizeable
Dragable | FontObj | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Accelerator | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Categorised System Functions

System Functions

Functions, Operators & Namespaces

⎕AT | attributes
⎕CR | canonical representation
⎕CS | change (name)space
⎕CY | copy objects to active ws
⎕DF | display form
⎕ED | edit objects
⎕EX | expunge objects
⎕EXPORT | export objects
⎕FX | fix definition
⎕LOCK | lock object
⎕ML | migration level
⎕NC | name class
⎕NL | name list
⎕NR | nested representation
⎕NS | create namespace
⎕NSI | namespace indicator
⎕OR | object representation
⎕PATH | search path
⎕SIZE | size of objects
⎕THIS | this space
⎕USING | using (.net search path)
⎕VFI | verify & fix numerics
⎕VR | vector representation

System Functions

Input/Output

⍞ | character input/output
⎕ | evaluated input/output
⎕Á | underscored alphabet
⎕A | alphabet
⎕ARBIN | arbitrary input
⎕ARBOUT | arbitrary output
⎕AV | atomic vector
⎕AVU | atomic vector - unicode
⎕D | digits
⎕DL | delay
⎕FMT | format
⎕FMT(Dyadic) | format by specification
⎕NULL | null item
⎕RTL | response time limit
⎕SD | screen dimensions
⎕SM | screen map
⎕SR | screen read
⎕TC | terminal control characters
⎕UCS | unicode convert

System Functions

APL Files

⎕FAPPEND | append component
⎕FAVAIL | file system availability
⎕FCREATE | create file
⎕FDROP | drop components
⎕FERASE | erase file
⎕FHOLD | hold file
⎕FLIB | file library list
⎕FNAMES | tied file names
⎕FNUMS | tied file numbers
⎕FPROPS | file properties
⎕FRDAC | read file access matrix
⎕FRDCI | read file component information
⎕FREAD | read component
⎕FRENAME | rename file
⎕FREPLACE | replace component
⎕FRESIZE | resize file
⎕FSIZE | file size
⎕FSTAC | set file access matrix
⎕FSTIE | share tie file
⎕FTIE | tie file
⎕FUNTIE | untie files
⎕XT | query external variable
⎕XT(Dyadic) | set external variable

System Functions

Native Files

⎕DR | data representation (monadic)
⎕DR(Dyadic) | data representation (dyadic)
⎕NAPPEND | appends value to a native file
⎕NCREATE | creates a native file
⎕NERASE | erases a native file
⎕NLOCK | locks a native file
⎕NNAMES | reports names of all open native files
⎕NNUMS | reports tie numbers of all open native files
⎕NREAD | reads data from a native file
⎕NRENAME | renames a native file
⎕NREPLACE | writes data to a native file, overwriting existing data
⎕NRESIZE | changes the size of a native file
⎕NSIZE | reports the current size of a native file
⎕NTIE | opens a native file
⎕NUNTIE | closes one or more native files
⎕NXLATE | specifies/reports character translation for a native file

System Functions

Graphical User Interface

⎕DQ | await & process (dequeue) events
⎕NQ | place event in queue (enqueue)
⎕SE | session namespace
⎕WC | create windows object
⎕WG | get windows object properties
⎕WN | query child object names
⎕WS | set windows object properties
⎕WX | expose windows object properties

System Functions

Object Oriented Features

⎕BASE | base class
⎕CLASS | class
⎕DF | display form
⎕FIX | fix script
⎕INSTANCES | instances
⎕NEW | new instance
⎕SRC | source script
⎕THIS | this space

System Functions

Event Trapping

⎕DM | diagnostic message
⎕EM | event messages
⎕EN | event numbers
⎕EXCEPTION | exception
⎕SIGNAL | signal event
⎕TRAP | trap events

System Functions

MultiThreading

⎕TCNUMS | thread child numbers
⎕TGET | get tokens
⎕TID | current thread identity
⎕TKILL | kill thread
⎕TNAME | current thread name
⎕TNUMS | thread numbers
⎕TPOOL | token pool
⎕TPUT | put tokens
⎕TREQ | token requests
⎕TSYNC | wait for threads to terminate

System Functions

Shared Variables

⎕SVC | query access control
⎕SVC(Dyadic) | set access control
⎕SVO | query degree of coupling
⎕SVO(Dyadic) | shared variable offer
⎕SVQ | shared variable query
⎕SVR | retract offer
⎕SVS | shared variable state

System Functions

State Indicator, Stack

⎕LC | line count
⎕MONITOR | query monitor
⎕MONITOR(Dyadic) | set monitor
⎕NSI | namespace indicator
⎕REFS | local references
⎕SHADOW | shadow names
⎕SI | state indicator
⎕STACK | state indicator stack
⎕STATE | state of an object
⎕STOP | query stop vector
⎕STOP(Dyadic) | set stop vector
⎕TRACE | query trace vector
⎕TRACE(Dyadic) | set trace vector
⎕XSI | extended state indicator

System Functions

Workspace

⎕AI | account information
⎕AN | account name
⎕CLEAR | clear workspace
⎕CT | comparison tolerance
⎕DIV | division method
⎕IO | index origin
⎕KL | key label
⎕LOAD | load workspace
⎕LX | latent expression
⎕PFKEY | programmable function key
⎕PP | print precision
⎕PW | page width
⎕RL | random link
⎕SAVE | save workspace
⎕WA | workspace available
⎕WSID | workspace identification

System Functions

System Operations

⎕CMD | execute command
⎕CMD(Dyadic) | start auxiliary processor
⎕MAP | map file
⎕NA | name association
⎕OFF | sign off
⎕SH | execute command
⎕SH(Dyadic) | start auxiliary processor
⎕TS | time stamp


Categorised System Functions

Functions Operators & Namespaces

Input & Output

APL Files

Native Files

Graphical User Interface

Object Oriented Features

Event Trapping

MultiThreading

Shared Variables

State Indicator & Stack

Workspace

System Operations


Catenate To

Catenate To V,←A

This idiom optimises the catenation of a scalar or a vector to a vector. The performance gain is most significant when A is small.

Note that the idiom is not applied if the value of vector V is shared with another symbol in the workspace.

      V1←⍳10
      V1,←11
 The idiom is used to perform the catenation to V1.
      V1←⍳10
      V2←V1
      V1,←11
 The idiom is not used to perform the catenation to V1, because its value is at that point shared with V2.
     ∇ V←V Join A
[1]    V,←A
     ∇
      (⍳10) Join 11
1 2 3 4 5 6 7 8 9 10 11
 The idiom is not used to perform the catenation to V in Join[1] because its value is at that point shared with the array used to call the function


Circle

○

Monadic Circle means

Pi Times

      ○ 0 1 2
0 3.141592654 6.283185307

Dyadic Circle means

Circular Function

      1 ○ 0 1.5707963 3.1415927
0 1 ¯4.6410207E¯8

Language Elements


Circle Bar

×

Monadic Circle Bar means

Reverse First

      ⊖ 3 2⍴1 2 3 4 5 6
5 6
3 4
1 2

Dyadic Circle Bar means

Rotate First

      1 2 ⊖ 3 2⍴1 2 3 4 5 6
3 6
5 2
1 4

Language Elements


Circle Events

Close | Create | DragDrop
Help | MouseDblClick | MouseDown
MouseMove | MouseUp | Select


Circle Methods

Detach


Circle Properties

Type | Points | Radius
FCol | BCol | Start
End | ArcMode | LStyle
L | FStyle | FillCol
Coord | Visible | Event
Dragable | OnTop | CursorObj
AutoConf | Data | Accelerator
KeepOnClose | DrawMode | RadiusMode
MethodList | ChildList | EventList
PropList |  |


Circle Stile

⌽

Monadic Circle Stile means

Reverse

      ⌽ 8 2 5 6.6 ¯2
¯2 6.6 5 2 8

Dyadic Circle Stile means

Rotate

      1 2 ¯1 ⌽ 3 3⍴⍳9
2 3 1
6 4 5
9 7 8

Language Elements


Class Declaration Statements

:Access Statement
:Interface, :EndInterface Statements
:Class, :EndClass Statements
:Namespace, :EndNamespace Statements
:Implements Statement
:Using Statement
:Attribute Statement
:Field Statement

Property Section
:Property Statement
PropertyArguments Class
PropertyGet Function
PropertySet Function
PropertyShape Function


Class Identifier (CLSID)

The CLSID is a unique identifier that, when displayed, appears as a string of hexadecimal digits wrapped in braces; for example “{3B7C8860-D78F-101B-B9B5-04021C009402}”.


Classes

Introduction

Defining Classes

Editing Classes

Inheritance

Instances


Clipboard Events

ClipChange | Close | Create
Select |  |


Clipboard Methods

Detach Wait


Clipboard Properties

Type | Event | Data
Formats | Text | Bits
CMap | CBits | MetafileObj
Picture | Array | RTFText
Translate | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


code

0 or more lines of APL code, including other (nested) control structures


ColorButton Events

Close | ColorChange | Configure
ContextMenu | Create | DragDrop
DropDown | DropFiles | DropObjects
Expose | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel


ColorButton Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


ColorButton Properties

Type | Caption | Posn
Size | CurrentColor | DefaultColors
CustomColors | OtherButton | Coord
Active | Visible | Event
Sizeable | Dragable | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | KeepOnClose
ShowDropDown | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


COM data types

COM data type

The table below shows the correspondence between COM data types and APL arrays.

OLE DataType | APL array
VT_BOOL | numeric scalar
VT_I1 | numeric scalar
VT_I2 | numeric scalar
VT_I4 | numeric scalar
VT_R4 | numeric scalar
VT_R8 | numeric scalar
VT_BSTR | character vector
VT_CY | 2-element numeric vector
VT_DATE | 6 element numeric vector
VT_VARIANT | any array
VT_SAFEARRAY | any array (VT_ARRAY OF VT_VARIANT)
VT_DISPATCH | ⎕OR of a namespace
VT_COLOR | 3-element RGB

APL vectors may be described by pre-fixing the data type string with 'VT_ARRAY OF '. For example 'VT_ARRAY OF BSTR' specifies a vector of character vectors.

If the APL array is the ⎕OR of a namespace, its data type should be specified as 'VT_DISPATCH'.


Combo Events

Change | Close | Configure
ContextMenu | Create | DragDrop
DropDown | DropFiles | DropObjects
Expose | FontCancel | FontOK
GotFocus | Help | KeyPress
LostFocus | MouseDblClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | Select


Combo Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Combo Properties

Type | Items | Text
Posn | Size | Style
Coord | Rows | Border
Active | Visible | Event
VScroll | HScroll | SelItems
SelText | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Index
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


ComboEx Events

Close | Configure | ContextMenu
Create | DragDrop | DropDown
DropFiles | DropObjects | Expose
FontCancel | FontOK | GotFocus
Help | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Select |


ComboEx Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


ComboEx Properties

Type | Items | Text
Posn | Size | Style
Coord | Rows | Border
Active | Visible | Event
Indents | ImageListObj | ImageIndex
SelImageIndex | CaseSensitive | EditImage
EditImageIndent | PathWordBreak | VScroll
HScroll | SelItems | SelText
Sizeable | Dragable | FontObj
FCol | BCol | CursorObj
AutoConf | Index | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Comma

,

Monadic Comma means

Ravel

      , 2 2 2 2⍴3
3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3

Dyadic Comma means

Catenate/Laminate

      (2 3⍴9) , 2 4⍴8
9 9 9 8 8 8 8
9 9 9 8 8 8 8

Language Elements


Comma Bar

⌈>

Monadic Comma Bar is not defined

Dyadic Comma Bar means

Catenate First

      (3 2⍴9) ⍪ 4 2⍴8
9 9
9 9
9 9
8 8
8 8
8 8
8 8

Language Elements


ComponentFile Class

:Class ComponentFile
    :Field Private Instance tie

    ∇ Open filename
      :Implements Constructor
      :Access Public Instance
      :Trap 0
          tie←filename ⎕FTIE 0
      :Else
          tie←filename ⎕FCREATE 0
      :EndTrap
      ⎕DF filename,'(Component File)'
    ∇

    ∇ Close
      :Access Public Instance
      ⎕FUNTIE tie
    ∇

    ∇ r←Append data
      :Access Public Instance
      r←data ⎕FAPPEND tie
    ∇

    ∇ Replace(comp data)
      :Access Public Instance
      data ⎕FREPLACE tie,comp
    ∇

    :Property Count
    :Access Public Instance
        ∇ r←get
          r←¯1+2⊃⎕FSIZE tie
        ∇
    :EndProperty ⍝ Count

    :Property Access
    :Access Public Instance
        ∇ r←get arg
          r←⎕FRDAC tie
        ∇
        ∇ set am;mat;OK
          mat←am.NewValue
          :Trap 0
              OK←(2=⍴⍴mat)∧(3=2⊃⍴mat)∧∧/,mat=⌊mat
          :Else
              OK←0

          :EndTrap
          'bad arg'⎕SIGNAL(~OK)/11
          mat ⎕FSTAC tie
        ∇
    :EndProperty ⍝ Access

    :Property Files
    :Access Public Shared
        ∇ r←get
          r←⎕FLIB''
        ∇
    :EndProperty

    :Property Numbered Default Component
    :Access Public Instance
        ∇ r←shape args
          r←¯1+2⊃⎕FSIZE tie
        ∇
        ∇ r←get arg
          r←⊂⎕FREAD tie,arg.Indexers
        ∇
        ∇ set arg
          arg.NewValue ⎕FREPLACE tie,arg.Indexers

        ∇
    :EndProperty

    ∇ Delete file;tie
      :Access Public Shared
      tie←file ⎕FTIE 0
      file ⎕FERASE tie
    ∇
:EndClass ⍝ Class ComponentFile


Constructor Overload Example Class

Constructor Overload Example

:Class Clover ⍝ Constructor Overload Example
    :Field Public Con
    ∇ Make0
      :Access Public
      :Implements Constructor
      make 0
    ∇
    ∇ Make1(arg)
      :Access Public
      :Implements Constructor
      make arg
    ∇
    ∇ Make2(arg1 arg2)
      :Access Public
      :Implements Constructor
      make arg1 arg2
    ∇
    ∇ Make3(arg1 arg2 arg3)
      :Access Public
      :Implements Constructor
      make arg1 arg2 arg3
    ∇
    ∇ MakeAny args
      :Access Public
      :Implements Constructor
      make args
    ∇
    ∇ make args
      Con←(⍴args)(2⊃⎕SI)args
    ∇
:EndClass ⍝ Clover


Constructors and Destructors

Introduction
Constructor Overloading
Niladic (Default) Constructors
Empty Arrays of Instances: Why?
Empty Arrays of Instances: How?
Base Constructors
Niladic Example
Monadic Example
Destructors


Control Structures TOC

Control Structures

Benefits
Introduction
:If | :GoTo
:While | :Return
:Repeat | :Leave
:For | :Continue
:Select | :Hold
:With | :Trap


CoolBand Events

Close | Create | DockAccept
DockCancel | DockEnd | DockMove
DockRequest | DockStart |


CoolBand Methods

Detach


CoolBand Properties

Type | Caption | Posn
Size | Visible | Event
ImageIndex | FCol | BCol
Picture | Index | Data
KeepOnClose | ChildEdge | NewLine
GripperMode | Dockable | UndocksToRoot
MethodList | ChildList | EventList
PropList |  |


CoolBar Events

Close | Configure | ContextMenu
Create | DockAccept | DockCancel
DockEnd | DockMove | DockRequest
DockStart | DragDrop | DropFiles
DropObjects | Expose | Help


CoolBar: Example 1

'F'⎕WC'Form' 'CoolBar Object with ToolControls'('Size' 25 50)
'F.IL'⎕WC'ImageList'('Masked' 0)('MapCols' 1)
'F.IL.'⎕WC'Bitmap'('ComCtl32' 120)⍝ STD_SMALL

'F.CB'⎕WC'CoolBar'

:With 'F.CB.C1'⎕WC'CoolBand'
    'TB'⎕WC'ToolControl'('ImageListObj' '#.F.IL')
    'TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
    'TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
    'TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)
:EndWith

:With 'F.CB.C2'⎕WC'CoolBand'
    'TB'⎕WC'ToolControl'('ImageListObj' '#.F.IL')
    'TB.B1'⎕WC'ToolButton' 'Cut'('ImageIndex' 1)
    'TB.B2'⎕WC'ToolButton' 'Copy'('ImageIndex' 2)
    'TB.B3'⎕WC'ToolButton' 'Paste'('ImageIndex' 3)
    'TB.B4'⎕WC'ToolButton' 'Undo'('ImageIndex' 4)
    'TB.B5'⎕WC'ToolButton' 'Redo'('ImageIndex' 5)
:EndWith

after user has moved band 2 into row 1

after user has maximised band 1

after user has maximised band 2


CoolBar: Example 2

'F'⎕WC'Form' 'CoolBar Object with simple controls'('Size' 25 40)
'F'⎕WS'Coord' 'Pixel'

'F.CB'⎕WC'CoolBar'

:With 'F.CB.C1'⎕WC'CoolBand'
    'E1'⎕WC'Edit' 'Edit1'
:EndWith

:With 'F.CB.C2'⎕WC'CoolBand'
    'C1'⎕WC'Combo'('One' 'Two' 'Three')('SelItems' 0 1 0)
:EndWith

:With 'F.CB.C3'⎕WC'CoolBand'
    'E2'⎕WC'Edit'(3 5⍴'Edit2')('Style' 'Multi')
:EndWith


CoolBar Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


CoolBar Properties

Type | Posn | Size
Align | Event | ImageListObj
FCol | BCol | CursorObj
Data | Attach | Handle
KeepOnClose | BandBorders | DblClickToggle
FixedOrder | VariableHeight | DockChildren
Redraw | MethodList | ChildList
EventList | PropList |


Cursor Events

Close Create Select


Cursor Methods

Detach FileRead FileWrite


Cursor Properties

Type | File | Bits
CMap | Mask | HotSpot
KeepBits | Event | Data
Handle | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Data Representation

⎕DR

Monadic ⎕DR means

Query Data Representation

      ⎕DR 1 2 3
83
      ⎕DR 1 0 0
11

Dyadic ⎕DR means

Set Data Representation

      11 ⎕DR 'AB'
0 1 0 0 0 0 0 1 0 1 0 0 0 0 1 0

Language Elements


DateTimePicker Events

Close | CloseUp | Configure
ContextMenu | Create | DateTimeChange
DragDrop | DropDown | DropFiles
DropObjects | Expose | FontCancel
FontOK | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


DateTimePicker Methods

Animate | ChooseFont | DateToIDN
Detach | GetFocus | GetTextSize
IDNToDate | ShowSIP |


DateTimePicker Properties

Type | Posn | Size
Style | Coord | Align
Border | Active | Visible
Event | DateTime | MinDate
MaxDate | CalendarCols | Today
HasToday | CircleToday | WeekNumbers
MonthDelta | HasCheckBox | FieldType
CustomFormat | Sizeable | Dragable
FontObj | CursorObj | AutoConf
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Decode Symbol

Decode;Up Tack

⊥

Monadic Decode is not defined

Dyadic Decode means

Decode;Base Value

      2 ⊥ 2 3⍴0 1 1 1 0 1
1 2 3

Language Elements


DeleteTypeLib Method

DeleteTypeLibMethod 521

Applies to: Root

The DeleteTypeLib method removes a loaded Type Library from the workspace.

The argument to DeleteTypeLib is as follows:

[1] TypeLib character vector

The Type Library may be identified by its name or by its class id.

The result is 0, 1 or ¯1.

If successful, the specified Type Library, and all dependant Type Libraries not referenced by any other currently loaded Type Libraries, are removed from the active workspace. The result is 1.

If the specified Type Library is in use, no action is taken and the result is 0.

If the argument is not the name or CLSID of a loaded Type Library, no action is taken and the result is ¯1.


Denormal Numbers

Numbers, very close to zero, in the range 2.2250738585072009E¯308 to 4.9406564584124654E¯324 are called denormal numbers.

Such numbers can occur as the result of calculations and are displayed correctly. However, denormals cannot be specified as literals and are converted to zero on input.

Numbers below the lower end of this range (4.94E¯324) are indistinguishable from zero in IEEE double floating point format.


DiaryStuff Example Namespace

:Namespace DiaryStuff
:Using System

    :Class DiaryEntry
        :Field Public When
        :Field Public What
        ∇ Make(ymdhm wot)
          :Access Public
          :Implements Constructor
          When What←(⎕NEW DateTime(6↑5↑ymdhm))wot
          ⎕DF⍕When What
        ∇
        ∇ Make0
          :Access Public
          :Implements Constructor
          When What←⎕NULL''
        ∇
    :EndClass ⍝ DiaryEntry

    :Class Diary
        :Field Private entries←0⍴⎕NEW DiaryEntry
        ∇ R←Add(ymdhm wot)
          :Access Public
          R←⎕NEW DiaryEntry(ymdhm wot)
          entries,←R
        ∇
        ∇ R←DoingOn ymd;X
          :Access Public
          X←,(↑entries.When.(Year Month Day))∧.=3 1⍴3↑ymd
          R←X/entries
        ∇
        ∇ R←Remove ymdhm;X
          :Access Public
          :If R←∨/X←entries.When=⎕NEW DateTime(6↑5↑ymdhm)
              entries←(~X)/entries
          :EndIf
        ∇
        :Property Numbered Default Entry
            ∇ R←Shape
              R←⍴entries
            ∇
            ∇ R←Get arg
              R←arg.Indexers⊃entries
            ∇
            ∇ Set arg
              entries[arg.Indexers]←arg.NewValue
            ∇
        :EndProperty
    :EndClass ⍝ Diary

:EndNamespace


Dieresis

¨

Dieresis is a Monadic operator with an ambivalent operand

Operator Dieresis means

Each

      ⊃¨ 1 2 3 'ABC' (9 8 7)
1 2 3 A 9

Each

      3 ↑¨ 1 2 3 (2 3) 'A'
 1 0 0  2 0 0  3 0 0  2 3 0  A

Language Elements


Dieresis Tilde

⍨

Dieresis Tilde is a Monadic operator with a Dyadic operand

Operator Dieresis Tilde means

Commute

      3.1243 -⍨ 4.1234 1 0
0.9991 ¯2.124 ¯3.124

Language Elements


DieresisStar

⍣

DieresisStar is a Dyadic operator with an ambivalent left operand and an integer or dyadic right operand

Operator DieresisStar means

Power Operator

      (↓⍣1)  2 2 2 2⍴⎕a     ⍝ split once.
 AB  CD
 EF  GH

 IJ  KL
 MN  OP

      (↓⍣2)  2 2 2 2⍴⎕a     ⍝ split twice.
  AB  CD    EF  GH
  IJ  KL    MN  OP

      (↓⍣3)  2 2 2 2⍴⎕a     ⍝ split thrice
   AB  CD    EF  GH      IJ  KL    MN  OP

      1+∘÷⍣=1               ⍝ Golden Mean
1.618033989

      f←(32∘+)∘(×∘1.8)      ⍝ Fahrenheit from Celsius

      f ¯273 ¯40 0 100
¯459.4 ¯40 32 212

      c←f⍣¯1                ⍝ inverse: Celsius from Fahrenheit

      c ¯459.4 ¯40 32 212

¯273 ¯40 0 100

Language Elements


Divide Sign

÷

Monadic Divide Sign means

Reciprocal

      ÷ 1 2 3
1 0.5 0.33333333

Dyadic Divide Sign means

Divided By

      1 2 3 4 ÷ 5 6 7 8
0.2 0.33333333 0.42857142 0.5

Language Elements


Domino

Domino;Quad Divide

⌹

Monadic Domino means

Matrix Inverse Of

      ⌹ (2 2⍴1 2 3 4)
¯2    1
 1.5 ¯0.5

Dyadic Domino means

Matrix Division By

      5 6 ⌹ 2 2⍴1 2 3 4
¯4 4.5

Language Elements


DOS Command

Windows Command

⎕CMD

Monadic ⎕CMD means

Execute Command

      ⎕CMD 'set'
PROMPT=$P$G
PATH=c:\Dyalog82\;C:\WINDOWS
MSINPUT=C:\MSINPUT
TEMP=C:\TEMP
TMP=C:\TMP
CLASSPATH=;C:\Exceed95

Dyadic ⎕CMD means

Start Auxiliary Processor

      'XUTILS' ⎕CMD ''

Language Elements


Dot

Dot;Full Stop;Decimal Point

.

Dot can be used as a Dyadic operator with Dyadic operands

Operator Dot means

Inner Product;Dot

      (4 3⍴1 2) +.× 3 5⍴3 4 5
17 15 16 17 15
19 21 20 19 21
17 15 16 17 15
19 21 20 19 21

Used with Jot in place of the left operand Jot Dot means

Outer Product;Jot Dot

      1 2 3 ∘.× 1 2 3 4
1 2 3  4
2 4 6  8
3 6 9 12

Language Elements

NB Dot is also used as a decimal decimal point and as a name separator in namespace reference syntax.


Down Arrow

↓

Monadic Down Arrow means

Split

      ↓ 3 3⍴1 2 3 4
 1 2 3  4 1 2  3 4 1

Dyadic Down Arrow means

Drop

      1 1 ↓ 3 3⍴1 2 3 4 5 6
5 6
2 3

Language Elements


Downstile

⌊

Monadic Downstile means

Floor

      ⌊ 3.4 ¯2.1 8.1 3 0
3 ¯3 8 3 0

Dyadic Downstile means

Minimum

      3  1.1 ¯2 ⌊ 3.4  8.1 ¯3.44
3 1.1 ¯3.44

Language Elements


Dual Example Class

Dual Class Example

:Class Dual: 'SubForm'
    :Include GUITools
    :Field Private _Caption1←''
    :Field Private _Caption2←''
    :Field Private _Value1←0
    :Field Private _Value2←0
    :Field Private _Range←0
    :Field Private _Intercept←0
    :Field Private _Gradient←1
    :Field Private _Height←40

    ∇ Create args;H;W;POS;SH;CH;Y1;Y2;BaseArgs;MyArgs;Defaults
      :Access Public
      MyArgs BaseArgs←SplitNV args
      :Implements Constructor :Base BaseArgs,⊂'EdgeStyle' 'Dialog'
      ExecNV_ MyArgs ⍝ Set Fields named _PropertyName in MyArgs
      Coord←'Pixel'
      H W←Size
      POS←2↑⌊0.5×0⌈(H-_Height)
      CH←⊃GetTextSize'W'
      'Slider'⎕WC'TrackBar'POS('Size'_Height W)
      Slider.(Limits AutoConf)←_Range 0
      Slider.(TickSpacing TickAlign)←10 'Top'
      Slider.onThumbDrag←'ChangeValue'
      Slider.onScroll←'ChangeValue'
      Y1←POS[1]-CH+1
      Y2←POS[1]+_Height+1
      'Caption1_'⎕WC'Text'_Caption1(Y1,0)('AutoConf' 0)
      'Caption2_'⎕WC'Text'_Caption2(Y2,0)('AutoConf' 0)
      'Value1_'⎕WC'Text'(⍕_Value1)(Y1,W)('HAlign' 2)('AutoConf' 0)
      CalcValue2
      'Value2_'⎕WC'Text'(⍕_Value2)(Y2,W)('HAlign' 2)('AutoConf' 0)
      onConfigure←'Configure'
    ∇
    :Property Caption1, Caption2
    :Access Public
        ∇ R←Get arg
          R←(arg.Name,'_')⎕WG'Text'
        ∇
        ∇ Set arg
          (arg.Name,'_')⎕WS'Text'arg.NewValue
        ∇
    :EndProperty

    :Property Value1
    :Access Public
        ∇ R←Get
          R←_Value1
        ∇
        ∇ Set arg
          ⎕NQ'Slider' 'Scroll' 0 arg.NewValue
        ∇
    :EndProperty

    :Property Intercept, Gradient, Range, Height, Value2
    :Access Public
        ∇ R←Get arg
          R←⍎'_',arg.Name
        ∇
    :EndProperty

    ∇ CalcValue2
      _Value2←_Intercept+_Gradient×_Value1
    ∇

    ∇ ChangeValue MSG
      ⍝ Callback for ThumbDrag and Scroll
      _Value1←⊃¯1↑MSG
      CalcValue2
      Value1_.Text←⍕_Value1
      Value2_.Text←⍕_Value2
    ∇

    ∇ Configure MSG;H;W;POS;CH;Y1;Y2
      2 ⎕NQ MSG
      H W←Size
      POS←2↑⌊0.5×(H-_Height)
      CH←⊃GetTextSize'W'
      Slider.(Posn Size)←POS(_Height W)
      Y1←POS[1]-CH+1
      Y2←POS[1]+_Height+1
      Caption1_.Points←1 2⍴Y1,0
      Caption2_.Points←1 2⍴Y2,0
      Value1_.Points←1 2⍴Y1,W
      Value1_.Points←1 2⍴Y2,W
    ∇

:EndClass ⍝ Dual


Dynamic Functions and Operators

Introduction

Multi-Line Dynamic Functions

Default Left Argument

Guards

Shy Results

Static Name Scope

Error Guards

Tail Calls

Recursion

Operators

Restrictions


Edit Events

BadValue | Change | Close
Configure | ContextMenu | Create
DragDrop | DropFiles | DropObjects
Expose | FontCancel | FontOK
GotFocus | Help | KeyError
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


Edit Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Edit Properties

Type | Text | Posn
Size | Style | Coord
Border | Justify | Active
Visible | Event | VScroll
HScroll | SelText | Sizeable
Dragable | FontObj | FCol
BCol | CursorObj | AutoConf
Data | Attach | TextSize
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
FieldType | MaxLength | Decimals
Password | ValidIfEmpty | ReadOnly
FormatString | Changed | Value
Translate | Accelerator | AcceptFiles
WantsReturn | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Ellipse Events

Close | Create | DragDrop
Help | MouseDblClick | MouseDown
MouseMove | MouseUp | Select


Ellipse Methods

Detach


Ellipse Properties

Type | Points | Size
FCol | BCol | Start
End | ArcMode | LStyle
L | FStyle | FillCol
Coord | Visible | Event
Dragable | OnTop | CursorObj
AutoConf | Data | Accelerator
KeepOnClose | DrawMode | MethodList
ChildList | EventList | PropList


Encode Symbol

Encode;Down Tack

⊤

Monadic Encode is not defined

Dyadic Encode means

Encode;Representation

      2 2 2 2 2 2 ⊤ 8 16 32
0 0 1
0 1 0
1 0 0
0 0 0
0 0 0
0 0 0

Language Elements


Epsilon

∊

Monadic Epsilon means

If ⎕ML=0 Type Of

      ∊ 3 3⍴1 'abc'
   0         0
        0
   0         0

If ⎕ML≥1 Enlist

      ∊ 3 3⍴1 'abc'
1 abc 1 abc 1 abc 1 abc 1

Dyadic Epsilon means

Member Of

      'abc' 1.1 ∊ 1.1 'ab' 'abcd'
0 1

Language Elements


Epsilon Underbar

⍷

Monadic Epsilon Underbar is not defined

Dyadic Epsilon Underbar means

Find

      0 0 ⍷ 4 4⍴0 1 0
0 0 1 0
0 1 0 0
1 0 0 0
0 0 1 0

Language Elements


Equal Sign

=

Monadic Equal Sign is not defined

Dyadic Equal Sign means

Equals

      2 = (2 2 2⍴1 2 3)
0 1
0 0

1 0
0 1

Language Elements


Equal Underbar

Equal Underbar;Equivalent

≡

Monadic Equal Underbar means

Depth Of

      ≡ 1 (1 2)('ab' 'def')
¯3

NB Result is always positive if ⎕ML is greater than or equal to 2.

Dyadic Equal Underbar means

Matchs

      'b' 'e' 'x'≡  'bex'
1

Language Elements


Equal Underbar Slash

Not Equal Underbar;Inequivalent

≢

Monadic Not Equal Underbar is not defined

Dyadic Not Equal Underbar means

Does Not Match;Natch

      'bex' ≢ 'b','e','x'
0

Language Elements


Exclamation Mark

Exclamation Mark;Quote Dot

!

Monadic Exclamation Mark means

Factorial

      ! 3 10 ¯0.11
6 3628800 1.076830683

Dyadic Exclamation Mark means

Binomial

      2 1 3 ! 3 10 ¯0.11
3 10 ¯0.0429385

Language Elements


Execute Symbol

Execute;Hydrant;Up Tack Jot

⍎

Monadic Execute means

Execute

      ⍎ '1+1⋄2+2'
2
4

Dyadic Execute means

Namespace Execute

      '#' ⍎ '⎕PP ⎕CT ⎕RL'
10 1E¯14 1131570933

Language Elements


Fields

Introduction

Public Fields

Initialising Fields

Private Fields

Shared Fields

Trigger Fields


FileBox Events

Close | Create | FileBoxCancel
FileBoxOK | Select |


FileBox Methods

Detach Wait


FileBox Properties

Type | Caption | Directory
Filters | File | FileMode
Style | Event | Index
Data | EdgeStyle | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Fill Items and Prototypes

Every array has an associated prototype which is derived from the array's first item. If the first item is a (ref to) an Instance of a Class, the prototype is a ref to that Class.

Fill items for an overtake operation, are derived from the argument's prototype.

For each Class reference in the prototype, there is a ref to a (newly constructed and distinct) instance of that Class that is initialised by the niladic (default) constructor for that Class, if defined.

      2↑⎕NEW MyClass
 #.[Instance of MyClass]  #.[Instance of MyClass]

Note that in the above example, two distinct instances are constructed (the first by ⎕NEW and the second by the overtake).

Fill items are used in a number of operations including:

  • First (⊃ or ↑) of an empty array

  • Fill-elements for overtake

  • For use with the Each operator on an empty array


Font Events

Close | Create | FontCancel
FontOK | Select |


Font Methods

ChooseFont Detach


Font Properties

Type | PName | Size
Fixed | Italic | Underline
Weight | Rotate | CharSet
Data | Handle | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


FontCancel Event

FontCancel Event 242

Applies to: ActiveXControl, Button, Calendar, Combo, ComboEx, DateTimePicker, Edit, Font, Form, Grid, Group, Label, List, ListView, PropertyPage, PropertySheet, RichEdit, Root, Spinner, Static, StatusBar, SubForm, TabBtn, Text, TipField, TreeView

Description

If enabled, this event is reported when the user has pressed the Cancel button or closed the font selection dialog box that is displayed by the ChooseFont method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 2-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'FontCancel' or 242


FontOK Event

FontOK Event 241

Applies to: BrowseBox, FileBox

Description

If enabled, this event is reported when the user has pressed the OK button in the font selection dialog box that is displayed by the ChooseFont method.

The event message reported as the result of ⎕DQ, or supplied as the right argument to your callback function, is a 4-element vector as follows :

[1] | Object name | character vector
[2] | Event code | 'FontOK' or 241
[3] | Font | nested vector
[4] | Colour | RGB triplet

The font specification in the 3rd element of the event message is a 7-element nested vector that describes the chosen font. See Font Object for further details.

The colour specification in the 4th element of the event message is a 3-element integer vector of RGB values for the colour chosen by the user.


:For Statement Definition

:For Statement

For:
       |
       :For varvar :In[Each] aexp
       |
       code
       |
       :End[For]
       |


Form Events

Close | Configure | ContextMenu
Create | DockAccept | DockCancel
DockEnd | DockMove | DockRequest
DockStart | DragDrop | DropFiles
DropObjects | DyalogCustomMessage1 | Expose
FontCancel | FontOK | FrameContextMenu
GotFocus | Help | HScroll
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select | StateChange | VScroll


Form Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | Wait


Form Properties

Type | Caption | Posn
Size | Coord | State
Border | Active | Visible
Event | Thumb | Range
Step | VScroll | HScroll
Sizeable | Moveable | SysMenu
MaxButton | MinButton | HelpButton
OKButton | SIPMode | SIPResize
FontObj | BCol | Picture
OnTop | IconObj | CursorObj
AutoConf | YRange | XRange
Data | TextSize | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Dockable | Docked | DockShowCaption
DockChildren | UndocksToRoot | MaskCol
AlphaBlend | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


GetCourses Method

    ∇ R←GetCourses;COURSECODES;COURSES;INDEX
      :Access Public
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      R←{⎕NEW GolfCourse ⍵}¨↓⍉↑COURSECODES COURSES
    ∇


GetStartingSheet Method

    ∇ R←GetStartingSheet ARGS;CODE;COURSE;DATE;COURSECODES;COURSES;INDEX;COURSEI;IDN;DATES;COMPS;IDATE;TEETIMES;GOLFERS;I;T
      :Access Public
      CODE DATE←ARGS
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      COURSEI←COURSECODES⍳CODE
      COURSE←⎕NEW GolfCourse(CODE(COURSEI⊃COURSES,⊂''))
      R←⎕NEW StartingSheet(0 COURSE DATE)
      :If COURSEI>⍴COURSECODES
          R.Message←'Invalid course code'
          :Return
      :EndIf
      IDN←2 ⎕NQ'.' 'DateToIDN',DATE.(Year Month Day)
      DATES COMPS←⎕FREAD GOLFID,COURSEI⊃INDEX
      IDATE←DATES⍳IDN
      :If IDATE>⍴DATES
          R.Message←'No Starting Sheet available'
          :Return
      :EndIf
      TEETIMES GOLFERS←⎕FREAD GOLFID,IDATE⊃COMPS
      T←DateTime.New¨(⊂DATE.(Year Month Day)),¨↓[1]24 60 1⊤TEETIMES
      R.Slots←{⎕NEW Slot ⍵}¨T,∘⊂¨↓GOLFERS
      R.OK←1
    ∇


Globally Unique Identifier (GUID)

GUID

A Globally Unique Identifier (GUID) is a 128-bit number that is generated by a special algorithm and is virtually guaranteed a to be unique in the world. That is to say that every GUID generated by this algorithm is different from any other.

Dyalog APL properties that represent GUIDs are read-only character vectors that represent the GUID as a string of hexadecimal digits wrapped in braces.

For example “{3B7C8860-D78F-101B-B9B5-04021C009402}”.


GolfCourse Class

    :Class GolfCourse
        :Field Public Code←¯1
        :Field Public Name←''

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          Code Name←args
          ⎕DF Name,'(',(⍕Code),')'
        ∇

    :EndClass


GolfService Example Class

:Class GolfService
:Using System

    :Field Private GOLFILE←'' ⍝ Name of Golf data file
    :Field Private GOLFID←0 ⍝ Tie number for Golf data file

    :Class GolfCourse
        :Field Public Code←¯1
        :Field Public Name←''

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          Code Name←args
          ⎕DF Name,'(',(⍕Code),')'
        ∇

    :EndClass

    :Class Slot
        :Field Public Time
        :Field Public Players

        ∇ ctor1 t
          :Implements Constructor
          :Access Public Instance
          Time←t
          Players←0⍴⊂''
        ∇
        ∇ ctor2 (t pl)
          :Implements Constructor
          :Access Public Instance
          Time Players←t pl
        ∇
        ∇ format
          :Implements Trigger Players
          ⎕DF⍕Time Players
        ∇
    :EndClass

    :Class Booking
        :Field Public OK
        :Field Public Course
        :Field Public TeeTime
        :Field Public Message

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          OK Course TeeTime Message←args
        ∇
        ∇ format
          :Implements Trigger OK,Message
          ⎕DF⍕Course TeeTime(⊃OK⌽Message'OK')
        ∇
    :EndClass

    :Class StartingSheet
        :Field Public OK
        :Field Public Course
        :Field Public Date
        :Field Public Slots←⎕NULL
        :Field Public Message

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          OK Course Date←args
        ∇
        ∇ format
          :Implements Trigger OK,Message
          ⎕DF⍕2 1⍴(⍕Course Date)(↑⍕¨Slots)
        ∇
    :EndClass

    ∇ ctor file
      :Implements Constructor
      :Access Public Instance
      GOLFILE←file
      ⎕FUNTIE(((↓⎕FNAMES)~' ')⍳⊂GOLFILE)⊃⎕FNUMS,0
      :Trap 22
          GOLFID←GOLFILE ⎕FTIE 0
      :Else
          InitFile
      :EndTrap
    ∇

    ∇ dtor
      :Implements Destructor
      ⎕FUNTIE GOLFID
    ∇

    ∇ InitFile;COURSECODES;COURSES;INDEX;I
      :Access Public
      :If GOLFID≠0
          GOLFILE ⎕FERASE GOLFID
      :EndIf
      GOLFID←GOLFILE ⎕FCREATE 0
      COURSECODES←1 2 3
      COURSES←'St Andrews' 'Hindhead' 'Basingstoke'
      INDEX←(⍴COURSES)⍴0
      COURSECODES COURSES INDEX ⎕FAPPEND GOLFID
      :For I :In ⍳⍴COURSES
          INDEX[I]←⍬ ⍬ ⎕FAPPEND 1
      :EndFor
      COURSECODES COURSES INDEX ⎕FREPLACE GOLFID 1
    ∇

    ∇ R←GetCourses;COURSECODES;COURSES;INDEX
      :Access Public
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      R←{⎕NEW GolfCourse ⍵}¨↓⍉↑COURSECODES COURSES
    ∇

    ∇ R←GetStartingSheet ARGS;CODE;COURSE;DATE;COURSECODES;COURSES;INDEX;COURSEI;IDN;DATES;COMPS;IDATE;TEETIMES;GOLFERS;I;T
      :Access Public
      CODE DATE←ARGS
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      COURSEI←COURSECODES⍳CODE
      COURSE←⎕NEW GolfCourse(CODE(COURSEI⊃COURSES,⊂''))
      R←⎕NEW StartingSheet(0 COURSE DATE)
      :If COURSEI>⍴COURSECODES
          R.Message←'Invalid course code'
          :Return
      :EndIf
      IDN←2 ⎕NQ'.' 'DateToIDN',DATE.(Year Month Day)
      DATES COMPS←⎕FREAD GOLFID,COURSEI⊃INDEX
      IDATE←DATES⍳IDN
      :If IDATE>⍴DATES
          R.Message←'No Starting Sheet available'
          :Return
      :EndIf
      TEETIMES GOLFERS←⎕FREAD GOLFID,IDATE⊃COMPS
      T←DateTime.New¨(⊂DATE.(Year Month Day)),¨↓[1]24 60 1⊤TEETIMES
      R.Slots←{⎕NEW Slot ⍵}¨T,∘⊂¨↓GOLFERS
      R.OK←1
    ∇

    ∇ R←MakeBooking ARGS;CODE;COURSE;SLOT;TEETIME;COURSECODES;COURSES;INDEX;COURSEI;IDN;DATES;COMPS;IDATE;TEETIMES;GOLFERS;OLD;COMP;HOURS;MINUTES;NEAREST;TIME;NAMES;FREE;FREETIMES;I;J;DIFF
      :Access Public
      ⍝ If GimmeNearest is 0, books (or fails) for specified time
      ⍝ If GimmeNearest is 1, books (or fails) for nearest to specified time
      CODE TEETIME NEAREST←3↑ARGS
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      COURSEI←COURSECODES⍳CODE
      COURSE←⎕NEW GolfCourse(CODE(COURSEI⊃COURSES,⊂''))
      SLOT←⎕NEW Slot TEETIME
      R←⎕NEW Booking(0 COURSE SLOT'')
      :If COURSEI>⍴COURSECODES
          R.Message←'Invalid course code'
          :Return
      :EndIf
      :If TEETIME.Now>TEETIME
          R.Message←'Requested tee-time is in the past'
          :Return
      :EndIf
      :If TEETIME>TEETIME.Now.AddDays 30
          R.Message←'Requested tee-time is more than 30 days from now'
          :Return
      :EndIf
      IDN←2 ⎕NQ'.' 'DateToIDN',TEETIME.(Year Month Day)
      DATES COMPS←⎕FREAD GOLFID,COURSEI⊃INDEX
      IDATE←DATES⍳IDN
      :If IDATE>⍴DATES
          TEETIMES←(24 60⊥7 0)+10×¯1+⍳1+8×6 ⍝ 10 minute intervals, 07:00 to 15:00
          GOLFERS←((⍴TEETIMES),4)⍴⊂''       ⍝ up to 4 golfers allowed per tee time
          :If 0=OLD←⊃(DATES<2 ⎕NQ'.' 'DateToIDN',3↑⎕TS)/⍳⍴DATES
              COMP←(TEETIMES GOLFERS)⎕FAPPEND GOLFID
              DATES,←IDN
              COMPS,←COMP
              (DATES COMPS)⎕FREPLACE GOLFID,COURSEI⊃INDEX
          :Else
              DATES[OLD]←IDN
              (TEETIMES GOLFERS)⎕FREPLACE GOLFID,COMP←OLD⊃COMPS
              DATES COMPS ⎕FREPLACE GOLFID,COURSEI⊃INDEX
          :EndIf
      :Else
          COMP←IDATE⊃COMPS
          TEETIMES GOLFERS←⎕FREAD GOLFID COMP
      :EndIf
      HOURS MINUTES←TEETIME.(Hour Minute)
      NAMES←(3↓ARGS)~⍬''
      TIME←24 60⊥HOURS MINUTES
      TIME←10×⌊0.5+TIME÷10                     ⍝ Round to nearest 10-minute interval
      :If ~NEAREST
          I←TEETIMES⍳TIME
          :If I>⍴TEETIMES
          :OrIf (⍴NAMES)>⊃,/+/0=⍴¨GOLFERS[I;]
              R.Message←'Not available'
              :Return
          :EndIf
      :Else
          :If ~∨/FREE←(⍴NAMES)≤⊃,/+/0=⍴¨GOLFERS
              R.Message←'Not available'
              :Return
          :EndIf
          FREETIMES←(FREE×TEETIMES)+32767×~FREE
          DIFF←|FREETIMES-TIME
          I←DIFF⍳⌊/DIFF
      :EndIf
      J←(⊃,/0=⍴¨GOLFERS[I;])/⍳4
      GOLFERS[I;(⍴NAMES)↑J]←NAMES
      (TEETIMES GOLFERS)⎕FREPLACE GOLFID COMP
      TEETIME←DateTime.New TEETIME.(Year Month Day),3↑24 60⊤I⊃TEETIMES
      SLOT.Time←TEETIME
      SLOT.Players←(⊃,/0<⍴¨GOLFERS[I;])/GOLFERS[I;]
      R.(OK TeeTime)←1 SLOT
    ∇

:EndClass


Grade Down

Grade Down;Del Stile

⍒

Monadic Grade Down means

Grade Down

      ⍒ 3 1 4 6 2
4 3 1 5 2

Dyadic Grade Down means

Collated Grade Down

      'ABCDEFG' ⍒ 'CDEDEDE'
3 5 7 2 4 6 1

Language Elements


Grade Up

Grade Up;Delta Stile

⍋

Monadic Grade Up means

Grade Up

      ⍋ 3 1 4 6 2
2 5 1 3 4

Dyadic Grade Up means

Collated Grade Up

      'ABCDEFG'⍋'CDEDEDE'
1 2 4 6 3 5 7

Language Elements


Greater Than Or Equal To Sign

≥

Monadic Greater Than or Equal To Sign is not defined

Dyadic Greater Than or Equal To Sign means

Is Greater Or Equal To

      (1 2⍴2 ¯8) ≥ (1 2⍴2 2)
1 0

Language Elements


Greater Than Sign

>

Monadic Greater Than Sign is not defined

Dyadic Greater Than Sign means

Is Greater Than

      2 ¯8 2 5 4 > 2 2 ¯2 0 8
0 0 1 1 0

Language Elements


Grid Events

AddCol | AddRow | CellChange
CellChanged | CellDblClick | CellDown
CellError | CellMove | CellOver
CellUp | ClickComment | Close
Configure | ContextMenu | Create
DragDrop | DropFiles | DropObjects
Expanding | Expose | FontCancel
FontOK | GotFocus | GridCopy
GridCut | GridDelete | GridDropSel
GridKeyPress | GridPaste | GridPasteError
GridSelect | Help | HideComment
IndexChanged | KeyPress | LostFocus
MouseEnter | MouseLeave | MouseWheel
Retracting | Select | SetColSize
SetRowSize | ShowComment |


Grid Methods

AddComment | Animate | CellFromPoint
ChooseFont | ColChange | ColSorted
DelCol | DelComment | DelRow
Detach | DuplicateColumn | DuplicateRow
GetCellRect | GetComment | GetFocus
GetTextSize | LockColumns | LockRows
RowChange | RowSetVisibleDepth | SetCellSet
SetCellType | ShowSIP | Undo


Grid Properties

Type | Values | Posn
Size | FCol | BCol
Coord | Border | Active
Visible | Event | VScroll
HScroll | SelItems | Sizeable
Dragable | FontObj | CursorObj
AutoConf | Index | YRange
XRange | Data | Attach
TextSize | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FormatString | RowTitles
ColTitles | CurCell | TitleWidth
CellHeights | Cells | TitleHeight
CellFonts | Input | CellTypes
AutoExpand | CellSelect | ResizeRows
ResizeCols | ResizeRowTitles | ResizeColTitles
ClipCells | InputModeKey | InputMode
GridFCol | GridBCol | ShowInput
CellSet | RowTitleFCol | ColTitleFCol
RowTitleDepth | ColTitleDepth | RowTitleAlign
ColTitleAlign | OverflowChar | AlignChar
GridLineFCol | GridLine | RowLineTypes
ColLineTypes | EnterReadOnlyCells | RowTitleBCol
ColTitleBCol | RowTreeDepth | RowTreeStyle
RowTreeImages | ColSortImages | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | InputProperties | TabIndex
AlwaysShowSelection | AlwaysShowBorder | MethodList
ChildList | EventList | PropList


Group Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


Group Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Group Properties

Type | Caption | Posn
Size | Coord | Border
Active | Visible | Event
Sizeable | Dragable | FontObj
FCol | BCol | Picture
CursorObj | AutoConf | YRange
XRange | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | AcceptFiles
KeepOnClose | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


:Hold Statement Definition

:Hold Statement

:Hold

      |
      :Hold token(s)
      |
      code
      |
      |-------.
      |       |
      |       :Else
      |       |
      |       code
      |       |
      |<------.
      |
      :End[Hold]
      |


Icon Events

Close Create Select


Icon Methods

Detach FileRead FileWrite


Icon Properties

Type | File | Bits
CMap | Mask | Style
KeepBits | Event | Data
Handle | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Idiom Recognition

Introduction

Idiom List

Version Issues


:If Statement Definition

:If Statement

If:
       |
       :If bexp
       |
       .-------.
       |       |
       |       andor
       |       |
       |<------'
       |
       code
       |
       |<------------------------------.
       |                               |
       .-------.-------.               |
       |       |       |               |
       |       :Else   :ElseIf bexp    |
       |       |       |               |
       |       |       .-------.       |
       |       |       |       |       |
       |       |       |       andor   |
       |       |       |       |       |
       |       |       |<------'       |
       |       |       |               |
       |       |       |               |
       |       |       |               |
       |<------'       `---------------'
       |
       :End[If]
       |


Image Events

Close | Create | DragDrop
Help | MouseDblClick | MouseDown
MouseMove | MouseUp | Select


Image Methods

Detach


Image Properties

Type | Points | Coord
Visible | Event | Dragable
Picture | OnTop | AutoConf
Data | EdgeStyle | Size
Accelerator | AcceptFiles | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


ImageList Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


ImageList Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


ImageList Properties

Type | Items | Posn
Size | Style | Coord
Border | Active | Visible
Event | VScroll | SelItems
Sizeable | Dragable | FontObj
FCol | BCol | CursorObj
AutoConf | Index | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | MultiColumn | Column
KeepOnClose | Redraw | SortItems
TabIndex | MethodList | ChildList
EventList | PropList |


Index Symbol

Index

⌷

Index means

Index

      2 3⌷4 3⍴⍳12

6

Index with Axes means

Index with Axes

      2⌷[1]⍳2 3 4
 2 1 1  2 1 2  2 1 3  2 1 4
 2 2 1  2 2 2  2 2 3  2 2 4
 2 3 1  2 3 2  2 3 3  2 3 4

Language Elements


InstanceMode Property

Applies to: OLEClient

The InstanceMode property specifies how APL attempts to connect the OLEClient to an OLE Server.

InstanceMode is a character vector that may be 'ExistingFirst' (the default), 'ExistingOnly' or 'New'. Its value is effective only when the object is created with ⎕WC. Changing InstanceMode with ⎕WS has no effect.

If InstanceMode is 'ExistingFirst', APL attempts first to connect to a running instance of the OLE Server. If there is no running instance, it starts the OLE server to obtain a new object.

If InstanceMode is 'ExistingOnly', APL attempts to connect to a running instance of the object. If there is no running instance, it fails with a DOMAIN ERROR.

Note that in either case, if there is more than one instance running, there is no way to predict to which instance APL will be connected.

If InstanceMode is 'New', APL attempts to start the OLE Server to obtain a new object, whether or not the OLE Server is already running. However, if the OLE Server has registered itself as a single instance object and is already running, APL will be connected to it, and a second instance of the Server will not in fact be started.


International Day Number

The values of dates used by the properties, events and methods of the Calendar object are specified using IDNs (International Day Numbers).

An IDN is an integer that represents a date as the number of days starting at Jan 1st 1900, i.e. Jan 01 1900 is IDN 1.

Note that IDNs calculated by Dyalog APL do not precisely match IDNs calculated by Microsoft Excel which incorrectly assumes that 1900 was a Leap Year.


Iota

⍳

Monadic Iota means

Index Generator

      ⍳10
1 2 3 4 5 6 7 8 9 10

Dyadic Iota means

Index Of

      'ABCDABCDEF' ⍳ 'ACF'
1 3 10

Language Elements


Join ,/

is currently treated as a special case only for vectors of vectors or scalars.

Otherwise, the expression is evaluated as a series of concatenations.

Recognition of this idiom turns join from an n-squared algorithm into a linear one. In other words, the improvement factor is proportional to the size of the argument vector.


Jot

Jot;Null

∘

Jot is a Dyadic operator with a Dyadic operand

Operator Jot means

Composed With

Form I

      *∘⍳ 3 2
 2.718 2.718  2.718 7.389
 7.389 2.718  7.389 7.389
 20.09 2.718  20.09 7.389

Form II

      3 0∘⍕ 1.2 3.4 5.678 22
  1  3  6 22

Form III

      (*∘0.5) 1 2 3 4 5 6
1 1.414 1.732 2 2.236 2.449

Form IV

      5 ×∘⍳ 3 4
 5 5   5 10   5 15   5 20
 10 5  10 10  10 15  10 20
 15 5  15 10  15 15  15 20

Language Elements

NB Jot is also used in conjunction with Dot to mean Outer Product.


Label Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | Help | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


Label Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Label Properties

Type | Caption | Posn
Size | Coord | Border
Justify | Active | Visible
Event | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FieldType | Decimals
FormatString | Value | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Language Elements

Primitive Functions
+ | - | × | ÷ | | | — | ˜ | * | µ |
± | ! | ? | ~ | ^ | Ÿ | Š | ‹ |  |
< | ˆ | = | > | ‰ | ¬ |  | » |  |
⍴ | , | ® | ² | ´ | ³ | † | ‡ |  |
› | œ | ¹ | º | / | š | \ | ™ |  |
 | ž | ¼ | ¦ | “ | ” | – | • | ƒ | ‚
Ž | « | … |  |  |  |  |  |  |
Primitive Operators
¨ þ ° . °. / š \ ™ ÿ ¦ &
Special Syntax
„ [;] [] () ''
 Œ 
Variables
← ¯ E ‘_ « '' ›
À to ü
Namespaces
#. ##.
Defined Fns & Ops
∇ {} : ; ª ©
Dynamic Fns & Ops
{} ¸ ¾ ¸¸ ¾¾ ’ ’’
MultiThreading

&
Control Structures

:AndIf to :With
System Functions

ŒA to ŒXT
System Commands

)CLEAR to )XLOAD
Error Messages

DEADLOCK to WS FULL


Left Arrow

←

USED AS A FUNCTION

Monadic Left Arrow is not defined

Dyadic Left Arrow means

Is Assigned;Is;Gets

      X←3 5⍴'ABCDEFG'
      X
ABCDE
FGABC
DEFGA

USED AS AN OPERATOR

Left Arrow is a Monadic operator with a Dyadic operand

Operator Left Arrow means

Modified Assigned;Is

      X,←3 4 5
      X
ABCDE 3
FGABC 4
DEFGA 5

Language Elements

NB A side effect of this operator/function is that a variable is created or changes its value. X resolves to the name(s) of this variable.


Left Shoe

Left Shoe;Subset Of

⊂

Monadic Left Shoe means

Enclose

      ⊂ 1 (2 2) (2 2⍴3)
 1  2 2  3 3
         3 3

Dyadic Left Shoe means

If ⎕ML<3 Partitioned Enclose

      0 1 0 1 ⊂ 1 2 3 4
 2 3  4

If ⎕ML≥3 Partition

      0 1 0 1 ⊂ 1 2 3 4
 2  4

Language Elements


Less Than Or Equal To Sign

≤

Monadic Less Than Or Equal To Sign is not defined

Dyadic Less Than or Equal To Sign means

Is Less Or Equal To

      (2 1⍴2 ¯8 ) ≤ (2 1⍴2 2)
1
1

Language Elements


Less Than Sign

<

Monadic Less Than Sign is not defined

Dyadic Less Than Sign means

Is Less Than

      2 ¯8 2 5 4 < 2 2 ¯2 0 8
0 1 0 0 1

Language Elements


List Events

Configure | Create | DragDrop
DropFiles | DropObjects | Expose
GotFocus | Help | KeyPress
LostFocus | MouseDblClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | Select |


List Methods

GetEnvironment GetFocus


List Properties

Type Items Posn
Size Style Coord
Border Active Visible
Event DragItems VScroll
SelItems Sizeable Dragable
FontObj FCol BCol
CursorObj AutoConf Index
Data Attach EdgeStyle
Handle Hint HintObj
Tip TipObj Translate
Accelerator AcceptFiles MultiColumn
Column KeepOnClose SortItems


ListTypeLibs Method

ListTypeLibsMethod 520

Applies to: Root

The ListTypeLibs method reports the names and CLSIDs of all the loaded Type Libraries.

The ListTypeLibs method is niladic.

The result is a nested vector with one element per loaded Type Library.

Each element is a vector of 2-element charcater vectors. The first is the name of the Type Library; the second is its class identifier or CLSID.

Example:

      'EX'⎕WC'OLEClient' 'Excel.Application'
      ⍴ListTypeLibs
3
      ↑⊃ListTypeLibs
Microsoft Excel 9.0 Object Library
{00020813-0000-0000-C000-000000000046}

      ↑⊃¨ListTypeLibs
Microsoft Excel 9.0 Object Library
Microsoft Visual Basic for Applications Extensibility 5.3
Microsoft Office 9.0 Object Library


ListView Events

BeginEditLabel | Close | ColumnClick
Configure | ContextMenu | Create
DragDrop | DropFiles | DropObjects
EndEditLabel | Expose | FontCancel
FontOK | GetTipText | GotFocus
Help | ItemDblClick | ItemDown
ItemUp | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Select | SetColSize
SetItemPosition |  |


ListView Methods

Animate | ChooseFont | Detach
GetFocus | GetItemPosition | GetItemState
GetTextSize | SetItemState | ShowSIP


ListView Properties

Type | Items | Posn
Size | Style | Coord
Align | Border | Active
Visible | Event | DragItems
View | AutoArrange | Header
Wrap | EditLabels | ImageListObj
ReportInfo | ColTitles | ImageIndex
VScroll | HScroll | SelItems
Sizeable | Dragable | FontObj
FCol | BCol | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
ColTitleAlign | ColTitle3D | Translate
Accelerator | AcceptFiles | KeepOnClose
CheckBoxes | FullRowSelect | GridLines
Redraw | TabIndex | AlwaysShowSelection
ItemGroups | ItemGroupMetrics | MethodList
ChildList | EventList | PropList


Locator Events

Close | Create | Locator
Select |  |


Locator Methods

Detach Wait


Locator Properties

Type | Posn | Size
LStyle | Style | Coord
Event | Step | Sizeable
CursorObj | Data | Accelerator
KeepOnClose | MethodList | ChildList
EventList | PropList |


Log

Log;Circle Star

⍟

Monadic Log means

Natural Logarithm

      ⍟ 1 2 3 2.7182818285
0 0.6931471806 1.098612289 1

Dyadic Log means

Logarithm

      10 ⍟ 1 10 100 1000
0 1 2 3

Language Elements


Logical And

Logical And;Up Caret

∧

Monadic Logical And is not defined

Dyadic Logical And means

And, Lowest Common Multiple

      0 1 0 1 ∧ 0 0 1 1
0 0 0 1

      15 1 2 7 ∧ 35 1 4 0
105 1 4 0

Language Elements


Logical Or

Logical Or;Down Caret

∨

Monadic Logical Or is not defined

Dyadic Logical Or means

Or, Greatest Common Divisor

      0 1 0 1 ∨ 0 0 1 1
0 1 1 1

      15 1 2 7 ∨ 35 1 4 0

5 1 2 7

Language Elements


<sgBox Events

MsgBox Events

Close | Create | MsgBtn1
MsgBtn2 | MsgBtn3 |


MakeBooking Method

    ∇ R←MakeBooking ARGS;CODE;COURSE;SLOT;TEETIME;COURSECODES;...
      :Access Public
      ⍝ If GimmeNearest is 0, books (or fails) for specified time
      ⍝ If GimmeNearest is 1, books (or fails) for nearest to specified time
      CODE TEETIME NEAREST←3↑ARGS
      COURSECODES COURSES INDEX←⎕FREAD GOLFID 1
      COURSEI←COURSECODES⍳CODE
      COURSE←⎕NEW GolfCourse(CODE(COURSEI⊃COURSES,⊂''))
      SLOT←⎕NEW Slot TEETIME
      R←⎕NEW Booking(0 COURSE SLOT'')
      :If COURSEI>⍴COURSECODES
          R.Message←'Invalid course code'
          :Return
      :EndIf
...
      TEETIME←DateTime.New TEETIME.(Year Month Day),3↑24 60⊤I⊃TEETIMES
      SLOT.Time←TEETIME
      SLOT.Players←(⊃,/0<⍴¨GOLFERS[I;])/GOLFERS[I;]
      R.(OK TeeTime)←1 SLOT
    ∇


Marker Events

Close | Create | DragDrop
Help | MouseDblClick | MouseDown
MouseMove | MouseUp | Select


Marker Methods

Detach


Marker Properties

Type | Points | Style
Size | FCol | Coord
Visible | Event | Dragable
OnTop | AutoConf | Data
Accelerator | KeepOnClose | DrawMode
MethodList | ChildList | EventList
PropList |  |


Matrix Iota

Matrix Iota {(↓⍺)⍳↓⍵}.

As well as being quicker, the Matrix Iota idiom can accommodate much larger character matrices. It is particularly effective when bound with a left argument using the compose operator:

      find←cmat∘{(↓⍺)⍳↓⍵}   ⍝ find rows in cmat table.

In this case, the internal hash table for cmat is retained so that it does not need to be generated each time the monadic derived function find is applied to a character matrix argument.


MDIClient Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | GotFocus
Help | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Select |


MDIClient Methods

Animate | Detach | GetFocus
GetTextSize | MDIArrange | MDICascade
MDITile | ShowSIP |


MDIClient Properties

Type | Posn | Size
Coord | Border | Event
BCol | Picture | IconObj
CursorObj | YRange | XRange
Data | Attach | EdgeStyle
Handle | MDIActive | MDIActiveObject
Hint | HintObj | Tip
TipObj | Translate | Accelerator
KeepOnClose | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


Menu Events

Close | Create | DropDown
Select |  |


Menu Methods

Detach Wait


Menu Properties

Type | Caption | Posn
Coord | Align | Active
Event | FontObj | FCol
BCol | BtnPix | Data
EdgeStyle | Handle | Translate
Accelerator | KeepOnClose | ImageListObj
ImageIndex | MethodList | ChildList
EventList | PropList |


MenuBar Events

Close Create


MenuBar Methods

Detach


MenuBar Properties

Type | Visible | Event
FontObj | Data | EdgeStyle
MDIMenu | Handle | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


MenuItem Events

Close Create Select


MenuItem Methods

Detach


MenuItem Properties

Type | Caption | Posn
Style | Align | Active
Event | Checked | FontObj
FCol | BCol | BtnPix
Data | EdgeStyle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | KeepOnClose
ImageIndex | MethodList | ChildList
EventList | PropList |


Metafile Events

Close Create Select


Metafile Methods

Detach FileRead FileWrite


Metafile Properties

Type | File | Size
Coord | RealSize | Event
YRange | XRange | Data
Handle | Translate | Accelerator
KeepOnClose | MethodList | ChildList
EventList | PropList |


Methods

Method | Num | Description
Abort | 103 | abort a print job
AddChildren | 310 | adds child items to an item in a TreeView
AddItems | 308 | adds items to a TreeView
CancelToClose | 367 | changes the buttons in a PropertySheet
CellFromPoint | 200 | converts from Grid coordinates to cell coordinates
ChooseFont | 240 | displays the standard Windows font selection box
ColChange | 159 | sets new values for a column of cells in a Grid
ColSorted | 174 | sets the sort image to be displayed in the column title of a Grid
DateToIDN | 264 | Converts a date from ⎕TS format into an IDN suitable for use in a Calendar object
DelCol | 155 | deletes a column from a Grid object
DeleteChildren | 311 | deletes child items from a parent item in a TreeView
DeleteItems | 309 | deletes items from a TreeView
DelRow | 154 | deletes a row from a Grid object
Detach | 270 | detaches the GUI component from an object
DuplicateColumn | 154 | Duplicates a column in a Grid object
DuplicateRow | 154 | Duplicates a row in a Grid object
FileRead | 90 | causes a graphical object to be read from a file
FileWrite | 91 | causes a graphical object to be written to a file
Flush | 135 | flushes all pending output
GetCellRect | 201 | obtains the extents of a particular Grid cell
GetCommanLine | 145 | obtains the entire command line that was used to start Dyalog APL
GetCommanLineArgs | 148 | obtains the command line and arguments (as a nested vector) that was used to start Dyalog APL
GetEventInfo | 551 | obtains information about an OLE Control event
GetFocus | 511 | obtains the name of the object that currently has the input focus
GetItemHandle | 313 | obtains the window handle of an item in a TreeView
GetItemPosition | 323 | obtains the position of an item in a ListView
GetItemState | 306 | obtains the status of an item in a TreeView
GetMethodInfo | 552 | obtains information about an OLE Control method
GetMinSize | 275 | Obtains the minimum size that you must specify for a Calendar object for it to display a complete month
GetParentItem | 312 | obtains the index of the parent of an item in a TreeView
GetPropertyInfo | 550 | obtains information about an OLE Control property
GetTypeInfo | 550 | obtains information about an OLE Control data type
GetVisibleRange | 262 | Obtains the range of dates that is currently visible in a Calendar object
IDNToDate | 263 | Used to convert a date from an IDN into ⎕TS format
LockColumns | 227 | Locks/unlocks columns in a Grid object
LockRows | 227 | Locks/unlocks rows in a Grid object
MakeGIF | 261 | Generates an uncompressed GIF representation of a picture from a Bitmap object
MakePNG | 260 | Generates a PNG representation of a picture from a Bitmap object
MDIArrange | 112 | MDIClient to arrange minimised SubForm icons
MDICascade | 110 | MDIClient to overlap its SubForms
MDITile | 111 | MDIClient to rearrange SubForms in row or column
NameFromHandle | 136 | obtains the name of an object from its handle
NewPage | 102 | throws a new page on a Printer
OLEAddEventSink | 540 | Connects a named event sink to a COM object
OLEDeleteEventSink | 541 | Disconnects a named event sink from a COM object
OLEListEventSinks | 542 | Returns the names of event sinks that are currently connected to a COM object
OLEQueryInterface | 543 | Used to obtain the methods and properties associated with a particular interface that is provided by a COM object
OLEUnregister | 531 | used to unregister an OLEServer object that has previously been saved by Dyalog APL
Print | 100 | spools Printer output
ProgressStep | 250 | increments the thumb in a ProgressBar
RowChange | 158 | sets new values for a row of cells in a Grid
RTFPrint | 461 | prints the contents of a RichEdit
RTFPrintSetup | 460 | displays a print setup dialog box
SetCellType | 156 | changes CellTypes property for a cell in a Grid
SetEventInfo | 547 | Used to register an event that may be generated by an ActiveXControl object
SetFnInfo | 545 | Used to describe an APL function that is to be exported as a method, or as a property, of an ActiveXControl object
SetItemImage | 315 | allocates a picture icon to an item in a TreeView
SetItemState | 307 | sets the status of an item in a TreeView
SetMethodInfo | 546 | Used to describe a method that is exported by a COM object
SetPropertyInfo | 554 | Used to describe a property that is exported by a COM object
Setup | 101 | displays printer setup dialog box
SetVarInfo | 546 | Used to describe an APL variable that is to be exported as a property of an ActiveXControl object
ShowHelp | 580 | displays the help file associated with an OLE Control
ShowItem | 316 | displays a particular item in a TreeView
ShowProperties | 560 | displays the property sheet associated with an OLE Control
ShowSIP | 25 | Raise or lowers the Input Panel (Pocket APL only)
TCPGetHostID | 376 | obtains the IP Address of your PC
TCPSend | 375 | used to send data to a remote process connected to a TCPSocket object
TCPSendPicture | 380 | Transmits a picture represented by a Bitmap object to a TCP/IP socket
Undo | 170 | reverses last change made to a Grid object


Methods

Introduction

Shared Methods

Instance Methods

Superseding Base Class Methods


Minus Sign

Minus Sign;Bar

-

Monadic Minus Sign means

Negate

      - 3 2 5.5 ¯7 0
¯3 ¯2 ¯5.5 7 0

Dyadic Minus Sign means

Minus;Subtract

      3 7 9 - 5
¯2 2 4

Language Elements


Miscellaneous Chracters

Miscellaneous Characters

The following characters are not used explicitly in Dyalog APL, but may be used in character arrays:

   "  `  %  @  ¶  ¿  ¡  §  ⍫ ·

¤ ¥ £ $ ¢ ý ⍣ €  ⌷

The following line drawing characters are not used explicitly in Dyalog APL, but may be used in character arrays, however, they can not be printed:

' . . ' Å – Ã ´ Á Â |

The following ascii characters are, by default, mapped to the corresponding APL characters via the MAPCHARS parameter:

’becomes'

^becomes∧

¦becomes|

Language Elements


Monadic Format

Format

R←⎕FMT Y

Y may be any array.  R is a simple character matrix which appears the same as the default display of Y.  If Y contains control characters from ⎕TC, they will be resolved.

Examples:

      A←⎕FMT '∩' ,⎕TC[1],'∘'

      ⍴A
1 1
      A
⍝

      A←⎕VR 'FOO'

      A
     ∇ R←FOO
[1]    R←10
     ∇

      ⍴A
31
      B←⎕FMT A

      B
     ∇ R←FOO
[1]    R←10
     ∇

      ⍴B
3 12


MsgBox Methods

Detach Wait


MsgBox Properties

Type | Caption | Text
Style | Btns | Default
Event | Data | EdgeStyle
KeepOnClose | MethodList | ChildList
EventList | PropList |


MultiThreading

Overview

Language Elements

Thread Switching

Name Scope

Debugging

Using Threads

Stack Considerations

Globals and Order of Execution

Threads and Niladic Functions

Synchronising Threads

Semaphore Example

Latch Example


Name-Class: Classes

Classes (Name-Class 9.4)

Classes created using the editor or ⎕FIX have name-class 9.4.

      )ED ○MyClass
:Class MyClass
    ∇ r←NC x
      :Access Public Shared
      r←⎕NC x
    ∇
:EndClass ⍝ MyClass
      ⎕NC 'MyClass'
9
      ⎕NC⊂'MyClass'
9.4

      ⎕FIX ':Class UrClass'  ':EndClass'
      ⎕NC 'MyClass' 'UrClass'
9.4 9.4

Note that the name of the Class is visible to a Public Method in that Class, or an Instance of that Class.

      MyClass.NC'MyClass'
9
      MyClass.NC⊂'MyClass'
9.4


Name-Class: Derived Functions

Derived Functions (Name-Class 3.3)

Derived Functions and functions created by naming a Primitive function have name-class 3.3.

      PLUS←+
      SUM←+/
      CUM←PLUS\
      ⎕NC'PLUS' 'SUM' 'CUM'
3.3 3.3 3.3
      ⎕NC 3 4⍴'PLUSSUM CUM '
3 3 3

Note that a function that is simply cloned from a defined function by assignment retains its name-class. Whereas, the name of a function that amalgamates a defined function with any other functions has the name-class of a Derived Function, i.e. 3.3.

     ∇ R←AVG X
[1]    R←(+/X)÷⍴X
     ∇
      MEAN←AVG
      VMEAN←AVG∘,
      ⎕NC'AVG' 'MEAN' 'VMEAN'
3.1 3.1 3.3


Name-Class: D-Fns

D-Fns (Name-Class 3.2)

D-Fns (Dynamic Functions) have name-class 3.2

      Avg←{(+/⍵)÷⍴⍵}

      ⎕NC'Avg'
3
      ⎕NC⊂'Avg'
3.2


Name-Class: D-Ops

D-Ops (Name-Class 4.2

D-Ops (Dynamic Operators) have name-class 4.2.

pred←{⎕IO ⎕ML←1 3   ⍝ Partitioned reduction.
     ⊃⍺⍺/¨(⍺/⍳⍴⍺)⊂⍵
     }
      2 3 3 2 +pred ⍳10
3 12 21 19

      ⎕NC'pred'
4
      ⎕NC⊂'pred'
4.2


Name-Class: External Classes

External Classes (Name-Class 9.6)

External Classes (Types) exposed by .Net have name-class 9.6.

      ⎕USING←'System' 'System.IO'

      ⎕NC 'DateTime' 'File' 'DirectoryInfo'
9.6 9.6 9.6

Note that referencing a .Net class (type) with ⎕NC, fixes the name of that class in the workspace and obviates the need for APL to repeat the task of searching for and loading the class when the name is next used.


Name-Class: External Events

External Events (Name-Class 8.6)

Events exposed by Dyalog APL GUI objects, COM and .NET objects have name-class ¯8.6.

      f←⎕NEW'Form'(⊂'Caption' 'Dyalog GUI Form')

      f.⎕NC'Close' 'Configure' 'MouseDown'
¯8.6 ¯8.6 ¯8.6
      xl←⎕NEW'OLEClient'(⊂'ClassName' 'Excel.Application')
      xl.⎕NL -8
NewWorkbook SheetActivate SheetBeforeDoubleClick SheetBeforeRightClick SheetCalculate SheetChange ...

      xl.⎕nc 'SheetActivate' 'SheetCalculate'
¯8.6 ¯8.6

      ⎕USING←'System.Windows.Forms,system.windows.forms.dll'
      ⎕NC,⊂'Form'
9.6
      Form.⎕NL -8
Activated  BackgroundImageChanged  BackColorChanged  BindingContextChanged ...


Name-Class: External Functions

External Functions (Name-Class 3.6)

Methods exposed by the Dyalog APL GUI and COM and .NET objects have name-class ¯3.6. Methods exposed by External Functions created using ⎕NA and ⎕SH all have name-class 3.6.

      'F'⎕WC'Form'

      F.⎕NC'GetTextSize' 'GetFocus'
¯3.6 ¯3.6

      'EX'⎕WC'OLEClient' 'Excel.Application'
      EX.⎕NC 'Wait' 'Save' 'Quit'
¯3.6 ¯3.6 ¯3.6

      ⎕USING←'System'
      dt←⎕NEW DateTime (2006 1 1)
      dt.⎕NC 'AddDays' 'AddHours'
¯3.6 ¯3.6

       'beep'⎕NA'user32|MessageBeep i'

      ⎕NC'beep'
3
      ⎕NC⊂'beep'
3.6
      'xutils'⎕SH''
      )FNS
avx     box     dbr     getenv  hex     ltom    ltov    mtol    ss      vtol
      ⎕NC'hex' 'ss'
3.6 3.6


Name-Class: External Interfaces

External Interfaces (Name-Class 9.7)

External Interfaces exposed by .Net have name-class 9.7.

      ⎕USING←'System.Web.UI,system.web.dll'

      ⎕NC 'IPostBackDataHandler' 'IPostBackEventHandler'
9.7 9.7

Note that referencing a .Net Interface with ⎕NC, fixes the name of that Interface in the workspace and obviates the need for APL to repeat the task of searching for and loading the Interface when the name is next used.


Name-Class: External Properties

External Properties (Name-Class 2.6)

Properties exposed by external objects (.Net and COM and the APL GUI) have name-class ¯2.6.

      ⎕USING←'System'
      dt←⎕NEW DateTime (2006 1 1)
      dt.⎕NC 'Day' 'Month' 'Year'
¯2.6 ¯2.6 ¯2.6

      'ex' ⎕WC 'OLEClient' 'Excel.Application'
      ex.⎕NC 'Caption' 'Version' 'Visible'
¯2.6 ¯2.6 ¯2.6

     'f'⎕WC'Form'
      f.⎕NC'Caption' 'Size'
¯2.6 ¯2.6

Note that the names of such Properties are reported as being unused if the argument to ⎕NC is simple.

      f.⎕NC 2 7⍴'CaptionSize   '
0 0


Name-Class: Field

Field (Name-Class 2.2)

Fields defined by APL Classes have name-class 2.2.

:Class nctest
    :Field Public pubFld
    :Field pvtFld

    ∇ r←NC x
      :Access Public
      r←⎕NC x
    ∇
...
:EndClass ⍝ nctest
      ncinst←⎕NEW nctest

The name-class of a Field, whether Public or Private, viewed from a Method that is executing within the Instance Space, is 2.2.

      ncinst.NC'pubFld' 'pvtFld'
2.2 2.2

Note that an internal Method sees both Public and Private Fields in the Class Instance. However, when viewed from outside the instance, only public fields are visible

      ⎕NC 'ncinst.pubFld' 'ncinst.pvtFld'
¯2.2 0

In this case, the name-class is negative to indicate that the name has been exposed by the class hierarchy, rather than existing in the associated namespace which APL has created to contain the instance. The same result is returned if ⎕NC is executed inside this space:

      ncinst.⎕NC'pubFld' 'pvtFld'
¯2.2 0

Note that the names of Fields are reported as being unused if the argument to ⎕NC is simple.

      ncinst.⎕NC 2 6⍴'pubFldpvtFld'
0 0


Name-Class: Instances

Instances (Name-Class 9.2)

Instances of Classes created using ⎕NEW, and GUI objects created using ⎕WC all have name-class 9.2.

      MyInst←⎕NEW MyClass
      ⎕NC'MyInst'
9
      ⎕NC⊂'MyInst'
9.2
      UrInst←⎕NEW ⎕FIX ':Class'  ':EndClass'
      ⎕NC 'MyInst' 'UrInst'
9.2 9.2

      'F'⎕WC 'Form'
      'F.B' ⎕WC 'Button'
      ⎕NC 2 3⍴'F  F.B'
9 9
      ⎕NC'F' 'F.B'
9.2 9.2
      F.⎕NC'B'
9
      F.⎕NC⊂,'B'
9.2

Instances of COM Objects whether created using ⎕WC or ⎕NEW also have name-class 9.2.

      xl←⎕NEW'OLEClient'(⊂'ClassName' 'Excel.Application')
      'XL'⎕WC'OLEClient' 'Excel.Application'
      ⎕nc'xl' 'XL'
9.2 9.2

The same is true of Instances of .Net Classes (Types) whether created using ⎕NEW or .New.

      ⎕USING←'System'
      dt←⎕NEW DateTime (3↑⎕TS)
      DT←DateTime.New 3↑⎕TS
      ⎕NC 'dt' 'DT'
9.2 9.2

Note that if you remove the GUI component of a GUI object, using the Detach method, it reverts to a plain namespace.

      F.Detach
      ⎕NC⊂,'F'
9.1

Correspondingly, if you attach a GUI component to a plain namespace using the monadic form of ⎕WC, it morphs into a GUI object

      F.⎕WC 'PropertySheet'
      ⎕NC⊂,'F'
9.2


Name-Class: Interfaces

Interfaces (Name-Class 9.5)

Interfaces, defined by :Interface ... :EndInterface clauses, have name-class 9.5.

:Interface IGolfClub
:Property Club
    ∇ r←get
    ∇
    ∇ set
    ∇
:EndProperty

∇ Shank←Swing Params
∇

:EndInterface ⍝ IGolfClub

      ⎕NC 'IGolfClub'
9
      ⎕NC ⊂'IGolfClub'
9.5


Name-Class: namespaces

Namespaces (Name-Class 9.1)

Plain namespaces created using ⎕NS have name-class 9.1.

      'MYSPACE' ⎕NS ''
      ⎕NC'MYSPACE'
9
      ⎕NC⊂'MYSPACE'
9.1

Note however that a namespace created by cloning, where the right argument to ⎕NS is a ⎕OR of a namespace, retains the name-class of the original space.

      'CopyMYSPACE'⎕NS ⎕OR 'MYSPACE'
      'CopyF'⎕NS ⎕OR 'F'⎕WC'Form'

      ⎕NC'MYSPACE' 'F'
9.1 9.2
      ⎕NC'CopyMYSPACE' 'CopyF'
9.1 9.2

The Name-Class of .Net namespaces (visible through ⎕USING) is also 9.1

      ⎕USING←''

      ⎕NC 'System' 'System.IO'
9.1 9.1


Name-Class: Operators

Operators (Name-Class 4.1)

Traditional Defined Operators have name-class 4.1.

      ∇FILTER∇
     ∇ VEC←(P FILTER)VEC  ⍝ Select from VEC those elts ..
[1]    VEC←(P¨VEC)/VEC    ⍝ for which BOOL fn P is true.
     ∇
      ⎕NC'FILTER'
4
      ⎕NC⊂'FILTER'
4.1


Name-Class: Property

Property (Name-Class 2.3)

Properties defined by APL Classes have name-class 2.3.

:Class nctest
    :Field pvtFld←99

    :Property pubProp
    :Access Public
        ∇ r←get
          r←pvtFld
        ∇
    :EndProperty

    :Property pvtProp
        ∇ r←get
          r←pvtFld
        ∇
    :EndProperty

    ∇ r←NC x
      :Access Public
      r←⎕NC x
    ∇
...
:EndClass ⍝ nctest

      ncinst←⎕NEW nctest

The name-class of a Property, whether Public or Private, viewed from a Method that is executing within the Instance Space, is 2.3.

      ncinst.NC'pubProp' 'pvtProp'
2.3 2.3

Note that an internal Method sees both Public and Private Properties in the Class Instance. However, when viewed from outside the instance, only Public Properties are visible

      ⎕NC 'ncinst.pubProp' 'ncinst.pvtProp'
¯2.3 0

In this case, the name-class is negative to indicate that the name has been exposed by the class hierarchy, rather than existing in the associated namespace which APL has created to contain the instance. The same result is returned if ⎕NC is executed inside this space:

      ncinst.⎕NC 'pubProp' 'pvtProp'
¯2.3 0

Note that the names of Properties are reported as being unused if the argument to ⎕NC is simple.

      ncinst.⎕NC 2 6⍴'pubProppvtProp'
0 0


Name-Class: Traditional Defined Functions

Defined Functions (Name-Class 3.1)

Traditional APL defined functions have name-class 3.1.

     ∇ R←AVG X
[1]    R←(+/X)÷⍴X
     ∇
      AVG ⍳100
50.5

      ⎕NC'AVG'
3
      ⎕NC⊂'AVG'
3.1

      'MYSPACE'⎕NS 'AVG'
       MYSPACE.AVG ⍳100
50.5

      MYSPACE.⎕NC'AVG'
3
      ⎕NC⊂'MYSPACE.AVG'
3.1

Note that a function that is simply cloned from a defined function by assignment retains its name-class.

      MEAN←AVG
      ⎕NC'AVG' 'MEAN'
3.1 3.1

Whereas, the name of a function that amalgamates a defined function with any other functions has the name-class of a Derived Function, i.e. 3.3.

      VMEAN←AVG∘,
      ⎕NC'AVG' 'VMEAN'
3.1 3.3


Name-Class: Variable

Variable (Name-Class 2.1)

Conventional APL arrays have name-class 2.1.

      NUM←88
      CHAR←'Hello World'

      ⎕NC ↑'NUM' 'CHAR'
2 2

      ⎕NC 'NUM' 'CHAR'
2.1 2.1

      'MYSPACE'⎕NS ''
      MYSPACE.VAR←10
      MYSPACE.⎕NC'VAR'
2
      MYSPACE.⎕NC⊂'VAR'
2.1


Name-Classes

The following table summarises the possible values for name-class.

Note that name-class 2 (Arrays) encompasses name-class 2.1 (variables), 2.2 (Fields), 2.3 (Properties) and 2.6 (External/Shared variables), and so forth.

 | Array (2) | Functions (3) | Operators (4) | Namespaces (9)
n.1 | Variables | Traditional Defined Functions | Traditional Defined Operators | Created by ⎕NS
n.2 | Fields | D-fns | D-ops | Instances
n.3 | Properties | Derived/Primitive Functions | N/A |
n.4 |  |  | N/A | Classes
n.5 | N/A | N/A | N/A | Interfaces
n.6 | External/Shared Variables | External Functions |  | External Classes
n.7 |  |  |  | External Interfaces


Namelist Header Syntax

Namelists

The right argument and the result of a function may be specified in the function header by a single name or by a Namelist. In this context, a Namelist is a blank-delimited list of names surrounded by a single set of parentheses.

Names specified in a Namelist are automatically local to the function; there is no need to localise them explicitly using semi-colons.

If the right argument of a function is declared as a Namelist, the function will only accept a right argument that is a vector whose length is the same as the number of names in the Namelist. Calling the function with any other argument will result in a LENGTH ERROR in the calling statement. Otherwise, the elements of the argument are assigned to the names in the Namelist in the specified order.

Example:

     ∇ IDN←Date2IDN(Year Month Day)
[1]    'Year is ',⍕Year
[2]    'Month is ',⍕Month
[3]    'Day is ',⍕Day
[4] ...
     ∇

      Date2IDN 2004 4 30
Year is 2004
Month is 4
Day is 30


Namespaces TOC

Namespaces

Introduction

Namespace Syntax

Namespace Reference Evaluation

Namespaces and Localisation

Namespace References

Unnamed Namespaces

Arrays of Namespace References

Distributed Assignment

Distributed Functions

Namespaces and Operators


Nand Symbol

Nand;Up Caret Tilde

⍲

Monadic Nand is not defined

Dyadic Nand means

Nand;Not And

      0 1 0 1 ⍲ 0 0 1 1
1 1 1 0

Language Elements


Nested Vector Transpose

Nested vector transpose ↓⍉↑ (⎕ml<2)

↓⍉⊃ (⎕ml≥2)

is only optimised for a vector of nested vectors, each of whose items is of the same length.


NetControl Properties

Type | Posn | Size
Coord | ClassName | Attach
MethodList | ChildList | EventList
PropList |  |


NetType Events

(None)


NetType Methods

(None)


NetType Properties

BaseClass


New Features in Version 10.1

New Features in Version 11.0 Release 1


No-blank Split

No-blank split ~∘' '¨↓

This expression typically takes a character matrix argument and returns a vector of character vectors from which, all blanks have been removed. An example might be the character matrix of names returned by the system function ⎕NL. In general, this idiom accommodates character arrays of any rank.


Non-Scalar Computational Functions

Non-Scalar Computational Fns

Niladic
Zilde | ⍬ | the zero length numeric vector
Naked Branch | → | abandon execution one level on stack
Monadic
Branch | →⍵ | jump to line number ⍵
Execute | ⍎⍵ | evaluate expression represented by ⍵
Matrix Inverse | ⌹⍵ | inverse of non-singular matrix ⍵
Dyadic
Decode | ⍺⊥⍵ | base ⍺ value of ⍵
Encode | ⍺⊤⍵ | base ⍺ representation of ⍵
Dyadic Execute | ⍺⍎⍵ | evaluate ⍵ in namespace ⍺
Matrix Divide | ⍺⌹⍵ | matrix inverse of ⍵ matrix multiplied by ⍺


Non-Scalar Dyadic Structural Functions

Non-Scalar Dyadic Structural Fns

Reshape | ⍺⍴⍵ | reshape ⍵ to dimension ⍺
Catenate | ⍺,⍵ | join ⍺ to ⍵ along (last) axis
Catenate First | ⍺⍪⍵ | join ⍺ to ⍵ along (first) axis
Laminate | ⍺,[K]⍵ | join along new axis after ⌊K
Laminate First | ⍺⍪[K]⍵ | join along new axis after ⌊K
Rotate | ⍺⌽⍵ | left/right rotation of each sub-array by ⍺ along (last) axis
Rotate First | ⍺⊖⍵ | left/right rotation of each sub-array by ⍺ along (first) axis
Dyadic Transpose | ⍺⍉⍵ | axis I of ⍵ becomes axis ⍺[I] of result
Partitioned Enclose | ⍺⊂⍵ | build non-simple vector from ⍵
Partitioned (APL2 Form) | ⍺⊂⍵ | build non-simple vector from ⍵
Dyadic Format | ⍺⍕⍵ | format ⍵ according to ⍺


Non-Scalar Monadic Structural Functions

Non-Scalar Monadic Structural Fns

Shape | ⍴⍵ | length of each axis of ⍵
Ravel | ,⍵ | vectorize ⍵ in row-major order
Ravel with Axes | ,[k]⍵ | vectorize ⍵ along axes [k]
Table | ⍪⍵ | tabularize ⍵ in row-major order
Reverse | ⌽⍵ | reverse along an axis, default last
Reverse First | ⊖⍵ | reverse along an axis, default first
Transpose | ⍉⍵ | reverse order of axes of ⍵
Mix | ↑⍵ | remove a nesting level along an axis
Split | ↓⍵ | enclose along an axis of ⍵
Enclose | ⊂⍵ | enclose ⍵ as a scalar element
Enclose with Axes | ⊂[k]⍵ | enclose ⍵ along axes [k]
Format | ⍕⍵ | character array printing form of ⍵
Depth | ≡⍵ | levels of nesting of ⍵
Enlist | ∊⍵ | simple vector from ⍵


Non-Scalar Selection Functions

Monadic
Disclose | ⊃⍵ | disclose first element of ⍵
Unique | ∪⍵ | unique occurrences in ⍵
Dyadic
Pick | ⍺⊃⍵ | indexes ⍵ through levels of enclosure according to ⍺
Take | ⍺↑⍵ | take from ⍵ according to ⍺
Take with Axes | ⍺↑[k]⍵ | take from ⍵ according to ⍺ and axes [k]
Drop | ⍺↓⍵ | drop from ⍵ according to ⍺
Drop with Axes | ⍺↓[k]⍵ | drop from ⍵ according to ⍺ and axes [k]
Replicate | ⍺/⍵ | replicate elements of ⍵ along (last) axis according to ⍺
Replicate First | ⍺⌿⍵ | replicate elements of ⍵ along (first) according to ⍺
Expand | ⍺\⍵ | extend elements of ⍵ along (last) axis according to ⍺
Expand First | ⍺⍀⍵ | extend elements of ⍵ along (last) axis according to ⍺
Excluding | ⍺~⍵ | items in ⍺ that do not occur in ⍵
Intersection | ⍺∩⍵ | elements both in ⍺ and in ⍵
Union | ⍺∪⍵ | ⍺ and members of ⍵ not in ⍺


Non-Scalar Selector Functions

Monadic
Index Generator | ⍳⍵ | all coordinates of array of shape ⍵
Grade Up | ⍋⍵ | ascending sort order of ⍵
Grade Down | ⍒⍵ | descending sort order of ⍵
Dyadic
Index | ⍺⌷⍵ | ⍵ indexed by ⍺
Index with Axes | ⍺⌷[k]⍵ | ⍵ indexed by ⍺
Index Of | ⍺⍳⍵ | first occurrence of ⍵ in ⍺
Membership | ⍺∊⍵ | element of ⍺ matches one from ⍵
Find | ⍺⍷⍵ | is place in ⍵ where pattern ⍺ begins
Dyadic Grade Up | ⍺⍋⍵ | ascending order of ⍵ collated by ⍺
Dyadic Grade Down | ⍺⍒⍵ | descending order of ⍵ collated by ⍺
Deal | ⍺?⍵ | ⍺ distinct random elements from ⍵
Match | ⍺≡⍵ | proposition: ⍺ is identical to ⍵
Not Match | ⍺≢⍵ | proposition: ⍺ is not identical to ⍵


Nor Symbol

Nor;Down Caret Tilde

⍱

Monadic Nor is not defined

Dyadic Nor means

Nor;Not Or

      0 1 0 1 ⍱ 0 0 1 1
1 0 0 0

Language Elements


Not Equal To

Not Equal

<⌈

Monadic Not Equal is not defined

Dyadic Not Equal means

Is Not Equal To

      (2 2 2⍴1 2 3) ≠ 3
1 1
0 1

1 0
1 1

Language Elements


No-trailing blank Split

No-trailing-blank split {(+/∨\' '≠⌽⍵)↑¨↓⍵}

This expression typically takes a character matrix argument and returns a vector of character vectors. Any embedded blanks in each row are preserved but trailing blanks are removed. In general, this idiom accommodates character arrays of any rank.


Object Oriented Programming

Classes
Constructors and Destructors
Fields, Properties and Methods
Fields
Methods
Properties
Interfaces
Example
Including Namespaces in Classes
Example
Nested Classes
GolfService Example
Namespace Scripts
DiaryStuff Example
Class Declaration Statements
Using the Dyalog GUI
Example
Writing Classes based on the Dyalog GUI
Writing Classes based on .Net Types
Example


OCXClass Events


OCXClass Methods

Browse | Detach | GetEventInfo
GetMethodInfo | GetPropertyInfo | GetTypeInfo
OLEAddEventSink | OLEDeleteEventSink | OLEListEventSinks
SetMethodInfo | SetPropertyInfo | ShowHelp
ShowProperties |  |


OCXClass Properties

Type | ClassName | Event
Data | Translate | ClassID
KeepOnClose | TypeList | HelpFile
ToolboxBitmap | LicenseKey | QueueEvents
MethodList | ChildList | EventList
PropList |  |


OLEClient Events

(None)


OLEClient Methods

Browse | Detach | GetEventInfo
GetMethodInfo | GetPropertyInfo | GetTypeInfo
OLEAddEventSink | OLEDeleteEventSink | OLEListEventSinks
OLEQueryInterface | SetMethodInfo | SetPropertyInfo
ShowHelp |  |


OLEClient Properties

Type | ClassName | Event
Data | Handle | ClassID
KeepOnClose | TypeList | HelpFile
LastError | Locale | AutoBrowse
QueueEvents | InstanceMode | MethodList
ChildList | EventList | PropList


OLEServer Events

Close Create


OLEServer Methods

Detach | OLERegister | OLEUnregister
SetEventInfo | SetFnInfo | SetVarInfo


OLEServer Properties

Type | ClassName | Event
Data | Handle | ExportedFns
ExportedVars | ClassID | KeepOnClose
TypeLibID | TypeLibFile | ServerVersion
LastError | RunMode | ShowSession
MethodList | ChildList | EventList
PropList |  |


Overview of Objects

Objects

Objects: Categorised

Object | Description
ActiveXContainer | represents the application hosting a Dyalog APL ActiveXControl
ActiveXControl | implements an ActiveX control written in Dyalog APL
Animation | plays simple AVIs
Bitmap | can be used to fill an area, or as a background pattern
BrowseBox | allows the user to browse for a folder or other resource
Button | used to perform a task or select an option
Calendar | displays a month calendar control
Circle | draws circles, arcs and pies
Clipboard | provides access to the Windows clipboard
ColorButton | allows the user to select a colour
Combo | combines text entry field with list of choices
ComboEx | an extended version of the Combo object that provides additional features including item images
CoolBand | represents a band in a CoolBar
CoolBar | acts as a container for CoolBand objects
Cursor | creates user-defined cursor
DateTimePicker | an editable date/time field with an optional drop-down Calendar
Edit | single or multi-line edit box for entering data
Ellipse | draws ellipses, elliptical arcs and pies
FileBox | standard File Selection dialog box
Font | a font resource
Form | window that acts as a container for other objects
Grid | spreadsheet object for editing data
Group | frame with border and optional title to group other objects
Icon | can be displayed, or used when a Form is minimized
Image | graphical object for displaying bitmaps and icons
ImageList | specifies a collection of bitmaps or icons for a ListView or TreeView
Label | fixed text that the user cannot change
List | list of items from which the user can choose
ListView | collection of items from which the user can choose
Locator | moving line, rectangle or ellipse for graphics input
Marker | draws marker at a series of points
MDIClient | provides Multiple Document Interface (MDI) behaviour
Menu | displays a pulldown or pop-up menu
MenuBar | displays list of pulldown menus across top of Form
MenuItem | component of a Menu that performs action or makes choice
Metafile | provides access to Windows Metafiles
MsgBox | displays message in dialog box and waits for response
NetClient | Provides access to .NET Classes
NetType | Exports a namespace as a .NET class
OCXClass | provides access to OLE Custom Controls
OLEClient | provides access to OLE Automation objects
OLEServer | enables APL to act as an OLE Automation server
Poly | draws lines, polygons and filled areas
Printer | controls output to a printer
ProgressBar | indicates the progress of a lengthy operation
PropertyPage | tabbed or paged container for other controls
PropertySheet | container for PropertyPages
Rect | draws filled and unfilled rectangles
RichEdit | an edit box with word-processing capabilities
Root | the system object that is the progenitor of all others
Scroll | horizontal or vertical scrollbar
Separator | horizontal or vertical line in Menu, or vertical break in MenuBar
SM | allows ⎕SM and ⎕SR to be used with GUI objects
Spinner | input field with spin buttons
Splitter | divides a Form or SubForm into resizable panes
Static | frame or box used to contain graphics
StatusBar | manages a set of StatusField objects
StatusField | displays context-sensitive help, or keyboard status
SubForm | child Form that is constrained within its parent
SysTrayItem | represents an item that you can create in the Windows system tray
TabBar | manages a set of TabBtn objects
TabBtn | brings forward an associated SubForm
TabButton | represents a tab or button in a TabControl
TabControl | represents the Windows 95 tab control
TCPSocket | provides an interface to TCP/IP sockets
Text | displays or prints arbitrary text
Timer | generates events at regular intervals
TipField | displays pop-up context-sensitive help
ToolBar | manages a block of controls including Buttons
ToolButton | represents a or button in a ToolControl
ToolControl | represents the Windows 95 toolbar
TrackBar | slider control for analogue input/output
TreeView | displays a hierarchical list of items
UpDown | a pair of arrow buttons


Parrot Classes

:Class DomesticParrot: Parrot
    :Field Public Name

    ∇ egg(name species)
      :Access Public
      :Implements Constructor :Base species
      ⎕DF Name←name
    ∇

    ∇ egg0
      :Access Public
      :Implements Constructor :Base 'Generic'
      ⎕DF Name←'Polly'
    ∇

    ∇ R←Speak
      :Access Public
      R←⎕BASE.Speak,' Who's a pretty boy,then!'
    ∇

    ∇ kill
      :Implements Destructor
      'This ',(⍕⎕THIS),' is dead'
    ∇
:EndClass ⍝ DomesticParrot

:Class Parrot: Bird

    ∇ egg species
      :Access Public Instance
      :Implements Constructor :Base 'Parrot: ',species
    ∇

    ∇ R←Speak
      :Access Public
      R←'Squark!'
    ∇
    ∇ kill
      :Implements Destructor
      'This Parrot is dead'
    ∇
:EndClass ⍝ Parrot

:Class Bird
    :Field Public Species

    ∇ egg spec
      :Access Public Instance
      :Implements Constructor
      Species←spec
    ∇

    ∇ R←Speak
      :Access Public
      R←'Tweet, tweet!'
    ∇
    ∇ kill
      :Implements Destructor
      'This Bird is dead'
    ∇
:EndClass ⍝ Bird


Penguin Class

:Interface FishBehaviour
∇ R←Swim ⍝ Returns description of swimming capability
∇
:EndInterface ⍝ FishBehaviour

:Interface BirdBehaviour
∇ R←Fly ⍝ Returns description of flying capability
∇
∇ R←Lay ⍝ Returns description of egg-laying behaviour
∇
∇ R←Sing ⍝ Returns description of bird-song
∇
:EndInterface ⍝ BirdBehaviour

:Class Penguin: Animal,BirdBehaviour,FishBehaviour
    ∇ R←NoCanFly
      :Implements Method BirdBehaviour.Fly
      R←'Although I am a bird, I cannot fly'
    ∇
    ∇ R←LayOneEgg
      :Implements Method BirdBehaviour.Lay
      R←'I lay one egg every year'
    ∇
    ∇ R←Croak
      :Implements Method BirdBehaviour.Sing
      R←'Croak, Croak!'
    ∇
    ∇ R←Dive
      :Implements Method FishBehaviour.Swim
      R←'I can dive and swim like a fish'
    ∇
:EndClass ⍝ Penguin


Plus Sign

+

Monadic Plus Sign means

Identical To

      + 3.2 ¯12.666
3.2 ¯12.666

Dyadic Plus Sign means

Plus;Added To

      1 2 3 4 + 5 6 7 8
6 8 10 12

Language Elements


Poly Events

Close | Create | DragDrop
Help | MouseDblClick | MouseDown
MouseMove | MouseUp | Select


Poly Methods

Detach


Poly Properties

Type | Points | FCol
BCol | LStyle | L
FStyle | FillCol | Coord
Visible | Event | Dragable
OnTop | CursorObj | AutoConf
Data | Accelerator | KeepOnClose
DrawMode | MethodList | ChildList
EventList | PropList |


Port Number

A port number identifies the service provided by a particular server. It is an integer number in the range 0-65536,

Port numbers in the range 0-1023 are reserved for “well-known” services (e.g., FTP and HTTP).

Port number 1024 is reserved for IANA.

Port numbers 1025-5000 are typically assigned for user-defined services.


Primitive Functions

Scalar Monadic Functions | + - × ÷ | ⌈ ⌊ * ⍟ ○ ! ~ ? ∊
Scalar Dyadic Arithmetic Functions | + - × ÷ | ⌈ ⌊ * ⍟ !
Scalar Dyadic Logical Functions | ∧ ∨ ⍲ ⍱ < > ≤ ≥ = ≠
Scalar Dyadic Circular Functions | ○
Non-Scalar Monadic Structural Fns | ⍴ , ⍪ ⌽ ⊖ ⍉ ↑ ↓ ⊂ ⍕ ≡ ∊
Non-Scalar Dyadic Structural Fns | ⍴ , ⍪ ⌽ ⊖ ⍉ ⊂ ⍕
Non-Scalar Selection Functions | ⊃ ↑ ↓ / ⌿ \ ⍀ ~ ∩ ∪
Non-Scalar Selector Functions | ⍳ ∊ ⍷ ⍋ ⍒ ? ≡ ≢
Non-Scalar Computational Fns | → ⍬ ⍎ ⊥ ⊤ ⌹


Primitive Operators

Each | f¨⍵ | apply monadic f to elements of ⍵
Dyadic Each | ⍺f¨⍵ | apply dyadic f to corresponding elements of ⍺ and ⍵
Power | ⍺(f⍣g)⍵ | apply monadic or dyadic f repeatedly to ⍵
Reduce | f/⍵ | dyadic f placed between each sub-array along (last) axis
Reduce First | f⌿⍵ | dyadic f placed between each sub-array along (first) axis
N-Wise Reduce | ⍺f/⍵ | dyadic f placed between items of sub-vectors of length ⍺
Scan | f\⍵ | successive reductions along (last) axis
Scan First | f⍀⍵ | successive reductions along (first) axis
Commute | ⍺f⍨⍵ | commute arguments of dyadic f
Compose (Form I) | f∘g⍵ | gives result f g ⍵
Compose (Form II) | I∘g⍵ | gives result I g ⍵
Compose (Form III) | f∘k⍵ | gives result ⍵ f k
Compose (Form IV) | ⍺f∘g⍵ | gives result ⍺ f g ⍵
Inner Product | ⍺f.g⍵ | apply f and g like + and × in matrix multiplication
Outer Product | ⍺∘.g⍵ | apply dyadic g to all combinations of elements from ⍺ and ⍵
Spawn | ⍺f&⍵ | start a new thread with f applied to its argument(s)
I-Beam | {f}(⍺⌶)⍵ | provides a range of system-related services


Printer Events

Close Create Select


Printer Methods

Abort | Detach | GetTextSize
NewPage | Print | RTFPrintSetup
Setup |  |


Printer Properties

Type | PName | DevCaps
Coord | Event | FontObj
FontList | YRange | XRange
Data | TextSize | EdgeStyle
Handle | Orientation | Copies
PrintRange | Collate | PaperSize
PaperSizes | PaperSource | PaperSources
ColorMode | Resolution | Resolutions
Duplex | Translate | Accelerator
KeepOnClose | MethodList | ChildList
EventList | PropList |


Programming Environment

Object Management Functions

⎕DQ Dequeue | processes user actions, invoking callbacks
⎕NQ Enqueue | generates an event under program control
⎕NS Create Namespace | creates namespace and copies in objects
⎕OR Object Representation | converts to object representation
⎕WC Create Object | creates new object with specified properties
⎕WG Get Properties | gets values of properties from an object
⎕WN Object Names | reports names of all children of an object
⎕WS Set Properties | sets values of properties for an object


ProgressBar Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | GotFocus
Help | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Select |


ProgressBar Methods

Animate | Detach | GetFocus
GetTextSize | ProgressStep | ShowSIP


ProgressBar Properties

Type | Posn | Size
Style | Coord | Active
Visible | Event | Thumb
Step | Wrap | Limits
Sizeable | Dragable | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | ProgressStyle
Redraw | TabIndex | Interval
MethodList | ChildList | EventList
PropList |  |


Properties

Property | Description
Accelerator | specifies keystroke that will generate Select event
Active | determines whether object can generate events
Align | determines the position of text or for Scroll object
AlignChar | specifies a character for column alignment in a Grid
AlwaysShowBorder | specifies how the current cell in a Grid is displayed when the Grid loses focus.
AlwaysShowSelection | specifies how the highlighted selection in an object is displayed when the object loses focus.
APLVersion | reports the version of Dyalog APL being run
ArcMode | determines how arcs are drawn (Ellipse)
Attach | specifies how object is reconfigured when parent is resized
AutoArrange | whether or not items in a ListView are rearranged automatically
AutoBrowse | specifies whether or not functions and variables are fixed when an OLEClient is created
AutoConf | how a child reacts to its parent being resized
AutoExpand | whether rows and columns are added to a Grid
BandBorders | Specifies whether or not narrow lines are drawn to separate adjacent bands in a CoolBar
BCol | specifies background colour
Bits | defines the pattern for a Bitmap, Cursor,or Icon
Border | determines whether or not an object has a border
BtnPix | associates Bitmaps with Button, Menu and MenuItem objects
Btns | determines the buttons shown in a MsgBox
CalendarCols | Specifies the colours used for various elements in the Calendar object
Cancel | used to associate the Esc key with a particular Button
Caption | specifies text in an object
CBits | represents the picture in a Bitmap object
CellFonts | specifies fonts to be used by the cells in a Grid
CellHeights | specifies the heights of the cells in a Grid
CellSelect | specifies the type(s) of selection a user can perform in a Grid
CellSet | flags which cells in a Grid have values and which are empty
CellTypes | specifies the type of the cells in a Grid
Cells | specifies the widths of cells in a Grid
Changed | flags whether or not data in an object has been changed
CharFormat | specifies character formatting in a RichEdit
CharSet | specifies the character encoding of a Font object.
CheckBoxes | specifies whether or not check boxes are displayed alongside items in a ListView or TreeView object
Checked | determines whether check mark is displayed by MenuItem
ChildEdge | specifies whether or not a CoolBand leaves space above and below its child window
ChildList | reports the types of object that may be children of an object
CircleToday | specifies whether or not a circle is drawn around the Today date in a Calendar object
ClassID | reports the CLSID of an OLEClient or OLEServer
ClassName | specifies the name of the OLE object to which an OLEClient object is to be connected.
ClipCells | specifies whether or not columns of a Grid are clipped.
CMap | defines a colour map for a Bitmap or Icon
ColLineTypes | specifies the appearance of vertical grid lines in a Grid.
ColSortImages | specifies the images to be used to display sort images in the column titles of a Grid.
ColTitle3D | specifies the appearance of column titles for a ListView
ColTitleAlign | specifies the alignment of column titles
ColTitleBCol | specifies the background colour for column titles
ColTitleDepth | specifies the structure of hierarchical column titles for a Grid
ColTitleFCol | specifies the colour of the row titles in a Grid
ColTitles | specifies the column titles for a Grid or ListView
Column | specifies the width of columns for a multi-column List
Container | the Object Representation of an ActiveXContainer object
Coord | specifies the coordinate system for an object
CurCell | identifies the current cell in a Grid
CurrentColor | Specifies the currently selected colour in a ColorButton object
CurrentState | reports the current state of a TCPSocket object
CursorObj | associates a cursor with an object
CustomColors | Specifies the custom colors associated with a ColorButton object
Decimals | specifies the number of decimal places for a Numeric field
Default | nominates a Button to be selected with the Enter key
DefaultColors | Specifies the default colors associated with a ColorButton object
Depth | specifies the structure of items for a TreeView
DevCaps | reports the device capabilities of the screen or printer
Directory | specifies the directory for a FileBox
Divider | controls the presence or absence of a recessed line in a ToolControl object
Dragable | specifies whether user may drag an object with the mouse
Dragitems | specifies whether user may drag/drop items in a ListView
Dragitems | specifies whether user may drag/drop items in a ListView
DrawMode | provides direct control over the low-level drawing operation performed by graphical objects
EdgeStyle | specifies 3-dimensional appearance
EditLabels | specifies whether or not the user may edit the labels in a ListView or TreeView
Encoding | specifies how character data are encoded or translated for a TCPSocket
EnterReadOnlyCells | specifies whether or not the user may visit read-only cells in a Grid
EvaluationDays | Specifies the number of days before the evaluation version of a Dyalog APL application expires. PocketAPL only.
Event | associates an event with a callback funtion or ⎕DQ termination
EventList | reports names of events generated by an object
ExportedFns | specifies the functions to be exposed as methods by an OLEServer object
ExportedVars | specifies the variables to be exposed as properties by an OLEServer object
FCol | specifies foreground colour
FieldType | specifies formatting and validation
FileMode | specifies the mode (read or write) for a FileBox object
File | specifies a filename
FillCol | specifies fill colour
Filters | specifies file filters for a FileBox
FirstDay | specifies the day that is considered to be the first day of the week for a Calendar object
Fixed | specifies whether a font is fixed-width or proportional
FixedOrder | specifies whether or not the CoolBar displays CoolBands in the same order
FlatSeparators | specifies whether or not separators are drawn between buttons in a TabControl object
FontList | provides a list of available fonts
FontObj | specifies the font to be used
Formats | data formats currently available from the Clipboard object
Formatstring | defines a ⎕FMT specification to be used to format a numeric value
FStyle | specifies fill style
FullRowSelect | specifies whether or not the entire row is highlighted when an item in a ListView or a TreeView is selected
GridBCol | specifies the background colour for a Grid
GridFCol | specifies the colour of (all) grid lines for a Grid
GridLineFCol | specifies grid line colours for a Grid
GridLine | specifies grid line widths for a Grid
GridLines | specifies whether or not lines are displayed between items in a ListView object
GripperMode | specifies whether or not a CoolBand has a gripper bar
HAlign | specifies horizontal text alignment
Handle | Returns the window handle of an object
HasApply | Specifies whether or not a PropertySheet has an Apply button
HasButtons | Specifies whether or not a TreeView object displays buttons
HasHelp | Specifies whether or not a Help button is displayed or active
HasLines | Specifies whether or not a TreeView object displays tree lines
HasTicks | Specifies whether or not tick marks are displayed in a TrackBar
HasToday | Specifies whether or not the Today date is displayed in the bottom left corner of a Calendar object
Header | specifies whether or not column titles are displayed in a ListView
HelpButton | specifies whether or not a question (?) button appears in the title bar of a Form
HelpFile | reports the name of a help file associated with an OLE Control
HintObj | specifies the object in which to display the Hint
Hint | specifies the text for a context sensitive help message
HotSpot | specifies the hotspot for a Cursor
HotTrack | specifies whether or not the tabs or buttons in a TabControl object are automatically highlighted by the mouse pointer
HScroll | determines whether an object has a horizontal scrollbar
IconObj | associates an Icon with a minimized Form
ImageCount | Reports the number of images in an ImageList
ImageIndex | Maps images in an ImageList to items in a ListView or TreeView
ImageListObj | Associates an ImageList with a ListView or TreeView
Index | position of items in Combo or List, or selected filter in a FileBox
Input | names of objects associated with cells of Grid
InputMode | specifies the behaviour of cursor keys etc. in a Grid
InputModeKey | specifies the key used to switch to Incell editing in a Grid
InputProperties | Specifies the mapping between the Values property of a Grid and properties of external objects (ActiveX controls and .NET classes) which are displayed in Grid cells.
Interval | frequency with which a Timer generates events
Italic | specifies whether or not a font is italic
Items | list of items
ItemGroups | specifies item groupings for a ListView object
ItemGroupMetrics | specifies caption, colours and spacing for grouped items in a ListView object
Justify | determines how text is justified within an object
KeepBits | determines how Bitmap objects are stored in the workspace
KeepOnClose | determines whether or not namespaces are retained when their GUI components are destroyed
LastError | provides information about the most recent error reported by OLE
Limits | specifies minimum and maximum values for an object
LocalAddrName | specifies the host name of your computer
LocalAddr | specifies the IP address of your computer
Locale | specifies the language in which the OLE server, attached to an OLEClient, exposes its methods and properties
LocalPortName | specifies the port name of the local service that you wish to offer as a TCP/IP server
LocalPort | identifies the port number associated with a TCPSocket object
LStyle | specifies line style
L | specifies line width
MapCols | specifies whether button colours in bitmaps and icons in an ImageList are re-mapped to reflect the users colour preferences
Masked | specifies the type of image in an ImageList
Mask | specifies the mask for a Cursor or Icon
MaxButton | determines whether or not a Form has a “maximize” button
MaxDate | specifies the largest date that may be displayed by a Calendar object
MaxLength | specifies the maximum number of characters that the user may enter into an object
MaxSelCount | specifies the maximum number of contiguous days that the user may select in a Calendar object
MDIActive | specifies the name of the active SubForm in an MDI application
MDIActiveObject | specifies a ref to the active SubForm in an MDI application
MDIMenu | nominates a particular Menu to be the MDI application menu
Metafile | accesses clipboard data in Windows Metafile format
MethodList | reports the names of methods provided by an OLE Control
MinButton | determines whether a Form has a “minimize” button
MinDate | Specifies the smallest date that may be displayed by a Calendar object
MonthDelta | specifies the number of months by which a Calendar object scrolls when the user clicks its scroll buttons
Moveable | determines whether a Form may be moved on the screen
MultiColumn | specifies whether or not a List displays items in more than one column
MultiLine | determines whether or not the tabs or buttons will be arranged in multiple flights or multiple rows/columns in a TabControl or ToolControl object
MultiSelect | specifies whether or not the user can select more than one button in a TabControl at the same time
NewLine | specifies whether or not a CoolBand starts a new row in a CoolBar
OLEControls | reports the names of OLE Controls installed on the computer
OnTop | specifies that a Form is permanently raised to the front or specifies the level at which a graphic is drawn on a Grid
Orientation | specifies the orientation of the Printer
OtherButton | Specifies whether or not a ColorButton object displays an Other button, that allows access to custom colours.
OverflowChar | specifies the character to be displayed in a Grid cell to indicate that its contents will not fit
PageActive | specifies the name of the current PropertyPage in a PropertySheet
PageActiveObject | specifies a ref to the current PropertyPage in a PropertySheet
Page | specifies the width of the paper for a RichEdit
ParaFormat | specifies paragraph formatting for a RichEdit
Password | specifies the symbol for a password field
Picture | specifies a BitMap, Icon or Metafile object to be drawn
PName | specifies the device for a Printer object,or the face name for a Font
Points | specifies points for graphical objects
Popup | specifies the name of a (popup) Menu object that is associated with a ToolButton
Posn | specifies the position of an object within its parent
PrintList | reports the list of installed printers
ProgressStyle | specifies the appearance of a ProgressBar control
PropList | reports the list of properties applicable to the object
QueueEvents | specifies how events are handled for an instance of an OCXClass object (an ActiveX control)
Radius | specifies the radius for a Circle
Range | specifies the range of a scrollbar
ReadOnly | specifies whether or not the user may change data in an Edit orSpinner, or the State of a Button
RealSize | specifies the size of a placeable Metafile
Redraw | specifies whether or not an object is automatically redrawn when required
RemoteAddrName | specifies the host name of the remote computer to which you wish to make a TCP/IP connection
RemoteAddr | identifies the port number associated with a service on a remote computer
RemotePortName | specifies the port name of the remote service to which you wish to make a TCP/IP connection
RemotePort | identifies the port number associated with a service on a remote computer
ReportInfo | specifies additional information for a ListView
ResizeCols | specifies whether or not the user may alter the width of columns in a Grid by dragging
ResizeColTitles | specifies whether or not the user may alter the height of the column titles in a Grid by dragging
ResizeRows | specifies whether or not the user may alter the height of rows in a Grid by dragging
ResizeRowTitles | specifies whether or not the user may alter the width of the row titles in a Grid by dragging
Rotate | specifies the angle of rotation for a font
RowLineTypes | specifies the appearance of horizontal grid lines in a Grid.
Rows | number of rows displayed in drop-down list of a Combo
RowTitleAlign | specifies the alignment of the row titles in a Grid
RowTitleBCol | specifies the background colour for row titles
RowTitleDepth | specifies the structure of hierarchical row titles in a Grid
RowTitleFCol | specifies the colour of the row titles in a Grid
RowTitles | specifies the row titles for a Grid
RowTreeDepth | specifies the structure of rows for a Grid
RowTreeImages | specifies the images (bitmaps) for the treeview items in a Grid
RowTreeStyle | specifies the appearance of treeview items in a Grid
RTFText | specifies the contents of an object in Rich Text Format
RunMode | specifies the way in which an OLEServer object serves multiple clients
ScrollOpposite | specifies that unneeded tabs scroll to the opposite side of a TabControl
SelDate | identifies the range of dates that is currently selected in a Calendar object
SelImageIndex | specifies which images in an ImageList are used to identify selected items in a TreeView
SelItems | specifies the selected item(s) in an object.
SelRange | specifies the selected range in a TrackBar
SelText | specifies the selected text in an Edit or Combo
ServerVersion | specifies the version number of an OLEServer object
ShowCaptions | specifies whether or not the captions of individual ToolButton objects are drawn
ShowDropDown | specifies whether or not a drop-down menu symbol is drawn in a ColorButton or alongside ToolButton objects
ShowInput | determines how Combo and Button objects associated with cells of a Grid are displayed
ShowSession | specifies whether or not the APL Session window is displayed when an OLEServer object is started by an OLE client
ShowThumb | specifies whether or not the thumb is displayed in a TrackBar
SingleClickExpand | specifies whether or not an item in a TreeView control is expanded when the user selects the item
SIPMode | specifies the behaviour of the Input Panel (PocketAPL only)
SIPResize | specifies the resize behaviour of a Form when the Input Panel is raised and lowered (PocketAPL only)
Sizeable | specifies whether user may resize an object using the mouse
Size | specifies the size of an object
SocketNumber | reports the Window handle of the socket attached to the TCPSocket object
SocketType | specifies the type of the TCP/IP socket for a TCPSocket object.
SortItems | specifies whether or not the items in a List object are sorted.
SplitObj1 | specifies the name of an object managed by a Splitter
SplitObj2 | specifies the name of an object managed by a Splitter
Start | specifies start angles for arcs of Circle and Ellipse objects
State | specifies the state of a Button or Form
Step | increments for movement
Style | specifies the style of an object
SysMenu | determines whether a Form has a standard system menu
TabFocus | specifies the focus behaviour for the TabControl object
TabIndex | Specifies the tabbing order for controls
TabJustify | Specifies the positions at which the picture and caption are drawn within a TabButton
TabObj | specifies name of SubForm associated with a TabBtn
TabSize | specifies the size of fixed size tabs or buttons in a TabControl object
TargetState | reports the intended final state of a TCPSocket object
Text | specifies/reports the text in an Edit, MsgBox, or Combo
TextSize | reports the bounding rectangle for text
Thumb | specifies the position of the thumb in a scrollbar
ThumbRect | reports the extents of the thumb in a TrackBar
TickAlign | specifies the alignment of tick marks in a TrackBar
TickSpacing | specifies the spacing of tick marks in a TrackBar
TipObj | specifies the object in which to display the Tip
Tip | specifies the text for a pop-up help message
TitleHeight | specifies the height of the column titles in a Grid
Title | specifies the width of the row titles in a Grid
Today | specifies today’s date in a Calendar object
ToolboxBitmap | reports the bitmap image associated with an OLE Control
TrackRect | reports the extents of the slider in a TrackBar
Translate | specifies whether or not an object performs ⎕AV translation
Transparent | specifies whether or not a ToolControl is transparent
TypeLibFile | reports the name of the file in which the Type Library for an OLEServer object is stored
TypeLibID | reports the value of the globally unique identifier (GUID) of the Type Library associated with an OLEServer object.
TypeList | reports the names of data types associated with an OLE Control
Type | specifies the type of an object
Underline | specifies whether or not a font is underlined
UpperCase | specifies that property names are to be reported in uppercase
ValidIfEmpty | specifies whether or not an empty Edit object is deemed to be valid
VAlign | specifies vertical text alignment
Value | value of a number, date or time in an Edit or Label object
Values | the data matrix in a Grid
VariableHeight | specifies whether or not a CoolBar displays bands at the minimum required height, or all the same height
View | specifies how items in a ListView are arranged
Visible | specifies whether or not an object is currently visible
VScroll | specifies whether or not an object has a vertical scrollbar
WantsReturn | specifies how the Enter key is treated by an edit box
WeekNumbers | specifies whether or not a Calendar object displays week numbers
Weight | specifies the weight (boldness) of a font
WordFormat | specifies word formatting for a RichEdit
Wrap | specifies whether or not an object wraps its contents
XRange | specifies origin and scale on the x-axis
Yield | specifies how frequently Dyalog APL/W yields control
YRange | specifies origin and scale on the y-axis


Properties

Introduction

Simple Instance Properties

Simple Shared Properties

Numbered Properties

Numbered Properties (Example)

The Default Property

Keyed Properties

Keyed Property Example 1

Keyed Property Example 2


PropertyArguments Class Popup

PropertyArguments Class

PropertyArguments has 2-3 read-only Fields which are as follows:

Name | The name of the property. This is useful when one function is handling several properties.
NewValue | Array containing the new value for the Property or for selected element(s) of the property as specified by Indexers.
Indexers | If present, an array that identifies the element(s) of the Property that are to be referenced or assigned.


PropertyPage Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | GotFocus | Help
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
PageActivate | PageApply | PageBack
PageCancel | PageChanged | PageDeactivate
PageFinish | PageHelp | PageNext
SetWizard |  |


PropertyPage Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


PropertyPage Properties

Type | Caption | Posn
Size | Coord | Active
Event | HasHelp | FontObj
Data | EdgeStyle | Hint
HintObj | Tip | TipObj
Changed | Translate | AcceptFiles
KeepOnClose | MethodList | ChildList
EventList | PropList |


PropertySheet Events

Close | Create | FontCancel
FontOK |  |


PropertySheet Methods

CancelToClose | ChooseFont | Detach
GetFocus | SetFinishText | Wait


PropertySheet Properties

Type | Caption | Posn
Size | Style | Coord
Active | Visible | Event
HasApply | HasHelp | PageActive
PageActiveObject | FontObj | OnTop
Data | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Query Access Control

R←⎕SVC Y

This system function queries the access control on one or more shared variables.

Y is a character scalar, vector, or matrix containing names of shared variables. Each name may optionally be paired with its surrogate. If so, the surrogate must be separated from the name by at least one space.

If Y specifies a single name, the result R is a Boolean vector containing the current effective access control vector. If Y is a matrix of names, R is a Boolean matrix whose rows contain the current effective access control vectors for the corresponding row in Y.

For further information, see the preceding section on setting the access control vector.

Example:

      ⎕SVC 'X'
0 0 0 0


Query Couplings

R←⎕SVO Y

This system function returns the current degree of coupling for one or more shared variables.

Y is a character scalar, vector or matrix. If it is a vector it contains a shared variable name and optionally its external name or surrogate separated from it by one of more blanks.

If Y is a scalar, it specifies a single 1-character name. If Y is a matrix, each row of Y specifies a name and an optional external name as for the vector case.

If Y specifies a single name, the result R is a vector whose value 0, 1 or 2 indicates its current degree of coupling. If Y specifies more than one name, R is a vector whose elements indicate the current degree of coupling of the variable specified by the corresponding row in Y. A value of 2 indicates that the variable is fully coupled (via a warm or hot DDE link) with a shared variable in another APL workspace, or with a DDE item in another application. A value of 1 indicates that you have offered the variable but there is no such connection, or that the second application rejected a warm link. In this case, a transfer of data may have taken place (via a cold link) but the connection is no longer open. A value of 0 indicates that the name is not a shared variable.

Examples:

      ⎕SVO 'X'
2
      ⎕SVO ↑'X SALES' 'Y' 'JUNK'
2 1 0


Query External Variable

External Variable Query

R←⎕XT Y

Y must be a simple character scalar or vector which is taken to be a variable name.  R is a simple character vector containing the file reference of the external array associated with the variable named by Y, or the null vector if there is no associated external array.

Example:

      ⎕XT'V'
EXT/ARRAY

      ⍴⎕XT'G'
0


Query Monitor

Monitor Query

R←⎕MONITOR Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator.  R is a simple non-negative integer matrix of 5 columns with one row for each line in the function or operator Y which has the monitor set, giving:

Column 1 | Line number
Column 2 | Number of times the line was executed
Column 3 | CPU time in milliseconds
Column 4 | Elapsed time in milliseconds
Column 5 | Reserved

The value of 0 in column one indicates that the monitor is set on the function or operator as a whole.

Example:

      ∇ FOO
[1]     A←?25 25⍴100
[2]     B←⌹A
[3]     C←⌹B
[4]     R1←⌊0.5+A+.×B
[5]     R2←A=C
      ∇

      (0,⍳5) ⎕MONITOR 'FOO' ⍝ Set monitor

      FOO                   ⍝ Run function

      ⎕MONITOR 'FOO'        ⍝ Monitor query
0 1 1418 1000 0
1 1   83    0 0
2 1  400    0 0
3 1  397    0 0
4 1  467 1000 0
5 1  100    0 0


Query Stop

Query Stop Vector

R←⎕STOP Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator.  R is a simple non-negative integer vector of the line numbers of the function or operator named by Y on which stop controls are set, shown in ascending order.  The value 0 in R indicates that a stop control is set immediately prior to exit from the function or operator.

Example:

      ⎕STOP'FOO'
0 1


Query Trace

Trace Query

R←⎕TRACE Y

Y must be a simple character scalar or vector which is taken to be the name of a visible defined function or operator.  R is a simple non-negative integer vector of the line numbers of the function or operator named by Y on which trace controls are set, shown in ascending order.  The value 0 in R indicates that a trace control is set to display the result of the function or operator immediately prior to exit.

Example:

      ⎕TRACE'DSL'
0 1 2 3 4 5 6


Question Mark

Question Mark;Query

?

Monadic Question Mark means

Roll

      ? 1000 1000 1000 9000
756 459 533 1971

Dyadic Question Mark means

Deal

      7 ? 1000
67 418 687 589 931 847 527

Language Elements


Rect Events

Close | Create | DragDrop
Help | MouseDblClick | MouseDown
MouseMove | MouseUp | Select


Rect Methods

Detach


Rect Properties

Type | Points | Size
Radius | FCol | BCol
LStyle | L | FStyle
FillCol | Coord | Visible
Event | Dragable | OnTop
CursorObj | AutoConf | Data
EdgeStyle | Accelerator | KeepOnClose
DrawMode | MethodList | ChildList
EventList | PropList |


:Repeat Statement Definition

:Repeat Statement

Repeat:
       |
       :Repeat
       |
       code
       |
       .---------------.
       |               |
       :End[Repeat]    :Until bexp
       |               |
       |               .-------.
       |               |       |
       |               |       andor
       |               |       |
       |               |<------'
       |               |
       |<--------------'
       |


Rho

⍴

Monadic Rho means

Shape Of

      ⍴ 15 3 7 8 75.53
5

Dyadic Rho means

Reshape

      2 3 4 ⍴ 15 3 7 8 75.53
15     3     7     8
75.53 15     3     7
 8    75.53 15     3

 7     8    75.53 15
 3     7     8    75.53
15     3     7     8

Language Elements


RichEdit Events

Change | Close | Configure
ContextMenu | Create | DragDrop
DropFiles | DropObjects | Expose
FontCancel | FontOK | GotFocus
Help | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Protected | Select


RichEdit Methods

Animate | ChooseFont | Detach
FileRead | FileWrite | GetFocus
GetTextSize | RTFPrint | RTFPrintSetup
ShowSIP |  |


RichEdit Properties

Type | Text | Posn
Size | File | Coord
Border | Active | Visible
Event | VScroll | HScroll
SelText | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Changed | RTFText
Translate | Accelerator | CharFormat
WordFormat | ParaFormat | PageWidth
AcceptFiles | WantsReturn | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Right Arrow

→

Niladic Right Arrow means

Abort

      →

Monadic Right Arrow means

Branch To

      → 10

Language Elements


Right Shoe

Right Shoe;Superset Of

⊃

Monadic Right Shoe means

If ⎕ML<2 Disclose;First

      ⊃ (2 2)(3 3 3)
2 2

If ⎕ML≥2 Mix

      ⊃ (2 2)(3 3 3)
2 2 0
3 3 3

Dyadic Right Shoe means

Pick

      2 ⊃ (2 2)(3 3⍴3)
3 3 3
3 3 3
3 3 3

Language Elements


Root Events

ActivateApp | DisplayChange | DDE
ExitApp | ExitWindows | FontCancel
FontOK | Idle | SysColorChange
WinIniChange |  |


Root Methods

ChooseFont | DateToIDN | DeleteTypeLib
Flush | GetBuildID | GetCommandLine
GetCommandLineArgs | GetEnvironment | GetFocus
GetTextSize | GreetBitmap | IDNToDate
ListTypeLibs | NameFromHandle | ShowSIP
TCPGetHostID | Wait |


Root Properties

Type | Caption | Posn
Size | DevCaps | Coord
Event | FontObj | FontList
PrintList | IconObj | CursorObj
YRange | XRange | Data
TextSize | Yield | EdgeStyle
HintObj | TipObj | Translate
UpperCase | APLVersion | EvaluationDays
KeepOnClose | OLEControls | OLEServers
LastError | RadiusMode | MethodList
ChildList | EventList | PropList


Scalar Dyadic Arithmetic Functions

Add | ⍺+⍵ | ⍺ added to ⍵
Subtract | ⍺⍎⍵ | ⍵ subtracted from ⍺
Multiply | ⍺×⍵ | ⍺ multiplied by ⍵
Divide | ⍺÷⍵ | ⍺ divided by ⍵
Residue | ⍺|⍵ | remainder on dividing ⍺ into ⍵
Minimum | ⍺⌊⍵ | lesser of ⍺ and ⍵
Maximum | ⍺⌈⍵ | greater of ⍺ and ⍵
Power | ⍺*⍵ | ⍺ to power ⍵
Logarithm | ⍺⍟⍵ | log of ⍵ to base ⍺
Binomial | ⍺!⍵ | combinations of ⍵ taken ⍺ at a time


Scalar Dyadic Circular Functions

Scalar Dyadic Circular Function

Pythagorean Functions
Altitude | 0○⍵ | 1-⍵*2)*0.5
Hypotenuse | 4○⍵ | (1+⍵*2)*0.5
Leg | ¯4○⍵ | (¯1+⍵*2)*0.5
Trigonometric Functions
Sin | 1○⍵ | trigonometric sine of angle ⍵ radians
Cos | 2○⍵ | trigonometric cosine of angle ⍵
Tan | 3○⍵ | trigonometric tangent of angle ⍵
Arcsin | ¯1○⍵ | inverse trigonometric sine of ⍵
Arccos | ¯2○⍵ | inverse trigonometric cosine of ⍵
Arctan | ¯3○⍵ | inverse trigonometric tangent of ⍵
Hyperbolic Functions
Sinh | 5○⍵ | hyperbolic sine of ⍵
Cosh | 6○⍵ | hyperbolic cosine of ⍵
Tanh | 7○⍵ | hyperbolic tangent of ⍵
Arcsinh | ¯5○⍵ | inverse hyperbolic sine of ⍵
Arccosh | ¯6○⍵ | inverse hyperbolic cosine of ⍵
Arctanh | ¯7○⍵ | inverse hyperbolic tangent of ⍵


Scalar Dyadic Logical Functions

And, LCM | ⍺∧⍵ | logical conjunction or lowest common multiple of ⍺ and ⍵
Or, GCD | ⍺∨⍵ | logical disjunction or greatest common divisor of ⍺ and ⍵
Nand | ⍺⍲⍵ | not both ⍺ and ⍵
Nor | ⍺⍱⍵ | neither ⍺ nor ⍵
Less | ⍺<⍵ | ⍺ is less than ⍵
Less or Equal | ⍺≤⍵ | ⍺ is less than or equal to ⍵
Equal | ⍺=⍵ | ⍺ is equal to ⍵
Greater or Equal | ⍺≥⍵ | ⍺ is greater than or equal to ⍵
Greater | ⍺>⍵ | ⍺ is greater than ⍵
Not Equal | ⍺≠⍵ | ⍺ is not equal to ⍵


Scalar Monadic Functions

Identity | +⍵ | return ⍵
Negative | –⍵ | zero minus ⍵
Signum | ×⍵ | direction of ⍵
Reciprocal | ÷⍵ | one divided by ⍵
Magnitude | |⍵ | absolute distance of ⍵ from origin
Floor | ⌊⍵ | largest integer less or equal to ⍵
Ceiling | ⌈⍵ | smallest integer greater or equal to ⍵
Exponential | *⍵ | e(2.71828...) to power ⍵
Natural Log | ⍟⍵ | natural logarithm of ⍵
Pi Times | ○⍵ | Pi(3.14159...) times ⍵
Factorial | !⍵ | Gamma function of ⍵+1
Not | ~⍵ | logical negation of ⍵
Roll | ?⍵ | random integer from index origin to ⍵
Type | ∊⍵ | zero for a number, blank for a character


Scroll Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | GotFocus
Help | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Scroll | Select


Scroll Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


Scroll Properties

Type | Posn | Size
Coord | Align | Border
Active | Visible | Event
Thumb | Range | Step
VScroll | HScroll | Limits
Sizeable | Dragable | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
MethodList | ChildList | EventList
PropList |  |


:Select Statement Definition

:Select Statement

Select:
       |
       :Select aexp
       |
       |<----------------------------------------------.
       |                                               |
       .-------.-------.---------------.               |
       |       |       |               |               |
       |       :Else   :Case aexp      :CaseList aexp  |
       |       |       |               |               |
       |       |       |<--------------'               |
       |       |       |                               |
       |       code    code                            |
       |       |       |                               |
       |<------'       `-------------------------------'
       |
       :End[Select]


Separator Events

Close Create


Separator Methods

Detach


Separator Properties

Type | Posn | Style
Event | FCol | BCol
Data | EdgeStyle | Translate
KeepOnClose | MethodList | ChildList
EventList | PropList |


Sequence Selection & Index Selection

Sequence Selection /... Index Selection
/⍳⍴

In addition to providing improved performance, the Sequence Selection and Index Selection idioms reduce intermediate workspace usage and consequently, the incidence of memory compactions and the likelihood of a WS FULL.


Set Intersection

Set Intersection;Up Shoe

∩

Monadic Set Intersection is not defined

Dyadic Set Intersection means

Intersection

      22 'ab' 'fg' ∩ 'a' 'ab' 22
22  ab

Language Elements


Set Union

Set Union;Down Shoe

∪

Monadic Set Union means

Unique

       ∪ 'ab' 'ba' 'ab' 1 1 2
 ab  ba  1 2

Dyadic Set Union means

Union

      'ab' 'cde' 'fg' ∪ 'a' 'ab'
 ab  cde  fg a

Language Elements


(Shell) Command

UNIX Shell Command

⎕SH

Monadic ⎕SH means

Execute Command

      ⎕SH 'set'
PROMPT=$P$G
PATH=c:\Dyalog82\;C:\WINDOWS
MSINPUT=C:\MSINPUT
TEMP=C:\TEMP
TMP=C:\TMP
CLASSPATH=;C:\Exceed95

Dyadic ⎕SH means

Start Auxiliary Processor

      'XUTILS' ⎕SH ''

Language Elements


Slash

/

USED AS A FUNCTION

Monadic Slash is not defined

Dyadic Slash means

Replicate

      2 1 3 3 / 3.1 4 1 3.2
3.1 3.1 4 1 1 1 3.2 3.2 3.2

USED AS AN OPERATOR

Slash is a Monadic operator with a Dyadic operand

Operator Slash with a Monadic derived function means

Reduce

      ∧/ 2 3 4⍴1 1 1 1 0
1 0 0
0 0 1

Operator Slash with a Dyadic derived function means

N-wise Reduce

      ¯2 -/ 1 3 4 1
2 1 ¯3

Language Elements


Slash Bar

⌿

USED AS A FUNCTION

Monadic Slash Bar is not defined

Dyadic Slash Bar means

Replicate along First Axis

      2 3 ⌿ 2 29⍴'NETHOTSONDS1'
NETHOTSONDS1NETHOTSONDS1NETHO
NETHOTSONDS1NETHOTSONDS1NETHO
TSONDS1NETHOTSONDS1NETHOTSOND
TSONDS1NETHOTSONDS1NETHOTSOND
TSONDS1NETHOTSONDS1NETHOTSOND

USED AS AN OPERATOR

Slash Bar is a Monadic operator with a Dyadic operand

Operator Slash Bar means

Reduce along First Axis

      +⌿ 10 3⍴5
50 50 50

Language Elements


Slope

Slope;Back Slash

\

USED AS A FUNCTION

Monadic Slope is not defined

Dyadic Slope means

Expand

      3 ¯2 4 \ 3 2⍴1.1 2.2 3.3
1.1 1.1 1.1 0 0 2.2 2.2 2.2 2.2
3.3 3.3 3.3 0 0 1.1 1.1 1.1 1.1
2.2 2.2 2.2 0 0 3.3 3.3 3.3 3.3

USED AS AN OPERATOR

Slope is a Monadic operator with a Dyadic operand

Operator Slope means

Scan

      +\ 1 2 3 4 5 6 7 8 9 10
1 3 6 10 15 21 28 36 45 55

Language Elements


Slope Bar

Slope Bar;Back Slash Bar

⍀

USED AS A FUNCTION

Monadic Slope Bar is not defined

Dyadic Slope Bar means

Expand along First Axis

      0 1 1 2 ⍀ 3 6⍴'ABCDE'

ABCDEA
BCDEAB
CDEABC
CDEABC

USED AS AN OPERATOR

Slope Bar is a Monadic operator with a Dyadic operand

Scan along First Axis

      =⍀ 5 6⍴0 1 0
0 1 0 0 1 0
1 1 1 1 1 1
0 1 0 0 1 0
1 1 1 1 1 1
0 1 0 0 1 0

Language Elements


Slot Class

    :Class Slot
        :Field Public Time
        :Field Public Players

        ∇ ctor1 t
          :Implements Constructor
          :Access Public Instance
          Time←t
          Players←0⍴⊂''
        ∇
        ∇ ctor2 (t pl)
          :Implements Constructor
          :Access Public Instance
          Time Players←t pl
        ∇
        ∇ format
          :Implements Trigger Players
          ⎕DF⍕Time Players
        ∇
    :EndClass


SM Events

Close | Configure | Create
DragDrop | Help | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseUp |  |


SM Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


SM Properties

Type | Posn | Size
Coord | Border | Visible
Event | Sizeable | Dragable
BCol | Picture | CursorObj
AutoConf | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Sparse2 Class

:Class Sparse2  ⍝ 2D Sparse Array
    :Field Private keys
    :Field Private values
    ∇ make
      :Access Public
      :Implements Constructor
      keys←0⍴⊂'' ''
      values←⍬
    ∇
    :Property Keyed Values
    :Access Public Instance
        ∇ v←get arg;k
          k←arg.Indexers
          ⎕SIGNAL(2≠⍴k)/4
          k←fixkeys k
          v←(values,0)[keys⍳k]
        ∇
        ∇ set arg;new;k;v;n
          v←arg.NewValue
          k←arg.Indexers
          ⎕SIGNAL(2≠⍴k)/4
          k←fixkeys k
          v←(⍴k)(⍴⍣(⊃1=⍴,v))v
          ⎕SIGNAL((⍴k)≠⍴v)/5
          k v←,¨k v
          :If ∨/new←~k∊keys
              values,←new/v
              keys,←new/k
              k v/⍨←⊂~new
          :EndIf
          :If 0<⍴k
              values[keys⍳k]←v
          :EndIf
        ∇
    :EndProperty

    ∇ k←fixkeys k
      k←(2≠¨k){,(⊂⍣⍺)⍵}¨k
      k←⊃(∘.{⊃,/⊂¨⍺ ⍵})/k
    ∇
:EndClass ⍝ 2D Sparse Array


Specials

Special Syntax

Indexing | ⍺[⍵] | select elements of ⍺ given by ⍵
Assignment | ⍺←⍵ | ⍵ given name ⍺
Assignment (Indexed) | ⍺[;]←⍵ | assignment where LHS is ⍺[;]
Assignment (Selective) | (g⍺)←⍵ | assignment where LHS is (g⍺)
Assignment (Modified) | ⍺f←⍵ | variable ⍺ gets new value ⍺f⌈
Assignment (Mod. Indexed) | ⍺[;]f←⍵ | reassignment, where LHS is ⍺[;]
Assignment (Mod. Selective) | (g⍺)f←⍵ | reassignment, where LHS is (g⍺)
Axis Operator | f[K]⍵ | apply monadic f along axis K of ⍵, f can be ⌽ ⊖ ↑ ↓ or derived from ⌿ \ ⍀
Dyadic Axis Operator | ⍺f[K]⍵ | apply f along axis K, where dyadic f is , ⍪ ⌽ ⊖ ↑ ↓ / ⌿ \ ⍀


Spinner Events

BadValue | Change | Close
Configure | ContextMenu | Create
DragDrop | DropFiles | DropObjects
Expose | FontCancel | FontOK
GotFocus | Help | KeyError
KeyPress | LostFocus | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select | SetSpinnerText | Spin


Spinner Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Spinner Properties

Type | Items | Text
Posn | Size | Coord
Align | Border | Justify
Active | Visible | Event
Thumb | Step | Wrap
Limits | Sizeable | Dragable
FontObj | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | FieldType | MaxLength
Decimals | Password | ValidIfEmpty
ReadOnly | FormatString | Changed
Value | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Splitter Events

Close | Create | EndSplit
Splitting | StartSplit |


Splitter: Example 1

'F'⎕WC'Form' 'Vertical Splitter'('Size' 25 25)
'F.E1'⎕WC'Edit'(10 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.S'⎕WC'Splitter' 'F.E1' 'F.E2'


Splitter: Example 2

'F'⎕WC'Form' 'Horizontal Splitter'('Size' 25 25)
'F.E1'⎕WC'Edit'(5 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(5 6⍴'Edit 2')('Style' 'Multi')
'F.S'⎕WC'Splitter' 'F.E1' 'F.E2'('Style' 'Horz')


Splitter: Example 3

'F'⎕WC'Form' 'Multiple Splitters: hierarchical using SubForms'('Size' 25 50)
'F.E1'⎕WC'Edit'(10 6⍴'Edit 1')('Style' 'Multi')
'F.SF1'⎕WC'SubForm'('EdgeStyle' 'Default')
'F.S1'⎕WC'Splitter' 'F.E1' 'F.SF1'
'F.SF1.E1'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.SF1.E2'⎕WC'Edit'(10 6⍴'Edit 3')('Style' 'Multi')
'F.SF1.S1'⎕WC'Splitter' 'F.SF1.E1' 'F.SF1.E2'

After dragging the first Splitter to the left.


Splitter: Example 4

'F'⎕WC'Form' 'Multiple Splitters: non-hierarchical'('Size' 25 50)
'F.E1'⎕WC'Edit'(10 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.E3'⎕WC'Edit'(10 6⍴'Edit 3')('Style' 'Multi')
'F.S1'⎕WC'Splitter' 'F.E1'
'F.S2'⎕WC'Splitter' 'F.E2' 'F.E3'

After dragging the first Splitter to the left.


Splitter: Example 5

'F'⎕WC'Form' 'Combining Horizontal and Vertical Splitters'
'F.E1'⎕WC'Edit'(20 6⍴'Edit 1')('Style' 'Multi')
'F.E2'⎕WC'Edit'(10 6⍴'Edit 2')('Style' 'Multi')
'F.E3'⎕WC'Edit'(10 6⍴'Edit 3')('Style' 'Multi')
'F.E4'⎕WC'Edit'(5 6⍴'Edit 4')('Style' 'Multi')
'F.E5'⎕WC'Edit'(5 6⍴'Edit 5')('Style' 'Multi')

'F.S1'⎕WC'Splitter' 'F.E1'('Style' 'Vert')
'F.S2'⎕WC'Splitter' 'F.E2'('Style' 'Horz')
'F.S3'⎕WC'Splitter' 'F.E3'('Style' 'Vert')
'F.S4'⎕WC'Splitter' 'F.E4' 'F.E5'('Style' 'Horz')


Splitter Methods

Detach


Splitter Properties

Type | SplitObj1 | SplitObj2
Posn | Size | Style
Coord | Align | Active
Visible | Event | BCol
CursorObj | Data | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Star

*

Monadic Star means

Exponential

      * 2 2⍴1 2 3 4
 2.718281828  7.389056099
20.08553692  54.59815003

Dyadic Star means

Power

     (2 2⍴1 2 3 4) * 2 2⍴1 2 3 4
 1   4
27 256

Language Elements


StartingSheet Class

    :Class StartingSheet
        :Field Public OK
        :Field Public Course
        :Field Public Date
        :Field Public Slots←⎕NULL
        :Field Public Message

        ∇ ctor args
          :Implements Constructor
          :Access Public Instance
          OK Course Date←args
        ∇
        ∇ format
          :Implements Trigger OK,Message
          ⎕DF⍕2 1⍴(⍕Course Date)(↑⍕¨Slots)
        ∇
    :EndClass


Static Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | Help | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


Static Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


Static Properties

Type | Posn | Size
Style | Coord | Border
Active | Visible | Event
Sizeable | Dragable | FontObj
FCol | BCol | Picture
CursorObj | AutoConf | YRange
XRange | Data | Attach
TextSize | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


StatusBar Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | Help | MouseDblClick
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | MouseWheel
Select |  |


StatusBar Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


StatusBar Properties

Type | Posn | Size
Coord | Align | Border
Active | Visible | Event
VScroll | HScroll | Sizeable
FontObj | FCol | BCol
Picture | CursorObj | AutoConf
YRange | XRange | Data
Attach | TextSize | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


StatusField Events

Close | Create | DropObjects
MouseDblClick | MouseDown | MouseMove
MouseUp | Select |


StatusField Methods

Detach


StatusField Properties

Type | Caption | Text
Posn | Size | Style
Coord | Align | Border
Visible | Event | Sizeable
Dragable | FontObj | FCol
BCol | Picture | AutoConf
Data | Attach | EdgeStyle
Translate | Accelerator | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Stile

Stile;Vertical Bar

|

Monadic Stile means

Magnitude

      | 2.3 4 ¯2 0
2.3 4 2 0

Dyadic Stile means

Residue;Modulus

      2 | 2.3 4 ¯2 0 ¯2.3
0.3 0 0 0 1.7

Language Elements


Stream Sockets

A Stream socket is a connection-based transport that is analogous to a telephone service. A Stream socket handles error correction, guarantees delivery, and preserves data sequence. This means that if you send two messages to a recipient, the messages are sure to arrive and in the sequence that you sent them. However, individual messages may be broken up into several packets (or accumulated into one), and there is no predetermined protocol to identify message boundaries. This means that Stream-based applications must implement some kind of message protocol that both ends of a connection understand and adhere to.


SubForm Events

Close | Configure | ContextMenu
Create | DockAccept | DockCancel
DockEnd | DockMove | DockRequest
DockStart | DragDrop | DropFiles
DropObjects | Expose | FontCancel
FontOK | FrameContextMenu | GotFocus
Help | HScroll | KeyPress
LostFocus | MouseDblClick | MouseDown
MouseEnter | MouseLeave | MouseMove
MouseUp | MouseWheel | MDIActivate
MDIDeactivate | Select | StateChange
VScroll |  |


SubForm Methods

Animate | ChooseFont | Detach
GetFocus | GetTextSize | ShowSIP


SubForm Properties

Type | Caption | Posn
Size | Coord | State
Border | Active | Visible
Event | Thumb | Range
Step | VScroll | HScroll
Sizeable | Moveable | SysMenu
MaxButton | MinButton | HelpButton
FontObj | BCol | Picture
OnTop | IconObj | CursorObj
AutoConf | YRange | XRange
Data | Attach | TextSize
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
TabObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Dockable
Docked | DockShowCaption | DockChildren
UndocksToRoot | Redraw | TabIndex
MethodList | ChildList | EventList
PropList |  |


System Functions: APL Files

⎕FAPPEND | append component
⎕FAVAIL | file system availability
⎕FCREATE | create file
⎕FDROP | drop components
⎕FERASE | erase file
⎕FHOLD | hold file
⎕FLIB | file library list
⎕FNAMES | tied file names
⎕FNUMS | tied file numbers
⎕FPROPS | file properties
⎕FRDAC | read file access matrix
⎕FRDCI | read file component information
⎕FREAD | read component
⎕FRENAME | rename file
⎕FREPLACE | replace component
⎕FRESIZE | resize file
⎕FSIZE | file size
⎕FSTAC | set file access matrix
⎕FSTIE | share tie file
⎕FTIE | tie file
⎕FUNTIE | untie files
⎕XT | query external variable
⎕XT(Dyadic) | set external variable


System Functions: Event Trapping

⎕DM | diagnostic message
⎕EM | event messages
⎕EN | event numbers
⎕EXCEPTION | exception
⎕SIGNAL | signal event
⎕TRAP | trap events


System Functions: Functions, Operators & Namespaces

⎕AT | attributes
⎕CR | canonical representation
⎕CS | change (name)space
⎕CY | copy objects to active ws
⎕DF | display form
⎕ED | edit objects
⎕EX | expunge objects
⎕EXPORT | export objects
⎕FX | fix definition
⎕LOCK | lock object
⎕ML | migration level
⎕NC | name class
⎕NL | name list
⎕NR | nested representation
⎕NS | create namespace
⎕NSI | namespace indicator
⎕OR | object representation
⎕PATH | search path
⎕SIZE | size of objects
⎕THIS | this space
⎕USING | using (.net search path)
⎕VFI | verify & fix numerics
⎕VR | vector representation


System Functions: Graphical User Interface

⎕DQ | await & process (dequeue) events
⎕NQ | place event in queue (enqueue)
⎕SE | session namespace
⎕WC | create windows object
⎕WG | get windows object properties
⎕WN | query child object names
⎕WS | set windows object properties
⎕WX | expose windows object properties


System Functions: Input & Output

System Functions: Input/Output

⍞ | character input/output
⎕ | evaluated input/output
⎕Á | underscored alphabet
⎕A | alphabet
⎕ARBIN | arbitrary input
⎕ARBOUT | arbitrary output
⎕AV | atomic vector
⎕AVU | atomic vector - unicode
⎕D | digits
⎕DL | delay
⎕FMT | format
⎕FMT(Dyadic) | format by specification
⎕NULL | null item
⎕RTL | response time limit
⎕SD | screen dimensions
⎕SM | screen map
⎕SR | screen read
⎕TC | terminal control characters
⎕UCS | unicode convert


System Functions: MultiThreading

⎕TCNUMS | thread child numbers
⎕TGET | get tokens
⎕TID | current thread identity
⎕TKILL | kill thread
⎕TNAME | current thread name
⎕TNUMS | thread numbers
⎕TPOOL | token pool
⎕TPUT | put tokens
⎕TREQ | token requests
⎕TSYNC | wait for threads to terminate


System Functions: Native Files

⎕DR | data representation (monadic)
⎕DR(Dyadic) | data representation (dyadic)
⎕NAPPEND | appends value to a native file
⎕NCREATE | creates a native file
⎕NERASE | erases a native file
⎕NLOCK | locks a native file
⎕NNAMES | reports names of all open native files
⎕NNUMS | reports tie numbers of all open native files
⎕NREAD | reads data from a native file
⎕NRENAME | renames a native file
⎕NREPLACE | writes data to a native file, overwriting existing data
⎕NRESIZE | changes the size of a native file
⎕NSIZE | reports the current size of a native file
⎕NTIE | opens a native file
⎕NUNTIE | closes one or more native files
⎕NXLATE | specifies/reports character translation for a native file


System Functions: Object Oreinted Features

System Functions: Object Oriented Features

⎕BASE | base class
⎕CLASS | class
⎕DF | display form
⎕FIX | fix script
⎕INSTANCES | instances
⎕NEW | new instance
⎕SRC | source script
⎕THIS | this space


System Functions: Shared Variables

⎕SVC | query access control
⎕SVC(Dyadic) | set access control
⎕SVO | query degree of coupling
⎕SVO(Dyadic) | shared variable offer
⎕SVQ | shared variable query
⎕SVR | retract offer
⎕SVS | shared variable state


System Functions: State Indicator & Stack

⎕LC | line count
⎕MONITOR | query monitor
⎕MONITOR(Dyadic) | set monitor
⎕NSI | namespace indicator
⎕REFS | local references
⎕SHADOW | shadow names
⎕SI | state indicator
⎕STACK | state indicator stack
⎕STATE | state of an object
⎕STOP | query stop vector
⎕STOP(Dyadic) | set stop vector
⎕TRACE | query trace vector
⎕TRACE(Dyadic) | set trace vector
⎕XSI | extended state indicator


System Functions: System Operations

⎕CMD | execute command
⎕CMD(Dyadic) | start auxiliary processor
⎕MAP | map file
⎕NA | name association
⎕OFF | sign off
⎕SH | execute command
⎕SH(Dyadic) | start auxiliary processor
⎕TS | time stamp


System Functions: Workspace

⎕AI | account information
⎕AN | account name
⎕CLEAR | clear workspace
⎕CT | comparison tolerance
⎕DIV | division method
⎕IO | index origin
⎕KL | key label
⎕LOAD | load workspace
⎕LX | latent expression
⎕PFKEY | programmable function key
⎕PP | print precision
⎕PW | page width
⎕RL | random link
⎕SAVE | save workspace
⎕WA | workspace available
⎕WSID | workspace identification


System Commands

Object Commands | )CLASSES
 | )COPY {wsid {names}}
 | )CS {name}
 | )ED names
 | )ERASE names
 | )EVENTS
 | )FNS {name}
 | )METHODS
 | )NS {name}
 | )OBS {nms}
 | )OPS {name}
 | )PCOPY {wsid {names}}
 | )PROPS
 | )VARS {name}
Stack Commands | )RESET
 | )SI
 | )SINL
Workspace Commands | )CLEAR
 | )DROP {wsid}
 | )LIB {dir}
 | )LOAD {wsid}
 | )SAVE {wsid}
 | )WSID
 | )XLOAD {wsid}
Operating Commands | )CMD {cmd}
 | )CONTINUE
 | )OFF
 | )SH {cmd}
MultiThreading Commands | )HOLDS
 | )TID {tid}


System Functions

System Functions & Variables

Categorised System Functions & Variables

⍞ | character input/output
⎕ | evaluated input/output
⎕Á | underscored alphabet
⎕A | alphabet
⎕AI | account information
⎕AN | account name
⎕ARBIN | arbitrary input
⎕ARBOUT | arbitrary output
⎕AT | attributes
⎕AV | atomic vector
⎕AVU | atomic vector - unicode
⎕BASE | base class
⎕CLASS | class
⎕CLEAR | clear workspace
⎕CMD | (DOS) command
⎕CR | canonical representation
⎕CS | change (name)space
⎕CT | comparison tolerance
⎕CY | copy objects to active ws
⎕D | digits
⎕DF | display form
⎕DIV | division method
⎕DL | delay
⎕DM | diagnostic message
⎕DQ | await & process (dequeue) events
⎕DR | data representation
⎕ED | edit objects
⎕EM | event messages
⎕EN | event numbers
⎕EX | expunge objects
⎕EXCEPTION | exception
⎕EXPORT | export objects
⎕FAPPEND | append component
⎕FAVAIL | file system availability
⎕FCREATE | create file
⎕FDROP | drop components
⎕FERASE | erase file
⎕FHOLD | hold file
⎕FIX | fix script
⎕FLIBf | ile library list
⎕FMT | format
⎕FNAMES | tied file names
⎕FNUMS | tied file numbers
⎕FPROPS | file properties
⎕FRDAC | read file access matrix
⎕FRDCI | read file component information
⎕FREAD | read component
⎕FRENAME | rename file
⎕FREPLACE | replace component
⎕FRESIZE | resize file
⎕FSIZE | file size
⎕FSTAC | set file access matrix
⎕FSTIE | share tie file
⎕FTIE | tie file
⎕FUNTIE | untie files
⎕FX | fix definition
⎕INSTANCES | instances
⎕IO | index origin
⎕KL | key label
⎕LC | line count
⎕LOAD | load workspace
⎕LOCK | lock object
⎕LX | latent expression
⎕MAP | map file
⎕ML | migration level
⎕MONITOR | execution monitor
⎕NA | name association
⎕NAPPEND | appends value to a native file
⎕NC | name class
⎕NCREATE | creates a native file
⎕NERASE | erases a native file
⎕NEW | new instance
⎕NL | name list
⎕NNAMES | reports names of all open native files
⎕NNUMS | reports tie numbers of all open native files
⎕NQ | place event in queue (enqueue)
⎕NR | nested representation
⎕NREAD | reads data from a native file
⎕NRENAME | renames a native file
⎕NREPLACE | writes data to a native file, overwriting existing data
⎕NRESIZE | changes the size of a native file
⎕NS | create namespace
⎕NSI | namespace indicator
⎕NSIZE | reports the current size of a native file
⎕NTIE | opens a native file
⎕NULL | null item
⎕NUNTIE | closes one or more native files
⎕NXLATE | specifies/reports character translation for a native file
⎕OFF | sign off
⎕OR | object representation
⎕PATH | search path
⎕PFKEY | programmable function key
⎕PP | print precision
⎕PW | page width
⎕REFS | local references
⎕RL | random link
⎕RTL | response time limit
⎕SAVE | save workspace
⎕SD | screen dimensions
⎕SE | session namespace
⎕SH | (UNIX shell) command
⎕SHADOWs | hadow names
⎕SI | state indicator
⎕SIGNAL | signal event
⎕SIZE | size of objects
⎕SM | screen map
⎕SR | screen read
⎕SRC | source script
⎕STACK | state indicator stack
⎕STATE | state of an object
⎕STOP | stop vector
⎕SVCs | hared variable control
⎕SVO | shared variable offer
⎕SVQ | shared variable query
⎕SVR | retract offer
⎕SVS | shared variable state
⎕TC | terminal control characters
⎕TCNUMS | thread child numbers
⎕TGET | get tokens
⎕THIS | this space
⎕TID | current thread identity
⎕TKILL | kill thread
⎕TNAME | current thread name
⎕TNUMS | thread numbers
⎕TPOOL | token pool
⎕TRACE | trace vector
⎕TRAP | trap events
⎕TREQ | token requests
⎕TS | time stamp
⎕TSYNC | wait for threads to terminate
⎕UCS | unicode convert
⎕USING | using (.net search path)
⎕VFI | verify & fix numerics
⎕VR | vector representation
⎕WA | workspace available
⎕WC | create windows object
⎕WG | get windows object properties
⎕WN | query child object names
⎕WS | set windows object properties
⎕WSID | workspace identification
⎕WX | expose windows object properties
⎕XSI | extended state indicator
⎕XT | external variable


SysTrayItem Events

Close | Create | MouseDblClick
MouseDown | MouseMove | MouseUp


SysTrayItem Methods

Detach Wait


SysTrayItem Properties

Type | Event | IconObj
Data | Tip | Translate
Popup | KeepOnClose | MethodList
ChildList | EventList | PropList


TabBar Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | Help
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Select |


TabBar Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


TabBar Properties

Type | Posn | Size
Coord | Align | Active
Visible | Event | VScroll
HScroll | Sizeable | FontObj
BCol | Picture | OnTop
IconObj | CursorObj | AutoConf
YRange | XRange | Data
Attach | TextSize | Handle
Hint | HintObj | Tip
TipObj | TabObj | Translate
Accelerator | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


TabBtn Events

Close | Create | DropObjects
FontCancel | FontOK | MouseDblClick
MouseDown | MouseMove | MouseUp
Select |  |


TabBtn Methods

ChooseFont Detach


TabBtn Properties

Type | Caption | Posn
Size | Align | Border
Active | Visible | Event
FontObj | FCol | BCol
AutoConf | Data | Attach
EdgeStyle | TabObj | Translate
Accelerator | KeepOnClose | MethodList
ChildList | EventList | PropList


TabButton Events

Close Create Select


TabButton Methods

Detach


TabButton Properties

Type | Caption | Posn
Size | State | Event
ImageIndex | Data | Tip
TabObj | KeepOnClose | MethodList
ChildList | EventList | PropList


TabControl Events

Close Create


TabControl: Example 1

'F'⎕WC'Form' 'TabControl: Default'('Size' 25 50)
'F.TC'⎕WC'TabControl'

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 2

'F'⎕WC'Form' 'TabControl: Buttons Style'('Size' 25 50)
'F.TC'⎕WC'TabControl'('Style' 'Buttons')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)


TabControl: Example 3

'F'⎕WC'Form' 'TabControl: FlatButtons Style'('Size' 25 50)
'F.TC'⎕WC'TabControl'('Style' 'FlatButtons')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)


TabControl: Example 3a

'F1'⎕WC'Form' 'TabControl: FlatButtons with FlatSeparators'('Size' 25 50)
'F1.TC'⎕WC'TabControl'('Style' 'FlatButtons')('FlatSeparators' 1)

'F1.TC.IL'⎕WC'ImageList'
'F1.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F1.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F1.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F1.TC'⎕WS'ImageListObj' 'F1.TC.IL'

'F1.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F1.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F1.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)


TabControl: Example 4

'F'⎕WC'Form' 'TabControl: Align Bottom'('Size' 25 50)
'F.TC'⎕WC'TabControl'('Align' 'Bottom')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 5

'F'⎕WC'Form' 'TabControl: Align Left'('Size' 40 30)
'F.TC'⎕WC'TabControl'('Align' 'Left')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 6

'F'⎕WC'Form' 'TabControl: Align Right'('Size' 40 30)
'F.TC'⎕WC'TabControl'('Align' 'Right')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'One'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Two'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Three'('ImageIndex' 3)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')


TabControl: Example 7

'F'⎕WC'Form' 'TabControl: Default Scrolling'('Size' 25 40)
'F.TC'⎕WC'TabControl'

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)

'F.TC.S1'⎕WC'SubForm'('TabObj' 'F.TC.T1')
'F.TC.S2'⎕WC'SubForm'('TabObj' 'F.TC.T2')
'F.TC.S3'⎕WC'SubForm'('TabObj' 'F.TC.T3')
'F.TC.S4'⎕WC'SubForm'('TabObj' 'F.TC.T4')


TabControl: Example 8

'F'⎕WC'Form' 'TabControl: MultiLine Tabs'('Size' 25 40)
'F.TC'⎕WC'TabControl'('MultiLine' 1)

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 9

'F'⎕WC'Form' 'TabControl: MultiLine Buttons'('Size' 25 40)
'F.TC'⎕WC'TabControl'('Style' 'Buttons')( 'MultiLine' 1))

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 10

'F'⎕WC'Form' 'TabControl: ScrollOpposite'('Size' 25 40)
'F.TC'⎕WC'TabControl'('ScrollOpposite' 1)

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 11

'F'⎕WC'Form' 'TabControl: MultiLine Tabs, Justify None'('Size' 25 40)
'F.TC'⎕WC'TabControl'('MultiLine' 1)('Justify ' 'None')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 12

'F'⎕WC'Form' 'TabControl: MultiLine Buttons, Justify None'('Size' 25 40)
'F.TC'⎕WC'TabControl'('Style ' 'Buttons') ('MultiLine' 1)('Justify ' 'None')

'F.TC.IL'⎕WC'ImageList'
'F.TC.IL.'⎕WC'Icon'('' 'APLIcon')
'F.TC.IL.'⎕WC'Icon'('' 'FUNIcon')
'F.TC.IL.'⎕WC'Icon'('' 'EDITIcon')

'F.TC'⎕WS'ImageListObj' 'F.TC.IL'

'F.TC.T1'⎕WC'TabButton' 'First Tab'('ImageIndex' 1)
'F.TC.T2'⎕WC'TabButton' 'Second Tab'('ImageIndex' 2)
'F.TC.T3'⎕WC'TabButton' 'Third Tab'('ImageIndex' 3)
'F.TC.T4'⎕WC'TabButton' 'Fourth Tab'('ImageIndex' 1)


TabControl: Example 13

The TabJustify Property.


TabControl Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


TabControl Properties

Type | Posn | Size
Style | Event | ImageListObj
FontObj | Data | Attach
TabObj | KeepOnClose | MultiLine
TabSize | Justify | TabJustify
Align | MultiSelect | TabFocus
HotTrack | ScrollOpposite | FlatSeparators
MethodList | ChildList | EventList
PropList |  |


TCP/IP

TCP/IP is an acronym for Transmission Control Protocol/Internet Protocol. These two protocols provide for network connection between computer systems using a wide variety of network media.


TCPSocket Events

Close | Create | TCPAccept
TCPClose | TCPConnect | TCPError
TCPGotAddr | TCPGotPort | TCPReady
TCPRecv |  |


TCPSocket Methods

Detach | TCPGetHostID | TCPSend
TCPSendPicture | Wait |


TCPSocket Properties

Type | LocalAddr | LocalPort
RemoteAddr | RemotePort | Style
Event | LocalAddrName | LocalPortName
RemoteAddrName | RemotePortName | Data
SocketType | SocketNumber | CurrentState
TargetState | Encoding | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Temperature Converter Example Class

Temperature Converter Example

:Class Temp: 'Form'
    ∇ Make pv;TITLE
      :Access Public
      TITLE←'Temperature Converter'
      :Implements Constructor :Base (⊂'Caption' TITLE),pv,⊂('Size' (30 40))
      MB←⎕NEW⊂'MenuBar'
      MB.(M←⎕NEW'Menu'(,⊂'Caption' '&Scale'))
      MB.M.(C←⎕NEW'MenuItem'(('Caption' '&Centigrade')('Checked' 1)))
      MB.M.(F←⎕NEW'MenuItem'(,⊂('Caption' '&Fahrenheit')))
      LF←⎕NEW'Label'(('Caption' 'Fahrenheit')('Posn'(10 10)))
      F←⎕NEW'Edit'(('Posn'(10 40))('Size'(⍬ 20))('FieldType' 'Numeric'))
      LC←⎕NEW'Label'(('Caption' 'Centigrade')('Posn'(40 10)))
      C←⎕NEW'Edit'(('Posn'(40 40))('Size'(⍬ 20))('FieldType' 'Numeric'))
      F2C←⎕NEW'Button'(('Caption' 'F->C')('Posn'(10 70))('Default' 1))
      C2F←⎕NEW'Button'(('Caption' 'C->F')('Posn'(40 70)))
      Q←⎕NEW'Button'(('Caption' '&Quit')('Posn'(70 30))('Size'(⍬ 40))('Cancel' 1))
      S←⎕NEW'Scroll'(⊂('Range' 101))
      MB.M.C.onSelect←'SET_C'
      MB.M.F.onSelect←'SET_F'
      F2C.onSelect←'f2c'
      F.onGotFocus←'SET_DEF'
      C2F.onSelect←'c2f'
      C.onGotFocus←'SET_DEF'
      onClose←'QUIT'
      Q.onSelect←'QUIT'
      S.onScroll←'c2f_scroll'
    ∇

    ∇ f2c
      C.Value←(F.Value-32)×5÷9
    ∇
    ∇ c2f
      F.Value←32+C.Value×9÷5
    ∇
    ∇ c2f_scroll MSG
      ⍝ Callback for Centigrade input via scrollbar
      C.Value←101-4⊃MSG
      c2f
    ∇
    ∇ f2c_scroll Msg
      ⍝ Callback for Fahrenheit input via scrollbar
      F.Value←213-4⊃Msg
      f2c
    ∇
    ∇ Quit
      Close
    ∇
    ∇ SET_DEF MSG
      (⊃MSG).Default←1
    ∇
    ∇ SET_C
      ⍝ Sets the scrollbar to work in Centigrade
      S.Range←101
      S.onScroll←'c2f_scroll'
      MB.M.C.Checked←1
      MB.M.F.Checked←0
    ∇
    ∇ SET_F
      ⍝ Sets the scrollbar to work in Fahrenheit
      S.Range←213
      S.onScroll←'f2c_scroll'
      MB.M.F.Checked←1
      MB.M.C.Checked←0
    ∇
:EndClass ⍝ Temp


Text Events

Close | Create | DragDrop
FontCancel | FontOK | Help
MouseDblClick | MouseDown | MouseMove
MouseUp | Select |


Text Methods

ChooseFont Detach


Text Properties

Type | Text | Points
FCol | BCol | VAlign
HAlign | Coord | Active
Visible | Event | Dragable
FontObj | OnTop | CursorObj
AutoConf | Data | Translate
Accelerator | KeepOnClose | DrawMode
MethodList | ChildList | EventList
PropList |  |


Thorn Symbol

Format;Thorn;Down Tack Jot

⍕

Monadic Format means

Format

      ⍕ 0.0000003  3.87687857858
3E¯7 3.876878579

NB Depends on ⎕PP

Dyadic Format means

Format By Specification

           8 3 ⍕ 0.00003 3.87687
   0.000   3.877

Language Elements


Tilde

~

Monadic Tilde means

Not

      ~ 3 3⍴0 1
1 0 1
0 1 0
1 0 1

Dyadic Tilde means

Without;Excluding

      'ab' 'ce' 'fg' ~ 'ce' 'ab'
 fg

Language Elements


Timer Events

Close Create Timer


Timer Methods

Detach Wait


Timer Properties

Type | Interval | Active
Event | Data | KeepOnClose
MethodList | ChildList | EventList
PropList |  |


Times Sign

×

Monadic Times Sign means

Sign Of

      × 3 2 ¯2 0 8
1 1 ¯1 0 1

Dyadic Times Sign means

Times;Multiplied By

      2 ¯8 2 5 4 × 3 2 ¯2 0 8
6 ¯16 ¯4 0 32

Language Elements


TipField Events

Close | Create | FontCancel
FontOK |  |


TipField Methods

ChooseFont Detach


TipField Properties

Type | Event | FontObj
FCol | BCol | Data
Translate | KeepOnClose | MethodList
ChildList | EventList | PropList


ToolBar Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | Help
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Select |


ToolBar Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


ToolBar Properties

Type | Posn | Size
Coord | Align | Border
Active | Visible | Event
VScroll | HScroll | Sizeable
FontObj | FCol | BCol
Picture | OnTop | IconObj
CursorObj | AutoConf | YRange
XRange | Data | Attach
TextSize | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


ToolButton Events

Close | Create | Help
MouseDblClick | MouseDown | MouseMove
MouseUp | Select |


ToolButton: Example 1

'F'⎕WC'Form' 'ToolControl: Dropdown Buttons'('Size' 20 40)
'F.TB'⎕WC'ToolControl'('ShowDropDown' 1)

:With 'F.FMENU'⎕WC'Menu' ⍝ Popup File menu
    'NEW'⎕WC'MenuItem' '&New'
    'OPEN'⎕WC'MenuItem' '&Open'
    'CLOSE'⎕WC'MenuItem' '&Close'
:EndWith

:With 'F.EMENU'⎕WC'Menu' ⍝ Popup File menu
    'CUT'⎕WC'MenuItem' 'Cu&t'
    'COPY'⎕WC'MenuItem' '&Copy'
    'PASTE'⎕WC'MenuItem' '&Paste'
:EndWith

'F.TB.B1'⎕WC'ToolButton' 'File'('Style' 'DropDown')('Popup' 'F.FMENU')
'F.TB.B2'⎕WC'ToolButton' 'Edit'('Style' 'DropDown')('Popup' 'F.EMENU')


ToolButton Methods

Detach


ToolButton Properties

Type | Caption | Posn
Size | Style | State
Active | Visible | Event
ImageIndex | Data | Hint
HintObj | Tip | Accelerator
Popup | KeepOnClose | MethodList
ChildList | EventList | PropList


ToolControl Events

Close | Configure | ContextMenu
Create | DockAccept | DockCancel
DockEnd | DockMove | DockRequest
DockStart | DragDrop | DropFiles
DropObjects | Expose | Help
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel |  |


ToolControl: Example 1

'F'⎕WC'Form' 'ToolControl: FlatButtons Style (default)'('Size' 10 40)
'F.TB'⎕WC'ToolControl'

'F.TB.IL'⎕WC'ImageList'('Masked' 0)
'F.TB.IL.'⎕WC'Bitmap'('Comctl32' 120)
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
'F.TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
'F.TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)

'F.TB'⎕WC'ToolControl'('Style' 'Buttons')

'F.TB'⎕WC'ToolControl'('Style' 'FlatList')

'F.TB'⎕WC'ToolControl'('Style' 'List')


ToolControl: Example 2

'F'⎕WC'Form' 'ToolControl: MultiLine 0'('Size' 20 36)
'F.TB'⎕WC'ToolControl'('Style' 'List')

'F.TB.IL'⎕WC'ImageList'('Masked' 0)('Size' 24 24)
'F.TB.IL.'⎕WC'Bitmap'('ComCtl32' 121)⍝ STD_LARGE
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'Cut'('ImageIndex' 1)
'F.TB.B2'⎕WC'ToolButton' 'Copy'('ImageIndex' 2)
'F.TB.B3'⎕WC'ToolButton' 'Paste'('ImageIndex' 3)
'F.TB.B4'⎕WC'ToolButton' 'Undo'('ImageIndex' 4)
'F.TB.B5'⎕WC'ToolButton' 'Redo'('ImageIndex' 5)
'F.TB.B6'⎕WC'ToolButton' 'Delete'('ImageIndex' 6)

'F.TB'⎕WC'ToolControl'('MultiLine' 1)('Style' 'List')


ToolControl: Example 3

'F'⎕WC'Form' 'ToolControl: Transparent 1)'('Size' 10 40)
'F.BM'⎕WC'Bitmap' 'C:\WINDOWS\WINLOGO'
'F'⎕WS'Picture' 'F.BM' 1

'F.TB'⎕WC'ToolControl'('Transparent' 1)('Style' 'FlatList')
'F.TB.IL'⎕WC'ImageList'('Masked' 0)('Size' 24 24)
'F.TB.IL.'⎕WC'Bitmap'('ComCtl32' 121)⍝ STD_LARGE
'F.TB'⎕WS'ImageListObj' 'F.TB.IL'

'F.TB.B1'⎕WC'ToolButton' 'New'('ImageIndex' 7)
'F.TB.B2'⎕WC'ToolButton' 'Open'('ImageIndex' 8)
'F.TB.B3'⎕WC'ToolButton' 'Save'('ImageIndex' 9)


ToolControl: Example 4

'F'⎕WC'Form' 'ToolControl with MenuBar'('Size' 20 40)
'F.TB'⎕WC'ToolControl'

:With 'F.TB.MB'⎕WC'MenuBar'
    :With 'File'⎕WC'Menu' 'File'
        'New'⎕WC'MenuItem' 'New'
        'Open'⎕WC'MenuItem' 'Open'
        'Close'⎕WC'MenuItem' 'Close'
    :EndWith

    :With 'Edit'⎕WC'Menu' 'Edit'
        'Cut'⎕WC'MenuItem' 'Cut'
        'Copy'⎕WC'MenuItem' 'Copy'
        'Paste'⎕WC'MenuItem' 'Paste'
    :EndWith

:EndWith


ToolControl Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


ToolControl Properties

Type | Posn | Size
Style | Align | Visible
Event | ImageListObj | FontObj
Data | Attach | Handle
KeepOnClose | MultiLine | Transparent
Divider | ShowCaptions | ShowDropDown
Dockable | UndocksToRoot | Redraw
MethodList | ChildList | EventList
PropList |  |


TrackBar Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | GotFocus
Help | KeyPress | LostFocus
MouseDown | MouseMove | MouseUp
Scroll | Select | ThumbDrag


TrackBar Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


TrackBar Properties

Type | Posn | Size
Style | Coord | Border
Active | Visible | Event
Thumb | Step | VScroll
HScroll | Limits | SelRange
Sizeable | Dragable | FontObj
BCol | CursorObj | AutoConf
Data | Attach | EdgeStyle
Handle | Hint | HintObj
Tip | TipObj | Translate
Accelerator | TickAlign | TickSpacing
HasTicks | ShowThumb | TrackRect
ThumbRect | AcceptFiles | KeepOnClose
Redraw | TabIndex | MethodList
ChildList | EventList | PropList


Transpose

Transpose;Circle Slope

⍉

Monadic Transpose means

Transpose

      ⍉ 3 3⍴1 2 3 4 5 6 7 8 9
1 4 7
2 5 8
3 6 9

Dyadic Transpose means

General Transpose

      2 1 3 ⍉ 2 3 4⍴⍳24
 1  2  3  4
13 14 15 16

 5  6  7  8
17 18 19 20

 9 10 11 12
21 22 23 24

Language Elements


:Trap Statement Definition

:Trap Statement

Trap:
       |
       :Trap <ecode>
       |
       code
       |
       |<------------------------------------.
       |                                     |
       .-------.-------.                     |
       |       |       |                     |
       |       :Else   :Case[List] <ecode>   |
       |       |       |                     |
       |       |       |                     |
       |       |       |                     |
       |       code    code                  |
       |       |       |                     |
       |<------'       `---------------------'
       |
       :End[Trap]

Where <ecode> is a scalar or vector of ⎕TRAP event codes.

Note that within the :Trap control structure, :Case is used for a single event code and :CaseList for a vector of event codes.


TreeView Events

BeginEditLabel | Close | Configure
ContextMenu | Create | DragDrop
DropFiles | DropObjects | EndEditLabel
Expanding | Expose | FontCancel
FontOK | GetTipText | GotFocus
Help | ItemDblClick | ItemDown
ItemUp | KeyPress | LostFocus
MouseDblClick | MouseDown | MouseEnter
MouseLeave | MouseMove | MouseUp
MouseWheel | Retracting | Select


TreeView Methods

AddChildren | AddItems | Animate
ChooseFont | DeleteChildren | DeleteItems
Detach | GetFocus | GetItemHandle
GetItemState | GetParentItem | GetTextSize
SetItemImage | SetItemState | ShowItem
ShowSIP |  |


TreeView Properties

Type | Items | Posn
Size | Coord | Border
Active | Visible | Event
Depth | HasLines | HasButtons
EditLabels | ImageListObj | ImageIndex
SelImageIndex | SelItems | Sizeable
Dragable | FontObj | FCol
BCol | CursorObj | AutoConf
Index | Data | Attach
EdgeStyle | Handle | Hint
HintObj | Tip | TipObj
Translate | Accelerator | AcceptFiles
KeepOnClose | CheckBoxes | FullRowSelect
SingleClickExpand | Redraw | TabIndex
AlwaysShowSelection | MethodList | ChildList
EventList | PropList |


Triggers

Introduction

Example

Trigger Fields in Classes


Trim leading blanks {(∨\' '≠⍵)/⍵}
{(+/∧\' '=⍵)↓⍵}

Both these idioms for Trim leading blanks are recognised and optimised for performance.


Twips

There are 1,440 Twips to one inch.


(Untitled)

⍝ Structure rearrangement:
      rotate1←{       ⍝ Simple binary tree rotation.
           (a b c)d e←⍵
           a b(c d e)
      }

      rotate3←{       ⍝ Compound binary tree rotation.
           (a b(c d e))f g←⍵
           (a b c)d(e f g)
      }


Up Arrow

↑

Monadic Up Arrow means

If ⎕ML<2 Mix

      ↑ (6 4) 5 3
6 4
5 0
3 0

If ⎕ML≥2 Disclose;First

      ↑ (6 4) 5 3
6 4

Dyadic Up Arrow means

Take

      3 3↑7
7 0 0
0 0 0
0 0 0

Language Elements


UpDown Events

Close | Configure | ContextMenu
Create | DragDrop | DropFiles
DropObjects | Expose | Help
MouseDown | MouseEnter | MouseLeave
MouseMove | MouseUp | Select
Spin |  |


UpDown Methods

Animate | Detach | GetFocus
GetTextSize | ShowSIP |


UpDown Properties

Type | Posn | Size
Coord | Border | Active
Visible | Event | Thumb
Step | VScroll | HScroll
Wrap | Limits | Sizeable
Dragable | FCol | BCol
CursorObj | AutoConf | Data
Attach | EdgeStyle | Handle
Hint | HintObj | Tip
TipObj | Translate | Accelerator
AcceptFiles | KeepOnClose | Redraw
TabIndex | MethodList | ChildList
EventList | PropList |


Upper and Lower Right Item

Upper Right Item ⊃⌽A (⎕ml<2)

↑⌽A (⎕ml≥2)

 Lower Right Item ⊃⌽,A (⎕ml<2)

↑⌽,A (⎕ml≥2)

These expressions now take constant time.

Prior to idiom recognition, the time taken depended linearly on the number of items in the argument.


Upstile

⌈

Monadic Upstile means

Ceiling

      ⌈ 3.4 2 8.1 ¯3.44 0
4 2 9 ¯3 0

Dyadic Upstile means

Maximum

      3 1.1 ¯2 ⌈ 3.4 8.1 ¯3.44
3.4 8.1 ¯2

Language Elements


User Datagram Protocol (UDP)

User Datagram Protocol (UDP) is a connection-less transport mechanism that is somewhat similar to a postal service. It permits a sending application to transmit a message or messages to a recipient. It neither guarantees delivery nor acknowledgment, nor does it preserve the sequence of messages. Messages are also limited to fit into a single packet which is typically no more than 1500 bytes in size. However, a UDP message will be delivered in its entirety.

You may wonder why anybody would use a service that does not guarantee delivery. The answer is that although UDP is technically an unreliable service, it is perfectly possible to implement reliable applications on top of it by building in acknowledgments, time-outs and re-transmissions.


var

Loop variable used by :For control


Variables

Arrays | APL data structures
Numbers | input and output formats
Characters | use of quotes
Enclosed Elements | formation of enclosed scalar
Legal Names | valid names of objects
Specification of Variables | simple assignment
Vector Notation | adjacent expressions
Structuring of Arrays | array transformations
Display of Arrays | default output format


Wait Method

WaitMethod 147

Applies to: BrowseBox, Clipboard, FileBox, Form, Locator, Menu, MsgBox, PropertySheet, Root, SysTrayItem, TCPSocket, Timer

The Wait method is the same as executing ⎕DQ on the object.

The Wait method is niladic.

      'F'⎕WC'Form'
...
      Z←F.Wait


:While Statement Definition

:While Statement

While:
       |
       :While bexp
       |
       .-------.
       |       |
       |       andor
       |       |
       |<------'
       |
              |       |
       |<------'
       |
       code
       |
       .---------------.
       |               |
       :End[While]     :Until bexp
       |               |
       |               .-------.
       |               |       |
       |               |       andor
       |               |       |
       |               |<------'
       |               |
       |<--------------'
       |


Windows XP Look and Feel

Windows XP Look and Feel is an optional feature of Windows XP and other advanced versions of Windows.

Under XP, it may be enabled from the Appearance tab of the Display Properties dialog box, by choosing Windows XP style.

Dyalog APL Version 10.1 provides full support for Windows XP Look and Feel. This means that both the APL Session and the Dyalog APL GUI will optionally display XP style buttons, combo boxes, and other GUI components if XP Look and Feel is in effect.

Furthermore, GUI applications developed using Dyalog APL Version 10.1 will also exhibit standard XP behaviour if required.

To obtain Windows XP Look and Feel a program (myprog.exe) must be built with a specific set of resources, or there must be a file that specifies these resources named myprog.exe.manifest in the same directory as the myprog.exe executable. The contents of this file are in XML format.


:With Statement Definition

:With Statement

:With

       |
       :With namespace
       |
       code
       |
       :End[With]
       |


Zero Depth

Zero Depth 0=≡

This expression now takes a small constant time.

Without idiom recognition, time taken would depend on the size and depth of the argument, which in the case of a deeply nested array, could be significant.


Zilde Symbol

Zilde;Zero Tilde

⍬

Niladic Zilde is

Zilde;Zero Length Numeric

      ⍬≡⍳0
1

      ⍬≢''
1

      ⍬≡0⍴0
1

Language Elements