You can interface to .Net by supplying 'net' or .net as the environment string (left argument) for ŒNEW, ŒGETCLASS, or ŒCALL. These system functions will allow you to create an instance of a .Net class, or to call a .Net static (shared) method.
.Net classes are defined in Assemblies (each assembly usually corresponds to a single .Net library DLL, for example mscorlib.dll which contains the basic .Net utility classes), and are organized into Namespaces (such as System, System.Text, System.IO and so on). For example, Microsoft provide a class called Font for representing fonts. This is defined in the System.Drawing namespace, so its fully-qualified name is System.Drawing.Font. The code for this class is held in the System.Drawing assembly, in the shared library system.drawing.dll.
When you use ŒNEW (or ŒGETCLASS or ŒCALL) to refer to a .Net class, you can specify the class name in one of the following ways:
As an undecorated class name, without the namespace qualifier, for example: 'Font'.
In this case, the assembly must be one of those loaded by default or
already loaded by a previous call, and the namespace must be included in the namespace search list (see below).
As a fully (or partially) qualified namespace and class name, for example 'System.Drawing.Font'.
In this case, the assembly must be one of those loaded by default, or
already loaded by a previous call, but the namespace does not have to be included in the namespace search list.
As an undecorated or fully-qualified class name, and a simple file name specifying the DLL in which the assembly can be found, for example: 'System.Data.SqlClient,system.data.dll'.
A comma is used as the delimiter between the class and file name.
In this case, the DLL must exist in the standard location known as the Global Assembly Cache (GAC).
As an undecorated or fully-qualified class name and a full path name specifying the DLL, for example: 'MyBase.MyFirstClass,c:\devt\myclasses.dll'
Again a comma is used as a delimiter between the class and file name.
When you use ŒNEW (or ŒGETCLASS or ŒCALL) to refer to a .Net class, the system searches through the namespaces and assemblies which are in its search path to resolve the class name. If the class is not found, you will get an error:
SW„'.net' ŒNEW 'StringWriter' Class StringWriter not found in current search list DOMAIN ERROR SW„'.net' ŒNEW 'StringWriter' ^
The above example has failed because StringWriter is a class defined in the System.IO namespace, which is not included in the default search list. You can set the current search path for .Net namespaces and DLLs by using the system function ŒSETUP and the 'using' keyword. For example, we can tell the .Net subsystem to include System.IO in the search list:
'.net' ŒSETUP 'using' 'System' 'System.IO' SW„'.net' ŒNEW 'StringWriter' SW [.net:StringWriter]
The namespaces (and optionally DLLs in which they are located) should be supplied as character vectors after the keyword:
'.net' ŒSETUP 'using' 'System' 'System.Text' 'QMath.Geom,c:\dev\qmath.dll'
Each element comprises either just a namespace (such 'System.Text'), or a namespace followed by the name of the DLL in which it is located. This can be a full path name, or just the name of the DLL (in which case the DLL should be in the Global Assembly Cache).
For convenience, the path is set by default to include the most important .Net libraries, as follows:
System System,system.dll System.Text System.Collections System.Windows.Forms,system.windows.forms.dll System.Drawing,system.drawing.dll
You can read the current search list by supplying the 'using' keyword to ŒSETUP with no arguments.
When your read a .Net property, or call a method which returns a result, APLX by default applies the following data conversion rules:
Any .Net numeric types (Int32, Int64, single- or double-precision floats, decimal, etc) are converted to APL integers or floats. 64-bit integers are converted to APL floats on 32-bit platforms, to APL integers on 64-bit platforms.
.Net Booleans are converted to APL binary values 0 or 1
.Net Strings and Chars are converted to APL character arrays, translated from Unicode to APLX internal representation. (Any characters which do not appear in the APLX character set are converted to question marks.)
.Net Enumeration types are converted to APL integers (see below)
Simple .Net arrays are converted to APL arrays, with individual elements converted as above.
Anything else is left as an Object in the .Net environment, and a reference to the object is returned to APL.
There are some special cases to consider. The data might not be convertible at all, or it might lose precision in the conversion. For example, a .Net Decimal might have a higher precision than an APL double-precision floating point can represent. To handle cases like this, APLX provides the ŒREF system method. This forces the data to remain as a .Net object. You can then call ToString, or other .Net methods appropriate to the Decimal data type, to manipulate the data without losing precision.
An example which cannot be represented at all is where a .Net Double contains a NaN (Not A Number). APL does not handle NaNs, so it cannot be converted to an APL floating-point value. Instead, NaNs are left as Objects. If you try to use the data in an APL expression, you will get a DOMAIN ERROR, but you can see that it is a NaN and use ToString and other operations on it.
Enumeration types are special classes in .Net, which contain sets of alternative values which a particular type of variable can hold (somewhat similar to enum types in the C language). When a .Net nethod or property returns an Enumeration type, APLX converts it to the equivalent integer. Equally, calls which expect an Enumeration type can be passed the equivalent integer from APL (the type is converted automatically). This means that Enumerations which are sets of bits can be combined in APL using the + primitive. However, for readability of code, and to avoid having to check the specific value of an Enumeration, you can use ŒGETCLASS to fetch the Enumeration type, and use that directly.
For example, most .Net dialogs (such as OpenFileDialog, which puts up a dialog inviting the user to select an existing file) return a Enumeration type called DialogResult, indicating which button (OK, Cancel, etc) was clicked to end the dialog. We can access this class to see what the various enumeration values are:
DR„'.net' ŒGETCLASS 'DialogResult' DR.OK 1 DR.OK.ToString OK DR.Cancel 2 DR.Cancel.ToString Cancel ŒBOX DR.ŒNL 2 Abort Cancel Ignore No None OK Retry value__ Yes
This means that, if you call the ShowDialog method of the OpenFileDialog, you can test which button ended the dialog either by checking the numeric value returned, or by seeing if it is equal to the named enumeration value:
’R„FileDialog;DR;DLG [1] © Put up file dialog, return file selected or empty vector if none [2] DR„'.net' ŒGETCLASS 'DialogResult' [3] DLG„'.net' ŒNEW 'OpenFileDialog' [4] :If DLG.ShowDialog=DR.OK [5] R„DLG.FileName [6] :Else [7] R„'' [8] :End ’
To handle the (relatively uncomon) cases where a .Net method takes an argument 'by reference', and modifies one or more of the arguments in-situ, you can use ŒSETUP and the 'byref' keyword. See the documentation for ŒSETUP.
There are no special restrictions on using the .Net interface from multiple APL tasks. Each task will have an independent copy of the interface, which will be deleted on )CLEAR, )LOAD, or )OFF.
Your own classes (written in APL) cannot inherit directly from a .Net class. However, you can achieve much the same result by using mixins.
In this example, the constructor of a user-defined class called APLDate 'mixes-in' the .Net class DateTime
Œcr 'APLDate' APLDate { ’APLDate b © Constructor for APLDate class © Argument is vector of Year Month Day Hour Sec © (or just Year Month day) © If no argument supplied, use current Œts value :If 0=½b '.net' Œmixin(›'DateTime'),6†Œts :Else '.net' Œmixin(›'DateTime'),b :End ’ ’r„ts © Return .Net DateTime in ŒTS format r„Year,Month,Day,Hour,Minute,Second,Millisecond ’ ’r„ts_gmt;gmt © Return the date/time adjusted to GMT, in Œts form gmt„ToUniversalTime r„gmt.Year,gmt.Month,gmt.Day,gmt.Hour,gmt.Minute,gmt.Second,gmt.Millisecond ’ } dt„Œnew APLDate
As well as the methods written in APL, all the public properties and methods of the .Net DateTime class become available in the APL class APLDate:
dt„Œnew APLDate dt.Œnl 2 Date Day DayOfWeek DayOfYear Hour Kind MaxValue Millisecond MinValue Minute Month Now Second Ticks TimeOfDay Today UtcNow Year dt.ToLongDateString © Method 'mixed-in' from .Net DateTime 19 March 2009 dt.ts © Method written in APL 2009 3 19 16 0 5 0 dt.ts_gmt 2009 3 19 21 0 5 0
If the .Net environment raises an error (or exception), APLX will normally try to print the error message or exception text on the session window, and then raise an APL error (typically DOMAIN ERROR). You can get further information by using ŒLE Last Exception to read back the .Net exception object: For example:
'.net' ŒNEW 'DateTime' 'Bastille Day' Constructor on type 'System.DateTime' not found. DOMAIN ERROR '.net' ŒNEW 'DateTime' 'Bastille Day' ^ exception„'.net' ŒLE 1 exception [.net:MissingMethodException] exception.ŒNL 2 Data HelpLink InnerException Message Source StackTrace TargetSite exception.Message Constructor on type 'System.DateTime' not found. exception.Source mscorlib exception.ToString System.MissingMethodException: Constructor on type 'System.DateTime' not found. at System.RuntimeType.CreateInstanceImpl(BindingFlags bindingAttr, Binder bin der, Object[] args, CultureInfo culture, Object[] activationAttributes) at System.Activator.CreateInstance(Type type, BindingFlags bindingAttr, Binde r binder, Object[] args, CultureInfo culture, Object[] activationAttribute s) at NetBridge.NetBridge.CreateNamedInstance(String class_name, Object[] arg_li st) at APLXObj_New(Void* arch_if, Void** objref, wsobj* args, _ExportedProcs* pro cs, SByte* errmsg)
User-interface programming in APLX can be done by using the built-in System classes (formerly accessed through ŒWI). This has the advantages that it is relatively easy to do, and that APLX applications using the System classes will work on other platforms (e.g. the Macintosh). But for more flexibility, you can alternatively use Microsoft's .Net classes directly.
User-interface programming using the .Net framework (System.Windows.Forms) is a special case of using .Net objects from within APLX. See the Microsoft documentation for full information on this topic.
From the APL programmer's point of view, there are a few specific points to note:
The typical scenario is that you create a .Net Form object, set various properties of the Form (such as the Text property, which is the window title), and then create further items using control classes such as Button and TextBox. You need to use the Add method of the form's Controls property to link up the controls and the form. (Note: If you have a copy of Microsoft Visual Studio or Visual Studio Express, you can use the form designer to design a form interactively, and then copy the dimensions and other properties created in C# or Visual Basic into your APLX code, adjusting the syntax as necessary).
To handle .Net events, you need to assign the name of an APL callback function (or some other expression) to one of the control's event properties. For example, a Button has a Click event, which fires when the button is clicked. As with System classes, the event is held in a queue and de-queued using the system function ŒWE, which causes your event handler to be run.
When one of your callback functions is running, there are three system functions which you can use to find out more about the event. These are:
ŒEVA Returns a reference to the event argument object (class EventArgs)
ŒEVN Returns the name of the event (such as 'Click')
ŒEVT Returns a reference to the target object, for example the Button object
The following complete example (available in the workspace 10 HELPDOTNET) shows a simple application which displays a window with an edit box, a text box to output results, and a button. When the button is clicked, it simply evaluates the APL expression typed into the edit box and displays the result in the text box. Note in particular the callbacks set up on lines 32 and 33. The first of these (the Closed event) is triggered when the window is closed; this terminates the function by clearing the )SI, and this in turn causes all the object references to be deleted because they are held in localized variables. The second call back (the Click event of the button) causes the EVALUATE function to be run.
’DOT_Forms;X;F;EditResult;EditIn;ButtonDo [1] © Simple example of using Windows Forms from APLX v4 [2] © Create main form [3] F„'.net' ŒNEW 'Form' [4] F.Text„'Expression Evaluator' [5] © [6] © Create edit box for input line [7] EditIn„'.net' ŒNEW 'TextBox' [8] EditIn.Left„12 ª EditIn.Top„21 [9] EditIn.Width„265 ª EditIn.Height„20 [10] EditIn.Font„'.net' ŒNEW 'Font' 'APLX Upright' 10 [11] F.Controls.Add EditIn [12] © [13] © Create multi-line box for result [14] EditResult„'.net' ŒNEW 'TextBox' [15] EditResult.Multiline„1 [16] EditResult.Left„12 ª EditResult.Top„50 [17] EditResult.Width„265 ª EditResult.Height„180 [18] EditResult.Font„'.net' ŒNEW 'Font' 'APLX Upright' 10 [19] F.Controls.Add EditResult [20] © [21] © Create button [22] ButtonDo„'.net' ŒNEW 'Button' [23] ButtonDo.Left„94 ª ButtonDo.Top„240 [24] ButtonDo.Width„100 ª ButtonDo.Height„22 [25] ButtonDo.Text„'Evaluate' [26] F.Controls.Add ButtonDo [27] © [28] © Make the button accept Enter as equivalent to clicking [29] F.AcceptButton„ButtonDo [30] © [31] © Add callbacks [32] F.Closed„'"Cleaning up.." ª …' [33] ButtonDo.Click„'EditResult EVALUATE EditIn.Text' [34] © [35] © Show the window [36] F.Show [37] © [38] © Process events [39] X„ŒWE ¯1 ’ ’A EVALUATE B;RESULT;ŒIO [1] © Evaluate expression B and put it into the Text property of object A [2] © If an error occurs, change the colour of the text [3] ŒIO„1 [4] RESULT„ŒEC B [5] :Select †RESULT [6] :Case 0 © Error [7] A.ForeColor„A.ForeColor.Red [8] A.Text„MAKEVEC 3œRESULT [9] :Case 1 © Expression with a result which would display [10] A.ForeColor„A.ForeColor.DarkOliveGreen [11] A.Text„MAKEVEC•3œRESULT [12] :Else [13] © 2 Expression with a result which would not display [14] © 3 Expression with no explicit result [15] © 4 Branch to a line [16] © 5 Naked branch [17] A.Text„'' [18] :End ’ ’R„MAKEVEC B [1] © Given a character array, ensure it's a text vector [2] © If matrix or higher rank, make into CRLF-delimited vector [3] :If 2>½½B [4] R„B [5] :Else [6] R„ŒR ŒBOX B [7] :EndIf [8] R„ŒSS R ŒR(ŒR,ŒL) ’
This function shows a simple example of using the System.IO namespace to create a text file and write some text to it. On line [1], it sets up the search path for .Net classes. Lines [2] and [3] fetch the FileMode and FileAccess enumeration types, which are then used in line [5].
’FileWrite;sw;MyFile;FileMode;FileAccess;DateTime [1] '.net' ŒSETUP 'using' 'System' 'System.IO' [2] FileMode„'.net' ŒGETCLASS 'FileMode' [3] FileAccess„'.net' ŒGETCLASS 'FileAccess' [4] DateTime„'.net' ŒGETCLASS 'DateTime' [5] MyFile„'.net' ŒNEW 'FileStream' 'c:\temp\testdotnet.txt' (FileMode.OpenOrCreate) (FileAccess.ReadWrite) [6] sw„'.net' ŒNEW 'StreamWriter' MyFile [7] sw.Write 'Written from APLX',ŒR,ŒL [8] sw.Write 'Created by APLX Version 4 at ',DateTime.Now.ToString [9] sw.Close [10] MyFile.Close ’