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

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.