💾 Archived View for blitter.com › apl-books › APLX50 › APLX-manual › www.microapl.com › apl_help › c… captured on 2023-01-29 at 14:30:27.
⬅️ Previous capture (2022-07-17)
-=-=-=-=-=-=-
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Introduction to System Classes</TITLE>
<META NAME="DESCRIPTION" CONTENT="APL language help page: Introduction to System Classes">
<META NAME="KEYWORDS" CONTENT="⎕WI,window,windowing interface,system classes,apl,aplx,apl help">
<!-- %%COMMON_HEAD%% -->
<META http-equiv="Content-Type" content="text/html; charset=utf-8">
<LINK rel="stylesheet" type="text/css" href="http://www.microapl.com/styles_apl_help.css">
<!-- %%END%%-->
</HEAD>
<body>
<table>
<tr>
<td width="800" valign="top" colspan="2">
<center>Topic: <A HREF="ch.htm"><code>APLX Help</code></A> : <A HREF="ch_030.htm"><code>System Classes</code></A> : <A HREF="ch_030_010.htm"><code>Introduction to System Classes</code></A>
</center>
<center>
[ <A HREF="ch_030_011.htm">Next</A> | <A HREF="ch.htm">Contents</A> | <A HREF="help_index.htm">Index</A> | <A HREF="http://www.microapl.co.uk/apl/index.html">APL Home</A> ]</center>
<br></td>
</tr>
<tr>
<td width="120">
<a href="http://www.microapl.co.uk/apl/index.html"><img height="68" border="0" width="119" src="MicroAPL_logo.gif" alt="www.microapl.co.uk"></a>
</td>
<td align="left" valign="bottom">
<h1>Introduction to System Classes</h1>
</td>
</tr>
<tr>
<td width="800" valign="top" colspan="2">
<hr>
<H2>Overview</H2>
<P>Built in to all versions of APLX (excluding console-only versions) is a rich set of <i>System Classes</i>, which implement windows, dialogs, graphics, movies, and other user-interface components which you can use from your APL applications. They also include more advanced components, such as a chart-drawing class for business and scientific graphs, an image-manipulation class, and some non-visual classes for networking, e-mail and web access. As far as possible, these classes work cross-platform, so that, with a few exceptions, the same APL user-interface code will run under APLX for Windows, MacOS or Linux.</p>
<p>The syntax for using these System Classes is similar to the syntax for <A HREF="ch_020_010_160.htm">user-defined classes</A> (which you write yourself in APL), or <A HREF="ch_070_020.htm">external classes</A> (for example, classes written in C# or Java). There is also an alternative syntax (based on the <code>⎕WI</code> system function) which is retained for compatibility with other APL interpreters and with earlier versions of APLX, and which is sometimes useful in itself.</p>
<p> The workspaces <tt>10 HELPSYSCLASS</tt> and <tt>10 SAMPLESSYSCLASS</tt> contain examples of using System Classes. If you take a look at these examples, you will see that the basic steps which you typically need to carry out are as follows:</P>
<P>1. Create a top-level object (for example, a Dialog, Form, Window, or Document), using <code>⎕NEW</code>.</P>
<P>2. Create controls such as edit boxes, buttons, or rectangles on the top-level object, using the <tt>New</tt> or <tt>Create</tt> method which is implemented for all System Classes.</P>
<P>3. Provide APL functions known as <i>callbacks</i> which get run when certain events occur (such as when a Button is pressed).</P>
<P>4. Call the <code>⎕WE</code> system function which waits for events, and where appropriate executes your callback functions.</P>
<P>Each object you create is an instance of a pre-defined class of objects which are built into APLX (or accessible as an external OCX class). You tailor the appearance and behavior of an object by setting <i>properties</i> for it, and you find out about an object's current state by reading its properties. Properties include things like the size and position of an object, its title, its color and font, the current text displayed in it, and so on. In most cases, when you set a property, the object immediately reacts accordingly (for example, if you change its <tt>size</tt> property, it is immediately re-sized). Some properties (such as the <tt>data</tt> property, an arbitrary APL array associated with the object) are valid for all objects. Many properties (such as <tt>size</tt>) are valid for several classes of object, and a few (such as the <tt>text</tt> property) for certain specific classes only. Most properties can be both set and read by your program, but some are read-only.</P>
<P>You can also call built-in functions associated with objects from APL (these are known as <i>methods</i>). These carry out operations such as hiding or closing the object.</P>
<H2>Creating instances of System Classes using <code>⎕NEW</code></H2>
<P>The first stage in using System Classes is to create a top-level object (i.e. an instance of a class such as <tt>Window</tt>, <tt>GetMail</tt> or <tt>Image</tt>) using <code>⎕NEW</code>. The right argument is the name of the class, and the left argument should be <code>'⎕'</code> to indicate that this is a System Class (rather than a user-defined or external class).</P>
<P>For example, you might create a window with the standard Dialog border and appearance:</P>
<PRE> dlg←'⎕' ⎕NEW 'Dialog'
</PRE>
<p>This has created a new object, and returned a reference to that object which has been placed in the variable <tt>dlg</tt>.</p>
<p>You can then set and read properties, or call methods, of this new object using <i>dot notation</i>, where you refer to the property or method using a compound name in the form <tt>ObjectRef.PropertyName</tt> or <tt>ObjectRef.MethodName</tt>. For example, to set the <tt>caption</tt> property of the window (which sets the title of the window):</p>
<pre> dlg.caption←'My first window'</pre>
<p>Reading the value of a property is similar:</p>
<pre> dlg.caption
My first window
</pre>
<p>To call a method which takes no arguments, you simply refer to the object and method:</p>
<pre> dlg.Show</pre>
<p>To call a method which takes arguments:</p>
<pre> dlg.Clienttoscreen 8 12
158 180</pre>
<p>Not all System Classes can be created as top-level objects. For example, a <tt>Button</tt> can be created only as the child of a <tt>Window</tt> or similar container, as described below. The classes which can be top-level objects are either windows, pre-defined dialogs, or invisible classes. The full list is:</p>
<P>
<tt><A HREF="ch_030_020_005.htm">APL</A>
<A HREF="ch_030_020_050.htm">ChooseColor</A>
<A HREF="ch_030_020_060.htm">ChooseDir</A>
<A HREF="ch_030_020_070.htm">ChooseFont</A>
<A HREF="ch_030_020_090.htm">Dialog</A>
<A HREF="ch_030_020_100.htm">Document</A>
<A HREF="ch_030_020_120.htm">Form</A>
<A HREF="ch_030_020_132.htm">GetMail</A>
<A HREF="ch_030_020_142.htm">HTTPClient</A>
<A HREF="ch_030_020_144.htm">Image</A>
<A HREF="ch_030_020_145.htm">ImageList</A>
<A HREF="ch_030_020_180.htm">Menu</A>
<A HREF="ch_030_020_200.htm">MsgBox</A>
<A HREF="ch_030_020_210.htm">OpenFile</A>
<A HREF="ch_030_020_240.htm">Printer</A>
<A HREF="ch_030_020_300.htm">SaveFile</A>
<A HREF="ch_030_020_324.htm">SendMail</A>
<A HREF="ch_030_020_328.htm">Socket</A>
<A HREF="ch_030_020_350.htm">System</A>
<A HREF="ch_030_020_360.htm">Timer</A>
<A HREF="ch_030_020_120.htm">Window</A>
<A HREF="ch_030_080_030.htm">OLE (COM) Server</A></tt>
</P>
<H2>Creating Child controls</H2>
<p>Once you have a top-level object (such a window or form), you can typically create <i>child controls</i> (such as buttons, list boxes, and so on) on it. Because these controls cannot exist independently of the parent object, you cannot use <code>⎕NEW</code> to create them. Instead, you use the <tt><A HREF="ch_030_040_0250.htm">New</A></tt> or <tt><A HREF="ch_030_040_0095.htm">Create</A></tt> methods. These take a right argument which is the name of the System Class which you want to create. The name of the control is specified using dot notation.</p>
<P>for example, to create an object called <tt>Lst1</tt>, of class <tt>List</tt>, on the window which we have just defined, you would enter:</P>
<PRE> dlg.Lst1.New 'List'
</PRE>
<P>When you create a control in this way, the system chooses defaults for properties such as size and position. You can change these using dot notation in the normal way. For example, to set the <tt>size</tt> property of the list you just created to be 5 standard rows high and 30 columns wide (the object will immediately be re-sized):</P>
<PRE> dlg.Lst1.size←5 30
</PRE>
<P>Put a set of choices (contained in the variable NAMES) into the list box by setting its <tt>list</tt> property:</P>
<PRE> dlg.Lst1.list←NAMES
</PRE>
<P>Read back the selection which the user has made by reading the <tt>value</tt> property of the list box:</P>
<PRE> dlg.Lst1.value
2
</PRE>
<H2>Rules for Object Names </H2>
<P>As can be seen in the above examples, the dot-notation syntax is hierarchical in that the first part (up to the first dot) represents the reference to the top-level object, created using <code>⎕NEW</code>. The next part represents the child object name (created using the <tt>New</tt> or <tt>Create</tt> method of the System Class sub-system), if there is one. Potentially there may be further levels of hierarchy separated by further dots - for example, a menu item may be a child of a sub-menu which is a child of a menu-bar item. The maximum length of each part of an object's name is 32 characters. Apart from the special significance of dots, names follow the normal APL symbol-naming rules. Object names are case-sensitive.</P>
<P>Finally, the last part of the dot-notation sequence is the property or method name. The valid property, method, and class names are pre-assigned and are documented separately. APLX ignores case when searching for these pre-assigned names, but it is recommended that you enter them as shown for future compatibility with other systems.</P>
<H2>Responding to events </H2>
<P>The processing of events which occur in your program (such as a button being pressed) is handled by the system function <code>⎕WE</code> in conjunction with callback properties which you set. These callback properties tell the system 'If this event occurs for this object, then you should execute the following APL expression'. For example, if you want to run a function called <code>HITME</code> when a button is pressed, you would set the <tt>onClick</tt> handler for that button as follows:</P>
<PRE> MyWin.MyButton.onClick←'HITME'
</PRE>
<P>The actual execution of the <code>HITME</code> function takes place during an event loop, invoked by the function <code>⎕WE.</code> This is described in detail separately.</P>
<H2>Drawing pictures, shapes and text</H2>
<p>As well as placing controls and text or graphic objects on your windows, you can also use the <A HREF="ch_030_040_0136.htm"><tt>Draw</tt></A> method to display text, geometric shapes such as polygons and ellipses, and pictures or bitmaps.</p>
<H2>Implementing Drag-and-Drop</H2>
<P>If you want to use drag-and-drop for specific functionality in your application, you can do this very simply. In outline, all you need to do is the following. First define the <tt>sourceformats</tt> property for the control which can be dragged. Then define the <tt>targetformats</tt> property for the control or controls on to which it can be dragged. If the two formats match, the user will now be able to drag the source control on to the target control. Your program will be notified when a drag-drop occurs using the <tt>onDragDrop</tt> callback for the target, and the <tt>onDragEnd</tt> callback for the source control.</P>
<P><i>Note:</i> Under Windows, APLX Edit and RichEdit controls have built-in drag-and-drop capability for text editing, and you do not need to do anything for users of your application to take advantage of this.</p>
<H2>Deleting objects </H2>
<P>In order to free up memory used by an object, you must make sure it is deleted when you are finished with it. As with user-defined APL classes, a top-level object will be deleted when the last reference to it is deleted from the workspace. Thus, if the variable <tt>dlg</tt> in the above example was erased (either explicitly, or because the name was localized in a function header, and the function completed), then the window would be closed (if it were still open), and it would be deleted. All child objects on the window are automatically deleted when the parent is deleted.</P>
<P>You can also delete an object explicitly using the <tt>Delete</tt> method (note that this is not the same as closing the object). This closes the object (and any children it has), and frees up any memory which it was using. However, this does not erase any references to the object in your workspace, if it is a top-level object:</P>
<pre> dlg.Delete
dlg
[⎕:UNKNOWN OBJECT]
</pre>
<P>As a convenience, windows which have no <tt>onClose</tt> callback defined are automatically deleted if the user closes the window.</P>
<H2>Alternative syntax using <code>⎕WI</code></H2>
<P>As an alternative to using <code>⎕NEW</code> and dot-notation, you can interface to System Classes by means of the system function <code>⎕WI</code>. This syntax usually less readable than dot-notation, but is retained for compatibility with earlier versions of APLX and with some other APL interpreters. In a few cases, it is preferable to dot-notation.</P>
<p>When you use <code>⎕WI</code> to create objects, there is no object reference held in the workspace. Instead, you provide a name for the object, which is held in the System Class sub-system, and you use a character vector to identify the object.</p>
<P>The left argument of <code>⎕WI</code> is the name of the object, and the right argument names the property or method you wish to access, and if appropriate also provides the value you wish to assign to the property or pass to the method. When you create an object, you can optionally set properties at creation time, otherwise the system chooses defaults. You can use the <tt><A HREF="ch_030_040_0250.htm">New</A></tt> or <tt><A HREF="ch_030_040_0095.htm">Create</A></tt> methods to create a new object. The following examples show how this works:</P>
<P>Create a top-level object called Example, in this case a window with the standard Dialog border and appearance:</P>
<PRE> 'Example' ⎕WI 'New' 'Dialog'
</PRE>
<P>Create an object called Lst1, of class List Box, on the window Example (the system chooses defaults for things like size and position):</P>
<PRE> 'Example.Lst1' ⎕WI 'New' 'List'
</PRE>
<P>Set the <tt>size</tt> property of the list you just created to be 5 standard rows high and 30 columns wide (the object will immediately be re-sized):</P>
<PRE> 'Example.Lst1' ⎕WI 'size' 5 30
</PRE>
<P>Create an object called Lst1, as above, but this time set the <tt>size</tt> property at the time you create it:</P>
<PRE> 'Example.Lst1' ⎕WI 'New' 'List' ('size' 5 30)
</PRE>
<P>Put a set of choices (contained in the variable NAMES) into the list box by setting its <tt>list</tt> property:</P>
<PRE> 'Example.Lst1' ⎕WI 'list' NAMES
</PRE>
<P>Read back the selection which the user has made by reading the <tt>value</tt> property of the list box:</P>
<PRE> 'Example.Lst1' ⎕WI 'value'
2
</PRE>
<P>The exact syntax of <code>⎕WI</code> for the three possible cases is as follows:</P>
<P><i>Setting a property:</i></P>
<PRE> ObjectName ⎕WI PropertyName Value
</PRE>
<P>ObjectName and PropertyName are character vectors, and Value can be any APL array valid for the particular property in question. The right argument to <code>⎕WI</code> is thus a two-element nested vector. However, as a convenience <code>⎕WI</code> accepts any length of nested array vector and treats the first element as the property name and the rest of the argument as the property value, so that the following two statements are both valid and do exactly the same thing:</P>
<PRE> 'Win1.But' ⎕WI 'where' (12 20 3 8) ⍝ Two-element vector
'Win1.But' ⎕WI 'where' 12 20 3 8 ⍝ Five-element vector
</PRE>
<P>(You can also use the <tt>New</tt>, <tt>Create</tt> and <tt>Set</tt> methods to set multiple properties in one line.)</p>
<P><i>Reading a property:</i></P>
<PRE> Value ← ObjectName ⎕WI PropertyName
</PRE>
<P>ObjectName and PropertyName are character vectors as before, and the current value for the property is returned as the explicit result of <code>⎕WI.</code> For example:</P>
<PRE> 'Win1.But' ⎕WI 'where'
12 20 3 8
'Win1.But' ⎕WI 'caption'
Cancel
</PRE>
<P><i>Invoking a method:</i></P>
<PRE> {Result ← } ObjectName ⎕WI MethodName {Argument}
</PRE>
<P>ObjectName and MethodName are character vectors, and Argument is an optional argument to the method. It can be any APL array valid for the particular method in question. Again, <code>⎕WI</code> accepts any length of nested array vector and treats the first element as the method name and the rest as the argument to the method. In addition some methods return a result.</P>
<PRE> 'Win1.Movie' ⎕WI 'Rewind' ⍝ Method with no argument
'Win1.But' ⎕WI 'New' 'Button' ⍝ Argument is 'Button'
'Win1.RichEdit' ⎕WI 'Linelength' 4 ⍝ Argument is 4
17 ⍝ Method returns result
</PRE>
<H2>Mixing dot-notation and <code>⎕WI</code></H2>
<p>If you create a top-level object using <code>⎕WI</code>, you cannot access it using dot notation because there is no reference to the object held in the workspace. However, if you create a top-level object using <code>⎕NEW</code>, then you can access it (and its children, if any) using <code>⎕WI</code>. When an object is created using <code>⎕NEW</code>, APLX automatically assigns a name in the form <tt>SYSOBJ-<i>NNN</i></tt> to the object, and you can use this name in the left argument to <code>⎕WI</code>. The easiest way of doing this is to reference the <A HREF="ch_030_030_0690.htm"><tt>self</tt></A> property, which gives the fully-qualified name:</p>
<pre> dlg←'⎕' ⎕NEW 'Dialog'
dlg.self
SYSOBJ-1
dlg.Lst1.New 'List'
dlg.Lst1.self
SYSOBJ-1.Lst1
dlg.Lst1.self ⎕WI 'List' ⎕W
</pre>
<p>This is particularly useful for a few cases where <code>⎕WI</code> provides an easier syntax than dot-notation. These include accessing array properties in OCX/ActiveX controls, and dynamically determining the source of an event using <code><A HREF="ch_020_070_880.htm">⎕WSELF</A></code>.</p>
<H2>Converting <code>⎕WI</code> syntax to dot-notation</H2>
<p>If you have written code using <code>⎕WI</code> syntax in previous versions of APLX, it will continue to work. However, if you wish, you can convert the syntax to use <code>⎕NEW</code> and dot-notation. The workspace <tt>10 CONVERTQWI</tt> helps to automate this.</p>
<H2>Special considerations for Client-Server versions of APLX</H2>
<p>In Client-Server implementations of APLX, the front-end which implements the user-interface (the "Client") runs on one machine, and the APLX interpreter itself (the "Server") can run on a different machine. The two parts of the application communicate via a TCP/IP network. Typically, the Client will be the APLX front-end built as a 32-bit Windows application running on a desktop PC, and the Server will be a 64-bit APLX64 interpreter running on a 64-bit Linux or Windows server. Alternatively, the Client and the Server may run on the same physical machine (this is the case if you are running APLX64 on a 64-bit desktop machine).</p>
<p>In this environment, it is important to bear in mind that <b>the whole of the System Class sub-system runs on the Client machine as a 32-bit application</b>. This is nearly always transparent to your application, so for example a workspace originally written for a 32-bit Windows desktop machine should continue to work unchanged in a Client-Server configuration where the Client executes on a 32-bit Windows desktop and the APLX interpreter (Server) executes on a 64-bit server machine. However, you should be aware that any file or path names used in your objects always relate to the Client machine, never to the Server.</p>
<p>In such an environment, when you make a <code>⎕WI</code> call, the parameters are passed over the network from the Server to the <code>⎕WI</code> sub-system on the Client machine. If the Server is a 64-bit APLX64 interpreter, the data will be converted to 32-bit form before it is sent over the network. (This means that any data you associate with an object using the <tt><A HREF="ch_030_030_0170.htm">data</A></tt> property or a <A HREF="ch_030_030_1040.htm">'delta' variable</a> will be held on the Client machine, and must be representable as a 32-bit variable).</p>
<p>See also the description of the <code>
<A HREF="ch_030_020_005.htm">APL</A></code> (Child Task) object for special considerations applying to multiple tasks in a Client-Server environment.</p>
<hr>
</td>
</tr>
<tr>
<td width="800" valign="top" colspan="2">
<center>Topic: <A HREF="ch.htm"><code>APLX Help</code></A> : <A HREF="ch_030.htm"><code>System Classes</code></A> : <A HREF="ch_030_010.htm"><code>Introduction to System Classes</code></A>
</center>
<center>
[ <A HREF="ch_030_011.htm">Next</A> | <A HREF="ch.htm">Contents</A> | <A HREF="help_index.htm">Index</A> | <A HREF="http://www.microapl.co.uk/apl/index.html">APL Home</A> ]</center>
<br></td>
</tr>
</table>
<!-- %%COMMON_BODY_TAIL%% -->
<p class="copyright">Copyright © 1996-2010 MicroAPL Ltd</p>
<!-- %%END%% -->
</body>
</html>