Interface Guide Version 13.2 The tool of thought for expert programming Dyalog is a trademark of Dyalog Limited Copyright © 1982-2013 by Dyalog Limited All rights reserved. Version: 13.2 Revision: 22186 No part of this publication may be reproduced in any form by any means without the prior written per- mission of Dyalog Limited. Dyalog Limited makes no representations or warranties with respect to the contents hereof and spe- cifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Dya- log Limited reserves the right to revise this publication without notification. TRADEMARKS: SQAPL is copyright of Insight Systems ApS. UNIX is a registered trademark of The Open Group. Windows, Windows Vista, Visual Basic and Excel are trademarks of Microsoft Corporation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Array Editor is copyright of davidliebtag.com All other trademarks and copyrights are acknowledged. Contents Chapter 1: Introduction 1 Overview 1 Concepts 2 Creating Objects 8 Properties 11 User Interaction & Events 17 Methods 24 GUI Objects as Namespaces 26 Modal Dialog Boxes 31 Multi-Threading with Objects 33 The Co-ordinate System 34 Colour 35 Fonts 36 Drag and Drop 37 Debugging 38 Creating Objects using NEW 39 Native Look and Feel 40 Chapter 2: GUI Tutorial 43 Introduction 43 Some Concepts 43 Creating a Form 44 Adding a Fahrenheit Label 45 Adding a Fahrenheit Edit Field 46 Adding a Centigrade Label & Edit Field 47 Adding Calculate Buttons 48 Closing the Application Window 49 Adding a Quit Button 50 The Calculation Functions 51 Testing the Application 52 Making the Enter Key Work 53 Introducing a ScrollBar 54 Adding a Menu 55 Running from Desktop 58 Using NEW instead of WC 60 Temperature Converter Class 62 Dual Class Example 65 iv Chapter 3: Graphics 69 Introduction 69 Drawing Lines 70 Drawing in a Bitmap 71 Multiple Graphical Items 72 Unnamed Graphical Objects 73 Bitmaps and Icons 74 Metafiles 76 Picture Buttons 78 Using Icons 81 Chapter 4: Composite Controls 83 The ToolControl and ToolButton Objects 83 The CoolBar and CoolBand Objects 95 The TabControl and TabButton Objects 104 The StatusBar Object 113 Chapter 5: Hints and Tips 117 Using Hints 117 Using Tips 120 Hints and Tips Combined 121 Chapter 6: Using the Grid Object 123 Defining Overall Appearance 124 Row and Column Titles 125 Displaying and Editing Values in Grid Cells 127 Specifying Individual Cell Attributes 132 Drawing Graphics on a Grid 136 Controlling User Input 139 TreeView Feature 142 Grid Comments 147 Chapter 7: Multiple-Document (MDI) Applications 151 MDI Behaviour 152 Menus in MDI Applications 154 Defining a Window Menu 155 Arranging Child Forms and Icons 156 Chapter 8: Docking 157 Introduction 157 Docking Events 158 v Docking a Form inside another 160 Docking a Form into a CoolBar 165 Undocking a SubForm or a CoolBand 167 Docking and Undocking a ToolControl 168 Native Look and Feel 172 Chapter 9: TCP/IP Support 173 Introduction 173 APL as a TCP/IP Server 175 APL as a TCP/IP Client 177 Host and Service Names 178 Sending and Receiving Data 179 User Datagram Protocol (UDP) and APL 181 Client/Server Operation 183 Chapter 10: APL and the Internet 189 Introduction 189 Writing a Web Client 191 Writing a Web Server 200 Chapter 11: OLE Automation Client and OLE Controls 205 Introduction 205 Using an OLE Server 206 Loading an ActiveX Control 206 Type Information 207 Methods 215 Properties 219 Events 221 Using the Microsoft Jet Database Engine 222 OLE Objects without Type Information 224 Collections 226 Null Values 227 Additional Interfaces 228 Writing Classes based on OLEClient 229 Chapter 12: OLE Automation Server 231 Introduction 231 In-process OLE Servers 234 Out-of-process OLE Servers 236 The LOAN Workspace 239 Implementing an Object Hierarchy 249 The CFILES Workspace 250 vi Configuring an out-of-process OLEServer for DCOM 260 Calling an OLE Function Asynchronously 264 Chapter 13: Writing ActiveX Controls in Dyalog APL 269 Overview 270 The Dual Control Tutorial 274 Chapter 14: Shared Variables (DDE) 299 Introduction to DDE 299 Shared Variable Principles 300 APL and DDE in Practice 305 State and Access Control 308 Example: Communication Between APLs 314 Example : Excel as the Server 315 Example : Excel as the Client 317 Example : APL as Compute Server for Excel 318 Restrictions & Limitations 320 Index 321 1 Chapter 1: Introduction Overview This manual describes various interfaces between Dyalog APL and Windows. Chapter 1 introduces the concepts of the Dyalog APL Graphical User Interface (GUI) and describes, in outline, how the system works. Chapter 2 contains a tutorial which takes you step-by-step through the imple- mentation of a simple GUI application. Chapters 3 explains how to draw graphics using primitive graphical objects such as Poly, Bitmap and Metafile objects. Chapter 4 describes how to use toolbars, tab controls and status bars. Chapter 6 covers the important Grid object that provides a spreadsheet interface for displaying and editing tables of data and Chapters 7 and 8 describe the Multiple Document Interface (MDI) and docking. Fur- ther GUI material is provided in the WTUTOR, WTUTOR95 and WDESIGN work- spaces. Chapter 9 describes the TCP/IP interface which is implemented in the same object- oriented style. Chapter 10 explores how the TCP/IP interface is used to connect Dya- log APL to the Internet. Chapters 11-13 describe the various ways in which Dyalog APL may communicate with other Windows applications using Component Object Model (COM) inter- faces. These interfaces allow APL to act as an OLE Automation server and client, and allow you to write ActiveX controls in Dyalog APL. Chapter 14 describes the DDE interface which is implemented using (traditional) APL shared variables. However, please note that DDE has all but been replaced by COM, and is no longer promoted as a major technology by Microsoft. 2 Dyalog APL/W Interface Guide Version 13.2 Concepts The Dyalog APL GUI is based upon four important concepts; objects, properties, events and methods. Objects Objects are instances of classes that contain information and provide functionality. Most Dyalog APL objects are GUI objects that may be displayed on the screen and with which you can interact. An example of an object is a push-button (an instance of class Button) which you may press to cause the program to take a particular action. Objects are defined in hierarchies. Objects are also namespaces and may contain functions, variables, and indeed other namespaces. This allows you to store the code and data that is required by a given object within that object. Functions and variables stored in an object are hidden and protected from conflicts with functions and variables in the outside workspace and with those in other objects. Properties Each object has an associated set of properties which describe how it looks and behaves. For example, a Button has a property called Caption which defines the char- acter string to be displayed in it. It also has a property called Type which may be Push (the button appears to move in and out when it is pressed), Radio (the button has two states and may be toggled on and off); and so forth. Events During interaction with the user, an object is capable of generating events. There are essentially two types of event, raw events and object events. Raw events are typ- ically associated with a particular hardware operation. Pressing a mouse button, press- ing a key on the keyboard, or moving the mouse pointer are examples of raw events. An object event is generated by some action that is specific to the object in question, but which may typically be achieved by a variety of hardware operations. An example is the Select event. For a Button object, this event is generated when the user presses the Button. In MS-Windows, this can be done in several ways. Firstly, the user may click the left mouse button over the object. Secondly, under certain cir- cumstances, the Select event can be generated when the user presses the Enter key. Finally, the event will occur if the user presses a "short-cut" (mnemonic) key that is associated with the Button. Chapter 1: Introduction 3 Methods Methods are effectively functions that an object provides; they are things that you may invoke to make the object do something for you. In Dyalog APL, the distinction between methods and events is tenuous, because events also make objects perform actions and you may generate events under program control. For example, a Scroll event is generated by a scrollbar when the user moves the thumb. Conversely, you can make a scrollbar scroll by generating a Scroll event. Nevertheless, the concept of a method is useful to describe functions that can only be invoked by a program and are not directly accessible to the user. 4 Dyalog APL/W Interface Guide Version 13.2 Objects The following objects are supported. 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 standard Windows tool control PropertySheet contains PropertyPages PropertyPage