# Windows Interface Reference

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 GetClipBox, 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.

Many objects, such as windows and fonts, are represented by handles, 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 Globals 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 SetParent or GetActiveWindow 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 GetCurrentObject and GetObjectType.

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.

### Drawing and device contexts (GDI functions)

Drawing to a window or printing a page on a printer are handled in the same way. An abstract device, a device context, is used and all drawing is done on one of these.

Bitmap | Arbitrary bitmap patterns
Brush | Coloured and patterned brushes
Clipping | Clipping regions
Color | Colours
DeviceContext | Creating device contexts and getting their properties
Font | Creating fonts and drawing text
Line | Drawing lines
Metafile | Recording drawing operations
Path | Sequences of lines to form a path
Pen | Pens used when drawing lines
Printing | Functions used when drawing to a printer
Rectangle | Operations on rectangles
Region | Areas of a device context
Shape | Various shapes
Transform | Co-ordinate transforms

### Window creation and communication

Class | Creating custom window classes.
Window | General functions on windows.
Message | Sending messages to windows.
Caret | The insertion point in an edit window.
Cursor | Mouse cursors.
Icon | Icons for windows.
Menu | Pull-down and pop-up menus.
DragDrop | Dragging and dropping files.
Keyboard | Keyboard input control. The input itself is by way of messages.
Mouse | Mouse input control. The input itself is by way of messages.
Painting | Painting and drawing to a window.

### Dialogue windows

Dialogue boxes are windows typically consisting of a number of controls and a button to confirm or cancel a selection.

Dialog | Custom dialogue boxes.
MessageBox | A simple dialogue box containing a piece of text and one or more buttons.
CommonDialog | Standard dialogues to select a file, print a document, etc.

### Standard window classes

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 Message structure.

Button | Push buttons, radio buttons and check boxes
Combobox | A combination of a list box and an edit box.
Edit | Single lines for text input or multiple lines for general editing.
ListBox | Selection from a list of options.
Scrollbar | Can be used to scroll a window. This structure includes functions to scroll windows and device contexts..
Static | Static windows can be used to display text labels or pictures.

### Others

Various other structures.

Globals | Various functions on handles and to obtain the handles for the Poly/ML window and application.
WinSystem | System information functions.
Resource | Resource files can be used to hold resources such as menus, strings, dialogues etc.
Clipboard | The clipboard is used to communicate with other applications.
Locale | Language definitions to be used with resource files.

### Restrictions and Differences between ML and C

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.

#### Messages and Window Procedures

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 wParam and lParam. 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.

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.

Last updated: 28 October 2001 by David Matthews.