\chapter{Notes on XPCE for MS-Windows}		\label{sec:mswin}

\index{Windows 95}\index{Windows NT}\index{Windows 2000}\index{Windows XP}
The binary version of \product{} runs on Windows~NT, 2000 and XP.%
	\footnote{As of 6.5.x, XPCE is a UNICODE application and is no
		  longer supported for Windows 95, 98 and ME.}
Its functionality is very close to the Unix/X11 version, making
applications source-code compatible between the two platforms. \ifpw{
Quintus \fileext{qof} files are identical on Unix and Windows platforms,
reducing the effort of porting an applicaction to relinking the
\fileext{qof} files on the target platform}{}.

\product{} does not build on top of the hosting window-systems GUI library.
Instead, the primitive windowing and graphics facilities of the host are
used to implement `\product{}'s Virtual Window System'. All of \product{}'s
graphical functionality is build on top of this `Virtual Window System'.
This approach guarantees full portability of applications between the
platforms.

The look-and-feel of \product{} may be tailored using the defaults file
located in \metafile{<pcehome>/Defaults}.


\section{Currently unsupported features in the Win32 version}

\begin{itemlist}
    \item [Class socket]
No support of file-based addressing (Unix domain sockets). Inet-domain
sockets are provided (interfacing to WinSock).
\end{itemlist}


\section{Interprocess communication, extensions and interaction}

\begin{itemlist}
    \item [DDE]		\index{DDE}%
Not (yet) supported by \product{}. \ifpw{}{SWI-Prolog supports it
though, making DDE a feasible interprocess communication approach.}
    \item [WinSock]		\index{WinSock}%
Provides standard TCP/IP communication, both server- and client-side.
    \item [Named Pipes]		\index{named pipes}%
Not (yet) supported.
    \item [OLE]			\index{OLE}\index{CORBA}%
Not considered yet.  We however are considering CORBA, which provides
an open standard for object-oriented, network-transparent interprocess
communications.  CORBA and OLE are integrated.
    \item [Drag-And-Drop]	\index{drag-and-drop}%
\product{} can accept dropped files from other applications. Inside the
application, drag-and-drop is fully compatible to the Unix version.
See \pllib{dragdrop}.
    \item [Cut/Paste]		\index{cut-and-paste}%
Supported for exchanging text, and pictures using the Windows MetaFile
format.
    \item [DLL]			\index{DLL}%
Not supported by \product{}. \ifpw{\quintus{}}{SWI-Prolog} provides it
though, making DLL available to \productpl{} applications.
\end{itemlist}


\section{Accessing Windows Graphics Resources}

\product{} on Win32 defines the same cursor, colour and font-names as the
Unix/X11 version to guarantee portability. It is desirable to have
access to all the native Windows graphical resources. This allows the
application to maintain better look-and-feel compatibility to other
Win32 applications. Therefore the classes colour, cursor and font
provide access to related Window resources.

\strong{It is NOT advised to use these objects in your application code
directly as this will stop the application to run on the Unix/X11
version of \product{}. We advice using these objects in the \product{}
defaults file (\metafile{<pcehome>/Defaults}) only, or use conditional code
using `pce <-window_system'.}


\section{Accessing Windows Colours}

Colours may be created from their X11 names. The X11 name-table is in
\metafile{<pcehome>/lib/rgb.txt}. In the Windows API, all colours described
as \idx{RGB} (Red, Green, Blue) tuples. This is no problem as \product{}
also provides RGB colours. Note however that Win32 intensity is ranged
0..255, where the \product{} intensity is ranged 0..65535. This is true
on all \product{}'s platforms.

To provide access to the window-system colours as they can be obtained
using the Win32 API function GetSysColor(), \product{} binds these
colours to named colour objects. These colour objects are normally used
in the \product{} resource file (\metafile{<pcehome>/Defaults}) to colour
\product{}'s controller objects according to the user's preferences.

If the name of the Windows API colours are COLOR_SOMETHING, the \product{}
name is \const{win_something}.  The full list is in \tabref{wincolours}.

\begin{table}
\begin{center}
\begin{tabularlp}{\const{win_gradientinactivecaption}}
\hline
\const{win_3ddkshadow} & Dark shadow for three-dimensional display elements. \\
\const{win_3dface} & \\
\const{win_btnface} & Face color for three-dimensional display elements. \\
\const{win_3dhilight} & \\
\const{win_3dhighlight} & \\
\const{win_btnhilight} & \\
\const{win_btnhighlight} & Highlight color for three-dimensional display elements \\
\const{win_3dlight} & Light color for three-dimensional display elements \\
\const{win_3dshadow} & \\
\const{win_btnshadow} & Shadow color for three-dimensional display elements \\
\const{win_activeborder} & Active window border. \\
\const{win_activecaption} & Active window title bar. \\
\const{win_appworkspace} & Background color of MDI applications. \\
\const{win_background} & \\
\const{win_desktop} & Desktop. \\
\const{win_btntext} & Text on push buttons. \\
\const{win_captiontext} & Text in caption, size box, and scroll bar arrow box. \\
\const{win_gradientactivecaption} & Right side color of an active window's title bar. \\
\const{win_activecaption} & specifies the left side color. \\
\const{win_gradientinactivecaption} & Right side color of an inactive window's title bar. \\
\const{win_inactivecaption} & specifies the left side color. \\
\const{win_graytext} & Grayed (disabled) text. \\
\const{win_highlight} & Item(s) selected in a control. \\
\const{win_highlighttext} & Text of item(s) selected in a control. \\
\const{win_hotlight} & Color for a hot-tracked item. \\
\const{win_inactiveborder} & Inactive window border. \\
\const{win_inactivecaption} & Inactive window caption. \\
\const{win_inactivecaptiontext} & Color of text in an inactive caption. \\
\const{win_infobk} & Background color for tooltip controls. \\
\const{win_infotext} & Text color for tooltip controls. \\
\const{win_menu} & Menu background. \\
\const{win_menutext} & Text in menus. \\
\const{win_scrollbar} & Scroll bar gray area. \\
\const{win_window} & Window background. \\
\const{win_windowframe} & Window frame. \\
\const{win_windowtext} & Text in windows \\
\hline
\end{tabularlp}
\end{center}
\caption{Windows colour name mapping}
\label{tab:wincolours}
\end{table}



\section{Accessing Windows Fonts}			\label{sec:winfont}

The normal screen, helvetica, roman and times font families available in
the Unix/X11 version are available using the same names. The system will
try to use an as close as possible equivalent Windows TrueType font for
these.

The Windows `stock' fonts as available from the GetStockObject() API are
available under the special `family' "win". They are in
\tabref{winfonts}

\begin{table}
\begin{center}
\begin{tabularlp}{\const{win_inactivecaptiontext}}
\hline
\tt font(win, ansi_fixed)	& Default ANSI encoded fixed font\\
\tt font(win, ansi_var)		& Default ANSI encoded variable font\\
\tt font(win, device_default)	& Default device font\\
\tt font(win, oem_fixed)	& Computers `native' fixed font (PC)\\
\tt font(win, system)		& Variable pitched system font\\
\tt font(win, system_fixed)	& Fixed system font\\
\hline
\end{tabularlp}
\end{center}
\caption{Windows font name mapping}
\label{tab:winfonts}
\end{table}


Note that these  fonts  do  not   have  a  specified  point-size.  Their
point-size depends on the Windows installation.  The get-method <-points
will return the <-height of the font.

Other Windows fonts may be accessed using a similar method as in
Unix/X11: provide a fourth argument describing the font using the hosts
conventions. For the Win32 API, this is a textual description of the
Windows API structure LOGFONT passed to CreateFontIndirect(). The
description is a `:' (colon) separated list of attributes of the
structure. The attributes need not be specified in the order of the
structure-layout. Omited attributes are set to their default.

Attributes come in four types: numeric, boolean, enumerated and string.
In general, an attribute is specified as: \line{<name>(<value>)} <name>
is matches case-insensitive against the name of the structure field
without the leading `lf' string. For numeric types, the argument is
interpreted as a decimal number (spaces are not allowed). For a boolean
argument, the (value) part is omitted. By default the boolean attributes
are FALSE. Including the attribute name in the specification sets the
field to TRUE. Enumerated fields are specified using their symbolic
name. Name-matching is case-insensitive. Common parts of the API
identifier to make the symbol unique (for example _CHARSET in
ANSI_CHARSET) are removed. String arguments simply take the value
between the brackets. Spaces are included in the output, case is not
changed and there is no escape for the closing-brace.

The default settings are in \tabref{winfontdefaults}, the attributes are
in \tabref{winfontattributes}.
	
\begin{table}
\begin{center}
\begin{tabularlp}{\const{win_inactivecaptiontext}}
\hline
\const{charset}		& ansi \\
\const{height}		& $<points> \times font.scale$ \\
\const{weigth}		& bold if <style> is bold, normal otherwise \\
\const{italic}		& TRUE if <style> is italic or oblique \\
\const{pitch}		& fixed if <family> is screen \\
\const{family}		& swiss if <family> is helvetica, 
			  roman if <family> is times,
			  modern if <family> is screen
			  dontcare otherwise. \\
\const{face}		& <family> \\
\hline
\end{tabularlp}
\end{center}
\caption{Windows font defaults}
\label{tab:winfontdefaults}
\end{table}


\begin{table}
\begin{center}
\begin{tabularlp}{\const{win_inactivecaptiontext}}
\hline
\const{height}(int)	& point-size of the requested font \\
\const{width}(int)	& average width of the characters \\
\const{escapement}(int) & angle in 1/10 degrees of the baseline \\
\const{orientation}(int)& angle for each character \\
\const{weigth}(int)	& 0..1000 scale for thickness \\
\const{italic}		& request italic look \\
\const{underline}	& underline all characters \\
\const{strikeout}	& use strikeout-fonts \\
\const{charset}(enum)	& character encoding
			  \nameof{ansi, oem, symbol} \\
\const{outprecision}(enum)& accurate aspects
			\nameof{character, default, string, stroke} \\
\const{clipprecision}(enum)& how the characters clip
			\nameof{character, default, stroke} \\
\const{quality}(enum)	& Quality of output
			\nameof{default, draft, proof} \\
\const{pitch}(enum)	& Spacing attributes
			\nameof{default, fixed, variable} \\
\const{family}(enum)	& Style of the characters
			  \nameof{decorative, dontcare, modern,
				  roman, script, swiss}\\
\const{face}(string)    & Use specific font database \\
\hline
\end{tabularlp}
\end{center}
\caption{Windows font attributes}
\label{tab:winfontattributes}
\end{table}


The following example binds the Windows `WingDings' symbol-font:

\begin{code}
1 ?- new(F, font(wingdings, roman, 20, 'charset(symbol)')).
\end{code}

The following example uses this  font  to   create  an  image from such a
character:

\begin{code}
:- send(@display, font_alias, wingdings,
	font(wingdings, roman, 20, 'charset(symbol)')).

wingding_image(Index, Image) :-
	new(Image, image(@nil, 32, 32)),
	new(T, text(string('%c', Index), center, wingdings)),
	send(T, center, point(16, 16)),
	send(Image, draw_in, T),
	send(T, done).

test :-
	wingding_image(60, Floppy),
	send(label(test, Floppy), open).
\end{code}


\section{Accessing Windows Cursors}

The Win32 version of \product{} supports all the X11 cursors. It also
supports the definition of cursors from images. Note that such cursors
are generally limited to $32 \times 32$ pixels on Windows (formally
there is no limit in X11, but many (colour) servers exhibit strange
behaviour when given cursors larger than this size). The window cursor
names are in \tabref{wincursors}. Use the File/Demo/Cursors entry from
the PCE Manual to inspect all available cursors.

\begin{table}
\begin{center}
\begin{tabularlp}{\const{win_inactivecaptiontext}}
\hline
\const{win_arrow}	& Default Windows arrow\\
\const{win_ibeam}	& Like xterm\\
\const{win_wait}	& hour-class (good replacement of `watch')\\
\const{win_cross}	& like crosshair\\
\const{win_uparrow}	& long up arrow (no good X11 replacement)\\
\const{win_size}	& A bit like `fleur'\\
\const{win_icon}	& (see icon and icon_cross)\\
\const{win_sizenwse}	& NorthWest - SouthEast arrow (no X11 replacement)\\
\const{win_sizenesw}	& NorthEast - SouthWest arrow\\
\const{win_sizewe}	& West - East arrow\\
\const{win_sizens}	& North - South arrow\\
\const{win_sizeall}	& as win_size\\
\const{win_no}		& Stop-sign\\
\const{win_appstarting}	& Arrow with hour-class\\
\hline
\end{tabularlp}
\end{center}
\caption{Windows cursor name mapping}
\label{tab:wincursors}
\end{table}

The distributed \file{Defaults} file assigns \const{win_arrow} as the
default cursor under Windows. \const{win_ibeam} is the default editor
cursor and \const{win_wait} is the default wait cursor.