winutil.h File Reference

#include "maxheap.h"
#include <limits>
#include <float.h>
#include <locale.h>
#include "coreexp.h"
#include <wtypes.h>
#include <CommCtrl.h>
#include "strclass.h"
#include "ipoint2.h"
#include "box2.h"
#include "containers/Array.h"
#include "plugapi.h"

Classes
class	DialogItemSizeData
	Dialog resizing and positioning. More...
class	DialogResizer
class	MaxLocaleHandler
	MaxLocaleHandler handles Globalization. More...
class	ToolTipExtender
	Internal use only. Hidden internal implementation for ToolTipExtender. More...

Namespaces
	MaxSDK
	This API is used to support OLE structured storage streams containing user specified string data in 3ds Max scene files or other OLE Structured Storage based files.

Macros
#define	MAKEPOINT(lparam, pt)   { pt.x = (short)LOWORD(lparam); pt.y = (short)HIWORD(lparam); }
#define	GET_X_LPARAM(lp)    ((int)(short)LOWORD(lp))
#define	GET_Y_LPARAM(lp)    ((int)(short)HIWORD(lp))
#define	CUSTLIST_DISABLED   (1<<0)
#define	CUSTLIST_MED_DISABLED   (1<<1)
#define	CUSTLIST_SEPARATOR   (1<<2)
#define	CUSTLIST_DBL_SERPARATOR   (1<<3)
#define	CUSTLIST_RED   (1<<4)
#define	MAX_MB_HOLD   0x0001
	Add "Hold" button. More...
#define	MAX_MB_DONTSHOWAGAIN   0x0002
	Add "Do not show this message again" check box. More...

Enumerations
enum	LoadMAXIconErrors { LMI_Ok, LMI_ResourceNotFound, LMI_ResourceLoadFailed, LMI_ImageAndMaskNotCompatible }

Functions
UtilExport float	GetUIScaleFactor (int monitorID=-1)
	Returns the UI scaling factor relative to a default of 96 DPI. More...
UtilExport float	GetUIUserScaleFactor ()
	Get the additional user UI scaling factor. More...
int	UIScaled (int value, int monitorID=-1)
	Returns the given value multiplied with the UI scaling factor. More...
float	UIScaled (float value, int monitorID=-1)
	Returns the given value multiplied with the UI scaling factor. More...
int	UIUnScaled (int value, int monitorID=-1)
	Returns the given value divided with the UI scaling factor. More...
float	UIUnScaled (float value, int monitorID=-1)
	Returns the given value divided with the UI scaling factor. More...
void	ScaleRect (RECT &rect, int monitorID=-1)
	Scaling of a rectangle values based on UIScaleFactor. More...
void	UnscaleRect (RECT &rect, int monitorID=-1)
	Unscaling of a rectangle values based on UIScaleFactor. More...
UtilExport HBITMAP	GetUIScaledBitmap (HBITMAP bitmap, int monitorID=-1)
	Returns a scaled copy of the bitmap if the UI scaling factor is not 1.0. More...
UtilExport HRESULT	AnnotateControlName (HWND hWnd, const MSTR &name)
	Annotates the control with Microsoft Active Accessibility name property. More...
UtilExport HRESULT	RemoveAnnotatedNameFromControl (HWND hWnd)
	Removes the Microsoft Active Accessibility name from the control. More...
CoreExport void	ScaleFileOpenSaveDialogToolbar (HWND hDlg)
	Scales the toolbar size and icons in standard file open/save dialogs. More...
CoreExport INT_PTR WINAPI	MinimalMaxFileOpenHookProc (HWND hDlg, UINT message, WPARAM wParam, LPARAM lParam)
	A minimal LPOFNHOOKPROC for scaling the toolbar size and icons in standard file open/save dialogs. More...
CoreExport float	GetWindowFloat (HWND hwnd, BOOL *valid=NULL)
	Returns a floating point value parsed from the specified windows control. More...
CoreExport float	GetFloatFromText (const MCHAR *buf, BOOL *valid)
	Returns a floating point value parsed using formatted with user locale input. More...
CoreExport int	GetWindowInt (HWND hwnd, BOOL *valid=NULL)
	Returns an integer value parsed from the specified windows control. More...
CoreExport BOOL	SetWindowTextInt (HWND hwnd, int i)
	Converts an integer value to a string for display in a windows control. More...
CoreExport BOOL	SetWindowTextFloat (HWND hwnd, float f, int precision=3)
	Converts a floating point value to a string for display in a control. More...
CoreExport MSTR	GetTextFromFloat (float f, int precision=3)
	Converts a floating point value to a string in the user locale. More...
CoreExport BOOL	SetDlgItemFloat (HWND hwnd, int idControl, float val)
	Sets the dialog box control to display the passed floating point value. More...
CoreExport float	GetDlgItemFloat (HWND hwnd, int idControl, BOOL *valid=NULL)
	Returns a floating point value parsed from the specified dialog box control. More...
CoreExport void	SetDlgFont (HWND hDlg, HFONT hFont)
	Sets the font used for the specified dialog and all its child dialogs. More...
CoreExport void	SlideWindow (HWND hwnd, int x, int y)
	Moves the window to the specified coordinates. More...
CoreExport void	StretchWindow (HWND hwnd, int w, int h)
	Stretches the window to the specified size. More...
CoreExport BOOL	CenterWindow (HWND hWndChild, HWND hWndParent)
	Centers the specified child window in the parent window. More...
CoreExport void	GetClientRectP (HWND hwnd, Rect *rect)
	This function is the same as the Win32 function GetClientRect() except that it returns the coordinates relative to the window's parent's client window. More...
CoreExport void	DrawIconButton (HDC hdc, HBITMAP hBitmap, Rect &wrect, Rect &brect, BOOL in)
	Draws a button that has a bitmap icon. More...
CoreExport int	GetListHieght (HWND hList)
	Returns the height of a list box dropdown list. More...
CoreExport void	ShadedVertLine (HDC hdc, int x, int y0, int y1, BOOL in)
	Draws a shaded vertical line at the specified x coordinate between the two given y coordinates. More...
CoreExport void	ShadedHorizLine (HDC hdc, int y, int x0, int x1, BOOL in)
	Draws a shaded horizontal line at the specified y coordinate between the two given x coordinates. More...
CoreExport void	ShadedRect (HDC hdc, RECT &rect)
	Draws a shaded rectangle. More...
CoreExport void	Rect3D (HDC hdc, RECT &rect, BOOL in)
	Draws a rectangle with a 3D appearance. More...
CoreExport void	WhiteRect3D (HDC hdc, RECT rect, BOOL in)
	Draws a rectangle with a white background and a 3D appearance. More...
CoreExport void	DrawButton (HDC hdc, RECT rect, BOOL in)
	Draws a toolbar button using the given rectangle and the in or out state. More...
CoreExport void	SetPathWithEllipses (HWND hwnd, const MCHAR *path, HFONT hFont)
	Sets a pathname in an edit control, truncating with an ellipses if the pathname is too long. More...
UtilExport void	DisplayStringWithEllipses (const MCHAR *displayString, HWND hWnd, int additionalSpace=0)
	Displays a string in an HWND (typically an edit control), trimming beginning characters with an ellipses if the string is too long. More...
UtilExport void	DisplayStringWithEllipses (const MCHAR *displayString, HWND hWnd, HFONT hFont, int additionalSpace=0)
	Displays a string in an HWND (typically an edit control), trimming beginning characters with an ellipses if the string is too long. More...
CoreExport int	UpdateComboBoxDropDownWidth (HWND hComboBox, bool vScroll=true)
	Updates the width of a combo-box drop-down window to make all its items fit. More...
CoreExport void	XORDottedRect (HWND hwnd, IPoint2 p0, IPoint2 p1, int solidToRight=0, bool bErase=false, bool bDelayUpdate=false, COLORREF color=RGB(128, 128, 128))
	XOR drawing method of rectangle. More...
CoreExport void	XORDottedCircle (HWND hwnd, IPoint2 p0, IPoint2 p1, int solidToRight=0, bool bErase=false, bool bDelayUpdate=false, COLORREF color=RGB(128, 128, 128))
	XOR drawing method of circle. More...
CoreExport void	XORDottedPolyline (HWND hwnd, int count, IPoint2 *pts, int solid=0, bool bErase=false, bool bDelayUpdate=false, COLORREF color=RGB(128, 128, 128))
	XOR drawing method of polylines. More...
CoreExport void	XORRect (HDC hdc, RECT &r, int border=1)
	Draws a rectangle in XOR mode using a specified border width. More...
CoreExport BOOL	IsVistaAeroEnabled ()
	Vista Aero related method. More...
CoreExport BOOL	IsHovering (HWND hWnd)
	If the mouse cursor is currently hovering over a window. More...
CoreExport BOOL	IsHovering (HWND hWnd, int x, int y)
	If the cursor position specified is currently confined in a window's rectangle. More...
CoreExport void	MakeButton2State (HWND hCtrl)
	This sets the control whose window handle is passed to include the BS_AUTOCHECKBOX bit set. More...
CoreExport void	MakeButton3State (HWND hCtrl)
	This sets the control whose window handle is passed to include the BS_AUTO3STATE bit set. More...
CoreExport int	GetCheckBox (HWND hw, int id)
	Returns the checked state of the given control. More...
CoreExport void	SetCheckBox (HWND hw, int id, BOOL b)
	Set the check state of a radio button or check box to checked or unchecked. More...
CoreExport BOOL	DoesFileExist (const MCHAR *file, bool allowDirectory=true)
	Detects whether the file specified by the full, absolute filename exists, considering the missing file cache. More...
CoreExport BOOL	DoesFileExist (const MCHAR *file, bool allowDirectory, bool ignoreMissingPathCache)
	Detects whether the file specified by the full, absolute filename exists, potentially considering the missing file cache. More...
CoreExport BOOL	DoesDirectoryExist (const MCHAR *dir)
	Detects whether the directory specified by the full, absolute filename exists, considering the missing file cache. More...
CoreExport BOOL	DoesDirectoryExist (const MCHAR *dir, bool ignoreMissingPathCache)
	Detects whether the directory specified by the full, absolute filename exists, potentially considering the missing file cache. More...
CoreExport bool	GetFileTime (const MCHAR *filePath, FILETIME *creationTime, FILETIME *lastAccessTime, FILETIME *lastWriteTime)
	Retrieves a file's or directory's creation, last access and last modification times. More...
CoreExport MSTR	FileTimeToString (const FILETIME &fileTime)
	Converts a FILETIME value to a string representation. More...
CoreExport int	GetBitsPerPixel ()
	Returns the number of adjacent color bits for each pixel in use by the desktop. More...
CoreExport void	StripTrailingZeros (MCHAR *buf)
	Delete superfluous zeroes from a string representing a floating point value. More...
template<class T >
void	LimitValue (T &value, T min, T max)
float	Dbl2Flt (double val, BOOL *valid=NULL)
	Safely casts double to float. Valid flag will indicate overflow. More...
int	Dbl2Int (double val, BOOL *valid=NULL)
	Safely casts double to int. Valid flag will indicate overflow. More...
CoreExport void	CustListMeasureItem (HWND hList, WPARAM wParam, LPARAM lParam)
	Calculate Item text extents using GetTextExtendPoint. More...
CoreExport void	FastListMeasureItem (HWND hList, WPARAM wParam, LPARAM lParam, bool calcWidth=false)
	Calculate Item text extents using TextMetrics. More...
CoreExport void	CustListDrawItem (HWND hList, WPARAM wParam, LPARAM lParam, DWORD flags)
	Draw a list item. More...
CoreExport INT_PTR	MaxMsgBox (HWND hWndParent, LPCMSTR lpText, LPCMSTR lpCaption, UINT type, UINT exType=0, DWORD *exRet=NULL)
	Provides an extended message box functionality, This is used to support message dialogs with a 'Hold' or a 'Help' button and/or a 'Do not show this message again' check box. More...
UtilExport int	MaxMessageBox (HWND parent, LPCMSTR text, LPCMSTR caption, unsigned int type, unsigned int exType=0, DWORD *exRet=nullptr)
	Provides an extended message box functionality. This is used to support message dialogs with a 'Hold', a 'Help' button and/or a 'Do not show this message again' check box. More...
CoreExport LoadMAXIconErrors	LoadMAXIcon (HINSTANCE hInstance, LPCMSTR resID, LPCMSTR resMaskID, COLORREF bkColor, HIMAGELIST imageList, int imageIndex, int preMultAlpha=TRUE)
CoreExport int	LoadMAXIconFromBMI (LPBITMAPINFOHEADER biImage, LPBITMAPINFOHEADER biMask, COLORREF bkColor, const MCHAR *pFilePrefix, int preMultAlpha=TRUE, HIMAGELIST *pImageList=NULL)
CoreExport BITMAPINFOHEADER *	LoadBitmapFromFile (const MCHAR *filename)
CoreExport void	DrawMAXIcon (HDC hDC, Rect &r, HIMAGELIST hList32, HIMAGELIST hList16, int index)
CoreExport COLORREF	ComputeXORDrawColor (COLORREF bkgColor)
	Returns a suggested color to use when drawing XOR lines over a specified background color. More...
CoreExport COLORREF	ComputeViewportXORDrawColor ()
	Returns a suggested color to use when drawing XOR lines over a viewport. More...
static BOOL CALLBACK	GetInitialPositionECP (HWND hwnd, LPARAM lParam)
UtilExport const _locale_t &	GetUserLocale ()
	GetUserLocale retrieves user specific locale specifications Method to retrieve a cached user locale The context to use this method is preferably when interacting through the user interface As an example, to interpret and/or display floating point numbers using user specified decimal separator symbol. More...
CoreExport bool	SearchComboBox (HWND hWnd, MCHAR key, const MCHAR *szTrim=NULL)
	Multiple character search for ComboBoxes. More...
CoreExport bool	SearchListBox (HWND hWnd, MCHAR key, const MCHAR *szTrim=NULL)
	Multiple character search for ListBoxes. More...
CoreExport int	GetDefaultToolTipMaxWidth ()
UtilExport MSTR	GetListBoxItemText (HWND hDlg, int nIDDlgItem, int nListboxItem)
	Returns a Listbox item's string as a MSTR. More...
UtilExport void	GetListBoxItemText (HWND hDlg, int nIDDlgItem, int nListboxItem, MSTR &itemText)
	Returns a Listbox item's string as a MSTR. More...
UtilExport MSTR	GetListBoxItemText (HWND hListBoxWnd, int nListboxItem)
	Returns a Listbox item's string as a MSTR. More...
UtilExport void	GetListBoxItemText (HWND hListBoxWnd, int nListboxItem, MSTR &itemText)
	Returns a Listbox item's string as a MSTR. More...
UtilExport MSTR	GetComboBoxItemText (HWND hDlg, int nIDDlgItem, int nComboboxItem)
	Returns a Combobox item's string as a MSTR. More...
UtilExport void	GetComboBoxItemText (HWND hDlg, int nIDDlgItem, int nComboboxItem, MSTR &itemText)
	Returns a Combobox item's string as a MSTR. More...
UtilExport MSTR	GetComboBoxItemText (HWND hComboBoxWnd, int nComboboxItem)
	Returns a Combobox item's string as a MSTR. More...
UtilExport void	GetComboBoxItemText (HWND hComboBoxWnd, int nComboboxItem, MSTR &itemText)
	Returns a Combobox item's string as a MSTR. More...
UtilExport MSTR	GetWindowText (HWND hDlg, int nIDDlgItem)
	Returns an window's text as a MSTR. More...
UtilExport void	GetWindowText (HWND hDlg, int nIDDlgItem, MSTR &windowText)
	Returns an window's text as a MSTR. More...
UtilExport MSTR	GetWindowText (HWND hWnd)
	Returns an window's text as a MSTR. More...
UtilExport void	GetWindowText (HWND hWnd, MSTR &windowText)
	Returns an window's text as a MSTR. More...

Macro Definition Documentation

#define MAKEPOINT	(		lparam,
			pt
	)		{ pt.x = (short)LOWORD(lparam); pt.y = (short)HIWORD(lparam); }

#define GET_X_LPARAM

(

lp

)

((int)(short)LOWORD(lp))

#define GET_Y_LPARAM

(

lp

)

((int)(short)HIWORD(lp))

#define CUSTLIST_DISABLED   (1<<0)

#define CUSTLIST_MED_DISABLED   (1<<1)

#define CUSTLIST_SEPARATOR   (1<<2)

#define CUSTLIST_DBL_SERPARATOR   (1<<3)

#define CUSTLIST_RED   (1<<4)

#define MAX_MB_HOLD   0x0001

Add "Hold" button.

#define MAX_MB_DONTSHOWAGAIN   0x0002

Add "Do not show this message again" check box.

Enumeration Type Documentation

enum LoadMAXIconErrors

Enumerator
LMI_Ok
LMI_ResourceNotFound
LMI_ResourceLoadFailed
LMI_ImageAndMaskNotCompatible

{
    LMI_Ok,
    LMI_ResourceNotFound,
    LMI_ResourceLoadFailed,
    LMI_ImageAndMaskNotCompatible,
};

Function Documentation

CoreExport float GetWindowFloat	(	HWND	hwnd,
		BOOL *	valid = NULL
	)

Returns a floating point value parsed from the specified windows control.

CoreExport float GetFloatFromText	(	const MCHAR *	buf,
		BOOL *	valid
	)

Returns a floating point value parsed using formatted with user locale input.

CoreExport int GetWindowInt	(	HWND	hwnd,
		BOOL *	valid = NULL
	)

Returns an integer value parsed from the specified windows control.

CoreExport BOOL SetWindowTextInt	(	HWND	hwnd,
		int	i
	)

Converts an integer value to a string for display in a windows control.

CoreExport BOOL SetWindowTextFloat	(	HWND	hwnd,
		float	f,
		int	precision = 3
	)

Converts a floating point value to a string for display in a control.

The precision parameter is used to determine the number of values to display to the right of the decimal point.

CoreExport MSTR GetTextFromFloat	(	float	f,
		int	precision = 3
	)

Converts a floating point value to a string in the user locale.

The precision parameter is used to determine the number of values appearing to the right of the decimal point.

CoreExport BOOL SetDlgItemFloat	(	HWND	hwnd,
		int	idControl,
		float	val
	)

Sets the dialog box control to display the passed floating point value.

Trailing zeros are removed.

CoreExport float GetDlgItemFloat	(	HWND	hwnd,
		int	idControl,
		BOOL *	valid = NULL
	)

Returns a floating point value parsed from the specified dialog box control.

CoreExport void SetDlgFont	(	HWND	hDlg,
		HFONT	hFont
	)

Sets the font used for the specified dialog and all its child dialogs.

CoreExport void SlideWindow	(	HWND	hwnd,
		int	x,
		int	y
	)

Moves the window to the specified coordinates.

CoreExport void StretchWindow	(	HWND	hwnd,
		int	w,
		int	h
	)

Stretches the window to the specified size.

CoreExport BOOL CenterWindow	(	HWND	hWndChild,
		HWND	hWndParent
	)

Centers the specified child window in the parent window.

CoreExport void GetClientRectP	(	HWND	hwnd,
		Rect *	rect
	)

This function is the same as the Win32 function GetClientRect() except that it returns the coordinates relative to the window's parent's client window.

CoreExport void DrawIconButton	(	HDC	hdc,
		HBITMAP	hBitmap,
		Rect &	wrect,
		Rect &	brect,
		BOOL	in
	)

Draws a button that has a bitmap icon.

CoreExport int GetListHieght

(

HWND

hList

)

Returns the height of a list box dropdown list.

CoreExport void ShadedVertLine	(	HDC	hdc,
		int	x,
		int	y0,
		int	y1,
		BOOL	in
	)

Draws a shaded vertical line at the specified x coordinate between the two given y coordinates.

The in parameter indicates whether the shading that appears to the right is light or dark.

CoreExport void ShadedHorizLine	(	HDC	hdc,
		int	y,
		int	x0,
		int	x1,
		BOOL	in
	)

Draws a shaded horizontal line at the specified y coordinate between the two given x coordinates.

The in parameter indicates whether the shading that appears below the line is light or dark.

CoreExport void ShadedRect	(	HDC	hdc,
		RECT &	rect
	)

Draws a shaded rectangle.

CoreExport void Rect3D	(	HDC	hdc,
		RECT &	rect,
		BOOL	in
	)

Draws a rectangle with a 3D appearance.

CoreExport void WhiteRect3D	(	HDC	hdc,
		RECT	rect,
		BOOL	in
	)

Draws a rectangle with a white background and a 3D appearance.

CoreExport void DrawButton	(	HDC	hdc,
		RECT	rect,
		BOOL	in
	)

Draws a toolbar button using the given rectangle and the in or out state.

CoreExport void SetPathWithEllipses	(	HWND	hwnd,
		const MCHAR *	path,
		HFONT	hFont
	)

Sets a pathname in an edit control, truncating with an ellipses if the pathname is too long.

UtilExport void DisplayStringWithEllipses	(	const MCHAR *	displayString,
		HWND	hWnd,
		int	additionalSpace = 0
	)

Displays a string in an HWND (typically an edit control), trimming beginning characters with an ellipses if the string is too long.

Parameters

displayString	The string to be displayed.
hWnd	The hWnd to display the string in - uses existing font
additionalSpace	Reserved space in pixels that reduces string display area in hWnd

UtilExport void DisplayStringWithEllipses	(	const MCHAR *	displayString,
		HWND	hWnd,
		HFONT	hFont,
		int	additionalSpace = 0
	)

Displays a string in an HWND (typically an edit control), trimming beginning characters with an ellipses if the string is too long.

Parameters

displayString	The string to be displayed.
hWnd	The window to display the string in
hFont	The font to use in the window
additionalSpace	Reserved space in pixels that reduces string display area in hWnd

CoreExport int UpdateComboBoxDropDownWidth	(	HWND	hComboBox,
		bool	vScroll = true
	)

Updates the width of a combo-box drop-down window to make all its items fit.

Call this function if some strings in your combo-box are longer than the actual combo-box control's width. This function will update the width of the combo-box to make the widest combo-box item fit.

Parameters

hComboBox	The handle of the combobox to update
vScroll	true if the width of a vertical scroll bar should be taken into account

Returns

-1 if the combo-box could not be updated successfully, the new width of the combo-box drop down otherwise.

CoreExport void XORDottedRect	(	HWND	hwnd,
		IPoint2	p0,
		IPoint2	p1,
		int	solidToRight = 0,
		bool	bErase = false,
		bool	bDelayUpdate = false,
		COLORREF	color = RGB(128, 128, 128)
	)

XOR drawing method of rectangle.

This method will draw a dotted or solid rectangle onto the specified window. This method can provide better compatibility with Vista Aero than using GDI function directly.

Parameters

[in]	hwnd	Window handle of the window on which the drawing will occur.
[in]	p0	One corner of the rectangle.
[in]	p1	p0's diagonal in the rectangle.
[in]	solidToRight	If zero, the rectangle will be dotted. If less than zero, and p0.x >= p1.x, the line will be solid, otherwize dotted. If greater than zero, and p0.x <= p1.x, the line will be solid, otherwize dotted.
[in]	bErase	Whether to erase the foreground and use the background to fill the affected pixels, this is only valid for the window handle associated with graphic window.
[in]	bDelayUpdate	if true, the result image will be stored on the back buffer and won't be presented to screen immediately. If next drawing function is invoked with bDelayUpdate being false, then the image will be presented combined with the result of previous drawing function. If the drawing result is not necessary to be seen immediately, passing true to this parameter will reduce the times of back buffer presenting, thus optimize the performance. This is only valid for window handle associated with graphic window.
[in]	color	Optional XOR line color. Default is grey (128,128,128)

CoreExport void XORDottedCircle	(	HWND	hwnd,
		IPoint2	p0,
		IPoint2	p1,
		int	solidToRight = 0,
		bool	bErase = false,
		bool	bDelayUpdate = false,
		COLORREF	color = RGB(128, 128, 128)
	)

XOR drawing method of circle.

This method will draw a dotted or solid circle onto the specified window. This method can provide better compatibility with Vista Aero than using GDI function directly.

Parameters

[in]	hwnd	Window handle of the window on which the drawing will occur.
[in]	p0	One corner of the circle's bounding rectangle.
[in]	p1	p0's diagonal in the rectangle.
[in]	solidToRight	If zero, the circle will be dotted. If less than zero, and p0.x >= p1.x, the line will be solid, otherwize dotted. If greater than zero, and p0.x <= p1.x, the line will be solid, otherwize dotted.
[in]	bErase	Whether to erase the foreground and use the background to fill the affected pixels, this is only valid for the window handle associated with graphic window.
[in]	bDelayUpdate	if true,the result image will be stored on the back buffer and won't be presented to screen immediately. If next drawing function is invoked with bDelayUpdate being false, then the image will be presented combined with the result of previous drawing function. If the drawing result is not necessary to be seen immediately, passing true to this parameter will reduce the times of back buffer presenting, thus optimize the performance. This is only valid for window handle associated with graphic window.
[in]	color	Optional XOR line color. Default is grey (128,128,128)

CoreExport void XORDottedPolyline	(	HWND	hwnd,
		int	count,
		IPoint2 *	pts,
		int	solid = 0,
		bool	bErase = false,
		bool	bDelayUpdate = false,
		COLORREF	color = RGB(128, 128, 128)
	)

XOR drawing method of polylines.

This method will draw dotted or solid polylines onto the specified window. This method can provide better compatibility with Vista Aero than using GDI function directly.

Parameters

[in]	hwnd	Window handle of the window on which the drawing will occur.
[in]	count	The count of corners of the polylines.
[in]	pts	Pointer to the corners.
[in]	solid	If nonzero, the polylines will be solid, otherwize dotted.
[in]	bErase	Whether to erase the foreground and use the background to fill the affected pixels, this is only valid for the window handle associated with graphic window.
[in]	bDelayUpdate	if true, the result image will be stored on the back buffer and won't be presented to screen immediately. If next drawing function is invoked with bDelayUpdate being false, then the image will be presented combined with the result of previous drawing function. If the drawing result is not necessary to be seen immediately, passing true to this parameter will reduce the times of back buffer presenting, thus optimize the performance. This is only valid for window handle associated with graphic window.
[in]	color	Optional XOR line color. Default is grey (128,128,128)

CoreExport void XORRect	(	HDC	hdc,
		RECT &	r,
		int	border = 1
	)

Draws a rectangle in XOR mode using a specified border width.

CoreExport BOOL IsVistaAeroEnabled

(

)

Vista Aero related method.

This method will tell whether the Vista Aero is turned on or not.

Returns

TRUE if Vista Aero is turned on, otherwize FALSE. On Window XP or previous Windows, it will always return FALSE.

CoreExport BOOL IsHovering

(

HWND

hWnd

)

If the mouse cursor is currently hovering over a window.

This method will not differentiate whether the cursor is actually hovering over a window, or it's blocked by some other window. It only does a point-rectangle containment test.

Parameters

[in]

hWnd

The handle of the window.

Returns

TRUE if the mouse cursor is currently hovering the window, otherwise FALSE.

CoreExport BOOL IsHovering	(	HWND	hWnd,
		int	x,
		int	y
	)

If the cursor position specified is currently confined in a window's rectangle.

This method will not differentiate whether the cursor is actually hovering over a window, or it's blocked by some other window. It only does a point-rectangle containment test.

Parameters

[in]	hWnd	The handle of the window.
[in]	x	The x-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.
[in]	y	The y-coordinate of the cursor. The coordinate is relative to the upper-left corner of the client area.

Returns

TRUE if the mouse cursor is currently hovering the window, otherwise FALSE.

CoreExport void MakeButton2State

(

HWND

hCtrl

)

This sets the control whose window handle is passed to include the BS_AUTOCHECKBOX bit set.

This creates a control which is same as a check box, except that a check mark appears in the check box when the user selects the box. The check mark disappears when the user selects the box next time.

CoreExport void MakeButton3State

(

HWND

hCtrl

)

This sets the control whose window handle is passed to include the BS_AUTO3STATE bit set.

This creates a control which is the same as a three-state check box, except that the box changes its state when the user selects it.

CoreExport int GetCheckBox	(	HWND	hw,
		int	id
	)

Returns the checked state of the given control.

• BST_CHECKED - Button is checked.
• BST_INDETERMINATE - Button is greyed, which indicates an indeterminate state.
• BST_UNCHECKED - Button is unchecked.

CoreExport void SetCheckBox	(	HWND	hw,
		int	id,
		BOOL	b
	)

Set the check state of a radio button or check box to checked or unchecked.

CoreExport BOOL DoesFileExist	(	const MCHAR *	file,
		bool	allowDirectory = true
	)

Detects whether the file specified by the full, absolute filename exists, considering the missing file cache.

Detects whether specified file exists, optionally excluding files that are directories. Note that if the filename is a guid string, the guid string is converted to a AssetUser, and then the AssetUser's filename is tested to see if it exists.

Parameters

file	The null-terminated filename or guid string
allowDirectory	If true, returns TRUE if the filename is found and is either a file or a directory. If false, returns TRUE if the filename is found and is a file but not a directory.

Returns

TRUE if the file exists.

CoreExport BOOL DoesFileExist	(	const MCHAR *	file,
		bool	allowDirectory,
		bool	ignoreMissingPathCache
	)

Detects whether the file specified by the full, absolute filename exists, potentially considering the missing file cache.

Detects whether specified file exists, optionally excluding files that are directories. Note that if the filename is a guid string, the guid string is converted to a AssetUser, and then the AssetUser's filename is tested to see if it exists.

Parameters

file	The null-terminated filename or guid string
allowDirectory	If true, returns TRUE if the filename is found and is either a file or a directory. If false, returns TRUE if the filename is found and is a file but not a directory.
ignoreMissingPathCache	If true, testing does not consider whether the file's path may be in the missing path cache.

Returns

TRUE if the file exists.

CoreExport BOOL DoesDirectoryExist

(

const MCHAR *

dir

)

Detects whether the directory specified by the full, absolute filename exists, considering the missing file cache.

Detects whether specified directory exists. Note that if the filename is a guid string, the guid string is converted to a AssetUser, and then the AssetUser's filename is tested to see if it exists.

Parameters

dir	The null-terminated directory or guid string

Returns

TRUE if the directory exists.

CoreExport BOOL DoesDirectoryExist	(	const MCHAR *	dir,
		bool	ignoreMissingPathCache
	)

Detects whether the directory specified by the full, absolute filename exists, potentially considering the missing file cache.

Detects whether specified directory exists. Note that if the filename is a guid string, the guid string is converted to a AssetUser, and then the AssetUser's filename is tested to see if it exists.

Parameters

dir	The null-terminated directory or guid string
ignoreMissingPathCache	If true, testing does not consider whether the file's path may be in the missing path cache.

Returns

TRUE if the directory exists.

CoreExport bool GetFileTime	(	const MCHAR *	filePath,
		FILETIME *	creationTime,
		FILETIME *	lastAccessTime,
		FILETIME *	lastWriteTime
	)

Retrieves a file's or directory's creation, last access and last modification times.

Parameters

[in]	filePath	- absolute path to the file
[out]	creationTime	- pointer to a FILETIME structure to receive the date and time the file or directory was created. This parameter can be NULL.
[out]	lastAccessTime	- pointer to a FILETIME structure to receive the date and time the file or directory was last accessed. This parameter can be NULL.
[out]	lastWriteTime-	pointer to a FILETIME structure to receive the date and time the file or directory was last modified. This parameter can be NULL.

Returns

True if the operation was successful, false otherwise.

CoreExport MSTR FileTimeToString

(

const FILETIME &

fileTime

)

Converts a FILETIME value to a string representation.

The FILETIME is converted into local time and date, and then to a string. The format of the time and date string is given by the default user locale.

Parameters

fileTime

- the file time to convert to string

Returns

A string representation of the file time, or empty string if an error occurred.

CoreExport int GetBitsPerPixel

(

)

Returns the number of adjacent color bits for each pixel in use by the desktop.

CoreExport void StripTrailingZeros

(

MCHAR *

buf

)

Delete superfluous zeroes from a string representing a floating point value.

For example, "1.2300000" becomes "1.23".

void LimitValue	(	T &	value,
		T	min,
		T	max
	)

{
    if ( value < min ) 
        value = min;
    if ( value > max )
        value = max;
}

float Dbl2Flt ( double  val, BOOL *  valid = NULL  )

inline

Safely casts double to float. Valid flag will indicate overflow.

{
    if ( val < 0.0f )
    {
        if ( val < -FLT_MAX )
        {
            if (valid) *valid = FALSE;
            return -FLT_MAX;
        }
        if ( val > -FLT_MIN )
        {
            if (valid) *valid = FALSE;
            return -FLT_MIN;
        }
        if (valid) *valid = TRUE;
        return (float)val;
    }

    if ( val > FLT_MAX )
    {
        if (valid) *valid = FALSE;
        return FLT_MAX;
    }
    if ( val < FLT_MIN && val != 0.0 )
    {
        if (valid) *valid = FALSE;
        return FLT_MIN;
    }
    if (valid) *valid = TRUE;
    return (float)val;
}

int Dbl2Int ( double  val, BOOL *  valid = NULL  )

inline

Safely casts double to int. Valid flag will indicate overflow.

{
    if ( val > INT_MAX )
    {
        if (valid) *valid = FALSE;
        return INT_MAX;
    }
    if ( val < INT_MIN )
    {
        if (valid) *valid = FALSE;
        return INT_MIN;
    }
    if (valid) *valid = TRUE;
    return (int)val;
}

CoreExport void CustListMeasureItem	(	HWND	hList,
		WPARAM	wParam,
		LPARAM	lParam
	)

Calculate Item text extents using GetTextExtendPoint.

This method will calculate in precise dimension base on control content

Parameters

[in]	hList	The handle of the listbox/combobox list.
[in]	wParam	- Unused
[in]	lParam	- Pointer to the MEASUREITEMSTRUCT.

CoreExport void FastListMeasureItem	(	HWND	hList,
		WPARAM	wParam,
		LPARAM	lParam,
		bool	calcWidth = false
	)

Calculate Item text extents using TextMetrics.

This method will calculate in average/maximum character size based on the control content. Note that it will cache the values retrieved and will not make any further GDI call. Also, it will not calculate the width extent otherwise specified and that calculation is the max size possible

Parameters

[in]	hList	The handle of the listbox/combobox list.
[in]	wParam	- Unused
[in]	lParam	- Pointer to the MEASUREITEMSTRUCT.
[in]	calcWidth	(optional) - Width calculation necessary.

CoreExport void CustListDrawItem	(	HWND	hList,
		WPARAM	wParam,
		LPARAM	lParam,
		DWORD	flags
	)

Draw a list item.

This method will Draw a list item based on previously fetched measurement using DrawText Note that it will cache the values retrieved and will not make any further GDI call. Also, it will not calculate the width extent otherwise specified and that calculation is the max size possible

Parameters

[in]	hList	The handle of the listbox/combobox list.
[in]	wParam	- Unused
[in]	lParam	- Pointer to the DRAWITEMSTRUCT.
[in]	flags	- Possible values (CUSTLIST_DISABLED/MED_DISABLED/RED/SEPARATOR/DBL_SERPARATOR)

CoreExport INT_PTR MaxMsgBox	(	HWND	hWndParent,
		LPCMSTR	lpText,
		LPCMSTR	lpCaption,
		UINT	type,
		UINT	exType = 0,
		DWORD *	exRet = NULL
	)

Provides an extended message box functionality, This is used to support message dialogs with a 'Hold' or a 'Help' button and/or a 'Do not show this message again' check box.

The first four parameters correspond to the Win32 MessageBox method parameters, but not all Win32 MessageBox functionality is supported. The last two optional args add the functionality listed above - exType is used for adding the additional buttons, and exRet is used for getting the extra return info.

Parameters

hWndParent	- The parent window handle
lpText	- The main message
lpCaption	- The caption or title for the message window
type	- The type of message box. The supported types are: MB_YESNO MB_OK MB_YESNOCANCEL MB_OKCANCEL The following Win32 MessageBox types are not supported and they will be treated like MB_OKCANCEL: MB_ABORTRETRYIGNORE MB_RETRYCANCEL MB_CANCELTRYCONTINUE The following Win32 MessageBox flags are not supported and will be ignored: MB_DEFBUTTON* MB_TASKMODAL MB_SYSTEMMODAL MB_NOFOCUS MB_SETFOREGROUND MB_TOPMOST MB_RIGHT MB_RTLREADING The MB_HELP flag is supported, albeit in a manner different than Win32 MessageBox. If specified and 'exRet' is not null, a Help button is displayed and clicking the Help button causes 3ds Max Help to be displayed using the help topic id that is passed through 'exRet'. The MB_HELP flag is ignored if MAX_MB_HOLD is specified in 'exType' or if a type of MB_YESNOCANCEL is specified.
exType	- Used for adding additional UI elements. The supported bit field values are: MAX_MB_HOLD - display a 'Hold' button. This flag is ignored if a type of MB_YESNOCANCEL is specified. MAX_MB_DONTSHOWAGAIN - display a 'Do not show this message again' check box
exRet	- Used for specifying the help file topic id and for returning extra info: if MAX_MB_DONTSHOWAGAIN is specified as part of 'exType', on return the MAX_MB_DONTSHOWAGAIN bit will or will not be set in 'exRet' based on check box setting. if MAX_MB_HOLD is specified as part of 'exType', if the button is pressed the MAX_MB_HOLD bit will set in 'exRet' and a value of IDOK is returned.

Note

- See "https://docs.microsoft.com/en-us/windows/desktop/api/winuser/nf-winuser-messagebox" for a description of the Win32 MessageBox method parameters.

- the MaxMessageBox methods provide a more complete extended message box functionality that better matches the Win32 MessageBox functionality, and should be used instead of MaxMsgBox. The MaxMsgBox method will be deprecated in the future.

CoreExport LoadMAXIconErrors LoadMAXIcon	(	HINSTANCE	hInstance,
		LPCMSTR	resID,
		LPCMSTR	resMaskID,
		COLORREF	bkColor,
		HIMAGELIST	imageList,
		int	imageIndex,
		int	preMultAlpha = TRUE
	)

CoreExport int LoadMAXIconFromBMI	(	LPBITMAPINFOHEADER	biImage,
		LPBITMAPINFOHEADER	biMask,
		COLORREF	bkColor,
		const MCHAR *	pFilePrefix,
		int	preMultAlpha = TRUE,
		HIMAGELIST *	pImageList = NULL
	)

CoreExport BITMAPINFOHEADER* LoadBitmapFromFile

(

const MCHAR *

filename

)

CoreExport void DrawMAXIcon	(	HDC	hDC,
		Rect &	r,
		HIMAGELIST	hList32,
		HIMAGELIST	hList16,
		int	index
	)

CoreExport COLORREF ComputeXORDrawColor

(

COLORREF

bkgColor

)

Returns a suggested color to use when drawing XOR lines over a specified background color.

CoreExport COLORREF ComputeViewportXORDrawColor

(

)

Returns a suggested color to use when drawing XOR lines over a viewport.

The color is suggested based on the background color settings.

static BOOL CALLBACK GetInitialPositionECP ( HWND  hwnd, LPARAM  lParam  )

static

UtilExport const _locale_t& GetUserLocale

(

)

GetUserLocale retrieves user specific locale specifications Method to retrieve a cached user locale The context to use this method is preferably when interacting through the user interface As an example, to interpret and/or display floating point numbers using user specified decimal separator symbol.

The method could be used in conjunction with _stscanf_l/_sntprintf_s_l note: writing floating point numbers to data files MUST ALWAYS be done using a dot (.) as decimal separator (default C Locale) disregarding user Locale settings (you may use MaxLocaleHandler to help) returns The cached user locale

UtilExport MSTR GetListBoxItemText	(	HWND	hDlg,
		int	nIDDlgItem,
		int	nListboxItem
	)

Returns a Listbox item's string as a MSTR.

Parameters

[in]	hDlg	The hWnd of the Dialog the Listbox is in
[in]	nIDDlgItem	The id of the Listbox in the dialog.
[in]	nListboxItem	The index of the Listbox item

Returns

the Listbox item's string

If the ListBox is not found, an empty string is returned

UtilExport void GetListBoxItemText	(	HWND	hDlg,
		int	nIDDlgItem,
		int	nListboxItem,
		MSTR &	itemText
	)

Returns a Listbox item's string as a MSTR.

Parameters

[in]	hDlg	The hWnd of the Dialog the Listbox is in
[in]	nIDDlgItem	The id of the Listbox in the dialog.
[in]	nListboxItem	The index of the Listbox item
[out]	itemText	The Listbox item's string

If the ListBox is not found, an empty string is returned

UtilExport MSTR GetListBoxItemText	(	HWND	hListBoxWnd,
		int	nListboxItem
	)

Returns a Listbox item's string as a MSTR.

Parameters

[in]	hListBoxWnd	Window handle of ListBox
[in]	nListboxItem	The index of the Listbox item

Returns

the Listbox item's string

If the ListBox is not found, an empty string is returned

UtilExport void GetListBoxItemText	(	HWND	hListBoxWnd,
		int	nListboxItem,
		MSTR &	itemText
	)

Returns a Listbox item's string as a MSTR.

Parameters

[in]	hListBoxWnd	Window handle of ListBox
[in]	nListboxItem	The index of the Listbox item
[out]	itemText	The Listbox item's string

If the ListBox is not found, an empty string is returned

UtilExport MSTR GetComboBoxItemText	(	HWND	hDlg,
		int	nIDDlgItem,
		int	nComboboxItem
	)

Returns a Combobox item's string as a MSTR.

Parameters

[in]	hDlg	The hWnd of the Dialog the Combobox is in
[in]	nIDDlgItem	The id of the Combobox in the dialog.
[in]	nComboboxItem	The index of the Combobox item

Returns

the Combobox item's string

If the Combobox is not found, an empty string is returned

UtilExport void GetComboBoxItemText	(	HWND	hDlg,
		int	nIDDlgItem,
		int	nComboboxItem,
		MSTR &	itemText
	)

Returns a Combobox item's string as a MSTR.

Parameters

[in]	hDlg	The hWnd of the Dialog the Combobox is in
[in]	nIDDlgItem	The id of the Combobox in the dialog.
[in]	nComboboxItem	The index of the Combobox item
[out]	itemText	The Combobox item's string

If the Combobox is not found, an empty string is returned

UtilExport MSTR GetComboBoxItemText	(	HWND	hComboBoxWnd,
		int	nComboboxItem
	)

Returns a Combobox item's string as a MSTR.

Parameters

[in]	hComboBoxWnd	Window handle of ComboBox
[in]	nComboboxItem	The index of the Combobox item

Returns

the Combobox item's string

If the Combobox is not found, an empty string is returned

UtilExport void GetComboBoxItemText	(	HWND	hComboBoxWnd,
		int	nComboboxItem,
		MSTR &	itemText
	)

Returns a Combobox item's string as a MSTR.

Parameters

[in]	hComboBoxWnd	Window handle of ComboBox
[in]	nComboboxItem	The index of the Combobox item
[out]	itemText	The Combobox item's string

If the Combobox is not found, an empty string is returned

UtilExport MSTR GetWindowText	(	HWND	hDlg,
		int	nIDDlgItem
	)

Returns an window's text as a MSTR.

Parameters

[in]	hDlg	The hWnd of the Dialog the window is in
[in]	nIDDlgItem	The id of the window in the dialog.

Returns

the window's string

If the window is not found, an empty string is returned

UtilExport void GetWindowText	(	HWND	hDlg,
		int	nIDDlgItem,
		MSTR &	windowText
	)

Returns an window's text as a MSTR.

Parameters

[in]	hDlg	The hWnd of the Dialog the window is in
[in]	nIDDlgItem	The id of the window in the dialog.
[out]	windowText	The window's text

If the window is not found, an empty string is returned

UtilExport MSTR GetWindowText

(

HWND

hWnd

)

Returns an window's text as a MSTR.

Parameters

[in]

hWnd

The Window handle

Returns

the window's string

If the window is not found, an empty string is returned

UtilExport void GetWindowText	(	HWND	hWnd,
		MSTR &	windowText
	)

Returns an window's text as a MSTR.

Parameters

[in]	hWnd	The Window handle
[out]	windowText	The window's text

If the window is not found, an empty string is returned