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 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|
|DeviceContext||Creating device contexts and getting their properties|
|Font||Creating fonts and drawing text|
|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|
|Class||Creating custom window classes.|
|Window||General functions on windows.|
|Message||Sending messages to windows.|
|Caret||The insertion point in an edit window.|
|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 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.|
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.|
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.|
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.
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.