Ellipse

This function draws an ellipse. The center of the ellipse is the center of the specified bounding rectangle. The ellipse is outlined by the currently selected pen and filled by the currently selected brush.

At a Glance

Syntax

BOOL Ellipse(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

hdc

[in] Handle to the device context.

nLeftRect

[in] Specifies the x-coordinate of the upper-left corner of the bounding rectangle.

nTopRect

[in] Specifies the y-coordinate of the upper-left corner of the bounding rectangle.

nRightRect

[in] Specifies the x-coordinate of the lower-right corner of the bounding rectangle.

nBottomRect

[in] Specifies the y-coordinate of the lower-right corner of the bounding rectangle.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The current position is neither used nor updated by Ellipse.

EmptyClipboard

This function empties the clipboard and frees handles to data in the clipboard. The function then assigns ownership of the clipboard to the window that currently has the clipboard open.

At a Glance

Syntax

BOOL EmptyClipboard(void);

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Before calling EmptyClipboard, an application must open the clipboard by using the OpenClipboard function. If the application specifies a NULL window handle when opening the clipboard, EmptyClipboard succeeds but sets the clipboard owner to NULL.

See Also

OpenClipboard, SetClipboardData, WM_DESTROYCLIPBOARD

EnableEUDC

This function enables or disables end-user-defined characters (EUDC).

At a Glance

Syntax

BOOL EnableEUDC(BOOL fEnableEUDC);

Parameters

fEnableEUDC

[in] Boolean that is set to TRUE to enable EUDC, and to FALSE to disable EUDC.

Return Values

TRUE indicates success. FALSE indicates failure.

Remarks

Enabling EUDC allows text output functions to retrieve information about end-user-defined characters from EUDC fonts. Disabling EUDC prevents output functions from accessing these fonts. By default, Windows CE enables EUDC fonts during GWES initialization.

For Windows CE versions 2.01 and later, this function is supported in TrueType font and no longer supported in raster font.

EnableHardwareKeyboard

This function enables or disables the keyboard.

At a Glance

Syntax

BOOL EnableHardwareKeyboard ( BOOL bEnable );

Parameters

bEnable

[in] Boolean value that specifies whether to enable or disable the keyboard. Set it to TRUE to enable the keyboard or FALSE to disable it.

Return Values

This function always returns TRUE.

Remarks

The EnableHardwareKeyboard function is useful for applications in which a user can write on the touch screen. When the keyboard is disabled, a user can rest a hand on it without causing spurious keyboard input. Use the disable mode carefully. If an application hangs while the keyboard is disabled, the keyboard is not available to other applications.

When EnableHardwareKeyboard changes the enabled state of the keyboard, it causes menus, tabs, buttons and static controls to repaint themselves, so they can change the way they display keyboard accelerators or other relevant information.

See Also

GetKeyboardStatus

EnableMenuItem

This function enables or disables (grays) the specified menu item.

At a Glance

Syntax

BOOL EnableMenuItem(HMENU hMenu, UINT uIDEnableItem,
UINT uEnable);

Parameters

hMenu

[in] Handle to the menu.

uIDEnableItem

[in] Specifies the menu item to be enabled, disabled, or grayed, as determined by the uEnable parameter. This parameter specifies an item in a menu bar, menu, or submenu.

uEnable

[in] Specifies flags that control the interpretation of the uIDEnableItem parameter and indicate whether the menu item is enabled, disabled, or grayed. This parameter must be a combination of either MF_BYCOMMAND or MF_BYPOSITION and MF_ENABLED, MF_DISABLED, or MF_GRAYED.

Return Values

The return value specifies the previous state of the menu item (it is either MF_ENABLED or MF_GRAYED). 0xFFFFFFFF indicates that the menu item does not exist.

Remarks

An application must use the MF_BYPOSITION flag to specify the correct menu handle. If the menu handle to the menu bar is specified, the top-level menu item (an item in the menu bar) is affected. To set the state of an item in a drop-down menu or submenu by position, an application must specify the handle to the drop-down menu or submenu.

When an application specifies the MF_BYCOMMAND flag, the system checks all items that open submenus in the menu identified by the specified menu handle. Therefore, unless duplicate menu items are present, specifying the menu handle to the menu bar is sufficient.

The InsertMenu, InsertMenuItem, LoadMenuIndirect, ModifyMenu, and SetMenuItemInfo functions can also set the state (enabled or grayed) of a menu item.

Menu items cannot be disabled without being grayed. To disable a menu item, use the MF_GRAYED flag.

See Also

CreateMenu, InsertMenu

EnableWindow

This function enables or disables mouse and keyboard input to the specified window or control. When input is disabled, the window does not receive input such as mouse clicks and key presses. When input is enabled, the window receives all input.

At a Glance

Syntax

BOOL EnableWindow( HWND hWnd, BOOL bEnable);

Parameters

hWnd

Handle to the window to be enabled or disabled.

bEnable

Boolean that specifies whether to enable or disable the window. If this parameter is TRUE, the window is enabled. If the parameter is FALSE, the window is disabled.

Return Values

Nonzero indicates that the window was previously disabled. Zero indicates that the window was not previously disabled. To get extended error information, call GetLastError.

Remarks

If the enabled state of a window is changing, a WM_ENABLE message is sent before the EnableWindow function returns. If a window is already disabled, all its child windows are implicitly disabled, although they are not sent a WM_ENABLE message.

A window must be enabled before it can be activated. For example, if an application is displaying a modeless dialog box and has disabled its main window, the application must enable the main window before destroying the dialog box. Otherwise, another window will receive the keyboard focus and be activated. If a child window is disabled, it is ignored when the system tries to determine which window should receive mouse messages.

By default, a window is enabled when it is created. To create a window that is initially disabled, an application can specify the WS_DISABLED style in the CreateWindow or CreateWindowEx function. After a window has been created, an application can use EnableWindow to enable or disable the window.

An application can use this function to enable or disable a control in a dialog box. A disabled control cannot receive the keyboard focus, nor can a user gain access to it.

See Also

CreateWindow, CreateWindowEx, IsWindowEnabled, WM_ENABLE

EndDeferWindowPos

This function simultaneously updates the position and size of one or more windows in a single screen-refreshing cycle.

At a Glance

Syntax

BOOL EndDeferWindowPos( HDWP hWinPosInfo);

Parameters

hWinPosInfo

Handle to a multiple-window – position structure that contains size and position information for one or more windows. This internal structure is returned by the BeginDeferWindowPos function or by the most recent call to the DeferWindowPos function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Windows CE Remarks

This function does not cause a WM_WINDOWPOSCHANGING message to be sent.

Remarks

The EndDeferWindowPos function sends the WM_WINDOWPOSCHANGING and WM_WINDOWPOSCHANGED messages to each window identified in the internal structure.

See Also

DeferWindowPos, BeginDeferWindowPos

EndDialog

This function destroys a modal dialog box, causing the system to end any processing for the dialog box.

At a Glance

Syntax

BOOL EndDialog( HWND hDlg, int nResult );

Parameters

hDlg

[in] Handle to the dialog box to be destroyed.

nResult

[in] Specifies the value to be returned to the application from the function that created the dialog box.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

Dialog boxes created by the DialogBox, DialogBoxParam, DialogBoxIndirect, and DialogBoxIndirectParam functions must be destroyed using the EndDialog function. An application calls EndDialog from within the dialog box procedure; the function must not be used for any other purpose.

A dialog box procedure can call EndDialog at any time, even during the processing of the WM_INITDIALOG message. If your application calls the function while WM_INITDIALOG is being processed, the dialog box is destroyed before it is shown and before the input focus is set.

EndDialog does not destroy the dialog box immediately. Instead, it sets a flag and allows the dialog box procedure to return control to the system. The system checks the flag before attempting to retrieve the next message from the application queue. If the flag is set, the system ends the message loop, destroys the dialog box, and uses the value in nResult as the return value from the function that created the dialog box.

See Also

DialogBox, DialogBoxIndirect, DialogBoxIndirectParam, DialogBoxParam, WM_INITDIALOG

EndDoc

This function ends a print job.

At a Glance

Syntax

int EndDoc( HDC hdc);

Parameters

hdc

[in] Handle to the device context (DC) for the print job.

Return Values

A value greater than zero indicates success. A value less than or equal to zero indicates failure. To get extended error information, call GetLastError.

Remarks

Applications should call EndDoc immediately after finishing a print job.

See Also

EndPage, StartDoc

EndPage

This function informs the device that the application has finished writing to a page. This function is typically used to direct the device driver to advance to a new page.

At a Glance

Syntax

int EndPage( HDC hdc);

Parameters

hdc

[in] Handle to the device context (DC) for the print job.

Return Values

A value greater than zero indicates success. A value less than or equal to zero indicates failure. To get extended error information, call GetLastError.

Remarks

For Windows CE versions 1.0 through 2.01, the device context attributes are not retained between a call to EndPage and a call StartPage. You must reselect objects and set up the mapping mode again before printing the next page.

For Windows CE versions 2.10 and later, neither EndPage or StartPage resets the device context attributes. Device context attributes remain constant across subsequent pages. You do not need to reselect objects and set up the mapping mode again before printing the next page; however, doing so produces identical printer output and is compatible with earlier versions of Windows CE.

See Also

EndDoc, StartPage

EndPaint

This function marks the end of painting in the specified window. This function is required for each call to the BeginPaint function, but only after painting is complete.

At a Glance

Syntax

BOOL EndPaint( HWND hWnd, CONST PAINTSTRUCT *lpPaint );

Parameters

hWnd

Handle to the window that has been repainted.

lpPaint

Long pointer to a PAINTSTRUCT structure that contains the painting information retrieved by BeginPaint.

Return Values

The return value is always nonzero.

Remarks

If the caret was hidden by BeginPaint, EndPaint restores the caret to the screen.

See Also

BeginPaint, PAINTSTRUCT

EnumClipboardFormats

This function lets you enumerate the data formats that are currently available on the clipboard.

At a Glance

Syntax

UINT EnumClipboardFormats(UINT format);

Parameters

format

[in] Unsigned integer that specifies a clipboard format that is known to be available.

To start an enumeration of clipboard formats, set format to zero. When format is zero, the function retrieves the first available clipboard format. For subsequent calls during an enumeration, set format to the result of the previous EnumClipboardFormat call.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError. If the clipboard is not open, the function fails.

If there are no more clipboard formats to enumerate, the return value is zero. In this case, the GetLastError function returns the value NO_ERROR. This lets you distinguish between function failure and the end of enumeration.

Remarks

You must open the clipboard before enumerating its formats. Use the OpenClipboard function to open the clipboard. The EnumClipboardFormats function fails if the clipboard is not open.

The EnumClipboardFormats function enumerates formats in the order that they were placed on the clipboard. If you are copying information to the clipboard, add clipboard objects in order from the most descriptive clipboard format to the least descriptive clipboard format. If you are pasting information from the clipboard, retrieve the first clipboard format that you can handle. That will be the most descriptive clipboard format that you can handle.

The system provides automatic type conversions for certain clipboard formats. In the case of such a format, this function enumerates the specified format, then enumerates the formats to which it can be converted.

See Also

CountClipboardFormats, GetClipboardData, OpenClipboard, RegisterClipboardFormat, SetClipboardData

EnumFontFamilies

This function enumerates the fonts in a specified font family that are available on a specified device. This function supersedes the EnumFonts function.

At a Glance

Syntax

int EnumFontFamilies(HDC hdc, LPCTSTR lpszFamily,
FONTENUMPROC lpEnumFontFamProc, LPARAM lParam);

Parameters

hdc

[in] Handle to the device context (DC).

lpszFamily

[in] Long pointer to a null-terminated string that specifies the family name of the desired fonts. If lpszFamily is NULL, EnumFontFamilies randomly selects and enumerates one font of each available type family.

lpEnumFontFamProc

[in] Long pointer to the procedure-instance address of the application-defined callback function. For information about the callback function, see EnumFontFamProc.

lParam

[in] Pointer to application-supplied data. The data is passed to the callback function along with the font information.

Return Values

The return value is the last value returned by the callback function. Its meaning is defined by the application.

Remarks

For each font having the typeface name specified by the lpszFamily parameter, the EnumFontFamilies function retrieves information about that font and passes it to the function pointed to by the lpEnumFontFamProc parameter. The application-defined callback function can process the font information as desired. Enumeration continues until there are no more fonts or the callback function returns zero.

Windows CE versions 2.0 and later support systems that use either TrueType or raster fonts but not both. The font type (raster or TrueType) is chosen at system design time, and cannot be changed by an application.

Windows CE versions 1.0 and 1.01 support only raster fonts.

See Also

EnumFontFamProc, EnumFonts

EnumFonts

This function enumerates the fonts available on a specified device. This function is provided for compatibility with earlier versions of the Microsoft Platform SDK. Whenever possible, applications should use the EnumFontFamilies function.

At a Glance

Syntax

int EnumFonts(HDC hdc, LPCTSTR lpFaceName,
FONTENUMPROC lpFontFunc, LPARAM lParam);

Parameters

hdc

[in] Handle to the device context (DC).

lpFaceName

[in] Long pointer to a null-terminated string that specifies the typeface name of the desired fonts. If lpFaceName is NULL, EnumFonts randomly selects and enumerates one font of each available typeface.

lpFontFunc

[in] Long pointer to the application-defined callback function. For more information, see EnumFontsProc.

lParam

[in] Pointer to any application-defined data. The data is passed to the callback function along with the font information.

Return Values

The return value is the last value returned by the callback function. Its meaning is defined by the application.

Remarks

Use EnumFontFamiliesEx instead of EnumFonts. The EnumFontFamiliesEx function differs from the EnumFonts function in that it retrieves the style names associated with a TrueType font. With EnumFontFamiliesEx, you can retrieve information about font styles that cannot be enumerated using the EnumFonts function.

Windows CE versions 2.0 and later support systems that use either TrueType or raster fonts but not both. The font type (raster or TrueType) is chosen at system design time, and cannot be changed by an application.

Windows CE versions 1.0 and 1.01 support only raster fonts.

See Also

EnumFontFamilies, EnumFontsProc, GetDeviceCaps

EnumRegisterWordProc

This function is an application-defined callback function used with the ImmEnumRegisterWord function. It is used to process data of register strings. The REGISTERWORDENUMPROC type defines a pointer to this callback function. EnumRegisterWordProc is a placeholder for the application-defined function name.

At a Glance

Syntax

UINT CALLBACK EnumRegisterWordProc(LPCTSTR lpszReading,
DWORD dwStyle, LPCTSTR lpszString, LPVOID lpData );

Parameters

lpszReading

[in] Long pointer to a null-terminated string specifying the matched reading string.

dwStyle

[in] Specifies the style of register string.

lpszString

[in] Long pointer to a null-terminated string specifying the matched register string.

lpData

[in] Long pointer to application-supplied data.

Return Values

Nonzero continues enumeration. Zero stops enumeration.

Remarks

An application must register this function by passing its address to the ImmEnumRegisterWord function.

EnumWindows

This function enumerates all top-level windows on the screen by passing the handle to each window, in turn, to an application-defined callback function. EnumWindows continues until the last top-level window is enumerated or the callback function returns FALSE.

At a Glance

Syntax

BOOL EnumWindows( WNDENUMPROC lpEnumFunc, LPARAM lParam );

Parameters

lpEnumFunc

Long pointer to an application-defined callback function. For more information, see EnumWindowsProc.

lParam

Specifies an application-defined value to be passed to the callback function.

Return Values

Nonzero indicates success. Zero indicates failure. To get extended error information, call GetLastError.

Remarks

The EnumWindows function does not enumerate child windows.

This function is more reliable than calling the GetWindow function in a loop. An application that calls GetWindow to perform this task risks being caught in an infinite loop or referencing a handle to a window that has been destroyed.

See Also

EnumWindowsProc, GetWindow

EqualRgn

This function checks the two specified regions to determine whether they are identical. The function considers two regions identical if they are equal in size and shape.

At a Glance

Syntax

BOOL EqualRgn(HRGN hSrcRgn1, HRGN hSrcRgn2);

Parameters

hSrcRgn1

[in] Handle to a region.

hSrcRgn2

[in] Handle to a region.

Return Values

Nonzero indicates that the two regions are equal. Zero indicates that the two regions are not equal. ERROR indicates that at least one of the region handles is invalid.

See Also

CreateRectRgnIndirect

ExcludeClipRect

This function creates a new clipping region that consists of the existing clipping region minus the specified rectangle.

At a Glance

Syntax

int ExcludeClipRect(HDC hdc, int nLeftRect, int nTopRect, int nRightRect,
int nBottomRect);

Parameters

hdc

[in] Handle to the device context.

nLeftRect

[in] Specifies the logical x-coordinate of the upper-left corner of the rectangle.

nTopRect

[in] Specifies the logical y-coordinate of the upper-left corner of the rectangle.

nRightRect

[in] Specifies the logical x-coordinate of the lower-right corner of the rectangle.

nBottomRect

[in] Specifies the logical y-coordinate of the lower-right corner of the rectangle.

Return Values

The return value specifies the new clipping region’s complexity. NULLREGION indicates that the region is empty. SIMPLEREGION indicates that the region is a single rectangle. COMPLEXREGION indicates that the region is more than one rectangle. ERROR indicates that no region was created.

Remarks

The lower and right edges of the specified rectangle are not excluded from the clipping region.

See Also

IntersectClipRect

ExtEscape

This function allows applications to access capabilities of a particular device that are not available through the graphics display interface (GDI). The device capabilities that this function accesses must be implemented by an OEM.

At a Glance

Syntax

int  ExtEscape( HDC hdc, int nEscape, int cbInput, LPCSTR lpszInData,
in cbOutput, LPSTR lpszOutData );

Parameters

hdc

[in] Handle to the device context.

nEscape

[in] Specifies the escape function to be performed.

cbInput

[in] Specifies the number of bytes of data pointed to by the lpszInData parameter.

lpszInData

[in] Long pointer to the input structure required for the specified escape.

cbOutput

[in] Specifies the number of bytes of data pointed to by the lpszOutData parameter.

lpszOutData

[out] Long pointer to the structure that receives output from this escape. This parameter must not be NULL if ExtEscape is called as a query function. If no data is to be returned in this structure, set cbOutput to 0.

Return Values

A value greater than zero indicates success. A value less than zero indicates an error. The QUERYESCSUPPORT printer escape, which checks for implementation only, returns zero when the escape is not implemented.

To get extended error information, call GetLastError.

Remarks

Use this function to pass a driver-defined escape value to a device.

The escape values passed in to this function are driver-defined. Windows CE does not support any system-defined escape values.

When using QUERYESCSUPPORT to find out whether a device supports an escape value, set the nEscape parameter to QUERYESCSUPPORT and point to the escape value in question with the lpszInData parameter.

See Also

GetDeviceCaps

ExtractIconEx

This function retrieves the handle from the specified executable file or dynamic-link library (DLL).

At a Glance

Syntax

HICON ExtractIconEx(LPCTSTR lpszFile, int nIconIndex, HICON FAR *phiconLarge, HICON FAR *phiconSmall, UINT nIcons);

Parameters

lpszFile

[in] Long pointer to a null-terminated string that specifies the name of an executable file, DLL, or icon file from which icons will be extracted.

nIconIndex

[in] Specifies the zero-based index of the first icon to extract. For example, if this value is zero, the function extracts the first icon in the specified file.

For Windows CE versions 2.10 and later, the nIconIndex parameter must be zero or –N, where N is a specified resource identifier. The nIcons parameter must be 1.

For Windows CE versions 1.0 through 2.01, the function returns the total number of icons in the specified file if nIconIndex is –1 and phIconLarge and phiconSmall are both NULL. If the file is an executable file or DLL, the return value is the number of RT_GROUP_ICON resources. If the file is an .ICO file, the return value is 1.

phiconLarge

[out] Pointer to an array of icon handles which receives handles to the large icons extracted from the file. If this parameter is NULL, no large icons are extracted from the file.

phiconSmall

[out] Pointer to an array of icon handles which receives handles to the small icons extracted from the file. If this parameter is NULL, no small icons are extracted from the file.

nIcons

[in] Specifies the number of icons to extract from the file.

Return Values

For Windows CE versions 2.10 and later, this function returns the handle to an icon. If both phiconLarge and phiconSmall are not NULL, the return value defaults to the large icon.

For Windows CE versions 1.0 through 2.01, this function returns a UINT data type. If the nIconIndex parameter is –1, the phiconLarge parameter is NULL, and the phiconSmall parameter is NULL, then the return value is the number of icons contained in the specified file. Otherwise, the return value is the number of icons successfully extracted from the file.

Remarks

You must destroy all icons extracted by ExtractIconEx by calling the DestroyIcon function.

To retrieve the dimensions of the large and small icons, use the GetSystemMetrics function with the SM_CXICON, SM_CYICON, SM_CXSMICON, and SM_CYSMICON flags.

ExtTextOut

This function draws a character string by using the currently selected font. An optional rectangle may be provided, to be used for clipping, opaquing, or both.

At a Glance

Syntax

BOOL ExtTextOut(HDC hdc, int X, int Y, UINT fuOptions, const RECT *lprc, LPCTSTR lpString, UINT cbCount, const int *lpDx);

Parameters

hdc

[in] Handle to the device context (DC).

X

[in] Specifies the logical x-coordinate of the reference point used to position the string.

Y

[in] Specifies the logical y-coordinate of the reference point used to position the string.

fuOptions

[in] Specifies how to use the application-defined rectangle. This parameter can be a combination of the following values:

lprc

[in] Long pointer to an optional RECT structure that specifies the dimensions of a rectangle that is used for clipping, opaquing, or both.

lpString

[in] Long pointer to the character string to be drawn. The string does not need to be zero-terminated, since cbCount specifies the length of the string.

cbCount

[in] Specifies the number of characters in the string.

lpDx

[in] Long pointer to an optional array of values that indicate the distance between origins of adjacent character cells. For example, lpDx[i] logical units separate the origins of character cell i and character cell i + 1.

Return Values

Nonzero indicates that the string is drawn. Zero indicates failureTo get extended error information, call GetLastError.

Remarks

The current text-alignment settings for the specified DC determine how the reference point is used to position the text.

If the lpDx parameter is NULL, the ExtTextOut function uses the default spacing between characters. The character-cell origins and the contents of the array pointed to by the lpDx parameter are given in logical units. A character-cell origin is defined as the upper-left corner of the character cell.

By default, the current position is not used or updated by this function. However, an application can call the SetTextAlign function with the fMode parameter set to TA_UPDATECP to permit the system to use and update the current position each time the application calls ExtTextOut for a specified DC. When this flag is set, the system ignores the X and Y parameters on subsequent ExtTextOut calls.

See Also

RECT