1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3 4<head> 5<title>Windows Interface Reference</title> 6</head> 7 8<body> 9 10<h1>Windows Interface Reference</h1> 11 12<p>The Windows™ interface is arranged as forty structures containing several hundred 13functions. It is not possible to provide documentation for all these functions and 14it would involve duplicating much of the Windows documentation. Generally the 15functions take the same arguments and return the same result types as the corresponding 16function in C but there are some differences to reflect the differences in the type 17systems. Functions that return a status result in C generally return unit in ML and 18raise an OS.Syserr exception if they fail. Where a C function, such as <a href="Clipping.html#GetClipBox">GetClipBox</a>, takes an argument by reference as a way of 19returning a result the corresponding ML function simply returns the appropriate 20result. This often occurs with functions that extract strings.</p> 21 22<p>Many objects, such as windows and fonts, are represented by <em>handles</em>, e.g. HWND 23and HFONT. Frequently, when programming with Windows in C it is necessary to cast 24between handles and integers, such as when sending a message to obtain the current font 25for a window. The ML interface avoids this where possible by using union types but 26the <a href="Globals.html">Globals</a> structure includes functions to perform these casts 27if necessary. It also contains a value hNull which can be used as a NULL handle. 28 Generally though, functions such as <a href="Window.html#SetParent">SetParent</a> 29or <a href="Keyboard.html#GetActiveWindow">GetActiveWindow</a> which can take an optional 30argument or return an optional result use an option type in ML. Although there are 31separate types HFONT, HBITMAP, etc for the various kinds of GDI object, these are all the 32same as HGDIOBJ. This simplifies the types of functions such as <a href="DeviceContext.html#GetCurrentObject">GetCurrentObject</a> and <a href="DeviceContext.html#GetObjectType">GetObjectType</a>.</p> 33 34<p>Frequently functions in C take an integer argument with constants defined. 35 Datatypes are used for these in ML where possible. Where in C several options 36can be or-ed together in ML a list of a datatype is used.</p> 37 38<h3>Drawing and device contexts (GDI functions)</h3> 39 40<p>Drawing to a window or printing a page on a printer are handled in the same way. 41An abstract device, a <em>device context</em>, is used and all drawing is done on one of 42these.</p> 43<div align="left"> 44 45<table border="0" cellpadding="0" cellspacing="0" width="100%"> 46 <tr> 47 <td width="15%"><a href="Bitmap.html">Bitmap</a></td> 48 <td>Arbitrary bitmap patterns</td> 49 </tr> 50 <tr> 51 <td><a href="Brush.html">Brush</a></td> 52 <td>Coloured and patterned brushes</td> 53 </tr> 54 <tr> 55 <td><a href="Clipping.html">Clipping</a></td> 56 <td>Clipping regions</td> 57 </tr> 58 <tr> 59 <td><a href="Color.html">Color</a></td> 60 <td>Colours</td> 61 </tr> 62 <tr> 63 <td><a href="DeviceContext.html">DeviceContext</a></td> 64 <td>Creating device contexts and getting their properties</td> 65 </tr> 66 <tr> 67 <td><a href="Font.html">Font</a></td> 68 <td>Creating fonts and drawing text</td> 69 </tr> 70 <tr> 71 <td><a href="Line.html">Line</a></td> 72 <td>Drawing lines</td> 73 </tr> 74 <tr> 75 <td><a href="Metafile.html">Metafile</a></td> 76 <td>Recording drawing operations</td> 77 </tr> 78 <tr> 79 <td><a href="Path.html">Path</a></td> 80 <td>Sequences of lines to form a path</td> 81 </tr> 82 <tr> 83 <td><a href="Pen.html">Pen</a></td> 84 <td>Pens used when drawing lines</td> 85 </tr> 86 <tr> 87 <td><a href="Printing.html">Printing</a></td> 88 <td>Functions used when drawing to a printer</td> 89 </tr> 90 <tr> 91 <td><a href="Rectangle.html">Rectangle</a></td> 92 <td>Operations on rectangles</td> 93 </tr> 94 <tr> 95 <td><a href="Region.html">Region</a></td> 96 <td>Areas of a device context</td> 97 </tr> 98 <tr> 99 <td><a href="Shape.html">Shape</a></td> 100 <td>Various shapes</td> 101 </tr> 102 <tr> 103 <td><a href="Transform.html">Transform</a></td> 104 <td>Co-ordinate transforms</td> 105 </tr> 106</table> 107</div> 108 109<h3>Window creation and communication</h3> 110<div align="left"> 111 112<table border="0" cellpadding="0" cellspacing="0" width="100%"> 113 <tr> 114 <td width="15%"><a href="Class.html">Class</a></td> 115 <td>Creating custom window classes.</td> 116 </tr> 117 <tr> 118 <td><a href="Window.html">Window</a></td> 119 <td>General functions on windows.</td> 120 </tr> 121 <tr> 122 <td><a href="Message.html">Message</a></td> 123 <td>Sending messages to windows.</td> 124 </tr> 125 <tr> 126 <td><a href="Caret.html">Caret</a></td> 127 <td>The insertion point in an edit window.</td> 128 </tr> 129 <tr> 130 <td><a href="Cursor.html">Cursor</a></td> 131 <td>Mouse cursors.</td> 132 </tr> 133 <tr> 134 <td><a href="Icon.html">Icon</a></td> 135 <td>Icons for windows.</td> 136 </tr> 137 <tr> 138 <td><a href="Menu.html">Menu</a></td> 139 <td>Pull-down and pop-up menus.</td> 140 </tr> 141 <tr> 142 <td><a href="DragDrop.html">DragDrop</a></td> 143 <td>Dragging and dropping files.</td> 144 </tr> 145 <tr> 146 <td><a href="Keyboard.html">Keyboard</a></td> 147 <td>Keyboard input control. The input itself is by way of messages.</td> 148 </tr> 149 <tr> 150 <td><a href="Mouse.html">Mouse</a></td> 151 <td>Mouse input control. The input itself is by way of messages.</td> 152 </tr> 153 <tr> 154 <td><a href="Painting.html">Painting</a></td> 155 <td>Painting and drawing to a window.</td> 156 </tr> 157</table> 158</div> 159 160<h3>Dialogue windows</h3> 161 162<p>Dialogue boxes are windows typically consisting of a number of controls and a button to 163confirm or cancel a selection. </p> 164<div align="left"> 165 166<table border="0" cellpadding="0" cellspacing="0" width="100%"> 167 <tr> 168 <td width="15%"><a href="Dialog.html">Dialog</a></td> 169 <td>Custom dialogue boxes.</td> 170 </tr> 171 <tr> 172 <td><a href="MessageBox.html">MessageBox</a></td> 173 <td>A simple dialogue box containing a piece of text and one or more buttons.</td> 174 </tr> 175 <tr> 176 <td><a href="CommonDialog.html">CommonDialog</a></td> 177 <td>Standard dialogues to select a file, print a document, etc.</td> 178 </tr> 179</table> 180</div> 181 182<h3>Standard window classes</h3> 183 184<p>For many purposes a standard window class can be used. These structures mainly 185contain values for the window styles which can be used to control the appearance of the 186window. Most operations are performed by sending messages from the <a href="Message.html">Message</a> structure.</p> 187<div align="left"> 188 189<table border="0" cellpadding="0" cellspacing="0" width="100%"> 190 <tr> 191 <td width="15%"><a href="Button.html">Button</a></td> 192 <td>Push buttons, radio buttons and check boxes</td> 193 </tr> 194 <tr> 195 <td><a href="Combobox.html">Combobox</a></td> 196 <td>A combination of a list box and an edit box.</td> 197 </tr> 198 <tr> 199 <td><a href="Edit.html">Edit</a></td> 200 <td>Single lines for text input or multiple lines for general editing.</td> 201 </tr> 202 <tr> 203 <td><a href="ListBox.html">ListBox</a></td> 204 <td>Selection from a list of options.</td> 205 </tr> 206 <tr> 207 <td><a href="Scrollbar.html">Scrollbar</a></td> 208 <td>Can be used to scroll a window. This structure includes functions to scroll 209 windows and device contexts..</td> 210 </tr> 211 <tr> 212 <td><a href="Static.html">Static</a></td> 213 <td>Static windows can be used to display text labels or pictures.</td> 214 </tr> 215</table> 216</div> 217 218<h3>Others</h3> 219 220<p>Various other structures.</p> 221<div align="left"> 222 223<table border="0" cellpadding="0" cellspacing="0" width="100%"> 224 <tr> 225 <td width="15%"><a href="Globals.html">Globals</a></td> 226 <td>Various functions on handles and to obtain the handles for the Poly/ML window and 227 application.</td> 228 </tr> 229 <tr> 230 <td width="15%"><a href="WinSystem.html">WinSystem</a></td> 231 <td>System information functions.</td> 232 </tr> 233 <tr> 234 <td><a href="Resource.html">Resource</a></td> 235 <td>Resource files can be used to hold resources such as menus, strings, dialogues etc.</td> 236 </tr> 237 <tr> 238 <td><a href="Clipboard.html">Clipboard</a></td> 239 <td>The clipboard is used to communicate with other applications.</td> 240 </tr> 241 <tr> 242 <td><a href="Locale.html">Locale</a></td> 243 <td>Language definitions to be used with resource files.</td> 244 </tr> 245</table> 246</div> 247 248<h3>Restrictions and Differences between ML and C</h3> 249 250<p>The interface was designed so that the definition of functions provided for C should 251carry over to the ML version. This simplifies documentation and also makes it 252relatively easy to port programs between C and ML. There are a few differences which 253are worth noting. </p> 254 255<h4>Messages and Window Procedures</h4> 256 257<p>The major difference is in the way messages are handled. In C a message is simply 258an integer but each message is accompanied by two parameters, called <em>wParam</em> and <em>lParam</em>. 259 Each message defines how these are to interpreted and it is usually necessary to 260coerce one or other of them to a specific type. Often lParam is defined to be a 261pointer to a particular structure. Sometimes the parameters are pointers which are 262updated by the window procedure. In ML messages are fully typed and as much as 263possible of the message information is made available. This does require some 264conversion and it is possible that information could be lost if a message was converted to 265ML form and then back to C. For this reason the handling of messages is done 266slightly differently from C. In C it is necessary to call DefWindowProc to provide 267default processing of messages. If it is not called a result must be returned to the 268caller. In ML an option type is used. If NONE is returned then DefWindowProc 269is called with the original arguments, before they were converted to ML, otherwise the 270value given is returned as the result. </p> 271 272<p>There are generally complications with callback functions due to differences in the 273notion of a function in ML and C. In C a function is always the pointer to a piece 274of code whereas in ML it is a closure. This makes it impossible to pass ML functions 275directly to C and instead different callbacks have to be implemented by hand. For 276this reason EM_SETWORDBREAKPROC and EM_GETWORDBREAKPROC to set and get the word break 277procedure for an edit window are not implemented nor are various of the callbacks in the 278common controls.</p> 279 280<p><strong><small><small>Last updated: <!--webbot bot="TimeStamp" S-FORMAT="%d %B %Y" S-TYPE="EDITED" startspan -->28 October 2001<!--webbot bot="TimeStamp" endspan i-checksum="32163" --> by David Matthews.</small></small></strong> </p> 281</body> 282</html> 283