<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Windows Interface Reference</title>
</head>
<body>
<h1>Windows Interface Reference</h1>
<p>The Windows™ interface is arranged as forty structures containing several hundred
functions. It is not possible to provide documentation for all these functions and
it would involve duplicating much of the Windows documentation. Generally the
functions take the same arguments and return the same result types as the corresponding
function in C but there are some differences to reflect the differences in the type
systems. Functions that return a status result in C generally return unit in ML and
raise 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
returning a result the corresponding ML function simply returns the appropriate
result. This often occurs with functions that extract strings.</p>
<p>Many objects, such as windows and fonts, are represented by <em>handles</em>, e.g. HWND
and HFONT. Frequently, when programming with Windows in C it is necessary to cast
between handles and integers, such as when sending a message to obtain the current font
for a window. The ML interface avoids this where possible by using union types but
the <a href="Globals.html">Globals</a> structure includes functions to perform these casts
if necessary. It also contains a value hNull which can be used as a NULL handle.
Generally though, functions such as <a href="Window.html#SetParent">SetParent</a>
or <a href="Keyboard.html#GetActiveWindow">GetActiveWindow</a> which can take an optional
argument or return an optional result use an option type in ML. Although there are
separate types HFONT, HBITMAP, etc for the various kinds of GDI object, these are all the
same 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>
<p>Frequently functions in C take an integer argument with constants defined.
Datatypes are used for these in ML where possible. Where in C several options
can be or-ed together in ML a list of a datatype is used.</p>
<h3>Drawing and device contexts (GDI functions)</h3>
<p>Drawing to a window or printing a page on a printer are handled in the same way.
An abstract device, a <em>device context</em>, is used and all drawing is done on one of
these.</p>
<div align="left">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="15%"><a href="Bitmap.html">Bitmap</a></td>
<td>Arbitrary bitmap patterns</td>
</tr>
<tr>
<td><a href="Brush.html">Brush</a></td>
<td>Coloured and patterned brushes</td>
</tr>
<tr>
<td><a href="Clipping.html">Clipping</a></td>
<td>Clipping regions</td>
</tr>
<tr>
<td><a href="Color.html">Color</a></td>
<td>Colours</td>
</tr>
<tr>
<td><a href="DeviceContext.html">DeviceContext</a></td>
<td>Creating device contexts and getting their properties</td>
</tr>
<tr>
<td><a href="Font.html">Font</a></td>
<td>Creating fonts and drawing text</td>
</tr>
<tr>
<td><a href="Line.html">Line</a></td>
<td>Drawing lines</td>
</tr>
<tr>
<td><a href="Metafile.html">Metafile</a></td>
<td>Recording drawing operations</td>
</tr>
<tr>
<td><a href="Path.html">Path</a></td>
<td>Sequences of lines to form a path</td>
</tr>
<tr>
<td><a href="Pen.html">Pen</a></td>
<td>Pens used when drawing lines</td>
</tr>
<tr>
<td><a href="Printing.html">Printing</a></td>
<td>Functions used when drawing to a printer</td>
</tr>
<tr>
<td><a href="Rectangle.html">Rectangle</a></td>
<td>Operations on rectangles</td>
</tr>
<tr>
<td><a href="Region.html">Region</a></td>
<td>Areas of a device context</td>
</tr>
<tr>
<td><a href="Shape.html">Shape</a></td>
<td>Various shapes</td>
</tr>
<tr>
<td><a href="Transform.html">Transform</a></td>
<td>Co-ordinate transforms</td>
</tr>
</table>
</div>
<h3>Window creation and communication</h3>
<div align="left">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="15%"><a href="Class.html">Class</a></td>
<td>Creating custom window classes.</td>
</tr>
<tr>
<td><a href="Window.html">Window</a></td>
<td>General functions on windows.</td>
</tr>
<tr>
<td><a href="Message.html">Message</a></td>
<td>Sending messages to windows.</td>
</tr>
<tr>
<td><a href="Caret.html">Caret</a></td>
<td>The insertion point in an edit window.</td>
</tr>
<tr>
<td><a href="Cursor.html">Cursor</a></td>
<td>Mouse cursors.</td>
</tr>
<tr>
<td><a href="Icon.html">Icon</a></td>
<td>Icons for windows.</td>
</tr>
<tr>
<td><a href="Menu.html">Menu</a></td>
<td>Pull-down and pop-up menus.</td>
</tr>
<tr>
<td><a href="DragDrop.html">DragDrop</a></td>
<td>Dragging and dropping files.</td>
</tr>
<tr>
<td><a href="Keyboard.html">Keyboard</a></td>
<td>Keyboard input control. The input itself is by way of messages.</td>
</tr>
<tr>
<td><a href="Mouse.html">Mouse</a></td>
<td>Mouse input control. The input itself is by way of messages.</td>
</tr>
<tr>
<td><a href="Painting.html">Painting</a></td>
<td>Painting and drawing to a window.</td>
</tr>
</table>
</div>
<h3>Dialogue windows</h3>
<p>Dialogue boxes are windows typically consisting of a number of controls and a button to
confirm or cancel a selection. </p>
<div align="left">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="15%"><a href="Dialog.html">Dialog</a></td>
<td>Custom dialogue boxes.</td>
</tr>
<tr>
<td><a href="MessageBox.html">MessageBox</a></td>
<td>A simple dialogue box containing a piece of text and one or more buttons.</td>
</tr>
<tr>
<td><a href="CommonDialog.html">CommonDialog</a></td>
<td>Standard dialogues to select a file, print a document, etc.</td>
</tr>
</table>
</div>
<h3>Standard window classes</h3>
<p>For many purposes a standard window class can be used. These structures mainly
contain values for the window styles which can be used to control the appearance of the
window. Most operations are performed by sending messages from the <a href="Message.html">Message</a> structure.</p>
<div align="left">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="15%"><a href="Button.html">Button</a></td>
<td>Push buttons, radio buttons and check boxes</td>
</tr>
<tr>
<td><a href="Combobox.html">Combobox</a></td>
<td>A combination of a list box and an edit box.</td>
</tr>
<tr>
<td><a href="Edit.html">Edit</a></td>
<td>Single lines for text input or multiple lines for general editing.</td>
</tr>
<tr>
<td><a href="ListBox.html">ListBox</a></td>
<td>Selection from a list of options.</td>
</tr>
<tr>
<td><a href="Scrollbar.html">Scrollbar</a></td>
<td>Can be used to scroll a window. This structure includes functions to scroll
windows and device contexts..</td>
</tr>
<tr>
<td><a href="Static.html">Static</a></td>
<td>Static windows can be used to display text labels or pictures.</td>
</tr>
</table>
</div>
<h3>Others</h3>
<p>Various other structures.</p>
<div align="left">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td width="15%"><a href="Globals.html">Globals</a></td>
<td>Various functions on handles and to obtain the handles for the Poly/ML window and
application.</td>
</tr>
<tr>
<td width="15%"><a href="WinSystem.html">WinSystem</a></td>
<td>System information functions.</td>
</tr>
<tr>
<td><a href="Resource.html">Resource</a></td>
<td>Resource files can be used to hold resources such as menus, strings, dialogues etc.</td>
</tr>
<tr>
<td><a href="Clipboard.html">Clipboard</a></td>
<td>The clipboard is used to communicate with other applications.</td>
</tr>
<tr>
<td><a href="Locale.html">Locale</a></td>
<td>Language definitions to be used with resource files.</td>
</tr>
</table>
</div>
<h3>Restrictions and Differences between ML and C</h3>
<p>The interface was designed so that the definition of functions provided for C should
carry over to the ML version. This simplifies documentation and also makes it
relatively easy to port programs between C and ML. There are a few differences which
are worth noting. </p>
<h4>Messages and Window Procedures</h4>
<p>The major difference is in the way messages are handled. In C a message is simply
an integer but each message is accompanied by two parameters, called <em>wParam</em> and <em>lParam</em>.
Each message defines how these are to interpreted and it is usually necessary to
coerce one or other of them to a specific type. Often lParam is defined to be a
pointer to a particular structure. Sometimes the parameters are pointers which are
updated by the window procedure. In ML messages are fully typed and as much as
possible of the message information is made available. This does require some
conversion and it is possible that information could be lost if a message was converted to
ML form and then back to C. For this reason the handling of messages is done
slightly differently from C. In C it is necessary to call DefWindowProc to provide
default processing of messages. If it is not called a result must be returned to the
caller. In ML an option type is used. If NONE is returned then DefWindowProc
is called with the original arguments, before they were converted to ML, otherwise the
value given is returned as the result. </p>
<p>There are generally complications with callback functions due to differences in the
notion of a function in ML and C. In C a function is always the pointer to a piece
of code whereas in ML it is a closure. This makes it impossible to pass ML functions
directly to C and instead different callbacks have to be implemented by hand. For
this reason EM_SETWORDBREAKPROC and EM_GETWORDBREAKPROC to set and get the word break
procedure for an edit window are not implemented nor are various of the callbacks in the
common controls.</p>
<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>
</body>
</html>
